JSON RPC 与 LSP 协议基础

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

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

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

报文划分

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

Header

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

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

Content

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

JSONRPC

Message

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

interface Message {
  // 表示 jsonrpc 的版本,在 LSP 中使用 2.0
  jsonrpc: "2.0";
}

RequestMessage

Request 是客户端向服务端发送的,结构如下:

interface RequestMessage extends Message {
  /**
   * 标识请求的 ID
   */
  id: integer | string;

  /**
   * 请求的方法
   */
  method: string;

  /**
   * 请求的参数
   */
  params?: array | object;
}

ResponseMessage

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

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

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

// 请求成功时,返回中携带 result 字段
interface ResponseSuccessMessage extends ResponseBaseMessage {
  /**
   * 请求成功后的结果
   */
  result: string | number | boolean | object | null;
}

// 请求失败时,返回中携带错误详情
interface ResponseErrorMessage extends ResponseBaseMessage {
  /**
   * 请求失败时的错误详情
   */
  error: ResponseError;
}

// 错误详情
interface ResponseError {
  /**
   * 错误代码
   */
  code: integer;

  /**
   * 错误的解释信息
   */
  message: string;

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

NotificationMessage

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

interface NotificationMessage extends Message {
  /**
   * 待触发的 method
   */
  method: string;

  /**
   * 通知的参数
   */
  params?: array | object;
}

实现相关(Implementation dependent)消息

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

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

取消请求($/cancelRequest

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

interface CancelParams {
  /**
   * The request id to cancel.
   */
  id: integer | string;
}

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

进度通知($/progress

since 3.15.0

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

type ProgressToken = integer | string;

interface ProgressParams<T> {
  /**
   * 标识进度的 token
   */
  token: ProgressToken;

  /**
   * 实际的进度数据
   */
  value: T;
}

错误代码

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

// 一些错误代码
export namespace ErrorCodes {
  // 由 JSON RPC 定义
  export const ParseError: integer = -32700;
  export const InvalidRequest: integer = -32600;
  export const MethodNotFound: integer = -32601;
  export const InvalidParams: integer = -32602;
  export const InternalError: integer = -32603;

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

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

  /**
   * JSON RPC 保留错误代码的结束
   *
   * @since 3.16.0
   */
  export const jsonrpcReservedErrorRangeEnd = -32000;
  /** @deprecated use jsonrpcReservedErrorRangeEnd */
  export const serverErrorEnd: integer = jsonrpcReservedErrorRangeEnd;

  /**
   * LSP 保留错误代码的开始
   *
   * @since 3.16.0
   */
  export const lspReservedErrorRangeStart: integer = -32899;

  export const ContentModified: integer = -32801;
  export const RequestCancelled: integer = -32800;

  /**
   * LSP 保留错误代码的结束
   *
   * @since 3.16.0
   */
  export const lspReservedErrorRangeEnd: integer = -32800;
}

暂无评论

发送评论 编辑评论


上一篇
下一篇