From 6673b7a726be0fa364cf95f92a1d83e396fd967d Mon Sep 17 00:00:00 2001 From: bensynapse <118375461+bensynapse@users.noreply.github.com> Date: Tue, 6 Oct 2026 05:59:55 +0300 Subject: [PATCH 1/2] Rewrite the docs and README, with an API reference and tested examples The docs site now has the same layout as jsonrpcclient's, in pink. It adds one page per framework, an API reference built from the docstrings, and a migration guide. Every page is honest about the release that people actually get. A banner says the docs describe 5.0.10 and PyPI has 5.0.9. Security opens with a tested wrapper that stops 5.0.9 from sending exception messages to clients. Each 5.0.10 feature is marked "New in" or "Changed in". The examples follow the Security page. Each one sets max_batch_size and a body size limit, and listens on localhost:8000, where the jsonrpcclient examples connect. CI starts each one and sends it real requests. That includes a batch over the limit and a body over the limit. The http.server example now handles a missing Content-Length and bytes that aren't UTF-8. The quickstart starts a server, calls it with curl and with jsonrpcclient, and both run in CI. New pages cover notifications and batches, errors and logging (with every logger), context, validation, typing, testing and threads. A new test calls dispatch from many threads at once, and runs on free-threaded 3.14t. The site gets per-page titles and descriptions, a social card, a neutral favicon, a visible h1 and a 404 page. It also has the client's copy button fix, accessibility fixes and an HTTPS redirect. The pink is darkened to #c2185b so links and the header pass WCAG AA. A new CI job opens every page in Chromium, light and dark, at desktop and phone widths. It fails on any serious axe-core finding, a broken internal link or anchor, or a page that scrolls sideways. The README follows the agreed layout and renders cleanly on PyPI. The release workflow refuses to publish while the docs still call the version unreleased. RELEASING.md lists the clean-up steps and the advisory step. --- .github/ISSUE_TEMPLATE/bug_report.yml | 3 + .github/ISSUE_TEMPLATE/config.yml | 5 +- .github/scripts/check_site.py | 194 +++++++++++++++++++++ .github/workflows/ci.yml | 33 +++- .github/workflows/release.yml | 18 +- CHANGELOG.md | 38 ++-- CONTRIBUTING.md | 17 +- README.md | 109 +++++++++--- RELEASING.md | 32 +++- SECURITY.md | 7 +- docs/assets/a11y.js | 27 +++ docs/assets/apple-touch-icon.png | Bin 0 -> 7388 bytes docs/assets/copy-without-prompts.js | 19 ++ docs/assets/extra.css | 191 ++++++++++---------- docs/assets/favicon.png | Bin 0 -> 2408 bytes docs/assets/social-card.png | Bin 0 -> 67107 bytes docs/async.md | 57 ++++-- docs/batches.md | 135 +++++++++++++++ docs/changelog.md | 5 + docs/context.md | 163 ++++++++++++++++++ docs/contributing.md | 5 + docs/dispatch.md | 148 +++++++++++----- docs/errors.md | 181 +++++++++++++++++++ docs/examples.md | 158 ++++++----------- docs/examples/aiohttp_server.py | 8 +- docs/examples/check_examples.py | 145 +++++++++++++--- docs/examples/django_server.py | 9 +- docs/examples/fastapi_server.py | 14 +- docs/examples/flask_server.py | 7 +- docs/examples/http_server.py | 27 ++- docs/examples/{serve.py => quickstart.py} | 2 +- docs/examples/sanic_server.py | 7 +- docs/examples/socketio_server.py | 8 +- docs/examples/tornado_server.py | 7 +- docs/examples/websockets_server.py | 6 +- docs/examples/werkzeug_server.py | 14 +- docs/examples/zeromq_async_server.py | 7 +- docs/examples/zeromq_server.py | 8 +- docs/faq.md | 121 ++++++++++--- docs/frameworks/aiohttp.md | 38 ++++ docs/frameworks/django.md | 48 ++++++ docs/frameworks/fastapi.md | 44 +++++ docs/frameworks/flask.md | 41 +++++ docs/frameworks/http-server.md | 70 ++++++++ docs/frameworks/sanic.md | 40 +++++ docs/frameworks/socketio.md | 28 +++ docs/frameworks/tornado.md | 37 ++++ docs/frameworks/websockets.md | 38 ++++ docs/frameworks/werkzeug.md | 43 +++++ docs/frameworks/zeromq.md | 43 +++++ docs/index.md | 115 +++++++++---- docs/license.md | 12 ++ docs/methods.md | 78 ++++++--- docs/migration.md | 167 ++++++++++++++++++ docs/reference.md | 116 +++++++++++++ docs/roadmap.md | 25 ++- docs/security-policy.md | 5 + docs/security.md | 177 +++++++++++++------ docs/testing.md | 119 +++++++++++++ docs/threads.md | 63 +++++++ docs/typing.md | 76 ++++++++ docs/validation.md | 145 ++++++++++++++++ mkdocs.yml | 108 ++++++++++-- overrides/404.html | 22 +++ overrides/main.html | 49 ++++++ pyproject.toml | 15 +- requirements/docs.txt | 2 + requirements/examples.txt | 7 + requirements/site.txt | 2 + tests/doc_examples.py | 201 +++++++++++++++++----- tests/test_docs.py | 121 ++++++++++++- tests/test_threading.py | 92 ++++++++++ 72 files changed, 3566 insertions(+), 556 deletions(-) create mode 100644 .github/scripts/check_site.py create mode 100644 docs/assets/a11y.js create mode 100644 docs/assets/apple-touch-icon.png create mode 100644 docs/assets/copy-without-prompts.js create mode 100644 docs/assets/favicon.png create mode 100644 docs/assets/social-card.png create mode 100644 docs/batches.md create mode 100644 docs/changelog.md create mode 100644 docs/context.md create mode 100644 docs/contributing.md create mode 100644 docs/errors.md rename docs/examples/{serve.py => quickstart.py} (83%) create mode 100644 docs/frameworks/aiohttp.md create mode 100644 docs/frameworks/django.md create mode 100644 docs/frameworks/fastapi.md create mode 100644 docs/frameworks/flask.md create mode 100644 docs/frameworks/http-server.md create mode 100644 docs/frameworks/sanic.md create mode 100644 docs/frameworks/socketio.md create mode 100644 docs/frameworks/tornado.md create mode 100644 docs/frameworks/websockets.md create mode 100644 docs/frameworks/werkzeug.md create mode 100644 docs/frameworks/zeromq.md create mode 100644 docs/license.md create mode 100644 docs/migration.md create mode 100644 docs/reference.md create mode 100644 docs/security-policy.md create mode 100644 docs/testing.md create mode 100644 docs/threads.md create mode 100644 docs/typing.md create mode 100644 docs/validation.md create mode 100644 overrides/404.html create mode 100644 overrides/main.html create mode 100644 requirements/site.txt create mode 100644 tests/test_threading.py diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml index b9df452..58b7fe8 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.yml +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -13,6 +13,9 @@ body: id: version attributes: label: jsonrpcserver version + description: >- + Run `pip show jsonrpcserver` to find it. From 5.0.10 you can also + print `jsonrpcserver.__version__`. placeholder: "5.0.9" validations: required: true diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml index 719b40b..0484ccf 100644 --- a/.github/ISSUE_TEMPLATE/config.yml +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -1,8 +1,11 @@ blank_issues_enabled: true contact_links: + - name: Ask a question + url: https://github.com/bensynapse/jsonrpcserver/discussions/categories/q-a + about: Questions about using jsonrpcserver are answered in Discussions. - name: Report a security problem url: https://github.com/bensynapse/jsonrpcserver/security/advisories/new about: Please report security problems privately, not in a public issue. - name: Documentation url: https://bensynapse.github.io/jsonrpcserver/ - about: Usage and examples. + about: Guides, framework examples, the API reference and the FAQ. diff --git a/.github/scripts/check_site.py b/.github/scripts/check_site.py new file mode 100644 index 0000000..dfdd15d --- /dev/null +++ b/.github/scripts/check_site.py @@ -0,0 +1,194 @@ +"""Check the built docs site in a real browser. + +Usage: python .github/scripts/check_site.py SITE_DIR AXE_JS + +Serves SITE_DIR at http://localhost:8765/jsonrpcserver/, the same path as on +GitHub Pages, and opens every page in the sitemap, plus the 404 page, in light +and dark mode at desktop and phone widths. It fails if: + +- axe-core finds a serious or critical accessibility problem, +- a page scrolls sideways, has a JavaScript error, or has no visible h1, + description or canonical link, +- a link to another page of the site, or to an anchor on it, is broken. + +Needs playwright (pip install playwright, then playwright install chromium). +""" + +import functools +import re +import sys +import threading +import urllib.error +import urllib.request +from http.server import SimpleHTTPRequestHandler, ThreadingHTTPServer +from pathlib import Path +from typing import Any, Dict, List, Set, Tuple +from urllib.parse import urldefrag + +from playwright.sync_api import Page, sync_playwright + +PORT = 8765 +BASE = f"http://localhost:{PORT}/jsonrpcserver/" +LIVE = "https://bensynapse.github.io/jsonrpcserver/" +VIEWPORTS = {"desktop": (1280, 900), "phone": (375, 812)} + + +class Handler(SimpleHTTPRequestHandler): + """Serve the site under /jsonrpcserver/, with 404.html for missing pages.""" + + def translate_path(self, path: str) -> str: + path = path.split("?", 1)[0].split("#", 1)[0] + if not path.startswith("/jsonrpcserver/"): + return "" + return super().translate_path(path[len("/jsonrpcserver") :]) + + def send_error(self, code: int, message: Any = None, explain: Any = None) -> None: + if code != 404: + super().send_error(code, message, explain) + return + body = (Path(self.directory) / "404.html").read_bytes() + self.send_response(404) + self.send_header("Content-Type", "text/html") + self.send_header("Content-Length", str(len(body))) + self.end_headers() + self.wfile.write(body) + + def log_message(self, format: str, *args: Any) -> None: + pass + + +class Server(ThreadingHTTPServer): + def handle_error(self, request: Any, client_address: Any) -> None: + # The browser often drops a connection it no longer needs. + if not isinstance(sys.exc_info()[1], ConnectionError): + super().handle_error(request, client_address) + + +def record(errors: List[str], exc: Exception) -> None: + errors.append(str(exc)) + + +def page_info(page: Page) -> Dict[str, Any]: + return page.evaluate( + """() => { + const q = (s) => document.querySelector(s); + const h1 = [...document.querySelectorAll(".md-content h1")] + .filter((h) => h.offsetParent !== null); + const doc = document.documentElement; + return { + h1: h1.length, + description: (q('meta[name="description"]') || {}).content || "", + canonical: (q('link[rel="canonical"]') || {}).href || "", + overflow: doc.scrollWidth > doc.clientWidth, + links: [...document.querySelectorAll("a[href]")].map((a) => a.href), + ids: [...document.querySelectorAll("[id]")].map((e) => e.id), + }; + }""" + ) + + +def axe_problems(page: Page, axe: str) -> List[str]: + page.add_script_tag(content=axe) + violations: List[Dict[str, Any]] = page.evaluate( + """async () => { + const result = await axe.run(document, { + runOnly: ["wcag2a", "wcag2aa", "wcag21a", "wcag21aa", "best-practice"], + }); + return result.violations.map((v) => ({ + id: v.id, impact: v.impact, nodes: v.nodes.map((n) => n.target.join(" ")), + })); + }""" + ) + return [ + f"{v['id']} ({v['impact']}): {', '.join(v['nodes'][:3])}" + for v in violations + if v["impact"] in ("serious", "critical") + ] + + +def main(site: Path, axe: str) -> int: + handler = functools.partial(Handler, directory=str(site)) + server = Server(("localhost", PORT), handler) + threading.Thread(target=server.serve_forever, daemon=True).start() + sitemap = (site / "sitemap.xml").read_text() + urls = re.findall(r"(.*?)", sitemap) + pages = [url.replace(LIVE, BASE) for url in urls] + problems: List[str] = [] + links: Set[str] = set() + ids: Dict[str, Set[str]] = {} + with sync_playwright() as playwright: + browser = playwright.chromium.launch() + for scheme in ("light", "dark"): + for name, (width, height) in VIEWPORTS.items(): + context = browser.new_context( + viewport={"width": width, "height": height}, + color_scheme=scheme, + is_mobile=name == "phone", + ) + page = context.new_page() + errors: List[str] = [] + page.on("pageerror", functools.partial(record, errors)) + for url in [*pages, BASE + "no-such-page/"]: + errors.clear() + response = page.goto(url, wait_until="networkidle") + where = f"{url} ({scheme}, {name})" + expected = 404 if url.endswith("no-such-page/") else 200 + status = response.status if response else None + if status != expected: + problems.append(f"{where}: status {status}") + info = page_info(page) + if info["h1"] != 1: + problems.append(f"{where}: {info['h1']} visible h1") + if not info["description"]: + problems.append(f"{where}: no description") + if expected == 200 and not info["canonical"]: + problems.append(f"{where}: no canonical link") + if info["overflow"]: + problems.append(f"{where}: the page scrolls sideways") + problems.extend(f"{where}: JavaScript error {e}" for e in errors) + problems.extend(f"{where}: {p}" for p in axe_problems(page, axe)) + links.update(info["links"]) + ids[url] = set(info["ids"]) + context.close() + browser.close() + problems.extend(check_links(links, ids)) + server.shutdown() + for problem in problems: + print(problem) + print(f"{len(pages) + 1} pages, 4 views each, {len(problems)} problems") + return 1 if problems else 0 + + +def check_links(links: Set[str], ids: Dict[str, Set[str]]) -> List[str]: + problems: List[str] = [] + status: Dict[str, int] = {} + for link in sorted(links): + # The banner and the 404 page link to the live site's address. + url, fragment = urldefrag(link.replace(LIVE, BASE)) + if not url.startswith(BASE): + continue + if url not in status: + status[url] = fetch_status(url) + if status[url] != 200: + problems.append(f"broken link: {link} ({status[url]})") + elif fragment and url in ids and fragment not in ids[url]: + problems.append(f"broken anchor: {link}") + return problems + + +def fetch_status(url: str) -> int: + try: + with urllib.request.urlopen(url, timeout=10) as response: + return int(response.status) + except urllib.error.HTTPError as exc: + return exc.code + + +def parse_args(argv: List[str]) -> Tuple[Path, str]: + if len(argv) != 2: + raise SystemExit(__doc__) + return Path(argv[0]), Path(argv[1]).read_text() + + +if __name__ == "__main__": + sys.exit(main(*parse_args(sys.argv[1:]))) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index a011fd9..07a673c 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -55,7 +55,9 @@ jobs: - name: No links to hijacked domains anywhere in the repo run: | # The second pattern is the previous author's blog, which now redirects to spam. - if git grep -n -I -i -E 'jsonrpc(client|server)\.com|composed\.blog' -- ':!.github/scripts/check_metadata.py'; then + # The FAQ names the old domains, as plain text, so readers recognise them. + # tests/test_docs.py checks that they're never links there. + if git grep -n -I -i -E 'jsonrpc(client|server)\.com|composed\.blog' -- ':!.github/scripts/check_metadata.py' ':!docs/faq.md'; then echo "::error::Remove the links above. Those domains no longer belong to the project." exit 1 fi @@ -89,16 +91,41 @@ jobs: - run: mkdocs build --strict - name: Examples in the README and docs, with every optional library installed run: | - for f in README.md docs/*.md; do + for f in README.md $(find docs -name '*.md' | sort); do python tests/doc_examples.py "$f" done - name: Start each example server and send it requests run: python docs/examples/check_examples.py + site: + # The built docs in a browser: accessibility (axe-core), links and anchors, + # and pages that scroll sideways. See .github/scripts/check_site.py. + runs-on: ubuntu-24.04 + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false + - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0 + with: + python-version: "3.13" + - run: python -m pip install -r requirements/docs.txt -r requirements/site.txt + - run: python -m playwright install --with-deps chromium + - run: mkdocs build --strict + - name: Download axe-core and check its hash + env: + AXE_VERSION: "4.14.0" + AXE_SHA512: "9WTZxEjsZ7b13TH8JPmbV2z8CHbl80/2hm3XPEG4JgNdQLK81IBRXmSxHfMAOkSqQeRxT/0dwNDz2GOm3zzpcQ==" + run: | + curl -sSfL -o axe.tgz "https://registry.npmjs.org/axe-core/-/axe-core-$AXE_VERSION.tgz" + echo "$AXE_SHA512" | base64 -d > expected.bin + openssl dgst -sha512 -binary axe.tgz | cmp - expected.bin + tar -xzf axe.tgz package/axe.min.js + - run: python .github/scripts/check_site.py site package/axe.min.js + ci-ok: name: CI OK if: always() - needs: [test, lint, package, docs] + needs: [test, lint, package, docs, site] runs-on: ubuntu-24.04 steps: - name: All jobs passed diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 88226b6..293fcf5 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -32,8 +32,22 @@ jobs: echo "Tag $GITHUB_REF_NAME does not match __version__ $version" exit 1 fi - - name: CHANGELOG must have an entry for this version - run: grep -q "^## ${GITHUB_REF_NAME#v}\b" CHANGELOG.md + - name: CHANGELOG entry must be dated, and the docs must not call it unreleased + run: | + version="${GITHUB_REF_NAME#v}" + pattern="${version//./\\.}" + if ! grep -qE "^## ${pattern} \([0-9]{4}-[0-9]{2}-[0-9]{2}\)$" CHANGELOG.md; then + echo "CHANGELOG.md needs a heading like: ## $version (YYYY-MM-DD). See RELEASING.md." + exit 1 + fi + if grep -qE "^ *unreleased: \"?${pattern}\"?$" mkdocs.yml; then + echo "mkdocs.yml still marks $version as unreleased. See RELEASING.md." + exit 1 + fi + if grep -q "isn't released yet" README.md; then + echo "README.md still says a version isn't released yet. See RELEASING.md." + exit 1 + fi - run: python -m build - run: python -m twine check --strict dist/* - run: check-wheel-contents dist/*.whl diff --git a/CHANGELOG.md b/CHANGELOG.md index 50164a9..25a42df 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,11 +1,15 @@ -# jsonrpcserver Change Log +# Changelog -## 5.0.10 +## 5.0.10 (not released yet) The first release since the project moved to [bensynapse/jsonrpcserver](https://github.com/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. +working, apart from the security fix and the "Behaviour changes" below. The +[migration guide](https://bensynapse.github.io/jsonrpcserver/migration/#from-509-to-5010) +lists what you might notice. Until it's on PyPI, the +[Security page](https://bensynapse.github.io/jsonrpcserver/security/#if-you-are-on-509) +shows how to protect a 5.0.9 server. ### Security @@ -22,9 +26,10 @@ The response now leaves `data` out: ``` The same applies to the -32000 "Server error" response for errors inside -jsonrpcserver itself. The exception and its traceback are still logged, through -the `jsonrpcserver.dispatcher` and `jsonrpcserver.async_dispatcher` loggers, so -you can find them in your server logs. +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](https://bensynapse.github.io/jsonrpcserver/errors/#logging) +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 @@ -108,6 +113,13 @@ 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 @@ -192,18 +204,24 @@ work in 5.x but give a `DeprecationWarning`, and will be removed in 6.0. - Add to FAQ. -## 5.0.3 +## 5.0.3 (Aug 31, 2021) - Update readme and documentation. - Internal function `compose` has been replaced with a better one. -## 5.0.2 +## 5.0.2 (Aug 18, 2021) - Update readme and setup.py, minor adjustments. +## 5.0.1 (Aug 18, 2021) + +No changelog entry was written for this release. See the `5.0.1` tag. + ## 5.0.0 (Aug 16, 2021) -A complete rebuild, with a few important usage changes. +A complete rebuild, with a few important usage changes. The +[migration guide](https://bensynapse.github.io/jsonrpcserver/migration/#from-4x-to-5x) +shows how to update 4.x code. - Methods must now return a Result (Success or Error). - The dispatch function now returns a string. @@ -333,7 +351,7 @@ _The 4.x releases will support Python 3.6+ only._ - Pass some context data through dispatch to the methods. - Fix not calling notifications in batch requests. -## 3.4.3 (Jul 13, 2017) +## 3.4.4 (Jul 13, 2017) - Fix AttributeError on batch responses ## 3.4.3 (Jul 12, 2017) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 8e79632..14e2934 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -36,10 +36,19 @@ mkdocs serve ``` `tests/test_docs.py` runs every Python block in the README and docs, so keep -the shown output accurate. The framework examples are files in -`docs/examples/`. To run them against real servers, install -`requirements/examples.txt` and run `python docs/examples/check_examples.py`. -They listen on port 5000, so free it first. +the shown output accurate. `tests/doc_examples.py` explains the markers that +skip a block or start the quickstart server for it. Blocks that need a +framework are skipped unless it's installed, so to run them all, install +`requirements/examples.txt` first, as CI's docs job does. + +The framework examples are files in `docs/examples/`. To start each one and +send it real requests, install `requirements/examples.txt` and run +`python docs/examples/check_examples.py`. It also needs curl. The examples +listen on `localhost:8000`, so free that port first. + +The API reference is built from the docstrings with mkdocstrings. Use Google +style, and add every new public name to `docs/reference.md`. A test checks +that every name in `__all__` is there. ## Pull requests diff --git a/README.md b/README.md index 0edf0cc..b55fbfb 100644 --- a/README.md +++ b/README.md @@ -1,63 +1,124 @@

- PyPI + PyPI version CI - Python versions - Downloads - License + Python 3.8 to 3.14 + Downloads per month + License: MIT

- Jsonrpcserver Logo + jsonrpcserver

- Process incoming JSON-RPC requests in Python + Process incoming JSON-RPC 2.0 requests in Python

Documentation | + API reference | Examples | - Changelog + Changelog | + Migration

