fastapi-streams 0.3.0__tar.gz → 0.3.1__tar.gz

{fastapi_streams-0.3.0 → fastapi_streams-0.3.1}/CHANGELOG.md

@@ -3,6 +3,41 @@
 All notable changes and consumer upgrade steps are recorded here. Entries marked
 unreleased describe prepared source versions that have not been published.
 
+## 0.3.1 - 2026-10-18
+
+### Added
+
+- Repeatable Python and Node benchmarks for generated SDK request preparation,
+  decoding/validation, SSE framing, complete consumption, fragmented chunks and
+  Python unknown-event ignoring. Reports include individual timing samples and
+  optional separate Python peak-memory measurements; no CI timing thresholds.
+- Add generation provenance and validation capabilities to version 1 diagnostic
+  reports: canonical schema SHA-256, generator version, target/HTTP backend and
+  request/event/error validation phases. Existing diagnostic fields, IDs and
+  exact reviewed allowances remain unchanged. Additional report object keys are
+  additive; the metadata does not introduce runtime checks or full JSON Schema
+  guarantees.
+
+### Performance
+
+- Reuse the JSON-value adapter for skipped unknown events and HTTP-error JSON
+  decoding. Cache top-level discriminator metadata per generated event adapter
+  instead of rebuilding its JSON Schema for every ignore-policy stream.
+- Prepare sanitized validation details only for errors that are actually raised.
+  Known events still use direct Pydantic JSON validation; malformed known events,
+  missing/non-string tags, invalid JSON and unknown nested variants still fail.
+  Public signatures, coercion, validation timing and wire encoding are unchanged.
+
+### Upgrade from 0.3.0
+
+1. Upgrade the generator to 0.3.1 and regenerate with the existing HTTP backend
+   to obtain the Python runtime improvements. Existing generated SDKs keep working.
+2. Diagnostic-report readers should tolerate the new `generation` and `validation`
+   keys. Existing exact diagnostic allowances need no migration.
+3. Continue validating server requests and domain invariants at their own
+   boundaries; consumers should reuse parsed events instead of validating the
+   same schema again. TypeScript remains static-only with no added dependency.
+
 ## 0.3.0 - 2026-10-18
 
 ### Breaking changes

