Implementation of JSON-RPC in kotlinx.rpc

1.1. Goals

• Provide a full implementation of JSON-RPC 2.0 protocol in kotlinx.rpc¶

• Support for both suspend functions and flows between Kotlin endpoints¶

• Simple compatibility for suspend functions with non-Kotlin endpoints¶

• Maintain backwards compatibility¶

• Add a minimal API surface (while reusing existing APIs in kotlinx.rpc core)¶

• Stay transport-agnostic¶

• Provide Ktor integrations¶

• No code changes, instead the implementation shall live in new module(s)¶

• No changes to the compiler plugin¶

1.2. Non-Goals

• Extend or modify JSON-RPC 2.0 protocol¶

• Compatibility for flows with non-Kotlin endpoints (since JSON-RPC 2.0 does not provide streaming semantics)¶

2.1. Notifications

JSON-RPC defines notifications as requests that must not be responded to.¶

Importantly, the server can't repsond to them with errors, either.¶

While it seems natural to use a Unit return type for notifications, it can be surprising to the user that errors aren't propagated.¶

To sidestep this problem, a custom NotificationOk return type is provided for notifications:¶

public data object NotificationOk

For example:¶

@Rpc interface Foo {
    suspend fun noResponse(): NotificationOk
    suspend fun mightError()
}

noResponse is a notification, while mightError is a normal request that can result in an exception.¶

2.2. Reserved method names

While JSON-RPC reserves method names starting with rpc., the implementation shall make no effort to enforce this restriction.¶

Instead, we assume that, if the user defines such a method, they know what they are doing.¶

2.3. Parameter encoding

JSON-RPC allows parameters in a request to be passed by-position (as an array) or by-name (as an object).¶

Since we'd like to support the full JSON-RPC spec, we provide a ParameterEncoding enum:¶

public enum class ParameterEncoding { ByName, ByPosition }

API methods should have ByName as a default where possible, since it's more human-readable.¶

The choice of parameter encoding is configurable on the client only. The server must support both encodings.¶

A minor complication arises with the currently-experimental context parameters, since context parameters may have no name.¶

In that case, they're assumed to have the special name <contextN>, where N is the index of the context parameter in the parameter list.¶

An alternative is to simply not support unnamed context parameters with by-name encoding, but that seems less than ideal.¶

2.4. Ids

Every JSON-RPC request must have an id, except for notifications.¶

We thus specify that the client must generate numerical ids and ensure their uniqueness.¶

2.5. Serialization

In the presence of complex data in the parameters or return types of API methods, serialization is necessary.¶

Since JSON-RPC is JSON-based, we can only support String-based serialization formats.¶

Hence, we use StringFormat from kotlinx.serialization as the serialization abstraction.¶

2.6. Errors

JSON-RPC requires an error code in error responses.¶

Kotlin exceptions don't come with error codes, so, we provide a public JsonRpcException type as follows:¶

public class JsonRpcException(val code: Int, message: String): IllegalStateException(message)

We make no effort to validate error codes, instead leaving it up to the user to provide appropriate codes.¶

For all other exceptions, we use the error code -32000, which is within the server error range defined by JSON-RPC.¶

Importantly, JSON-RPC reserves some error codes for special RPC errors, with the relevant ones being (adapted from JSON-RPC 2.0 §5.1):¶

These errors must be used by the implementation where appropriate.¶

The error response's message field must contain the Exception's message.¶

The error response's data field must contain, at a minimum, the fully-qualified name of the Exception class and the stacktrace.¶

Other fields may be added as necessary.¶

Alternatively, SerializedException, which is internally used by Krpc, may be moved into core and used for this purpose.¶

2.7. Batching

JSON-RPC supports batching of requests into a single request (as an array).¶

The server implementation must support batching.¶

Batching on the client is to be done on a best-effort basis, i.e., the client may choose to batch requests or not.¶

The relaxed constraint is to ensure that the client can make requests in a timely fashion.¶

2.8. Transport

Since the protocol communicates through JSON, all we require is a transport that can send and receive strings.¶

We thus define a simple JsonRpcTransport interface as follows:¶

public interface JsonRpcTransport : CoroutineScope {
    suspend fun send(message: String)
    suspend fun receive(): String
}

Importantly, the transport is also a CoroutineScope, to allow for cancellation when needed. IT also thus provides a coroutineContext which determines important coroutine properties such as the dispatcher.¶

2.9. Entrypoints

Kotlinx.rpc provides RpcClient and RpcServer interfaces as the main entrypoints for clients and servers, respectively.¶

We thus provide JsonRpcClient and JsonRpcServer implementations of these interfaces:¶

public class JsonRpcClient(
        private val format: StringFormat,
        private val encoding: ParameterEncoding = ParameterEncoding.ByName,
        private val transport: JsonRpcTransport,
): RpcClient
public class JsonRpcServer(
    private val format: StringFormat,
    private val transport: JsonRpcTransport,
): RpcServer {
    public fun close(message: String? = null) { ... }
    public suspend fun awaitCompletion() { ... }
}

3.1. Transport

Our canonical Ktor transport implementation, using Ktor's WebSocketSession, is as follows:¶

@InternalRpcApi
public class KtorTransport(private val webSocketSession: WebSocketSession) : JsonRpcTransport, CoroutineScope by webSocketSession {
    override suspend fun send(message: String) = webSocketSession.send(message)

    override suspend fun receive(): KrpcTransportMessage = webSocketSession.incoming.receive() as? Frame.Text ?: error("Unsupported websocket frame type: ${message::class}. Expected Frame.Text")
}

We use @InternalRpcApi from core to denote that this API is not intended for public use.¶

3.2. Client

Ktor client APIs are provided in Appendix A (Appendix A).¶

Importantly, we provide an installJsonRpc extension function that takes in a StringFormat and an optional ParameterEncoding, and installs the necessary WebSocket support.¶

HttpClient.rpc sets up the websocket and allows the user to configure the url and other HttpRequestBuilder properties; the returned JsonRpcClient can then be used to access RPC services¶

3.3. Server

Ktor server APIs are provided in Appendix B (Appendix B).¶

Importantly, we provide an installJsonRpc extension function that takes in a StringFormat and installs the necessary WebSocket support.¶

Route.rpc sets up the websocket route and allows the user to register services inside the block.¶