release: 0.1.5 — code-review fixes (StreamingResponse double-exec, path-param coercion, GraphiQL SRI, FileFlagProvider race, --offline)

Author: Berik Ashimov

CHANGELOG.md

@@ -7,6 +7,26 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.1.5] - 2026-04-19
+
+### Fixed
+
+- **[HIGH] Double-execution of handler on `StreamingResponse`.** Routes whose handler returns a `StreamingResponse` / `FileResponse` were classified as trivial by the Wave 3 fast path, and a late fallback to `_execute_route` re-ran the handler — doubling any side effects (DB writes, emails, billing). `_compute_trivial` now inspects the handler's return annotation and excludes streaming returns at registration time; the fast path dispatches streaming responses in-place as a defensive guard.
+- **[MEDIUM] Path-param coercion missing on the trivial fast path.** `{id:int}`-style typed path params were passed as raw `str` to the handler, breaking the declared type contract. The fast path now calls `_coerce_fast` on path values (same behaviour as the general path).
+- **[MEDIUM] GraphiQL CDN assets now use pinned versions + Subresource Integrity (SRI) hashes.** Default `app.mount_graphql(...)` ships with `graphiql=True`; the embedded HTML loaded React/GraphiQL from `cdn.jsdelivr.net` with the `@3` / `@18` floating tags and without `integrity=` attributes — a supply-chain vector. All four assets are now pinned to exact versions (`graphiql@3.0.9`, `react@18.3.1`, `react-dom@18.3.1`) with `sha384` SRI hashes.
+- **[LOW] `FileFlagProvider` cache/mtime update order.** Under free-threaded CPython or thread-pool workers, writing `_mtime` before `_cache` could let a concurrent reader observe the new mtime, skip the reload, and return the stale cache. Cache is now written first, mtime last.
+- **[LOW] Lazy imports inside `_execute_trivial_route` hoisted out of the hot path.** `ParamSource` and `_coerce_fast` are now imported at module scope in `app.py` — a small but per-request saving on every trivial dispatch.
+
+### Added
+
+- `hawkapi doctor --offline` — skip rules that require network access (e.g. DOC050's PyPI version check). Rules opt in via `requires_network: bool = True`.
+- README `Security` section note: always use `secrets.compare_digest` to compare credentials returned by `HTTPBasic` / `HTTPBearer` to avoid timing attacks.
+
+### Changed
+
+- `build_mypyc.py` documents the MSVC reserved-identifier trap (`__is_trivial`, `__is_class`, `__is_base_of`, `__has_trivial_destructor`, …) so future additions to `HOT_MODULES` avoid `_is_*` / `_has_*` private attribute names that collide with C++11 type-trait keywords on Windows.
+- `[tool.ruff] extend-exclude` and `[tool.ruff.lint.per-file-ignores]` extended so local venvs, build artefacts, and non-library code (`benchmarks/**`, `examples/**`, `hatch_build.py`) no longer block lint.
+
 ## [0.1.4] - 2026-04-19
 
 ### Added

README.md

@@ -357,6 +357,15 @@ async def protected(credentials=Depends(auth)):
 
 Built-in schemes: `HTTPBearer`, `HTTPBasic`, `APIKeyHeader`, `APIKeyQuery`, `APIKeyCookie`, `OAuth2PasswordBearer`.
 
+> **Comparing credentials safely.** `HTTPBasic` / `HTTPBearer` only *extract* credentials; comparison against your stored secret is your responsibility. Always use a constant-time helper to avoid timing attacks:
+>
+> ```python
+> import secrets
+>
+> if not secrets.compare_digest(creds.password, stored_hash):
+>     raise HTTPException(401, detail="Invalid credentials")
+> ```
+
 #### Declarative Permissions (RBAC)
 
 ```python

build_mypyc.py

@@ -33,6 +33,16 @@
 # subclassing at runtime, so compiling these would break the public API.
 # Compiling the radix tree, route record, param converters and middleware
 # pipeline still captures the dominant request-routing hot path.
+#
+# MSVC RESERVED IDENTIFIERS — when adding attributes to compiled classes,
+# avoid any name that starts with ``__is_`` or ``__has_`` and matches a C++11
+# type-trait keyword. mypyc transpiles ``_private`` attribute names to
+# ``__private`` in generated C, and MSVC interprets tokens like ``__is_trivial``,
+# ``__is_class``, ``__is_base_of``, ``__is_constructible``,
+# ``__has_trivial_destructor``, ``__has_virtual_destructor`` as built-in
+# compiler intrinsics — resulting in ``error C4233: nonstandard extension
+# used`` on Windows wheel builds. Prefer ``_trivial`` / ``_class`` /
+# ``_base_of`` / ``_constructible`` over the ``is_``/``has_`` prefix form.
 HOT_MODULES: tuple[str, ...] = (
     "src/hawkapi/routing/_radix_tree.py",
     "src/hawkapi/routing/route.py",

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "hawkapi"
-version = "0.1.4"
+version = "0.1.5"
 description = "High-performance Python web framework — faster alternative to FastAPI"
 readme = "README.md"
 license = { file = "LICENSE" }
@@ -100,13 +100,19 @@ markers = [
 [tool.ruff]
 target-version = "py312"
 line-length = 100
+# Ignore local venvs, build artefacts, and agent scratch worktrees —
+# none are part of the project source tree or tracked in git.
+extend-exclude = [".venv", "site", "build", "worktrees"]
 
 [tool.ruff.lint]
 select = ["E", "F", "I", "UP", "B", "SIM", "S"]
 ignore = ["S101"]
 
 [tool.ruff.lint.per-file-ignores]
 "tests/**" = ["S"]
+"benchmarks/**" = ["S", "F401", "F841", "E402", "F541", "E501", "I001", "B007", "SIM"]
+"examples/**" = ["F401", "F841", "E402", "I001", "S"]
+"hatch_build.py" = ["SIM105"]
 
 [tool.coverage.run]
 source = ["hawkapi"]

src/hawkapi/__init__.py

@@ -79,7 +79,7 @@
     from hawkapi.validation.constraints import Body, Cookie, Header, Path, Query
     from hawkapi.websocket import WebSocket, WebSocketDisconnect
 
-__version__ = "0.1.4"
+__version__ = "0.1.5"
 
 # Lazy imports — loaded on first access for faster cold start
 _LAZY_IMPORTS: dict[str, tuple[str, str]] = {

src/hawkapi/app.py

@@ -14,7 +14,12 @@
 from hawkapi._types import ASGIApp, Receive, Scope, Send
 from hawkapi.background import BackgroundTasks
 from hawkapi.di.container import Container
-from hawkapi.di.resolver import resolve_dependencies, resolve_from_plan
+from hawkapi.di.param_plan import ParamSource
+from hawkapi.di.resolver import (
+    _coerce_fast,  # pyright: ignore[reportPrivateUsage]
+    resolve_dependencies,
+    resolve_from_plan,
+)
 from hawkapi.di.scope import Scope as DIScope
 from hawkapi.exceptions import HTTPException
 from hawkapi.lifespan.hooks import HookRegistry
@@ -573,11 +578,6 @@ async def _execute_trivial_route(
         # IMPLICIT_PATH/IMPLICIT_QUERY/PATH params, no DI, no body, no cleanup.
         # Coercion (e.g. int query params) can raise RequestValidationError,
         # so the entire kwargs-build + handler call is inside the try block.
-        from hawkapi.di.param_plan import ParamSource  # noqa: PLC0415
-        from hawkapi.di.resolver import (
-            _coerce_fast,  # noqa: PLC0415  # pyright: ignore[reportPrivateUsage]
-        )
-
         try:
             kwargs: dict[str, Any] = {}
             if plan is not None:
@@ -586,11 +586,16 @@ async def _execute_trivial_route(
                     if src is ParamSource.REQUEST:
                         kwargs[spec.name] = request
                     elif src is ParamSource.PATH or src is ParamSource.IMPLICIT_PATH:
-                        value = request.path_params.get(spec.alias or spec.name)
-                        if value is None and spec.has_marker_default:
+                        raw = request.path_params.get(spec.alias or spec.name)
+                        if raw is not None and spec.coerce_type is not None:
+                            # path_params values are always str — coerce to the
+                            # handler's declared type (int / uuid / float / …).
+                            kwargs[spec.name] = _coerce_fast(str(raw), spec.coerce_type)
+                        elif raw is None and spec.has_marker_default:
                             mdf = spec.marker_default_factory
-                            value = mdf() if mdf is not None else spec.marker_default
-                        kwargs[spec.name] = value
+                            kwargs[spec.name] = mdf() if mdf is not None else spec.marker_default
+                        else:
+                            kwargs[spec.name] = raw
                     elif src is ParamSource.QUERY or src is ParamSource.IMPLICIT_QUERY:
                         qval = request.query_params.get(spec.alias or spec.name)
                         if qval is not None:
@@ -633,10 +638,13 @@ async def _execute_trivial_route(
             response = await self._handle_exception(request, exc)
 
         # Minimal HEAD handling: zero out the body but keep content-length.
-        # StreamingResponse is not a Response subclass — fall back to the
-        # general path if somehow one slips through (guards _trivial calc).
+        # StreamingResponse-returning handlers are excluded at registration
+        # time by ``_compute_trivial`` so they never reach this path — if one
+        # somehow does (subclassing edge case), dispatch it as-is rather than
+        # re-running the handler via the general path (which would double
+        # any side effects).
         if isinstance(response, StreamingResponse):
-            await self._execute_route(scope, receive, send, route, plan, request)
+            await response(scope, receive, send)
             return
 
         if scope["method"] == "HEAD" and hasattr(response, "body"):

src/hawkapi/cli.py

@@ -182,6 +182,11 @@ def main(argv: list[str] | None = None) -> None:
         action="store_true",
         help="Apply safe auto-fixes where available (v1: none implemented)",
     )
+    doctor_parser.add_argument(
+        "--offline",
+        action="store_true",
+        help="Skip rules that require network access (e.g. DOC050 PyPI version check)",
+    )
 
     # `hawkapi migrate` subcommand
     migrate_parser = subparsers.add_parser(
@@ -249,7 +254,14 @@ def _run_doctor(args: argparse.Namespace) -> int:
     if args.fix:
         print("--fix: no auto-fixable findings in v1.")
 
-    findings = run(app, min_severity=min_sev)
+    rules: list[Any] | None = None
+    if args.offline:
+        from hawkapi.doctor.rules import ALL_RULES  # noqa: PLC0415
+
+        # Drop rules tagged as requiring network access (e.g. DOC050 queries PyPI).
+        rules = [r for r in ALL_RULES if not getattr(r, "requires_network", False)]
+
+    findings = run(app, rules=rules, min_severity=min_sev)
 
     if args.output_format == "json":
         print(format_json(findings, args.app))

src/hawkapi/doctor/rules/deps.py

@@ -31,6 +31,8 @@ class _DOC050:
     severity: Severity = Severity.INFO
     title: str = "HawkAPI version older than latest published on PyPI"
     docs_url: str = docs_url("DOC050")
+    # Flag consumed by ``hawkapi doctor --offline`` to skip rules that phone home.
+    requires_network: bool = True
 
     def check(self, app: HawkAPI) -> list[Finding]:
         import hawkapi

src/hawkapi/flags/providers.py

@@ -180,6 +180,12 @@ def _ensure_loaded(self) -> None:
                 f"Unsupported flag file extension {ext!r}. Use .json, .toml, .yaml, or .yml."
             )
 
+        # Order matters under concurrent reads (free-threaded CPython or
+        # thread-pool workers): if we updated _mtime first, another thread
+        # could see the new mtime, skip the reload, and read the stale
+        # _cache. Assigning _cache first and _mtime last means readers that
+        # observe the new mtime always observe the new cache too. Both
+        # assignments are atomic at the Python level.
         self._cache = data if isinstance(data, dict) else {}
         self._mtime = current_mtime
 

src/hawkapi/graphql/_graphiql.py

@@ -1,4 +1,11 @@
-"""GraphiQL HTML template served for browser requests."""
+"""GraphiQL HTML template served for browser requests.
+
+All CDN assets are pinned to exact versions and protected by Subresource
+Integrity (SRI) hashes so a compromised CDN cannot inject arbitrary JS into
+the developer's browser. Regenerate the hashes with::
+
+    curl -sL <url> | openssl dgst -sha384 -binary | openssl base64 -A
+"""
 
 from __future__ import annotations
 
@@ -13,21 +20,26 @@
     #graphiql { height: 100vh; }
   </style>
   <link rel="stylesheet"
-    href="https://cdn.jsdelivr.net/npm/graphiql@3/graphiql.min.css" />
+    href="https://cdn.jsdelivr.net/npm/graphiql@3.0.9/graphiql.min.css"
+    integrity="sha384-yz3/sqpuplkA7msMo0FE4ekg0xdwdvZ8JX9MVZREsxipqjU4h8IRfmAMRcb1QpUy"
+    crossorigin="anonymous" />
 </head>
 <body>
   <div id="graphiql">Loading&hellip;</div>
   <script
-    crossorigin
-    src="https://cdn.jsdelivr.net/npm/react@18/umd/react.production.min.js"
+    src="https://cdn.jsdelivr.net/npm/react@18.3.1/umd/react.production.min.js"
+    integrity="sha384-DGyLxAyjq0f9SPpVevD6IgztCFlnMF6oW/XQGmfe+IsZ8TqEiDrcHkMLKI6fiB/Z"
+    crossorigin="anonymous"
   ></script>
   <script
-    crossorigin
-    src="https://cdn.jsdelivr.net/npm/react-dom@18/umd/react-dom.production.min.js"
+    src="https://cdn.jsdelivr.net/npm/react-dom@18.3.1/umd/react-dom.production.min.js"
+    integrity="sha384-gTGxhz21lVGYNMcdJOyq01Edg0jhn/c22nsx0kyqP0TxaV5WVdsSH1fSDUf5YJj1"
+    crossorigin="anonymous"
   ></script>
   <script
-    crossorigin
-    src="https://cdn.jsdelivr.net/npm/graphiql@3/graphiql.min.js"
+    src="https://cdn.jsdelivr.net/npm/graphiql@3.0.9/graphiql.min.js"
+    integrity="sha384-Mjte+vxCWz1ZYCzszGHiJqJa5eAxiqI4mc3BErq7eDXnt+UGLXSEW7+i0wmfPiji"
+    crossorigin="anonymous"
   ></script>
   <script>
     const root = ReactDOM.createRoot(document.getElementById('graphiql'));