enso/docs/language-server/protocol-project-manager.md

layout	title	category	tags	order
developer-doc	Enso Protocol Project Manager Message Specification	language-server	language-server protocol specification	3

Enso Protocol Project Manager Message Specification

This document contains the specification of the Enso protocol messages that pertain to the project manager component. Please familiarise yourself with the common features of the protocol before reading this document.

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

• Types
  • ProjectMetadata
• Project Management Operations
  • project/open
  • project/close
  • project/list
  • project/create
  • project/delete
  • project/listSample
• Language Server Management
• Errors
  • ProjectNameValidationError
  • ProjectDataStoreError
  • ProjectExistsError
  • ProjectNotFoundError
  • ProjectOpenError
  • ProjectCloseError
  • ProjectNotOpenError
  • ProjectOpenByOtherPeersError
  • CannotRemoveOpenProjectError

Types

There are a number of types that are used only within the project server's protocol messages. These are specified here.

ProjectMetadata

This type represents information about a project.

Format

interface ProjectMetadata {
  name: String;
  id: UUID;
  lastOpened: UTCDateTime;
}

Project Management Operations

The primary responsibility of the project managers is to allow users to manage their projects.

project/open

This message requests that the project manager open a specified project. This operation also includes spawning an instance of the language server open on the specified project.

• Type: Request
• Direction: Client -> Server
• Connection: Protocol
• Visibility: Public

Parameters

interface ProjectOpenRequest {
  projectId: UUID;
}

Result

interface ProjectOpenResult {
  languageServerJsonAddress: IPWithSocket;
  languageServerBinaryAddress: IPWithSocket;
}

Errors

• ProjectNotFoundError to signal that the project doesn't exist.
• ProjectDataStoreError to signal problems with underlying data store.
• ProjectOpenError to signal failures during server boot.

project/close

This message requests that the project manager close a specified project. This operation includes shutting down the language server gracefully so that it can persist state to disk as needed.

• Type: Request
• Direction: Client -> Server
• Connection: Protocol
• Visibility: Public

Parameters

interface ProjectCloseRequest {
  projectId: UUID;
}

Result

{}

Errors

• ProjectNotFoundError to signal that the project doesn't exist.
• ProjectDataStoreError to signal problems with underlying data store.
• ProjectCloseError to signal failures that occurred during language server stoppage.
• ProjectNotOpenError to signal cannot close a project that is not open.
• ProjectOpenByOtherPeersError to signal that cannot close a project that is open by other clients.

project/list

This message requests that the project manager lists all user's projects. The list of projects is sorted by the open time.

• Type: Request
• Direction: Client -> Server
• Connection: Protocol
• Visibility: Public

Parameters

interface ProjectListRequest {
  numberOfProjects?: Int;
}

Result

interface ProjectListResponse {
  projects: [ProjectMetadata];
}

Errors

• ProjectDataStoreError to signal problems with underlying data store.

project/create

This message requests the creation of a new project.

• Type: Request
• Direction: Client -> Server
• Connection: Protocol
• Visibility: Public

Parameters

interface ProjectCreateRequest {
  name: String;
}

Result

interface ProjectOpenResponse {
  projectId: UUID;
}

Errors

• ProjectNameValidationError to signal validation failures.
• ProjectDataStoreError to signal problems with underlying data store.
• ProjectExistsError to signal that the project already exists.

project/delete

This message requests the deletion of a project.

• Type: Request
• Direction: Client -> Server
• Connection: Protocol
• Visibility: Public

Parameters

interface ProjectDeleteRequest {
  projectId: UUID;
}

Result

{}

Errors

• ProjectDataStoreError to signal problems with underlying data store.
• ProjectNotFoundError to signal that the project doesn't exist.
• CannotRemoveOpenProjectError to signal that the project cannot be removed, because is open by at least one user.

project/listSample

This request lists the sample projects that are available to the user.

• Type: Request
• Direction: Client -> Server
• Connection: Protocol
• Visibility: Public

Parameters

interface ProjectListSampleRequest {
  numProjects: Int;
}

Result

interface ProjectListSampleResponse {
  projects: [ProjectMetadata];
}

Errors

TBC

Language Server Management

The project manager is also responsible for managing the language server. This means that it needs to be able to spawn the process, but also tell the process when to shut down.

The actionables for this section are:

• Fill it in when we have more of an idea about exactly how this spawning relationship is going to work.

Errors

The project manager component has its own set of errors. This section is not a complete specification and will be updated as new errors are added.

ProjectNameValidationError

Signals validation failures.

"error" : {
  "code" : 4001,
  "message" : "Cannot create project with empty name"
}

ProjectDataStoreError

Signals problems with underlying data store.

"error" : {
  "code" : 4002,
  "message" : "Cannot load project index"
}

ProjectExistsError

Signals that the project already exists.

"error" : {
  "code" : 4003,
  "message" : "Project with the provided name exists"
}

ProjectNotFoundError

Signals that the project doesn't exist.

"error" : {
  "code" : 4004,
  "message" : "Project with the provided id does not exist"
}

ProjectOpenError

Signals that the project cannot be open due to boot failures.

"error" : {
  "code" : 4005,
  "message" : "A boot failure."
}

ProjectCloseError

Signals failures during shutdown of a server.

"error" : {
  "code" : 4009,
  "message" : "A shutdown failure."
}

ProjectNotOpenError

Signals that cannot close project that is not open.

"error" : {
  "code" : 4006,
  "message" : "Cannot close project that is not open"
}

ProjectOpenByOtherPeersError

Signals that cannot close a project that is open by other clients.

"error" : {
  "code" : 4007,
  "message" : "Cannot close project because it is open by other peers"
}

CannotRemoveOpenProjectError

Signals that cannot remove open project.

"error" : {
  "code" : 4008,
  "message" : "Cannot remove open project"
}