jsonrpc

JSON-RPC is a stateless, light-weight remote procedure call (RPC) protocol. Primarily this specification defines several data structures and the rules around their processing. It is transport agnostic in that the concepts can be used within the same process, over sockets, over http, or in many various message passing environments. It uses JSON (RFC 4627) as data format.

The error codes from and including -32768 to -32000 are reserved for pre-defined errors. Any code within this range, but not defined explicitly below is reserved for future use.

code	message	meaning
-32700	Parse error	Invalid JSON was received by the server. An error occurred on the server while parsing the JSON text.
-32600	Invalid Request	The JSON sent is not a valid Request object.
-32601	Method not found	The method does not exist / is not available.
-32602	Invalid params	Invalid method parameter(s).
-32603	Internal error	Internal JSON-RPC error.
-32000 to -32099	Server error	Reserved for implementation-defined server-errors.

The remainder of the space is available for application defined errors.

Types

BatchRequest

opaque </>

A request that is made up of a list of JSON-RPC requests and/or notifications. Items in a batch request MUST be able to be processed in any other. As such, order is not preserved.

pub opaque type BatchRequest(a)

BatchRequestItem

</>

A union of the types allowed in a single batch request.

pub type BatchRequestItem(a) {
  BatchRequestItemRequest(Request(a))
  BatchRequestItemNotification(Notification(a))
}

Constructors

```
BatchRequestItemRequest(Request(a))
```

BatchRequestItemNotification(Notification(a))

BatchResponse

opaque </>

A response that is made up of a list of JSON-RPC responses and/or error responses. A batch response should contain a response or error response for each request in the request batch (except for notifications). Items in a batch response are not ordered. The client is responsible to map the response IDs to their own request IDs.

pub opaque type BatchResponse(a)

BatchResponseItem

</>

A union of the types allowed in a single batch response.

pub type BatchResponseItem(a) {
  BatchResponseItemResponse(Response(a))
  BatchResponseItemErrorResponse(ErrorResponse(a))
}

Constructors

```
BatchResponseItemResponse(Response(a))
```

BatchResponseItemErrorResponse(ErrorResponse(a))

ErrorBody

</>

When an RPC call encounters an error, the Response Object MUST contain the error member

pub type ErrorBody(data) {
  ErrorBody(code: Int, message: String, data: Option(data))
}

Constructors

```
ErrorBody(code: Int, message: String, data: Option(data))
```
Arguments

code

A Number that indicates the error type that occurred.

message

A String providing a short description of the error. The message SHOULD be limited to a concise single sentence.

data

A Primitive or Structured value that contains additional information about the error. This may be omitted. The value of this member is defined by the Server (e.g. detailed error information, nested errors etc.).

ErrorResponse

</>

When an RPC call encounters an error, the server MUST send an error response, except in the case of Notifications.

pub type ErrorResponse(data) {
  ErrorResponse(jsonrpc: Version, id: Id, error: ErrorBody(data))
}

Constructors

```
ErrorResponse(jsonrpc: Version, id: Id, error: ErrorBody(data))
```
Arguments

jsonrpc

Specifies the version of the JSON-RPC protocol. MUST be exactly “2.0”.

id

It MUST be the same as the value of the id member in the Request Object. If there was an error in detecting the id in the Request object (e.g. Parse error/Invalid Request), it MUST be Null.

error

When a rpc call encounters an error, the Response Object MUST contain the error member with a value that is a Object with the following members:

Id

</>

An identifier established by the Client that MUST contain a String, Number, or NULL value. The value SHOULD normally not be Null.

pub type Id {
  StringId(String)
  IntId(Int)
  NullId
}

Constructors

```
StringId(String)
```
```
IntId(Int)
```
```
NullId
```

JsonRpcError

opaque </>

Represents the error code and associated message. Error types provided by the JSON-RPC spec are already defined in the module.

pub opaque type JsonRpcError

Message

</>

A union of the JSON-RPC message types.

pub type Message {
  RequestMessage(Request(Dynamic))
  NotificationMessage(Notification(Dynamic))
  ResponseMessage(Response(Dynamic))
  ErrorResponseMessage(ErrorResponse(Dynamic))
  BatchRequestMessage(BatchRequest(Dynamic))
  BatchResponseMessage(BatchResponse(Dynamic))
}

Constructors

```
RequestMessage(Request(Dynamic))
```

NotificationMessage(Notification(Dynamic))

```
ResponseMessage(Response(Dynamic))
```

ErrorResponseMessage(ErrorResponse(Dynamic))

BatchRequestMessage(BatchRequest(Dynamic))

BatchResponseMessage(BatchResponse(Dynamic))

Nothing

opaque </>

A type that can help with type inference for RPC objects that omit optional fields.

pub opaque type Nothing

Notification

</>

A notification signifies the Client’s lack of interest in the corresponding Response object, and as such no Response object needs to be returned to the client. The Server MUST NOT reply to a Notification, including those that are within a batch request.

Notifications are not confirmable by definition, since they do not have a Response object to be returned. As such, the Client would not be aware of any errors (like e.g. “Invalid params”,“Internal error”).

