# An implementation of the JSON-RPC for Scheme


## Introduction

*EXPERIMENTAL*

The JSON-RPC is allows calling procedures on remote servers by
exchanging JSON objects. It's specification can be found at
[https://www.jsonrpc.org/specification](https://www.jsonrpc.org/specification).

The low-level API strives to be R7RS compliant, relying on some SRFI's when needed. 
So far it was only tested under CHICKEN 5 and Guile 3.

## Installing

The library is small enough so that simply *loading* the *.sld* file
and *importing* `(json-rpc)` should be sufficient. 
Due to limitations of Guile's R7RS support, a separate *.sld* is
provided for it.

## (Un)marshalling

To allow using different JSON representations, this library doesn't make
any assumptions regarding how JSON objects are mapped to Scheme structures. Before calling any functions, the user *must* define marshalling
and unmarshalling functions using following parameters:

```
[parameter] scheme->json-string

[parameter] json-string->scheme
```

## API
### High-level API
```
[parameter] json-rpc-handler-table
```
An association list mapping method names (*strings*) to functions that
get an unmarshalled scheme object as input. These handlers must return
a scheme object that is *mappable* to a JSON string using the defined
`scheme->json-string` parameter.

```
[function] (json-rpc-call in-port out-port method params)
[function] (json-rpc-call/tcp tcp-address tcp-port method params)
```
Call the remote procedure `method` (string) with the JSON-mappable scheme object `params`.

```
[function] (json-rpc-start-server/tcp tcp-port)
```
Listen on `tcp-port` and loop over input connections, answering requests according to `json-rpc-handler-table`.

### Low-level API
```
[function] (json-rpc-read input-port)
```
Read from `input-port` and return a Scheme object based on the provided
`json-string->scheme` parameter.

```
[function] (json-rpc-write scm output-port)
```
Convert the scheme object `scm` to a JSON string using the provided paramter `scheme->json-string` and writes the result to `output-port`.

```
[function] (json-rpc-loop input-port output-port)
```
JSON-RPC 2.0 demands that all requests are answered. This functions loops over `input-port` and answers to the requests through `output-port` using the handlers defined in `json-rpc-handler-table`.

## LICENSE

This Software is licensed under the MIT License. See `LICENSE` for more details.