mirror of
https://github.com/enso-org/enso.git
synced 2024-12-01 04:22:21 +03:00
114 lines
3.1 KiB
Markdown
114 lines
3.1 KiB
Markdown
---
|
|
layout: developer-doc
|
|
title: Enso Protocol Common Message Specification
|
|
category: language-server
|
|
tags: [language-server, protocol, specification]
|
|
order: 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-architecture).
|
|
|
|
<!-- MarkdownTOC levels="2,3" autolink="true" -->
|
|
|
|
- [Protocol Message Specification](#protocol-message-specification)
|
|
- [Common Types](#common-types)
|
|
- [`Path`](#path)
|
|
- [`IPWithSocket`](#ipwithsocket)
|
|
- [`EnsoUUID`](#ensouuid)
|
|
|
|
<!-- /MarkdownTOC -->
|
|
|
|
## 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.
|
|
|
|
```typescript
|
|
interface Path {
|
|
rootId: UUID;
|
|
segments: [String];
|
|
}
|
|
```
|
|
|
|
```idl
|
|
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
|
|
|
|
```typescript
|
|
interface IPWithSocket {
|
|
host: String;
|
|
port: Int;
|
|
}
|
|
```
|
|
|
|
### `EnsoUUID`
|
|
An EnsoUUID is a value object containing 128-bit universally unique identifier.
|
|
|
|
#### Format
|
|
|
|
```idl
|
|
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;
|
|
|
|
}
|
|
```
|