spring-runtime-mcp 0.2.0__py3-none-any.whl

spring_runtime_mcp/server.py

@@ -0,0 +1,322 @@
+"""Official MCP SDK host over STDIO. Tool calls stay on the read-only path."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import sys
+import time
+from dataclasses import replace
+from typing import Any, TextIO, cast
+
+import mcp.types as types
+from jsonschema import Draft202012Validator, FormatChecker
+from jsonschema.exceptions import ValidationError
+from mcp.server.lowlevel import Server
+from mcp.server.stdio import stdio_server
+from mcp.shared.exceptions import MCPError
+from mcp.shared.message import SessionMessage
+
+from . import __version__
+from .contracts.definitions import list_tools
+from .models.source_catalog import SourceCatalog
+from .models.timestamps import parse_rfc3339
+from .models.common import CALL_BUDGET, CallBudget, NormalizationError
+from .policy.sanitization import SanitizerPipeline
+from .policy.configuration import ConfigReadPolicy
+from .snapshots import SnapshotStore
+from .services import Services
+from .diagnostics import failed
+from .tools.registry import call_tool, validate_handlers
+from .tools.support import TOOL_TIMEOUT_SECONDS
+from .transport.actuator_http import ActuatorHttpTransport
+from .transport.response_gate import ENDPOINTS, ResponseGateReader
+from .transport.responses import serialize_response, tool_result
+from .transport.responses import MAX_RESPONSE_BYTES, _check_request_id
+
+MAX_FRAME_BYTES = 64 * 1024
+SERVER_NAME = "spring-runtime-mcp"
+SERVER_VERSION = __version__
+# The SDK stamps this on every 2026-era result; the budget measurement includes
+# it so a response that fits our cap also fits the stamped wire frame.
+SERVER_INFO_META: dict[str, Any] = {
+    "io.modelcontextprotocol/serverInfo": {
+        "name": SERVER_NAME,
+        "version": SERVER_VERSION,
+    }
+}
+_FORMAT_CHECKER = FormatChecker()
+
+
+def _is_rfc3339(value: object) -> bool:
+    return not isinstance(value, str) or parse_rfc3339(value) is not None
+
+
+_FORMAT_CHECKER.checkers["date-time"] = (_is_rfc3339, ())
+
+
+def build_services(
+    base_url: str,
+    target_id: str = "local",
+    timeout: float = 5.0,
+    *,
+    config_policy: ConfigReadPolicy | None = None,
+    source_catalog: SourceCatalog | None = None,
+    bearer_token: str | None = None,
+) -> Services:
+    """Assemble the real reader. No connection is opened until a tool calls it."""
+    targets = frozenset({target_id})
+    transport = ActuatorHttpTransport(
+        base_url, targets=targets, bearer_token=bearer_token
+    )
+    reader = ResponseGateReader(
+        transport,
+        targets=targets,
+        enabled_endpoints=ENDPOINTS - {"env", "configprops"}
+        if config_policy is None
+        else ENDPOINTS,
+        timeout=timeout,
+    )
+    if source_catalog is None:
+        # Missing workspace facts are recorded provenance, not absent code.
+        catalog = SourceCatalog(target_id, None, {}, (), ("SOURCE_CATALOG_UNPROVIDED",))
+    elif source_catalog.target_id != target_id:
+        raise ValueError("SOURCE_TARGET_MISMATCH")
+    else:
+        catalog = source_catalog
+    return Services(
+        reader,
+        catalog,
+        SanitizerPipeline(
+            known_secrets=() if bearer_token is None else (bearer_token,)
+        ),
+        SnapshotStore(),
+        targets=targets,
+        config_policy=config_policy,
+    )
+
+
+def _tool_models() -> list[types.Tool]:
+    return [types.Tool.model_validate(item, by_alias=True) for item in list_tools()]
+
+
+def _valid_envelope(schema: dict[str, Any], envelope: object) -> bool:
+    if not isinstance(envelope, dict):
+        return False
+    try:
+        Draft202012Validator(schema, format_checker=_FORMAT_CHECKER).validate(envelope)
+    except ValidationError:
+        return False
+    return True
+
+
+async def _call_tool(
+    ctx: Any, params: types.CallToolRequestParams, services: Services
+) -> types.CallToolResult:
+    name = params.name
+    catalog = {item["name"]: item for item in list_tools()}
+    arguments = params.arguments or {}
+    if name not in catalog:
+        # Unknown names are protocol errors, not tool execution results.
+        raise MCPError(-32602, "UNKNOWN_TOOL")
+    try:
+        Draft202012Validator(
+            catalog[name]["inputSchema"], format_checker=_FORMAT_CHECKER
+        ).validate(arguments)
+    except ValidationError:
+        return _result(failed("INVALID_ARGUMENT"), params_id(ctx))
+    try:
+        envelope = await call_tool(name, arguments, services)
+        if not _valid_envelope(catalog[name]["outputSchema"], envelope):
+            source = envelope.get("source") if isinstance(envelope, dict) else None
+            target = source.get("targetId") if isinstance(source, dict) else None
+            envelope = failed(
+                "OUTPUT_CONTRACT_VIOLATION",
+                target if isinstance(target, str) else "local",
+            )
+    except Exception:
+        envelope = failed("INTERNAL_ERROR")
+    return _result(envelope, params_id(ctx))
+
+
+def params_id(ctx: Any) -> str | int | None:
+    request_id = getattr(ctx, "request_id", None)
+    return request_id if isinstance(request_id, (str, int)) else None
+
+
+def _result(
+    envelope: dict[str, Any], request_id: str | int | None
+) -> types.CallToolResult:
+    fallback_id = request_id
+    try:
+        # Enforce the full-frame budget, server stamp included.
+        serialize_response(envelope, request_id, server_meta=SERVER_INFO_META)
+    except NormalizationError as exc:
+        # Preserve the real rejection reason; an unsafe/sanitization failure is
+        # not the same failure as an oversized frame. An invalid identity cannot
+        # be echoed, so the safe fallback uses a null id.
+        envelope = failed(exc.code)
+        if exc.code == "INVALID_REQUEST_ID":
+            fallback_id = None
+        serialize_response(envelope, fallback_id, server_meta=SERVER_INFO_META)
+    except Exception:
+        envelope = failed("INTERNAL_ERROR")
+        serialize_response(envelope, fallback_id, server_meta=SERVER_INFO_META)
+    return types.CallToolResult.model_validate(tool_result(envelope), by_alias=True)
+
+
+def build_server(services: Services) -> Server[Services]:
+    validate_handlers()
+
+    async def list_tools_handler(
+        ctx: Any, params: types.PaginatedRequestParams | None
+    ) -> types.ListToolsResult:
+        # Re-publish each committed contract entry unchanged, outputSchema included.
+        return types.ListToolsResult(tools=_tool_models())
+
+    async def call_tool_handler(
+        ctx: Any, params: types.CallToolRequestParams
+    ) -> types.CallToolResult:
+        scope = CallBudget(time.monotonic() + TOOL_TIMEOUT_SECONDS)
+        token = CALL_BUDGET.set(scope)
+        try:
+            async with asyncio.timeout(scope.check()):
+                result = await _call_tool(ctx, params, services)
+                scope.check()
+                return result
+        except (TimeoutError, NormalizationError):
+            # Expired scopes cannot be used while serializing the safe fallback.
+            CALL_BUDGET.reset(token)
+            token = CALL_BUDGET.set(None)
+            return _result(failed("TARGET_TIMEOUT"), params_id(ctx))
+        finally:
+            CALL_BUDGET.reset(token)
+
+    return Server(
+        SERVER_NAME,
+        version=SERVER_VERSION,
+        on_list_tools=list_tools_handler,
+        on_call_tool=call_tool_handler,
+    )
+
+
+class _BoundedLineReader:
+    """UTF-8 stdin lines capped at the frame limit, one byte over so overflow is visible."""
+
+    def __init__(self, binary: Any, limit: int = MAX_FRAME_BYTES) -> None:
+        self._binary = binary
+        self._limit = limit
+        self.oversized = False
+        self.invalid_identity = False
+
+    def readline(self, size: int = -1) -> str:
+        line = self._binary.readline(self._limit + 1)
+        if len(line) > self._limit:
+            self.oversized = True
+            return ""
+        decoded: str = line.decode("utf-8", errors="replace")
+        try:
+            message = json.loads(decoded)
+            identifier = message.get("id") if isinstance(message, dict) else None
+            if type(identifier) in (str, int):
+                _check_request_id(identifier)
+        except (ValueError, UnicodeError, RecursionError) as exc:
+            if isinstance(exc, NormalizationError):
+                self.invalid_identity = True
+                return ""
+        return decoded
+
+    async def read_line(self) -> str:
+        # The stdio transport awaits this; the bounded read stays off the loop.
+        return await asyncio.to_thread(self.readline)
+
+    def __aiter__(self) -> _BoundedLineReader:
+        return self
+
+    async def __anext__(self) -> str:
+        line = await self.read_line()
+        if not line:
+            raise StopAsyncIteration
+        return line
+
+
+class _BoundedWriteStream:
+    """Check SDK-serialized tool frames at the last send boundary."""
+
+    def __init__(self, stream: Any) -> None:
+        self._stream = stream
+
+    async def __aenter__(self) -> _BoundedWriteStream:
+        await self._stream.__aenter__()
+        return self
+
+    async def aclose(self) -> None:
+        await self._stream.aclose()
+
+    async def __aexit__(self, *args: Any) -> None:
+        await self._stream.__aexit__(*args)
+
+    async def send(self, item: SessionMessage) -> None:
+        message = item.message
+        if (
+            isinstance(message, types.JSONRPCResponse)
+            and "structuredContent" in message.result
+        ):
+            size = len(
+                message.model_dump_json(by_alias=True, exclude_unset=True).encode(
+                    "utf-8"
+                )
+            )
+            if size > MAX_RESPONSE_BYTES:
+                message = types.JSONRPCResponse(
+                    jsonrpc="2.0",
+                    id=message.id,
+                    result=tool_result(
+                        failed("RESPONSE_TOO_LARGE"), server_meta=SERVER_INFO_META
+                    ),
+                )
+                _check_request_id(message.id)
+                if (
+                    len(
+                        message.model_dump_json(
+                            by_alias=True, exclude_unset=True
+                        ).encode("utf-8")
+                    )
+                    > MAX_RESPONSE_BYTES
+                ):
+                    raise ValueError("RESPONSE_TOO_LARGE")
+                item = replace(item, message=message)
+        # The destination is the SDK's protocol stream, not a socket. Its stdio
+        # writer retains ownership of fd 1 and all JSON-RPC framing.
+        await self._stream.send(item)
+
+
+async def run_stdio(services: Services, stdout: TextIO | None = None) -> None:
+    """Serve MCP over the process's stdin/stdout until EOF.
+
+    A frame over the limit is rejected once and ends the session, so its
+    remaining bytes cannot be re-read as later requests.
+    """
+    reader = _BoundedLineReader(sys.stdin.buffer)
+    server = build_server(services)
+    # The SDK accepts a text-receive stream; the bounded reader implements the
+    # async iteration and read_line contract used by stdio_server.
+    async with stdio_server(stdin=cast(Any, reader)) as (read_stream, write_stream):
+        await server.run(
+            read_stream,
+            _BoundedWriteStream(write_stream),
+            server.create_initialization_options(),
+        )
+    if reader.oversized or reader.invalid_identity:
+        frame = json.dumps(
+            {
+                "jsonrpc": "2.0",
+                "id": None,
+                "error": {"code": -32600, "message": "INVALID_REQUEST"},
+            },
+            separators=(",", ":"),
+            sort_keys=True,
+        )
+        channel = stdout if stdout is not None else sys.stdout
+        channel.write(frame + "\n")
+        channel.flush()

spring_runtime_mcp/services.py

@@ -0,0 +1,44 @@
+"""Application services shared by all tools, with one target read coordinator."""
+
+from __future__ import annotations
+
+import asyncio
+from dataclasses import dataclass, field
+from typing import Protocol
+
+from .models.common import NormalizationError, ParsedObservation, remaining_seconds
+from .models.source_catalog import SourceCatalog
+from .policy.configuration import ConfigReadPolicy
+from .policy.sanitization import SanitizerPipeline
+from .snapshots import SnapshotStore
+
+
+class RuntimeReader(Protocol):
+    async def read(
+        self, target_id: str, endpoint_id: str, *, snapshot_id: str
+    ) -> ParsedObservation: ...
+
+
+@dataclass
+class Services:
+    reader: RuntimeReader
+    catalog: SourceCatalog
+    sanitizer: SanitizerPipeline
+    snapshots: SnapshotStore
+    targets: frozenset[str] = frozenset({"local"})
+    config_policy: ConfigReadPolicy | None = None
+    _read_slots: dict[str, asyncio.Semaphore] = field(default_factory=dict, init=False)
+
+    async def read(
+        self, target_id: str, endpoint_id: str, *, snapshot_id: str
+    ) -> ParsedObservation:
+        if target_id not in self.targets or self.catalog.target_id != target_id:
+            raise NormalizationError("TARGET_NOT_REGISTERED")
+        slot = self._read_slots.setdefault(target_id, asyncio.Semaphore(2))
+        # The outer tool deadline also includes waiting for this shared slot.
+        async with asyncio.timeout(remaining_seconds()):
+            async with slot:
+                return await asyncio.wait_for(
+                    self.reader.read(target_id, endpoint_id, snapshot_id=snapshot_id),
+                    timeout=remaining_seconds(5.0),
+                )

spring_runtime_mcp/snapshots.py

@@ -0,0 +1,340 @@
+"""Bounded in-memory cursor store; callers supply sanitized envelopes only."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import secrets
+import time
+from collections import OrderedDict
+from collections.abc import Callable
+from copy import deepcopy
+from dataclasses import asdict, dataclass
+from typing import Any
+
+from .models.common import NormalizationError
+from .models.queries import InspectBeansQuery
+from .policy.output_guard import ensure_safe_output
+from .policy.sanitization import SanitizerPipeline
+
+
+@dataclass(frozen=True)
+class _Entry:
+    data: bytes
+    query_digest: bytes
+    expires_at: float
+
+
+@dataclass
+class _PagedSnapshot:
+    header: bytes
+    items: tuple[bytes, ...]
+    query_digest: bytes
+    expires_at: float
+    size: int
+    policy: tuple[object, bytes] | None
+    references: int = 0
+
+
+@dataclass(frozen=True)
+class _PageEntry:
+    snapshot: _PagedSnapshot
+    offset: int
+
+    @property
+    def expires_at(self) -> float:
+        return self.snapshot.expires_at
+
+
+def page_envelope(envelope: dict[str, Any], items: list[Any]) -> dict[str, Any]:
+    """Copy only page metadata and selected records, never the unsent tail."""
+    result = {key: deepcopy(value) for key, value in envelope.items() if key != "data"}
+    result["data"] = {
+        key: deepcopy(value)
+        for key, value in envelope["data"].items()
+        if key != "items"
+    }
+    result["data"]["items"] = deepcopy(items)
+    return result
+
+
+class SnapshotStore:
+    """Opaque cursor handles bind a frozen result to all non-cursor arguments."""
+
+    def __init__(
+        self,
+        clock: Callable[[], float] = time.monotonic,
+        *,
+        ttl: float = 60.0,
+        max_bytes: int = 32 * 1024 * 1024,
+    ) -> None:
+        if not 0 < ttl <= 60 or not 0 < max_bytes <= 32 * 1024 * 1024:
+            raise ValueError("INVALID_SNAPSHOT_LIMITS")
+        self._clock = clock
+        self._ttl = ttl
+        self._max_bytes = max_bytes
+        self._size = 0
+        self._entries: OrderedDict[str, _Entry | _PageEntry] = OrderedDict()
+
+    @staticmethod
+    def _digest(query: InspectBeansQuery) -> bytes:
+        values = asdict(query)
+        values.pop("cursor", None)
+        encoded = json.dumps(
+            values,
+            sort_keys=True,
+            ensure_ascii=False,
+            separators=(",", ":"),
+            allow_nan=False,
+        ).encode("utf-8")
+        return hashlib.sha256(encoded).digest()
+
+    def _remove(self, token: str) -> None:
+        entry = self._entries.pop(token)
+        if isinstance(entry, _Entry):
+            self._size -= len(entry.data)
+        else:
+            self._size -= 256
+            entry.snapshot.references -= 1
+            if entry.snapshot.references == 0:
+                self._size -= entry.snapshot.size
+
+    def _prune(self) -> None:
+        now = self._clock()
+        for token in tuple(self._entries):
+            if self._entries[token].expires_at <= now:
+                self._remove(token)
+
+    def _token(self, sanitizer: SanitizerPipeline | None) -> str:
+        for _ in range(16):
+            token = secrets.token_urlsafe(32)
+            if token in self._entries:
+                continue
+            try:
+                ensure_safe_output({"nextCursor": token}, sanitizer=sanitizer)
+            except NormalizationError as exc:
+                if exc.code not in {"UNSAFE_OUTPUT", "UNTRUSTED_OUTPUT"}:
+                    raise
+                continue
+            return token
+        raise NormalizationError("UNSAFE_OUTPUT")
+
+    def put(
+        self,
+        envelope: dict[str, Any],
+        query: InspectBeansQuery,
+        *,
+        sanitizer: SanitizerPipeline | None = None,
+        expires_at: float | None = None,
+    ) -> str:
+        self._prune()
+        deadline = self._clock() + self._ttl
+        if expires_at is not None:
+            deadline = min(deadline, expires_at)
+        if deadline <= self._clock():
+            raise NormalizationError("CURSOR_EXPIRED")
+        ensure_safe_output(envelope, sanitizer=sanitizer)
+        try:
+            data = json.dumps(
+                envelope,
+                sort_keys=True,
+                ensure_ascii=False,
+                separators=(",", ":"),
+                allow_nan=False,
+            ).encode("utf-8")
+        except (TypeError, ValueError, UnicodeError):
+            raise NormalizationError("INVALID_RESPONSE") from None
+        if len(data) > self._max_bytes:
+            raise NormalizationError("SNAPSHOT_TOO_LARGE")
+        token = self._token(sanitizer)
+        while self._entries and self._size + len(data) > self._max_bytes:
+            self._remove(next(iter(self._entries)))
+        self._entries[token] = _Entry(data, self._digest(query), deadline)
+        self._size += len(data)
+        return token
+
+    def deadline(self, token: str, query: InspectBeansQuery) -> float:
+        """Continuations inherit the original observation's absolute expiry."""
+        self._prune()
+        entry = self._entries.get(token)
+        if entry is None:
+            raise NormalizationError("CURSOR_EXPIRED")
+        digest = (
+            entry.query_digest
+            if isinstance(entry, _Entry)
+            else entry.snapshot.query_digest
+        )
+        if not secrets.compare_digest(digest, self._digest(query)):
+            raise NormalizationError("CURSOR_QUERY_MISMATCH")
+        return entry.expires_at
+
+    def get(
+        self,
+        token: str,
+        query: InspectBeansQuery,
+        *,
+        sanitizer: SanitizerPipeline | None = None,
+    ) -> dict[str, Any]:
+        self._prune()
+        entry = self._entries.get(token)
+        if entry is None:
+            raise NormalizationError("CURSOR_EXPIRED")
+        digest = (
+            entry.query_digest
+            if isinstance(entry, _Entry)
+            else entry.snapshot.query_digest
+        )
+        if not secrets.compare_digest(digest, self._digest(query)):
+            raise NormalizationError("CURSOR_QUERY_MISMATCH")
+        self._entries.move_to_end(token)
+        if isinstance(entry, _PageEntry):
+            self._review(entry.snapshot, sanitizer)
+            paged = self._decode_page(entry, len(entry.snapshot.items))
+            ensure_safe_output(paged, sanitizer=sanitizer)
+            return paged
+        # Decoding produces a fresh mutable copy; callers cannot alter cached facts.
+        value: dict[str, Any] = json.loads(entry.data)
+        try:
+            ensure_safe_output(value, sanitizer=sanitizer)
+        except NormalizationError:
+            # A newly registered credential/policy may invalidate old facts.
+            # Evict rather than retaining a now-recognized secret in the cache.
+            self._remove(token)
+            raise
+        return value
+
+    def put_paged(
+        self,
+        envelope: dict[str, Any],
+        query: Any,
+        *,
+        offset: int,
+        sanitizer: SanitizerPipeline | None = None,
+        expires_at: float | None = None,
+    ) -> str:
+        """Freeze sanitized evidence once; continuations share encoded records."""
+        self._prune()
+        deadline = self._clock() + self._ttl
+        if expires_at is not None:
+            deadline = min(deadline, expires_at)
+        if deadline <= self._clock():
+            raise NormalizationError("CURSOR_EXPIRED")
+        ensure_safe_output(envelope, sanitizer=sanitizer)
+        items = envelope["data"]["items"]
+        if not 0 <= offset < len(items):
+            raise ValueError("INVALID_PAGE_OFFSET")
+
+        def encode(value: Any) -> bytes:
+            return json.dumps(
+                value,
+                sort_keys=True,
+                ensure_ascii=False,
+                separators=(",", ":"),
+                allow_nan=False,
+            ).encode("utf-8")
+
+        header = encode(page_envelope(envelope, []))
+        records = tuple(encode(item) for item in items)
+        size = len(header) + sum(len(item) + 32 for item in records) + 128
+        snapshot = _PagedSnapshot(
+            header,
+            records,
+            self._digest(query),
+            deadline,
+            size,
+            sanitizer.cache_revision if sanitizer is not None else None,
+        )
+        return self._register_page(snapshot, offset, sanitizer)
+
+    def _register_page(
+        self, snapshot: _PagedSnapshot, offset: int, sanitizer: SanitizerPipeline | None
+    ) -> str:
+        if snapshot.size + 256 > self._max_bytes:
+            raise NormalizationError("SNAPSHOT_TOO_LARGE")
+        token = self._token(sanitizer)
+        # Eviction may remove the last handle for this snapshot. Recompute its
+        # storage charge each iteration so continuation accounting stays exact.
+        while (
+            self._size + 256 + (snapshot.size if snapshot.references == 0 else 0)
+            > self._max_bytes
+        ):
+            self._remove(next(iter(self._entries)))
+        if snapshot.expires_at <= self._clock():
+            raise NormalizationError("CURSOR_EXPIRED")
+        if snapshot.references == 0:
+            self._size += snapshot.size
+        snapshot.references += 1
+        self._size += 256
+        self._entries[token] = _PageEntry(snapshot, offset)
+        return token
+
+    def _review(
+        self, snapshot: _PagedSnapshot, sanitizer: SanitizerPipeline | None
+    ) -> None:
+        # Replacement policies or changed credential variants must recheck ALL
+        # cached facts, including unrequested records. Cache only an opaque stamp.
+        revision = sanitizer.cache_revision if sanitizer is not None else None
+        if snapshot.policy == revision:
+            return
+        try:
+            ensure_safe_output(json.loads(snapshot.header), sanitizer=sanitizer)
+            for item in snapshot.items:
+                ensure_safe_output(json.loads(item), sanitizer=sanitizer)
+        except NormalizationError:
+            for token, entry in tuple(self._entries.items()):
+                if isinstance(entry, _PageEntry) and entry.snapshot is snapshot:
+                    self._remove(token)
+            raise
+        snapshot.policy = revision
+
+    @staticmethod
+    def _decode_page(entry: _PageEntry, limit: int) -> dict[str, Any]:
+        result: dict[str, Any] = json.loads(entry.snapshot.header)
+        result["data"]["items"] = [
+            json.loads(item)
+            for item in entry.snapshot.items[entry.offset : entry.offset + limit]
+        ]
+        return result
+
+    def get_page(
+        self, token: str, query: Any, *, sanitizer: SanitizerPipeline | None = None
+    ) -> tuple[dict[str, Any], bool]:
+        self.deadline(token, query)
+        entry = self._entries[token]
+        self._entries.move_to_end(token)
+        if isinstance(entry, _Entry):
+            result = self.get(token, query, sanitizer=sanitizer)
+            items = result["data"]["items"]
+            return page_envelope(result, items[: query.max_results]), len(
+                items
+            ) > query.max_results
+        self._review(entry.snapshot, sanitizer)
+        result = self._decode_page(entry, query.max_results)
+        ensure_safe_output(result, sanitizer=sanitizer)
+        return result, entry.offset + query.max_results < len(entry.snapshot.items)
+
+    def advance(
+        self,
+        token: str,
+        query: Any,
+        consumed: int,
+        *,
+        sanitizer: SanitizerPipeline | None = None,
+    ) -> str:
+        self.deadline(token, query)
+        entry = self._entries[token]
+        if not 0 < consumed <= query.max_results:
+            raise ValueError("INVALID_PAGE_OFFSET")
+        if isinstance(entry, _Entry):
+            return self.put_paged(
+                self.get(token, query, sanitizer=sanitizer),
+                query,
+                offset=consumed,
+                sanitizer=sanitizer,
+                expires_at=entry.expires_at,
+            )
+        self._review(entry.snapshot, sanitizer)
+        offset = entry.offset + consumed
+        if offset >= len(entry.snapshot.items):
+            raise ValueError("INVALID_PAGE_OFFSET")
+        return self._register_page(entry.snapshot, offset, sanitizer)