sillo-graphql 1.0.0a1__tar.gz

sillo_graphql-1.0.0a1/.github/workflows/ci.yml

@@ -0,0 +1,165 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+# The framework this package extends, installed from the 1.0 branch rather
+# than from PyPI: this package tracks `main`, not the last tag cut from it.
+# (`sillo-framework>=1.0` does resolve on PyPI now that 1.0.0a1 is published,
+# but only to that pre-release.)
+#
+# Installed first and explicitly, and this package then installed with
+# `--no-deps`, so the declared floor is not re-resolved against PyPI.
+env:
+  FRAMEWORK: "git+https://github.com/sillohq/core.git@main"
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          pip install ruff mypy
+          pip install "$FRAMEWORK" strawberry-graphql
+
+      - name: Lint
+        run: ruff check sillo_graphql tests
+
+      - name: Format
+        run: ruff format --check sillo_graphql tests
+
+      - name: Types
+        run: mypy sillo_graphql
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          pip install "$FRAMEWORK" strawberry-graphql
+          pip install pytest pytest-asyncio pytest-cov httpx
+          pip install -e . --no-deps
+
+      # `fail_under = 100` lives in pyproject, so a line that stops being
+      # covered fails here rather than being noticed later.
+      - name: Test
+        run: pytest --cov --cov-report=term-missing
+
+  wheel:
+    name: sillo_graphql, from a built wheel
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      # The newest supported interpreter. The matrix already exercises the
+      # package on every version through the editable install, so the one place
+      # worth a separate job is the wheel path on the interpreter most likely
+      # to have changed underneath site-packages.
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.14"
+
+      - name: Build the wheel
+        run: |
+          python -m pip install --upgrade pip build
+          python -m build --wheel -o dist .
+
+      # Two distributions writing into one package directory goes wrong in both
+      # directions, so the wheel must add a top-level `sillo_graphql` and
+      # nothing else. Checked on the artefact, not on an install, because an
+      # install can hide it behind whatever is already there.
+      - name: The wheel ships sillo_graphql only
+        run: |
+          python - <<'PY'
+          import glob
+          import zipfile
+
+          names = zipfile.ZipFile(glob.glob("dist/*.whl")[0]).namelist()
+          intruders = [name for name in names if name.startswith("sillo/")]
+          assert not intruders, f"wheel writes into sillo/: {intruders}"
+          strays = [n for n in names if n.endswith(".pth") or n.startswith("sillo-stubs/")]
+          assert not strays, f"alias machinery is back in the wheel: {strays}"
+          assert "sillo_graphql/py.typed" in names, "the PEP 561 marker is missing"
+          print("\n".join(sorted(names)))
+          PY
+
+      # Against a real install, not the checkout: an editable install can
+      # import what the wheel does not actually ship.
+      - name: sillo_graphql imports, and sillo.graphql does not
+        run: |
+          python -m venv /tmp/v
+          /tmp/v/bin/pip install -q "$FRAMEWORK" strawberry-graphql mypy
+          /tmp/v/bin/pip install -q --no-deps dist/*.whl
+          /tmp/v/bin/python - <<'PY'
+          import os
+
+          import sillo
+          import sillo_graphql  # noqa: F401
+
+          package = os.path.dirname(sillo.__file__)
+          assert "graphql" not in os.listdir(package), "something wrote into sillo/"
+
+          # The package used to ship a .pth aliasing `sillo.graphql` onto it.
+          # That is gone, and the framework has not shipped a module of that
+          # name since 1.0, so the import must simply fail.
+          try:
+              import sillo.graphql  # noqa: F401
+          except ImportError:
+              print("sillo_graphql imports; sillo.graphql does not resolve")
+          else:
+              raise AssertionError("sillo.graphql still resolves")
+          PY
+
+      # Types come from the package's own annotations plus py.typed now, not
+      # from a separate set of stubs that had to be kept in step with them.
+      - name: Type checkers resolve the package
+        run: |
+          cat > /tmp/check.py <<'PY'
+          from sillo_graphql import Graph, Limits, not_found
+
+          limits: Limits = Limits(depth=3)
+          error = not_found("gone")
+          graph: type[Graph] = Graph
+          PY
+          /tmp/v/bin/python -m mypy /tmp/check.py
+
+      # Removing either distribution must leave the other whole. The failure
+      # this guards against is an empty `sillo/` left standing with no
+      # __init__.py in it, which shadows a later reinstall.
+      #
+      # Run from /tmp, not the checkout: with the repository on sys.path these
+      # would import the source tree and prove nothing about the install.
+      - name: Uninstalling either one leaves the other intact
+        working-directory: /tmp
+        run: |
+          /tmp/v/bin/pip uninstall -y -q sillo-graphql
+          /tmp/v/bin/python -c "import sillo; print('framework survives')"
+          /tmp/v/bin/pip install -q --no-deps $GITHUB_WORKSPACE/dist/*.whl
+          /tmp/v/bin/pip uninstall -y -q sillo-framework
+          /tmp/v/bin/python - <<'PY'
+          import importlib.util
+
+          # `sillo_graphql` needs the framework to import, so it is not asked
+          # to. What must be true is that nothing of `sillo` is left behind:
+          # a directory with no __init__.py in it would shadow a reinstall.
+          assert importlib.util.find_spec("sillo") is None, "headless sillo/ left behind"
+          print("no headless sillo/")
+          PY

sillo_graphql-1.0.0a1/.github/workflows/release.yml

@@ -0,0 +1,90 @@
+name: release
+
+on:
+  push:
+    tags:
+      - 'sillo-graphql-v*'
+
+# The framework this package extends. `sillo-framework>=1.0` now resolves on
+# PyPI -- 1.0.0a1 is published -- but a pre-release only, and this package
+# tracks the 1.0 branch rather than the last tag cut from it. Install the
+# framework from `main`, then this package with `--no-deps`.
+env:
+  FRAMEWORK: "git+https://github.com/sillohq/core.git@main"
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      # Trusted publishing, used when PYPI_TOKEN is not set.
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Read the tag
+        id: version
+        run: echo "version=${GITHUB_REF_NAME#sillo-graphql-v}" >> "$GITHUB_OUTPUT"
+
+      # Three places carry the version; a release that reports one it is not is
+      # worse than one that fails to build.
+      - name: The tag, pyproject.toml and __version__ must agree
+        run: |
+          tag='${{ steps.version.outputs.version }}'
+          project=$(grep -m1 '^version = ' pyproject.toml | cut -d'"' -f2)
+          module=$(grep -m1 '^__version__' sillo_graphql/__init__.py | cut -d'"' -f2)
+
+          echo "tag=$tag pyproject=$project module=$module"
+
+          if [ "$tag" != "$project" ] || [ "$tag" != "$module" ]; then
+            echo "These disagree. Bump all three and tag again."
+            exit 1
+          fi
+
+      - name: Install
+        run: |
+          uv venv
+          uv pip install "$FRAMEWORK" strawberry-graphql
+          uv pip install pytest pytest-asyncio pytest-cov httpx
+          uv pip install -e . --no-deps
+
+      - name: Test
+        run: uv run pytest -q
+
+      - name: Build
+        run: uv build
+
+      # The collision this layout exists to avoid: two distributions writing
+      # into one package directory. Checked on the artefact, not on an install.
+      - name: The wheel must write nothing into sillo/
+        run: |
+          python - <<'PY'
+          import glob
+          import zipfile
+
+          names = zipfile.ZipFile(glob.glob("dist/*.whl")[0]).namelist()
+          intruders = [n for n in names if n.startswith("sillo/")]
+          assert not intruders, f"wheel writes into sillo/: {intruders}"
+          assert "sillo_graphql/__init__.py" in names, "the package is missing"
+          assert "sillo_graphql/py.typed" in names, "the PEP 561 marker is missing"
+          strays = [n for n in names if n.endswith(".pth") or n.startswith("sillo-stubs/")]
+          assert not strays, f"alias machinery is back in the wheel: {strays}"
+          print("wheel ships sillo_graphql only, and stays out of sillo/")
+          PY
+
+      - name: Publish
+        env:
+          UV_PUBLISH_TOKEN: ${{ secrets.PYPI_TOKEN }}
+        run: |
+          if [ -n "$UV_PUBLISH_TOKEN" ]; then
+            uv publish
+          else
+            uv publish --trusted-publishing always
+          fi

sillo_graphql-1.0.0a1/.gitignore

@@ -0,0 +1,15 @@
+__pycache__/
+*.py[cod]
+.venv/
+dist/
+build/
+*.egg-info/
+.coverage
+.coverage.*
+htmlcov/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.DS_Store
+
+.venv*/