pub type Notification(params) {
  Notification(
    jsonrpc: Version,
    method: String,
    params: Option(params),
  )
}

Constructors

```
Notification(
  jsonrpc: Version,
  method: String,
  params: Option(params),
)
```
Arguments

jsonrpc

Specifies the version of the JSON-RPC protocol. MUST be exactly “2.0”.

method

A String containing the name of the method to be invoked. Method names that begin with the word rpc followed by a period character (U+002E or ASCII 46) are reserved for rpc-internal methods and extensions and MUST NOT be used for anything else.

params

A Structured value that holds the parameter values to be used during the invocation of the method. This member MAY be omitted.

Request

</>

An RPC call to a server

pub type Request(params) {
  Request(
    jsonrpc: Version,
    method: String,
    id: Id,
    params: Option(params),
  )
}

Constructors

```
Request(
  jsonrpc: Version,
  method: String,
  id: Id,
  params: Option(params),
)
```
Arguments

jsonrpc

Specifies the version of the JSON-RPC protocol. MUST be exactly “2.0”.

method

A String containing the name of the method to be invoked. Method names that begin with the word rpc followed by a period character (U+002E or ASCII 46) are reserved for rpc-internal methods and extensions and MUST NOT be used for anything else.

id

An identifier established by the Client that MUST contain a String, Number, or NULL value. The value SHOULD normally not be Null.

params

A Structured value that holds the parameter values to be used during the invocation of the method. This member MAY be omitted.

Response

</>

When an RPC call is made, the Server MUST reply with a Response, except for in the case of Notifications.

pub type Response(result) {
  Response(jsonrpc: Version, id: Id, result: result)
}

Constructors

```
Response(jsonrpc: Version, id: Id, result: result)
```
Arguments

jsonrpc

Specifies the version of the JSON-RPC protocol. MUST be exactly “2.0”.

id

It MUST be the same as the value of the id member in the Request Object.

result

The value of this member is determined by the method invoked on the Server.

Version

</>

Specifies the version of the JSON-RPC protocol. Only 2.0 is supported.

pub type Version {
  V2
}

Constructors

```
V2
```

Values

add_error_response

</>

pub fn add_error_response(
  batch_response: BatchResponse(Json),
  error_response: ErrorResponse(a),
  data_to_json: fn(a) -> Json,
) -> BatchResponse(Json)

Add an error response to a batch response. Batch responses have no guarantees about order. Therefore order is not preserved when your batch response is sent.

add_notification

</>

pub fn add_notification(
  batch_request: BatchRequest(Json),
  notification: Notification(a),
  params_to_json: fn(a) -> Json,
) -> BatchRequest(Json)

Add a notification to a batch request. Batch requests have no guarantees about order. Therefore order is not preserved when your batch request is sent.

add_request

</>

pub fn add_request(
  batch_request: BatchRequest(Json),
  request: Request(a),
  params_to_json: fn(a) -> Json,
) -> BatchRequest(Json)

Add a request to a batch request. Batch requests have no guarantees about order. Therefore order is not preserved when your batch request is sent.

add_response

</>

pub fn add_response(
  batch_response: BatchResponse(Json),
  response: Response(a),
  result_to_json: fn(a) -> Json,
) -> BatchResponse(Json)

Add a response to a batch response. Batch responses have no guarantees about order. Therefore order is not preserved when your batch response is sent.

application_error

</>

pub fn application_error(
  code: Int,
  message: String,
) -> Result(JsonRpcError, Nil)

An error defined for your specific application. The error code MUST not be within the range -32768 to -32000, otherwise Error(Nil) will be returned. The message SHOULD be limited to a concise single sentence.

batch_request

</>

pub fn batch_request() -> BatchRequest(Json)

Create a new, empty batch request

batch_request_decoder

</>

pub fn batch_request_decoder() -> Decoder(BatchRequest(Dynamic))

batch_request_item_decoder

</>

pub fn batch_request_item_decoder() -> Decoder(
  BatchRequestItem(Dynamic),
)

batch_request_item_to_json

</>

pub fn batch_request_item_to_json(
  item: BatchRequestItem(Json),
) -> Json

batch_request_items

</>

pub fn batch_request_items(
  batch_request: BatchRequest(a),
) -> List(BatchRequestItem(a))

retrieve the list of BatchRequestItems

batch_request_to_json

</>

pub fn batch_request_to_json(
  batch_request: BatchRequest(Json),
) -> Json

batch_response

</>

pub fn batch_response() -> BatchResponse(Json)

Create a new, empty batch response

batch_response_decoder

</>

pub fn batch_response_decoder() -> Decoder(BatchResponse(Dynamic))

batch_response_item_decoder

</>

pub fn batch_response_item_decoder() -> Decoder(
  BatchResponseItem(Dynamic),
)

batch_response_item_to_json

</>

pub fn batch_response_item_to_json(
  item: BatchResponseItem(Json),
) -> Json

batch_response_items

</>

