JSON RPC 与 LSP 协议基础

之前实现 ZenScript 的 LSP 的时候只是简单实现了一个 server，没有对协议相关的功能进行更深入的了解。最近四个月前因为工作原因开始重新关注起这方面的内容，于是开始对协议的相关内容进行整理清库存。

本文基于 Language Server Protocol 3.16 编写，与当前的 LSP 版本可能不完全一致，阅读时需要注意。

什么 LSP，哪有 LSP，哦，是我啊

报文划分

LSP 的报文划分为 Header 和 Content 两个部分。二者之间通过 \r\n 隔开，很有微软的风格。

`Header`

Header 的组织方式和 Http 很像，也是通过 : （冒号空格）的方式隔开。Header 之间也是通过 \r\n 分割的。

目前支持的 Header 有两个：Content-Length 和 Content-Type。其中前者为必选，后者默认为 application/vscode-jsonrpc; charset=utf-8。

`Content`

LSP 中的 Content 通过 jsonrpc 的方式组织。

JSONRPC

`Message`

这里定义了 Message 作为所有消息的共有内容。

1
interface Message {
2
  // 表示 jsonrpc 的版本，在 LSP 中使用 2.0
3
  jsonrpc: "2.0";
4
}

`RequestMessage`

Request 是客户端向服务端发送的，结构如下：

1
interface RequestMessage extends Message {
2
  /**
3
   * 标识请求的 ID
4
   */
5
  id: integer | string;
6

7
  /**
8
   * 请求的方法
9
   */
10
  method: string;
11

12
  /**
13
   * 请求的参数
14
   */
15
  params?: array | object;
16
}

`ResponseMessage`

对应客户端请求的 Request 的就是服务端返回的 Response 了。结构如下：

1
// 请求的返回，有成功和失败两种情况
2
type ResponseMessage = ResponseSuccessMessage | ResponseErrorMessage;
3

4
// 两种情况都需要包含对应的请求 ID
5
interface ResponseBaseMessage extends Message {
6
  /**
7
   * 返回对应的请求 ID
8
   */
9
  id: integer | string | null;
10
}
11

12
// 请求成功时，返回中携带 result 字段
13
interface ResponseSuccessMessage extends ResponseBaseMessage {
14
  /**
15
   * 请求成功后的结果
16
   */
17
  result: string | number | boolean | object | null;
18
}
19

20
// 请求失败时，返回中携带错误详情
21
interface ResponseErrorMessage extends ResponseBaseMessage {
22
  /**
23
   * 请求失败时的错误详情
24
   */
25
  error: ResponseError;
26
}
27

28
// 错误详情
29
interface ResponseError {
30
  /**
31
   * 错误代码
32
   */
33
  code: integer;
34

35
  /**
36
   * 错误的解释信息
37
   */
38
  message: string;
39

40
  /**
41
   * 错误的可选附加信息
42
   */
43
  data?: string | number | boolean | array | object | null;
44
}

`NotificationMessage`

除请求和相应之外，jsonrpc 还定义了一种消息类型：通知。通知的工作方式和 event 类似，没有返回（Response）。定义如下：

1
interface NotificationMessage extends Message {
2
  /**
3
   * 待触发的 method
4
   */
5
  method: string;
6

7
  /**
8
   * 通知的参数
9
   */
10
  params?: array | object;
11
}

实现相关（`Implementation dependent`）消息

对以 $/ 字符串开头的 method 字段，其表示对应的消息是实现相关的，服务端或客户端可能没有实现此类方法。

当收到一个未实现的实现相关通知时，服务端或客户端可以直接忽略该通知；当收到一个未实现的实现相关请求（**Request**）时，其必须返回 MethodNotFound 错误（-32601）。

取消请求（`$/cancelRequest`）

取消请求可以用于正在进行的请求中，通过指定请求的 id 尝试取消对应 id 的请求操作。定义如下：

1
interface CancelParams {
2
  /**
3
   * The request id to cancel.
4
   */
5
  id: integer | string;
6
}

为了和 jsonrpc 契合，已经取消的请求也必须产生对应的返回（Response）。当被取消的请求返回产生错误时，可以选用 ErrorCodes.RequestCancelled。

进度通知（`$/progress`）

since 3.15.0

LSP 提供了一种抽象的进度报告方式以对进度进行汇报。进度的标识通过 ProgressToken 表示，使得进度可以通过 Notification 的形式报告。结构定义如下：

1
type ProgressToken = integer | string;
2

3
interface ProgressParams<T> {
4
  /**
5
   * 标识进度的 token
6
   */
7
  token: ProgressToken;
8

9
  /**
10
   * 实际的进度数据
11
   */
12
  value: T;
13
}

错误代码

jsonrpc 定义了一些错误代码用于表示其内部错误，同时保留了一部分区间作为 reserved error code；LSP 也定义了一些错误代码，总体定义如下：

1
// 一些错误代码
2
export namespace ErrorCodes {
3
  // 由 JSON RPC 定义
4
  export const ParseError: integer = -32700;
5
  export const InvalidRequest: integer = -32600;
6
  export const MethodNotFound: integer = -32601;
7
  export const InvalidParams: integer = -32602;
8
  export const InternalError: integer = -32603;
9

10
  /**
11
   * JSON RPC 保留错误代码的开始
12
   *
13
   * LSP 的错误代码不应该被定义在这个区间之内
14
   * 除了为了兼容而定义的 `ServerNotInitialized` 和 `UnknownErrorCode`
15
   *
16
   * @since 3.16.0
17
   */
18
  export const jsonrpcReservedErrorRangeStart: integer = -32099;
19
  /** @deprecated use jsonrpcReservedErrorRangeStart */
20
  export const serverErrorStart: integer = jsonrpcReservedErrorRangeStart;
21

22
  /**
23
   * 错误代码：表示 LSP 服务器在收到 `initialized` Notification
24
   * 之前收到了其他请求或 `Notification`
25
   */
26
  export const ServerNotInitialized: integer = -32002;
27
  export const UnknownErrorCode: integer = -32001;
28

29
  /**
30
   * JSON RPC 保留错误代码的结束
31
   *
32
   * @since 3.16.0
33
   */
34
  export const jsonrpcReservedErrorRangeEnd = -32000;
35
  /** @deprecated use jsonrpcReservedErrorRangeEnd */
36
  export const serverErrorEnd: integer = jsonrpcReservedErrorRangeEnd;
37

38
  /**
39
   * LSP 保留错误代码的开始
40
   *
41
   * @since 3.16.0
42
   */
43
  export const lspReservedErrorRangeStart: integer = -32899;
44

45
  export const ContentModified: integer = -32801;
46
  export const RequestCancelled: integer = -32800;
47

48
  /**
49
   * LSP 保留错误代码的结束
50
   *
51
   * @since 3.16.0
52
   */
53
  export const lspReservedErrorRangeEnd: integer = -32800;
54
}

ToC

报文划分

Header

Content

JSONRPC

Message

RequestMessage

ResponseMessage

NotificationMessage

实现相关（Implementation dependent）消息

取消请求（$/cancelRequest）

进度通知（$/progress）