sillo_graphql-1.0.0a1/CHANGELOG.md

@@ -0,0 +1,124 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
+adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [1.0.0a1] - 2026-09-13
+
+First alpha, released alongside `sillo-framework` 1.0.0a1. Install with
+`pip install --pre sillo-graphql==1.0.0a1`.
+
+An alpha: this is what 1.0 is expected to look like, but the API is not frozen
+yet and may still change before `1.0.0`.
+
+### Removed
+
+- **The `sillo.graphql` import alias.** `sillo_graphql` is now the only import
+  path:
+
+  ```python
+  from sillo_graphql import Graph, field    # was: from sillo.graphql import ...
+  ```
+
+  The alias was a meta-path finder in `_sillo_graphql_bootstrap.py`, a
+  `sillo_graphql.pth` registering it at interpreter startup, and PEP 561 stubs
+  under `sillo-stubs/` to serve type checkers, which never run import hooks.
+  That is three mechanisms, a `.pth` executing on every interpreter start in
+  every environment the package is installed in, and a second set of type
+  declarations to keep in step with the real ones — so that an import could
+  read as part of the framework. A plain top-level package needs none of it.
+
+  `_sillo_graphql_bootstrap.py`, `sillo_graphql.pth` and `sillo-stubs/` are
+  gone, along with the `force-include` blocks that shipped them.
+
+### Added
+
+- **`sillo_graphql/py.typed`.** The package claimed `Typing :: Typed` but
+  shipped no PEP 561 marker of its own — type checkers were served entirely by
+  `sillo-stubs/`. Removing the stubs without this would have silently made the
+  package untyped for consumers. Its inline annotations are now the single
+  source of truth.
+
+### Fixed
+
+- **Resolver `Depend(...)` stopped resolving on newer framework builds.** Sillo
+  v1's `get_dependant` treats a callable's first parameter as the context slot
+  and only scans the parameters after it for `Depend` markers. The stand-in
+  signature this package builds for a resolver's dependencies had no such slot,
+  so its first dependency was skipped and injected as `None`. It now carries a
+  leading context parameter. A resolver dependency that took no arguments must
+  now take a leading one (`def get_db(_): ...`), matching the framework's rule
+  for every dependency.
+
+### Added
+
+- A `release` workflow: pushing a `sillo-graphql-v<version>` tag checks the
+  three version strings agree, runs the suite, builds, verifies the wheel
+  carries the alias `.pth` and the PEP 561 stubs and writes nothing into
+  `sillo/`, and publishes (trusted publishing, or `PYPI_TOKEN`).
+
+## [0.1.0]
+
+First release. Extracted from the framework's `sillo.graphql` module, and
+rebuilt around it rather than moved.
+
+### Added
+
+- `Graph`, built and then mounted, matching how every other subsystem attaches
+  to an application. Mounts on a `SilloApp` or a `Router`.
+- `field`, `mutation` and `subscription` decorators that adapt `sillo`'s
+  handler convention onto Strawberry resolvers: `ctx` and `Depend` parameters
+  are injected and stripped from the schema; everything else is a GraphQL
+  argument. Dependencies are resolved through the framework's own solver, so
+  one operation shares one dependency cache.
+- `GraphContext`, a typed context carrying the connection, a response handle
+  for setting status, headers and cookies from a resolver, the loader registry
+  and the authenticated user. Also a `Mapping`, so `info.context["ctx"]` keeps
+  working.
+- Static cost analysis before execution: depth, aliases, breadth, document
+  tokens, and a weighted cost with list multipliers derived from `first`,
+  `last`, `limit` and friends. `@field(cost=...)` prices a field.
+- Error policy: free builders (`not_found`, `forbidden`, `unauthenticated`,
+  `bad_input`, `conflict`, `too_many_requests`, `internal`) with stable
+  `extensions.code`, masking of unexpected exceptions, `@graph.on_error`
+  mapping, and a correlation id on every error.
+- Request-scoped `DataLoader` batching via `@graph.loader`, with cache
+  priming, `load_many`, batch-size chunking and per-key error results.
+- Subscriptions over `graphql-transport-ws`, with an initialisation timeout,
+  ping/pong, duplicate-id detection and cancellation of every operation when
+  the socket closes. `@graph.on_connect` authenticates from the
+  `connection_init` payload.
+- Subscriptions over `text/event-stream` (`sse=True`) for clients that cannot
+  hold a socket open.
+- GraphQL-over-HTTP: content negotiation between
+  `application/graphql-response+json` and legacy `application/json`, correct
+  status codes, `GET` queries with mutations refused, `application/graphql`
+  bodies, form bodies, capped sequential batching, and body size limits.
+- File uploads per the GraphQL multipart request spec, with per-file, per-count
+  and per-request size limits and a content-type allow-list. Off by default.
+- Persisted operations: APQ with hash verification, and a trusted-document
+  manifest that refuses everything not in it.
+- A bundled explorer with no external requests, so it works offline and under
+  a strict CSP. GraphiQL from a CDN remains available with `IDE(assets="cdn")`.
+- `Metrics`, `OperationLog` and an OpenTelemetry hook, all through
+  `@graph.on_operation`.
+- `GraphClient` and `SubscriptionStream` test helpers.
+- `sillo.graphql` as an import alias for `sillo_graphql`, via a `.pth`-loaded
+  meta-path finder and PEP 561 partial stubs. Nothing is written into the
+  framework's package directory, and the alias refuses rather than shadows a
+  framework that still ships its own `sillo.graphql`.
+
+### Changed from the framework's `sillo.graphql`
+
+- The explorer is **off** by default, and introspection with it.
+- Resolver exceptions are **masked** by default.
+- Depth and cost limits are **enforced** by default.
+- A request with no document is a 400, not a 500.
+- The endpoint is excluded from the OpenAPI document, which described it
+  incorrectly.
+
+[Unreleased]: https://github.com/sillohq/graphql/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/sillohq/graphql/releases/tag/v0.1.0

