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

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;

}