-https://github.com/user-attachments/assets/94fb4f04-a5f1-41ca-84dd-7e18b87990e0 - -## Installation +jsonrpcserver takes a [JSON-RPC 2.0](https://www.jsonrpc.org/specification) +request, calls your Python function and gives you the response to send back. +It leaves the networking to you, so it fits into whatever server you already +have. + +## Features + +- Works with any framework or transport. The docs have tested examples for + http.server, Flask, Werkzeug, Django, FastAPI, aiohttp, Sanic, Tornado, + websockets, ZeroMQ and Socket.IO. +- Sync and async: `dispatch` and `async_dispatch`. With `async_dispatch`, the + requests in a batch run concurrently. +- Follows the spec for batches, notifications and errors, and checks each + request's params against your function's signature. +- Keeps exception messages out of responses and in your logs, and limits + batch size with `max_batch_size` (from 5.0.10). +- Typed: ships `py.typed`, and `@method` keeps your functions' signatures for + mypy and pyright. +- Safe to call from several threads, and tested on Python 3.8 to 3.14, + including free-threaded 3.14t. + +## Install ```sh pip install jsonrpcserver ``` -It supports Python 3.8 and later. +The latest release on PyPI is 5.0.9. This README and the documentation +describe 5.0.10, which isn't released yet. 5.0.9 sends exception messages to +clients. The +[Security page](https://bensynapse.github.io/jsonrpcserver/security/#if-you-are-on-509) +shows how to stop that, and the +[changelog](https://bensynapse.github.io/jsonrpcserver/changelog/) lists the +other differences. + +## Quickstart -## Usage +Save this as `server.py` and run it with `python server.py`: + ```python -from jsonrpcserver import Result, Success, dispatch, method +from jsonrpcserver import Result, Success, method, serve @method def ping() -> Result: return Success("pong") + + +if __name__ == "__main__": + serve("localhost", 8000) ``` -```python ->>> dispatch('{"jsonrpc": "2.0", "method": "ping", "id": 1}') -'{"jsonrpc": "2.0", "result": "pong", "id": 1}' +Then send it a request from another terminal: + +```sh +curl -s -H 'Content-Type: application/json' -d '{"jsonrpc": "2.0", "method": "ping", "id": 1}' http://localhost:8000/ ``` -jsonrpcserver doesn't listen on a port itself. The -[examples](https://bensynapse.github.io/jsonrpcserver/examples/) show it with -Flask, FastAPI, Django, aiohttp, websockets, ZeroMQ and more. +Output: -Before you expose a server to the internet, read the -[security notes](https://bensynapse.github.io/jsonrpcserver/security/). +```text +{"jsonrpc": "2.0", "result": "pong", "id": 1} +``` + +`serve()` is a small server for trying things out. In your own framework, +pass the request body to `dispatch` and send back the string it returns. The +[examples](https://bensynapse.github.io/jsonrpcserver/examples/) show how. + +## Security + +Before you put a server on the internet, pass `max_batch_size` to `dispatch` +and limit the request body size in your framework. Upgrade to 5.0.10 when +it's out. The +[Security page](https://bensynapse.github.io/jsonrpcserver/security/) +explains why. ## Documentation -Full documentation is at -[bensynapse.github.io/jsonrpcserver](https://bensynapse.github.io/jsonrpcserver/). +- [Documentation](https://bensynapse.github.io/jsonrpcserver/): guides, + framework examples and the + [API reference](https://bensynapse.github.io/jsonrpcserver/reference/). +- [Migrating from 4.x](https://bensynapse.github.io/jsonrpcserver/migration/): + methods must now return `Success(value)`. A 4.x method that returns a plain + value still runs, but the client gets an Internal error. +- [Contributing](https://github.com/bensynapse/jsonrpcserver/blob/main/CONTRIBUTING.md) + and the + [security policy](https://github.com/bensynapse/jsonrpcserver/blob/main/SECURITY.md). +- [License](https://github.com/bensynapse/jsonrpcserver/blob/main/LICENSE): MIT. ## See also -- [jsonrpcclient](https://github.com/bensynapse/jsonrpcclient): create JSON-RPC requests and parse responses in Python +[jsonrpcclient](https://bensynapse.github.io/jsonrpcclient/) +([GitHub](https://github.com/bensynapse/jsonrpcclient)) creates JSON-RPC +requests and parses the responses in Python. It's the client-side companion +to this library, and its quickstart talks to the server above. + +## Credits + +Created by Beau Barker. Maintained by [Synapse Research](https://synapsereality.io). diff --git a/RELEASING.md b/RELEASING.md index a5165d3..ef7fe1c 100644 --- a/RELEASING.md +++ b/RELEASING.md @@ -29,9 +29,23 @@ Settings → Environments → pypi. ## Each release -1. Merge a pull request that sets `__version__` in `jsonrpcserver/__init__.py` - and adds a `## ` section to CHANGELOG.md. The release workflow - fails if either is missing or they don't match the tag. +1. Merge a pull request that gets the version ready: + - `__version__` in `jsonrpcserver/__init__.py` is the new version. + - Its CHANGELOG.md heading has the release date instead of "not released + yet": `## 5.0.10 (2026-10-20)`. + - The `unreleased` and `pypi_version` lines under `extra` in mkdocs.yml are + deleted. They show the "not on PyPI yet" banner on every docs page. + Merging this redeploys the docs, so merge it just before you tag. + - The paragraph under "Install" in README.md that says the version isn't + released yet is deleted. The README becomes the PyPI page. + - For 5.0.10 only: shorten the "If you are on 5.0.9" section of + `docs/security.md` to a note for people who can't upgrade. The "when it's + out" wording in README.md and SECURITY.md can go too. `grep -rn "when it's out\|isn't on PyPI" README.md + SECURITY.md docs` finds them. + + The release workflow checks the first three. It stops if the version and + tag don't match or the CHANGELOG heading has no date. It also stops if + mkdocs.yml or README.md still say the version isn't released. 2. Tag the merge commit on main and push the tag: ```sh @@ -50,6 +64,14 @@ Settings → Environments → pypi. The release should have two files, a `.tar.gz` and a `.whl`. +5. If the release fixes a security problem, publish a repository security + advisory for it, so Dependabot, `pip-audit` and OSV warn people on older + versions. In the Security tab, choose "New draft security advisory". Set + the affected versions (for 5.0.10: `<= 5.0.9`) and the patched version. + Pick the CWE, link the docs page that explains it, and publish. For the + 5.0.10 fix, the CWE is CWE-209, information exposure through an error + message. + ## If the upload fails - `invalid-publisher`: the PyPI publisher settings above don't match. Check @@ -65,4 +87,6 @@ whose version reached PyPI. ## Docs The docs site deploys itself from main through `.github/workflows/docs.yml`, -so it changes when the docs change, not at release time. +so it changes when the docs change, not at release time. While main is ahead +of PyPI, the `unreleased` setting in mkdocs.yml shows a banner that says so. +The docs also mark features with "New in" or "Changed in" notes. diff --git a/SECURITY.md b/SECURITY.md index 4ccaa45..b38006a 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -14,9 +14,10 @@ problem. We'll reply within a week. Fixes go into the latest 5.x release. Older releases don't get updates. Versions before 5.0.10 send the message of any uncaught exception in a method -to the client. Please upgrade. The -[security notes](https://bensynapse.github.io/jsonrpcserver/security/) in the -docs explain this and the other settings to check before exposing a server. +to the client. Please upgrade when 5.0.10 is on PyPI. Until then, the +[security notes](https://bensynapse.github.io/jsonrpcserver/security/#if-you-are-on-509) +in the docs show how to protect a 5.0.9 server. They also cover the other +settings to check before exposing a server. ## Old domains diff --git a/docs/assets/a11y.js b/docs/assets/a11y.js new file mode 100644 index 0000000..a752b79 --- /dev/null +++ b/docs/assets/a11y.js @@ -0,0 +1,27 @@ +// Small accessibility fixes for Material for MkDocs defaults. They run after +// Material has rendered each page, including after instant navigation. +document$.subscribe(() => { + // The search overlay is a dialog, so it needs a name. + const search = document.querySelector(".md-search"); + if (search && !search.hasAttribute("aria-label")) { + search.setAttribute("aria-label", "Search"); + } + document.querySelectorAll(".md-code__nav").forEach((nav, i) => { + // Each code block's toolbar is a nav landmark; give each a distinct name. + nav.setAttribute("aria-label", `Code block ${i + 1} actions`); + }); + document.querySelectorAll(".highlight pre > code").forEach((code) => { + // A code block that scrolls sideways must be reachable with the keyboard. + if (code.scrollWidth > code.clientWidth) { + code.setAttribute("tabindex", "0"); + } + }); + document.querySelectorAll(".md-typeset__scrollwrap").forEach((wrap, i) => { + // So must a table that's wider than the screen. + if (wrap.scrollWidth > wrap.clientWidth) { + wrap.setAttribute("tabindex", "0"); + wrap.setAttribute("role", "region"); + wrap.setAttribute("aria-label", `Table ${i + 1}, scrolls sideways`); + } + }); +}); diff --git a/docs/assets/apple-touch-icon.png b/docs/assets/apple-touch-icon.png new file mode 100644 index 0000000000000000000000000000000000000000..fac09450bc5bd0afe5fa14b5e559bca5b3f4f610 GIT binary patch literal 7388 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 n_*$rR$D3DSNH&keM>> " and "... " prompts are removed and output lines are left +// out, so the result can be pasted into a file or a terminal. +document.addEventListener( + "click", + (event) => { + const button = event.target.closest("[data-clipboard-target]"); + if (!button) return; + const target = document.querySelector(button.dataset.clipboardTarget); + if (!target || !target.closest(".language-pycon")) return; + const code = target.textContent + .split("\n") + .filter((line) => /^(>>>|\.\.\.)( |$)/.test(line)) + .map((line) => line.slice(4)) + .join("\n"); + button.setAttribute("data-clipboard-text", code + "\n"); + }, + true, +); diff --git a/docs/assets/extra.css b/docs/assets/extra.css index 26e3b96..dc7db7f 100644 --- a/docs/assets/extra.css +++ b/docs/assets/extra.css @@ -1,106 +1,117 @@ +/* System fonts instead of web fonts (theme.font is false in mkdocs.yml). */ :root { - /* ✅ Fonts */ - --md-text-font: -apple-system, BlinkMacSystemFont, "Segoe UI Adjusted", - "Segoe UI", "Liberation Sans", sans-serif; + --md-text-font: -apple-system, BlinkMacSystemFont, "Segoe UI", "Liberation Sans", + Roboto, sans-serif; --md-code-font: "SF Mono", SFMono-Regular, ui-monospace, "DejaVu Sans Mono", Menlo, Consolas, monospace; +} - /* ✅ Light Mode Text Colors */ +/* Code colours with at least 4.5:1 contrast on the code background. Material's + defaults for comments, output and a few token types fall just short. */ +[data-md-color-scheme="default"] { --md-default-fg-color: #111; + --md-code-hl-comment-color: #5e5e5e; + --md-code-hl-generic-color: #5e5e5e; + --md-code-hl-operator-color: #5e5e5e; + --md-code-hl-variable-color: #5e5e5e; +} + +/* Pink is this site's colour (jsonrpcclient's is indigo). Material's pink, + #e92063, gives white text 4.3:1 and fails WCAG AA, so use a darker one: + #c2185b is 5.9:1 against white either way round. */ +[data-md-color-primary="pink"] { + --md-primary-fg-color: #c2185b; + --md-primary-fg-color--light: #d81b60; + --md-primary-fg-color--dark: #ad1457; +} + +[data-md-color-accent="pink"] { + --md-accent-fg-color: #ad1457; + --md-accent-fg-color--transparent: rgba(173, 20, 87, 0.1); +} + +/* Material sets the link colour per scheme and primary colour, so match those + selectors. */ +[data-md-color-scheme="default"][data-md-color-primary="pink"] { + --md-typeset-a-color: #c2185b; +} + +[data-md-color-scheme="slate"][data-md-color-primary="pink"] { + --md-typeset-a-color: #f48fb1; +} + +[data-md-color-scheme="slate"][data-md-color-accent="pink"] { + --md-accent-fg-color: #f8bbd0; + --md-accent-fg-color--transparent: rgba(248, 187, 208, 0.1); } [data-md-color-scheme="slate"] { - /* ✅ Dark Mode Text Colors */ --md-default-fg-color: #e9e9e9; + --md-code-hl-comment-color: #a8a8b3; + --md-code-hl-generic-color: #a8a8b3; + --md-code-hl-number-color: #f39287; + --md-code-hl-constant-color: #ab9ff0; +} + +/* The repository's star and fork counts in the header are faded by default, + which leaves them below 4.5:1 on the pink header. */ +.md-source__facts { + opacity: 1; +} + +/* The "not on PyPI yet" banner sits on a dark background in both schemes. */ +.md-banner a, +.md-banner a:hover, +.md-banner a:focus { + color: #fff; + text-decoration: underline; +} + +.md-banner code { + background-color: transparent; + color: inherit; } -/* Fix a horizontal scroll isue */ -.md-typeset * { - margin-left: 0 !important; - margin-right: 0 !important; +/* The footer's copyright text, which is too faint by default. */ +.md-footer-meta { + --md-footer-fg-color--lighter: hsla(0, 0%, 100%, 0.75); +} + +.md-copyright a { + text-decoration: underline; } .md-typeset { - margin-left: 0 !important; - margin-right: 0 !important; - - p, - h1, - h2, - h3, - h4, - h5, - h6 { - margin: 0; - padding: 0; - padding-left: 20px; - padding-right: 20px; - } - - /* Change header fonts */ - h1, h2, h3, h4, h5, h6 { - font-weight: 700; - font-style: normal; - letter-spacing: -0.5px; - line-height: 140%; - } - - h1 { - color: var(--md-default-fg-color); - font-size: 1.2rem; - margin-bottom: 1em; - } - - h2 { - font-size: 1rem; - } - - h3 { - font-size: 0.9rem; - } - - p, ul, ol, pre { - font-size: 17px; - margin-top: 1em; - margin-bottom: 1em; - } - - ul, ol { - margin-left: 3rem; - padding-left: 3rem; - } - - blockquote { - border-left: 0 !important; - border-radius: 0; - margin: 0; - margin-bottom: 1em; - padding: 1px; - background-color: rgba(255, 87, 34, 0.05); - - [data-md-color-scheme="slate"] { - background-color: rgba(255, 204, 0, 0.1); - } - } - - pre { - line-height: 150%; - } - pre > code { - padding-left: 20px; - } -} - -.md-content__inner { - /* Target only the page title (first H1 in the article) */ - .md-typeset { - h1:first-of-type { - padding-left: 20px; - } - } -} - -article { - padding-bottom: 3rem; + font-size: 0.85rem; +} + +.md-typeset h1, +.md-typeset h2, +.md-typeset h3 { + font-weight: 700; + letter-spacing: -0.01em; } +.md-typeset h1 { + color: var(--md-default-fg-color); +} + +/* Underline links in running text, so they don't rely on colour alone + (WCAG 1.4.1). Navigation, buttons and permalinks keep their own style. */ +.md-typeset p a, +.md-typeset li a, +.md-typeset td a { + text-decoration: underline; + text-underline-offset: 0.15em; +} + +.md-typeset blockquote { + border-left: 0.2rem solid rgb(255, 87, 34); + background-color: rgba(255, 87, 34, 0.05); + color: var(--md-default-fg-color); +} + +[data-md-color-scheme="slate"] .md-typeset blockquote { + border-left-color: rgb(255, 204, 0); + background-color: rgba(255, 204, 0, 0.1); +} diff --git a/docs/assets/favicon.png b/docs/assets/favicon.png new file mode 100644 index 0000000000000000000000000000000000000000..0170a2d33bf34c33098e6f363563f4ea6c0ebf95 GIT binary patch literal 2408 zcmV-u377VXP)xRCM;#M6}Dvn!%MGNV;tW^*r>`{534d10pSE(3ThDy>=R)R%1)p1 zVCmrY_a@p_Uow^PJuAL&TDuf(OVR6!VwZZ9SUoAq$*>$kP7DU2qS--*JkqZtzwSKn z{D%`kkcr0kcU*RLLEOE0ai>;%N{Y|IaUv(G=ckGUPzBUsY|%KXn(iOb^oI7{=l(qw z1Q~1mz>1AGwwm1CF&S0WRKT7rMjr_bg)A@Pa#+ef-n!(#&U@-M%c$pe9wVTt+)*@9XN+bG)%cL_Vq!Eany6EiI|NjQmVIfpTKAekTGJD_#5I!>9D+y7 zlBMUG%tl*E;@VQYU+BiySYJ}SFNtf*Y_!FoexnA@FPbHR4?z7!19E<>9$mn>KRFG= z#OeV#-#C$#$s)-8iD{6aIFXemMRhTS|JXE0Q8kOn^HW8Fo0lsa1BX)%X?Emut(|vbLlrbmz)yH!5v08}fO9y4I(P_DU#IHuYYapVDHgyP$ovTifHmmg zFcLY;`m-@>&%mtefI_ZuOf@07=TUU159IcskE@0-RfQ}Izb1e*mDk5%@X;Y;koqQN!oaDXCa@1LLPDvw6`5G{{dLi5{@nA z!}TH;t|bx(RF(YgHzCX0A<2$@y?KoQBT%Vg&su}MaBc9ev!mgRD#^o7lRf(q+FuU& zJTMfFnJN-QsNVEDXe}YFMa+hEMBlp>DduZWYr%VDRR?y%I?|_J2z-#~aRNXDO_Gqa z`3SrQP_hiHC3)aUM!tOu6iSW4+fqED*U}euhp;w+-uEwb|3~C+ziITEbzseztKsqE z9RW2@OG~lgb!2qZm~Hxx(4+e&7&tqlY&`lT`}ZleAhPg;2^SeNdRT`(@WyNK1}hl3qo65j{;Sq8?M1! zw+a8oyFqFGb34i39}SXwnq}9`)cbPUa_ps_9bf9|a{$1<{todU?k9cZ*;<>L%|1ah zk1S~+d-_Ex*Z!2;FTRVt4zs$G=ttM%uK8jE zgft66rmKgc4c`eVFxygS3_3VO>G3}YjamkAy2!y$1AkDDn8ucVAkTHU;;^MD0Eh_<&$uyF_;uG`ft2!SPaoQQ5bf1Tet?#Tky0@{U9CHGS6oc##ea~!up2!z2$gtxTVtKe zkd^}Gf^)DN){RLgMmJskYwsXY)BxtV0H6wm9DeTyq)+{a=&P590cPYz+f{SU>6mj) zZ;aC7TL>tpj4Qh)NbxbOp#)q_*Zw~-+C|T|FLf!q*)l8#7PM2 zX>5%VCoobC2J4sxEEl1D15|(Vdo)RFD)e}BfLF-p@cVih{_@Sle|ZT1c2`50)wjoH zx;0kFhe$F(_G(u*$^B0-eAN%}FTWP{BAP&iGZRBc8(+lowYgm>KV=U;?X9tieN}zSy~%5S-Vsu*k<%HT;}0fU`gV1BbX(ClQOFj7_p_pL;?Zp_eY?7hh7SU7sraNPhge;} zT%f4WA-3X^9uaO)5CfY{ThET}IMXc!v0@SR3lId4dW&d5ti+jaY3te14V#S-wq?p@ z+upb1nL!_KEsC>wF~&o>5K3e19rH9V#uUZbK_71&{brDD*~g#Gjz4h`e>^=A1XvuO a&;K8lb)PN%CA{wd0000 literal 0 HcmV?d00001 diff --git a/docs/assets/social-card.png b/docs/assets/social-card.png new file mode 100644 index 0000000000000000000000000000000000000000..f6d8bb300c1592296fc6958c2752302527b997d7 GIT binary patch literal 67107 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 F|1VClKF Result: return Success("pong") ``` -```python +```pycon >>> asyncio.run(async_dispatch('{"jsonrpc": "2.0", "method": "ping", "id": 1}')) '{"jsonrpc": "2.0", "result": "pong", "id": 1}' ``` @@ -26,10 +30,34 @@ In a real server you're already inside a coroutine, so write `async_dispatch_to_serializable` and `async_dispatch_to_response` are the async versions of the other two functions. -Plain functions work as methods too, but they run on the event loop, so a slow -one holds up everything else. Async methods don't work with the synchronous -`dispatch`. The client gets an Internal error, and the log says to use -`async_dispatch`. +## Plain methods + +Plain functions work as methods too: + +```python +@method +def add(a: int, b: int) -> Result: + return Success(a + b) +``` + +```pycon +>>> asyncio.run( +... async_dispatch('{"jsonrpc": "2.0", "method": "add", "params": [2, 3], "id": 1}') +... ) +'{"jsonrpc": "2.0", "result": 5, "id": 1}' +``` + +They run on the event loop, so a slow one holds up every other request. Make +slow methods `async`, or move the work to a thread with +`await asyncio.to_thread(...)`. + +!!! info "New in 5.0.10" + In 5.0.9, a plain method called through `async_dispatch` gives an + Internal error. There, make every method `async def`. + +It doesn't work the other way round. Async methods don't work with the +synchronous `dispatch`. The client gets an Internal error, and the log says to +use `async_dispatch`. ## Batches run concurrently @@ -50,7 +78,7 @@ async def wait() -> Result: batch = json.dumps([{"jsonrpc": "2.0", "method": "wait", "id": n} for n in range(10)]) ``` -```python +```pycon >>> start = time.monotonic() >>> responses = json.loads(asyncio.run(async_dispatch(batch))) >>> len(responses) @@ -59,15 +87,18 @@ batch = json.dumps([{"jsonrpc": "2.0", "method": "wait", "id": n} for n in range True ``` -Every request in a batch runs at once, so set `max_batch_size` if clients -can send big batches. See [Security](security.md). +The responses still come back in the same order as the requests. + +Every request in a batch runs at once, so a big batch can start thousands of +tasks. Set `max_batch_size` if clients can send big batches. See +[Security](security.md#limit-batch-size). ## Notifications A notification is a request with no `id`. The spec says not to respond to it, so `async_dispatch` gives an empty string: -```python +```pycon >>> asyncio.run(async_dispatch('{"jsonrpc": "2.0", "method": "ping"}')) '' ``` @@ -76,7 +107,13 @@ With HTTP you have to send something, so send an empty body with status 204. With websockets or a message queue, you can skip sending: ```python -async def handle(request: str, send) -> None: +from typing import Awaitable, Callable + + +async def handle(request: str, send: Callable[[str], Awaitable[None]]) -> None: if response := await async_dispatch(request): await send(response) ``` + +The [framework examples](examples.md) include aiohttp, FastAPI, Sanic, +Tornado, websockets and ZeroMQ's asyncio API. diff --git a/docs/batches.md b/docs/batches.md new file mode 100644 index 0000000..8b94e77 --- /dev/null +++ b/docs/batches.md @@ -0,0 +1,135 @@ +--- +description: How jsonrpcserver handles JSON-RPC notifications and batches. When there's nothing to send, HTTP 204, response order, invalid members, empty batches and max_batch_size. +--- + +# Notifications and batches + +## Notifications + +A notification is a request with no `id`. The client doesn't want an answer, +and the spec says the server must not send one. The method still runs, and +`dispatch` gives an empty string: + +```python +from jsonrpcserver import Result, Success, dispatch, method + + +@method +def ping() -> Result: + return Success("pong") +``` + +```pycon +>>> dispatch('{"jsonrpc": "2.0", "method": "ping"}') +'' +``` + +What to do with the empty string depends on the transport: + +- **HTTP** always sends a response, so send status 204 No Content with no + body. +- **websockets** and most message queues: send nothing. +- **ZeroMQ REQ/REP** sockets must answer every message, so send the empty + string. + +The [framework examples](examples.md) each do the right thing. + +!!! note + A notification gets no response even when it fails, so the client never + hears about the error. That's how the spec wants it. If the method raises + an exception, it's logged (see [Errors and logging](errors.md)). Other + errors, such as an unknown method or params that don't fit, aren't + recorded anywhere. + +## Batches + +A batch is a JSON array of requests. Each one is run, and the responses come +back as an array: + +```pycon +>>> dispatch( +... '[{"jsonrpc": "2.0", "method": "ping", "id": 1}, {"jsonrpc": "2.0", "method": "ping", "id": 2}]' +... ) +'[{"jsonrpc": "2.0", "result": "pong", "id": 1}, {"jsonrpc": "2.0", "result": "pong", "id": 2}]' +``` + +jsonrpcserver sends the responses in the same order as the requests. The spec +doesn't require that, so clients should match responses to requests by `id`. + +`dispatch` runs the requests one after another. `async_dispatch` runs them all +at once. See [Async](async.md#batches-run-concurrently). + +### Notifications in a batch + +Notifications in a batch run, but get no response. If every request in a +batch is a notification, there's nothing to send, and `dispatch` gives an +empty string: + +```pycon +>>> dispatch( +... '[{"jsonrpc": "2.0", "method": "ping", "id": 1}, {"jsonrpc": "2.0", "method": "ping"}]' +... ) +'[{"jsonrpc": "2.0", "result": "pong", "id": 1}]' +>>> dispatch('[{"jsonrpc": "2.0", "method": "ping"}, {"jsonrpc": "2.0", "method": "ping"}]') +'' +``` + +### Invalid members + +Each request in a batch is checked on its own. One that isn't a valid request +gets its own -32600 "Invalid request" response, with `id` null, and the +others run as usual: + +```pycon +>>> dispatch('[1, {"jsonrpc": "2.0", "method": "ping", "id": 1}]') +'[{"jsonrpc": "2.0", "error": {"code": -32600, "message": "Invalid request", "data": "The request failed schema validation"}, "id": null}, {"jsonrpc": "2.0", "result": "pong", "id": 1}]' +``` + +An array inside a batch is not a request either, so it gets the same error. + +!!! info "Changed in 5.0.10" + In 5.0.9, one invalid member got the whole batch rejected with a single + "Invalid request" response. + +### An empty batch + +The spec says an empty array gets a single error response, not an empty +array: + +```pycon +>>> dispatch("[]") +'{"jsonrpc": "2.0", "error": {"code": -32600, "message": "Invalid request", "data": "The request failed schema validation"}, "id": null}' +``` + +## Limit the batch size + +A client can put thousands of requests in one batch, and each one is +validated and run. Set `max_batch_size` on every dispatch call on a server +that strangers can reach: + +```pycon +>>> big_batch = ( +... "[" + ", ".join(['{"jsonrpc": "2.0", "method": "ping", "id": 1}'] * 101) + "]" +... ) +>>> dispatch(big_batch, max_batch_size=100) +'{"jsonrpc": "2.0", "error": {"code": -32600, "message": "Invalid request", "data": "The batch has 101 requests. The limit is 100."}, "id": null}' +``` + +A batch over the limit gets one error response, and none of its requests run. +A single request that isn't in a batch is never affected. The default, +`None`, means no limit. + +`max_batch_size` must be `None` or a positive `int`. Anything else, including +`0`, `True`, `1.5` or `"100"`, raises `ValueError` when you call `dispatch`: + +```pycon +>>> dispatch(big_batch, max_batch_size=0) +Traceback (most recent call last): + ... +ValueError: max_batch_size must be a positive int or None, not 0 +``` + +!!! info "New in 5.0.10" + `max_batch_size`. On 5.0.9, limit the size of the request body in your + web server instead. [Security](security.md#limit-batch-size) explains + why both matter. diff --git a/docs/changelog.md b/docs/changelog.md new file mode 100644 index 0000000..f305617 --- /dev/null +++ b/docs/changelog.md @@ -0,0 +1,5 @@ +--- +description: Every jsonrpcserver release and what changed in it, from the first release to the latest. +--- + +--8<-- "CHANGELOG.md" diff --git a/docs/context.md b/docs/context.md new file mode 100644 index 0000000..90041f9 --- /dev/null +++ b/docs/context.md @@ -0,0 +1,163 @@ +--- +description: Give jsonrpcserver methods the HTTP request, the logged-in user or a database session through context, with examples for Flask, FastAPI and Django. +--- + +# Context + +Methods often need something from the server that the client mustn't control: +the logged-in user, the HTTP request, a database session. Pass it as +`context`. It becomes the first argument of every method, and the client can't +see or change it. + +A small class keeps the context tidy when there's more than one thing to pass: + +```python +from dataclasses import dataclass +from typing import Any + +from jsonrpcserver import Result, Success, dispatch + + +@dataclass +class Context: + user: str + request: Any + + +def whoami(context: Context) -> Result: + return Success(context.user) + + +def user_for(authorization: str) -> str: + # Look the token up in your user store. This is a stand-in. + return {"Bearer abc123": "beau"}.get(authorization, "anonymous") + + +METHODS = {"whoami": whoami} +``` + +The method's other parameters come after `context`, and the request's +`params` fill those as usual. + +## Flask + + +```python +from flask import Flask, Response, request + +app = Flask(__name__) + + +@app.post("/") +def index() -> Response: + context = Context(user_for(request.headers.get("Authorization", "")), request) + if response := dispatch( + request.get_data(as_text=True), METHODS, context=context, max_batch_size=100 + ): + return Response(response, content_type="application/json") + return Response(status=204) +``` + +Trying it with Flask's test client: + + +```pycon +>>> client = app.test_client() +>>> client.post( +... "/", +... data='{"jsonrpc": "2.0", "method": "whoami", "id": 1}', +... headers={"Authorization": "Bearer abc123"}, +... ).get_data(as_text=True) +'{"jsonrpc": "2.0", "result": "beau", "id": 1}' +``` + +## FastAPI + + +```python +from fastapi import FastAPI, Request +from fastapi import Response as FastAPIResponse + +from jsonrpcserver import async_dispatch + +api = FastAPI() + + +@api.post("/") +async def endpoint(request: Request) -> FastAPIResponse: + context = Context(user_for(request.headers.get("Authorization", "")), request) + body = (await request.body()).decode() + if response := await async_dispatch( + body, METHODS, context=context, max_batch_size=100 + ): + return FastAPIResponse(response, media_type="application/json") + return FastAPIResponse(status_code=204) +``` + +`async_dispatch` calls the plain `whoami` method too. To try it, FastAPI's +test client needs [httpx2](https://pypi.org/project/httpx2/): + + +```pycon +>>> from fastapi.testclient import TestClient +>>> TestClient(api).post( +... "/", +... content='{"jsonrpc": "2.0", "method": "whoami", "id": 1}', +... headers={"Authorization": "Bearer abc123"}, +... ).text +'{"jsonrpc": "2.0", "result": "beau", "id": 1}' +``` + +FastAPI's `Depends` doesn't reach into methods, because jsonrpcserver calls +them, not FastAPI. Resolve what you need in the endpoint, as above, and pass +it in the context. + +## Django + + +```python +from django.http import HttpRequest, HttpResponse +from django.views.decorators.csrf import csrf_exempt + + +@csrf_exempt +def jsonrpc(request: HttpRequest) -> HttpResponse: + # With Django's authentication, use request.user instead of user_for. + context = Context(user_for(request.headers.get("Authorization", "")), request) + if response := dispatch( + request.body.decode(), METHODS, context=context, max_batch_size=100 + ): + return HttpResponse(response, content_type="application/json") + return HttpResponse(status=204) +``` + +## A database session per request + +Open the session in the view, pass it in the context, and close it when +`dispatch` returns. Every method in a batch then shares the one session: + +```python +from contextlib import closing +import sqlite3 + + +def count_users(context: sqlite3.Connection) -> Result: + (count,) = context.execute("SELECT count(*) FROM users").fetchone() + return Success(count) + + +def handle(request_body: str) -> str: + with closing(sqlite3.connect(":memory:")) as db: + db.execute("CREATE TABLE users (name TEXT)") # Stand-in for a real database. + return dispatch( + request_body, {"count_users": count_users}, context=db, max_batch_size=100 + ) +``` + +```pycon +>>> handle('{"jsonrpc": "2.0", "method": "count_users", "id": 1}') +'{"jsonrpc": "2.0", "result": 0, "id": 1}' +``` + +With `async_dispatch`, the requests in a batch run concurrently. Make sure the +shared object can be used that way, or open what you need in each method. diff --git a/docs/contributing.md b/docs/contributing.md new file mode 100644 index 0000000..1506091 --- /dev/null +++ b/docs/contributing.md @@ -0,0 +1,5 @@ +--- +description: How to set up jsonrpcserver for development, run its checks, and send a pull request. +--- + +--8<-- "CONTRIBUTING.md" diff --git a/docs/dispatch.md b/docs/dispatch.md index bbefd8f..d78fc26 100644 --- a/docs/dispatch.md +++ b/docs/dispatch.md @@ -1,3 +1,7 @@ +--- +description: The dispatch function in jsonrpcserver and every option it takes, from methods and context to debug, max_batch_size, deserializer, serializer and validator. Plus the dict and Response forms of the result. +--- + # Dispatch `dispatch` takes a JSON-RPC request string, calls the method and gives a @@ -12,7 +16,7 @@ def ping() -> Result: return Success("pong") ``` -```python +```pycon >>> dispatch('{"jsonrpc": "2.0", "method": "ping", "id": 1}') '{"jsonrpc": "2.0", "result": "pong", "id": 1}' ``` @@ -20,22 +24,18 @@ def ping() -> Result: It never raises for a bad request or a failing method. Those become JSON-RPC error responses, as the spec requires: -```python +```pycon >>> dispatch('{"jsonrpc": "2.0", "method": "nope", "id": 1}') '{"jsonrpc": "2.0", "error": {"code": -32601, "message": "Method not found", "data": "nope"}, "id": 1}' >>> dispatch("{") '{"jsonrpc": "2.0", "error": {"code": -32700, "message": "Parse error", "data": "Expecting property name enclosed in double quotes: line 1 column 2 (char 1)"}, "id": null}' ``` -A batch gets a list of responses, in the same order: - -```python ->>> dispatch('[{"jsonrpc": "2.0", "method": "ping", "id": 1}, {"jsonrpc": "2.0", "method": "ping", "id": 2}]') -'[{"jsonrpc": "2.0", "result": "pong", "id": 1}, {"jsonrpc": "2.0", "result": "pong", "id": 2}]' -``` +[Errors and logging](errors.md) lists every error it can send. A notification, or a batch of only notifications, gives an empty string. The -spec says not to respond to those. +spec says not to respond to those. [Notifications and batches](batches.md) +covers both. [See how dispatch is used in different frameworks.](examples.md) @@ -54,12 +54,16 @@ def multiply(a: int, b: int) -> Result: return Success(a * b) ``` -```python ->>> dispatch('{"jsonrpc": "2.0", "method": "multiply", "params": [2, 3], "id": 1}', methods={"multiply": multiply}) +```pycon +>>> dispatch( +... '{"jsonrpc": "2.0", "method": "multiply", "params": [2, 3], "id": 1}', +... methods={"multiply": multiply}, +... ) '{"jsonrpc": "2.0", "result": 6, "id": 1}' ``` -The default is the dict that `@method` fills in. +The default is the dict that `@method` fills in, +`jsonrpcserver.methods.global_methods`. Any mapping works, not only a dict. ### context @@ -71,12 +75,17 @@ def greet(context: str, name: str) -> Result: return Success(context + " " + name) ``` -```python ->>> dispatch('{"jsonrpc": "2.0", "method": "greet", "params": ["Beau"], "id": 1}', methods={"greet": greet}, context="Hello") +```pycon +>>> dispatch( +... '{"jsonrpc": "2.0", "method": "greet", "params": ["Beau"], "id": 1}', +... methods={"greet": greet}, +... context="Hello", +... ) '{"jsonrpc": "2.0", "result": "Hello Beau", "id": 1}' ``` -The client can't see or set it. +The client can't see or set it. [Context](context.md) shows how to pass the +HTTP request or the user from Flask, FastAPI and Django. ### debug @@ -89,12 +98,16 @@ def broken() -> Result: raise ValueError("Something went wrong") ``` -```python +```pycon >>> import logging >>> logging.disable(logging.CRITICAL) # Keep the logged traceback out of this page. >>> dispatch('{"jsonrpc": "2.0", "method": "broken", "id": 1}', methods={"broken": broken}) '{"jsonrpc": "2.0", "error": {"code": -32603, "message": "Internal error"}, "id": 1}' ->>> dispatch('{"jsonrpc": "2.0", "method": "broken", "id": 1}', methods={"broken": broken}, debug=True) +>>> dispatch( +... '{"jsonrpc": "2.0", "method": "broken", "id": 1}', +... methods={"broken": broken}, +... debug=True, +... ) '{"jsonrpc": "2.0", "error": {"code": -32603, "message": "Internal error", "data": "Something went wrong"}, "id": 1}' >>> logging.disable(logging.NOTSET) ``` @@ -102,18 +115,30 @@ def broken() -> Result: Only use it in development. Exception messages can include passwords, file paths and SQL. The default is `False`. +!!! info "New in 5.0.10" + The `debug` option, and leaving the message out by default. In 5.0.9 and + earlier the message is always sent, and `debug` raises `TypeError`. See + [Security](security.md#if-you-are-on-509). + ### max_batch_size The most requests a batch may hold. A bigger batch gets a single -32600 "Invalid request" response, and none of its requests are run: -```python ->>> dispatch('[{"jsonrpc": "2.0", "method": "ping", "id": 1}, {"jsonrpc": "2.0", "method": "ping", "id": 2}]', max_batch_size=1) +```pycon +>>> dispatch( +... '[{"jsonrpc": "2.0", "method": "ping", "id": 1}, {"jsonrpc": "2.0", "method": "ping", "id": 2}]', +... max_batch_size=1, +... ) '{"jsonrpc": "2.0", "error": {"code": -32600, "message": "Invalid request", "data": "The batch has 2 requests. The limit is 1."}, "id": null}' ``` The default, `None`, means no limit. A server open to the internet should set -one. See [Security](security.md). +one. See [Security](security.md#limit-batch-size). Anything other than `None` +or a positive `int` raises `ValueError`. + +!!! info "New in 5.0.10" + 5.0.9 raises `TypeError` for this keyword. ### deserializer @@ -126,6 +151,9 @@ import ujson dispatch('{"jsonrpc": "2.0", "method": "ping", "id": 1}', deserializer=ujson.loads) ``` +If it raises, the client gets a -32700 "Parse error" whose `data` is the +exception's message, so don't put anything secret in it. + ### serializer The function that turns the response into a string. The default is @@ -133,42 +161,82 @@ The function that turns the response into a string. The default is `Infinity` gives an Internal error instead of output that isn't valid JSON. If the serializer raises for a response (say the method returned a -`datetime`), that response becomes an Internal error. The rest of a batch is -sent as usual. +`datetime`), that response becomes an Internal error, and the error is logged. +The rest of a batch is sent as usual. ```python dispatch('{"jsonrpc": "2.0", "method": "ping", "id": 1}', serializer=ujson.dumps) ``` +!!! info "Changed in 5.0.10" + 5.0.9 writes `NaN` and `Infinity` into the response, and raises when the + serializer fails. + ### validator The function that checks each request against the JSON-RPC spec, after -parsing. It should raise an exception, any exception, if the request is -invalid. In a batch, it's called once for each request. The default checks -against a JSON schema. - -Validation takes most of the time for a small method. If you're sure the -requests are valid, turn it off: +parsing. The default checks against a JSON schema. [Validation](validation.md) +says what it checks, how to write your own, and what you lose by turning it +off. -```python -dispatch('{"jsonrpc": "2.0", "method": "ping", "id": 1}', validator=lambda _: None) -``` +!!! info "Changed in 5.0.10" + In a batch, the validator is called once for each request. In 5.0.9 it + was called once with the whole list. ## Other return types -`dispatch` is an alias for `dispatch_to_json`. Two other functions take the -same options, apart from `serializer`, and give the response in other forms: +`dispatch` is also called `dispatch_to_json`. Two other functions take the +same options, apart from `serializer`, and give the response in other forms. -- `dispatch_to_serializable` gives a dict, a list of dicts for a batch, or - `None` for a notification. -- `dispatch_to_response` gives `Response` objects. Each is an oslash `Right` - holding a `SuccessResponse`, or a `Left` holding an `ErrorResponse`. Both are - defined in - [`jsonrpcserver.response`](https://github.com/bensynapse/jsonrpcserver/blob/main/jsonrpcserver/response.py). +### dispatch_to_serializable -```python +It gives a dict, a list of dicts for a batch, or `None` for a notification. +Use it when your framework serializes the response itself: + +```pycon >>> from jsonrpcserver import dispatch_to_serializable >>> dispatch_to_serializable('{"jsonrpc": "2.0", "method": "ping", "id": 1}') {'jsonrpc': '2.0', 'result': 'pong', 'id': 1} ``` + +### dispatch_to_response + +It gives `Response` objects, or `None` for a notification. Use it to look at +or change responses before they're serialized. It also takes a `post_process` +function, which is applied to each response. + +A `Response` comes from the [oslash](https://pypi.org/project/oslash/) +library. It's a `Right` holding a `SuccessResponse`, or a `Left` holding an +`ErrorResponse`. oslash has no public way to read them, so check which one you +have and read `_value` or `_error`. Those attributes are stable for all of +5.x: + +```pycon +>>> from oslash.either import Left +>>> from jsonrpcserver import dispatch_to_response +>>> response = dispatch_to_response('{"jsonrpc": "2.0", "method": "ping", "id": 1}') +>>> isinstance(response, Left) +False +>>> response._value +SuccessResponse(result='pong', id=1) +>>> error = dispatch_to_response('{"jsonrpc": "2.0", "method": "nope", "id": 1}') +>>> isinstance(error, Left) +True +>>> error._error +ErrorResponse(code=-32601, message='Method not found', data='nope', id=1) +``` + +`print(response)` raises `TypeError: not all arguments converted during +string formatting`, because of a bug in oslash. Turn it into a dict first with +`to_dict`: + +```pycon +>>> from jsonrpcserver.response import to_dict +>>> print(to_dict(response)) +{'jsonrpc': '2.0', 'result': 'pong', 'id': 1} +``` + +For a batch, it gives a list of Responses. Everything here works the same +with `async_dispatch_to_serializable` and `async_dispatch_to_response`. See +[Async](async.md). diff --git a/docs/errors.md b/docs/errors.md new file mode 100644 index 0000000..6cdbf6f --- /dev/null +++ b/docs/errors.md @@ -0,0 +1,181 @@ +--- +description: Every error code jsonrpcserver sends, what its data holds, what reaches the client and what is logged. The jsonrpcserver loggers, debug mode, and how to see tracebacks. +--- + +# Errors and logging + +## The errors the client can get + +These are the errors jsonrpcserver sends by itself. Your own errors, from +`Error` or `JsonRpcError`, are sent exactly as you made them. + +| Code | Message | When | `data` | +|---|---|---|---| +| -32700 | Parse error | The request isn't valid JSON, or your `deserializer` raised. | The deserializer's exception message. | +| -32600 | Invalid request | The JSON isn't a valid request, a batch is empty, or a batch is bigger than `max_batch_size`. | "The request failed schema validation", or the batch size and the limit. | +| -32601 | Method not found | No method has that name. | The method name from the request. | +| -32602 | Invalid params | The params don't fit the method's signature. | Python's explanation, which names the parameter, such as "missing a required argument: 'name'". | +| -32603 | Internal error | The method raised an exception, returned something other than `Success` or `Error`, or returned a result the serializer couldn't handle. | None. With `debug=True`, the exception message. | +| -32000 | Server error | Something failed inside jsonrpcserver, outside any method. For example, a custom validator let through a request with no `method`. | None. With `debug=True`, the exception message. | + +`debug` only changes the last two rows. The `data` in the other rows always +reaches the client. Keep that in mind if you write a custom deserializer, +because its exception messages are sent as they are. + +!!! info "Changed in 5.0.10" + Before 5.0.10, the -32603 and -32000 errors always carried the exception + message. It could hold passwords, paths or SQL. See + [Security](security.md). + +## Four ways for a method to fail + +```python +import logging + +from jsonrpcserver import Error, InvalidParams, JsonRpcError, Result, Success, dispatch + + +def by_return(amount: int) -> Result: + return Error(1, "Insufficient funds", {"balance": 10}) + + +def by_raise(amount: int) -> Result: + raise JsonRpcError(1, "Insufficient funds", {"balance": 10}) + + +def bad_value(amount: int) -> Result: + return InvalidParams("amount must be positive") + + +def by_accident(amount: int) -> Result: + return Success(amount / 0) + + +methods = { + "by_return": by_return, + "by_raise": by_raise, + "bad_value": bad_value, + "by_accident": by_accident, +} +``` + +```pycon +>>> logging.disable(logging.CRITICAL) # Keep the traceback out of this page. +>>> dispatch('{"jsonrpc": "2.0", "method": "by_return", "params": [50], "id": 1}', methods) +'{"jsonrpc": "2.0", "error": {"code": 1, "message": "Insufficient funds", "data": {"balance": 10}}, "id": 1}' +>>> dispatch('{"jsonrpc": "2.0", "method": "by_raise", "params": [50], "id": 1}', methods) +'{"jsonrpc": "2.0", "error": {"code": 1, "message": "Insufficient funds", "data": {"balance": 10}}, "id": 1}' +>>> dispatch('{"jsonrpc": "2.0", "method": "bad_value", "params": [-5], "id": 1}', methods) +'{"jsonrpc": "2.0", "error": {"code": -32602, "message": "Invalid params", "data": "amount must be positive"}, "id": 1}' +>>> dispatch( +... '{"jsonrpc": "2.0", "method": "by_accident", "params": [50], "id": 1}', methods +... ) +'{"jsonrpc": "2.0", "error": {"code": -32603, "message": "Internal error"}, "id": 1}' +>>> logging.disable(logging.NOTSET) +``` + +- **Return `Error`** for errors the client should know about. It's the + normal way. +- **Raise `JsonRpcError`** when the error is found deep inside other + functions. The response is the same as returning `Error`. +- **Return `InvalidParams`** when the arguments have the right shape but a + bad value. +- **An uncaught exception** is a bug as far as the client is concerned. It + gets a bare Internal error, and the details go to the log. + +Errors you make on purpose are sent as they are, whatever `debug` is, so +don't put secrets in them. + +## Debug mode + +`debug=True` adds the exception message to the -32603 and -32000 errors, so +you can see what went wrong without reading the log: + +```pycon +>>> logging.disable(logging.CRITICAL) +>>> dispatch( +... '{"jsonrpc": "2.0", "method": "by_accident", "params": [50], "id": 1}', +... methods, +... debug=True, +... ) +'{"jsonrpc": "2.0", "error": {"code": -32603, "message": "Internal error", "data": "division by zero"}, "id": 1}' +>>> logging.disable(logging.NOTSET) +``` + +Use it in development only. It's the same option on every dispatch function, +sync and async. It's new in 5.0.10. + +## Spec warnings + +The spec says an error code must be an integer, and the message should be a +string. It also reserves method names that start with `rpc.`. jsonrpcserver +warns about these with a `UserWarning`, but still sends what you gave it, so +existing code keeps working: + +```pycon +>>> import warnings +>>> with warnings.catch_warnings(record=True) as caught: +... warnings.simplefilter("always") +... _ = Error("E1", "Insufficient funds") +>>> print(caught[0].message) +JSON-RPC error codes must be integers, not 'E1' +``` + +To make them errors in your tests, run pytest with `-W error::UserWarning`. +These warnings are new in 5.0.10. 6.0 may turn them into errors. + +## Logging + +Everything is logged on the `jsonrpcserver` logger or one of its children: + +| Logger | What it logs | +|---|---| +| `jsonrpcserver.dispatcher` | For `dispatch`: an exception a method didn't catch (ERROR, with the traceback). A method that returned something other than `Success` or `Error` (ERROR). A failure inside jsonrpcserver (ERROR, with the traceback). | +| `jsonrpcserver.async_dispatcher` | The same, for `async_dispatch`. | +| `jsonrpcserver.main` | A result the serializer couldn't handle, such as a `datetime` (ERROR, with the traceback). Both sync and async. | +| `jsonrpcserver.server` | `serve()` only: where it's listening, and one line per HTTP request (INFO). | + +Invalid requests, unknown methods and params that don't fit aren't logged. +The client gets the error, and it's not a problem with your server. + +jsonrpcserver doesn't configure logging itself. If nothing configures it, +Python still prints warnings and errors to stderr, but without the time or the +logger's name. To see them properly, configure logging when your server +starts: + +```python +logging.basicConfig( + level=logging.INFO, format="%(asctime)s %(name)s %(levelname)s %(message)s" +) +``` + +To change only jsonrpcserver's messages, set the level or add a handler on +the parent logger: `logging.getLogger("jsonrpcserver")`. + +This is what a method that returns a plain value, as it would in 4.x, looks +like in the log: + +```python +import sys + +handler = logging.StreamHandler(sys.stdout) +handler.setFormatter(logging.Formatter("%(name)s %(levelname)s: %(message)s")) +logging.getLogger("jsonrpcserver").addHandler(handler) + + +def ping() -> str: + return "pong" # Should be Success("pong") + + +dispatch('{"jsonrpc": "2.0", "method": "ping", "id": 1}', {"ping": ping}) +logging.getLogger("jsonrpcserver").removeHandler(handler) +``` + +```text title="Output" +jsonrpcserver.dispatcher ERROR: Method 'ping' returned 'pong', which is not a Result, so the client got an Internal error. Return Success(value) or Error(code, message). Since 5.0 a plain return value is not enough: https://bensynapse.github.io/jsonrpcserver/migration/ +``` + +!!! info "New in 5.0.10" + The `jsonrpcserver.main` messages and this one. Before 5.0.10, a + serializer failure raised out of `dispatch`, and a plain return value was + only explained in the response's `data`. diff --git a/docs/examples.md b/docs/examples.md index 78bcf48..829ef4b 100644 --- a/docs/examples.md +++ b/docs/examples.md @@ -1,102 +1,56 @@ -# Examples - -jsonrpcserver doesn't listen on a port itself. You receive the request with a -framework or transport library, pass it to `dispatch` or `async_dispatch`, and -send back the result. Each example below answers `ping` with `pong` on -`localhost:5000`. CI starts every one of them and sends it real requests. - -For HTTP, send status 204 with an empty body when `dispatch` gives an empty -string. That means the request was a notification. With websockets and most -message queues, you can send nothing at all. - -The libraries' own docs cover running them in production. - -## http.server - -Python's built-in HTTP server, with no other dependencies: - -```python ---8<-- "docs/examples/http_server.py" -``` - -jsonrpcserver also has a small built-in server, `serve()`. It's for trying -things out, not for production: - -```python ---8<-- "docs/examples/serve.py" -``` - -## Flask - -```python ---8<-- "docs/examples/flask_server.py" -``` - -## Werkzeug - -```python ---8<-- "docs/examples/werkzeug_server.py" -``` - -## Django - -A whole Django project in one file. In your project, the view goes in an app -and the URL pattern in its `urls.py`. - -```python ---8<-- "docs/examples/django_server.py" -``` - -## FastAPI - -```python ---8<-- "docs/examples/fastapi_server.py" -``` - -## aiohttp - -```python ---8<-- "docs/examples/aiohttp_server.py" -``` - -## Sanic - -```python ---8<-- "docs/examples/sanic_server.py" -``` - -## Tornado - -```python ---8<-- "docs/examples/tornado_server.py" -``` - -## websockets - -Uses the `websockets.asyncio` server from websockets 13 and later. - -```python ---8<-- "docs/examples/websockets_server.py" -``` - -## ZeroMQ - -Using [pyzmq](https://pyzmq.readthedocs.io/): - -```python ---8<-- "docs/examples/zeromq_server.py" -``` - -With asyncio, using pyzmq's `zmq.asyncio`: - -```python ---8<-- "docs/examples/zeromq_async_server.py" -``` - -## Socket.IO - -Using [Flask-SocketIO](https://flask-socketio.readthedocs.io/): - -```python ---8<-- "docs/examples/socketio_server.py" -``` +--- +description: Use jsonrpcserver with any Python framework or transport. Complete, tested examples for http.server, Flask, Werkzeug, Django, FastAPI, aiohttp, Sanic, Tornado, websockets, ZeroMQ and Socket.IO. +--- + +# Frameworks + +jsonrpcserver doesn't do the networking. You receive the request with a +framework or transport library, pass it to `dispatch` or `async_dispatch`, +and send back the result. Each page below has a complete example that answers +`ping` with `pong` on `localhost:8000`. CI starts every one of them and sends +it real requests, including a batch that's too big and, for HTTP, a body +that's too big. + +| Framework | Transport | Sync or async | Body size limit in the example | Page | +|---|---|---|---|---| +| `http.server` (standard library) | HTTP | sync | checked by hand | [http.server and serve()](frameworks/http-server.md) | +| [Flask](https://flask.palletsprojects.com/) | HTTP | sync | `MAX_CONTENT_LENGTH` | [Flask](frameworks/flask.md) | +| [Werkzeug](https://werkzeug.palletsprojects.com/) | HTTP | sync | `max_content_length` | [Werkzeug](frameworks/werkzeug.md) | +| [Django](https://www.djangoproject.com/) | HTTP | sync | `DATA_UPLOAD_MAX_MEMORY_SIZE` | [Django](frameworks/django.md) | +| [FastAPI](https://fastapi.tiangolo.com/) | HTTP | async | checked by hand | [FastAPI](frameworks/fastapi.md) | +| [aiohttp](https://docs.aiohttp.org/) | HTTP | async | `client_max_size` | [aiohttp](frameworks/aiohttp.md) | +| [Sanic](https://sanic.dev/) | HTTP | async | `REQUEST_MAX_SIZE` | [Sanic](frameworks/sanic.md) | +| [Tornado](https://www.tornadoweb.org/) | HTTP | async | `max_body_size` | [Tornado](frameworks/tornado.md) | +| [websockets](https://websockets.readthedocs.io/) | WebSocket | async | `max_size` | [websockets](frameworks/websockets.md) | +| [pyzmq](https://pyzmq.readthedocs.io/) | ZeroMQ | both | `MAXMSGSIZE` | [ZeroMQ](frameworks/zeromq.md) | +| [Flask-SocketIO](https://flask-socketio.readthedocs.io/) | Socket.IO | sync | `max_http_buffer_size` | [Socket.IO](frameworks/socketio.md) | + +The pattern is the same everywhere: + +1. Read the request body as a string. Refuse one that's too big before you + read it. +2. Pass it to `dispatch`, or `await async_dispatch(...)` in an async + framework, with `max_batch_size` set. +3. If the result is a non-empty string, send it with + `Content-Type: application/json` and status 200. If it's empty, the + request was a notification: over HTTP, send status 204 with no body. Over + other transports, send nothing (ZeroMQ's REQ/REP sockets are the exception: + they must reply, so send the empty string). + +A JSON-RPC error is still a successful HTTP exchange, so it's sent with +status 200 too. + +Every example limits the body to 1,000,000 bytes and batches to 100 requests. +Pick limits that fit your methods. [Security](security.md) explains why both +matter. To give methods the request or the logged-in user, see +[Context](context.md). + +!!! tip "Port 8000" + The examples use port 8000, the same as the + [jsonrpcclient](https://bensynapse.github.io/jsonrpcclient/) examples. + Run one of each and they talk to each other. Port 5000, which many + tutorials use, is taken by the AirPlay Receiver on recent macOS versions. + +The examples listen on `localhost` only. To accept connections from other +machines, change it to the address you want. Then put the server behind a +production web server, as each framework's docs describe. diff --git a/docs/examples/aiohttp_server.py b/docs/examples/aiohttp_server.py index 11e0137..ce05a99 100644 --- a/docs/examples/aiohttp_server.py +++ b/docs/examples/aiohttp_server.py @@ -9,13 +9,15 @@ async def ping() -> Result: async def handle(request: web.Request) -> web.Response: - if response := await async_dispatch(await request.text()): + # max_batch_size: see the Security page. + if response := await async_dispatch(await request.text(), max_batch_size=100): return web.Response(text=response, content_type="application/json") return web.Response(status=204) -app = web.Application() +# Bigger requests get 413 Request Entity Too Large. 1 MiB is also the default. +app = web.Application(client_max_size=1_000_000) app.router.add_post("/", handle) if __name__ == "__main__": - web.run_app(app, host="localhost", port=5000) + web.run_app(app, host="localhost", port=8000) diff --git a/docs/examples/check_examples.py b/docs/examples/check_examples.py index b755796..7f59104 100644 --- a/docs/examples/check_examples.py +++ b/docs/examples/check_examples.py @@ -4,24 +4,51 @@ Each server must answer a "ping" request with "pong". The HTTP servers must also answer a notification with 204 No Content and an empty body. The servers -listen on localhost port 5000, as the docs say. Needs the packages in -requirements/examples.txt. +that follow the Security page must refuse a batch over 100 requests and a body +over 1,000,000 bytes. The servers listen on localhost port 8000, as the docs +say. Needs the packages in requirements/examples.txt, and curl. + +It also sends the quickstart server the curl command from the docs. """ +import http.client import json +import shlex import socket import subprocess import sys import time +import urllib.error import urllib.request from pathlib import Path -from typing import Callable, Dict, List, Tuple +from typing import Callable, Dict, List, Optional, Tuple HERE = Path(__file__).parent -PORT = 5000 +PORT = 8000 REQUEST = json.dumps({"jsonrpc": "2.0", "method": "ping", "id": 1}) NOTIFICATION = json.dumps({"jsonrpc": "2.0", "method": "ping"}) EXPECTED = {"jsonrpc": "2.0", "result": "pong", "id": 1} +BIG_BATCH = json.dumps( + [{"jsonrpc": "2.0", "method": "ping", "id": n} for n in range(101)] +) +BATCH_REFUSED = { + "jsonrpc": "2.0", + "error": { + "code": -32600, + "message": "Invalid request", + "data": "The batch has 101 requests. The limit is 100.", + }, + "id": None, +} +MAX_BODY = 1_000_000 + +# The curl command in the README and on the home page. tests/test_docs.py +# checks that they show this command and this output. +CURL = ( + "curl -s -H 'Content-Type: application/json' " + """-d '{"jsonrpc": "2.0", "method": "ping", "id": 1}' http://localhost:8000/""" +) +CURL_OUTPUT = '{"jsonrpc": "2.0", "result": "pong", "id": 1}' def post(body: str) -> Tuple[int, str, str]: @@ -30,15 +57,46 @@ def post(body: str) -> Tuple[int, str, str]: data=body.encode(), headers={"Content-Type": "application/json"}, ) - with urllib.request.urlopen(request, timeout=10) as response: - return ( - response.status, - response.headers.get("Content-Type", ""), - response.read().decode(), - ) + try: + with urllib.request.urlopen(request, timeout=10) as response: + return ( + response.status, + response.headers.get("Content-Type", ""), + response.read().decode(), + ) + except urllib.error.HTTPError as exc: + return exc.code, exc.headers.get("Content-Type", ""), exc.read().decode() + + +def post_raw(body: Optional[bytes]) -> int: + """POST without urllib's help: no Content-Length when body is None.""" + connection = http.client.HTTPConnection("localhost", PORT, timeout=10) + try: + if body is None: + connection.putrequest("POST", "/") + connection.putheader("Content-Type", "application/json") + connection.endheaders() + else: + connection.request( + "POST", "/", body=body, headers={"Content-Type": "application/json"} + ) + return connection.getresponse().status + finally: + connection.close() + + +def post_raw_body(body: bytes) -> Tuple[int, str]: + """POST bytes that may not be valid UTF-8. Return the status and body.""" + connection = http.client.HTTPConnection("localhost", PORT, timeout=10) + try: + connection.request("POST", "/", body=body) + response = connection.getresponse() + return response.status, response.read().decode() + finally: + connection.close() -def check_http() -> None: +def check_ping_and_notification() -> None: status, content_type, body = post(REQUEST) assert status == 200, status assert content_type.startswith("application/json"), content_type @@ -47,12 +105,47 @@ def check_http() -> None: assert (status, body) == (204, ""), (status, body) +def check_limits(too_large: int) -> None: + status, _, body = post(BIG_BATCH) + assert status == 200, status + assert json.loads(body) == BATCH_REFUSED, body + status = post_raw(b" " * (MAX_BODY + 1)) + assert status == too_large, status + + +def check_quickstart() -> None: + check_ping_and_notification() + output = subprocess.run( + shlex.split(CURL), capture_output=True, text=True, timeout=30, check=True + ).stdout + assert output == CURL_OUTPUT, output + + +def check_http_server() -> None: + check_ping_and_notification() + check_limits(413) + assert post_raw(None) == 411 + status, body = post_raw_body(b'{"jsonrpc": "2.0", "method": "\xff", "id": 1}') + assert status == 200, status + assert json.loads(body)["error"]["code"] == -32700, body + + +def check_http(too_large: int) -> Callable[[], None]: + def check() -> None: + check_ping_and_notification() + check_limits(too_large) + + return check + + def check_websockets() -> None: from websockets.sync.client import connect - with connect(f"ws://localhost:{PORT}") as websocket: + with connect(f"ws://localhost:{PORT}", max_size=None) as websocket: websocket.send(REQUEST) assert json.loads(websocket.recv(timeout=10)) == EXPECTED + websocket.send(BIG_BATCH) + assert json.loads(websocket.recv(timeout=10)) == BATCH_REFUSED def check_zeromq() -> None: @@ -68,6 +161,8 @@ def check_zeromq() -> None: assert json.loads(client.recv_string()) == EXPECTED client.send_string(NOTIFICATION) assert client.recv_string() == "" + client.send_string(BIG_BATCH) + assert json.loads(client.recv_string()) == BATCH_REFUSED finally: client.close() context.term() @@ -82,23 +177,29 @@ def check_socketio() -> None: event, data = client.receive(timeout=10) assert event == "message", event assert json.loads(data) == EXPECTED, data + client.emit("message", BIG_BATCH) + event, data = client.receive(timeout=10) + assert json.loads(data) == BATCH_REFUSED, data EXAMPLES: Dict[str, Callable[[], None]] = { - "http_server.py": check_http, - "serve.py": check_http, - "flask_server.py": check_http, - "werkzeug_server.py": check_http, - "django_server.py": check_http, - "fastapi_server.py": check_http, - "aiohttp_server.py": check_http, - "sanic_server.py": check_http, - "tornado_server.py": check_http, + "quickstart.py": check_quickstart, + "http_server.py": check_http_server, + "flask_server.py": check_http(413), + "werkzeug_server.py": check_http(413), + # Django answers a body over DATA_UPLOAD_MAX_MEMORY_SIZE with 400. + "django_server.py": check_http(400), + "fastapi_server.py": check_http(413), + "aiohttp_server.py": check_http(413), + "sanic_server.py": check_http(413), + "tornado_server.py": check_http(400), "websockets_server.py": check_websockets, "zeromq_server.py": check_zeromq, "zeromq_async_server.py": check_zeromq, "socketio_server.py": check_socketio, } +# Files that aren't servers. +NOT_SERVERS = {"check_examples.py"} def port_open() -> bool: @@ -148,7 +249,7 @@ def run(example: str) -> bool: def main(names: List[str]) -> int: - on_disk = {path.name for path in HERE.glob("*.py")} - {Path(__file__).name} + on_disk = {path.name for path in HERE.glob("*.py")} - NOT_SERVERS missing = on_disk - set(EXAMPLES) if missing: print(f"Examples with no check: {sorted(missing)}") diff --git a/docs/examples/django_server.py b/docs/examples/django_server.py index db58863..3991ff3 100644 --- a/docs/examples/django_server.py +++ b/docs/examples/django_server.py @@ -13,6 +13,8 @@ ROOT_URLCONF=__name__, ALLOWED_HOSTS=["localhost", "127.0.0.1"], SECRET_KEY="replace-me", + # Bigger requests get 400 Bad Request. Django's default is 2.5 MB. + DATA_UPLOAD_MAX_MEMORY_SIZE=1_000_000, ) @@ -23,7 +25,8 @@ def ping() -> Result: @csrf_exempt def jsonrpc(request: HttpRequest) -> HttpResponse: - if response := dispatch(request.body.decode()): + # max_batch_size: see the Security page. + if response := dispatch(request.body.decode(), max_batch_size=100): return HttpResponse(response, content_type="application/json") return HttpResponse(status=204) @@ -33,4 +36,6 @@ def jsonrpc(request: HttpRequest) -> HttpResponse: if __name__ == "__main__": from django.core.management import execute_from_command_line - execute_from_command_line([sys.argv[0], "runserver", "5000", "--noreload"]) + execute_from_command_line( + [sys.argv[0], "runserver", "localhost:8000", "--noreload"] + ) diff --git a/docs/examples/fastapi_server.py b/docs/examples/fastapi_server.py index 4a36856..96fffbd 100644 --- a/docs/examples/fastapi_server.py +++ b/docs/examples/fastapi_server.py @@ -3,6 +3,8 @@ from jsonrpcserver import Result, Success, async_dispatch, method +MAX_BODY = 1_000_000 # bytes + app = FastAPI() @@ -13,10 +15,18 @@ async def ping() -> Result: @app.post("/") async def index(request: Request) -> Response: - if response := await async_dispatch((await request.body()).decode()): + # FastAPI has no limit on the body size, so read it in chunks and stop + # when it gets too big. + body = b"" + async for chunk in request.stream(): + body += chunk + if len(body) > MAX_BODY: + return Response(status_code=413) + # max_batch_size: see the Security page. + if response := await async_dispatch(body.decode(), max_batch_size=100): return Response(response, media_type="application/json") return Response(status_code=204) if __name__ == "__main__": - uvicorn.run(app, host="localhost", port=5000) + uvicorn.run(app, host="localhost", port=8000) diff --git a/docs/examples/flask_server.py b/docs/examples/flask_server.py index 6212f7a..210bbc8 100644 --- a/docs/examples/flask_server.py +++ b/docs/examples/flask_server.py @@ -3,6 +3,8 @@ from jsonrpcserver import Result, Success, dispatch, method app = Flask(__name__) +# Bigger requests get 413 Request Entity Too Large. +app.config["MAX_CONTENT_LENGTH"] = 1_000_000 @method @@ -12,10 +14,11 @@ def ping() -> Result: @app.post("/") def index() -> Response: - if response := dispatch(request.get_data(as_text=True)): + # max_batch_size: see the Security page. + if response := dispatch(request.get_data(as_text=True), max_batch_size=100): return Response(response, content_type="application/json") return Response(status=204) if __name__ == "__main__": - app.run(port=5000) + app.run(host="localhost", port=8000) diff --git a/docs/examples/http_server.py b/docs/examples/http_server.py index 92dc91e..b4b29e9 100644 --- a/docs/examples/http_server.py +++ b/docs/examples/http_server.py @@ -1,7 +1,10 @@ +import json from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer from jsonrpcserver import Result, Success, dispatch, method +MAX_BODY = 1_000_000 # bytes + @method def ping() -> Result: @@ -10,8 +13,26 @@ def ping() -> Result: class Handler(BaseHTTPRequestHandler): def do_POST(self) -> None: - length = int(self.headers["Content-Length"]) - response = dispatch(self.rfile.read(length).decode()) + length = self.headers.get("Content-Length", "") + if not length.isdecimal(): + self.send_error(411, "Content-Length required") + return + if int(length) > MAX_BODY: + self.send_error(413, "Request body too large") + return + try: + request = self.rfile.read(int(length)).decode("utf-8") + except UnicodeDecodeError: + response = json.dumps( + { + "jsonrpc": "2.0", + "error": {"code": -32700, "message": "Parse error"}, + "id": None, + } + ) + else: + # max_batch_size: see the Security page. + response = dispatch(request, max_batch_size=100) if response: body = response.encode() self.send_response(200) @@ -26,4 +47,4 @@ def do_POST(self) -> None: if __name__ == "__main__": - ThreadingHTTPServer(("localhost", 5000), Handler).serve_forever() + ThreadingHTTPServer(("localhost", 8000), Handler).serve_forever() diff --git a/docs/examples/serve.py b/docs/examples/quickstart.py similarity index 83% rename from docs/examples/serve.py rename to docs/examples/quickstart.py index db6a68d..520b935 100644 --- a/docs/examples/serve.py +++ b/docs/examples/quickstart.py @@ -7,4 +7,4 @@ def ping() -> Result: if __name__ == "__main__": - serve("localhost", 5000) + serve("localhost", 8000) diff --git a/docs/examples/sanic_server.py b/docs/examples/sanic_server.py index 5ef95f1..f4447d2 100644 --- a/docs/examples/sanic_server.py +++ b/docs/examples/sanic_server.py @@ -3,6 +3,8 @@ from jsonrpcserver import Result, Success, async_dispatch, method app = Sanic("jsonrpc") +# Bigger requests get 413 Request Entity Too Large. Sanic's default is 100 MB. +app.config.REQUEST_MAX_SIZE = 1_000_000 @method @@ -12,10 +14,11 @@ async def ping() -> Result: @app.post("/") async def index(request: Request) -> HTTPResponse: - if response := await async_dispatch(request.body.decode()): + # max_batch_size: see the Security page. + if response := await async_dispatch(request.body.decode(), max_batch_size=100): return HTTPResponse(response, content_type="application/json") return HTTPResponse(status=204) if __name__ == "__main__": - app.run(host="localhost", port=5000, single_process=True) + app.run(host="localhost", port=8000, single_process=True) diff --git a/docs/examples/socketio_server.py b/docs/examples/socketio_server.py index 86f14ba..b2f899a 100644 --- a/docs/examples/socketio_server.py +++ b/docs/examples/socketio_server.py @@ -4,7 +4,8 @@ from jsonrpcserver import Result, Success, dispatch, method app = Flask(__name__) -socketio = SocketIO(app) +# A bigger message is rejected. 1,000,000 bytes is also the default. +socketio = SocketIO(app, max_http_buffer_size=1_000_000) @method @@ -14,11 +15,12 @@ def ping() -> Result: @socketio.on("message") def handle_message(message: str) -> None: - if response := dispatch(message): + # max_batch_size: see the Security page. + if response := dispatch(message, max_batch_size=100): send(response) if __name__ == "__main__": # Werkzeug's server is for development. See the Flask-SocketIO docs for # production servers. - socketio.run(app, host="localhost", port=5000, allow_unsafe_werkzeug=True) + socketio.run(app, host="localhost", port=8000, allow_unsafe_werkzeug=True) diff --git a/docs/examples/tornado_server.py b/docs/examples/tornado_server.py index 006eba5..3395aaf 100644 --- a/docs/examples/tornado_server.py +++ b/docs/examples/tornado_server.py @@ -12,7 +12,9 @@ async def ping() -> Result: class MainHandler(web.RequestHandler): async def post(self) -> None: - if response := await async_dispatch(self.request.body.decode()): + # max_batch_size: see the Security page. + request = self.request.body.decode() + if response := await async_dispatch(request, max_batch_size=100): self.set_header("Content-Type", "application/json") self.write(response) else: @@ -21,7 +23,8 @@ async def post(self) -> None: async def main() -> None: app = web.Application([(r"/", MainHandler)]) - app.listen(5000, address="localhost") + # Tornado's default limit is 100 MB. + app.listen(8000, address="localhost", max_body_size=1_000_000) await asyncio.Event().wait() diff --git a/docs/examples/websockets_server.py b/docs/examples/websockets_server.py index d2b2bff..00a5c7c 100644 --- a/docs/examples/websockets_server.py +++ b/docs/examples/websockets_server.py @@ -14,12 +14,14 @@ async def handler(websocket: ServerConnection) -> None: async for message in websocket: request = message.decode() if isinstance(message, bytes) else message # Unlike HTTP, there's no need to answer a notification. - if response := await async_dispatch(request): + # max_batch_size: see the Security page. + if response := await async_dispatch(request, max_batch_size=100): await websocket.send(response) async def main() -> None: - async with serve(handler, "localhost", 5000) as server: + # A bigger message closes the connection. 1 MiB is also the default. + async with serve(handler, "localhost", 8000, max_size=1_000_000) as server: await server.serve_forever() diff --git a/docs/examples/werkzeug_server.py b/docs/examples/werkzeug_server.py index d456634..6bce829 100644 --- a/docs/examples/werkzeug_server.py +++ b/docs/examples/werkzeug_server.py @@ -4,17 +4,23 @@ from jsonrpcserver import Result, Success, dispatch, method +class JsonRpcRequest(Request): + # Bigger requests get 413 Request Entity Too Large. + max_content_length = 1_000_000 + + @method def ping() -> Result: return Success("pong") -@Request.application -def application(request: Request) -> Response: - if response := dispatch(request.get_data(as_text=True)): +@JsonRpcRequest.application +def application(request: JsonRpcRequest) -> Response: + # max_batch_size: see the Security page. + if response := dispatch(request.get_data(as_text=True), max_batch_size=100): return Response(response, content_type="application/json") return Response(status=204) if __name__ == "__main__": - run_simple("localhost", 5000, application) + run_simple("localhost", 8000, application) diff --git a/docs/examples/zeromq_async_server.py b/docs/examples/zeromq_async_server.py index d10f47d..35f93b2 100644 --- a/docs/examples/zeromq_async_server.py +++ b/docs/examples/zeromq_async_server.py @@ -13,10 +13,13 @@ async def ping() -> Result: async def main() -> None: socket = zmq.asyncio.Context().socket(zmq.REP) - socket.bind("tcp://*:5000") + # A bigger message disconnects the client. The default is no limit. + socket.setsockopt(zmq.MAXMSGSIZE, 1_000_000) + socket.bind("tcp://127.0.0.1:8000") while True: request = await socket.recv_string() - await socket.send_string(await async_dispatch(request)) + # max_batch_size: see the Security page. + await socket.send_string(await async_dispatch(request, max_batch_size=100)) if __name__ == "__main__": diff --git a/docs/examples/zeromq_server.py b/docs/examples/zeromq_server.py index 63deeff..e161f67 100644 --- a/docs/examples/zeromq_server.py +++ b/docs/examples/zeromq_server.py @@ -10,9 +10,11 @@ def ping() -> Result: if __name__ == "__main__": socket = zmq.Context().socket(zmq.REP) - socket.bind("tcp://*:5000") + # A bigger message disconnects the client. The default is no limit. + socket.setsockopt(zmq.MAXMSGSIZE, 1_000_000) + socket.bind("tcp://127.0.0.1:8000") while True: request = socket.recv_string() # A REP socket must reply to every request, so a notification gets an - # empty message. - socket.send_string(dispatch(request)) + # empty message. max_batch_size: see the Security page. + socket.send_string(dispatch(request, max_batch_size=100)) diff --git a/docs/faq.md b/docs/faq.md index faac95c..c09f244 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -1,25 +1,33 @@ +--- +description: Answers to common jsonrpcserver questions. Internal errors with no details, tracebacks, HTTP status codes, printing responses, threads, orjson and the old domains. +--- + # FAQ -## How do I turn off request validation? +## My method works, but the client gets "Internal error" with no details -Validating each request against the JSON-RPC schema takes about three -quarters of the dispatch time for a trivial method. If you know the requests -are valid, for example because your own code makes them, turn it off: +Either the method raised an exception, or it returned something other than +`Success(...)` or `Error(...)`. The most common case is a method written for +4.x that returns its result directly, such as `return "pong"`. Return +`Success("pong")` instead. See [Migration](migration.md). -```python -from jsonrpcserver import Result, Success, dispatch, method +The details are in your server's log, not in the response. From 5.0.10 that's +on purpose, so that exception messages don't leak to clients. If the log +shows nothing, see the next question. +## How do I see the traceback? -@method -def ping() -> Result: - return Success("pong") +jsonrpcserver logs it on the `jsonrpcserver` logger, but doesn't configure +logging. Configure it when your server starts: +```python +import logging -dispatch('{"jsonrpc": "2.0", "method": "ping", "id": 1}', validator=lambda _: None) +logging.basicConfig(level=logging.INFO) ``` -Without validation, a malformed request can give a less helpful error, but -`dispatch` still won't raise. +While developing, you can also pass `debug=True` to `dispatch` to get the +exception message in the response. See [Errors and logging](errors.md). ## Which HTTP status code should I send? @@ -30,7 +38,21 @@ def status(response: str) -> int: A JSON-RPC error is still a successful HTTP exchange, so send 200 with it. If `dispatch` gives an empty string, the request was a notification and there's -no body, so send 204 No Content. The built-in `serve()` does this. +no body, so send 204 No Content. The built-in `serve()` does this from +5.0.10. + +## Why does printing the result of dispatch_to_response fail? + +`print(dispatch_to_response(...))` raises `TypeError: not all arguments +converted during string formatting`. That's a bug in oslash, the library the +`Response` objects come from. Print `to_dict(response)` instead, or use +`dispatch_to_serializable`, which gives dicts. See +[Dispatch](dispatch.md#dispatch_to_response). + +## How do I get the response as a dict instead of a string? + +Use `dispatch_to_serializable`. See +[other return types](dispatch.md#other-return-types). ## How do I rename a method? @@ -39,20 +61,75 @@ Use `@method(name="new_name")`, or pass your own dict as the ## Can a method get the HTTP request, user or database connection? -Pass it as [context](dispatch.md#context). It becomes the first argument of -every method, and the client can't change it. - -## How do I get the response as a dict instead of a string? - -Use `dispatch_to_serializable`. See -[other return types](dispatch.md#other-return-types). +Pass it as `context`. It becomes the first argument of every method, and the +client can't change it. [Context](context.md) has examples for Flask, FastAPI +and Django. ## Why does my async method give an Internal error? You called it with `dispatch`. Async methods need [`async_dispatch`](async.md). +## Is it thread-safe? + +Yes, including on free-threaded Python. Register your methods at import time. +See [Threads](threads.md). + +## How do I turn off request validation? + +Pass `validator=lambda _: None`. It saves time, but bad requests then get odd +answers. See [Validation](validation.md#turning-it-off). + +## Can I use orjson or ujson? + +Yes, through `deserializer` and `serializer`. ujson's functions fit as they +are. [orjson](https://pypi.org/project/orjson/)'s `dumps` returns bytes, and +`dispatch` must return a string, so decode it: + + +```python +import orjson + +from jsonrpcserver import Result, Success, dispatch + + +def ping() -> Result: + return Success("pong") + + +def orjson_dumps(response: object) -> str: + return orjson.dumps(response).decode() + + +print( + dispatch( + '{"jsonrpc": "2.0", "method": "ping", "id": 1}', + {"ping": ping}, + deserializer=orjson.loads, + serializer=orjson_dumps, + ) +) +``` + +```text title="Output" +{"jsonrpc":"2.0","result":"pong","id":1} +``` + +orjson writes `NaN` and `Infinity` as `null` instead of raising, so a result +that contains them is sent with `null` in their place, not as an error. + ## Where did the examples on the wiki go? -They're on the [Examples](examples.md) page now, and CI runs each one against -a real server. +They're on the [Frameworks](examples.md) pages now, and CI runs each one +against a real server. + +## Where is the old documentation website? + +The project's old domains, jsonrpcserver.com and jsonrpcclient.com, now +belong to someone else. Ignore them and any links to them. The copy at +explodinglabs.com/jsonrpcserver/ is old and no longer updated, and so is the +one on Read the Docs. + +The official places are these docs, the [GitHub +repository](https://github.com/bensynapse/jsonrpcserver) and the [PyPI +project](https://pypi.org/project/jsonrpcserver/). diff --git a/docs/frameworks/aiohttp.md b/docs/frameworks/aiohttp.md new file mode 100644 index 0000000..a001271 --- /dev/null +++ b/docs/frameworks/aiohttp.md @@ -0,0 +1,38 @@ +--- +description: A JSON-RPC 2.0 server with aiohttp and jsonrpcserver's async_dispatch, with a request size limit and max_batch_size set. Tested in CI. +--- + +# aiohttp + +```python +--8<-- "docs/examples/aiohttp_server.py" +``` + +aiohttp refuses a body bigger than `client_max_size` with 413. Its default is +1 MiB, and the example sets it explicitly so it's easy to change. +`max_batch_size` limits how many requests one batch can hold. See +[Security](../security.md). + +To give methods the request, pass it as `context`: +`await async_dispatch(..., context=request)`. See [Context](../context.md). + +## Try it + +Save the example as `aiohttp_server.py`, install aiohttp (`pip install aiohttp`), and run it: + +```sh +python aiohttp_server.py +``` + +Then send it a request from another terminal: + +```sh +curl -s -H 'Content-Type: application/json' -d '{"jsonrpc": "2.0", "method": "ping", "id": 1}' http://localhost:8000/ +``` + +```text title="Output" +{"jsonrpc": "2.0", "result": "pong", "id": 1} +``` + +The [jsonrpcclient quickstart](https://bensynapse.github.io/jsonrpcclient/#quickstart) +sends the same request from Python. diff --git a/docs/frameworks/django.md b/docs/frameworks/django.md new file mode 100644 index 0000000..4075e4d --- /dev/null +++ b/docs/frameworks/django.md @@ -0,0 +1,48 @@ +--- +description: A JSON-RPC 2.0 endpoint in Django with jsonrpcserver, as a whole project in one file, with a request size limit and max_batch_size set. Tested in CI. +--- + +# Django + +A whole Django project in one file. In your project, the view goes in an app +and the URL pattern in its `urls.py`. + +```python +--8<-- "docs/examples/django_server.py" +``` + +Django refuses a body bigger than `DATA_UPLOAD_MAX_MEMORY_SIZE` with 400 Bad +Request when the view reads `request.body`. The default is 2.5 MB, and the +example sets it explicitly. `max_batch_size` limits how many requests one +batch can hold. See [Security](../security.md). + +The view is exempt from CSRF checks, because JSON-RPC clients don't send a +CSRF token. Use another way to authenticate them, such as a token in a header. +To give methods `request.user`, pass it in the context. +[Context](../context.md#django) has an example. + +`runserver` is Django's development server. For production, use a WSGI or +ASGI server, as the +[Django docs](https://docs.djangoproject.com/en/stable/howto/deployment/) +describe. + +## Try it + +Save the example as `django_server.py`, install Django (`pip install django`), and run it: + +```sh +python django_server.py +``` + +Then send it a request from another terminal: + +```sh +curl -s -H 'Content-Type: application/json' -d '{"jsonrpc": "2.0", "method": "ping", "id": 1}' http://localhost:8000/ +``` + +```text title="Output" +{"jsonrpc": "2.0", "result": "pong", "id": 1} +``` + +The [jsonrpcclient quickstart](https://bensynapse.github.io/jsonrpcclient/#quickstart) +sends the same request from Python. diff --git a/docs/frameworks/fastapi.md b/docs/frameworks/fastapi.md new file mode 100644 index 0000000..503b138 --- /dev/null +++ b/docs/frameworks/fastapi.md @@ -0,0 +1,44 @@ +--- +description: A JSON-RPC 2.0 endpoint in FastAPI with jsonrpcserver's async_dispatch, with a request size limit and max_batch_size set. Tested in CI. +--- + +# FastAPI + +```python +--8<-- "docs/examples/fastapi_server.py" +``` + +FastAPI and Starlette have no limit on the body size, so the endpoint reads +the body in chunks and answers 413 once it's too big. Many deployments also +set a limit in the reverse proxy in front, such as nginx's +`client_max_body_size`. `max_batch_size` limits how many requests one batch +can hold. See [Security](../security.md). + +The methods are `async`, and the endpoint uses `async_dispatch`. Plain methods +work too, but they run on the event loop, so a slow one holds up other +requests. See [Async](../async.md). + +FastAPI's dependency injection doesn't reach into methods. Resolve what they +need in the endpoint and pass it as `context`. +[Context](../context.md#fastapi) has an example. + +## Try it + +Save the example as `fastapi_server.py`, install FastAPI and Uvicorn (`pip install fastapi uvicorn`), and run it: + +```sh +python fastapi_server.py +``` + +Then send it a request from another terminal: + +```sh +curl -s -H 'Content-Type: application/json' -d '{"jsonrpc": "2.0", "method": "ping", "id": 1}' http://localhost:8000/ +``` + +```text title="Output" +{"jsonrpc": "2.0", "result": "pong", "id": 1} +``` + +The [jsonrpcclient quickstart](https://bensynapse.github.io/jsonrpcclient/#quickstart) +sends the same request from Python. diff --git a/docs/frameworks/flask.md b/docs/frameworks/flask.md new file mode 100644 index 0000000..f6bab73 --- /dev/null +++ b/docs/frameworks/flask.md @@ -0,0 +1,41 @@ +--- +description: A JSON-RPC 2.0 server with Flask and jsonrpcserver, with a request size limit and max_batch_size set. Tested in CI. +--- + +# Flask + +```python +--8<-- "docs/examples/flask_server.py" +``` + +`MAX_CONTENT_LENGTH` makes Flask answer a bigger body with 413 before it's +read. Flask has no limit by default. `max_batch_size` limits how many +requests one batch can hold. See [Security](../security.md). + +To give methods the request or the logged-in user, pass `context`. +[Context](../context.md#flask) has a Flask example. + +`app.run` starts Flask's development server. For production, run the app with +a WSGI server such as Gunicorn, as the +[Flask docs](https://flask.palletsprojects.com/en/stable/deploying/) describe. + +## Try it + +Save the example as `flask_server.py`, install Flask (`pip install flask`), and run it: + +```sh +python flask_server.py +``` + +Then send it a request from another terminal: + +```sh +curl -s -H 'Content-Type: application/json' -d '{"jsonrpc": "2.0", "method": "ping", "id": 1}' http://localhost:8000/ +``` + +```text title="Output" +{"jsonrpc": "2.0", "result": "pong", "id": 1} +``` + +The [jsonrpcclient quickstart](https://bensynapse.github.io/jsonrpcclient/#quickstart) +sends the same request from Python. diff --git a/docs/frameworks/http-server.md b/docs/frameworks/http-server.md new file mode 100644 index 0000000..5dc8de2 --- /dev/null +++ b/docs/frameworks/http-server.md @@ -0,0 +1,70 @@ +--- +description: A JSON-RPC 2.0 server with Python's built-in http.server and jsonrpcserver, with no other dependencies. Plus serve(), the development server that comes with jsonrpcserver. +--- + +# http.server and serve() + +## http.server + +Python's built-in HTTP server, with no other dependencies. It reads the body +itself, so it also has to check the `Content-Length` header, refuse a body +that's too big and handle bytes that aren't UTF-8: + +```python +--8<-- "docs/examples/http_server.py" +``` + +A missing `Content-Length` gets 411, a body over the limit gets 413, and a +body that isn't UTF-8 gets a -32700 "Parse error". http.server is fine for +small internal tools. For anything public, use a framework or put a +production web server in front. + +## serve() + +jsonrpcserver also has a small built-in server, `serve()`. It's for trying +things out, not for production: + +```python +--8<-- "docs/examples/quickstart.py" +``` + +It answers POST requests on any path, sends 204 for notifications, and +handles each request in its own thread. It also handles a missing +`Content-Length` (411) and a body that isn't UTF-8 (-32700). + +Know its limits before you use it: + +- It listens on every network interface unless you pass a host, as the + example does with `"localhost"`. With `serve()` and no arguments, anyone + who can reach your machine on port 5000 can call your methods. +- It has no TLS, no authentication and no limit on the body size, and it + doesn't set `max_batch_size`. +- It says where it's listening when it starts (new in 5.0.10). Each request + is logged on the `jsonrpcserver.server` logger at INFO level, so + `logging.basicConfig(level=logging.INFO)` shows them. + +!!! info "Changed in 5.0.10" + In 5.0.9, `serve()` answers a notification with 200 and an empty body + instead of 204, and prints nothing when it starts. It drops the + connection for a missing `Content-Length` or a body that isn't UTF-8. + +## Try it + +Save the serve() example as `quickstart.py` and run it: + +```sh +python quickstart.py +``` + +Then send it a request from another terminal: + +```sh +curl -s -H 'Content-Type: application/json' -d '{"jsonrpc": "2.0", "method": "ping", "id": 1}' http://localhost:8000/ +``` + +```text title="Output" +{"jsonrpc": "2.0", "result": "pong", "id": 1} +``` + +The [jsonrpcclient quickstart](https://bensynapse.github.io/jsonrpcclient/#quickstart) +sends the same request from Python. diff --git a/docs/frameworks/sanic.md b/docs/frameworks/sanic.md new file mode 100644 index 0000000..5802ea4 --- /dev/null +++ b/docs/frameworks/sanic.md @@ -0,0 +1,40 @@ +--- +description: A JSON-RPC 2.0 server with Sanic and jsonrpcserver's async_dispatch, with a request size limit and max_batch_size set. Tested in CI. +--- + +# Sanic + +```python +--8<-- "docs/examples/sanic_server.py" +``` + +Sanic refuses a body bigger than `REQUEST_MAX_SIZE` with 413. Its default is +100 MB, so the example sets a smaller one. `max_batch_size` limits how many +requests one batch can hold. See [Security](../security.md). + +To give methods the request, pass it as `context`: +`await async_dispatch(..., context=request)`. See [Context](../context.md). + +`single_process=True` keeps the example simple. Sanic's own docs cover +running it with workers in production. + +## Try it + +Save the example as `sanic_server.py`, install Sanic (`pip install sanic`), and run it: + +```sh +python sanic_server.py +``` + +Then send it a request from another terminal: + +```sh +curl -s -H 'Content-Type: application/json' -d '{"jsonrpc": "2.0", "method": "ping", "id": 1}' http://localhost:8000/ +``` + +```text title="Output" +{"jsonrpc": "2.0", "result": "pong", "id": 1} +``` + +The [jsonrpcclient quickstart](https://bensynapse.github.io/jsonrpcclient/#quickstart) +sends the same request from Python. diff --git a/docs/frameworks/socketio.md b/docs/frameworks/socketio.md new file mode 100644 index 0000000..0364a2e --- /dev/null +++ b/docs/frameworks/socketio.md @@ -0,0 +1,28 @@ +--- +description: A JSON-RPC 2.0 server over Socket.IO with Flask-SocketIO and jsonrpcserver, with a message size limit and max_batch_size set. Tested in CI. +--- + +# Socket.IO + +Using [Flask-SocketIO](https://flask-socketio.readthedocs.io/). Requests +arrive as `message` events, and responses go back the same way. + +```python +--8<-- "docs/examples/socketio_server.py" +``` + +A notification gets nothing back. Flask-SocketIO refuses a message bigger +than `max_http_buffer_size`. Its default is 1,000,000 bytes, and the example +sets it explicitly. `max_batch_size` limits how many requests one batch can +hold. See [Security](../security.md). + +The example runs on Werkzeug's development server. Flask-SocketIO's docs +cover the production servers it supports. + +## Try it + +Install Flask-SocketIO (`pip install flask-socketio`) and run the example. +Any Socket.IO client can call it: connect to `http://localhost:8000`, emit a +`message` event with the request string, and wait for a `message` event with +the response. With [python-socketio](https://python-socketio.readthedocs.io/), +that's `SimpleClient.connect`, `emit("message", request)` and `receive()`. diff --git a/docs/frameworks/tornado.md b/docs/frameworks/tornado.md new file mode 100644 index 0000000..13c66a0 --- /dev/null +++ b/docs/frameworks/tornado.md @@ -0,0 +1,37 @@ +--- +description: A JSON-RPC 2.0 server with Tornado and jsonrpcserver's async_dispatch, with a request size limit and max_batch_size set. Tested in CI. +--- + +# Tornado + +```python +--8<-- "docs/examples/tornado_server.py" +``` + +Tornado refuses a body bigger than `max_body_size` with 400. Its default is +100 MB, so the example passes a smaller one to `listen`. `max_batch_size` +limits how many requests one batch can hold. See [Security](../security.md). + +To give methods the request, pass `self.request` as `context`. See +[Context](../context.md). + +## Try it + +Save the example as `tornado_server.py`, install Tornado (`pip install tornado`), and run it: + +```sh +python tornado_server.py +``` + +Then send it a request from another terminal: + +```sh +curl -s -H 'Content-Type: application/json' -d '{"jsonrpc": "2.0", "method": "ping", "id": 1}' http://localhost:8000/ +``` + +```text title="Output" +{"jsonrpc": "2.0", "result": "pong", "id": 1} +``` + +The [jsonrpcclient quickstart](https://bensynapse.github.io/jsonrpcclient/#quickstart) +sends the same request from Python. diff --git a/docs/frameworks/websockets.md b/docs/frameworks/websockets.md new file mode 100644 index 0000000..558ad99 --- /dev/null +++ b/docs/frameworks/websockets.md @@ -0,0 +1,38 @@ +--- +description: A JSON-RPC 2.0 server over WebSocket with the websockets library and jsonrpcserver's async_dispatch, with a message size limit and max_batch_size set. Tested in CI. +--- + +# websockets + +Uses the `websockets.asyncio` server from +[websockets](https://websockets.readthedocs.io/) 13 and later. + +```python +--8<-- "docs/examples/websockets_server.py" +``` + +Unlike HTTP, a WebSocket doesn't need an answer to every message, so a +notification gets nothing back. websockets closes the connection if a message +is bigger than `max_size`. Its default is 1 MiB, and the example sets it +explicitly. `max_batch_size` limits how many requests one batch can hold. See +[Security](../security.md). + +Requests on one connection are handled one at a time, in the order they +arrive. To answer them concurrently, start a task for each message. + +## Try it + +Save the example as `websockets_server.py`, install websockets +(`pip install websockets`), and run it: + +```sh +python websockets_server.py +``` + +websockets comes with an interactive client. Run +`python -m websockets ws://localhost:8000/` in another terminal and type a +request, such as `{"jsonrpc": "2.0", "method": "ping", "id": 1}`. + +From Python, jsonrpcclient's +[websockets example](https://bensynapse.github.io/jsonrpcclient/transports/websockets/) +calls this server. diff --git a/docs/frameworks/werkzeug.md b/docs/frameworks/werkzeug.md new file mode 100644 index 0000000..e7e50c0 --- /dev/null +++ b/docs/frameworks/werkzeug.md @@ -0,0 +1,43 @@ +--- +description: A JSON-RPC 2.0 server with Werkzeug and jsonrpcserver, with a request size limit and max_batch_size set. Tested in CI. +--- + +# Werkzeug + +[Werkzeug](https://werkzeug.palletsprojects.com/) is the WSGI toolkit under +Flask. Use it on its own for a small WSGI app: + +```python +--8<-- "docs/examples/werkzeug_server.py" +``` + +Setting `max_content_length` on a `Request` subclass makes `get_data` refuse +a bigger body with 413. `max_batch_size` limits how many requests one batch +can hold. See [Security](../security.md). + +To give methods the request, pass it as `context`: +`dispatch(..., context=request)`. See [Context](../context.md). + +`run_simple` is Werkzeug's development server. For production, use a WSGI +server such as Gunicorn. + +## Try it + +Save the example as `werkzeug_server.py`, install Werkzeug (`pip install werkzeug`), and run it: + +```sh +python werkzeug_server.py +``` + +Then send it a request from another terminal: + +```sh +curl -s -H 'Content-Type: application/json' -d '{"jsonrpc": "2.0", "method": "ping", "id": 1}' http://localhost:8000/ +``` + +```text title="Output" +{"jsonrpc": "2.0", "result": "pong", "id": 1} +``` + +The [jsonrpcclient quickstart](https://bensynapse.github.io/jsonrpcclient/#quickstart) +sends the same request from Python. diff --git a/docs/frameworks/zeromq.md b/docs/frameworks/zeromq.md new file mode 100644 index 0000000..95173c9 --- /dev/null +++ b/docs/frameworks/zeromq.md @@ -0,0 +1,43 @@ +--- +description: A JSON-RPC 2.0 server over ZeroMQ with pyzmq and jsonrpcserver, sync and asyncio, with a message size limit and max_batch_size set. Tested in CI. +--- + +# ZeroMQ + +Using [pyzmq](https://pyzmq.readthedocs.io/) with a REP socket, which +answers one request at a time. + +## Sync + +```python +--8<-- "docs/examples/zeromq_server.py" +``` + +## asyncio + +With pyzmq's `zmq.asyncio`: + +```python +--8<-- "docs/examples/zeromq_async_server.py" +``` + +## Notes + +A REP socket must send a reply for every message it receives, before it can +receive the next one. So a notification gets an empty message back, which +the client should ignore. + +`MAXMSGSIZE` makes ZeroMQ drop a client that sends a bigger message. There's +no limit by default. `max_batch_size` limits how many requests one batch can +hold. See [Security](../security.md). + +The examples bind to `127.0.0.1`. `tcp://*:8000` would listen on every +network interface, and ZeroMQ has no authentication unless you set up one of +its security mechanisms, such as CURVE. + +## Try it + +Install pyzmq (`pip install pyzmq`) and run one of the examples. From Python, +jsonrpcclient's +[ZeroMQ example](https://bensynapse.github.io/jsonrpcclient/transports/zeromq/) +calls this server. diff --git a/docs/index.md b/docs/index.md index 1fc433c..776d6f3 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,65 +1,108 @@ - +--- +title: Process incoming JSON-RPC 2.0 requests in Python +description: jsonrpcserver turns JSON-RPC 2.0 requests into calls to your Python functions. It works with any framework or transport, sync or async, and is typed and thread-safe. +--- # jsonrpcserver -![jsonrpcserver](assets/logo.png) - -_Process incoming JSON-RPC requests in Python._ +_Process incoming JSON-RPC 2.0 requests in Python._ jsonrpcserver takes a [JSON-RPC 2.0](https://www.jsonrpc.org/specification) -request string, calls your function and gives you the response string. It -doesn't listen on a port itself, so it works with any framework or transport: -HTTP, websockets, ZeroMQ, message queues and so on. +request, calls your Python function and gives you the response to send back. +It leaves the networking to you, so it works with any framework or transport: +Flask, Django, FastAPI, aiohttp, websockets, ZeroMQ and more. It runs sync and +async methods, ships type hints, and is safe to use from several threads. It +supports Python 3.8 to 3.14, including free-threaded 3.14t. -## Installation +## Install ```sh pip install jsonrpcserver ``` -It supports Python 3.8 and later. - -## Quick start +## Quickstart -Write a method: +Save this as `server.py`: ```python -from jsonrpcserver import Result, Success, dispatch, method +--8<-- "docs/examples/quickstart.py" +``` + +Run it with `python server.py` and leave it running. `serve()` is a small +server for trying things out. In production you'd use your web framework +instead, as in the [framework examples](examples.md). +In another terminal, send it a request with curl: -@method -def ping() -> Result: - return Success("pong") +```sh +curl -s -H 'Content-Type: application/json' -d '{"jsonrpc": "2.0", "method": "ping", "id": 1}' http://localhost:8000/ +``` + +```text title="Output" +{"jsonrpc": "2.0", "result": "pong", "id": 1} ``` -Then pass the request to `dispatch`: +Or call it from Python with +[jsonrpcclient](https://bensynapse.github.io/jsonrpcclient/), the companion +library for the client side (`pip install jsonrpcclient requests`): + + ```python +import requests +from jsonrpcclient import Error, Ok, parse, request + +url = "http://localhost:8000/" +response = requests.post(url, json=request("ping"), timeout=10) +response.raise_for_status() +parsed = parse(response.json()) +if isinstance(parsed, Ok): + print(parsed.result) +elif isinstance(parsed, Error): + print("Error:", parsed.message) +``` + +```text title="Output" +pong +``` + +### What happens inside + +The server passes each request body to `dispatch`, which calls your method and +gives back the response as a string: + +```pycon +>>> from jsonrpcserver import Result, Success, dispatch, method +>>> @method +... def ping() -> Result: +... return Success("pong") >>> dispatch('{"jsonrpc": "2.0", "method": "ping", "id": 1}') '{"jsonrpc": "2.0", "result": "pong", "id": 1}' ``` -Send that string back to the client. For a notification (a request without an -`id`), `dispatch` gives an empty string, meaning there's nothing to send: +That's all there is to it in your own framework: pass the request body to +`dispatch` and send back what it gives you. A notification (a request with no +`id`) gives an empty string, which means there's nothing to send: -```python +```pycon >>> dispatch('{"jsonrpc": "2.0", "method": "ping"}') '' ``` -## Next - -- [Methods](methods.md): writing methods, parameters and errors. -- [Dispatch](dispatch.md): the options `dispatch` takes. -- [Async](async.md): `async_dispatch` for asyncio servers. -- [Examples](examples.md): Flask, FastAPI, Django, aiohttp, websockets, - ZeroMQ and more. -- [Security](security.md): what to set before you expose a server. -- [FAQ](faq.md) - -jsonrpcclient, the companion library for the other end of the connection, is -at [bensynapse/jsonrpcclient](https://github.com/bensynapse/jsonrpcclient). +Over HTTP, answer that with status 204 and no body. + +## Where next + +- [Methods](methods.md) and [Dispatch](dispatch.md): writing methods, and the + options `dispatch` takes. +- [Frameworks](examples.md): complete, tested examples for http.server, + Flask, Werkzeug, Django, FastAPI, aiohttp, Sanic, Tornado, websockets, ZeroMQ + and Socket.IO. +- [Security](security.md): what to set before you put a server on the + internet. +- [Errors and logging](errors.md): every error the client can get, and where + the details go. +- [API reference](reference.md): every function and class, with signatures. +- [Migrating from 4.x](migration.md): methods must now return `Success(...)`. +- [jsonrpcclient](https://bensynapse.github.io/jsonrpcclient/): the same idea + for the client side. diff --git a/docs/license.md b/docs/license.md new file mode 100644 index 0000000..1a2de9d --- /dev/null +++ b/docs/license.md @@ -0,0 +1,12 @@ +--- +description: jsonrpcserver is released under the MIT License. It was created by Beau Barker and is maintained by Synapse Research. +--- + +# License + +jsonrpcserver is released under the MIT License. It was created by Beau +Barker and is maintained by [Synapse Research](https://synapsereality.io). + +```text +--8<-- "LICENSE" +``` diff --git a/docs/methods.md b/docs/methods.md index 2b64359..42e3941 100644 --- a/docs/methods.md +++ b/docs/methods.md @@ -1,7 +1,11 @@ +--- +description: Write JSON-RPC methods with jsonrpcserver. The @method decorator, renaming, returning Success or Error, raising JsonRpcError, and how parameters are checked. +--- + # Methods Methods are the functions a JSON-RPC request can call. To write one, decorate -a function with `@method`: +a function with `@method`, and return `Success` with the result: ```python from jsonrpcserver import Error, InvalidParams, Result, Success, dispatch, method @@ -24,13 +28,18 @@ def add_numbers(a: int, b: int) -> Result: return Success(a + b) ``` -```python +```pycon >>> dispatch('{"jsonrpc": "2.0", "method": "sum", "params": [2, 3], "id": 1}') '{"jsonrpc": "2.0", "result": 5, "id": 1}' ``` -If you'd rather not use a decorator, pass the methods to `dispatch` yourself. -See [methods](dispatch.md#methods) on the Dispatch page. +A later `@method` with the same name replaces the earlier one, without a +warning. If you'd rather not use a decorator, pass the methods to `dispatch` +yourself as a dict. See [methods](dispatch.md#methods) on the Dispatch page. + +!!! info "New in 5.0.10" + A name that starts with `rpc.` gives a `UserWarning`, because the + JSON-RPC spec reserves those names. The method is still added. ## Results @@ -38,6 +47,11 @@ A method returns `Success` or `Error`. They are the `result` and `error` parts of a [JSON-RPC response](https://www.jsonrpc.org/specification#response_object). jsonrpcserver adds the `jsonrpc` and `id` parts. +!!! warning "Return `Success(value)`, not the value" + In 4.x a method returned its result directly. In 5.x, `return "pong"` + sends the client a -32603 "Internal error", with no details. The log + says what went wrong. See [Migration](migration.md). + `Success` takes the result value. If there's nothing to return, call it with no argument and the result is `null`: @@ -47,13 +61,12 @@ def log(message: str) -> Result: return Success() ``` -```python +```pycon >>> dispatch('{"jsonrpc": "2.0", "method": "log", "params": ["hi"], "id": 1}') '{"jsonrpc": "2.0", "result": null, "id": 1}' ``` -`Error` takes a code, a message and, optionally, some data. The code must be -an integer and the message a string. +`Error` takes a code, a message and, optionally, some data: ```python @method @@ -63,11 +76,20 @@ def divide(a: float, b: float) -> Result: return Success(a / b) ``` -```python +```pycon >>> dispatch('{"jsonrpc": "2.0", "method": "divide", "params": [1, 0], "id": 1}') '{"jsonrpc": "2.0", "error": {"code": 1, "message": "Can\'t divide by zero", "data": {"a": 1}}, "id": 1}' ``` +The spec says the code must be an integer and the message should be a string. +The spec reserves the codes from -32768 to -32000 for its own errors, so pick +other numbers for yours. + +!!! info "New in 5.0.10" + `Error` and `JsonRpcError` give a `UserWarning` if the code isn't an + integer or the message isn't a string. The error is still sent as given, + so existing code keeps working, but some clients can't read it. + You can also raise `JsonRpcError`, which takes the same arguments as `Error`. That's handy deep inside other functions: @@ -86,13 +108,14 @@ def square_root(number: float) -> Result: return Success(number**0.5) ``` -```python +```pycon >>> dispatch('{"jsonrpc": "2.0", "method": "square_root", "params": [-4], "id": 1}') '{"jsonrpc": "2.0", "error": {"code": 2, "message": "Must be positive"}, "id": 1}' ``` Any other exception gives a -32603 "Internal error" response. The exception -isn't sent to the client, but it is logged. See [Security](security.md). +isn't sent to the client, but it is logged. See +[Errors and logging](errors.md). ## Parameters @@ -105,22 +128,29 @@ def hello(name: str) -> Result: return Success("Hello " + name) ``` -```python +```pycon >>> dispatch('{"jsonrpc": "2.0", "method": "hello", "params": ["Beau"], "id": 1}') '{"jsonrpc": "2.0", "result": "Hello Beau", "id": 1}' >>> dispatch('{"jsonrpc": "2.0", "method": "hello", "params": {"name": "Beau"}, "id": 1}') '{"jsonrpc": "2.0", "result": "Hello Beau", "id": 1}' ``` -If they don't fit, the client gets -32602 "Invalid params": +If they don't fit, the client gets -32602 "Invalid params", with Python's +explanation in `data`: -```python +```pycon >>> dispatch('{"jsonrpc": "2.0", "method": "hello", "params": [], "id": 1}') '{"jsonrpc": "2.0", "error": {"code": -32602, "message": "Invalid params", "data": "missing a required argument: \'name\'"}, "id": 1}' ``` +A request's `params` is either a list or an object, so a method can't get some +arguments by position and others by name. That's a JSON-RPC rule. + jsonrpcserver doesn't check the types of the values. A method gets whatever -JSON gave: `str`, `int`, `float`, `bool`, `None`, `list` or `dict`. +JSON gave: `str`, `int`, `float`, `bool`, `None`, `list` or `dict`. The client +also chooses which of your parameters to fill, including ones with default +values. [Security](security.md#every-parameter-is-up-to-the-client) explains +why that matters. ## Invalid params @@ -135,22 +165,18 @@ def rate(stars: int) -> Result: return Success() ``` -```python +```pycon >>> dispatch('{"jsonrpc": "2.0", "method": "rate", "params": [6], "id": 1}') '{"jsonrpc": "2.0", "error": {"code": -32602, "message": "Invalid params", "data": "Stars must be 1 to 5"}, "id": 1}' ``` -## Type checking +## Async methods -`@method` keeps the function's signature, so mypy and pyright check calls to -your methods as usual. +Methods can be `async def` functions too. Call them with `async_dispatch` +instead of `dispatch`. See [Async](async.md). -`Result` comes from the oslash library, which has type hints but no `py.typed` -marker. pyright reads them anyway. mypy treats `Result` as `Any` unless you add -this to `pyproject.toml`: +## Type checking -```toml -[[tool.mypy.overrides]] -module = ["oslash", "oslash.*"] -follow_untyped_imports = true -``` +`@method` keeps the function's signature, so mypy and pyright check your +methods and the calls to them. [Typing](typing.md) has the details, including +one setting mypy needs. diff --git a/docs/migration.md b/docs/migration.md new file mode 100644 index 0000000..ad78187 --- /dev/null +++ b/docs/migration.md @@ -0,0 +1,167 @@ +--- +description: Upgrade jsonrpcserver from 4.x to 5.x, and from 5.0.9 to 5.0.10. Side-by-side examples, removed options, and the plain return value that silently becomes an Internal error. +--- + +# Migration + +## From 4.x to 5.x + +Version 5 changed how methods report their result. Most other code needs only +small changes. + +!!! danger "Old methods fail with no details" + In 4.x a method returned its result directly. In 5.x it must return + `Success(result)`. A 4.x method such as + + + ```python + @method + def ping(): + return "pong" + ``` + + still runs, but the client gets `{"code": -32603, "message": "Internal + error"}` with no details. From 5.0.10 the log says what's wrong: + + ```text + Method 'ping' returned 'pong', which is not a Result, so the client got an Internal error. Return Success(value) or Error(code, message). ... + ``` + + If you don't see that line, configure logging (see + [Errors and logging](errors.md#logging)). Then search your code for + `return` statements in methods. mypy and pyright catch them too, once + methods are annotated `-> Result` (see [Typing](typing.md)). + +### A method, before and after + +4.x: + + +```python +# jsonrpcserver 4.x. This doesn't work on 5.x. +from jsonrpcserver import dispatch, method +from jsonrpcserver.exceptions import ApiError, InvalidParamsError + + +@method +def divide(a, b): + if not isinstance(b, (int, float)): + raise InvalidParamsError("b must be a number") + if b == 0: + raise ApiError("Can't divide by zero", code=1) + return a / b + + +response = dispatch(request_body) +if response.wanted: + send(str(response), status=response.http_status) +``` + +5.x: + +```python +from jsonrpcserver import Error, InvalidParams, Result, Success, dispatch, method + + +@method +def divide(a: float, b: float) -> Result: + if not isinstance(b, (int, float)): + return InvalidParams("b must be a number") + if b == 0: + return Error(1, "Can't divide by zero") + return Success(a / b) + + +response = dispatch('{"jsonrpc": "2.0", "method": "divide", "params": [1, 0], "id": 1}') +print(response, 200 if response else 204) +``` + +```text title="Output" +{"jsonrpc": "2.0", "error": {"code": 1, "message": "Can't divide by zero"}, "id": 1} 200 +``` + +### What changed + +| 4.x | 5.x | +|---|---| +| `return value` | `return Success(value)` | +| `raise ApiError(message, code=1, data=...)` | `return Error(code, message, data)`, or `raise JsonRpcError(code, message, data)`. Note the order: code first. | +| `raise InvalidParamsError(...)` | `return InvalidParams(data)` | +| `raise MethodNotFoundError` | there's no equivalent. jsonrpcserver sends "Method not found" itself | +| `dispatch` returns a `Response` object | `dispatch` returns a string. `dispatch_to_serializable` gives a dict | +| `str(response)` | `response` is already the string | +| `response.wanted` | `if response:`, since a notification gives `""` | +| `response.http_status` | `200 if response else 204`. Errors are sent with 200 too | +| `methods = Methods(ping, add)`, `methods.add(...)` | a plain dict, `{"ping": ping, "add": add}`, or `@method` | +| `dispatch(..., serialize=..., deserialize=...)` | `serializer=` and `deserializer=` | +| `convert_camel_case=True` | removed. Name your methods and parameters as clients call them | +| `basic_logging=True`, `trim_log_values=True` | removed. Configure the `jsonrpcserver` logger yourself | +| a `.jsonrpcserverrc` config file | removed. Pass options to `dispatch` | +| `debug=True` | still there. In 5.0.10 it controls whether exception messages reach the client | + +Code written for 4.x that 5.x can't run gives clear errors in most cases. The +removed keywords raise `TypeError`, and `response.wanted` raises +`AttributeError: 'str' object has no attribute 'wanted'`. The plain return +value above is the one that fails quietly, and `str(response)` still works but +is no longer needed. + +The 4.x documentation is no longer online. The [changelog](changelog.md) +lists every 4.x change. + +## From 5.0.9 to 5.0.10 + +Most code needs no change. These are the differences you might notice. + +**Exception messages are no longer sent.** A method that raises an exception +it doesn't catch gives a -32603 "Internal error" with no `data`. Clients that +read `error.data` for those errors get nothing now. The exception is logged. +Pass `debug=True` in development to get the message back in the response. See +[Security](security.md). + +**Custom validators see one request at a time.** In a batch, the `validator` +is called once for each request, with that request's dict. In 5.0.9 it was +called once with the whole list. A validator that enforced a rule about the +whole batch, such as a size limit, silently stops doing it. Use +`max_batch_size` instead. See [Validation](validation.md). + +**Batches are handled per request.** A batch that mixes valid and invalid +requests used to get one "Invalid request" for the whole batch. Now each +invalid request gets its own error, and the valid ones run. See +[Notifications and batches](batches.md#invalid-members). + +**NaN and Infinity give an error.** A result that contains `NaN`, `Infinity` +or `-Infinity` now gives an Internal error, because they aren't valid JSON. To +send them anyway, pass `serializer=json.dumps`. + +**A result that can't be serialized gives an error.** For example a +`datetime`. In 5.0.9 `dispatch` raised `TypeError`. Now that response becomes +an Internal error, the error is logged, and the rest of a batch is sent. + +**New warnings.** `Error` and `JsonRpcError` warn when the code isn't an +integer or the message isn't a string, and `@method` warns about names that +start with `rpc.`. The responses are the same as before. If your tests turn +warnings into errors, fix the code or the names. See +[Errors and logging](errors.md#spec-warnings). + +**Deprecated names.** In `jsonrpcserver.response`, `serialize_error`, +`serialize_success` and `to_serializable_one` give a `DeprecationWarning`. Use +`to_error_dict`, `to_success_dict` and `to_dict`. `ResponseType` is kept, but +use `Response`. They will be removed in 6.0. + +**New loggers and log lines.** A serializer failure is logged on +`jsonrpcserver.main`, and `serve()` logs where it's listening. A method that +returns a plain value is logged with a hint instead of a traceback. See +[Errors and logging](errors.md#logging). + +**Plain methods work with `async_dispatch`.** In 5.0.9 they gave an Internal +error. + +**`serve()` sends 204 for a notification**, instead of 200 with an empty +body, and answers bad requests instead of dropping the connection. + +**New features you can use:** `max_batch_size` and `debug` on every dispatch +function, `jsonrpcserver.__version__`, and type checking that sees through +`@method` (see [Typing](typing.md)). + +**Python 3.8 or later.** 5.0.10's package metadata says so, so older Pythons +keep installing 5.0.9. diff --git a/docs/reference.md b/docs/reference.md new file mode 100644 index 0000000..4460c48 --- /dev/null +++ b/docs/reference.md @@ -0,0 +1,116 @@ +--- +description: API reference for jsonrpcserver, generated from the source code. Every public function and class, with signatures, parameters, return values and exceptions. +--- + +# API reference + +This page is generated from the docstrings in the source code, so it matches +the code on the main branch. + +Everything in the first five sections can be imported from the package +itself, for example `from jsonrpcserver import Success, dispatch, method`. +The two `dispatch_to_json` entries are the exception: they're the functions +behind `dispatch` and `async_dispatch`, and live in `jsonrpcserver.main` and +`jsonrpcserver.async_main`. The other public names are in `jsonrpcserver.response`, +`jsonrpcserver.result`, `jsonrpcserver.codes`, `jsonrpcserver.methods` and +`jsonrpcserver.sentinels`. Anything not listed here is internal and can change +in any release. + +In the signatures, `context=NOCONTEXT` means "no context": methods get only +the request's params. `data=NODATA` means the error has no `data` member. + +## Methods and results + +::: jsonrpcserver.method + +::: jsonrpcserver.Success + +::: jsonrpcserver.Error + +::: jsonrpcserver.InvalidParams + +::: jsonrpcserver.JsonRpcError + +::: jsonrpcserver.Result + +## Dispatch + +::: jsonrpcserver.dispatch + +::: jsonrpcserver.main.dispatch_to_json + options: + show_root_full_path: true + +::: jsonrpcserver.dispatch_to_serializable + +::: jsonrpcserver.dispatch_to_response + +## Async dispatch + +::: jsonrpcserver.async_dispatch + +::: jsonrpcserver.async_main.dispatch_to_json + options: + show_root_full_path: true + +::: jsonrpcserver.async_dispatch_to_serializable + +::: jsonrpcserver.async_dispatch_to_response + +## Development server + +::: jsonrpcserver.serve + +## Version + +::: jsonrpcserver.__version__ + +## Responses + +::: jsonrpcserver.response.Response + +::: jsonrpcserver.response.SuccessResponse + +::: jsonrpcserver.response.ErrorResponse + +::: jsonrpcserver.response.to_dict + +::: jsonrpcserver.response.to_success_dict + +::: jsonrpcserver.response.to_error_dict + +::: jsonrpcserver.response.to_serializable + +## Results + +::: jsonrpcserver.result.SuccessResult + +::: jsonrpcserver.result.ErrorResult + +## Error codes + +::: jsonrpcserver.codes + options: + show_root_heading: false + show_root_toc_entry: false + +## Other names + +::: jsonrpcserver.methods.global_methods + +::: jsonrpcserver.sentinels.NODATA + +::: jsonrpcserver.sentinels.NOCONTEXT + +## Deprecated + +These still work in 5.x, but give a `DeprecationWarning` and will be removed +in 6.0. + +::: jsonrpcserver.response.serialize_error + +::: jsonrpcserver.response.serialize_success + +::: jsonrpcserver.response.to_serializable_one + +::: jsonrpcserver.response.ResponseType diff --git a/docs/roadmap.md b/docs/roadmap.md index f3da415..a9ec1dc 100644 --- a/docs/roadmap.md +++ b/docs/roadmap.md @@ -1,11 +1,17 @@ +--- +description: The plan for jsonrpcserver 6.0. Results without oslash, safer defaults, a faster validator, and cleanups. 5.x keeps its API and gets fixes. +--- + # Roadmap This is the plan for the next major version. Nothing here is released yet, and it may change. 5.x keeps its current API, and gets bug and security fixes. Discussion happens in the -[issues](https://github.com/bensynapse/jsonrpcserver/issues) and in the draft -[6.0 pull request (#255)](https://github.com/bensynapse/jsonrpcserver/pull/255). +[issues](https://github.com/bensynapse/jsonrpcserver/issues) and +[discussions](https://github.com/bensynapse/jsonrpcserver/discussions). An +older draft of 6.0 exists as a pull request from 2022. It's out of date, and +the plan below replaces it. ## 6.0 @@ -13,10 +19,11 @@ These change behaviour or remove things, so they wait for a major version. **Results without oslash.** `Success`, `Error` and the dispatch functions are built on the oslash library. Its last release for Python 3.8 to 3.11 came out -in 2020, and its newer releases need Python 3.12. 6.0 will replace it with plain typed -result classes, or with `returns` as #255 started. Code that only uses -`Success`, `Error` and `dispatch` should keep working. Code that inspects the -`Left` and `Right` objects from `dispatch_to_response` will need changes. +in 2020, and its newer releases need Python 3.12. 6.0 will replace it with +small typed result classes of its own, or with another maintained library. +Code that only uses `Success`, `Error` and `dispatch` should keep working. +Code that inspects the `Left` and `Right` objects from `dispatch_to_response` +will need changes. **Safer defaults.** @@ -36,9 +43,9 @@ five request fields would be faster and lighter. - Remove `serialize_error`, `serialize_success` and `to_serializable_one`, which 5.0.10 deprecated. -- Decide whether async methods need their own decorator, as #255 proposes, - or whether `async_dispatch` keeps accepting both kinds. Use the same option - names in the sync and async functions. +- Decide whether async methods need their own decorator, or whether + `async_dispatch` keeps accepting both kinds. Use the same option names and + return types in the sync and async functions. - Rework or remove the built-in `serve()` development server. - Drop Python versions that have reached end of life. diff --git a/docs/security-policy.md b/docs/security-policy.md new file mode 100644 index 0000000..d1923db --- /dev/null +++ b/docs/security-policy.md @@ -0,0 +1,5 @@ +--- +description: How to report a security problem in jsonrpcserver privately, and which versions get fixes. +--- + +--8<-- "SECURITY.md" diff --git a/docs/security.md b/docs/security.md index 2731747..1183be8 100644 --- a/docs/security.md +++ b/docs/security.md @@ -1,18 +1,85 @@ +--- +description: What to set before you expose a jsonrpcserver server to the internet. Exception messages, batch and body size limits, client-controlled parameters, the methods you expose, and a fix for 5.0.9. +--- + # Security jsonrpcserver handles requests from clients you may not trust. These are the things to know before you put a server on the internet. -## Exception messages stay on the server +## If you are on 5.0.9 + +!!! danger "5.0.9 sends exception messages to the client" + These docs describe 5.0.10, which isn't on PyPI yet. + `pip install jsonrpcserver` gives you 5.0.9. In 5.0.9, when a method + raises an exception it doesn't catch, the client gets the exception's + message in `error.data`. Messages from database drivers and HTTP clients + often contain connection strings, passwords, hostnames, file paths or SQL. + + Check your version with `pip show jsonrpcserver`. + +Until you can upgrade, wrap each method so that it catches unexpected +exceptions itself, logs them and returns a plain Internal error: + +```python +import functools +import logging +from typing import Any, Callable + +from jsonrpcserver import Error, JsonRpcError, Result, Success, dispatch, method + +logger = logging.getLogger(__name__) + + +def no_leak(func: Callable[..., Result]) -> Callable[..., Result]: + @functools.wraps(func) + def wrapper(*args: Any, **kwargs: Any) -> Result: + try: + return func(*args, **kwargs) + except JsonRpcError: + raise # Errors you raise on purpose still reach the client. + except Exception: + logger.exception("Method %s failed", func.__name__) + return Error(-32603, "Internal error") + + return wrapper -If a method raises an exception it doesn't catch, the client gets a -32603 -"Internal error" with no `data`. The exception and its traceback are logged -through the `jsonrpcserver.dispatcher` logger (`jsonrpcserver.async_dispatcher` -for `async_dispatch`), so make sure your logging configuration keeps them. -Before 5.0.10, the exception message was sent to the client. Messages from -database drivers and HTTP clients often contain connection strings, passwords, -hostnames, file paths or SQL. Upgrade if you're on an older version. +@method +@no_leak +def get_user(user_id: int) -> Result: + raise ConnectionError("could not connect to postgres://admin:hunter2@db") +``` + +```pycon +>>> logging.disable(logging.CRITICAL) # Keep the logged traceback out of this page. +>>> dispatch('{"jsonrpc": "2.0", "method": "get_user", "params": [1], "id": 1}') +'{"jsonrpc": "2.0", "error": {"code": -32603, "message": "Internal error"}, "id": 1}' +>>> logging.disable(logging.NOTSET) +``` + +Put `@no_leak` under `@method`, on every method. `functools.wraps` keeps the +function's signature, so jsonrpcserver still checks the params against it. For +async methods, write the same wrapper with `async def` and `await`. + +The wrapper can't cover one case. An exception inside jsonrpcserver itself, +outside your method, still sends its message in a -32000 "Server error". That needs a bug in jsonrpcserver or in a custom +`validator`, so it's rare. Upgrade to 5.0.10 when it's out, and then remove +the wrapper. + +5.0.9 also lacks `max_batch_size`, so limit the request body size in your web +server (see below). It sends `NaN` and `Infinity` in responses, which strict +JSON parsers reject. And when a result can't be serialized, such as a +`datetime`, `dispatch` raises `TypeError` instead of sending an error, so your +framework answers with its own error page. + +## Exception messages stay on the server + +From 5.0.10, if a method raises an exception it doesn't catch, the client +gets a -32603 "Internal error" with no `data`. The exception and its +traceback are logged, on the `jsonrpcserver` logger. Make sure your logging +configuration keeps them. [Errors and logging](errors.md#logging) lists the +loggers. `debug=True` puts the message back in the response. Use it only in development. @@ -20,22 +87,46 @@ development. Errors you return on purpose with `Error`, `InvalidParams` or `JsonRpcError` are sent as they are, so don't put secrets in their `data` either. +## What does reach the client + +Some error responses always carry details, `debug` or not: + +- **-32700 Parse error** carries the deserializer's exception message. With + the default `json.loads`, that's harmless. A custom `deserializer` must not + put secrets in its exception messages. +- **-32602 Invalid params** carries Python's explanation of why the params + don't fit, which names your parameters, such as + `got an unexpected keyword argument 'skip_checks'`. A client can use it to + discover parameter names. +- **-32601 Method not found** repeats the method name the client sent. + +[Errors and logging](errors.md) lists every error. + ## Limit batch size A single request can be a batch of thousands of requests. Each one is -validated and run. With `async_dispatch`, they all run at once. A 5 MB batch of -100,000 pings took about 4 seconds of CPU time in one test. If the methods do -I/O, a batch also multiplies the load on your database or the APIs you call. +validated and run. With `async_dispatch`, they all run at once. In one test, +on a laptop with Python 3.13, a 5 MB batch of 100,000 pings took about 4 +seconds of CPU time. If the methods do I/O, a batch also multiplies the load +on your database or the APIs you call. Set `max_batch_size` on every dispatch call: ```python -from jsonrpcserver import dispatch - response = dispatch('{"jsonrpc": "2.0", "method": "ping", "id": 1}', max_batch_size=100) ``` -Also limit the size of the request body in your web server or framework. +A bigger batch gets a single error response, and none of it runs. See +[Notifications and batches](batches.md#limit-the-batch-size). It's new in +5.0.10. + +## Limit the request body + +Also limit the size of the request body, in your web server or framework. +It stops a huge request before it's read into memory and parsed, which +`max_batch_size` can't do. Each [framework example](examples.md) sets a limit +of 1,000,000 bytes and names the setting it uses. Some frameworks have no +limit by default, and others allow 100 MB. ## Every parameter is up to the client @@ -44,9 +135,6 @@ your method has. That includes keyword-only parameters and ones with default values. So this is unsafe: ```python -from jsonrpcserver import Result, Success, method - - @method def transfer(amount: int, *, skip_checks: bool = False) -> Result: ... @@ -54,8 +142,9 @@ def transfer(amount: int, *, skip_checks: bool = False) -> Result: ``` A client can send `{"amount": 100, "skip_checks": true}`. Keep server-side -options out of a method's signature. Pass them through `context`, which the -client can't set, or use a separate function. +options out of a method's signature. Pass them through +[`context`](context.md), which the client can't set, or use a separate +function. The values themselves are whatever the JSON held. jsonrpcserver doesn't check them against your type hints, so check them in the method. @@ -70,9 +159,6 @@ name replaces the earlier one without a warning. For a public server, consider passing an explicit dict: ```python -from jsonrpcserver import Result, Success, dispatch - - def ping() -> Result: return Success("pong") @@ -85,45 +171,24 @@ response = dispatch('{"jsonrpc": "2.0", "method": "ping", "id": 1}', METHODS) ## The built-in server is for development `serve()` is a small server built on Python's `http.server`. It has no TLS, -no authentication and no request size limit. Use it to try things out, and put -`dispatch` behind a real web server or framework in production. The -[examples](examples.md) show how. +no authentication and no request size limit, and it doesn't set +`max_batch_size`. Use it to try things out, and put `dispatch` behind a real +web server or framework in production. The [examples](examples.md) show how. -## NaN and Infinity +By default, `serve()` listens on every network interface, so anyone who can +reach your machine can call your methods. Pass `"localhost"` to accept only +local connections, as in `serve("localhost", 8000)`. From 5.0.10 it says where +it's listening when it starts, including a note when that's every interface. -Python's `json` module accepts `NaN`, `Infinity` and numbers like `1e400` in a -request, which aren't valid JSON. To reject them, pass a stricter -`deserializer`: - -```python -import json -import math +## Strict JSON - -def reject(constant: str) -> None: - raise ValueError(f"{constant} is not valid JSON") - - -def finite_float(text: str) -> float: - number = float(text) - if math.isinf(number): - raise ValueError(f"{text} is too big") - return number - - -def strict_loads(request: str): - return json.loads(request, parse_constant=reject, parse_float=finite_float) -``` - -```python ->>> dispatch('{"jsonrpc": "2.0", "method": "ping", "params": [NaN], "id": 1}', METHODS, deserializer=strict_loads) -'{"jsonrpc": "2.0", "error": {"code": -32700, "message": "Parse error", "data": "NaN is not valid JSON"}, "id": null}' -``` - -Responses never contain them. The default serializer refuses to write them. +Python's `json` module accepts `NaN`, `Infinity` and numbers like `1e400` in a +request, which aren't valid JSON. [Validation](validation.md#nan-infinity-and-huge-numbers) +shows a stricter `deserializer` that rejects them. From 5.0.10, responses +never contain them: the default serializer sends an Internal error instead. ## Reporting a vulnerability Please report security problems privately, through the [Security tab](https://github.com/bensynapse/jsonrpcserver/security) on GitHub. -See [SECURITY.md](https://github.com/bensynapse/jsonrpcserver/blob/main/SECURITY.md). +See the [security policy](security-policy.md). diff --git a/docs/testing.md b/docs/testing.md new file mode 100644 index 0000000..f23b67d --- /dev/null +++ b/docs/testing.md @@ -0,0 +1,119 @@ +--- +description: How to unit test jsonrpcserver methods. Call them directly, test them through dispatch with your own methods dict, and keep the global methods from leaking between tests. +--- + +# Testing + +## Call the method directly + +`@method` returns your function unchanged, so a test can call it like any +other function and compare the result: + +```python +from jsonrpcserver import Error, Result, Success, method + + +@method +def divide(a: float, b: float) -> Result: + if b == 0: + return Error(1, "Can't divide by zero") + return Success(a / b) + + +def test_divide() -> None: + assert divide(6, 3) == Success(2) + assert divide(1, 0) == Error(1, "Can't divide by zero") + + +test_divide() +``` + +`Success` and `Error` results compare equal when they hold the same values. + +## Test through dispatch + +To test what the client sees, including the JSON-RPC parts and the parameter +check, call `dispatch_to_serializable` with a dict of methods. It gives a dict, +which is easier to compare than a string: + +```python +from jsonrpcserver import dispatch_to_serializable + + +def test_divide_request() -> None: + response = dispatch_to_serializable( + '{"jsonrpc": "2.0", "method": "divide", "params": [1, 0], "id": 1}', + {"divide": divide}, + ) + assert response == { + "jsonrpc": "2.0", + "error": {"code": 1, "message": "Can't divide by zero"}, + "id": 1, + } + + +def test_divide_wrong_params() -> None: + response = dispatch_to_serializable( + '{"jsonrpc": "2.0", "method": "divide", "params": [1], "id": 1}', + {"divide": divide}, + ) + assert response is not None + assert response["error"]["code"] == -32602 + + +test_divide_request() +test_divide_wrong_params() +``` + +Passing the dict keeps the test to the methods you meant. Without it, +`dispatch` uses every method registered with `@method` anywhere in the test +process. + +## The global methods + +`@method` adds to one dict for the whole process, +`jsonrpcserver.methods.global_methods`. In a test suite, every test module +that's imported adds to it. A later `@method` with the same name replaces an +earlier one without a warning. If two test modules define a method called +`ping`, whichever is imported last wins. + +Either pass `methods` explicitly in tests, as above, or give test methods +unique names. To start a test with no registered methods, clear the dict and +put it back afterwards. With pytest: + +```python +from typing import Any, Dict, Iterator + +from jsonrpcserver.methods import global_methods + + +def clean_methods() -> Iterator[Dict[str, Any]]: # Decorate with @pytest.fixture. + saved = dict(global_methods) + global_methods.clear() + yield global_methods + global_methods.clear() + global_methods.update(saved) +``` + +## Async methods + +An async method is a coroutine function, so run it with `asyncio.run` or +pytest-asyncio's `@pytest.mark.asyncio`: + +```python +import asyncio + + +async def ping() -> Result: + return Success("pong") + + +assert asyncio.run(ping()) == Success("pong") +``` + +## Logged errors + +An exception that a method doesn't catch is logged, and the client gets a +bare Internal error. To check that in a test, use pytest's `caplog` fixture +and look for a record from the `jsonrpcserver.dispatcher` logger. See +[Errors and logging](errors.md#logging). diff --git a/docs/threads.md b/docs/threads.md new file mode 100644 index 0000000..e010a30 --- /dev/null +++ b/docs/threads.md @@ -0,0 +1,63 @@ +--- +description: jsonrpcserver's dispatch functions are safe to call from several threads, including on free-threaded Python 3.14t. Register methods at import time. +--- + +# Threads + +`dispatch` and the other dispatch functions can be called from several +threads at once, so they work with threaded servers such as Flask's, Django's +and `serve()`. That includes free-threaded Python (3.14t), where there is no +GIL. The test suite runs on 3.14t. It calls `dispatch` from many threads at +once, with single requests, batches and a different context in each thread, +and checks that every response is right. + +```python +from concurrent.futures import ThreadPoolExecutor + +from jsonrpcserver import Result, Success, dispatch, method + + +@method +def square(number: int) -> Result: + return Success(number * number) + + +def call(number: int) -> str: + return dispatch( + f'{{"jsonrpc": "2.0", "method": "square", "params": [{number}], "id": {number}}}' + ) + + +with ThreadPoolExecutor(max_workers=8) as pool: + responses = list(pool.map(call, range(100))) + +print(responses[9]) +``` + +```text title="Output" +{"jsonrpc": "2.0", "result": 81, "id": 9} +``` + +`dispatch` keeps no state of its own between calls. Each call only reads the +methods dict. + +## Register methods at import time + +`@method` writes to one dict for the whole process. Run all your `@method` +decorators when your modules are imported, before the server starts handling +requests, which is what happens when they decorate top-level functions. Don't +add or replace methods while other threads are dispatching. If the set of +methods has to change at run time, pass a `methods` dict. To change it, build +a new dict and pass that from then on. + +## Your methods + +jsonrpcserver doesn't make your methods thread-safe. If a method changes +shared state, protect it with a lock as you would anywhere else. Objects +passed as `context` are shared too, if you pass the same one to every call. + +## asyncio + +`async_dispatch` runs on one event loop, and the requests in a batch run +concurrently on it. See [Async](async.md). Don't share one event loop's +objects between threads. diff --git a/docs/typing.md b/docs/typing.md new file mode 100644 index 0000000..f99d443 --- /dev/null +++ b/docs/typing.md @@ -0,0 +1,76 @@ +--- +description: Type checking jsonrpcserver code with mypy and pyright. What Result is, why mypy needs one setting for oslash, and how @method keeps your function's signature. +--- + +# Typing + +jsonrpcserver ships type hints (it has a `py.typed` marker), and its own code +is checked with mypy and pyright in strict mode. + +## Methods keep their signature + +`@method` returns your function unchanged, so type checkers see its real +signature. Calls to your methods from your own code are checked as usual: + +```python +from jsonrpcserver import Result, Success, method + + +@method +def add(a: int, b: int) -> Result: + return Success(a + b) + + +add(1, 2) # fine +# add("1", 2) is a type error: "str" is not "int". +``` + +!!! info "New in 5.0.10" + Before 5.0.10, type checkers saw every function decorated with `@method` + as `(*Any, **Any) -> Any`. They couldn't check calls to it. + +The values in a request aren't checked against these hints at run time. +jsonrpcserver only checks that the arguments fit the signature, so `add` +can still receive a string from a client. Check values in the method if it +matters. + +## What Result is + +`Result` is the return type of a method. `Success`, `Error` and +`InvalidParams` all return one. It comes from the +[oslash](https://pypi.org/project/oslash/) library: it's an `Either`, a +`Right` holding a `SuccessResult` or a `Left` holding an `ErrorResult`. You +don't need to look inside it. Return it, and annotate your methods with it. + +```pycon +>>> from jsonrpcserver import Error, Success +>>> from oslash.either import Left, Right +>>> isinstance(Success("pong"), Right) +True +>>> isinstance(Error(1, "Failed"), Left) +True +``` + +The [Dispatch](dispatch.md#dispatch_to_response) page shows how to read the +`Response` objects that `dispatch_to_response` gives, which work the same +way. The [roadmap](roadmap.md) plans to replace oslash in 6.0. + +## mypy needs one setting + +oslash has type hints but no `py.typed` marker. pyright reads them anyway. +mypy treats `Result` as `Any` unless you add this to `pyproject.toml`: + +```toml +[[tool.mypy.overrides]] +module = ["oslash", "oslash.*"] +follow_untyped_imports = true +``` + +Without it, mypy can't tell a method that returns `Success(...)` from one that +returns a plain value, which would give an Internal error at run time. + +## Async methods + +`async def` methods that return `Result` type-check too, and both `dispatch` +and `async_dispatch` accept them in `methods`. Only `async_dispatch` can +call them. See [Async](async.md). diff --git a/docs/validation.md b/docs/validation.md new file mode 100644 index 0000000..ed38ee4 --- /dev/null +++ b/docs/validation.md @@ -0,0 +1,145 @@ +--- +description: How jsonrpcserver validates JSON-RPC requests. What the default schema checks, custom validators, what you lose by turning it off, and rejecting NaN. +--- + +# Validation + +After parsing a request, jsonrpcserver checks it against the JSON-RPC spec. +A request that fails gets a -32600 "Invalid request" response, and no method +runs. + +## What the default checks + +The default validator checks each request against a JSON schema. A request +must be an object with: + +- `"jsonrpc": "2.0"`, exactly +- a `method` that's a string +- `params`, if present, that's an array or an object +- an `id`, if present, that's a string, a number or null + +Nothing else is allowed in the object. + +```python +from jsonrpcserver import Result, Success, dispatch, method + + +@method +def ping() -> Result: + return Success("pong") +``` + +```pycon +>>> dispatch('{"jsonrpc": "2.0", "method": "ping", "params": "x", "id": 1}') +'{"jsonrpc": "2.0", "error": {"code": -32600, "message": "Invalid request", "data": "The request failed schema validation"}, "id": null}' +``` + +The error doesn't say which rule the request broke, and its `id` is null +because the request couldn't be trusted. + +## A custom validator + +Pass `validator` to use your own. It gets the parsed request, a dict, and +should raise an exception of any kind if the request is invalid. What it +returns is ignored. In a batch, it's called once for each request. + +This one runs the default checks, then refuses requests without an `id`, so +clients can't send notifications: + +```python +from typing import Any, Dict + +from jsonrpcserver.main import default_validator + + +def no_notifications(request: Dict[str, Any]) -> None: + default_validator(request) + if "id" not in request: + raise ValueError("Notifications aren't allowed") +``` + +```pycon +>>> dispatch('{"jsonrpc": "2.0", "method": "ping"}', validator=no_notifications) +'{"jsonrpc": "2.0", "error": {"code": -32600, "message": "Invalid request", "data": "The request failed schema validation"}, "id": null}' +``` + +The exception's message isn't sent to the client. + +!!! info "Changed in 5.0.10" + Before 5.0.10, a batch was validated as a whole: the validator was called + once, with the list. A validator that enforced a rule about the whole + batch, such as refusing batches, no longer sees the list. Use + `max_batch_size` for a size limit. + +## Turning it off + +Validation takes most of the time `dispatch` spends on a small method. If +your own code makes the requests, so you know they're valid, you can turn it +off: + +```pycon +>>> dispatch('{"jsonrpc": "2.0", "method": "ping", "id": 1}', validator=lambda _: None) +'{"jsonrpc": "2.0", "result": "pong", "id": 1}' +``` + +Without it, `dispatch` still never raises, but bad requests get odd answers: + +```pycon +>>> import logging +>>> logging.disable(logging.CRITICAL) # Keep the logged traceback out of this page. +>>> no_validation = lambda _: None +>>> dispatch('{"method": "ping", "id": 1}', validator=no_validation) +'{"jsonrpc": "2.0", "result": "pong", "id": 1}' +>>> dispatch( +... '{"jsonrpc": "2.0", "method": "ping", "params": "x", "id": 1}', +... validator=no_validation, +... ) +'{"jsonrpc": "2.0", "result": "pong", "id": 1}' +>>> dispatch('{"jsonrpc": "2.0", "id": 1}', validator=no_validation) +'{"jsonrpc": "2.0", "error": {"code": -32000, "message": "Server error"}, "id": null}' +>>> logging.disable(logging.NOTSET) +``` + +A request with no `jsonrpc` member runs, and params that aren't a list or an +object are ignored. A request with no `method` gets a -32000 "Server error", +and jsonrpcserver logs it as an error of its own. Keep validation on for +anything that strangers can reach. + +## NaN, Infinity and huge numbers + +Python's `json` module accepts `NaN`, `Infinity` and numbers like `1e400` in +a request. They aren't valid JSON, and the schema can't see them, because +they're already floats by the time it runs. To reject them, pass a stricter +`deserializer`: + +```python +import json +import math + + +def reject(constant: str) -> None: + raise ValueError(f"{constant} is not valid JSON") + + +def finite_float(text: str) -> float: + number = float(text) + if math.isinf(number): + raise ValueError(f"{text} is too big") + return number + + +def strict_loads(request: str) -> Any: + return json.loads(request, parse_constant=reject, parse_float=finite_float) +``` + +```pycon +>>> dispatch( +... '{"jsonrpc": "2.0", "method": "ping", "params": [NaN], "id": 1}', +... deserializer=strict_loads, +... ) +'{"jsonrpc": "2.0", "error": {"code": -32700, "message": "Parse error", "data": "NaN is not valid JSON"}, "id": null}' +``` + +Responses never contain them in 5.0.10: the default serializer refuses to +write them and sends an Internal error instead. 5.0.9 writes them as they +are. diff --git a/mkdocs.yml b/mkdocs.yml index dd6c237..ea611ab 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,51 +1,137 @@ site_name: jsonrpcserver -site_description: Process incoming JSON-RPC requests in Python +site_description: Process incoming JSON-RPC 2.0 requests in Python site_url: https://bensynapse.github.io/jsonrpcserver/ repo_url: https://github.com/bensynapse/jsonrpcserver repo_name: bensynapse/jsonrpcserver edit_uri: edit/main/docs/ +copyright: >- + jsonrpcserver is MIT licensed. Created by Beau Barker. Maintained by + Synapse Research. theme: name: material + custom_dir: overrides + font: false logo: assets/logo.png + favicon: assets/favicon.png + icon: + repo: fontawesome/brands/github features: - - navigation.footer + - content.action.edit + - content.code.annotate - content.code.copy + - navigation.footer + - navigation.sections + - navigation.top + - search.highlight + - search.suggest + - toc.follow palette: - media: "(prefers-color-scheme)" scheme: default - primary: "pink" + primary: pink + accent: pink toggle: icon: material/brightness-auto name: Switch to light mode - media: "(prefers-color-scheme: light)" scheme: default - primary: "pink" + primary: pink + accent: pink toggle: icon: material/brightness-7 name: Switch to dark mode - media: "(prefers-color-scheme: dark)" scheme: slate - primary: "pink" + primary: pink + accent: pink toggle: icon: material/brightness-4 name: Switch to system preference +extra: + # The version these docs describe while it isn't on PyPI yet. It shows a + # banner on every page. Remove it when that version is released (see + # RELEASING.md). + unreleased: "5.0.10" + pypi_version: "5.0.9" + social_image: assets/social-card.png plugins: - search + - mkdocstrings: + handlers: + python: + paths: [.] + options: + docstring_style: google + docstring_section_style: list + heading_level: 3 + members_order: source + merge_init_into_class: true + separate_signature: true + show_root_full_path: false + show_root_heading: true + show_signature_annotations: true + show_source: false + show_symbol_type_heading: true + show_symbol_type_toc: true + signature_crossrefs: true extra_css: - assets/extra.css +extra_javascript: + - assets/copy-without-prompts.js + - assets/a11y.js markdown_extensions: - admonition - - pymdownx.highlight + - attr_list + - md_in_html + - pymdownx.details + - pymdownx.highlight: + # Adds language-pycon etc., which copy-without-prompts.js looks for. + pygments_lang_class: true - pymdownx.superfences - pymdownx.snippets: check_paths: true + - tables + - toc: + permalink: true +validation: + omitted_files: warn + absolute_links: warn + unrecognized_links: warn + anchors: warn nav: - Home: index.md - - Methods: methods.md - - Dispatch: dispatch.md - - Async: async.md - - Examples: examples.md + - Guide: + - Methods: methods.md + - Dispatch: dispatch.md + - Notifications and batches: batches.md + - Async: async.md + - Errors and logging: errors.md + - Context: context.md + - Validation: validation.md + - Typing: typing.md + - Testing: testing.md + - Threads: threads.md + - Frameworks: + - Overview: examples.md + - http.server and serve(): frameworks/http-server.md + - Flask: frameworks/flask.md + - Werkzeug: frameworks/werkzeug.md + - Django: frameworks/django.md + - FastAPI: frameworks/fastapi.md + - aiohttp: frameworks/aiohttp.md + - Sanic: frameworks/sanic.md + - Tornado: frameworks/tornado.md + - websockets: frameworks/websockets.md + - ZeroMQ: frameworks/zeromq.md + - Socket.IO: frameworks/socketio.md - Security: security.md + - API reference: reference.md + - Migration: migration.md - FAQ: faq.md - Roadmap: roadmap.md - - Changelog: https://github.com/bensynapse/jsonrpcserver/blob/main/CHANGELOG.md + - Project: + - Changelog: changelog.md + - Contributing: contributing.md + - Security policy: security-policy.md + - License: license.md + - jsonrpcclient: https://bensynapse.github.io/jsonrpcclient/ diff --git a/overrides/404.html b/overrides/404.html new file mode 100644 index 0000000..4dfa56c --- /dev/null +++ b/overrides/404.html @@ -0,0 +1,22 @@ +{% extends "main.html" %} + +{% block content %} +

