{"size": 4002, "ext": "scrbl", "max_stars_repo_path": "doc/utils/rpc/json.scrbl", "max_stars_repo_name": "christoff-buerger/sagittarius-scheme", "max_stars_repo_stars_event_min_datetime": "2015-11-07T07:13:35.000Z", "max_stars_repo_stars_event_max_datetime": "2022-02-15T03:35:14.000Z", "max_issues_repo_path": "doc/utils/rpc/json.scrbl", "max_issues_repo_name": "christoff-buerger/sagittarius-scheme", "max_issues_repo_issues_event_min_datetime": "2016-04-28T21:59:59.000Z", "max_issues_repo_issues_event_max_datetime": "2021-07-01T08:42:21.000Z", "max_forks_repo_path": "doc/utils/rpc/json.scrbl", "max_forks_repo_name": "christoff-buerger/sagittarius-scheme", "max_forks_repo_forks_event_min_datetime": "2016-12-28T12:41:23.000Z", "max_forks_repo_forks_event_max_datetime": "2020-02-26T20:52:02.000Z"}
{"max_stars_count": 39, "max_issues_count": 3, "max_forks_count": 4, "avg_line_length": 36.0540540541, "max_line_length": 80, "alphanum_fraction": 0.7446276862}
@; -*- mode:scribble; coding: utf-8 -*-

@subsection[:tag "lib.rpc.json"]{(rpc json) - JSON RPC library}

@define[Library]{@name{(rpc json)}}
@desc{This library provides procedures handling 
@hyperlink[:href "http://www.jsonrpc.org/specification"]{JSON RPC 2.0}.

This library doesn't provide transport layer. To send request and receive
response, use @secref["utils.rpc.transport.http"]{Http transport}.

This library uses @secref["ported.json"]{JSON parser library} and its
JSON representation.
}

Following piece of code describes how to use;
@codeblock{

(import (rnrs) (rpc json) (rpc transport http))

(define (json-rpc-send&request url method param)
  (let ((request (make-json-request method :param param)))
    (let-values (((status header response) (rpc-http-request url request)))
      ;; rpc-http-request unmarshalls only when HTTP status starts with "2"
      ;; for this example we don't check it.
      (json-response-result response))))

(json-rpc-send&request "http://localhost/json-rpc" "sample" "parameter")
;; -> result of method execution
}

@define[Class]{@name{<json-request>}}
@define[Class]{@name{<json-response>}}
@desc{These classes represents JSON RPC request and response respectively.

The class instance should be created by @code{make-json-request},
@code{json-string->json-request} or @code{json-string->json-response}. Users
should not create an instance directly using @code{make}.
}

@subsubsection{Predicates}

@define[Function]{@name{json-request?} @args{object}}
@define[Function]{@name{json-response?} @args{object}}
@desc{Returns #t if the given @var{object} is an instance of 
@code{<json-request>} and @code{<json-response>} respectively.
}

@subsubsection{Constructors}

@define[Function]{@name{make-json-request} @args{method :key (params '()) id}}
@desc{Creates a JSON RPC request.

@var{method} must be a symbol or string represents method name to be invoked.

The keyword argument @var{params} is the @code{params} field of the JSON
RPC protocol.

The keyword argument @var{id} is the @code{id} field of the JSON RPC protocol.
If this is not specified then a value generated by UUID v4 will be used.
}

@define[Function]{@name{json-string->json-request} @args{json}}
@define[Function]{@name{json-string->json-response} @args{json}}
@desc{Creates JSON RPC request and response from given JSON string @var{json}.
}

@subsubsection{Accessors}

@define[Function]{@name{json-request-method} @args{json-request}}
@define[Function]{@name{json-request-params} @args{json-request}}
@define[Function]{@name{json-request-id} @args{json-request}}
@desc{Retrieves JSON RPC request's method, params and id respectively from given
json request object @var{json-request}.
}

@define[Function]{@name{json-response-result} @args{json-response}}
@define[Function]{@name{json-response-id} @args{json-response}}
@desc{Retrieves JSON RPC response's result and id respectively from given
json response object @var{json-response}.
}

@subsubsection{Converters}

@define[Function]{@name{json-request->json-string} @args{json-request}}
@define[Function]{@name{json-response->json-string} @args{json-response}}
@desc{Converts given @var{json-request} and @var{json-response} to JSON string.
}

@subsubsection{Implemented methods}

Following methods are currently used only in @code{(rpc http transport)}.
When we support other transport, this implementation may change.

@sub*section{Message methods}

@define[Method]{@name{rpc-marshall-message} @args{(message <json-request>)}}
@desc{Converts to given JSON RPC request object to UTF8 bytes.}

@define[Method]{@name{rpc-unmarshall-message} @args{(type (eql 'json)) body}}
@desc{Converts to given UTF8 bytes to JSON RPC response object.}

@sub*section{Transport methods}

@define[Method]{@name{rpc-http-content-type} @args{(message <json-request>)}}
@desc{Returns @code{application/json} content type header value}

@define[Method]{@name{rpc-http-response-type} @args{(message <json-request>)}}
@desc{Returns @code{json} symbol.}