pub fn batch_response_items(
  batch_response: BatchResponse(a),
) -> List(BatchResponseItem(a))

retrieve the list of BatchResponseItems

batch_response_to_json

</>

pub fn batch_response_to_json(
  batch_response: BatchResponse(Json),
) -> Json

decode_errors

</>

pub fn decode_errors(errors: List(DecodeError)) -> JsonRpcError

Get the appropriate JsonRpcError based on a request’s decode.DecodeErrors.

error_code

</>

pub fn error_code(error: JsonRpcError) -> Int

Retrieve this error’s code

error_decoder

</>

pub fn error_decoder(
  data_decoder: Decoder(a),
) -> Decoder(ErrorBody(a))

error_message

</>

pub fn error_message(error: JsonRpcError) -> String

Retrieve this error’s message

error_response

</>

pub fn error_response(
  error error: JsonRpcError,
  id id: Id,
) -> ErrorResponse(a)

Creates a new error response with empty data. Error code and message are populated with the values from error.

error_response_data

</>

pub fn error_response_data(
  error_response: ErrorResponse(a),
  data: b,
) -> ErrorResponse(b)

Sets the data of this error response

error_response_decoder

</>

pub fn error_response_decoder(
  data_decoder: Decoder(a),
) -> Decoder(ErrorResponse(a))

error_response_from

</>

pub fn error_response_from(
  json_error: DecodeError,
  id: Id,
) -> ErrorResponse(Nothing)

error_response_to_json

</>

pub fn error_response_to_json(
  error_response: ErrorResponse(a),
  encode_data: fn(a) -> Json,
) -> Json

error_to_json

</>

pub fn error_to_json(
  error: ErrorBody(a),
  encode_data: fn(a) -> Json,
) -> Json

id

</>

pub fn id(id: Int) -> Id

Creates an Int ID

id_decoder

</>

pub fn id_decoder() -> Decoder(Id)

id_to_json

</>

pub fn id_to_json(id: Id) -> Json

internal_error

</>

pub const internal_error: JsonRpcError

Internal JSON-RPC error.

invalid_params

</>

pub const invalid_params: JsonRpcError

Invalid method parameter(s).

invalid_request

</>

pub const invalid_request: JsonRpcError

The JSON sent is not a valid Request object.

json_error

</>

pub fn json_error(error: DecodeError) -> JsonRpcError

Get the appropriate JsonRpcError based on a request’s json.DecodeError.

message_decoder

</>

pub fn message_decoder() -> Decoder(Message)

method_not_found

</>

pub const method_not_found: JsonRpcError

The method does not exist / is not available.

nothing_decoder

</>

pub fn nothing_decoder() -> Decoder(Nothing)

A decoder for the Nothing type, which is impossible to create. This decoder is intended for fields you KNOW are omitted, and therefore it will never be ran. It will always fail if ran

nothing_to_json

</>

pub fn nothing_to_json(nothing: Nothing) -> Json

Encode json for the Nothing type, which is impossible to create. This is intended for fields you KNOW are omitted, and therefore it will never be ran. It will always return null if ran.

notification

</>

pub fn notification(method: String) -> Notification(a)

Creates a new notification with empty params

notification_decoder

</>

pub fn notification_decoder(
  params_decoder: Decoder(a),
) -> Decoder(Notification(a))

notification_params

</>

pub fn notification_params(
  notification: Notification(a),
  params: b,
) -> Notification(b)

Sets the params for this notification

notification_to_json

</>

pub fn notification_to_json(
  notification: Notification(a),
  encode_params: fn(a) -> Json,
) -> Json

parse_error

</>

pub const parse_error: JsonRpcError

Invalid JSON was received by the server. An error occurred on the server while parsing the JSON text.

request

</>

pub fn request(method method: String, id id: Id) -> Request(a)

Creates a new request with empty params

request_decoder

</>

pub fn request_decoder(
  params_decoder: Decoder(a),
) -> Decoder(Request(a))

request_params

</>

pub fn request_params(
  request: Request(a),
  params: b,
) -> Request(b)

Sets the params of this request

request_to_json

</>

pub fn request_to_json(
  request: Request(a),
  encode_params: fn(a) -> Json,
) -> Json

response

</>

pub fn response(result result: a, id id: Id) -> Response(a)

Creates a new response

response_decoder

</>

pub fn response_decoder(
  result_decoder: Decoder(a),
) -> Decoder(Response(a))

response_to_json

</>

pub fn response_to_json(
  response: Response(a),
  encode_result: fn(a) -> Json,
) -> Json

server_error

</>

pub fn server_error(code: Int) -> Result(JsonRpcError, Nil)

An error reserved for implementation-defined server-errors. The error code MUST be within the range -32099 to -32000, otherwise Error(Nil) will be returned.

version_decoder

</>

pub fn version_decoder() -> Decoder(Version)

version_to_json

</>

pub fn version_to_json(version: Version) -> Json

Constructors

Constructors

Constructors

Arguments

Constructors

Arguments

Constructors

Constructors

Constructors

Arguments

Constructors

Arguments

Constructors

Arguments

Constructors