Skip to content

Hardening for public integration: per-project ports, compression, OpenAPI, alerts - #12

Merged
sinabigy merged 2 commits into
mainfrom
hardening/public-integration
Oct 6, 2026
Merged

sinabigy merged 2 commits into
mainfrom
hardening/public-integration

Conversation

@sinabigy

@sinabigy sinabigy commented Oct 6, 2026

Copy link
Copy Markdown
Owner

Public-release hardening pass (tasks T-0027 to T-0033). Each item is classified with its evidence in docs/BLUEPRINT_CAPABILITY_MATRIX.md (section Frequently requested).

item class evidence
Projects run side by side (infra/dev-ports.env, generator port blocks, ./dev ports, preflight that names port holders, readiness tied to the spawned process, project-scoped smoke/systemd names, per-project session cookie) DEFAULT Before: the second project's ./dev up failed with Docker's port is already allocated and left a container without ports. After: two generated projects passed ./dev test --system concurrently while a third stack held the blueprint's default ports.
Compression: build-time brotli/gzip for static files, on the fly for API JSON from 1 KiB (never no-store, SSE or already-encoded responses) DEFAULT Static 186 KB → 53 KB. A 13 KB list page → 1.3 KB. Throughput within run-to-run spread (off/on/off, repeat 5). ADR 0012
HTTP caching: private, no-cache API default; static caching already existed DEFAULT / ALREADY EXISTS tests and release-smoke checks
API ETags REJECTED (for now) the SPA is push-driven (SSE) and does not poll; the ADR records when to add them
OpenAPI 3.1 for the integration surface (/api/v1/openapi.json, docs/api/openapi.json) DEFAULT tests/openapi.rs: routes ⇄ spec drift, 401 per operation, live responses conform field for field (mutation-checked)
Generated TypeScript client REJECTED the SPA already uses compile-checked ts-rs types
Alert rules (12, with runbooks) DEFAULT (loaded by observability) promtool test rules in infra-verify; threshold and traffic-floor mutations caught
Alertmanager / tail sampling REJECTED / OPTIONAL deployment-specific; documented
DLQ/backoff, single-flight, gitleaks, trace↔log links ALREADY EXISTS now documented with their tests
Integration examples (curl, Python, Node.js) DEFAULT run by ./dev test --system with a scoped key, revoked afterwards

Also:

  • The GCRA property-test flake is fixed. Under parallel load the old test failed 13/40 runs and the fixed one 0/40; the bound is tighter, and the limiter is unchanged.
  • ./dev benchmark now forwards options to benchmarks/run.py.

Validation on a50fc05: blueprint ./dev check 29/29 (296 Rust tests), release audit OK. validate-generated on the three reference profiles is in progress; results follow in a comment.

Versioning: this is a MINOR change by docs/VERSIONING.md (a new generator flag, an additive API and a new config key), so v1.1.0, not v1.0.3. No tag yet.

🤖 Generated with Claude Code

sinabigy and others added 2 commits October 6, 2026 17:27
…nAPI, alerts

- Projects run side by side: every development port lives in infra/dev-ports.env, the
  generator gives each project its own block, ./dev checks ports before starting and names
  the holder, readiness checks the process it started, smoke/systemd tests use
  project-scoped names, and the dev session cookie is per project.
- Compression: build-time brotli/gzip for static files (source maps moved out of dist/),
  on-the-fly compression for API responses from 1 KiB, never for no-store responses or
  event streams. API responses default to Cache-Control: private, no-cache. ADR 0012.
- OpenAPI 3.1 for the integration surface (API keys, service accounts), derived from the
  response types and tested against live responses; served at /api/v1/openapi.json.
- Alert rules with runbooks and promtool unit tests, loaded by the observability stack.
- Integration examples (curl, Python, Node.js) run by the system smoke.
- GCRA property tests compute slots from the limiter's clock reading (was flaky under load).
- ./dev benchmark forwards run.py options; compression is an on-demand benchmark suite.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@sinabigy

sinabigy commented Oct 6, 2026

Copy link
Copy Markdown
Owner Author

Validation of a50fc05 (code is unchanged in c53a239, which only records the task and the version decision):

target result
blueprint ./dev check 29/29 (296 Rust tests)
generated core / basic / no admin ./dev check 22/22, system smoke 15 pass / 0 fail
generated performance / b2b / Cedar ./dev check 24/24, system smoke 15 pass / 0 fail
generated distributed / b2b ./dev check 25/25, system smoke 17 pass / 0 fail
release-image smoke, systemd live test pass (blueprint and each generated project)
CI on a50fc05 7/7
release audit OK (same 4 owner-action warnings)

Each generated project ran on its own port block, while another local stack held the blueprint's default ports. In every profile's live smoke, all three API client examples completed runs with a scoped key, the OpenAPI document was served (10 operations), and the revoked key got 401.

@sinabigy
sinabigy merged commit c53a239 into main Oct 6, 2026
7 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant