Skip to content

Releases

6.0.0rc1

6.0.0rc1 Pre-release
Pre-release

Choose a tag to compare

@github-actions github-actions released this 06 Nov 02:57
4e7da80

The first release candidate of 6.0. pip install --pre jsonrpcserver installs
it. pip install jsonrpcserver keeps installing 5.x until 6.0.0.
Migration
lists what changes, and #320
tracks the release. 5.x gets fixes on the release/5.x branch.

Added

  • max_concurrency on async_dispatch and the other async dispatch functions:
    the most requests of a batch that run at once. The default, None, runs them
    all at once, as before.

Changed

  • jsonrpcserver no longer uses oslash. Success returns a SuccessResult,
    and Error and InvalidParams return an ErrorResult. Both are frozen
    dataclasses, and Result is SuccessResult | ErrorResult. Code that only
    returns Success(...) or Error(...) from methods and calls dispatch
    keeps working.

  • dispatch_to_response gives SuccessResponse and ErrorResponse objects,
    frozen dataclasses with the response's fields. 5.x wrapped them in oslash's
    Right and Left, read through _value and _error. Check
    isinstance(response, ErrorResponse) instead.

  • Removed InvalidResultError, validate_result and log_invalid_result from
    jsonrpcserver.dispatcher. Without the oslash wrappers there's no invalid
    Result: a method's return value is its result.

  • The default validator checks the JSON-RPC 2.0 rules itself instead of using
    jsonschema. It accepts and rejects the same requests, which a test checks on
    500 generated requests and a list of edge cases. Dispatching a small method
    takes about 9.6 microseconds instead of 43 (Python 3.13). Its error is
    jsonrpcserver.validator.InvalidRequestError, with a message that says what's
    wrong. The client still gets the same -32600 response.

  • Batches are limited to 100 requests by default (max_batch_size). A bigger
    batch gets one -32600 error, and none of it runs. Pass max_batch_size=None
    for no limit, as in 5.x.

  • The default deserializer rejects NaN, Infinity, -Infinity and numbers
    too big for a float, with a -32700 Parse error. They aren't valid JSON.
    deserializer=json.loads accepts them, as in 5.x. dispatch_to_response
    now uses the same default as the other dispatch functions.

  • Error and JsonRpcError raise TypeError for a code that isn't an int or
    a message that isn't a str. @method raises ValueError for a name starting
    with rpc.. 5.0.10 warned about both.

  • serve() listens on localhost unless you pass a host. 5.x listened on every
    network interface by default. serve("", port) does that now.

  • The sync and async dispatch functions take the same options with the same
    defaults. A test keeps them that way.

Removed

  • serialize_error, serialize_success and to_serializable_one in
    jsonrpcserver.response (and to_serializable_one in jsonrpcserver.main),
    deprecated in 5.0.10. Use to_error_dict, to_success_dict and to_dict.
  • ResponseType. Use Response.
  • The jsonschema dependency, and jsonrpcserver/request-schema.json. 6.0 has no
    runtime dependencies.
  • The oslash dependency, and with it the mypy setting typing.md asked for.
  • Python 3.8, 3.9 and 3.10, which have reached end of life. 6.0 needs Python
    3.11 or later. Older Pythons keep installing 5.x.

5.2.0

Choose a tag to compare

@github-actions github-actions released this 06 Nov 02:38
e16a63c

Warnings about what 6.0 changes, so an upgrade doesn't surprise you. Nothing
else changes. Each is a FutureWarning, which Python shows by default.

  • serve() without a host warns. From 6.0 it listens on localhost only.
    serve("", port) keeps every network interface, quietly.
  • A request with NaN, Infinity, -Infinity or a number too big for a float
    warns. 6.0 rejects them with a Parse error. deserializer=json.loads accepts
    them quietly. dispatch_to_response now uses the same default deserializer
    as the other dispatch functions.
  • A batch of more than 100 requests without max_batch_size warns. 6.0 limits
    batches to 100 by default. Passing max_batch_size turns the warning off.

The 6.0 plan
lists everything else that changes, such as results and responses without
oslash.

