This is JSONRPC.info, produced by Macaulay2, version 1.25.11

JSONRPC -- JSONRPC 2.0 server
*****************************

Description
===========

This package provides a lightweight and flexible implementation of a JSON-RPC
2.0 (see https://jsonrpc.org ) server, providing an easy way to register and
handle remote procedure calls over JSON. It supports method registration, batch
processing, and error handling while ensuring compliance with the JSON-RPC
specification.  The package includes utilities for constructing valid JSON-RPC
requests and notifications, making it simple to integrate into existing
applications. Designed for reliability and ease of use, it offers built-in
logging and a clean, intuitive API for managing JSON-RPC methods.

+-----------------------------------------------------------------------------+
|i1 : server = new JSONRPCServer                                              |
|                                                                             |
|o1 = server                                                                  |
|                                                                             |
|o1 : JSONRPCServer                                                           |
+-----------------------------------------------------------------------------+
|i2 : registerMethod(server, "sum", plus)                                     |
+-----------------------------------------------------------------------------+
|i3 : setLogger(server, printerr)                                             |
+-----------------------------------------------------------------------------+
|i4 : handleRequest(server, makeRequest("sum", {2, 3}, 1))                    |
| -- received request: {"method": "sum", "id": 1, "jsonrpc": "2.0", "params": |
| -- calling method "sum" with params [2, 3]                                  |
| -- method "sum" returned: 5                                                 |
| -- sending response: {"result": 5, "jsonrpc": "2.0", "id": 1}               |
|                                                                             |
|o4 = {"result": 5, "jsonrpc": "2.0", "id": 1}                                |
|-----------------------------------------------------------------------------|
|[2, 3]}                                                                      |
+-----------------------------------------------------------------------------+

Author
======

  * Doug Torrance (see https://webwork.piedmont.edu/~dtorrance )
    <dtorrance@piedmont.edu>

Version
=======

This documentation describes version 0.1 of JSONRPC, released May 19, 2025.

Citation
========

If you have used this package in your research, please cite it as follows:

+----------------------------------------------------------------------------+
|@misc{JSONRPCSource,                                                        |
|  title = {{JSONRPC: JSON-RPC server. Version~0.1}},                        |
|  author = {Doug Torrance},                                                 |
|  howpublished = {A \emph{Macaulay2} package available at                   |
|    \url{https://github.com/Macaulay2/M2/tree/stable/M2/Macaulay2/packages}}|
|}                                                                           |
|                                                                            |
+----------------------------------------------------------------------------+

Exports
=======

  * Types
      * JSONRPCError -- class for JSON-RPC errors
      * JSONRPCServer -- JSONRPC server class
  * Functions and commands
      * handleRequest -- handle a JSON-RPC request
      * makeRequest -- construct a JSON-RPC request
      * registerMethod -- register a method for a
        JSON-RPC server
      * setLogger -- set up logging for a JSON-RPC server
  * Methods
      * "handleRequest(JSONRPCServer,String)" -- see handleRequest,
        -- handle a JSON-RPC request
      * "NewFromMethod(JSONRPCError,ZZ,String)" -- see JSONRPCError,
        -- class for JSON-RPC errors
      * "NewFromMethod(JSONRPCError,ZZ,String,Thing)" -- see
        JSONRPCError, -- class for JSON-RPC errors
      * "new JSONRPCServer" -- see JSONRPCServer, --
        JSONRPC server class
      * "makeRequest(List)" -- see makeRequest, -- construct
        a JSON-RPC request
      * "makeRequest(String)" -- see makeRequest, --
        construct a JSON-RPC request
      * "makeRequest(String,HashTable)" -- see makeRequest,
        -- construct a JSON-RPC request
      * "makeRequest(String,HashTable,String)" -- see makeRequest,
        -- construct a JSON-RPC request
      * "makeRequest(String,HashTable,ZZ)" -- see makeRequest,
        -- construct a JSON-RPC request
      * "makeRequest(String,List)" -- see makeRequest, --
        construct a JSON-RPC request
      * "makeRequest(String,List,String)" -- see makeRequest,
        -- construct a JSON-RPC request
      * "makeRequest(String,List,ZZ)" -- see makeRequest, --
        construct a JSON-RPC request
      * "makeRequest(String,String)" -- see makeRequest, --
        construct a JSON-RPC request
      * "makeRequest(String,ZZ)" -- see makeRequest, --
        construct a JSON-RPC request
      * methods(JSONRPCServer) -- list the
        methods registered to a JSON-RPC server
      * "registerMethod(JSONRPCServer,String,Function)" -- see
        registerMethod, -- register a method for a JSON-RPC
        server
      * "registerMethod(JSONRPCServer,String,List,Function)" -- see
        registerMethod, -- register a method for a JSON-RPC
        server
      * "setLogger(JSONRPCServer,Function)" -- see setLogger,
        -- set up logging for a JSON-RPC server

For the programmer
==================

The object JSONRPC, is a package (Macaulay2Doc),
defined in JSONRPC.m2.

-------------------------------------------------------------------------------

The source of this document is in JSONRPC.m2:229:0.

JSONRPCServer -- JSONRPC server class
*************************************

  * Usage:
        new JSONRPCServer

Description
===========

JSONRPCSever is the core class of the package, responsible for handling
JSON-RPC requests. It allows you to register methods,
process incoming requests, (including batches), and send
appropriate responses or error messages, all while following the JSON-RPC 2.0
specification (see https://www.jsonrpc.org/specification ).  The class also
includes basic logging functionality, to track incoming
requests and responses.

+-------------------------------+
|i1 : server = new JSONRPCServer|
|                               |
|o1 = server                    |
|                               |
|o1 : JSONRPCServer             |
+-------------------------------+

Methods that use a JSON-RPC server:
===================================

  * "handleRequest(JSONRPCServer,String)" -- see handleRequest,
    -- handle a JSON-RPC request
  * "new JSONRPCServer"
  * methods(JSONRPCServer) -- list the
    methods registered to a JSON-RPC server
  * "registerMethod(JSONRPCServer,String,Function)" -- see
    registerMethod, -- register a method for a JSON-RPC server
  * "registerMethod(JSONRPCServer,String,List,Function)" -- see
    registerMethod, -- register a method for a JSON-RPC server
  * "setLogger(JSONRPCServer,Function)" -- see setLogger, --
    set up logging for a JSON-RPC server

For the programmer
==================

The object JSONRPCServer, is a type (Macaulay2Doc),
with ancestor classes MutableHashTable (Macaulay2Doc),
< HashTable (Macaulay2Doc) <
Thing (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in JSONRPC.m2:256:0.

registerMethod -- register a method for a JSON-RPC server
*********************************************************

  * Usage:
        registerMethod(server, name, params, f)
  * Inputs:
      * server, a JSON-RPC server,
      * name, a string (Macaulay2Doc),
      * params, a list (Macaulay2Doc), optional;
      * f, a function (Macaulay2Doc),

Description
===========

This method registers a method with server.  The name parameter is the name of
the method that will be exposed in JSON-RPC requests, and f is the function
that will be called when the method is invoked.  The optional params argument
is a list of expected parameter names for the method. If provided, it helps
validate the parameters in incoming requests. The function should accept the
parameters passed in the request and return the result to be sent back in the
response.

+-----------------------------------------------------------------------------+
|i1 : server = new JSONRPCServer                                              |
|                                                                             |
|o1 = server                                                                  |
|                                                                             |
|o1 : JSONRPCServer                                                           |
+-----------------------------------------------------------------------------+
|i2 : registerMethod(server, "sum", plus)                                     |
+-----------------------------------------------------------------------------+
|i3 : registerMethod(server, "subtract", {"minuend", "subtrahend"},           |
|-----------------------------------------------------------------------------|
|difference)                                                                  |
+-----------------------------------------------------------------------------+
|i4 : handleRequest(server, makeRequest("sum", {1, 2, 4}, 1))                 |
|                                                                             |
|o4 = {"result": 7, "jsonrpc": "2.0", "id": 1}                                |
+-----------------------------------------------------------------------------+
|i5 : handleRequest(server, makeRequest("subtract", {42, 23}, 2))             |
|                                                                             |
|o5 = {"result": 19, "jsonrpc": "2.0", "id": 2}                               |
+-----------------------------------------------------------------------------+

To see a list of registered methods for a given server, run
methods(JSONRPCServer).

+-----------------------------------------+
|i6 : methods server                      |
|                                         |
|o6 = {0 => (subtract,minuend,subtrahend)}|
|     {1 => 1 : (sum)                    }|
|                                         |
|o6 : NumberedVerticalList                |
+-----------------------------------------+

If you would like to deregister a method, then you may use
remove(HashTable,Thing) (Macaulay2Doc).

+-----------------------------------------+
|i7 : remove(server, "sum")               |
|                                         |
|o7 = 1 : (sum)                           |
|                                         |
|o7 : JSONRPCMethod                       |
+-----------------------------------------+
|i8 : methods server                      |
|                                         |
|o8 = {0 => (subtract,minuend,subtrahend)}|
|                                         |
|o8 : NumberedVerticalList                |
+-----------------------------------------+

Ways to use registerMethod:
===========================

  * "registerMethod(JSONRPCServer,String,Function)"
  * "registerMethod(JSONRPCServer,String,List,Function)"

For the programmer
==================

The object registerMethod, is a method function (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in JSONRPC.m2:301:0.

methods(JSONRPCServer) -- list the methods registered to a JSON-RPC server
**************************************************************************

  * Function: methods (Macaulay2Doc),
  * Usage:
        methods server
  * Inputs:
      * server, a JSON-RPC server,
  * Outputs:
      * a numbered vertical list (Macaulay2Doc),
        the methods registered to server;

Description
===========

This method behaves much like the usual methods (Macaulay2Doc),
method.  It lists each of the methods that have been registered to the given
server.

+--------------------------------------------------------------------+
|i1 : server = new JSONRPCServer                                     |
|                                                                    |
|o1 = server                                                         |
|                                                                    |
|o1 : JSONRPCServer                                                  |
+--------------------------------------------------------------------+
|i2 : registerMethod(server, "add", (x, y) -> x + y)                 |
+--------------------------------------------------------------------+
|i3 : registerMethod(server, "subtract", {"x", "y"}, (x, y) -> x - y)|
+--------------------------------------------------------------------+
|i4 : methods server                                                 |
|                                                                    |
|o4 = {0 => (subtract,x,y)}                                          |
|     {1 => 1 : (add)     }                                          |
|                                                                    |
|o4 : NumberedVerticalList                                           |
+--------------------------------------------------------------------+

After running methods, both locate(ZZ) (Macaulay2Doc), and
code(ZZ) (Macaulay2Doc), work as expected.

+----------------------------+
|i5 : locate 0               |
|                            |
|o5 = currentString:3:47-3:62|
|                            |
|o5 : FilePosition           |
+----------------------------+

Ways to use this method:
========================

  * methods(JSONRPCServer) -- list the
    methods registered to a JSON-RPC server
-------------------------------------------------------------------------------

The source of this document is in JSONRPC.m2:330:0.

handleRequest -- handle a JSON-RPC request
******************************************

  * Usage:
        handleRequest(server, str)
  * Inputs:
      * server, a JSON-RPC server,
      * str, a string (Macaulay2Doc), a JSON-RPC 2.0 request
        object;
  * Outputs:
      * a string (Macaulay2Doc), or null (Macaulay2Doc),
        the response to the request or null if the request
        was a notification

Description
===========

This method processes an incoming JSON-RPC request. It takes a JSON-encoded
string representing a request (or batch of requests) and returns the
corresponding JSON-RPC response. It handles method invocation, error handling,
and batching automatically.  Note that makeRequest, is
useful for constructing requests.

+-----------------------------------------------------------------------------+
|i1 : server = new JSONRPCServer                                              |
|                                                                             |
|o1 = server                                                                  |
|                                                                             |
|o1 : JSONRPCServer                                                           |
+-----------------------------------------------------------------------------+
|i2 : registerMethod(server, "sum", plus)                                     |
+-----------------------------------------------------------------------------+
|i3 : handleRequest(server, makeRequest("sum", {2, 3}, 1))                    |
|                                                                             |
|o3 = {"result": 5, "jsonrpc": "2.0", "id": 1}                                |
+-----------------------------------------------------------------------------+
|i4 : handleRequest(server, makeRequest({("sum", {4, 5}, 2), ("sum", {6, 7},  |
|                                                                             |
|o4 = [{"result": 9, "jsonrpc": "2.0", "id": 2}, {"result": 13, "jsonrpc":    |
|     "2.0", "id": 3}]                                                        |
|-----------------------------------------------------------------------------|
|3)}))                                                                        |
+-----------------------------------------------------------------------------+

If you need to do any error handling in a method, then the JSONRPCError,
class may be useful.

Ways to use handleRequest:
==========================

  * "handleRequest(JSONRPCServer,String)"

For the programmer
==================

The object handleRequest, is a method function (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in JSONRPC.m2:363:0.

JSONRPCError -- class for JSON-RPC errors
*****************************************

  * Usage:
        JSONRPCError(errCode, msg, data)
        JSONRPCError(errCode, msg)
  * Inputs:
      * errCode, an integer (Macaulay2Doc),
      * msg, a string (Macaulay2Doc),
      * data, a thing (Macaulay2Doc),

Description
===========

This class is used to represent errors that occur during the processing of
JSON-RPC requests. It provides a structured way to format error responses,
including an error code, message, and optional additional data. This class
ensures that errors are properly formatted according to the JSON-RPC 2.0
specification and can be easily included in responses to clients.

Consider the following example.  The default response doesn't include a very
useful error message.

+------------------------------------------------------------------------+
|i1 : server = new JSONRPCServer                                         |
|                                                                        |
|o1 = server                                                             |
|                                                                        |
|o1 : JSONRPCServer                                                      |
+------------------------------------------------------------------------+
|i2 : registerMethod(server, "divide", (x, y) -> x/y)                    |
+------------------------------------------------------------------------+
|i3 : handleRequest(server, makeRequest("divide", {1, 0}, 1))            |
|                                                                        |
|o3 = {"error": {"code": -32602, "message": "Invalid params"}, "jsonrpc":|
|     "2.0", "id": 1}                                                    |
+------------------------------------------------------------------------+

Let's replace it with a more useful one.

+--------------------------------------------------------------------------+
|i4 : registerMethod(server, "divide", (x, y) -> (                         |
|             if zero y then JSONRPCError(-32001, "division by zero")      |
|             else x/y))                                                   |
+--------------------------------------------------------------------------+
|i5 : handleRequest(server, makeRequest("divide", {1, 0}, 1))              |
|                                                                          |
|o5 = {"error": {"code": -32001, "message": "division by zero"}, "jsonrpc":|
|     "2.0", "id": 1}                                                      |
+--------------------------------------------------------------------------+
|i6 : handleRequest(server, makeRequest("divide", {22, 7}, 1))             |
|                                                                          |
|o6 = {"result": 3.142857142857143, "jsonrpc": "2.0", "id": 1}             |
+--------------------------------------------------------------------------+

Note that the error codes -32000 to -32099 are reserved for use by JSON-RPC
servers, so errCode should lie in this interval (although this isn't checked).

Methods that use a JSON-RPC error:
==================================

  * "NewFromMethod(JSONRPCError,ZZ,String)"
  * "NewFromMethod(JSONRPCError,ZZ,String,Thing)"

For the programmer
==================

The object JSONRPCError, is a self initializing type (Macaulay2Doc),
with ancestor classes HashTable (Macaulay2Doc),
< Thing (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in JSONRPC.m2:406:0.

setLogger -- set up logging for a JSON-RPC server
*************************************************

  * Usage:
        setLogger(server, f)
  * Inputs:
      * server, a JSON-RPC server,
      * f, a function (Macaulay2Doc),

Description
===========

This method sets a custom logging function for the server. The provided logger
function will be used to log relevant server activities, such as incoming
requests and responses. This allows for flexible logging and monitoring,
enabling users to integrate with existing logging systems or implement custom
logging behavior.  The function f should accept a single string.

Let's set it up so that our server logs both to stderr (Macaulay2Doc),
and to a file.

+-----------------------------------------------------------------------------+
|i1 : server = new JSONRPCServer                                              |
|                                                                             |
|o1 = server                                                                  |
|                                                                             |
|o1 : JSONRPCServer                                                           |
+-----------------------------------------------------------------------------+
|i2 : registerMethod(server, "sum", plus)                                     |
+-----------------------------------------------------------------------------+
|i3 : logfile = temporaryFileName();                                          |
+-----------------------------------------------------------------------------+
|i4 : setLogger(server, x -> (printerr x; logfile << x << endl;));            |
+-----------------------------------------------------------------------------+
|i5 : handleRequest(server, makeRequest("sum", {2, 3}, 1))                    |
| -- received request: {"method": "sum", "id": 1, "jsonrpc": "2.0", "params": |
| -- calling method "sum" with params [2, 3]                                  |
| -- method "sum" returned: 5                                                 |
| -- sending response: {"result": 5, "jsonrpc": "2.0", "id": 1}               |
|                                                                             |
|o5 = {"result": 5, "jsonrpc": "2.0", "id": 1}                                |
|-----------------------------------------------------------------------------|
|[2, 3]}                                                                      |
+-----------------------------------------------------------------------------+
|i6 : handleRequest(server, makeRequest("sum", {4, 5}, 2))                    |
| -- received request: {"method": "sum", "id": 2, "jsonrpc": "2.0", "params": |
| -- calling method "sum" with params [4, 5]                                  |
| -- method "sum" returned: 9                                                 |
| -- sending response: {"result": 9, "jsonrpc": "2.0", "id": 2}               |
|                                                                             |
|o6 = {"result": 9, "jsonrpc": "2.0", "id": 2}                                |
|-----------------------------------------------------------------------------|
|[4, 5]}                                                                      |
+-----------------------------------------------------------------------------+
|i7 : logfile << close;                                                       |
+-----------------------------------------------------------------------------+
|i8 : get logfile                                                             |
|                                                                             |
|o8 = received request: {"method": "sum", "id": 1, "jsonrpc": "2.0", "params":|
|     calling method "sum" with params [2, 3]                                 |
|     method "sum" returned: 5                                                |
|     sending response: {"result": 5, "jsonrpc": "2.0", "id": 1}              |
|     received request: {"method": "sum", "id": 2, "jsonrpc": "2.0", "params":|
|     calling method "sum" with params [4, 5]                                 |
|     method "sum" returned: 9                                                |
|     sending response: {"result": 9, "jsonrpc": "2.0", "id": 2}              |
|-----------------------------------------------------------------------------|
|[2, 3]}                                                                      |
|                                                                             |
|                                                                             |
|                                                                             |
|[4, 5]}                                                                      |
+-----------------------------------------------------------------------------+

Ways to use setLogger:
======================

  * "setLogger(JSONRPCServer,Function)"

For the programmer
==================

The object setLogger, is a method function (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in JSONRPC.m2:484:0.

makeRequest -- construct a JSON-RPC request
*******************************************

  * Usage:
        makeRequest(m, params, ID)
  * Inputs:
      * m, a string (Macaulay2Doc), method name;
      * params, a hash table (Macaulay2Doc), or a list (Macaulay2Doc),
        method parameters (optional);
      * ID, a string (Macaulay2Doc), or an integer (Macaulay2Doc),
        id (if omitted, then the request is a notification);
  * Outputs:
      * a string (Macaulay2Doc), JSON-RPC request object;

Description
===========

This method constructs a JSON-RPC request. The m parameter specifies the name
of the method being called, while params contains the arguments for the method
(if any). The optional ID parameter is used to correlate requests and
responses. This method generates a JSON-encoded string representing the
request, ready to be sent to the server. If no ID is provided, then the request
is a notification and the server will return nothing.

+-----------------------------------------------------------------------------+
|i1 : makeRequest("foo", hashTable{"x" => 2, "y" => 3}, 1)                    |
|                                                                             |
|o1 = {"method": "foo", "id": 1, "jsonrpc": "2.0", "params": {"x": 2, "y": 3}}|
+-----------------------------------------------------------------------------+
|i2 : makeRequest("baz", {4, 5, 6}, 2)                                        |
|                                                                             |
|o2 = {"method": "baz", "id": 2, "jsonrpc": "2.0", "params": [4, 5, 6]}       |
+-----------------------------------------------------------------------------+

When a list is given, its elements are expected to be sequences that can be
passed to makeRequest.  The result is an array containing a
batch request.

+--------------------------------------------------------------------------+
|i3 : makeRequest({                                                        |
|             ("foo", hashTable{"x" => 7, "y" => 8}, 3),                   |
|             ("bar", {9, 10, 11}, 4)})                                    |
|                                                                          |
|o3 = [{"method": "foo", "id": 3, "jsonrpc": "2.0", "params": {"x": 7, "y":|
|     8}}, {"method": "bar", "id": 4, "jsonrpc": "2.0", "params": [9, 10,  |
|     11]}]                                                                |
+--------------------------------------------------------------------------+

Ways to use makeRequest:
========================

  * "makeRequest(List)"
  * "makeRequest(String)"
  * "makeRequest(String,HashTable)"
  * "makeRequest(String,HashTable,String)"
  * "makeRequest(String,HashTable,ZZ)"
  * "makeRequest(String,List)"
  * "makeRequest(String,List,String)"
  * "makeRequest(String,List,ZZ)"
  * "makeRequest(String,String)"
  * "makeRequest(String,ZZ)"

For the programmer
==================

The object makeRequest, is a method function (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in JSONRPC.m2:451:0.