Categorygithub.com/creachadair/jrpc2
modulepackage
1.3.1
Repository: https://github.com/creachadair/jrpc2.git
Documentation: pkg.go.dev
Overview
Versions
2
Dependencies
16
Dependents
136
Files
1.8k SLOC

# README

jrpc2

GoDoc CI

This repository provides a Go module that implements a JSON-RPC 2.0 client and server. There is also a working example in the Go playground.

Packages

  • Package jrpc2 implements the base client and server and standard error codes.

  • Package channel defines the communication channel abstraction used by the server & client.

  • Package handler defines support for adapting functions to service methods.

  • Package jhttp allows clients and servers to use HTTP as a transport.

  • Package server provides support for running a server to handle multiple connections, and an in-memory implementation for testing.

Versioning

From v1.0.0 onward, the API of this module is considered stable, and I intend to merge no breaking changes to the API without increasing the major version number. Following the conventions of semantic versioning, the minor version will be used to signify the presence of backward-compatible new features (for example, new methods, options, or types), while the patch version will be reserved for bug fixes, documentation updates, and other changes that do not modify the API surface.

Note, however, that this intent is limited to the package APIs as seen by the Go compiler: Changes to the implementation that change observable behaviour in ways not promised by the documentation, e.g., changing performance characteristics or the order of internal operations, are not protected. Breakage that results from reliance on undocumented side-effects of the current implementation are the caller's responsibility.

Implementation Notes

The following describes some of the implementation choices made by this module.

Batch requests and error reporting

The JSON-RPC 2.0 spec is ambiguous about the semantics of batch requests. Specifically, the definition of notifications says:

A Notification is a Request object without an "id" member. ... 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").

This conflicts with the definition of batch requests, which asserts:

A Response object SHOULD exist for each Request object, except that there SHOULD NOT be any Response objects for notifications. ... The Response objects being returned from a batch call MAY be returned in any order within the Array. ... If the batch rpc call itself fails to be recognized as an valid JSON or as an Array with at least one value, the response from the Server MUST be a single Response object.

and includes examples that contain request values with no ID (which are, perforce, notifications) and report errors back to the client. Since order may not be relied upon, and there are no IDs, the client cannot correctly match such responses back to their originating requests.

This implementation resolves the conflict in favour of the batch rules. Specifically:

  • If a batch is empty or not valid JSON, the server reports error -32700 (Invalid JSON) as a single error Response object.

  • Otherwise, parse or validation errors resulting from any batch member without an ID are mapped to error objects with a null ID, in the same position in the reply as the corresponding request. Preservation of order is not required by the specification, but it ensures the server has stable behaviour.

Because a server is allowed to reorder the results, a client should not depend on this implementation detail.

# Packages

Package channel defines a communications channel.
Package handler provides implementations of the [jrpc2.Assigner] interface, and support for adapting functions to [jrpc2.Handler] signature.
Package jhttp implements a bridge from HTTP to JSON-RPC.
Package server provides support routines for running jrpc2 servers.
No description provided by the author

# Functions

ClientFromContext returns the client associated with the given context.
ErrorCode returns a Code to categorize the specified error.
Errorf returns an Error with the specified code and formatted message.
InboundRequest returns the inbound request associated with the context passed to a Handler, or nil if ctx does not have an inbound request.
Network guesses a network type for the specified address and returns a tuple of that type and the address.
NewClient returns a new client that communicates with the server via ch.
NewServer returns a new unstarted server that will dispatch incoming JSON-RPC requests according to mux.
ParseRequests parses either a single request or a batch of requests from JSON.
ServerFromContext returns the server associated with the context passed to a [Handler] by a [Server].
ServerMetrics returns a map of exported server metrics for use with the expvar package.
StdLogger adapts a [*log.Logger] to a [Logger].
StrictFields wraps a value v to require unknown fields to be rejected when unmarshaling from JSON.

# Constants

Request cancelled (context.Canceled).
Request deadline exceeded (context.DeadlineExceeded).
[std] Internal JSON-RPC error.
[std] Invalid method parameters.
[std] The JSON sent is not a valid request object.
[std] The method does not exist or is unavailable.
Denotes a nil error (used by ErrorCode).
[std] Invalid JSON received by the server.
Errors from the operating environment.
Version is the version string for the JSON-RPC protocol understood by this implementation, defined at http://www.jsonrpc.org/specification.

# Variables

ErrConnClosed is returned by a server's push-to-client methods if they are called after the client connection is closed.
ErrPushUnsupported is returned by the Notify and Call methods if server pushes are not enabled.

# Structs

A Client is a JSON-RPC 2.0 client.
ClientOptions control the behaviour of a client created by [NewClient].
Error is the concrete type of errors returned from RPC calls.
A ParsedRequest is the parsed form of a request message.
A Request is a request message from a client to a server.
A Response is a response message from a server to a client.
Server implements a JSON-RPC 2.0 server.
ServerInfo is the concrete type of responses from the rpc.serverInfo method.
ServerOptions control the behaviour of a server created by [NewServer].
ServerStatus describes the status of a stopped server.
A Spec combines a method name and parameter value as part of a Batch.

# Interfaces

An Assigner maps method names to [Handler] functions.
An ErrCoder is a value that can report an error code value.
Namer is an optional interface that an [Assigner] may implement to expose the names of its methods to the ServerInfo method.
An RPCLogger receives callbacks from a server to record the receipt of requests and the delivery of responses.

# Type aliases

A Code is an error code included in the JSON-RPC error object.
A Handler function implements a method.
A Logger records text logs from a server or a client.