sillo_graphql-1.0.0a1/LICENSE

@@ -0,0 +1,27 @@
+BSD 3-Clause License
+
+Copyright (c) 2024-present, sillo-Labs OSS.
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification,
+are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

sillo_graphql-1.0.0a1/PKG-INFO

@@ -0,0 +1,250 @@
+Metadata-Version: 2.5
+Name: sillo-graphql
+Version: 1.0.0a1
+Summary: Production GraphQL for Sillo — sillo-style resolvers with DI, subscriptions, cost limits, persisted operations and batching.
+Project-URL: Homepage, https://sillo.build
+Project-URL: Documentation, https://docs.sillo.build/packages/graphql/
+Project-URL: Source, https://github.com/sillohq/graphql
+Project-URL: Changelog, https://github.com/sillohq/graphql/blob/main/CHANGELOG.md
+Author-email: Chidebele Dunamis <techwithdunamix@gmail.com>
+License-Expression: BSD-3-Clause
+License-File: LICENSE
+Keywords: api,asgi,dataloader,graphql,persisted-queries,sillo,strawberry,subscriptions
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: sillo-framework>=1.0
+Requires-Dist: strawberry-graphql>=0.219.0
+Provides-Extra: dev
+Requires-Dist: httpx>=0.27; extra == 'dev'
+Requires-Dist: mypy>=1.11; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# sillo-graphql
+
+Production GraphQL for [Sillo](https://sillo.build). Installs as
+`sillo-graphql`, imports as `sillo_graphql`.
+
+Strawberry owns the schema. This package owns everything around it — the
+transports, the safety, and the observability.
+
+```bash
+pip install sillo-graphql
+```
+
+```python
+import strawberry
+from sillo import Depend, HttpContext, SilloApp
+from sillo_graphql import Graph, Limits, field
+
+@strawberry.type
+class Query:
+    @field
+    async def me(ctx: HttpContext, db=Depend(get_db)) -> User:
+        return await db.users.get(ctx.user.id)
+
+app = SilloApp()
+Graph(strawberry.Schema(query=Query), limits=Limits(depth=8)).mount(app)
+```
+
+## Resolvers that read like handlers
+
+A `sillo` route handler takes the context first and declares what else it
+needs. So does a resolver here:
+
+```python
+@field
+async def posts(ctx: HttpContext, db=Depend(get_db), limit: int = 10) -> list[Post]:
+    return await db.posts.recent(limit)
+```
+
+One rule: **`ctx` and anything defaulted to `Depend` are injected and never
+appear in the schema; every other parameter is a GraphQL argument.** So this
+field takes exactly one argument, `limit`.
+
+Dependencies are resolved by the framework's own solver, with the framework's
+own pre-flattened execution plan — two resolvers in one operation that both
+ask for `Depend(get_db)` are handed the same session.
+
+## Configuration
+
+```python
+graph = Graph(
+    schema,
+    path="/graphql",
+    ide=False,                                       # explorer, off by default
+    introspection=False,                             # off by default
+    subscriptions=True,
+    auth=Bearer(),                                   # the route's auth= gate
+    limits=Limits(depth=10, cost=1_000, aliases=15),
+    errors=ErrorPolicy(mask=True),
+    transport=Transport(get_queries=True, batch=10),
+    uploads=Uploads(enabled=True, max_size="10MB"),
+    persisted=Persisted(apq=True, trusted="operations.json"),
+)
+graph.mount(app)
+```
+
+Common knobs are keyword arguments; the deeper ones are policy objects, the
+same split the framework makes between arguments on `SilloApp` and objects
+like `CSRFConfig`.
+
+Every default is chosen for a public endpoint.
+
+## What it does
+
+### Cost limits, enforced before execution
+
+Depth, aliases, breadth and document size, plus a weighted cost that
+understands lists — a field returning a list multiplies everything under it, by
+the page size the caller asked for when that is knowable.
+
+```python
+@field(cost=25)
+async def search(ctx: HttpContext, term: str) -> list[Hit]: ...
+```
+
+An operation over budget is refused with `OPERATION_TOO_COMPLEX` and the limit
+it passed, before a single resolver runs. Refusing afterwards would mean having
+already done the work.
+
+### Errors that say what happened, and no more
+
+```python
+from sillo_graphql import forbidden, not_found
+
+@field
+async def post(ctx: HttpContext, id: int) -> Post:
+    found = await Post.objects.get_or_none(id=id)
+    if found is None:
+        raise not_found("No such post")     # extensions.code == "NOT_FOUND"
+    return found
+```
+
+Free builders, like the framework's `json()` and `text()`. Errors raised this
+way are deliberate and reach the client. An exception that escapes a resolver
+is masked, logged with its traceback, and reported as `INTERNAL_SERVER_ERROR` —
+because what it said may name a host, a table or a credential.
+
+Map your own:
+
+```python
+@graph.on_error(RecordNotFound)
+def _(exc): return not_found(str(exc))
+```
+
+### Batching, so a graph query is not a table scan per node
+
+```python
+@graph.loader
+async def load_author(keys: list[int]) -> list[User]:
+    rows = await User.objects.filter(id__in=keys).all()
+    return align(rows, keys)
+
+@field
+async def author(ctx: HttpContext, root: Post) -> User:
+    return await load_author(root.author_id)
+```
+
+Keys asked for by sibling fields in the same tick become one call. State is per
+operation, so two concurrent requests never share a cache.
+
+### Subscriptions that exist
+
+`graphql-transport-ws` over the framework's own WebSocket layer, with an
+initialisation timeout, ping/pong keepalive, and cancellation in a `finally` so
+an operation cannot outlive its socket. Authentication belongs in
+`connection_init`, because a browser cannot set headers on a WebSocket
+handshake:
+
+```python
+@graph.on_connect
+async def authenticate(socket, params):
+    token = params.get("authorization")
+    if not token:
+        raise unauthenticated("A token is required")
+    return {"user": await user_for(token)}
+```
+
+The same subscriptions are available over `text/event-stream` with `sse=True`,
+for clients that cannot hold a socket open.
+
+### The rest of the HTTP surface
+
+Batched operations (capped, sequential), `GET` for queries with mutations
+refused, `application/graphql` bodies, file uploads per the multipart request
+spec, and content negotiation between `application/graphql-response+json` — the
+spec's status codes — and legacy `application/json`, which stays always-200 for
+the clients that expect it.
+
+### Persisted operations
+
+APQ saves bandwidth. A trusted-document manifest is the one that matters: with
+`Persisted(trusted="operations.json")` the endpoint executes nothing else, so
+the workload becomes finite and known.
+
+### Knowing what it is doing
+
+```python
+graph.on_operation(OperationLog(slower_than=0.5))
+
+metrics = Metrics()
+graph.on_operation(metrics)
+```
+
+Per operation, not per path: `p99` on `POST /graphql` averages over work that
+has nothing in common.
+
+## Testing
+
+```python
+from sillo_graphql.testing import GraphClient
+
+def test_me():
+    with GraphClient(app) as gql:
+        result = gql.query("{ me { email } }")
+        assert result.ok
+        assert result["me"]["email"] == "a@b.c"
+
+async def test_prices():
+    async with GraphClient(app).subscribe(PRICES, symbol="ACME") as stream:
+        assert (await stream.next())["prices"]["last"] == 10
+```
+
+## Migrating from `sillo.graphql` in the framework
+
+| before | now |
+| --- | --- |
+| `GraphQL(app, schema, path=, graphiql=True)` | `Graph(schema, path=, ide=False).mount(app)` |
+| `info.context["ctx"]` | a `ctx: HttpContext` parameter |
+| `self` / `info` resolver convention | `ctx` first, like every handler |
+| — | `Depend(...)`, `@graph.loader`, `@graph.on_error` |
+| errors leaked, IDE on, no limits | masked, IDE off, depth and cost enforced |
+
+`info.context["ctx"]` still works — the context is a `Mapping` — so a schema
+can migrate one resolver at a time.
+
+## Requirements
+
+Python 3.10+, `sillo-framework` 1.0 or newer, `strawberry-graphql`.
+
+1.0 is the floor because the resolver bridge is built on the context-handler
+API. Versions before 1.0 also shipped a `sillo.graphql` of their own, which is
+unrelated to this package and is what the table above migrates from.
+
+## License
+
+BSD-3-Clause.