{fastapi_streams-0.3.0 → fastapi_streams-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: fastapi-streams
-Version: 0.3.0
+Version: 0.3.1
 Summary: Typed FastAPI streams with generated TypeScript and Python clients.
 Project-URL: Documentation, https://github.com/mathisarends/canon/tree/main/packages/fastapi-streams/docs
 Project-URL: Source, https://github.com/mathisarends/canon/tree/main/packages/fastapi-streams

{fastapi_streams-0.3.0 → fastapi_streams-0.3.1}/docs/clients.md

@@ -121,6 +121,15 @@ remain ordinary members of the user-defined union.
 
 ## HTTP error contracts
 
+Keep schema validation at transport boundaries. Python prepares and validates
+requests at the method call and validates received events during iteration.
+Pass those parsed event models onward instead of serializing them to dictionaries
+and validating the same schema again. Server request validation remains necessary
+regardless of SDK checks; authentication, authorization and domain invariants have
+separate responsibilities. Canon composition does not need an additional event
+validator around Streams. TypeScript keeps its documented static-only behavior;
+applications needing runtime event checks can validate once before using a value.
+
 Python request parameters and JSON bodies are validated when calling the method;
 catch Pydantic `ValidationError` around that call. Network and event errors occur
 while iterating. See the [validation matrix and CI policy](codegen.md#validation-support-matrix).

{fastapi_streams-0.3.0 → fastapi_streams-0.3.1}/docs/codegen.md

@@ -191,6 +191,26 @@ including inline schemas and referenced component definitions. Shared definition
 identify each affected operation; unused components do not generate warnings.
 SSE framing metadata is outside generated event-model validation.
 
+The version 1 report also carries additive `generation` and `validation` objects.
+Consumers should tolerate additional object keys. `generation` records the
+generator name/version, target, selected Python HTTP library (null for TypeScript)
+and `schema_sha256`. The hash covers the complete parsed OpenAPI document,
+including unused definitions. Its `canonical-json-v1` encoding is Python
+`json.dumps(document, sort_keys=True, separators=(",", ":"), ensure_ascii=False)`
+encoded as UTF-8. Whitespace and object-key order in the input file do not affect
+the hash; array order and values do. It is a content identifier, not a signature
+or proof of schema enforcement.
+
+`validation` distinguishes parameter/body validation at `method_call`, event
+decoding at `iteration` and HTTP-error handling at `consumer_controlled`.
+TypeScript parameter/body schema checks are `not_performed`. Each boundary has
+a `schema_validation` boolean, with `json_decoding: true` for events. Python's
+`runtime_scope` is `generated_types_and_supported_constraints`; TypeScript's is
+`json_decoding_only`. Both set `full_json_schema: false`. These target capabilities
+describe supported boundaries, even if an operation has no parameters or body;
+source-specific limitations remain in `diagnostics` with their accepted status.
+The report is generated only when requested and adds no SDK runtime checks.
+
 `unsupported-constraint` identifies an unenforced rule for the selected target;
 TypeScript also diagnoses Python-supported scalar constraints because TypeScript
 has no runtime schema validator. Python's `optional-discriminator` diagnoses event

{fastapi_streams-0.3.0 → fastapi_streams-0.3.1}/docs/development.md

@@ -88,6 +88,35 @@ outside the checkout they invoke the installed `fastapi-streams` command, exerci
 and consume an event through the generated Python SDK. Metadata and `__version__`
 must match the release version in `pyproject.toml`.
 
+## Generated SDK performance
+
+From the workspace root, use the locked environment and installed Node tooling:
+
+```console
+uv run --locked python packages/fastapi-streams/scripts/benchmark_runtime.py --memory --output dist/streams-baseline.json
+```
+
+The harness generates both SDKs from the same small discriminated-union contract.
+It measures request preparation separately from decoding, framing and complete
+HTTP/SSE consumption with an in-memory HTTPX transport or Fetch response. Cases
+cover small token events, nested batches, seven-byte fragments and Python's
+unknown-event ignore policy. Python validates generated models; TypeScript only
+decodes JSON. Their decoding results do not represent equivalent guarantees.
+
+Reports record source location, generator/runtime versions, platform, payload
+sizes, individual samples, median CPU/wall time per request or input event, and
+throughput. Ignore-policy throughput counts skipped input events too. `--memory`
+adds a separate Python traced peak-memory sample; it does not instrument timings
+or count total allocations. There are three warmup iterations per case. These
+are warmed batch measurements, not individual-event latency percentiles, cold
+startup measurements, real-network results or Hermes deployment evidence.
+
+Use `--runtime python` or `--runtime typescript` for focused runs. Adjust
+`--events`, `--iterations` and `--rounds` for longer samples. For a comparison,
+run the same harness with `--source-dir` pointing to the other revision's Streams
+package directory, keeping the interpreter, dependencies and arguments fixed.
+Repeat runs to assess noise; ordinary CI does not enforce timing thresholds.
+
 ## Supported scope and roadmap
 
 GET/POST JSON SSE data; scalar path and header parameters; scalar/array query parameters;

{fastapi_streams-0.3.0/fastapi_streams/codegen/templates/python → fastapi_streams-0.3.1/examples/agent_runs/generated_python}/runtime.py

@@ -5,12 +5,15 @@ import codecs
 from collections.abc import AsyncGenerator, Mapping, Sequence
 from dataclasses import dataclass
 from enum import Enum
+from functools import cache
 from typing import Literal, cast
 
 import httpx
 from pydantic import JsonValue, TypeAdapter, ValidationError
 from pydantic_core import ErrorDetails
 
+_JSON_ADAPTER = TypeAdapter[JsonValue](JsonValue)
+
 
 class TransportError(Exception):
     pass
@@ -180,19 +183,11 @@ class Transport:
         options: RequestOptions | None = None,
     ) -> AsyncGenerator[T, None]:
         discriminator: str | None = None
-        known_tags: set[str] = set()
+        known_tags: frozenset[str] = frozenset()
         if options and options.unknown_events not in {"error", "ignore"}:
             raise ValueError("unknown_events must be 'error' or 'ignore'")
         if options and options.unknown_events == "ignore":
-            schema = adapter.json_schema()
-            policy = schema.get("discriminator", {})
-            discriminator = policy.get("propertyName")
-            known_tags = set(policy.get("mapping", {}))
-            if not isinstance(discriminator, str) or not known_tags:
-                raise ValueError(
-                    "unknown_events='ignore' requires a top-level "
-                    "discriminated event union"
-                )
+            discriminator, known_tags = _unknown_event_policy(adapter)
         request_headers = self.headers.copy()
         request_headers.update(headers)
         if options and options.headers:
@@ -223,11 +218,7 @@ class Transport:
                         failure = exc
                     text = raw.decode("utf-8", errors="replace")
                     try:
-                        details = (
-                            TypeAdapter[JsonValue](JsonValue).validate_json(text)
-                            if text
-                            else None
-                        )
+                        details = _JSON_ADAPTER.validate_json(text) if text else None
                     except ValidationError:
                         details = text
                     raise HttpError(response, details) from failure
@@ -245,6 +236,16 @@ class Transport:
                     try:
                         yield adapter.validate_json(payload)
                     except ValidationError as exc:
+                        if discriminator is not None:
+                            try:
+                                value = _JSON_ADAPTER.validate_json(payload)
+                            except ValidationError:
+                                pass
+                            else:
+                                if isinstance(value, dict):
+                                    tag = value.get(discriminator)
+                                    if isinstance(tag, str) and tag not in known_tags:
+                                        continue
                         # Exclude input and arbitrary validator context from public
                         # diagnostics. The original cause remains available explicitly.
                         details = exc.errors(
@@ -257,22 +258,6 @@ class Transport:
                             if any(error["type"] == "json_invalid" for error in details)
                             else "invalid_event_schema"
                         )
-                        if discriminator is not None:
-                            try:
-                                value = TypeAdapter[JsonValue](JsonValue).validate_json(
-                                    payload
-                                )
-                            except ValidationError:
-                                raise StreamParseError(
-                                    payload,
-                                    operation_id=operation_id,
-                                    category="invalid_json",
-                                    validation_errors=details,
-                                ) from exc
-                            if isinstance(value, dict):
-                                tag = value.get(discriminator)
-                                if isinstance(tag, str) and tag not in known_tags:
-                                    continue
                         raise StreamParseError(
                             payload,
                             operation_id=operation_id,
@@ -285,6 +270,19 @@ class Transport:
             raise TransportError("Invalid UTF-8 in SSE stream") from exc
 
 
+@cache
+def _unknown_event_policy[T](adapter: TypeAdapter[T]) -> tuple[str, frozenset[str]]:
+    schema = adapter.json_schema()
+    policy = schema.get("discriminator", {})
+    discriminator = policy.get("propertyName")
+    known_tags = frozenset(policy.get("mapping", {}))
+    if not isinstance(discriminator, str) or not known_tags:
+        raise ValueError(
+            "unknown_events='ignore' requires a top-level discriminated event union"
+        )
+    return discriminator, known_tags
+
+
 def _preserve_numbers[T](original: object, validated: T) -> T:
     if (
         type(original) is int

{fastapi_streams-0.3.0 → fastapi_streams-0.3.1}/fastapi_streams/__init__.py

@@ -1,4 +1,4 @@
 from fastapi_streams.router import StreamRouter
 
 __all__ = ["StreamRouter"]
-__version__ = "0.3.0"
+__version__ = "0.3.1"

{fastapi_streams-0.3.0 → fastapi_streams-0.3.1}/fastapi_streams/codegen/cli.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import argparse
+import hashlib
 import importlib
 import json
 import sys
@@ -9,6 +10,7 @@ from typing import TYPE_CHECKING, cast
 
 from fastapi import FastAPI
 
+from fastapi_streams import __version__
 from fastapi_streams.codegen.openapi import ContractError, Document, export_schema
 from fastapi_streams.codegen.writer import write_files
 
@@ -103,6 +105,7 @@ def main(argv: list[str] | None = None) -> int:
             document = json.loads(args.schema.read_text(encoding="utf-8"))
             if not isinstance(document, dict):
                 raise ContractError("The OpenAPI document must be an object")
+            document = cast(Document, document)
             if args.command == "check" and args.app:
                 expected = export_schema(_load_app(args.app))
                 if expected != document:
@@ -112,12 +115,17 @@ def main(argv: list[str] | None = None) -> int:
                     )
                     return 1
             diagnostics: list[GenerationDiagnostic] = []
-            contract = build_ir(
-                cast(Document, document), target=args.language, diagnostics=diagnostics
-            )
+            contract = build_ir(document, target=args.language, diagnostics=diagnostics)
             # Reports precede strict-policy failures, so CI can review new IDs.
             if args.diagnostics:
-                _write_diagnostics(args.diagnostics, diagnostics, set())
+                _write_diagnostics(
+                    args.diagnostics,
+                    diagnostics,
+                    set(),
+                    document,
+                    args.language,
+                    args.python_http_client or "httpx",
+                )
             accepted: set[str] = (
                 accepted_diagnostics(
                     diagnostics, json.loads(args.allow_diagnostics.read_text("utf-8"))
@@ -126,7 +134,14 @@ def main(argv: list[str] | None = None) -> int:
                 else set()
             )
             if args.diagnostics:
-                _write_diagnostics(args.diagnostics, diagnostics, accepted)
+                _write_diagnostics(
+                    args.diagnostics,
+                    diagnostics,
+                    accepted,
+                    document,
+                    args.language,
+                    args.python_http_client or "httpx",
+                )
             pending = [item for item in diagnostics if item.id not in accepted]
             emit_diagnostics(pending)
             if args.strict and pending:
@@ -168,13 +183,57 @@ def _load_app(value: str) -> FastAPI:
 
 
 def _write_diagnostics(
-    path: Path, diagnostics: list[GenerationDiagnostic], accepted: set[str]
+    path: Path,
+    diagnostics: list[GenerationDiagnostic],
+    accepted: set[str],
+    document: Document,
+    target: str,
+    http_client: str,
 ) -> None:
+    # Canonical JSON binds reports to schema content, independent of file layout.
+    encoded = json.dumps(
+        document, sort_keys=True, separators=(",", ":"), ensure_ascii=False
+    ).encode("utf-8")
+    python = target == "python"
+    request_phase = "method_call" if python else "not_performed"
     path.parent.mkdir(parents=True, exist_ok=True)
     path.write_text(
         json.dumps(
             {
                 "version": 1,
+                "generation": {
+                    "generator": "fastapi-streams",
+                    "generator_version": __version__,
+                    "schema_sha256": hashlib.sha256(encoded).hexdigest(),
+                    "schema_hash_encoding": "canonical-json-v1",
+                    "target": target,
+                    "python_http_client": http_client if python else None,
+                },
+                "validation": {
+                    "full_json_schema": False,
+                    "runtime_scope": (
+                        "generated_types_and_supported_constraints"
+                        if python
+                        else "json_decoding_only"
+                    ),
+                    "parameters": {
+                        "phase": request_phase,
+                        "schema_validation": python,
+                    },
+                    "request_body": {
+                        "phase": request_phase,
+                        "schema_validation": python,
+                    },
+                    "events": {
+                        "phase": "iteration",
+                        "schema_validation": python,
+                        "json_decoding": True,
+                    },
+                    "http_error_bodies": {
+                        "phase": "consumer_controlled",
+                        "schema_validation": False,
+                    },
+                },
                 "diagnostics": [
                     item.to_dict(accepted=item.id in accepted) for item in diagnostics
                 ],

{fastapi_streams-0.3.0/examples/agent_runs/generated_python → fastapi_streams-0.3.1/fastapi_streams/codegen/templates/python}/runtime.py

@@ -5,12 +5,15 @@ import codecs
 from collections.abc import AsyncGenerator, Mapping, Sequence
 from dataclasses import dataclass
 from enum import Enum
+from functools import cache
 from typing import Literal, cast
 
 import httpx
 from pydantic import JsonValue, TypeAdapter, ValidationError
 from pydantic_core import ErrorDetails
 
+_JSON_ADAPTER = TypeAdapter[JsonValue](JsonValue)
+
 
 class TransportError(Exception):
     pass
@@ -180,19 +183,11 @@ class Transport:
         options: RequestOptions | None = None,
     ) -> AsyncGenerator[T, None]:
         discriminator: str | None = None
-        known_tags: set[str] = set()
+        known_tags: frozenset[str] = frozenset()
         if options and options.unknown_events not in {"error", "ignore"}:
             raise ValueError("unknown_events must be 'error' or 'ignore'")
         if options and options.unknown_events == "ignore":
-            schema = adapter.json_schema()
-            policy = schema.get("discriminator", {})
-            discriminator = policy.get("propertyName")
-            known_tags = set(policy.get("mapping", {}))
-            if not isinstance(discriminator, str) or not known_tags:
-                raise ValueError(
-                    "unknown_events='ignore' requires a top-level "
-                    "discriminated event union"
-                )
+            discriminator, known_tags = _unknown_event_policy(adapter)
         request_headers = self.headers.copy()
         request_headers.update(headers)
         if options and options.headers:
@@ -223,11 +218,7 @@ class Transport:
                         failure = exc
                     text = raw.decode("utf-8", errors="replace")
                     try:
-                        details = (
-                            TypeAdapter[JsonValue](JsonValue).validate_json(text)
-                            if text
-                            else None
-                        )
+                        details = _JSON_ADAPTER.validate_json(text) if text else None
                     except ValidationError:
                         details = text
                     raise HttpError(response, details) from failure
@@ -245,6 +236,16 @@ class Transport:
                     try:
                         yield adapter.validate_json(payload)
                     except ValidationError as exc:
+                        if discriminator is not None:
+                            try:
+                                value = _JSON_ADAPTER.validate_json(payload)
+                            except ValidationError:
+                                pass
+                            else:
+                                if isinstance(value, dict):
+                                    tag = value.get(discriminator)
+                                    if isinstance(tag, str) and tag not in known_tags:
+                                        continue
                         # Exclude input and arbitrary validator context from public
                         # diagnostics. The original cause remains available explicitly.
                         details = exc.errors(
@@ -257,22 +258,6 @@ class Transport:
                             if any(error["type"] == "json_invalid" for error in details)
                             else "invalid_event_schema"
                         )
-                        if discriminator is not None:
-                            try:
-                                value = TypeAdapter[JsonValue](JsonValue).validate_json(
-                                    payload
-                                )
-                            except ValidationError:
-                                raise StreamParseError(
-                                    payload,
-                                    operation_id=operation_id,
-                                    category="invalid_json",
-                                    validation_errors=details,
-                                ) from exc
-                            if isinstance(value, dict):
-                                tag = value.get(discriminator)
-                                if isinstance(tag, str) and tag not in known_tags:
-                                    continue
                         raise StreamParseError(
                             payload,
                             operation_id=operation_id,
@@ -285,6 +270,19 @@ class Transport:
             raise TransportError("Invalid UTF-8 in SSE stream") from exc
 
 
+@cache
+def _unknown_event_policy[T](adapter: TypeAdapter[T]) -> tuple[str, frozenset[str]]:
+    schema = adapter.json_schema()
+    policy = schema.get("discriminator", {})
+    discriminator = policy.get("propertyName")
+    known_tags = frozenset(policy.get("mapping", {}))
+    if not isinstance(discriminator, str) or not known_tags:
+        raise ValueError(
+            "unknown_events='ignore' requires a top-level discriminated event union"
+        )
+    return discriminator, known_tags
+
+
 def _preserve_numbers[T](original: object, validated: T) -> T:
     if (
         type(original) is int

{fastapi_streams-0.3.0 → fastapi_streams-0.3.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "fastapi-streams"
-version = "0.3.0"
+version = "0.3.1"
 description = "Typed FastAPI streams with generated TypeScript and Python clients."
 readme = "README.md"
 requires-python = ">=3.12"

fastapi_streams-0.3.1/scripts/benchmark_runtime.mjs

@@ -0,0 +1,93 @@
+// Invoked by benchmark_runtime.py against a freshly generated, compiled SDK.
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+
+const [sdk, payloadPath, eventArg, iterationArg, roundArg] = process.argv.slice(2);
+const events = Number(eventArg);
+const iterations = Number(iterationArg);
+const rounds = Number(roundArg);
+const { createClient } = await import(pathToFileURL(resolve(sdk, "index.js")).href);
+const { parseSSE } = await import(pathToFileURL(resolve(sdk, "transport/sse.js")).href);
+const payloads = JSON.parse(await readFile(payloadPath, "utf8"));
+const encoder = new TextEncoder();
+let activeChunks = [];
+let sink;
+
+function body() {
+  return new ReadableStream({
+    start(controller) {
+      for (const chunk of activeChunks) controller.enqueue(chunk);
+      controller.close();
+    },
+  });
+}
+
+const client = createClient({
+  baseUrl: "http://benchmark.test",
+  fetch: async () => new Response(body(), { headers: { "content-type": "text/event-stream" } }),
+});
+
+async function measure(operation, repeats, units) {
+  for (let i = 0; i < 3; i++) await operation();
+  const wall = [];
+  const cpu = [];
+  for (let round = 0; round < rounds; round++) {
+    const started = process.hrtime.bigint();
+    const cpuStarted = process.cpuUsage();
+    for (let i = 0; i < repeats; i++) await operation();
+    const elapsedCpu = process.cpuUsage(cpuStarted);
+    cpu.push((elapsedCpu.user + elapsedCpu.system) / repeats / units);
+    wall.push(Number(process.hrtime.bigint() - started) / repeats / units / 1000);
+  }
+  const median = values => {
+    const sorted = [...values].sort((a, b) => a - b);
+    const middle = Math.floor(sorted.length / 2);
+    return sorted.length % 2 ? sorted[middle] : (sorted[middle - 1] + sorted[middle]) / 2;
+  };
+  return {
+    iterations_per_round: repeats,
+    units_per_iteration: units,
+    median_us_per_unit: median(wall),
+    cpu_median_us_per_unit: median(cpu),
+    units_per_second: 1_000_000 / median(wall),
+    samples_us_per_unit: wall,
+  };
+}
+
+const results = {};
+results.request_preparation = await measure(async () => {
+  sink = client.bench.events({ runId: "run_abc", limit: 100 });
+}, iterations * events, 1);
+
+for (const name of ["small", "nested"]) {
+  results[`decode_static_${name}`] = await measure(async () => {
+    sink = JSON.parse(payloads[name]);
+  }, iterations * events, 1);
+}
+
+for (const name of ["small", "nested", "fragmented"]) {
+  const payload = payloads[name === "nested" ? "nested" : "small"];
+  const raw = encoder.encode(`data: ${payload}\n\n`.repeat(events));
+  activeChunks = name === "fragmented"
+    ? Array.from({ length: Math.ceil(raw.length / 7) }, (_, index) => raw.subarray(index * 7, index * 7 + 7))
+    : [raw];
+  results[`stream_${name}`] = await measure(async () => {
+    let received = 0;
+    for await (const event of client.bench.events({ runId: "run_abc" })) {
+      sink = event;
+      received++;
+    }
+    if (received !== events) throw new Error("Incomplete benchmark stream");
+  }, iterations, events);
+  results[`frame_decode_${name}`] = await measure(async () => {
+    for await (const event of parseSSE(body())) sink = event;
+  }, iterations, events);
+}
+
+if (sink === undefined) throw new Error("Benchmark did not execute");
+process.stdout.write(JSON.stringify({
+  version: process.version,
+  event_validation: "JSON decoding and static types; no runtime schema validation",
+  results,
+}));