enso/docs/language-server/protocol-common.md

layout	title	category	tags	order
developer-doc	Enso Protocol Common Message Specification	language-server	language-server protocol specification	2

Enso Protocol Common Message Specification

This document contains the specification of the Enso protocol messages that are common to multiple sub-components of the protocol.

For information on the design and architecture of the protocol, as well as its transport formats, please look here.

• Protocol Message Specification
• Common Types
  • Path
  • IPWithSocket
  • EnsoUUID
• Common Errors
  • ParseError
  • InvalidRequest
  • MethodNotFound
  • InvalidParams
  • ServiceError
  • NotImplementedError
  • RequestTimeoutError

Protocol Message Specification

The message specification for protocol messages must include the following fields:

• Type: The type of the message (e.g. Request or Notification).
• Direction: The direction in which the originating message is sent (either Client -> Server or Server -> Client).
• Connection: Which connection the message should be sent on. Write 'Protocol' for the textual connection and 'Data' for the binary connection.
• Visibility: Whether the method should be used by the public or is an internal / implementation detail ('Public' or 'Private').

They must also contain separate sections specifying their parameters, result (if it has one), and any errors that may occur. These specifications should be either in typescript or flatbuffers syntax, depending on the connection on which the message occurs.

The capability specifications must include the following fields, as well as a section 'Enables' stating which protocol messages are gated by the capability.

• method: The name of the capability.
• registerOptions: The options that must be provided to register the capability, described using typescript type syntax.

Common Types

There are a number of types that are shared between many of the protocol messages. They are specified below.

Path

A path is a representation of a path relative to a specified content root.

Format

Please note that segments can only be ordinary file names, .. and . may not be supported.

interface Path {
  rootId: UUID;
  segments: [String];
}

namespace org.enso.languageserver.protocol.binary;

//A representation of a path relative to a specified content root.
table Path {

  //a content root id that the path is relative to
  rootId: EnsoUUID;

  //path segments
  segments: [string];

}

IPWithSocket

A IPWithSocket is an endpoint for communication between machines.

Format

interface IPWithSocket {
  host: String;
  port: Int;
}

EnsoUUID

An EnsoUUID is a value object containing 128-bit universally unique identifier.

Format

namespace org.enso.languageserver.protocol.binary;

//A binary representation of universally unique identifiers.
struct EnsoUUID {

  //The most significant bits of the UUID.
  leastSigBits:uint64;

  //The most significant bits of the UUID.
  mostSigBits:uint64;

}

Common Errors

ParseError

Signals that the message failed to parse.

"error" : {
  "code" : -32700,
  "message" : "Parse error"
}

InvalidRequest

Signals that the request is invalid.

"error" : {
  "code" : -32600,
  "message" : "Invalid Request"
}

MethodNotFound

Signals that the requested method is not supported.

"error" : {
  "code" : -32601,
  "message" : "Method not found"
}

InvalidParams

Signals that the parameters provided for the requested method were invalid.

This may indicate that the type or format of one of the parameters is different than expected.

"error" : {
  "code" : -32602,
  "message" : "Invalid params"
}

ServiceError

Signals a generic service error.

"error" : {
  "code" : 1,
  "message" : "Service error"
}

NotImplementedError

Signals that the requested method is supported, but it is has not been implemented yet.

"error" : {
  "code" : 10,
  "message" : "The requested method is not implemented"
}

RequestTimeoutError

Signals that request exceeded the waiting time.

"error" : {
  "code" : 11,
  "message" : "Request timeout"
}