Skip to content

5.0.10

Choose a tag to compare

@github-actions github-actions released this 06 Nov 00:29
· 46 commits to main since this release
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.