Repository navigation
5.0.10
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_sizekeyword 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.ErrorandJsonRpcErrorgive aUserWarningif 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.@methodgives aUserWarningfor a name that starts withrpc., 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.serverlogger, 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
-
@methodnow 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. -
Resulthad its two type arguments the wrong way round for oslash's
Either. It is nowEither[SuccessResult, ErrorResult]. Nothing changes at
run time. -
Success,ErrorandInvalidParamshave real signatures instead of
*args, **kwargs.Errorexpects anintcode and astrmessage. -
The
methodsargument accepts any mapping, and async methods type-check. -
oslash ships type hints but no
py.typedmarker, so mypy treatsResultas
Anyunless you tell it to read them. pyright reads them without help. For
mypy, add this topyproject.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
testextra now includes everything the tests need (pytest-asyncio
andhypothesiswere missing). Theexamplesextra is gone, because the
examples it was for are in the docs now, with their own requirements file. - The build uses
pyproject.tomlwith flit instead ofsetup.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_erroris nowto_error_dict.serialize_successis nowto_success_dict.to_serializable_oneis nowto_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 whensys.stderrwasNone. That's the case in a PyInstaller app
built with--noconsole(#269). It now logs requests through the logging
module, on thejsonrpcserver.serverlogger at INFO level, instead of
writing to stderr. Uselogging.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 invalidContent-Lengthgets 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 jsonrpcservergave aDeprecationWarningon Python 3.11 and 3.12,
which is an error when tests run with-W error. The request schema is now
loaded withpkgutil.get_data.- If a method returned something
json.dumpscan't handle, such as a
datetime,dispatchraisedTypeErrorinstead 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 asmax, 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_dispatchnow accepts plain (non-async) methods as well. Calling an
async method throughdispatchgives a clear message in the log, and no
"coroutine was never awaited" warning.- Under
python -O, a method that returned something other than aResult
broke the whole batch, because the check was anassertstatement. The
check now works with-Otoo.