Page not found

+

+ There's no page at this address. It may have moved when the documentation + was reorganized. +

+ +

+ You can also search with the box at the top of the page, or + open an issue + if a link brought you here. +

+{% endblock %} diff --git a/overrides/main.html b/overrides/main.html new file mode 100644 index 0000000..a004c8a --- /dev/null +++ b/overrides/main.html @@ -0,0 +1,49 @@ +{% extends "base.html" %} + +{% block announce %} + {%- if config.extra.unreleased -%} + These docs describe jsonrpcserver {{ config.extra.unreleased }}, which + isn't on PyPI yet. pip install jsonrpcserver gives you + {{ config.extra.pypi_version }}, which sends exception messages to clients. + Security + has a fix for that, and the + changelog lists the other + differences. + {%- endif -%} +{% endblock %} + +{% block extrahead %} + {#- GitHub Pages can't enforce HTTPS for this site yet, so send plain-HTTP + visitors to the HTTPS address. -#} + + {%- set meta = page.meta if page and page.meta else {} -%} + {%- if meta.title -%} + {%- set title = meta.title -%} + {%- elif page and page.title and not page.is_homepage -%} + {%- set title = page.title ~ " - " ~ config.site_name -%} + {%- else -%} + {%- set title = config.site_name -%} + {%- endif -%} + {%- set description = meta.description or config.site_description -%} + {%- set image = config.site_url ~ config.extra.social_image -%} + + + + + + {%- if page and page.canonical_url %} + + {%- endif %} + + + + + + + + +{% endblock %} diff --git a/pyproject.toml b/pyproject.toml index 8b56e3a..e79e830 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -5,7 +5,7 @@ build-backend = "flit_core.buildapi" [project] name = "jsonrpcserver" dynamic = ["version"] -description = "Process incoming JSON-RPC requests in Python" +description = "Process incoming JSON-RPC 2.0 requests in Python" readme = "README.md" license = "MIT" license-files = ["LICENSE"] @@ -14,7 +14,7 @@ authors = [ {name = "Beau Barker", email = "beau@explodinglabs.com"}, ] maintainers = [ - {name = "bensynapse"}, + {name = "Synapse Research"}, ] keywords = ["json-rpc", "jsonrpc", "json-rpc-2.0", "rpc", "server"] classifiers = [ @@ -48,7 +48,7 @@ Homepage = "https://bensynapse.github.io/jsonrpcserver/" Documentation = "https://bensynapse.github.io/jsonrpcserver/" Repository = "https://github.com/bensynapse/jsonrpcserver" Issues = "https://github.com/bensynapse/jsonrpcserver/issues" -Changelog = "https://github.com/bensynapse/jsonrpcserver/blob/main/CHANGELOG.md" +Changelog = "https://bensynapse.github.io/jsonrpcserver/changelog/" [project.optional-dependencies] test = [ @@ -61,8 +61,12 @@ test = [ [tool.flit.sdist] include = [ "CHANGELOG.md", + "CONTRIBUTING.md", + "RELEASING.md", + "SECURITY.md", "docs/", "mkdocs.yml", + "overrides/", "requirements/", "tests/", "tox.ini", @@ -71,9 +75,10 @@ include = [ [tool.ruff] target-version = "py38" + [tool.ruff.format] -# Its code blocks are "--8<--" include lines, not Python. -exclude = ["docs/examples.md"] +# Their code blocks include files with "--8<--" lines, which aren't Python. +exclude = ["docs/index.md", "docs/frameworks/*.md"] [tool.ruff.lint] select = ["E", "W", "F", "I", "UP", "B", "C4", "SIM", "RUF"] diff --git a/requirements/docs.txt b/requirements/docs.txt index 0c525b8..c9a765c 100644 --- a/requirements/docs.txt +++ b/requirements/docs.txt @@ -1,2 +1,4 @@ mkdocs==1.6.1 mkdocs-material==9.7.7 +mkdocstrings==1.0.6 +mkdocstrings-python==2.0.9 diff --git a/requirements/examples.txt b/requirements/examples.txt index 6314829..43a5b8b 100644 --- a/requirements/examples.txt +++ b/requirements/examples.txt @@ -4,8 +4,15 @@ django==6.1.1 fastapi==0.142.2 flask==3.1.3 flask-socketio==5.6.1 +# FastAPI's test client, used on the Context page. +httpx2==2.13.1 +# The quickstart calls the server with jsonrpcclient and requests. +jsonrpcclient==4.0.3 +# The FAQ's orjson example. +orjson==3.12.0 python-socketio[client]==5.17.0 pyzmq==27.2.0 +requests==2.34.2 sanic==25.12.1 tornado==6.5.10 ujson==6.0.0 diff --git a/requirements/site.txt b/requirements/site.txt new file mode 100644 index 0000000..78e0857 --- /dev/null +++ b/requirements/site.txt @@ -0,0 +1,2 @@ +# For .github/scripts/check_site.py, which CI's site job runs. +playwright==1.63.0 diff --git a/tests/doc_examples.py b/tests/doc_examples.py index e8aa78d..d659da2 100644 --- a/tests/doc_examples.py +++ b/tests/doc_examples.py @@ -6,31 +6,77 @@ request ids count up from 1 as they do for a reader trying the examples. Run each file in a fresh interpreter (tests/test_docs.py does). -A python block that contains ">>>" is a doctest: the output must match, and -"..." matches anything. Any other python block just has to run. +A python or pycon block that contains ">>>" is a doctest: the output must +match, and "..." matches anything. Any other python block has to run, and if +the next block is a text block titled "Output" (```text title="Output"), what +the code prints must match it. -An HTML comment on the line before a block can skip it: +HTML comments on the lines just before a block change how it runs: skip unless ujson can be imported skip on older Pythons -Blocks that include a file with "--8<--" are skipped. Those are the transport -examples, which docs/examples/check_examples.py runs against a test server. + run the quickstart server + (docs/examples/quickstart.py) on + localhost:8000 while the block runs + never run it, such as code for 4.x +A block can have several of these, one per line. Fences can be indented, as +they are inside an admonition. Blocks that include a file with "--8<--" are +skipped. Those are the framework examples, which +docs/examples/check_examples.py starts and sends requests to. """ import doctest import importlib.util +import io import re +import socket +import subprocess import sys +import time +from contextlib import contextmanager, nullcontext, redirect_stdout from pathlib import Path -from typing import Any, Dict, List, NamedTuple - -FENCE = re.compile(r"^```\s*(\w*)\s*$") -MARKER = re.compile(r"^$") +from typing import ( + Any, + ContextManager, + Dict, + Generator, + List, + NamedTuple, + Optional, + Tuple, +) + +QUICKSTART = Path(__file__).parent.parent / "docs" / "examples" / "quickstart.py" +PORT = 8000 + +# A fence can be indented, for example inside an admonition. +FENCE = re.compile(r"^(\s*)```\s*(\w*)(.*)$") +OUTPUT = re.compile(r'^\s*title="Output"\s*$') +MARKER = re.compile(r"^$") class Block(NamedTuple): line: int code: str - marker: str + markers: List[str] + output: Optional[str] + + +def fenced(lines: List[str], i: int) -> Tuple[str, str, List[str], int]: + """Read the fenced block starting at line i. + + Return its language, the rest of the opening line, its body without the + fence's indentation, and the index of the line after the closing fence. + """ + match = FENCE.match(lines[i]) + assert match + indent, language, rest = match.groups() + body: List[str] = [] + i += 1 + while i < len(lines) and not FENCE.match(lines[i]): + line = lines[i] + body.append(line[len(indent) :] if line.startswith(indent) else line) + i += 1 + return language, rest, body, i + 1 def python_blocks(text: str) -> List[Block]: @@ -38,34 +84,86 @@ def python_blocks(text: str) -> List[Block]: lines = text.splitlines() i = 0 while i < len(lines): - match = FENCE.match(lines[i]) - if not match: + if not FENCE.match(lines[i]): i += 1 continue - language, start = match.group(1), i - i += 1 - body: List[str] = [] - while i < len(lines) and not FENCE.match(lines[i]): - body.append(lines[i]) - i += 1 - i += 1 + start = i + language, _, body, i = fenced(lines, i) if language in ("python", "py", "pycon"): - marker = lines[start - 1].strip() if start > 0 else "" - blocks.append(Block(start + 1, "\n".join(body) + "\n", marker)) + markers: List[str] = [] + j = start - 1 + while j >= 0 and MARKER.match(lines[j].strip()): + markers.append(lines[j].strip()) + j -= 1 + code = "\n".join(body) + "\n" + blocks.append(Block(start + 1, code, markers, output_after(lines, i))) return blocks +def output_after(lines: List[str], i: int) -> Optional[str]: + """Return the text of an "Output" block that starts at or after line i.""" + while i < len(lines) and not lines[i].strip(): + i += 1 + if i >= len(lines) or not FENCE.match(lines[i]): + return None + language, rest, body, _ = fenced(lines, i) + if language != "text" or not OUTPUT.match(rest): + return None + return "\n".join(body) + + def skip_reason(block: Block) -> str: if "--8<--" in block.code: return "included file" - match = MARKER.match(block.marker) - if not match: - return "" - kind, value = match.groups() - if kind == "requires": - return "" if importlib.util.find_spec(value) else f"needs {value}" - wanted = tuple(int(part) for part in value.split(".")) - return f"needs Python {value}" if sys.version_info < wanted else "" + for marker in block.markers: + match = MARKER.match(marker) + assert match + kind, value = match.groups() + if kind == "skip": + return value or "marked skip" + if kind == "requires" and not importlib.util.find_spec(value): + return f"needs {value}" + if kind == "min-python": + wanted = tuple(int(part) for part in value.split(".")) + if sys.version_info < wanted: + return f"needs Python {value}" + return "" + + +def port_open() -> bool: + try: + with socket.create_connection(("localhost", PORT), timeout=1): + return True + except OSError: + return False + + +@contextmanager +def quickstart_server() -> Generator[None, None, None]: + """Run the quickstart server on localhost:8000, as a reader would.""" + if port_open(): + raise RuntimeError(f"Port {PORT} is already in use") + server = subprocess.Popen( + [sys.executable, str(QUICKSTART)], + stdout=subprocess.DEVNULL, + stderr=subprocess.DEVNULL, + ) + try: + deadline = time.monotonic() + 30 + while not port_open(): + if server.poll() is not None or time.monotonic() > deadline: + raise RuntimeError("The quickstart server didn't start") + time.sleep(0.1) + yield + finally: + server.terminate() + server.wait(10) + + +def server_for(block: Block) -> ContextManager[None]: + if "" in block.markers: + return quickstart_server() + return nullcontext() def run_file(path: Path) -> int: @@ -82,23 +180,42 @@ def run_file(path: Path) -> int: skipped += 1 continue ran += 1 - if ">>>" in block.code: - test = parser.get_doctest( - block.code, namespace, str(path), str(path), block.line - ) - failures += runner.run(test, clear_globs=False).failed - # DocTest works on a copy of the namespace. Keep what it defined. - namespace.update(test.globs) - else: - try: - exec(compile(block.code, f"{path}:{block.line}", "exec"), namespace) - except Exception as exc: - print(f"{path}:{block.line}: {type(exc).__name__}: {exc}") - failures += 1 + with server_for(block): + failures += run_block(path, block, namespace, runner, parser) print(f"{path}: {ran} blocks run, {skipped} skipped, {failures} failed") return failures +def run_block( + path: Path, + block: Block, + namespace: Dict[str, Any], + runner: doctest.DocTestRunner, + parser: doctest.DocTestParser, +) -> int: + """Run one block and return the number of failures.""" + if ">>>" in block.code: + test = parser.get_doctest( + block.code, namespace, str(path), str(path), block.line + ) + failed = runner.run(test, clear_globs=False).failed + # DocTest works on a copy of the namespace. Keep what it defined. + namespace.update(test.globs) + return failed + printed = io.StringIO() + try: + with redirect_stdout(printed): + exec(compile(block.code, f"{path}:{block.line}", "exec"), namespace) + except Exception as exc: + print(f"{path}:{block.line}: {type(exc).__name__}: {exc}") + return 1 + if block.output is not None and printed.getvalue().strip() != block.output.strip(): + print(f"{path}:{block.line}: printed {printed.getvalue()!r}") + print(f"{' ' * len(str(path))} expected {block.output!r}") + return 1 + return 0 + + if __name__ == "__main__": total = sum(run_file(Path(arg)) for arg in sys.argv[1:]) sys.exit(1 if total else 0) diff --git a/tests/test_docs.py b/tests/test_docs.py index b6abe50..ca2fe32 100644 --- a/tests/test_docs.py +++ b/tests/test_docs.py @@ -1,16 +1,33 @@ -"""Every Python example in the README and docs must run and show true output.""" +"""Every Python example in the README and docs must run and show true output. +The framework examples run in CI's docs job, which has the frameworks +installed. The checks here keep the docs complete and in step with the code. +""" + +import re +import runpy import subprocess import sys from pathlib import Path +from typing import Any, Dict, List, Set import pytest +import jsonrpcserver + ROOT = Path(__file__).parent.parent -FILES = [ROOT / "README.md", *sorted((ROOT / "docs").glob("*.md"))] +DOCS = ROOT / "docs" +FILES = [ROOT / "README.md", *sorted(DOCS.rglob("*.md"))] +# The constants that docs/examples/check_examples.py tests against. +CHECKER = runpy.run_path(str(DOCS / "examples" / "check_examples.py")) +CURL: str = CHECKER["CURL"] +CURL_OUTPUT: str = CHECKER["CURL_OUTPUT"] +EXAMPLES: Dict[str, Any] = CHECKER["EXAMPLES"] +NOT_SERVERS: Set[str] = CHECKER["NOT_SERVERS"] -@pytest.mark.parametrize("path", FILES, ids=lambda path: path.name) + +@pytest.mark.parametrize("path", FILES, ids=lambda path: str(path.relative_to(ROOT))) def test_doc_examples(path: Path) -> None: # A fresh interpreter per file, so methods registered with @method on one # page don't leak into another. @@ -20,3 +37,101 @@ def test_doc_examples(path: Path) -> None: text=True, ) assert result.returncode == 0, result.stdout + result.stderr + + +def block_after(text: str, after: str, language: str) -> str: + fence = f"```{language}\n" + start = text.index(fence, text.index(after)) + len(fence) + return text[start : text.index("```", start)] + + +def test_readme_quickstart_is_the_tested_example() -> None: + """check_examples.py runs quickstart.py, so the README must match it.""" + readme = (ROOT / "README.md").read_text() + example = (DOCS / "examples" / "quickstart.py").read_text() + assert block_after(readme, "## Quickstart", "python") == example + assert block_after(readme, "## Quickstart", "text") == CURL_OUTPUT + "\n" + + +@pytest.mark.parametrize("path", FILES, ids=lambda path: str(path.relative_to(ROOT))) +def test_every_curl_command_is_the_tested_one(path: Path) -> None: + """check_examples.py runs CURL against the quickstart server.""" + for line in path.read_text().splitlines(): + if line.startswith("curl "): + assert line == CURL + + +def test_every_included_example_is_checked() -> None: + included: Set[str] = set() + for path in DOCS.rglob("*.md"): + included.update( + re.findall(r'--8<-- "docs/examples/(\w+\.py)"', path.read_text()) + ) + assert included + assert included <= set(EXAMPLES) | NOT_SERVERS + # Every example server is shown somewhere in the docs. + assert set(EXAMPLES) <= included + + +def test_examples_use_port_8000_on_localhost() -> None: + for path in (DOCS / "examples").glob("*.py"): + text = path.read_text() + assert "5000" not in text, path.name + assert "tcp://*" not in text, path.name + + +@pytest.mark.parametrize("name", sorted(EXAMPLES)) +def test_examples_set_max_batch_size(name: str) -> None: + """The Security page says to set it on every dispatch call.""" + text = (DOCS / "examples" / name).read_text() + calls = re.findall(r"dispatch\((.*)\)", text) + if name == "quickstart.py": + # serve() calls dispatch itself. + assert calls == [] + else: + assert calls + assert all("max_batch_size=100" in call for call in calls), calls + + +def public_names() -> List[str]: + return [*jsonrpcserver.__all__, "__version__"] + + +@pytest.mark.parametrize("name", public_names()) +def test_reference_documents_every_public_name(name: str) -> None: + reference = (DOCS / "reference.md").read_text() + assert f"::: jsonrpcserver.{name}\n" in reference + + +def test_python_versions_badge_matches_classifiers() -> None: + pyproject = (ROOT / "pyproject.toml").read_text() + versions = re.findall(r'"Programming Language :: Python :: (3\.\d+)"', pyproject) + readme = (ROOT / "README.md").read_text() + badge = re.search(r"img\.shields\.io/badge/python-([^-]+)-blue", readme) + assert badge + assert badge.group(1).split("%20%7C%20") == versions + + +def test_tagline_is_the_same_everywhere() -> None: + tagline = "Process incoming JSON-RPC 2.0 requests in Python" + assert f'description = "{tagline}"' in (ROOT / "pyproject.toml").read_text() + assert f"site_description: {tagline}\n" in (ROOT / "mkdocs.yml").read_text() + assert f"{tagline}" in (ROOT / "README.md").read_text() + assert f"_{tagline}._" in (DOCS / "index.md").read_text() + + +def test_every_page_has_a_description() -> None: + for path in DOCS.rglob("*.md"): + text = path.read_text() + assert text.startswith("---\n"), path + front_matter = text.split("---\n")[1] + assert re.search(r"^description: .{50,}$", front_matter, re.M), path + + +def test_old_domains_are_named_not_linked() -> None: + """The FAQ names the old domains so readers recognise them. CI's domain + check skips that file, so make sure they're never links.""" + faq = (DOCS / "faq.md").read_text() + for match in re.finditer(r"jsonrpc(?:client|server)\.com", faq): + before = faq[max(0, match.start() - 12) : match.start()] + assert "://" not in before and "](" not in before and "www." not in before diff --git a/tests/test_threading.py b/tests/test_threading.py new file mode 100644 index 0000000..b29e9da --- /dev/null +++ b/tests/test_threading.py @@ -0,0 +1,92 @@ +"""dispatch must give the right response to each request when many threads +call it at once. CI runs this on free-threaded 3.14t too.""" + +import json +import sys +import threading +from typing import Any, Callable, Iterator, List + +import pytest + +from jsonrpcserver import Error, Result, Success, dispatch, method + +THREADS = 8 +CALLS = 500 + + +@pytest.fixture(autouse=True) +def frequent_thread_switches() -> Iterator[None]: + """On GIL builds, switch threads as often as possible to provoke races.""" + old = sys.getswitchinterval() + sys.setswitchinterval(1e-6) + yield + sys.setswitchinterval(old) + + +@method(name="threading_echo") +def echo(value: Any) -> Result: + return Success(value) + + +def double(context: int, value: int) -> Result: + if value < 0: + return Error(1, "Negative", value) + return Success(context * value) + + +def hammer(work: Callable[[int, int], None]) -> List[str]: + """Run work(thread, call) from several threads at once and collect errors.""" + errors: List[str] = [] + lock = threading.Lock() + barrier = threading.Barrier(THREADS) + + def worker(thread: int) -> None: + barrier.wait() + for call in range(CALLS): + try: + work(thread, call) + except Exception as exc: + with lock: + errors.append(repr(exc)) + + threads = [threading.Thread(target=worker, args=(n,)) for n in range(THREADS)] + for thread in threads: + thread.start() + for thread in threads: + thread.join() + return errors + + +def test_global_methods_from_many_threads() -> None: + def work(thread: int, call: int) -> None: + id_ = thread * CALLS + call + request = {"jsonrpc": "2.0", "method": "threading_echo", "params": [id_]} + response = json.loads(dispatch(json.dumps({**request, "id": id_}))) + assert response == {"jsonrpc": "2.0", "result": id_, "id": id_} + + assert hammer(work) == [] + + +def test_batches_and_context_from_many_threads() -> None: + def work(thread: int, call: int) -> None: + batch = [ + {"jsonrpc": "2.0", "method": "double", "params": [call], "id": 1}, + {"jsonrpc": "2.0", "method": "double", "params": [-1], "id": 2}, + {"jsonrpc": "2.0", "method": "double", "params": [call]}, + ] + response = dispatch( + json.dumps(batch), + {"double": double}, + context=thread, + max_batch_size=3, + ) + assert json.loads(response) == [ + {"jsonrpc": "2.0", "result": thread * call, "id": 1}, + { + "jsonrpc": "2.0", + "error": {"code": 1, "message": "Negative", "data": -1}, + "id": 2, + }, + ] + + assert hammer(work) == [] From 3c77838fe8b815b71441c9f1fb1aa1ba20921fb2 Mon Sep 17 00:00:00 2001 From: bensynapse <118375461+bensynapse@users.noreply.github.com> Date: Tue, 6 Oct 2026 06:13:59 +0300 Subject: [PATCH 2/2] Correct version history and defaults found in review An independent check of the new pages against the code found these. - 4.x had a debug option that hid exception messages by default. Only 5.0.0 to 5.0.9 always send them. The docs, SECURITY.md and the advisory range in RELEASING.md now say so. - Up to 5.0.9, a plain return value was logged with a traceback and explained to the client in data. Only 5.0.10 sends no details. - Only dispatch and async_dispatch refuse NaN by default. dispatch_to_serializable returns the float as it is. - aiohttp's and websockets' defaults are 1 MiB, which is more than the 1,000,000 bytes the examples set. - ResponseType gives no DeprecationWarning. - A custom validator can get things other than a dict, and with validation off an empty batch gets no response. - 5.0.9's serve() handled one request at a time and logged its start on the root logger. --- CHANGELOG.md | 2 +- RELEASING.md | 3 ++- SECURITY.md | 4 ++-- docs/dispatch.md | 5 +++-- docs/errors.md | 12 +++++++----- docs/examples/aiohttp_server.py | 2 +- docs/examples/websockets_server.py | 2 +- docs/frameworks/aiohttp.md | 2 +- docs/frameworks/http-server.md | 3 ++- docs/frameworks/websockets.md | 4 ++-- docs/methods.md | 5 +++-- docs/migration.md | 9 +++++---- docs/reference.md | 4 ++-- docs/security.md | 6 ++++-- docs/validation.md | 18 +++++++++++------- 15 files changed, 47 insertions(+), 34 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 25a42df..85087fd 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -70,7 +70,7 @@ the JSON-RPC spec says (#291). `[1, {"jsonrpc": "2.0", "method": "ping", "id": error and `ping` runs. As part of that change, a custom `validator` is now called once for each -request in a batch, with that request's dict. Before, it was called once with +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 diff --git a/RELEASING.md b/RELEASING.md index ef7fe1c..e41fe08 100644 --- a/RELEASING.md +++ b/RELEASING.md @@ -67,7 +67,8 @@ Settings → Environments → pypi. 5. If the release fixes a security problem, publish a repository security advisory for it, so Dependabot, `pip-audit` and OSV warn people on older versions. In the Security tab, choose "New draft security advisory". Set - the affected versions (for 5.0.10: `<= 5.0.9`) and the patched version. + the affected versions (for 5.0.10: `>= 5.0.0, <= 5.0.9`) and the patched + version. Pick the CWE, link the docs page that explains it, and publish. For the 5.0.10 fix, the CWE is CWE-209, information exposure through an error message. diff --git a/SECURITY.md b/SECURITY.md index b38006a..80bb104 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -13,8 +13,8 @@ problem. We'll reply within a week. Fixes go into the latest 5.x release. Older releases don't get updates. -Versions before 5.0.10 send the message of any uncaught exception in a method -to the client. Please upgrade when 5.0.10 is on PyPI. Until then, the +Versions 5.0.0 to 5.0.9 send the message of any uncaught exception in a +method to the client. Please upgrade when 5.0.10 is on PyPI. Until then, the [security notes](https://bensynapse.github.io/jsonrpcserver/security/#if-you-are-on-509) in the docs show how to protect a 5.0.9 server. They also cover the other settings to check before exposing a server. diff --git a/docs/dispatch.md b/docs/dispatch.md index d78fc26..72f9649 100644 --- a/docs/dispatch.md +++ b/docs/dispatch.md @@ -116,8 +116,9 @@ Only use it in development. Exception messages can include passwords, file paths and SQL. The default is `False`. !!! info "New in 5.0.10" - The `debug` option, and leaving the message out by default. In 5.0.9 and - earlier the message is always sent, and `debug` raises `TypeError`. See + The `debug` option, and leaving the message out by default. In 5.0.0 to + 5.0.9 the message is always sent, and `debug` raises `TypeError`. (4.x + had `debug` too, off by default.) See [Security](security.md#if-you-are-on-509). ### max_batch_size diff --git a/docs/errors.md b/docs/errors.md index 6cdbf6f..cd022d8 100644 --- a/docs/errors.md +++ b/docs/errors.md @@ -23,9 +23,10 @@ reaches the client. Keep that in mind if you write a custom deserializer, because its exception messages are sent as they are. !!! info "Changed in 5.0.10" - Before 5.0.10, the -32603 and -32000 errors always carried the exception - message. It could hold passwords, paths or SQL. See - [Security](security.md). + From 5.0.0 to 5.0.9, the -32603 and -32000 errors always carried the + exception message. It could hold passwords, paths or SQL. See + [Security](security.md). 4.x had a `debug` option that hid it by default, + and 5.0.10 brings that back. ## Four ways for a method to fail @@ -177,5 +178,6 @@ jsonrpcserver.dispatcher ERROR: Method 'ping' returned 'pong', which is not a Re !!! info "New in 5.0.10" The `jsonrpcserver.main` messages and this one. Before 5.0.10, a - serializer failure raised out of `dispatch`, and a plain return value was - only explained in the response's `data`. + serializer failure raised out of `dispatch`. A plain return value was + logged with a traceback, and its explanation was also sent to the client + in `data`. diff --git a/docs/examples/aiohttp_server.py b/docs/examples/aiohttp_server.py index ce05a99..31e40de 100644 --- a/docs/examples/aiohttp_server.py +++ b/docs/examples/aiohttp_server.py @@ -15,7 +15,7 @@ async def handle(request: web.Request) -> web.Response: return web.Response(status=204) -# Bigger requests get 413 Request Entity Too Large. 1 MiB is also the default. +# Bigger requests get 413 Request Entity Too Large. The default is 1 MiB. app = web.Application(client_max_size=1_000_000) app.router.add_post("/", handle) diff --git a/docs/examples/websockets_server.py b/docs/examples/websockets_server.py index 00a5c7c..38728de 100644 --- a/docs/examples/websockets_server.py +++ b/docs/examples/websockets_server.py @@ -20,7 +20,7 @@ async def handler(websocket: ServerConnection) -> None: async def main() -> None: - # A bigger message closes the connection. 1 MiB is also the default. + # A bigger message closes the connection. The default is 1 MiB. async with serve(handler, "localhost", 8000, max_size=1_000_000) as server: await server.serve_forever() diff --git a/docs/frameworks/aiohttp.md b/docs/frameworks/aiohttp.md index a001271..f3ea23c 100644 --- a/docs/frameworks/aiohttp.md +++ b/docs/frameworks/aiohttp.md @@ -9,7 +9,7 @@ description: A JSON-RPC 2.0 server with aiohttp and jsonrpcserver's async_dispat ``` aiohttp refuses a body bigger than `client_max_size` with 413. Its default is -1 MiB, and the example sets it explicitly so it's easy to change. +1 MiB (1,048,576 bytes). The example sets 1,000,000, like the other examples. `max_batch_size` limits how many requests one batch can hold. See [Security](../security.md). diff --git a/docs/frameworks/http-server.md b/docs/frameworks/http-server.md index 5dc8de2..d7a0636 100644 --- a/docs/frameworks/http-server.md +++ b/docs/frameworks/http-server.md @@ -45,7 +45,8 @@ Know its limits before you use it: !!! info "Changed in 5.0.10" In 5.0.9, `serve()` answers a notification with 200 and an empty body - instead of 204, and prints nothing when it starts. It drops the + instead of 204. It also handles one request at a time. It logs its start on + the root logger at INFO, so you usually see nothing. It drops the connection for a missing `Content-Length` or a body that isn't UTF-8. ## Try it diff --git a/docs/frameworks/websockets.md b/docs/frameworks/websockets.md index 558ad99..ebf8481 100644 --- a/docs/frameworks/websockets.md +++ b/docs/frameworks/websockets.md @@ -13,8 +13,8 @@ Uses the `websockets.asyncio` server from Unlike HTTP, a WebSocket doesn't need an answer to every message, so a notification gets nothing back. websockets closes the connection if a message -is bigger than `max_size`. Its default is 1 MiB, and the example sets it -explicitly. `max_batch_size` limits how many requests one batch can hold. See +is bigger than `max_size`. Its default is 1 MiB (1,048,576 bytes). The +example sets 1,000,000, like the other examples. `max_batch_size` limits how many requests one batch can hold. See [Security](../security.md). Requests on one connection are handled one at a time, in the order they diff --git a/docs/methods.md b/docs/methods.md index 42e3941..78d4a10 100644 --- a/docs/methods.md +++ b/docs/methods.md @@ -49,8 +49,9 @@ jsonrpcserver adds the `jsonrpc` and `id` parts. !!! warning "Return `Success(value)`, not the value" In 4.x a method returned its result directly. In 5.x, `return "pong"` - sends the client a -32603 "Internal error", with no details. The log - says what went wrong. See [Migration](migration.md). + sends the client a -32603 "Internal error". From 5.0.10 the response + has no details, and the log says what went wrong. See + [Migration](migration.md). `Success` takes the result value. If there's nothing to return, call it with no argument and the result is `null`: diff --git a/docs/migration.md b/docs/migration.md index ad78187..fc68ef2 100644 --- a/docs/migration.md +++ b/docs/migration.md @@ -20,8 +20,9 @@ small changes. return "pong" ``` - still runs, but the client gets `{"code": -32603, "message": "Internal - error"}` with no details. From 5.0.10 the log says what's wrong: + still runs, but the client gets a -32603 "Internal error". Up to 5.0.9, + its `data` says "The method did not return a valid Result". From 5.0.10 + the client gets no details, and the log says what's wrong: ```text Method 'ping' returned 'pong', which is not a Result, so the client got an Internal error. Return Success(value) or Error(code, message). ... @@ -97,7 +98,7 @@ print(response, 200 if response else 204) | `convert_camel_case=True` | removed. Name your methods and parameters as clients call them | | `basic_logging=True`, `trim_log_values=True` | removed. Configure the `jsonrpcserver` logger yourself | | a `.jsonrpcserverrc` config file | removed. Pass options to `dispatch` | -| `debug=True` | still there. In 5.0.10 it controls whether exception messages reach the client | +| `debug=True` | removed in 5.0.0, so 5.0.0 to 5.0.9 always send exception messages to the client. Back in 5.0.10, where it works as in 4.x: off by default | Code written for 4.x that 5.x can't run gives clear errors in most cases. The removed keywords raise `TypeError`, and `response.wanted` raises @@ -119,7 +120,7 @@ Pass `debug=True` in development to get the message back in the response. See [Security](security.md). **Custom validators see one request at a time.** In a batch, the `validator` -is called once for each request, with that request's dict. In 5.0.9 it was +is called once for each request, with just that request. In 5.0.9 it was called once with the whole list. A validator that enforced a rule about the whole batch, such as a size limit, silently stops doing it. Use `max_batch_size` instead. See [Validation](validation.md). diff --git a/docs/reference.md b/docs/reference.md index 4460c48..c824a74 100644 --- a/docs/reference.md +++ b/docs/reference.md @@ -104,8 +104,8 @@ the request's params. `data=NODATA` means the error has no `data` member. ## Deprecated -These still work in 5.x, but give a `DeprecationWarning` and will be removed -in 6.0. +These still work in 5.x and will be removed in 6.0. The three functions give +a `DeprecationWarning`. `ResponseType` gives none, but use `Response`. ::: jsonrpcserver.response.serialize_error diff --git a/docs/security.md b/docs/security.md index 1183be8..4cd3dc2 100644 --- a/docs/security.md +++ b/docs/security.md @@ -184,8 +184,10 @@ it's listening when it starts, including a note when that's every interface. Python's `json` module accepts `NaN`, `Infinity` and numbers like `1e400` in a request, which aren't valid JSON. [Validation](validation.md#nan-infinity-and-huge-numbers) -shows a stricter `deserializer` that rejects them. From 5.0.10, responses -never contain them: the default serializer sends an Internal error instead. +shows a stricter `deserializer` that rejects them. From 5.0.10, `dispatch` +and `async_dispatch` never write them with the default serializer: they send +an Internal error instead. `dispatch_to_serializable` gives you the float as +it is, so if your framework serializes the dict, check how it treats them. ## Reporting a vulnerability diff --git a/docs/validation.md b/docs/validation.md index ed38ee4..cd56e6a 100644 --- a/docs/validation.md +++ b/docs/validation.md @@ -39,8 +39,10 @@ because the request couldn't be trusted. ## A custom validator -Pass `validator` to use your own. It gets the parsed request, a dict, and -should raise an exception of any kind if the request is invalid. What it +Pass `validator` to use your own. It gets the parsed request, usually a +dict, and should raise an exception of any kind if the request is invalid. +It can also get anything else that parsed, such as a number, a string or an +empty list, so don't assume a dict. What it returns is ignored. In a batch, it's called once for each request. This one runs the default checks, then refuses requests without an `id`, so @@ -102,8 +104,9 @@ Without it, `dispatch` still never raises, but bad requests get odd answers: A request with no `jsonrpc` member runs, and params that aren't a list or an object are ignored. A request with no `method` gets a -32000 "Server error", -and jsonrpcserver logs it as an error of its own. Keep validation on for -anything that strangers can reach. +and jsonrpcserver logs it as an error of its own. An empty batch, `[]`, gets +no response at all instead of an error. Keep validation on for anything that +strangers can reach. ## NaN, Infinity and huge numbers @@ -140,6 +143,7 @@ def strict_loads(request: str) -> Any: '{"jsonrpc": "2.0", "error": {"code": -32700, "message": "Parse error", "data": "NaN is not valid JSON"}, "id": null}' ``` -Responses never contain them in 5.0.10: the default serializer refuses to -write them and sends an Internal error instead. 5.0.9 writes them as they -are. +In 5.0.10, `dispatch` and `async_dispatch` never write them with the default +serializer. It refuses, and the client gets an Internal error instead. 5.0.9 +writes them as they are. `dispatch_to_serializable` returns the float itself, +so if your framework serializes the dict, check how it treats them.