5.1.0

Choose a tag to compare

@github-actions github-actions released this 06 Nov 01:27
dddf0e3

Added

  • A method can return a plain value. return "pong" sends the same response as
    return Success("pong"), as in 4.x (#285). Before, a plain value gave the
    client an Internal error. Success and Error work as before.

Changed

  • A method that returns an oslash Left or Right not made by Success or
    Error, or a bare SuccessResult or ErrorResult, still gets an Internal
    error. Its log line and InvalidResultError message now say "Return a value,
    Success(value) or Error(code, message)", and the log line links the Methods
    page.

5.0.10

Choose a tag to compare

@github-actions github-actions released this 06 Nov 00:29
c42c6bf

The first release since the project moved to
bensynapse/jsonrpcserver. It
fixes a security problem, so please upgrade. Code that works with 5.0.9 keeps
working, apart from the security fix and the "Behaviour changes" below. The
migration guide
lists what you might notice.

Security

When a method raised an exception it didn't catch, the error response sent to
the client included the exception message in error.data. Exception messages
from database drivers, HTTP clients and the like often contain connection
strings, passwords, hostnames, file paths or SQL. Anyone who could call a method
could read them.

The response now leaves data out:

{"jsonrpc": "2.0", "error": {"code": -32603, "message": "Internal error"}, "id": 1}

The same applies to the -32000 "Server error" response for errors inside
jsonrpcserver itself. The exception and its traceback are still logged, on the
jsonrpcserver logger, so you can find them in your server logs. The
logging section
of the docs lists its child loggers.

To get the old behaviour back while developing, pass debug=True to
dispatch, async_dispatch or any of the other dispatch functions. Don't turn
it on in production.

Errors you return on purpose, with Error, InvalidParams or by raising
JsonRpcError, are not affected. Their data is sent as before.

New

  • max_batch_size keyword on all the dispatch functions, sync and async. A
    batch with more requests than this gets a single -32600 "Invalid request"
    response, and none of its requests are run. The default is no limit, as
    before. Each request in a batch costs schema validation time. A 5 MB batch
    of 100,000 pings took about 4 seconds of CPU, so a public server should set
    a limit. 100 is a sensible starting point.
  • Error and JsonRpcError give a UserWarning if the code isn't an integer
    or the message isn't a string. The spec requires an integer code, and some
    clients can't parse anything else. The response is still sent as before.
  • @method gives a UserWarning for a name that starts with rpc., because
    the spec reserves those names.
  • A method that returns a plain value instead of Success(value) is a common
    mistake when upgrading from 4.x. It's now logged with a message that says
    what to change, instead of a traceback. The client still gets an Internal
    error.
  • serve() says where it's listening when it starts, including a note when it
    listens on every network interface (the default). It logs the line on the
    jsonrpcserver.server logger, and writes it to stderr if logging isn't
    configured.
  • Every public function and class has a full docstring, which the new API
    reference on the docs site is built from.

Behaviour changes

Batches that mix valid and invalid requests are now handled per request, as
the JSON-RPC spec says (#291). [1, {"jsonrpc": "2.0", "method": "ping", "id": 1}] used to get a single "Invalid request" response. Now 1 gets its own
error and ping runs.

As part of that change, a custom validator is now called once for each
request in a batch, with just that request. Before, it was called once with
the whole list. Some validators enforced a rule about the batch as a whole,
such as a size limit or refusing batches. Those no longer see the list, so the
rule silently stops working. Use max_batch_size for a size limit. Validators
that check one request at a time, including the default and lambda _: None,
are not affected.

dispatch no longer writes NaN, Infinity or -Infinity into a response.
They aren't valid JSON, and strict parsers (JavaScript's JSON.parse, Go,
Rust) reject the whole response. A result containing one now gives an Internal
error instead. If you depend on the old output, pass serializer=json.dumps.

Typing

  • @method now returns the decorated function unchanged as far as type
    checkers are concerned. Before, mypy and pyright saw every decorated
    function as (*Any, **Any) -> Any, so they couldn't check calls to your own
    methods.

  • Result had its two type arguments the wrong way round for oslash's
    Either. It is now Either[SuccessResult, ErrorResult]. Nothing changes at
    run time.

  • Success, Error and InvalidParams have real signatures instead of
    *args, **kwargs. Error expects an int code and a str message.

  • The methods argument accepts any mapping, and async methods type-check.

  • oslash ships type hints but no py.typed marker, so mypy treats Result as
    Any unless you tell it to read them. pyright reads them without help. For
    mypy, add this to pyproject.toml:

    [[tool.mypy.overrides]]
    module = ["oslash", "oslash.*"]
    follow_untyped_imports = true

Documentation

The documentation now lives in this repository, under docs/, and is
published at https://bensynapse.github.io/jsonrpcserver/. The framework
examples moved there from the wiki. CI starts each example server and sends
it requests, and runs every code example in the docs. The websockets example
uses the current websockets.asyncio API (#287). A new Security page covers
the settings to check before exposing a server.

The site has an API reference built from the docstrings and a migration
guide from 4.x. New pages cover errors and logging, notifications and
batches, context, validation, typing, testing and threads. Each framework has its own
page, and every example sets max_batch_size and a request size limit. The
examples listen on localhost:8000, where the jsonrpcclient examples
connect.

Packaging

  • A wheel is published as well as the source distribution, so installs no
    longer have to build the package.
  • The package metadata says it needs Python 3.8 or later, and lists 3.8 to
    3.14. CI tests all of those, plus free-threaded 3.14.
  • The project links on PyPI point to this repository and the new docs. The
    old website domains belong to someone else now. Please don't follow links
    to them from older releases.
  • jsonrpcserver.__version__ gives the version.
  • The test extra now includes everything the tests need (pytest-asyncio
    and hypothesis were missing). The examples extra is gone, because the
    examples it was for are in the docs now, with their own requirements file.
  • The build uses pyproject.toml with flit instead of setup.py. The
    dependencies are the same as in 5.0.9.

Deprecations

Three functions in jsonrpcserver.response have new names. The old names still
work in 5.x but give a DeprecationWarning, and will be removed in 6.0.

  • serialize_error is now to_error_dict.
  • serialize_success is now to_success_dict.
  • to_serializable_one is now to_dict. It's also still importable from
    jsonrpcserver.main.

Fixes

  • @method(name="") now registers the empty name. It used to ignore that
    name and register the function's name instead.
  • The development server, serve(), dropped every connection without a
    response when sys.stderr was None. That's the case in a PyInstaller app
    built with --noconsole (#269). It now logs requests through the logging
    module, on the jsonrpcserver.server logger at INFO level, instead of
    writing to stderr. Use logging.basicConfig(level=logging.INFO) to see them.
  • serve() also answers a body that isn't valid UTF-8 with a -32700 "Parse
    error". A missing or invalid Content-Length gets 411 or 400. Before, all
    of these closed the connection with no response. Notifications get 204 No
    Content instead of 200 with an empty body. It handles requests in threads,
    and closes its socket when it stops.
  • import jsonrpcserver gave a DeprecationWarning on Python 3.11 and 3.12,
    which is an error when tests run with -W error. The request schema is now
    loaded with pkgutil.get_data.
  • If a method returned something json.dumps can't handle, such as a
    datetime, dispatch raised TypeError instead of responding. In a batch,
    the other responses were lost too. That response is now an Internal error,
    and the rest of the batch is sent as usual.
  • A failure outside the method itself used to turn a whole batch into a single
    "Server error" with a null id. Now only the member that failed gets the
    error. One way to hit it was a builtin such as max, whose signature can't
    be inspected. Another was a batch member that isn't an object, with
    validation turned off.
  • Methods whose signature can't be inspected are now called, instead of
    failing before the call.
  • async_dispatch now accepts plain (non-async) methods as well. Calling an
    async method through dispatch gives a clear message in the log, and no
    "coroutine was never awaited" warning.
  • Under python -O, a method that returned something other than a Result
    broke the whole batch, because the check was an assert statement. The
    check now works with -O too.