From f128272d4643246b343144faeb8711901259316b Mon Sep 17 00:00:00 2001 From: Aatu Harju Date: Sat, 15 Aug 2026 18:01:02 +0300 Subject: [PATCH] docs(release): disposition v4 release identity incident Refs: REL-000 --- README.md | 5 +- contrib/go.sum | 2 +- docs/README.md | 1 + docs/release-incident-v4-release-identity.md | 186 +++++++++++++++++++ docs/release-runbook.md | 16 +- docs/site/search-index.json | 4 +- docscheck/contract_test.go | 18 +- examples/reference-saas-api/go.mod | 25 +-- examples/reference-saas-api/go.sum | 66 +++---- 9 files changed, 259 insertions(+), 64 deletions(-) create mode 100644 docs/release-incident-v4-release-identity.md diff --git a/README.md b/README.md index 126e6c0e..bf5d31ed 100644 --- a/README.md +++ b/README.md @@ -319,7 +319,10 @@ Stable core package list: `VERSIONING.md` is the source of truth, and - Stable core readiness matrix: [docs/core-readiness.md](docs/core-readiness.md) - V3 migration guide: [docs/migration/v3.md](docs/migration/v3.md) - Troubleshooting guide: [docs/troubleshooting.md](docs/troubleshooting.md) -- Latest published release line: `v4.0.0` and `contrib/v4.0.0`. +- Published v4 tags: `v4.0.0`, `contrib/v4.0.0`, `v4.0.1`, and + `contrib/v4.0.1`. Before a new deployment or release, follow the + [v4 release-identity incident](docs/release-incident-v4-release-identity.md); + `v4.0.1` and `contrib/v4.0.1` are not approved release baselines. - `master` may contain unreleased changes after the latest tag; release consumers should use tags and release notes instead of assuming `master` is published evidence. diff --git a/contrib/go.sum b/contrib/go.sum index f0d2aa54..dd375cfb 100644 --- a/contrib/go.sum +++ b/contrib/go.sum @@ -2,7 +2,7 @@ github.com/MicahParks/jwkset v0.11.0 h1:yc0zG+jCvZpWgFDFmvs8/8jqqVBG9oyIbmBtmjOh github.com/MicahParks/jwkset v0.11.0/go.mod h1:U2oRhRaLgDCLjtpGL2GseNKGmZtLs/3O7p+OZaL5vo0= github.com/MicahParks/keyfunc/v3 v3.8.0 h1:Hx2dgIjAXGk9slakM6rV9BOeaWDPEXXZ4Us8guNBfds= github.com/MicahParks/keyfunc/v3 v3.8.0/go.mod h1:z66bkCviwqfg2YUp+Jcc/xRE9IXLcMq6DrgV/+Htru0= -github.com/aatuh/api-toolkit/v4 v4.0.0 h1:6ObM4eLrw6Z4jITc1544E5BHJdLZ1l1Tu1O1MufP31o= +github.com/aatuh/api-toolkit/v4 v4.0.0 h1:XiQQ/RTgNuLECNOHjIIU4P40FghmlnGF+cIIH9uLH6o= github.com/aatuh/api-toolkit/v4 v4.0.0/go.mod h1:BAZGQkcxNfPRa12e5LdttmxC1MISTqiGtnqi5mRRDEs= github.com/aatuh/envvar/v2 v2.1.5 h1:twOIF0rybu21KI3NrPxz/IhVEC/3xcQz3NeHEt4G7+o= github.com/aatuh/envvar/v2 v2.1.5/go.mod h1:DthPYkmwoKwZXuLkplMYurIWBcxY1Y8FF8qFRJsyPYE= diff --git a/docs/README.md b/docs/README.md index 738a9bde..db099c69 100644 --- a/docs/README.md +++ b/docs/README.md @@ -188,6 +188,7 @@ identifies the installed generator and contract tool. | --- | --- | --- | | [Audit and scratch archive policy](audits.md) | Maintainers and release reviewers | Keep local `.audits` and `.trash` scratch material out of tracked release evidence. | | [OpenSSF Best Practices gap review](openssf-best-practices.md) | Maintainers and release reviewers | Track Best Practices badge readiness, unclaimed status, and remaining gaps before publishing a badge. | +| [V4 release-identity incident](release-incident-v4-release-identity.md) | V4 consumers and release reviewers | Follow the current safe action while the v4 tag history and checksum mismatch are reconciled. | | [Release runbook](release-runbook.md) | Release operators | Command source of truth for local checks, release evidence, artifact verification, and baseline policy. | | [Release provenance](provenance.md) | Release consumers and reviewers | Verify GitHub artifact provenance, understand the attested asset scope, and apply the documented trust limits. | | [Reproducible build status](reproducible-builds.md) | Release consumers and maintainers | Distinguish unsupported binary reproducibility from the checksums, signatures, and provenance verified for release assets. | diff --git a/docs/release-incident-v4-release-identity.md b/docs/release-incident-v4-release-identity.md new file mode 100644 index 00000000..5e2ede6b --- /dev/null +++ b/docs/release-incident-v4-release-identity.md @@ -0,0 +1,186 @@ +# V4 release-identity incident + +Audience: v4 consumers, release operators, and independent reviewers. This is +the canonical record for the safe action and immutable evidence while the +published v4 history is repaired. + +**Status:** Open — no v4 tag is approved as a new release-evidence baseline. +`VERIFIED_V4_BASE_REF` is deliberately unset. + +**Owner:** Release engineer + +**Independent reviewer:** Unassigned; required before a final disposition + +**Evidence review date:** 2026-07-22 + +## Consumer action + +Do not adopt `v4.0.1` or `contrib/v4.0.1` for a new deployment. Do not start a +new deployment with `v4.0.0` or `contrib/v4.0.0` either, and do not use any of +those tags as `API_BASE_REF`. + +The published `contrib/v4.0.1` module requires root `v4.0.0` with a checksum +that does not match the Go module proxy's immutable `v4.0.0` content. Go +correctly rejects that dependency. Existing consumers should pin their current +known-good dependency versions and review this document before upgrading. + +Published tags and release assets will not be moved, deleted, recreated, or +overwritten. A repair uses a new SemVer-correct tag after the final decision. + +## Incident summary + +The public root `v4.0.0` module identity and the currently advertised Git tag +are different commits: + +* The Go module proxy resolves root `v4.0.0` to + `24188f75f7c65d41498781d5b48479fe6c65871b`. +* The current Git tag `v4.0.0` resolves to + `3cfc8d44423029ec50516d6b857d938b75067737`, whose parent is `24188f7…`. +* The `v4.0.0` release summary identifies `3cfc8d…` as its tested commit. + +This proves that the tag identity used by the Go module ecosystem differs from +the tag identity currently available from Git. It establishes a release +integrity incident. It does not establish a cause, compromise, or attribution. +It also does not establish who changed the tag or why it changed. + +The v4.0.0 and v4.0.1 release commits share common ancestor +`24c46a2efc50f8d03691047eb425122a740bd26a`; neither release commit is an +ancestor of the other. `v4.0.1` is reachable from `master`; `v4.0.0` is not. + +## Immutable tag and module evidence + +`Git tag target` is the peeled annotated-tag commit from the repository. +`Proxy origin` is the commit reported by `go list -m -json` for the published +module version. Checksums are Go module zip checksums (`h1:`). + +| Published tag | Git tag target and tree | Reachable from `master` | Proxy origin and module checksum | Status for consumers | +| --- | --- | --- | --- | --- | +| `v4.0.0` | `3cfc8d44423029ec50516d6b857d938b75067737`
`01a8f3d686d1923eed53d037ffd190a85b844f66` | No | `24188f75f7c65d41498781d5b48479fe6c65871b`
`h1:XiQQ/RTgNuLECNOHjIIU4P40FghmlnGF+cIIH9uLH6o=` | Do not use; Git and proxy identities diverge. | +| `contrib/v4.0.0` | `352d6574552d1822f573b27807144bf5f29a4a1f`
`b9a5e73a4c44fe7d68dd096d5b0ddf3dd8c21847` | No | `352d6574552d1822f573b27807144bf5f29a4a1f`
`h1:ViK7ZmlUQmpXpKyt9mwTIfW3/8gHl9NKG+TOP8Y3BG4=` | Do not use; paired root tag is not trustworthy. | +| `v4.0.1` | `09e0117828c960453e3fb4cd028a02bc3e56ff33`
`1cb357946d8df655a5ab5b230ba27dfb6957da7c` | Yes | `09e0117828c960453e3fb4cd028a02bc3e56ff33`
`h1:3AdpOFygErDjGFlDABj3GPy7erpnf0eFlIpq6cvFS1M=` | Do not use as a paired v4 baseline pending independent review. | +| `contrib/v4.0.1` | `09e0117828c960453e3fb4cd028a02bc3e56ff33`
`1cb357946d8df655a5ab5b230ba27dfb6957da7c` | Yes | `09e0117828c960453e3fb4cd028a02bc3e56ff33`
`h1:jGLOzYRBsh6beYbyuTO0yAgOt81DCn/hjQKOQ3d8DZk=` | Do not use; its root dependency checksum fails. | + +The published `contrib/v4.0.1` `go.sum` records: + +```text +github.com/aatuh/api-toolkit/v4 v4.0.0 h1:6ObM4eLrw6Z4jITc1544E5BHJdLZ1l1Tu1O1MufP31o= +``` + +The proxy's root `v4.0.0` zip checksum is: + +```text +h1:XiQQ/RTgNuLECNOHjIIU4P40FghmlnGF+cIIH9uLH6o= +``` + +The root `v4.0.0` `go.mod` checksum agrees in both records: + +```text +h1:BAZGQkcxNfPRa12e5LdttmxC1MISTqiGtnqi5mRRDEs= +``` + +This narrows the failure to the root module archive identity, rather than its +`go.mod` file. + +## Published release assets + +There are GitHub releases for root tags only; no GitHub release exists for +`contrib/v4.0.0` or `contrib/v4.0.1`. The root release asset sets contain both +root and contrib SBOMs. The full per-asset digest manifest for each release is +published as an asset and is reproduced below for independent verification. + +| Release | Published | Tested commit in `release-check-summary.json` | Manifest SHA-256 | +| --- | --- | --- | --- | +| [`v4.0.0`](https://github.com/aatuh/api-toolkit/releases/tag/v4.0.0) | 2026-07-11T14:34:38Z | `3cfc8d44423029ec50516d6b857d938b75067737` | `ed28b7a2a453540a5044134e8957a3eb72b19ba692871cea1f03f0022f32e90b` | +| [`v4.0.1`](https://github.com/aatuh/api-toolkit/releases/tag/v4.0.1) | 2026-07-20T12:08:15Z | `09e0117828c960453e3fb4cd028a02bc3e56ff33` | `65b7553016a7ba10194fa5c79f930ad8c527e7072fb9d3e4cae28771a665278f` | + +`v4.0.0` asset digests: + +```text +ac0ae06d4d2c57c127e8fb4ac36c76d31df6014840ce64e6b01158b6a37308b5 release-check-summary.json +58a8ed81a6941c8b9b85e30d4f696b4bba5c4c6ef5dc42e46a137a669593696d release-evidence-logs.tgz +46e83ea60e476e2b7dc25c95709cfc6cbe8f05b1051aa7612c6b2b9dbd5abc5f sbom-root.spdx.json +38972ce8f755f3f7b6452a04cbb2258c8317bdf7c9b8965052b5dee080ee26ce sbom-contrib.spdx.json +8d1c3d03c7549c931f10f3caddbdff041d11fda0fb4761e2e37c4637543175aa dependency-licenses-root.tsv +dcb1d645b743e7d4ccd1583cf192576fddf490ff8c8d8e5a7e41535b0ba98c31 dependency-licenses-contrib.tsv +ae8f368c06f6d5e5a6724d11a00efa31c065efe23ce72c352d9914c10ddaa20e sbom-root.spdx.json.sig +bfc20a0c070da3a9de181278ab90f666d046397d596ae24c5be3d5f08755c5c4 sbom-root.spdx.json.pem +44259d2944a99ab6c8732628eca51765f9380009ed7855229a9b21ce4c2fb6fb sbom-contrib.spdx.json.sig +39c38bb119ca0cbe27a8fe1f547dd346a71b2b8cfa3ec1431d1923f279654bb4 sbom-contrib.spdx.json.pem +``` + +`v4.0.1` asset digests: + +```text +fe1855ba31e54a1661604853a9ead91a1d00c8be658671013563e44bc98584bc release-check-summary.json +d2f816fd29c516fddf1dda06ae3c9943c0d0c3248cb9f9c6f214042c9bfa4f49 release-evidence-logs.tgz +c4a07efe96bbb58e549e7a4c6dc56affb15a2824b9b30d25502034676f6bb4bd sbom-root.spdx.json +bf9bb33e3a0c405d39e24f5b40e970372ed0b73f2baf5c50046ce7d20508e7c5 sbom-contrib.spdx.json +8d1c3d03c7549c931f10f3caddbdff041d11fda0fb4761e2e37c4637543175aa dependency-licenses-root.tsv +ab6daf232d07a0c4509e8434f53859a864404f5710b475180a7cf6f985f3b2d1 dependency-licenses-contrib.tsv +dde0efe3d3de1960cb22f393a756328758b5b225c39988f7b072957aa5d47502 sbom-root.spdx.json.sig +b546dc80e2c56de085f289b9eeafa20b89ccac734f506c5baae6d67d1f049e41 sbom-root.spdx.json.pem +d3d4bbf3b49d8cfe7a9acf737812638e8fa2e481d8113b00ee4700989da23fe2 sbom-contrib.spdx.json.sig +04aa97595b84af81f36079c48b4c5d9c48a0b4614ceebc2c4cbaf9c9fb3a6995 sbom-contrib.spdx.json.pem +``` + +The asset manifests and the GitHub asset API supply these SHA-256 values. Their +presence does not make either release verified: the v4.0.0 summary schema does +not bind a release tag, commit tree, branch reachability, or module identities +to the evidence. That missing binding is remediated by REL-002. + +## Provisional disposition and recovery + +The following is a safety hold, not the final public status required by +REL-000: + +| Tag | Provisional safety hold | Final status | +| --- | --- | --- | +| `v4.0.0` | Do not use: Git tag and proxy identity diverge. | Pending independent review. | +| `contrib/v4.0.0` | Do not use: paired root release is untrustworthy. | Pending independent review. | +| `v4.0.1` | Do not use as a paired release baseline. | Pending independent review. | +| `contrib/v4.0.1` | Do not use: root dependency checksum fails. | Pending independent review. | + +The release owner and independent reviewer must make one final public choice +for each tag: **Verified supported baseline**, **Superseded by a verified +release**, or **Withdrawn — do not use**. They must publish that same choice in +the GitHub release notes, `CHANGELOG.md`, README, support policy, and release +runbook. + +The proposed repair path is to leave every existing tag untouched, reconcile +the chosen verified code history into `master`, and publish a new paired v4 +repair tag. Use `v4.0.2` only if the repair is patch-compatible; do not create +v5 merely to evade this incident. The reviewer must approve the SemVer choice +and record the eventual `REPAIR_RELEASE_TAG` and `VERIFIED_V4_BASE_REF` here. + +## Independent review checklist + +Before setting `VERIFIED_V4_BASE_REF` or publishing a repair release, the +reviewer must independently: + +1. Re-run the evidence commands below from a clean checkout and compare every + tag target, tree, proxy origin, and checksum with this record. +2. Download each published release asset and verify its SHA-256 digest against + the corresponding manifest above. +3. Confirm that published tags have not changed again and that the selected + verified baseline is an ancestor of `origin/master`. +4. Decide and publish the final status of all four affected tags. +5. Confirm the next paired root/contrib tag has exact commit-bound evidence, + asset verification, and no `replace`-based module installation. + +## Evidence commands + +Run these commands from a clean checkout. They are evidence collection, not a +substitute for the independent review above. + +```sh +git show-ref --tags -d | rg '(^|/)(v4\.0\.[01]|contrib/v4\.0\.[01])($|\^\{\})' +git rev-parse v4.0.0^{} v4.0.0^{}^{tree} +git rev-parse contrib/v4.0.0^{} contrib/v4.0.0^{}^{tree} +git rev-parse v4.0.1^{} v4.0.1^{}^{tree} +git rev-parse contrib/v4.0.1^{} contrib/v4.0.1^{}^{tree} +git merge-base v4.0.0 v4.0.1 +git merge-base --is-ancestor v4.0.1 master +GOWORK=off GOTOOLCHAIN=local go list -m -json github.com/aatuh/api-toolkit/v4@v4.0.0 +GOWORK=off GOTOOLCHAIN=local go list -m -json github.com/aatuh/api-toolkit/contrib/v4@v4.0.1 +GOWORK=off GOTOOLCHAIN=local make docs-check +``` diff --git a/docs/release-runbook.md b/docs/release-runbook.md index fce05f5d..baac88d4 100644 --- a/docs/release-runbook.md +++ b/docs/release-runbook.md @@ -4,9 +4,12 @@ Audience: release operators and reviewers who need the canonical command sequence, evidence expectations, artifact verification path, and baseline maintenance rule. -Supported v4 release baseline: `v4.0.0` for v4 patch and minor releases. The -v4 major-release evidence compared against `v3.1.2` when recording intentional -v3-to-v4 breakage evidence. +V4 release publication is paused while the +[v4 release-identity incident](release-incident-v4-release-identity.md) is +open. Do not use `v4.0.0` or `v4.0.1` as `API_BASE_REF` for a new release until +the incident records `VERIFIED_V4_BASE_REF`. The v4 major-release evidence +compared against `v3.1.2` when recording intentional v3-to-v4 breakage +evidence. Supported Go toolchain: Go 1.25.x for root and contrib. Release and reviewer commands use `GOTOOLCHAIN=local` to ensure the module `go` directives and @@ -15,9 +18,10 @@ GitHub Actions setup stay compatible with the provisioned local toolchain. ## Baseline maintenance rule This runbook owns the supported `API_BASE_REF` baseline for releases. For v4 -patch and minor releases, set `API_BASE_REF` to the latest published v4 tag. -The v4 major-release evidence used `API_BASE_REF=v3.1.2` as major-version -transition evidence. When the supported v4 baseline changes, +patch and minor releases, set it only to `VERIFIED_V4_BASE_REF` from the open +incident; a latest-published-tag fallback is forbidden. The v4 major-release +evidence used `API_BASE_REF=v3.1.2` as major-version transition evidence. When +the supported v4 baseline changes, update this line first, then update command examples in `README.md`, `VERSIONING.md`, `docs/release-review.md`, `docs/release-notes.md`, scripts that mention the supported baseline, and any release evidence fixtures in the same diff --git a/docs/site/search-index.json b/docs/site/search-index.json index a8e2738d..6b2152eb 100644 --- a/docs/site/search-index.json +++ b/docs/site/search-index.json @@ -333,13 +333,13 @@ "title": "Documentation", "category": "navigation", "url": "https://github.com/aatuh/api-toolkit/blob/master/docs/README.md", - "text": "docs/README.md Documentation Audience: readers who need the fastest path to the right api-toolkit document without scanning the root README. New users and application developers Document Audience Purpose [Library-first path] Documentation Audience: readers who need the fastest path to the right api-toolkit document without scanning the root README. New users and application developers Document Audience Purpose [Library-first path] library-first.md Existing-service users Add the smallest useful root package set to a `net/http` chi or app-owned router service. [Minimal core path] minimal-core.md Existing-service users Use only `httpx` `binding` `middleware/maxbody` and `middleware/timeout` without contrib or generators. [Core package decision guide] core-package-guide.md Adopters and reviewers Choose packages by use case when-not-to-use guidance stability tier dependency note and example link. [Scaffold-first path] scaffold-first.md New service teams Generate app-owned service code and understand what the toolkit owns versus what the generated app owns. [Contrib adapter path] contrib-adapters.md Adapter adopters Decide when to add supported contrib adapters integrations examples or generator tooling. [CLI and scaffold identity] cli-scaffold-identity.md Adopters and maintainers Decide how CLI scaffold generated-service and library-first identities stay separate. [Stable core charter] stable-core.md New users and maintainers Decide which root packages are the recommended small-core dependency surface and what evidence stable packages need. [Roadmap and non-goals] ../ROADMAP.md Adopters and contributors See current direction candidate work explicit non-goals and proposal rules. [Core readiness matrix] core-readiness.md API consumers and release reviewers Review docs examples tests fuzz benchmark compatibility security review and production caveats for each stable package. [Alternatives] alternatives.md Evaluators Decide when to use `api-toolkit` instead of `net/http` chi oapi-codegen Goa Connect or app-owned helpers. [Getting started] getting-started.md Scaffold users Generate run and verify the production-oriented app-owned service scaffold. [Full service scaffold] full-service-scaffold.md Application teams Understand the `saas-api-full` production foundation support tier and integration-test policy. [Reference service] reference-service.md Maintainers and release reviewers Verify the checked-in `saas-api-full` adoption proof and know which evidence is local Docker-backed or deployment-owned. [Adopter story] adopters.md Evaluators and maintainers Read the maintainer-owned reference-service outcome friction changes and evidence limits without treating it as a customer case study. [Production readiness] production-readiness.md Technical leads and platform owners Decide which surfaces are production-ready supported-adapter experimental caveated or part of the adapter maturity review. [V3 migration guide] migration/v3.md Application teams upgrading dependencies Upgrade root contrib and generated-service adoption paths within the v3 line. [V4 migration guide] migration/v4.md Application teams upgrading major versions Update module paths and replace removed root-port contracts. [Troubleshooting] troubleshooting.md Application developers and maintainers Diagnose Go version contrib tier timeout buffering health idempotency auth and generated-service issues. [Test coverage evidence] test-coverage.md Maintainers and release reviewers Read the coverage gate outputs package-level floor summary and release-evidence relationship. [Package coverage trend] coverage-trend.md Maintainers and release reviewers Compare root and selected contrib package coverage across published releases. [Benchmark baselines] performance.md Maintainers and release reviewers Run and interpret package-level benchmark baselines before performance-sensitive changes or releases. [Coverage hardening backlog] coverage-hardening-backlog.md Maintainers Track behavior-test prerequisites before raising high-risk package coverage floors. [Cookbook] cookbook.md Application developers Complete common API tasks with commands requests expected responses and caveats. [Examples catalog] ../contrib/examples/README.md Developers copying runnable patterns Find each contrib example its command endpoint expected result required env and safety note. [Architecture] architecture.md Developers and maintainers Understand the hexagonal boundary between stable core ports and contrib adapters. The contrib CLI can scaffold the fuller reusable service baseline: Use `--auth jwt` or `--auth clerk` when the generated service should validate bearer tokens via JWKS instead of local API keys. Bearer scaffolds require the matching issuer audience and JWKS URL environment variables extract tenant scope from validated token claims and keep the same tenant mismatch idempotency OpenAPI and admin-route defaults. Generated services wire the default router to the contrib Prometheus recorder so protected `/metrics` includes bounded HTTP request counters and histograms using method route pattern and status labels. Generated services also expose `/version` with build metadata. The generated Makefile `build` target stamps the binary with `VERSION` `BUILD_COMMIT` and `BUILD_DATE` the Dockerfile accepts matching build args and uses `dev`/`unknown` defaults for local builds. Use `--profile dev-api --auth dev-headers` only for local development services that need debug-header authentication. The generated service requires explicit dev-bypass environment variables trusts only configured loopback proxies by default uses separate debug tenant and scope headers and refuses to start with dev-header auth when `ENV production`. The `saas-api-full` profile keeps the lean `saas-api` default intact and starts the heavier Postgres Redis production foundation described in [full-service-scaffold.md] full-service-scaffold.md . The full profile is wired through `bootstrap.NewAPIService` exposes `/livez` separately from `/readyz` keeps detailed health/metrics/pprof on admin routes and enables runtime OpenAPI request validation by default. Reference-service evidence starts at [reference-service.md] reference-service.md and then follows the app-owned docs under `examples/reference-saas-api` including its README deployment starter docs observability runbook and provider workflow runbook. Read the [adopter story] adopters.md for the maintainer-owned outcome and its explicit evidence limits. The same CLI can review OpenAPI artifacts before release. `contracts lint` checks operation IDs non-public security requirements unsafe-write tenant idempotency rate-limit metadata request body metadata documented 2xx success responses Problem Details responses and protected operator paths. `contracts diff` allows additive operations and fails closed on removed operations changed operation IDs removed documented parameters added required parameters removed documented responses request-body tightening or content removal response content removal changed operation or inherited global security requirements component and inline schema removals obvious schema type/required/property/enum narrowing or drift in tenant idempotency rate-limit admin and deprecation route policy metadata: `clients go` emits a stdlib-only Go client package for the supported OpenAPI subset: JSON request bodies path/query/header options API-key auth bearer auth and Problem Details error decoding. The default `raw` style preserves the original operation helpers `--style typed` also generates component schema structs typed request/response methods and raw method escape hatches. The contract and client commands accept OpenAPI 3.1 schema `type` arrays that include `null` and schema-level `examples` normalizing them to the toolkit s compatibility model before validation. `api-toolkit version` prints the tool version Go runtime main module core module version contrib module version and optional build commit/date fields. Use `api-toolkit version --json` for machine-readable release evidence that identifies the installed generator and contract tool. Security operations and runtime behavior Document Audience Purpose [Security posture] security.md Developers and operators Configure secure defaults dangerous bypasses trusted proxies health detail and docs surfaces. [Security threat model] threat-model.md Maintainers application teams and security reviewers Review protected assets assumptions threats mitigations and verification evidence for security-sensitive surfaces. [Package security review] security-review.md Maintainers and reviewers Record threat input secret authorization DoS data-leakage and observability review evidence for each affected package. [Auth production guide] auth.md Developers and operators Configure API-key JWT tenant role JWK rotation clock skew failure modes and auth tests. [Idempotency production guide] idempotency.md Developers and operators Configure storage locking TTL replay semantics request hashes tenant scoping conflicts and Redis/Postgres ownership. [Health and admin operations] operations.md Operators and developers Split public probes from detailed health metrics pprof admin auth network policy and fail-closed checks. [OpenAPI contract workflow] openapi-workflow.md Maintainers and application teams Run route metadata golden diff contract tests generated docs validation and drift handling. [Runtime configuration] configuration.md Operators and developers Review required production env vars defaults unsafe dev defaults and startup validation. [Observability] observability.md Operators and developers Keep metrics logs traces correlation IDs and dashboards useful and redaction-safe. [Scaffold support matrix] scaffold-support.md Generated service teams Understand what generated code is supported app-owned fragile on regeneration and migration-owned. [Adapter maturity matrix] adapter-maturity.md Contrib adopters Review supported/tested/experimental posture for Postgres Redis Stripe Resend Clerk OpenTelemetry CORS validation and related adapters. [Safe defaults audit] safe-defaults.md Developers and reviewers Check fail-open and fail-closed behavior for root and contrib middleware before broad rollout. [Middleware safety matrix] middleware-safety.md Developers and reviewers Decide which middleware is safe globally route-specific forbidden for streaming or requires opt-outs. [Input-size threat review] input-size-threat-review.md Developers reviewers and operators Review header body JSON query multipart replay-capture and timeout-capture size limits before changing route contracts. [Negative-path test matrix] negative-path-test-matrix.tsv Maintainers and release reviewers Verify stable-package tests for malformed input missing headers bad content types invalid auth invalid tenant oversized bodies and invalid query limits. [Testing policy] testing.md Maintainers and release reviewers Keep tests deterministic with fake clocks injected sleep bounded retries and documented deadlock guards. [Security policy] ../SECURITY.md Security reporters and release consumers Report vulnerabilities and understand supported release security handling. [Security advisory drill] security-advisory-drill.md Maintainers and security reviewers Review the completed fictional private-advisory drill and disclosure process. [Code of conduct] ../CODE_OF_CONDUCT.md Contributors and maintainers Set expectations for respectful project participation and conduct reporting. [Panic policy] ../PANIC_POLICY.md Maintainers and API designers Decide when panics are allowed and how HTTP recovery behaves. [Metrics] metrics.md Operators and developers Use low-cardinality HTTP metric names and labels. [Support policy] support-policy.md Adopters and maintainers Understand the supported Go line platform gate and generated-service ownership limits. [Dependency boundary] dependency-boundary.md Maintainers Keep root stable code free of contrib adapter dependencies. [Auth dependency split decision] auth-dependency-split.md Adopters and maintainers Understand current v3 JWT/JWK module graph cost and the v4 target for auth-heavy packages. [Provider adapter split decision] provider-adapter-split.md Adopters and maintainers Keep Postgres Redis Stripe Resend OpenTelemetry router and provider adapters out of stable core. [Extension module assessment] extension-module-assessment.md Maintainers and release reviewers Reject speculative provider-module splits until adoption ownership dependency and release-cadence evidence supports one. [Dependency policy] dependency-policy.md Maintainers Review allowed dependency classes banned patterns update SLA and security-sensitive review gates. [License policy] license-policy.md Maintainers Review allowed dependency licenses dependency-review enforcement and exception handling. [Dependency risk] dependency-risk.md Release reviewers and security maintainers Review imported-but-not-called vulnerability disposition and ownership. [Dependency footprint] dependency-footprint.md Adopters and release reviewers Run and interpret root/contrib dependency footprint and base-ref diff reports. Stability compatibility and package docs Document Audience Purpose [Versioning] ../VERSIONING.md API consumers and maintainers Define the stable core API surface and contrib compatibility policy. [Public API inventory] api-inventory.md API consumers and maintainers Review generated exported symbols grouped by package stability tier added version and deprecation status. [API reference index] api-reference.md API consumers Jump from each stable or compatibility-only root package to pkg.go.dev and its compile-checked example. [Generated API docs site] site/index.html API consumers Search package status examples compatibility docs and migration guides from a static generated site. [Downstream compatibility kit] downstream-compatibility.md API consumers Run experimental `compatkit` service checks against an in-process handler or explicit base URL. [API review checklist] api-review-checklist.md Maintainers Review naming zero values context cancellation errors concurrency options return types and interface necessity. [Governance] governance.md Maintainers Review stable API review board process branch protection CODEOWNERS required checks release approval and maintainer succession policy. [API addition example exceptions] api-addition-exceptions.tsv Maintainers Record exact symbol exceptions when a new stable exported identifier has a doc comment and release note but a compile-checked example would mislead. [Deprecation policy] deprecations.md Maintainers and release reviewers Track deprecation format replacements removal horizon migration snippets and release-note requirements. [Interface ownership] interface-ownership.md Maintainers Document whether exported interfaces are user-implemented adapter-owned test-only or compatibility-sensitive. [Options struct audit] options-structs.md Maintainers Review defaults validation behavior zero-value behavior and example evidence for stable exported options structs. [Global state audit] global-state-audit.md Maintainers Review package-level globals in stable packages and the limited mutable-state exceptions. [Context and cancellation] context-cancellation.md Maintainers and adopters Apply context propagation and bounded cleanup rules across HTTP auth idempotency scheduler and client APIs. [Error taxonomy] errors.md Maintainers and API consumers Match sentinel typed field wrapped configuration and Problem Details errors safely. [Concurrency safety] concurrency.md API consumers and maintainers Decide which values are immutable request-scoped synchronized or implementation-owned. [Resource lifecycle] resource-lifecycle.md Maintainers and adopters Track ownership for close shutdown timers goroutines stores adapters and generated service resources. [Ports surface] ports-surface.md Maintainers and advanced API consumers Identify compatibility-sensitive port history and preferred replacements. [Ports export exceptions] ports-export-exceptions.tsv Maintainers Review the accepted ADR required for any new root `ports` export. [V3 compatibility record] v3-compatibility-roadmap.md Maintainers Track completed v3 cleanup decisions and remaining compatibility-sensitive guardrails. [V4 scope cleanup plan] v4-plan.md Maintainers and advanced adopters Plan which root surfaces to keep stable demote split or remove only in a future major release. [Ports v4 migration ledger] ports-v4-migration-ledger.tsv Maintainers and advanced adopters Record every current root-port export consumer packages implementation evidence v3 deprecation status and v4 disposition. [Package doc standard] package-doc-standard.md Maintainers Apply the minimum package-doc template and see the placeholder inventory remediated in this pass. [Package classification guide] package-classification.md Maintainers and adopters Read the rendered status glossary before using the TSV source of truth. [Core readiness matrix] core-readiness.md API consumers and release reviewers Review stable package readiness by docs examples tests fuzz benchmark compatibility security review and production caveat. [Module-boundary ADR] adr/0001-module-boundaries.md Maintainers Record the v3 decision to keep root and contrib modules while deferring deeper splits to v4 planning. `docs/package-classification.tsv` Maintainers and automation Machine-readable API and test-status classification for every package. `docs/package-owners.tsv` Maintainers and automation Machine-readable maintainer owner test owner stability tier and release-blocker status for every package. `docs/supported-adapter-contracts.tsv` Maintainers and automation Machine-readable behavior contracts and evidence paths for supported contrib adapters. `docs/supported-adapter-test-realism.tsv` Maintainers and automation Machine-readable default and scheduled/manual test-realism evidence for each supported contrib adapter. Release and evidence Document Audience Purpose [Audit and scratch archive policy] audits.md Maintainers and release reviewers Keep local `.audits` and `.trash` scratch material out of tracked release evidence. [OpenSSF Best Practices gap review] openssf-best-practices.md Maintainers and release reviewers Track Best Practices badge readiness unclaimed status and remaining gaps before publishing a badge. [Release runbook] release-runbook.md Release operators Command source of truth for local checks release evidence artifact verification and baseline policy. [Release provenance] provenance.md Release consumers and reviewers Verify GitHub artifact provenance understand the attested asset scope and apply the documented trust limits. [Reproducible build status] reproducible-builds.md Release consumers and maintainers Distinguish unsupported binary reproducibility from the checksums signatures and provenance verified for release assets. [Release review checklist] release-review.md Release reviewers Short path through summary fields manifests dirty-tree decisions artifacts and release notes. [Governance] governance.md Maintainers Branch protection CODEOWNERS tag protection required checks and release approval expectations. [Changelog] ../CHANGELOG.md Release consumers Concise user-facing history for published releases. [Release notes] release-notes.md Release consumers and maintainers Dated behavior changes upgrade notes and package-tied contrib drift acknowledgements. [Release manifests] release-manifests.md Release reviewers and maintainers Human guide for package classification contrib drift contrib dispositions and vulnerability dispositions. `docs/contrib-api-drift-packages.txt` Maintainers and automation Selected contrib packages reviewed by drift checks supported-adapter incompatible drift is gate-enforced. `docs/supported-adapter-contracts.tsv` Maintainers and automation Required supported-adapter behavior contracts with direct-test and release-drift evidence. `docs/supported-adapter-test-realism.tsv` Maintainers and automation Required supported-adapter realism rows that distinguish direct-unit fake DB miniredis hermetic fixture and scheduled/manual real-service evidence. `docs/contrib-api-drift-dispositions.tsv` Release reviewers and automation Owner status review date expiry and acknowledgement for current contrib drift. `docs/vulnerability-dispositions.tsv` Release reviewers and automation Owner review expiry and upgrade trigger rows for imported-only vulnerability IDs when present. `release-check-summary.json` Release reviewers Generated local release evidence summary only clean publication evidence is publishable. Documentation quality workflow Use the narrowest check that matches the change: Change type Preferred command Notes Documentation-only edits `GOTOOLCHAIN local make docs-check` Runs documentation contracts generated docs-site drift checks getting-started build extraction API/docs policy checks and release evidence parser contracts. Architecture or dependency-boundary edits `GOTOOLCHAIN local make dependency-boundary-check` Runs the stable-core import boundary check before the broader docs gate. V3 cleanup readiness `GOTOOLCHAIN local make v3-readiness-check` Runs focused compatibility-sensitive surface guardrails for major-version cleanup planning and release-note requirements. Docs plus ordinary code changes `GOTOOLCHAIN local make fast-check` Runs `docs-check` and unit tests without rewriting files. Reference service coverage `GOTOOLCHAIN local make reference-service-coverage` Records non-Docker generated-service coverage under `.ci-result/coverage/` without folding app-owned code into toolkit coverage thresholds. Reference service load `GOTOOLCHAIN local make reference-service-load` Records non-Docker generated-service latency throughput memory allocation and expected auth-failure evidence under `.ci-result/reference-service-load/`. Generated full-profile soak `GOTOOLCHAIN local make generated-soak-check` Records nightly-style generated `saas-api-full` race/goroutine soak evidence and repeated Docker integration-cycle logs under `.ci-result/generated-soak/`. Generated full-profile failure `GOTOOLCHAIN local make generated-failure-check` Records generated `saas-api-full` Redis-down Postgres-down expired API-key bad JWKS and slow downstream timeout evidence under `.ci-result/generated-failure/`. Timeout determinism `GOTOOLCHAIN local make timeout-determinism-check` Repeats the hard-timeout late-write test under normal and race runs then runs the root timeout/idempotency/rate-limit/scheduler race subset. Reviewer or audit pass `GOTOOLCHAIN local make audit-check` Non-mutating reviewer gate with lint vuln gosec build smoke GitHub Actions pin audit docs contracts tests race and fuzz smoke. Generated files examples scripts package docs or repo-wide contracts `GOTOOLCHAIN local make finalize` when practical Installs tools and may rewrite Go formatting and module files through `fmt` and `tidy` avoid it in shared dirty worktrees unless that mutation is intended. Do not treat `make finalize` as release evidence. Release publication evidence is owned by [release-runbook.md] release-runbook.md . If the local Go version is not Go 1.25.x `GOTOOLCHAIN local` failures are expected. Install the supported toolchain or use the repository CI image before running root and contrib gates. Canonical high-centrality paths These literal paths are kept here so docs index coverage checks can detect when important public docs disappear from navigation: `README.md` `ROADMAP.md` `docs/library-first.md` `docs/minimal-core.md` `docs/core-package-guide.md` `docs/scaffold-first.md` `docs/cli-scaffold-identity.md` `docs/contrib-adapters.md` `docs/getting-started.md` `docs/cookbook.md` `docs/architecture.md` `docs/migration/v3.md` `docs/troubleshooting.md` `docs/security.md` `docs/threat-model.md` `docs/security-review.md` `docs/auth.md` `docs/idempotency.md` `docs/operations.md` `docs/openapi-workflow.md` `docs/configuration.md` `docs/observability.md` `docs/scaffold-support.md` `docs/adapter-maturity.md` `docs/safe-defaults.md` `docs/middleware-safety.md` `docs/input-size-threat-review.md` `docs/testing.md` `docs/site/index.html` `docs/downstream-compatibility.md` `SECURITY.md` `CODE_OF_CONDUCT.md` `docs/metrics.md` `docs/support-policy.md` `docs/dependency-policy.md` `docs/license-policy.md` `docs/dependency-footprint.md` `docs/adr/0001-module-boundaries.md` `VERSIONING.md` `docs/api-inventory.md` `docs/api-review-checklist.md` `docs/api-reference.md` `docs/core-readiness.md` `docs/deprecations.md` `docs/interface-ownership.md` `docs/context-cancellation.md` `docs/errors.md` `docs/concurrency.md` `docs/resource-lifecycle.md` `docs/release-runbook.md` `docs/release-review.md` `docs/audits.md` `docs/openssf-best-practices.md` `docs/release-notes.md` `docs/release-manifests.md` `docs/ports-surface.md` `docs/v3-compatibility-roadmap.md` `docs/production-readiness.md` `docs/governance.md` `docs/performance.md` `docs/dependency-boundary.md` `docs/dependency-risk.md` `docs/package-doc-standard.md` `docs/full-service-scaffold.md` `docs/package-classification.tsv` `docs/supported-adapter-contracts.tsv` `docs/supported-adapter-test-realism.tsv` `docs/contrib-api-drift-packages.txt` `docs/contrib-api-drift-dispositions.tsv` `docs/vulnerability-dispositions.tsv` `contrib/examples/README.md` `examples/reference-saas-api/README.md` `examples/reference-saas-api/deploy/helm/README.md` `examples/reference-saas-api/deploy/kubernetes/README.md` `examples/reference-saas-api/deploy/terraform/aws/README.md` `examples/reference-saas-api/observability/runbooks/observability.md` `examples/reference-saas-api/docs/providers/provider-runbook.md` `PANIC_POLICY.md` and `release-check-summary.json`." + "text": "docs/README.md Documentation Audience: readers who need the fastest path to the right api-toolkit document without scanning the root README. New users and application developers Document Audience Purpose [Library-first path] Documentation Audience: readers who need the fastest path to the right api-toolkit document without scanning the root README. New users and application developers Document Audience Purpose [Library-first path] library-first.md Existing-service users Add the smallest useful root package set to a `net/http` chi or app-owned router service. [Minimal core path] minimal-core.md Existing-service users Use only `httpx` `binding` `middleware/maxbody` and `middleware/timeout` without contrib or generators. [Core package decision guide] core-package-guide.md Adopters and reviewers Choose packages by use case when-not-to-use guidance stability tier dependency note and example link. [Scaffold-first path] scaffold-first.md New service teams Generate app-owned service code and understand what the toolkit owns versus what the generated app owns. [Contrib adapter path] contrib-adapters.md Adapter adopters Decide when to add supported contrib adapters integrations examples or generator tooling. [CLI and scaffold identity] cli-scaffold-identity.md Adopters and maintainers Decide how CLI scaffold generated-service and library-first identities stay separate. [Stable core charter] stable-core.md New users and maintainers Decide which root packages are the recommended small-core dependency surface and what evidence stable packages need. [Roadmap and non-goals] ../ROADMAP.md Adopters and contributors See current direction candidate work explicit non-goals and proposal rules. [Core readiness matrix] core-readiness.md API consumers and release reviewers Review docs examples tests fuzz benchmark compatibility security review and production caveats for each stable package. [Alternatives] alternatives.md Evaluators Decide when to use `api-toolkit` instead of `net/http` chi oapi-codegen Goa Connect or app-owned helpers. [Getting started] getting-started.md Scaffold users Generate run and verify the production-oriented app-owned service scaffold. [Full service scaffold] full-service-scaffold.md Application teams Understand the `saas-api-full` production foundation support tier and integration-test policy. [Reference service] reference-service.md Maintainers and release reviewers Verify the checked-in `saas-api-full` adoption proof and know which evidence is local Docker-backed or deployment-owned. [Adopter story] adopters.md Evaluators and maintainers Read the maintainer-owned reference-service outcome friction changes and evidence limits without treating it as a customer case study. [Production readiness] production-readiness.md Technical leads and platform owners Decide which surfaces are production-ready supported-adapter experimental caveated or part of the adapter maturity review. [V3 migration guide] migration/v3.md Application teams upgrading dependencies Upgrade root contrib and generated-service adoption paths within the v3 line. [V4 migration guide] migration/v4.md Application teams upgrading major versions Update module paths and replace removed root-port contracts. [Troubleshooting] troubleshooting.md Application developers and maintainers Diagnose Go version contrib tier timeout buffering health idempotency auth and generated-service issues. [Test coverage evidence] test-coverage.md Maintainers and release reviewers Read the coverage gate outputs package-level floor summary and release-evidence relationship. [Package coverage trend] coverage-trend.md Maintainers and release reviewers Compare root and selected contrib package coverage across published releases. [Benchmark baselines] performance.md Maintainers and release reviewers Run and interpret package-level benchmark baselines before performance-sensitive changes or releases. [Coverage hardening backlog] coverage-hardening-backlog.md Maintainers Track behavior-test prerequisites before raising high-risk package coverage floors. [Cookbook] cookbook.md Application developers Complete common API tasks with commands requests expected responses and caveats. [Examples catalog] ../contrib/examples/README.md Developers copying runnable patterns Find each contrib example its command endpoint expected result required env and safety note. [Architecture] architecture.md Developers and maintainers Understand the hexagonal boundary between stable core ports and contrib adapters. The contrib CLI can scaffold the fuller reusable service baseline: Use `--auth jwt` or `--auth clerk` when the generated service should validate bearer tokens via JWKS instead of local API keys. Bearer scaffolds require the matching issuer audience and JWKS URL environment variables extract tenant scope from validated token claims and keep the same tenant mismatch idempotency OpenAPI and admin-route defaults. Generated services wire the default router to the contrib Prometheus recorder so protected `/metrics` includes bounded HTTP request counters and histograms using method route pattern and status labels. Generated services also expose `/version` with build metadata. The generated Makefile `build` target stamps the binary with `VERSION` `BUILD_COMMIT` and `BUILD_DATE` the Dockerfile accepts matching build args and uses `dev`/`unknown` defaults for local builds. Use `--profile dev-api --auth dev-headers` only for local development services that need debug-header authentication. The generated service requires explicit dev-bypass environment variables trusts only configured loopback proxies by default uses separate debug tenant and scope headers and refuses to start with dev-header auth when `ENV production`. The `saas-api-full` profile keeps the lean `saas-api` default intact and starts the heavier Postgres Redis production foundation described in [full-service-scaffold.md] full-service-scaffold.md . The full profile is wired through `bootstrap.NewAPIService` exposes `/livez` separately from `/readyz` keeps detailed health/metrics/pprof on admin routes and enables runtime OpenAPI request validation by default. Reference-service evidence starts at [reference-service.md] reference-service.md and then follows the app-owned docs under `examples/reference-saas-api` including its README deployment starter docs observability runbook and provider workflow runbook. Read the [adopter story] adopters.md for the maintainer-owned outcome and its explicit evidence limits. The same CLI can review OpenAPI artifacts before release. `contracts lint` checks operation IDs non-public security requirements unsafe-write tenant idempotency rate-limit metadata request body metadata documented 2xx success responses Problem Details responses and protected operator paths. `contracts diff` allows additive operations and fails closed on removed operations changed operation IDs removed documented parameters added required parameters removed documented responses request-body tightening or content removal response content removal changed operation or inherited global security requirements component and inline schema removals obvious schema type/required/property/enum narrowing or drift in tenant idempotency rate-limit admin and deprecation route policy metadata: `clients go` emits a stdlib-only Go client package for the supported OpenAPI subset: JSON request bodies path/query/header options API-key auth bearer auth and Problem Details error decoding. The default `raw` style preserves the original operation helpers `--style typed` also generates component schema structs typed request/response methods and raw method escape hatches. The contract and client commands accept OpenAPI 3.1 schema `type` arrays that include `null` and schema-level `examples` normalizing them to the toolkit s compatibility model before validation. `api-toolkit version` prints the tool version Go runtime main module core module version contrib module version and optional build commit/date fields. Use `api-toolkit version --json` for machine-readable release evidence that identifies the installed generator and contract tool. Security operations and runtime behavior Document Audience Purpose [Security posture] security.md Developers and operators Configure secure defaults dangerous bypasses trusted proxies health detail and docs surfaces. [Security threat model] threat-model.md Maintainers application teams and security reviewers Review protected assets assumptions threats mitigations and verification evidence for security-sensitive surfaces. [Package security review] security-review.md Maintainers and reviewers Record threat input secret authorization DoS data-leakage and observability review evidence for each affected package. [Auth production guide] auth.md Developers and operators Configure API-key JWT tenant role JWK rotation clock skew failure modes and auth tests. [Idempotency production guide] idempotency.md Developers and operators Configure storage locking TTL replay semantics request hashes tenant scoping conflicts and Redis/Postgres ownership. [Health and admin operations] operations.md Operators and developers Split public probes from detailed health metrics pprof admin auth network policy and fail-closed checks. [OpenAPI contract workflow] openapi-workflow.md Maintainers and application teams Run route metadata golden diff contract tests generated docs validation and drift handling. [Runtime configuration] configuration.md Operators and developers Review required production env vars defaults unsafe dev defaults and startup validation. [Observability] observability.md Operators and developers Keep metrics logs traces correlation IDs and dashboards useful and redaction-safe. [Scaffold support matrix] scaffold-support.md Generated service teams Understand what generated code is supported app-owned fragile on regeneration and migration-owned. [Adapter maturity matrix] adapter-maturity.md Contrib adopters Review supported/tested/experimental posture for Postgres Redis Stripe Resend Clerk OpenTelemetry CORS validation and related adapters. [Safe defaults audit] safe-defaults.md Developers and reviewers Check fail-open and fail-closed behavior for root and contrib middleware before broad rollout. [Middleware safety matrix] middleware-safety.md Developers and reviewers Decide which middleware is safe globally route-specific forbidden for streaming or requires opt-outs. [Input-size threat review] input-size-threat-review.md Developers reviewers and operators Review header body JSON query multipart replay-capture and timeout-capture size limits before changing route contracts. [Negative-path test matrix] negative-path-test-matrix.tsv Maintainers and release reviewers Verify stable-package tests for malformed input missing headers bad content types invalid auth invalid tenant oversized bodies and invalid query limits. [Testing policy] testing.md Maintainers and release reviewers Keep tests deterministic with fake clocks injected sleep bounded retries and documented deadlock guards. [Security policy] ../SECURITY.md Security reporters and release consumers Report vulnerabilities and understand supported release security handling. [Security advisory drill] security-advisory-drill.md Maintainers and security reviewers Review the completed fictional private-advisory drill and disclosure process. [Code of conduct] ../CODE_OF_CONDUCT.md Contributors and maintainers Set expectations for respectful project participation and conduct reporting. [Panic policy] ../PANIC_POLICY.md Maintainers and API designers Decide when panics are allowed and how HTTP recovery behaves. [Metrics] metrics.md Operators and developers Use low-cardinality HTTP metric names and labels. [Support policy] support-policy.md Adopters and maintainers Understand the supported Go line platform gate and generated-service ownership limits. [Dependency boundary] dependency-boundary.md Maintainers Keep root stable code free of contrib adapter dependencies. [Auth dependency split decision] auth-dependency-split.md Adopters and maintainers Understand current v3 JWT/JWK module graph cost and the v4 target for auth-heavy packages. [Provider adapter split decision] provider-adapter-split.md Adopters and maintainers Keep Postgres Redis Stripe Resend OpenTelemetry router and provider adapters out of stable core. [Extension module assessment] extension-module-assessment.md Maintainers and release reviewers Reject speculative provider-module splits until adoption ownership dependency and release-cadence evidence supports one. [Dependency policy] dependency-policy.md Maintainers Review allowed dependency classes banned patterns update SLA and security-sensitive review gates. [License policy] license-policy.md Maintainers Review allowed dependency licenses dependency-review enforcement and exception handling. [Dependency risk] dependency-risk.md Release reviewers and security maintainers Review imported-but-not-called vulnerability disposition and ownership. [Dependency footprint] dependency-footprint.md Adopters and release reviewers Run and interpret root/contrib dependency footprint and base-ref diff reports. Stability compatibility and package docs Document Audience Purpose [Versioning] ../VERSIONING.md API consumers and maintainers Define the stable core API surface and contrib compatibility policy. [Public API inventory] api-inventory.md API consumers and maintainers Review generated exported symbols grouped by package stability tier added version and deprecation status. [API reference index] api-reference.md API consumers Jump from each stable or compatibility-only root package to pkg.go.dev and its compile-checked example. [Generated API docs site] site/index.html API consumers Search package status examples compatibility docs and migration guides from a static generated site. [Downstream compatibility kit] downstream-compatibility.md API consumers Run experimental `compatkit` service checks against an in-process handler or explicit base URL. [API review checklist] api-review-checklist.md Maintainers Review naming zero values context cancellation errors concurrency options return types and interface necessity. [Governance] governance.md Maintainers Review stable API review board process branch protection CODEOWNERS required checks release approval and maintainer succession policy. [API addition example exceptions] api-addition-exceptions.tsv Maintainers Record exact symbol exceptions when a new stable exported identifier has a doc comment and release note but a compile-checked example would mislead. [Deprecation policy] deprecations.md Maintainers and release reviewers Track deprecation format replacements removal horizon migration snippets and release-note requirements. [Interface ownership] interface-ownership.md Maintainers Document whether exported interfaces are user-implemented adapter-owned test-only or compatibility-sensitive. [Options struct audit] options-structs.md Maintainers Review defaults validation behavior zero-value behavior and example evidence for stable exported options structs. [Global state audit] global-state-audit.md Maintainers Review package-level globals in stable packages and the limited mutable-state exceptions. [Context and cancellation] context-cancellation.md Maintainers and adopters Apply context propagation and bounded cleanup rules across HTTP auth idempotency scheduler and client APIs. [Error taxonomy] errors.md Maintainers and API consumers Match sentinel typed field wrapped configuration and Problem Details errors safely. [Concurrency safety] concurrency.md API consumers and maintainers Decide which values are immutable request-scoped synchronized or implementation-owned. [Resource lifecycle] resource-lifecycle.md Maintainers and adopters Track ownership for close shutdown timers goroutines stores adapters and generated service resources. [Ports surface] ports-surface.md Maintainers and advanced API consumers Identify compatibility-sensitive port history and preferred replacements. [Ports export exceptions] ports-export-exceptions.tsv Maintainers Review the accepted ADR required for any new root `ports` export. [V3 compatibility record] v3-compatibility-roadmap.md Maintainers Track completed v3 cleanup decisions and remaining compatibility-sensitive guardrails. [V4 scope cleanup plan] v4-plan.md Maintainers and advanced adopters Plan which root surfaces to keep stable demote split or remove only in a future major release. [Ports v4 migration ledger] ports-v4-migration-ledger.tsv Maintainers and advanced adopters Record every current root-port export consumer packages implementation evidence v3 deprecation status and v4 disposition. [Package doc standard] package-doc-standard.md Maintainers Apply the minimum package-doc template and see the placeholder inventory remediated in this pass. [Package classification guide] package-classification.md Maintainers and adopters Read the rendered status glossary before using the TSV source of truth. [Core readiness matrix] core-readiness.md API consumers and release reviewers Review stable package readiness by docs examples tests fuzz benchmark compatibility security review and production caveat. [Module-boundary ADR] adr/0001-module-boundaries.md Maintainers Record the v3 decision to keep root and contrib modules while deferring deeper splits to v4 planning. `docs/package-classification.tsv` Maintainers and automation Machine-readable API and test-status classification for every package. `docs/package-owners.tsv` Maintainers and automation Machine-readable maintainer owner test owner stability tier and release-blocker status for every package. `docs/supported-adapter-contracts.tsv` Maintainers and automation Machine-readable behavior contracts and evidence paths for supported contrib adapters. `docs/supported-adapter-test-realism.tsv` Maintainers and automation Machine-readable default and scheduled/manual test-realism evidence for each supported contrib adapter. Release and evidence Document Audience Purpose [Audit and scratch archive policy] audits.md Maintainers and release reviewers Keep local `.audits` and `.trash` scratch material out of tracked release evidence. [OpenSSF Best Practices gap review] openssf-best-practices.md Maintainers and release reviewers Track Best Practices badge readiness unclaimed status and remaining gaps before publishing a badge. [V4 release-identity incident] release-incident-v4-release-identity.md V4 consumers and release reviewers Follow the current safe action while the v4 tag history and checksum mismatch are reconciled. [Release runbook] release-runbook.md Release operators Command source of truth for local checks release evidence artifact verification and baseline policy. [Release provenance] provenance.md Release consumers and reviewers Verify GitHub artifact provenance understand the attested asset scope and apply the documented trust limits. [Reproducible build status] reproducible-builds.md Release consumers and maintainers Distinguish unsupported binary reproducibility from the checksums signatures and provenance verified for release assets. [Release review checklist] release-review.md Release reviewers Short path through summary fields manifests dirty-tree decisions artifacts and release notes. [Governance] governance.md Maintainers Branch protection CODEOWNERS tag protection required checks and release approval expectations. [Changelog] ../CHANGELOG.md Release consumers Concise user-facing history for published releases. [Release notes] release-notes.md Release consumers and maintainers Dated behavior changes upgrade notes and package-tied contrib drift acknowledgements. [Release manifests] release-manifests.md Release reviewers and maintainers Human guide for package classification contrib drift contrib dispositions and vulnerability dispositions. `docs/contrib-api-drift-packages.txt` Maintainers and automation Selected contrib packages reviewed by drift checks supported-adapter incompatible drift is gate-enforced. `docs/supported-adapter-contracts.tsv` Maintainers and automation Required supported-adapter behavior contracts with direct-test and release-drift evidence. `docs/supported-adapter-test-realism.tsv` Maintainers and automation Required supported-adapter realism rows that distinguish direct-unit fake DB miniredis hermetic fixture and scheduled/manual real-service evidence. `docs/contrib-api-drift-dispositions.tsv` Release reviewers and automation Owner status review date expiry and acknowledgement for current contrib drift. `docs/vulnerability-dispositions.tsv` Release reviewers and automation Owner review expiry and upgrade trigger rows for imported-only vulnerability IDs when present. `release-check-summary.json` Release reviewers Generated local release evidence summary only clean publication evidence is publishable. Documentation quality workflow Use the narrowest check that matches the change: Change type Preferred command Notes Documentation-only edits `GOTOOLCHAIN local make docs-check` Runs documentation contracts generated docs-site drift checks getting-started build extraction API/docs policy checks and release evidence parser contracts. Architecture or dependency-boundary edits `GOTOOLCHAIN local make dependency-boundary-check` Runs the stable-core import boundary check before the broader docs gate. V3 cleanup readiness `GOTOOLCHAIN local make v3-readiness-check` Runs focused compatibility-sensitive surface guardrails for major-version cleanup planning and release-note requirements. Docs plus ordinary code changes `GOTOOLCHAIN local make fast-check` Runs `docs-check` and unit tests without rewriting files. Reference service coverage `GOTOOLCHAIN local make reference-service-coverage` Records non-Docker generated-service coverage under `.ci-result/coverage/` without folding app-owned code into toolkit coverage thresholds. Reference service load `GOTOOLCHAIN local make reference-service-load` Records non-Docker generated-service latency throughput memory allocation and expected auth-failure evidence under `.ci-result/reference-service-load/`. Generated full-profile soak `GOTOOLCHAIN local make generated-soak-check` Records nightly-style generated `saas-api-full` race/goroutine soak evidence and repeated Docker integration-cycle logs under `.ci-result/generated-soak/`. Generated full-profile failure `GOTOOLCHAIN local make generated-failure-check` Records generated `saas-api-full` Redis-down Postgres-down expired API-key bad JWKS and slow downstream timeout evidence under `.ci-result/generated-failure/`. Timeout determinism `GOTOOLCHAIN local make timeout-determinism-check` Repeats the hard-timeout late-write test under normal and race runs then runs the root timeout/idempotency/rate-limit/scheduler race subset. Reviewer or audit pass `GOTOOLCHAIN local make audit-check` Non-mutating reviewer gate with lint vuln gosec build smoke GitHub Actions pin audit docs contracts tests race and fuzz smoke. Generated files examples scripts package docs or repo-wide contracts `GOTOOLCHAIN local make finalize` when practical Installs tools and may rewrite Go formatting and module files through `fmt` and `tidy` avoid it in shared dirty worktrees unless that mutation is intended. Do not treat `make finalize` as release evidence. Release publication evidence is owned by [release-runbook.md] release-runbook.md . If the local Go version is not Go 1.25.x `GOTOOLCHAIN local` failures are expected. Install the supported toolchain or use the repository CI image before running root and contrib gates. Canonical high-centrality paths These literal paths are kept here so docs index coverage checks can detect when important public docs disappear from navigation: `README.md` `ROADMAP.md` `docs/library-first.md` `docs/minimal-core.md` `docs/core-package-guide.md` `docs/scaffold-first.md` `docs/cli-scaffold-identity.md` `docs/contrib-adapters.md` `docs/getting-started.md` `docs/cookbook.md` `docs/architecture.md` `docs/migration/v3.md` `docs/troubleshooting.md` `docs/security.md` `docs/threat-model.md` `docs/security-review.md` `docs/auth.md` `docs/idempotency.md` `docs/operations.md` `docs/openapi-workflow.md` `docs/configuration.md` `docs/observability.md` `docs/scaffold-support.md` `docs/adapter-maturity.md` `docs/safe-defaults.md` `docs/middleware-safety.md` `docs/input-size-threat-review.md` `docs/testing.md` `docs/site/index.html` `docs/downstream-compatibility.md` `SECURITY.md` `CODE_OF_CONDUCT.md` `docs/metrics.md` `docs/support-policy.md` `docs/dependency-policy.md` `docs/license-policy.md` `docs/dependency-footprint.md` `docs/adr/0001-module-boundaries.md` `VERSIONING.md` `docs/api-inventory.md` `docs/api-review-checklist.md` `docs/api-reference.md` `docs/core-readiness.md` `docs/deprecations.md` `docs/interface-ownership.md` `docs/context-cancellation.md` `docs/errors.md` `docs/concurrency.md` `docs/resource-lifecycle.md` `docs/release-runbook.md` `docs/release-review.md` `docs/audits.md` `docs/openssf-best-practices.md` `docs/release-notes.md` `docs/release-manifests.md` `docs/ports-surface.md` `docs/v3-compatibility-roadmap.md` `docs/production-readiness.md` `docs/governance.md` `docs/performance.md` `docs/dependency-boundary.md` `docs/dependency-risk.md` `docs/package-doc-standard.md` `docs/full-service-scaffold.md` `docs/package-classification.tsv` `docs/supported-adapter-contracts.tsv` `docs/supported-adapter-test-realism.tsv` `docs/contrib-api-drift-packages.txt` `docs/contrib-api-drift-dispositions.tsv` `docs/vulnerability-dispositions.tsv` `contrib/examples/README.md` `examples/reference-saas-api/README.md` `examples/reference-saas-api/deploy/helm/README.md` `examples/reference-saas-api/deploy/kubernetes/README.md` `examples/reference-saas-api/deploy/terraform/aws/README.md` `examples/reference-saas-api/observability/runbooks/observability.md` `examples/reference-saas-api/docs/providers/provider-runbook.md` `PANIC_POLICY.md` and `release-check-summary.json`." }, { "title": "api-toolkit", "category": "overview", "url": "https://github.com/aatuh/api-toolkit/blob/master/README.md", - "text": "README.md api-toolkit [ [OpenSSF Scorecard] https://api.scorecard.dev/projects/github.com/aatuh/api-toolkit/badge ] https://scorecard.dev/viewer/ uri github.com 2Faatuh 2Fapi-toolkit `api-toolkit` provides small composable Go HTTP API building blocks for teams that already own their service architecture api-toolkit [ [OpenSSF Scorecard] https://api.scorecard.dev/projects/github.com/aatuh/api-toolkit/badge ] https://scorecard.dev/viewer/ uri github.com 2Faatuh 2Fapi-toolkit `api-toolkit` provides small composable Go HTTP API building blocks for teams that already own their service architecture and want production guardrails without adopting a full framework. Target user: Go developers building conventional JSON/HTTP APIs with `net/http` chi or app-owned routers. Differentiator: production guardrails for conventional Go JSON APIs not a router or full framework. Non-goals: not a router persistence framework billing framework universal auth platform RPC framework streaming middleware suite or replacement for app-owned business ports. Core-only install: Stable core package list: `VERSIONING.md` is the source of truth and `scripts/apicheck.sh` must cover the same package list. Root and contrib target Go 1.25.x. Minimal existing-service example [source] examples/snippets/minimal-existing-service/main.go : Start Here - Add the core library to an existing service: [docs/library-first.md] docs/library-first.md - Use the smallest root-only path: [docs/minimal-core.md] docs/minimal-core.md - Choose a core package: [docs/core-package-guide.md] docs/core-package-guide.md - Browse stable API references: [docs/api-reference.md] docs/api-reference.md - Generate a new app-owned service scaffold: [docs/scaffold-first.md] docs/scaffold-first.md - Wire supported adapters: [docs/contrib-adapters.md] docs/contrib-adapters.md - Review CLI/scaffold identity: [docs/cli-scaffold-identity.md] docs/cli-scaffold-identity.md - Review the stable-core charter: [docs/stable-core.md] docs/stable-core.md - Review the public roadmap and non-goals: [ROADMAP.md] ROADMAP.md - Browse concise release history: [CHANGELOG.md] CHANGELOG.md - Compare alternatives and non-goals: [docs/alternatives.md] docs/alternatives.md - Find task recipes: [docs/cookbook.md] docs/cookbook.md - Review benchmark baselines: [docs/performance.md] docs/performance.md - Review contributor rules: [CONTRIBUTING.md] CONTRIBUTING.md - Ask a focused usage question: [.github/ISSUE_TEMPLATE/question.md] .github/ISSUE_TEMPLATE/question.md - Share adopter feedback: [.github/ISSUE_TEMPLATE/adopter_review.md] .github/ISSUE_TEMPLATE/adopter_review.md - Use the PR checklist: [.github/pull_request_template.md] .github/pull_request_template.md - Use the documentation map: [docs/README.md] docs/README.md - Review safe defaults: [docs/safe-defaults.md] docs/safe-defaults.md - Review middleware placement: [docs/middleware-safety.md] docs/middleware-safety.md - Review core readiness: [docs/core-readiness.md] docs/core-readiness.md - Upgrade within v3: [docs/migration/v3.md] docs/migration/v3.md - Troubleshoot adoption issues: [docs/troubleshooting.md] docs/troubleshooting.md Funding And Sponsorship api-toolkit does not currently accept or solicit sponsorships donations grants or paid support through this repository. Users and contributors have no financial obligation to use evaluate report issues for or contribute to the project. Contributions issue triage API review and security handling remain governed by the published technical policies. A payment offer of funding or request for priority would not create paid support release priority maintainer access or a security-response commitment. Do not send money or payment details to maintainers based on repository activity or public comments. If the project later accepts funding maintainers must add a reviewed public funding link and state the recipient scope conflicts-of-interest handling and whether funding changes any support expectations before soliciting or accepting funds. Modules Module Import path Use for Core `github.com/aatuh/api-toolkit/v4` Stable HTTP/API primitives middleware helpers route contracts and compatibility-gated root packages. Contrib `github.com/aatuh/api-toolkit/contrib/v4` Third-party adapters integrations runnable examples and generator tooling outside the stable core API promise. Install contrib only when you need maintained adapters generated scaffolds or contrib examples: Supported development and CI toolchain policy: root and contrib target Go 1.25.x. Local and release gates should run with `GOTOOLCHAIN local` so drift between module `go` directives GitHub Actions setup and release evidence is visible before publication. Package Map Recommended small-core starting points are mapped in [docs/core-package-guide.md] docs/core-package-guide.md . The minimum root-only adoption path is documented in [docs/minimal-core.md] docs/minimal-core.md . Common first packages: - HTTP responses and errors: `httpx` `fielderrors`. - Request parsing and bounds: `binding` `queryparams` `upload` `middleware/maxbody` `middleware/querylimits` and `middleware/json`. - Runtime guardrails: `middleware/timeout` `middleware/secure` `middleware/deprecation` `middleware/trace` and selected auth middleware. - API contracts: `routecontracts` `routepolicy` `specs` and `endpoints/health` `endpoints/version` `endpoints/docs`. - App-owned integration boundaries: `idempotent` `webhooks` and small package-local interfaces where the consuming package owns the shape. Stable but not the default adoption story: - `ports` remains a v3 compatibility commitment but new app design should prefer package-local or app-owned interfaces unless a shared root abstraction is proven. - `compat/billing` migration-shaped packages scaffolding support test helpers and client helpers are stable where listed in `VERSIONING.md` but they are not the recommended minimal path for a new library user. Contrib packages provide routers logging validation Postgres Redis Stripe Resend OpenTelemetry CORS OpenAPI validation request logging config bootstrap composition generated service tooling and runnable examples. Contrib supported-adapter incompatible drift is gate-enforced and does not make contrib stable. For API owner and test-status metadata use `docs/package-classification.tsv` `docs/package-owners.tsv` the rendered guide in [docs/package-classification.md] docs/package-classification.md and the human guide in [docs/package-doc-standard.md] docs/package-doc-standard.md . Package maturity tier badges use the TSV-backed labels `[stable]` `[compatibility-only]` `[supported-adapter]` `[experimental]` `[generated]` and `[tooling]` do not treat a package as a different tier unless the TSV row changes in the same review. Trust Proof Current repository trust signals: - CI runs `make coverage-check` `make test-race` `make vuln` `make docs-check` `make v3-readiness-check` `make release-api-check` and `make fuzz`. - Stable SemVer policy is enforced by `VERSIONING.md` `scripts/apicheck.sh` `docs/api-inventory.md` and release API compatibility checks. - Package status is machine-owned by `docs/package-classification.tsv` and rendered in `docs/package-classification.md`. - Release review covers dependency footprint contrib drift vulnerability dispositions SBOM assets signatures and provenance/attestation policy through `docs/release-runbook.md` `docs/release-review.md` and `docs/provenance.md` and `release-check-summary.json`. - OpenSSF Scorecard results are published by `.github/workflows/scorecard.yml` as a public badge/API report uploaded SARIF artifact `scorecard-sarif` and code-scanning SARIF. Target ` 8` a lower public score requires remediation or an explicit release-review disposition before publishing. - OpenSSF Best Practices Badge status is documented in [docs/openssf-best-practices.md] docs/openssf-best-practices.md : not claimed until a registered bestpractices.dev project ID exists and the remaining gaps are resolved or explicitly accepted. - Code scanning merge protection is documented in [docs/governance.md] docs/governance.md : the protected branch ruleset must require CodeQL code scanning results for pull requests with explicit alert thresholds. - Governance docs publish required checks CODEOWNERS expectations tag policy and branch-protection evidence boundaries. - Maintenance status: this is currently a single-maintainer project. Security reports use the acknowledgement and remediation targets in [SECURITY.md] SECURITY.md routine issues feature requests adopter reviews and non-security pull requests are handled best effort. Use [.github/ISSUE_TEMPLATE/adopter_review.md] .github/ISSUE_TEMPLATE/adopter_review.md to report API friction missing docs and migration pain without posting secrets or vulnerability details publicly. Supported versions are the latest release on the default branch with Go/platform support documented in [docs/support-policy.md] docs/support-policy.md . There is no automatic successor [governance documents the unavailability and verified handover policy] docs/governance.md maintainer-succession-and-unavailability . Production readiness api-toolkit v3 is production-credible for conventional Go JSON/HTTP APIs and generated SaaS/API services. It is not a universal backend platform for every transport streaming workload provider workflow or organization-specific operating model. Use [docs/production-readiness.md] docs/production-readiness.md as the readiness matrix and adapter maturity review before standardizing on a package or generated profile. Generated code is app-owned api-toolkit standardizes infrastructure defaults without becoming your product or provider framework. Use [docs/core-readiness.md] docs/core-readiness.md as the package-specific production checklist and [docs/middleware-safety.md] docs/middleware-safety.md before applying request or response middleware globally. Area Readiness Notes Stable core packages Stable SemVer surface Covered by `VERSIONING.md` `scripts/apicheck.sh` package classification and release evidence. Supported contrib adapters Supported adapter tier Direct tests docs drift coverage and behavior contracts are required supported-adapter incompatible drift is gate-enforced and does not make contrib stable. Experimental contrib packages Maintained but unstable Use only with app-owned compatibility expectations until promoted with evidence. `saas-api` scaffold Lean service starter Keeps production-safe HTTP defaults without forcing persistence or membership models. `saas-api-full` scaffold Production reference scaffold Includes Postgres Redis tenancy API keys async/outbox audit webhooks OpenAPI 3.1 clients and deployment starters. Generated code is app-owned. Streaming SSE WebSockets and large downloads Explicit caveat Use route-level opt-outs do not apply hard-timeout response buffering response validation or idempotency response capture globally. Streaming routes server-sent events websocket upgrades and large downloads should be marked with `x-api-toolkit-streaming` and wired with `securityprofile.StreamingRouteOverride` or equivalent route-specific middleware. This preserves optional `http.ResponseWriter` interfaces and avoids buffering or validating responses that are not finite JSON documents. Health endpoint contract The health package exposes separate liveness readiness and detailed health behaviors: - Liveness and readiness are expected to reflect configured checker state and should not silently report healthy when no probe checks are configured. - Detailed health output is an operator-focused surface because it can include dependency-level status and check details. - `ports.HealthCheckConfig.EnableDetailed` controls whether HTTP packages should expose detailed health responses. - Mount detailed health pprof and metrics behind admin/internal access control or upstream network policy prefer `Handler.RegisterPublicRoutesTo` `Handler.RegisterAdminDetailedHealthRoute` `pprof.RegisterAdminRoutes` and `bootstrap.MountSystemEndpointsToWithAdmin` for new mounts because operator-only routes require an explicit wrapper. - HTTP dependency check URLs are application configuration. Do not derive them from request parameters or tenant-controlled input. - Missing checker registrations or invalid probe wiring should fail closed and surface as unhealthy state rather than synthetic success. - When `EnableCaching` is true checker results may be reused across health endpoints until `CacheDuration` expires. Safe system endpoint mounting should keep public probes separate from operator-only dependency detail metrics and pprof. Web mobile and desktop clients should use public probes only they should never call operator-only endpoints directly. If you mount pprof outside the bootstrap helper use `pprof.RegisterAdminRoutes`. If you split routers manually use `healthHandler.RegisterPublicRoutesTo publicRouter ` for public probes and `healthHandler.RegisterAdminDetailedHealthRoute adminRouter requireAdmin ` for operator detail. The bootstrap snippet below is compile checked in [contrib/bootstrap/example_test.go] contrib/bootstrap/example_test.go . Security and operations - Security posture and dangerous-bypass configuration: [docs/security.md] docs/security.md - Security threat model: [docs/threat-model.md] docs/threat-model.md - Package security review: [docs/security-review.md] docs/security-review.md - Auth production guide: [docs/auth.md] docs/auth.md - Idempotency production guide: [docs/idempotency.md] docs/idempotency.md - Health and admin operations: [docs/operations.md] docs/operations.md - OpenAPI contract workflow: [docs/openapi-workflow.md] docs/openapi-workflow.md - Runtime configuration: [docs/configuration.md] docs/configuration.md - Observability: [docs/observability.md] docs/observability.md - Scaffold support: [docs/scaffold-support.md] docs/scaffold-support.md - Adapter maturity: [docs/adapter-maturity.md] docs/adapter-maturity.md - Safe defaults audit: [docs/safe-defaults.md] docs/safe-defaults.md - Middleware safety matrix: [docs/middleware-safety.md] docs/middleware-safety.md - Vulnerability reporting policy: [SECURITY.md] SECURITY.md - Panic policy: [PANIC_POLICY.md] PANIC_POLICY.md - Metrics naming and labels: [docs/metrics.md] docs/metrics.md - Go and platform support policy: [docs/support-policy.md] docs/support-policy.md - Dependency boundary: [docs/dependency-boundary.md] docs/dependency-boundary.md - Dependency policy: [docs/dependency-policy.md] docs/dependency-policy.md - Dependency license policy: [docs/license-policy.md] docs/license-policy.md - Dependency risk disposition: [docs/dependency-risk.md] docs/dependency-risk.md - Dependency footprint report: [docs/dependency-footprint.md] docs/dependency-footprint.md - Test coverage evidence: [docs/test-coverage.md] docs/test-coverage.md - Vulnerability disposition manifest: `docs/vulnerability-dispositions.tsv` - Community conduct: [CODE_OF_CONDUCT.md] CODE_OF_CONDUCT.md Stability Stable core package list: `VERSIONING.md` is the source of truth and `scripts/apicheck.sh` must cover the same package list. - Public API inventory: [docs/api-inventory.md] docs/api-inventory.md - API reference index: [docs/api-reference.md] docs/api-reference.md - API review checklist: [docs/api-review-checklist.md] docs/api-review-checklist.md - Deprecation policy: [docs/deprecations.md] docs/deprecations.md - Interface ownership: [docs/interface-ownership.md] docs/interface-ownership.md - Context and cancellation: [docs/context-cancellation.md] docs/context-cancellation.md - Error taxonomy: [docs/errors.md] docs/errors.md - Concurrency safety: [docs/concurrency.md] docs/concurrency.md - Resource lifecycle: [docs/resource-lifecycle.md] docs/resource-lifecycle.md - Stable core readiness matrix: [docs/core-readiness.md] docs/core-readiness.md - V3 migration guide: [docs/migration/v3.md] docs/migration/v3.md - Troubleshooting guide: [docs/troubleshooting.md] docs/troubleshooting.md - Latest published release line: `v4.0.0` and `contrib/v4.0.0`. - `master` may contain unreleased changes after the latest tag release consumers should use tags and release notes instead of assuming `master` is published evidence. - Versioning and stable API policy: [VERSIONING.md] VERSIONING.md - Compatibility-sensitive ports: [docs/ports-surface.md] docs/ports-surface.md - V3 compatibility record: [docs/v3-compatibility-roadmap.md] docs/v3-compatibility-roadmap.md - Response writer removal record: [docs/response-writer-inventory.md] docs/response-writer-inventory.md - Production readiness matrix: [docs/production-readiness.md] docs/production-readiness.md - Governance and branch protection: [docs/governance.md] docs/governance.md - Public package classification: `docs/package-classification.tsv` Release command details live in [docs/release-runbook.md] docs/release-runbook.md . Keep this landing page as a pointer not a second release runbook. - Release review checklist: [docs/release-review.md] docs/release-review.md - Release notes: [docs/release-notes.md] docs/release-notes.md - Release manifests guide: [docs/release-manifests.md] docs/release-manifests.md - Contrib drift package manifest: `docs/contrib-api-drift-packages.txt` - Contrib drift disposition manifest: `docs/contrib-api-drift-dispositions.tsv` - Current supported v4 API baseline: see `docs/release-runbook.md`. - The v4 major-release evidence compared against `API_BASE_REF v3.1.2` v4 patch and minor releases compare against the latest published v4 tag from the runbook. - Release readiness and publication evidence require an explicit `API_BASE_REF` use the current command examples in `docs/release-runbook.md`. - `ALLOW_DIRTY_RELEASE_EVIDENCE 1` is only for local dirty-tree audit evidence and is not acceptable before publishing. - `make finalize` is not release evidence. - `make release-api-check` `make contrib-api-drift-report` and `make contrib-release-notes-check` are explained in the runbook. Supported-adapter contrib packages are still outside the stable core API promise supported-adapter incompatible drift is gate-enforced and does not make contrib stable. Adapter coverage policy Use `docs/package-classification.tsv` as the source of truth for API and test coverage status. - `wrapper-only` packages may use `wrapper-smoke-tested` only when smoke coverage is sufficient because the wrapper delegates behavior to another maintained package. - Wrapper smoke tests must prove interface satisfaction constructor/defaults disabled or nil behavior and option propagation. - `example-only` packages are build-smoke checked and are not behavior-complete coverage. - Public packages need direct tests unless explicitly classified as wrapper example generated tooling test-support or excluded. - `needs-tests` is a release blocker until replaced with direct tests or a documented exception. Local documentation checks For documentation-only changes prefer: For implementation changes examples package docs generated files scripts or repo-wide contracts use the workflow in [docs/README.md] docs/README.md to choose between `docs-check` `fast-check` `audit-check` and `finalize`." + "text": "README.md api-toolkit [ [OpenSSF Scorecard] https://api.scorecard.dev/projects/github.com/aatuh/api-toolkit/badge ] https://scorecard.dev/viewer/ uri github.com 2Faatuh 2Fapi-toolkit `api-toolkit` provides small composable Go HTTP API building blocks for teams that already own their service architecture api-toolkit [ [OpenSSF Scorecard] https://api.scorecard.dev/projects/github.com/aatuh/api-toolkit/badge ] https://scorecard.dev/viewer/ uri github.com 2Faatuh 2Fapi-toolkit `api-toolkit` provides small composable Go HTTP API building blocks for teams that already own their service architecture and want production guardrails without adopting a full framework. Target user: Go developers building conventional JSON/HTTP APIs with `net/http` chi or app-owned routers. Differentiator: production guardrails for conventional Go JSON APIs not a router or full framework. Non-goals: not a router persistence framework billing framework universal auth platform RPC framework streaming middleware suite or replacement for app-owned business ports. Core-only install: Stable core package list: `VERSIONING.md` is the source of truth and `scripts/apicheck.sh` must cover the same package list. Root and contrib target Go 1.25.x. Minimal existing-service example [source] examples/snippets/minimal-existing-service/main.go : Start Here - Add the core library to an existing service: [docs/library-first.md] docs/library-first.md - Use the smallest root-only path: [docs/minimal-core.md] docs/minimal-core.md - Choose a core package: [docs/core-package-guide.md] docs/core-package-guide.md - Browse stable API references: [docs/api-reference.md] docs/api-reference.md - Generate a new app-owned service scaffold: [docs/scaffold-first.md] docs/scaffold-first.md - Wire supported adapters: [docs/contrib-adapters.md] docs/contrib-adapters.md - Review CLI/scaffold identity: [docs/cli-scaffold-identity.md] docs/cli-scaffold-identity.md - Review the stable-core charter: [docs/stable-core.md] docs/stable-core.md - Review the public roadmap and non-goals: [ROADMAP.md] ROADMAP.md - Browse concise release history: [CHANGELOG.md] CHANGELOG.md - Compare alternatives and non-goals: [docs/alternatives.md] docs/alternatives.md - Find task recipes: [docs/cookbook.md] docs/cookbook.md - Review benchmark baselines: [docs/performance.md] docs/performance.md - Review contributor rules: [CONTRIBUTING.md] CONTRIBUTING.md - Ask a focused usage question: [.github/ISSUE_TEMPLATE/question.md] .github/ISSUE_TEMPLATE/question.md - Share adopter feedback: [.github/ISSUE_TEMPLATE/adopter_review.md] .github/ISSUE_TEMPLATE/adopter_review.md - Use the PR checklist: [.github/pull_request_template.md] .github/pull_request_template.md - Use the documentation map: [docs/README.md] docs/README.md - Review safe defaults: [docs/safe-defaults.md] docs/safe-defaults.md - Review middleware placement: [docs/middleware-safety.md] docs/middleware-safety.md - Review core readiness: [docs/core-readiness.md] docs/core-readiness.md - Upgrade within v3: [docs/migration/v3.md] docs/migration/v3.md - Troubleshoot adoption issues: [docs/troubleshooting.md] docs/troubleshooting.md Funding And Sponsorship api-toolkit does not currently accept or solicit sponsorships donations grants or paid support through this repository. Users and contributors have no financial obligation to use evaluate report issues for or contribute to the project. Contributions issue triage API review and security handling remain governed by the published technical policies. A payment offer of funding or request for priority would not create paid support release priority maintainer access or a security-response commitment. Do not send money or payment details to maintainers based on repository activity or public comments. If the project later accepts funding maintainers must add a reviewed public funding link and state the recipient scope conflicts-of-interest handling and whether funding changes any support expectations before soliciting or accepting funds. Modules Module Import path Use for Core `github.com/aatuh/api-toolkit/v4` Stable HTTP/API primitives middleware helpers route contracts and compatibility-gated root packages. Contrib `github.com/aatuh/api-toolkit/contrib/v4` Third-party adapters integrations runnable examples and generator tooling outside the stable core API promise. Install contrib only when you need maintained adapters generated scaffolds or contrib examples: Supported development and CI toolchain policy: root and contrib target Go 1.25.x. Local and release gates should run with `GOTOOLCHAIN local` so drift between module `go` directives GitHub Actions setup and release evidence is visible before publication. Package Map Recommended small-core starting points are mapped in [docs/core-package-guide.md] docs/core-package-guide.md . The minimum root-only adoption path is documented in [docs/minimal-core.md] docs/minimal-core.md . Common first packages: - HTTP responses and errors: `httpx` `fielderrors`. - Request parsing and bounds: `binding` `queryparams` `upload` `middleware/maxbody` `middleware/querylimits` and `middleware/json`. - Runtime guardrails: `middleware/timeout` `middleware/secure` `middleware/deprecation` `middleware/trace` and selected auth middleware. - API contracts: `routecontracts` `routepolicy` `specs` and `endpoints/health` `endpoints/version` `endpoints/docs`. - App-owned integration boundaries: `idempotent` `webhooks` and small package-local interfaces where the consuming package owns the shape. Stable but not the default adoption story: - `ports` remains a v3 compatibility commitment but new app design should prefer package-local or app-owned interfaces unless a shared root abstraction is proven. - `compat/billing` migration-shaped packages scaffolding support test helpers and client helpers are stable where listed in `VERSIONING.md` but they are not the recommended minimal path for a new library user. Contrib packages provide routers logging validation Postgres Redis Stripe Resend OpenTelemetry CORS OpenAPI validation request logging config bootstrap composition generated service tooling and runnable examples. Contrib supported-adapter incompatible drift is gate-enforced and does not make contrib stable. For API owner and test-status metadata use `docs/package-classification.tsv` `docs/package-owners.tsv` the rendered guide in [docs/package-classification.md] docs/package-classification.md and the human guide in [docs/package-doc-standard.md] docs/package-doc-standard.md . Package maturity tier badges use the TSV-backed labels `[stable]` `[compatibility-only]` `[supported-adapter]` `[experimental]` `[generated]` and `[tooling]` do not treat a package as a different tier unless the TSV row changes in the same review. Trust Proof Current repository trust signals: - CI runs `make coverage-check` `make test-race` `make vuln` `make docs-check` `make v3-readiness-check` `make release-api-check` and `make fuzz`. - Stable SemVer policy is enforced by `VERSIONING.md` `scripts/apicheck.sh` `docs/api-inventory.md` and release API compatibility checks. - Package status is machine-owned by `docs/package-classification.tsv` and rendered in `docs/package-classification.md`. - Release review covers dependency footprint contrib drift vulnerability dispositions SBOM assets signatures and provenance/attestation policy through `docs/release-runbook.md` `docs/release-review.md` and `docs/provenance.md` and `release-check-summary.json`. - OpenSSF Scorecard results are published by `.github/workflows/scorecard.yml` as a public badge/API report uploaded SARIF artifact `scorecard-sarif` and code-scanning SARIF. Target ` 8` a lower public score requires remediation or an explicit release-review disposition before publishing. - OpenSSF Best Practices Badge status is documented in [docs/openssf-best-practices.md] docs/openssf-best-practices.md : not claimed until a registered bestpractices.dev project ID exists and the remaining gaps are resolved or explicitly accepted. - Code scanning merge protection is documented in [docs/governance.md] docs/governance.md : the protected branch ruleset must require CodeQL code scanning results for pull requests with explicit alert thresholds. - Governance docs publish required checks CODEOWNERS expectations tag policy and branch-protection evidence boundaries. - Maintenance status: this is currently a single-maintainer project. Security reports use the acknowledgement and remediation targets in [SECURITY.md] SECURITY.md routine issues feature requests adopter reviews and non-security pull requests are handled best effort. Use [.github/ISSUE_TEMPLATE/adopter_review.md] .github/ISSUE_TEMPLATE/adopter_review.md to report API friction missing docs and migration pain without posting secrets or vulnerability details publicly. Supported versions are the latest release on the default branch with Go/platform support documented in [docs/support-policy.md] docs/support-policy.md . There is no automatic successor [governance documents the unavailability and verified handover policy] docs/governance.md maintainer-succession-and-unavailability . Production readiness api-toolkit v3 is production-credible for conventional Go JSON/HTTP APIs and generated SaaS/API services. It is not a universal backend platform for every transport streaming workload provider workflow or organization-specific operating model. Use [docs/production-readiness.md] docs/production-readiness.md as the readiness matrix and adapter maturity review before standardizing on a package or generated profile. Generated code is app-owned api-toolkit standardizes infrastructure defaults without becoming your product or provider framework. Use [docs/core-readiness.md] docs/core-readiness.md as the package-specific production checklist and [docs/middleware-safety.md] docs/middleware-safety.md before applying request or response middleware globally. Area Readiness Notes Stable core packages Stable SemVer surface Covered by `VERSIONING.md` `scripts/apicheck.sh` package classification and release evidence. Supported contrib adapters Supported adapter tier Direct tests docs drift coverage and behavior contracts are required supported-adapter incompatible drift is gate-enforced and does not make contrib stable. Experimental contrib packages Maintained but unstable Use only with app-owned compatibility expectations until promoted with evidence. `saas-api` scaffold Lean service starter Keeps production-safe HTTP defaults without forcing persistence or membership models. `saas-api-full` scaffold Production reference scaffold Includes Postgres Redis tenancy API keys async/outbox audit webhooks OpenAPI 3.1 clients and deployment starters. Generated code is app-owned. Streaming SSE WebSockets and large downloads Explicit caveat Use route-level opt-outs do not apply hard-timeout response buffering response validation or idempotency response capture globally. Streaming routes server-sent events websocket upgrades and large downloads should be marked with `x-api-toolkit-streaming` and wired with `securityprofile.StreamingRouteOverride` or equivalent route-specific middleware. This preserves optional `http.ResponseWriter` interfaces and avoids buffering or validating responses that are not finite JSON documents. Health endpoint contract The health package exposes separate liveness readiness and detailed health behaviors: - Liveness and readiness are expected to reflect configured checker state and should not silently report healthy when no probe checks are configured. - Detailed health output is an operator-focused surface because it can include dependency-level status and check details. - `ports.HealthCheckConfig.EnableDetailed` controls whether HTTP packages should expose detailed health responses. - Mount detailed health pprof and metrics behind admin/internal access control or upstream network policy prefer `Handler.RegisterPublicRoutesTo` `Handler.RegisterAdminDetailedHealthRoute` `pprof.RegisterAdminRoutes` and `bootstrap.MountSystemEndpointsToWithAdmin` for new mounts because operator-only routes require an explicit wrapper. - HTTP dependency check URLs are application configuration. Do not derive them from request parameters or tenant-controlled input. - Missing checker registrations or invalid probe wiring should fail closed and surface as unhealthy state rather than synthetic success. - When `EnableCaching` is true checker results may be reused across health endpoints until `CacheDuration` expires. Safe system endpoint mounting should keep public probes separate from operator-only dependency detail metrics and pprof. Web mobile and desktop clients should use public probes only they should never call operator-only endpoints directly. If you mount pprof outside the bootstrap helper use `pprof.RegisterAdminRoutes`. If you split routers manually use `healthHandler.RegisterPublicRoutesTo publicRouter ` for public probes and `healthHandler.RegisterAdminDetailedHealthRoute adminRouter requireAdmin ` for operator detail. The bootstrap snippet below is compile checked in [contrib/bootstrap/example_test.go] contrib/bootstrap/example_test.go . Security and operations - Security posture and dangerous-bypass configuration: [docs/security.md] docs/security.md - Security threat model: [docs/threat-model.md] docs/threat-model.md - Package security review: [docs/security-review.md] docs/security-review.md - Auth production guide: [docs/auth.md] docs/auth.md - Idempotency production guide: [docs/idempotency.md] docs/idempotency.md - Health and admin operations: [docs/operations.md] docs/operations.md - OpenAPI contract workflow: [docs/openapi-workflow.md] docs/openapi-workflow.md - Runtime configuration: [docs/configuration.md] docs/configuration.md - Observability: [docs/observability.md] docs/observability.md - Scaffold support: [docs/scaffold-support.md] docs/scaffold-support.md - Adapter maturity: [docs/adapter-maturity.md] docs/adapter-maturity.md - Safe defaults audit: [docs/safe-defaults.md] docs/safe-defaults.md - Middleware safety matrix: [docs/middleware-safety.md] docs/middleware-safety.md - Vulnerability reporting policy: [SECURITY.md] SECURITY.md - Panic policy: [PANIC_POLICY.md] PANIC_POLICY.md - Metrics naming and labels: [docs/metrics.md] docs/metrics.md - Go and platform support policy: [docs/support-policy.md] docs/support-policy.md - Dependency boundary: [docs/dependency-boundary.md] docs/dependency-boundary.md - Dependency policy: [docs/dependency-policy.md] docs/dependency-policy.md - Dependency license policy: [docs/license-policy.md] docs/license-policy.md - Dependency risk disposition: [docs/dependency-risk.md] docs/dependency-risk.md - Dependency footprint report: [docs/dependency-footprint.md] docs/dependency-footprint.md - Test coverage evidence: [docs/test-coverage.md] docs/test-coverage.md - Vulnerability disposition manifest: `docs/vulnerability-dispositions.tsv` - Community conduct: [CODE_OF_CONDUCT.md] CODE_OF_CONDUCT.md Stability Stable core package list: `VERSIONING.md` is the source of truth and `scripts/apicheck.sh` must cover the same package list. - Public API inventory: [docs/api-inventory.md] docs/api-inventory.md - API reference index: [docs/api-reference.md] docs/api-reference.md - API review checklist: [docs/api-review-checklist.md] docs/api-review-checklist.md - Deprecation policy: [docs/deprecations.md] docs/deprecations.md - Interface ownership: [docs/interface-ownership.md] docs/interface-ownership.md - Context and cancellation: [docs/context-cancellation.md] docs/context-cancellation.md - Error taxonomy: [docs/errors.md] docs/errors.md - Concurrency safety: [docs/concurrency.md] docs/concurrency.md - Resource lifecycle: [docs/resource-lifecycle.md] docs/resource-lifecycle.md - Stable core readiness matrix: [docs/core-readiness.md] docs/core-readiness.md - V3 migration guide: [docs/migration/v3.md] docs/migration/v3.md - Troubleshooting guide: [docs/troubleshooting.md] docs/troubleshooting.md - Published v4 tags: `v4.0.0` `contrib/v4.0.0` `v4.0.1` and `contrib/v4.0.1`. Before a new deployment or release follow the [v4 release-identity incident] docs/release-incident-v4-release-identity.md `v4.0.1` and `contrib/v4.0.1` are not approved release baselines. - `master` may contain unreleased changes after the latest tag release consumers should use tags and release notes instead of assuming `master` is published evidence. - Versioning and stable API policy: [VERSIONING.md] VERSIONING.md - Compatibility-sensitive ports: [docs/ports-surface.md] docs/ports-surface.md - V3 compatibility record: [docs/v3-compatibility-roadmap.md] docs/v3-compatibility-roadmap.md - Response writer removal record: [docs/response-writer-inventory.md] docs/response-writer-inventory.md - Production readiness matrix: [docs/production-readiness.md] docs/production-readiness.md - Governance and branch protection: [docs/governance.md] docs/governance.md - Public package classification: `docs/package-classification.tsv` Release command details live in [docs/release-runbook.md] docs/release-runbook.md . Keep this landing page as a pointer not a second release runbook. - Release review checklist: [docs/release-review.md] docs/release-review.md - Release notes: [docs/release-notes.md] docs/release-notes.md - Release manifests guide: [docs/release-manifests.md] docs/release-manifests.md - Contrib drift package manifest: `docs/contrib-api-drift-packages.txt` - Contrib drift disposition manifest: `docs/contrib-api-drift-dispositions.tsv` - Current supported v4 API baseline: see `docs/release-runbook.md`. - The v4 major-release evidence compared against `API_BASE_REF v3.1.2` v4 patch and minor releases compare against the latest published v4 tag from the runbook. - Release readiness and publication evidence require an explicit `API_BASE_REF` use the current command examples in `docs/release-runbook.md`. - `ALLOW_DIRTY_RELEASE_EVIDENCE 1` is only for local dirty-tree audit evidence and is not acceptable before publishing. - `make finalize` is not release evidence. - `make release-api-check` `make contrib-api-drift-report` and `make contrib-release-notes-check` are explained in the runbook. Supported-adapter contrib packages are still outside the stable core API promise supported-adapter incompatible drift is gate-enforced and does not make contrib stable. Adapter coverage policy Use `docs/package-classification.tsv` as the source of truth for API and test coverage status. - `wrapper-only` packages may use `wrapper-smoke-tested` only when smoke coverage is sufficient because the wrapper delegates behavior to another maintained package. - Wrapper smoke tests must prove interface satisfaction constructor/defaults disabled or nil behavior and option propagation. - `example-only` packages are build-smoke checked and are not behavior-complete coverage. - Public packages need direct tests unless explicitly classified as wrapper example generated tooling test-support or excluded. - `needs-tests` is a release blocker until replaced with direct tests or a documented exception. Local documentation checks For documentation-only changes prefer: For implementation changes examples package docs generated files scripts or repo-wide contracts use the workflow in [docs/README.md] docs/README.md to choose between `docs-check` `fast-check` `audit-check` and `finalize`." }, { "title": "Core Readiness Matrix", diff --git a/docscheck/contract_test.go b/docscheck/contract_test.go index 45cb14e4..259944ed 100644 --- a/docscheck/contract_test.go +++ b/docscheck/contract_test.go @@ -55,6 +55,15 @@ func TestPublicMarkdownUsesV2ModulePaths(t *testing.T) { } } +func TestPublicMarkdownModulePathClassifierKeepsRepositoryURLs(t *testing.T) { + if forbiddenModuleToken("github.com/aatuh/api-toolkit/releases/tag/v4.0.0") { + t.Fatal("official repository URLs must not be classified as stale Go module paths") + } + if !forbiddenModuleToken("github.com/aatuh/api-toolkit/v2/httpx") { + t.Fatal("a stale Go module import must remain rejected") + } +} + func TestGettingStartedGuideUsesGeneratedServiceScaffold(t *testing.T) { repoRoot := mustRepoRoot(t) docPath := filepath.Join(repoRoot, "docs", "getting-started.md") @@ -5442,9 +5451,9 @@ func TestReleaseDocsDocumentExplicitAPICheckBaseRef(t *testing.T) { } } for _, required := range []string{ - "Supported v4 release baseline: `v4.0.0`", - "API_BASE_REF=v4.0.0 GOTOOLCHAIN=local make release-check", - "API_BASE_REF=v4.0.0 GOTOOLCHAIN=local make release-evidence", + "V4 release publication is paused while the", + "Do not use `v4.0.0` or `v4.0.1` as `API_BASE_REF`", + "`VERIFIED_V4_BASE_REF`", "API_BASE_REF=v3.1.2", "schema v2", "local release evidence", @@ -9471,6 +9480,9 @@ func forbiddenModuleToken(token string) bool { if token == rootModulePath+"/badge" { return false } + if strings.HasPrefix(token, rootModulePath+"/releases/") { + return false + } if strings.HasPrefix(token, rootModulePath+"-contrib") { return true } diff --git a/examples/reference-saas-api/go.mod b/examples/reference-saas-api/go.mod index cda329ff..7921b196 100644 --- a/examples/reference-saas-api/go.mod +++ b/examples/reference-saas-api/go.mod @@ -5,7 +5,7 @@ go 1.25.0 require ( github.com/aatuh/api-toolkit/contrib/v4 v4.0.0 github.com/aatuh/api-toolkit/v4 v4.0.0 - github.com/getkin/kin-openapi v0.133.0 + github.com/getkin/kin-openapi v0.144.0 github.com/jackc/pgx/v5 v5.9.2 github.com/redis/go-redis/v9 v9.19.0 ) @@ -18,36 +18,31 @@ require ( github.com/go-chi/cors v1.2.2 // indirect github.com/go-logr/logr v1.4.3 // indirect github.com/go-logr/stdr v1.2.2 // indirect - github.com/go-openapi/jsonpointer v0.21.0 // indirect - github.com/go-openapi/swag v0.23.0 // indirect + github.com/go-openapi/jsonpointer v0.22.5 // indirect + github.com/go-openapi/swag/jsonname v0.25.5 // indirect github.com/jackc/pgpassfile v1.0.0 // indirect github.com/jackc/pgservicefile v0.0.0-20240606120523-5a60cdf6a761 // indirect github.com/jackc/puddle/v2 v2.2.2 // indirect - github.com/josharian/intern v1.0.0 // indirect - github.com/mailru/easyjson v0.7.7 // indirect - github.com/mohae/deepcopy v0.0.0-20170929034955-c48cc78d4826 // indirect github.com/munnerz/goautoneg v0.0.0-20191010083416-a7dc8b61c822 // indirect - github.com/oasdiff/yaml v0.0.0-20250309154309-f31be36b4037 // indirect - github.com/oasdiff/yaml3 v0.0.0-20250309153720-d2182401db90 // indirect - github.com/perimeterx/marshmallow v1.1.5 // indirect + github.com/oasdiff/yaml v0.1.1 // indirect + github.com/oasdiff/yaml3 v0.0.14 // indirect github.com/prometheus/client_golang v1.23.2 // indirect github.com/prometheus/client_model v0.6.2 // indirect github.com/prometheus/common v0.67.3 // indirect github.com/prometheus/procfs v0.19.2 // indirect - github.com/woodsbury/decimal128 v1.3.0 // indirect + github.com/santhosh-tekuri/jsonschema/v6 v6.0.2 // indirect go.opentelemetry.io/auto/sdk v1.2.1 // indirect - go.opentelemetry.io/otel v1.43.0 // indirect - go.opentelemetry.io/otel/metric v1.43.0 // indirect - go.opentelemetry.io/otel/trace v1.43.0 // indirect + go.opentelemetry.io/otel v1.44.0 // indirect + go.opentelemetry.io/otel/metric v1.44.0 // indirect + go.opentelemetry.io/otel/trace v1.44.0 // indirect go.uber.org/atomic v1.11.0 // indirect go.uber.org/multierr v1.11.0 // indirect - go.uber.org/zap v1.27.1 // indirect + go.uber.org/zap v1.28.0 // indirect go.yaml.in/yaml/v2 v2.4.3 // indirect golang.org/x/sync v0.20.0 // indirect golang.org/x/sys v0.45.0 // indirect golang.org/x/text v0.37.0 // indirect google.golang.org/protobuf v1.36.11 // indirect - gopkg.in/yaml.v3 v3.0.1 // indirect ) replace github.com/aatuh/api-toolkit/v4 => ../.. diff --git a/examples/reference-saas-api/go.sum b/examples/reference-saas-api/go.sum index 61092b61..302d983f 100644 --- a/examples/reference-saas-api/go.sum +++ b/examples/reference-saas-api/go.sum @@ -1,7 +1,7 @@ github.com/aatuh/envvar/v2 v2.1.5 h1:twOIF0rybu21KI3NrPxz/IhVEC/3xcQz3NeHEt4G7+o= github.com/aatuh/envvar/v2 v2.1.5/go.mod h1:DthPYkmwoKwZXuLkplMYurIWBcxY1Y8FF8qFRJsyPYE= -github.com/alicebob/miniredis/v2 v2.37.0 h1:RheObYW32G1aiJIj81XVt78ZHJpHonHLHW7OLIshq68= -github.com/alicebob/miniredis/v2 v2.37.0/go.mod h1:TcL7YfarKPGDAthEtl5NBeHZfeUQj6OXMm/+iu5cLMM= +github.com/alicebob/miniredis/v2 v2.38.0 h1:nZAzCR+Lj+Vxk4ZXzm2NuKq2O33RXj1XxJ2e2uP9jiw= +github.com/alicebob/miniredis/v2 v2.38.0/go.mod h1:TcL7YfarKPGDAthEtl5NBeHZfeUQj6OXMm/+iu5cLMM= github.com/beorn7/perks v1.0.1 h1:VlbKKnNfV8bJzeqoa4cOKqO6bYr3WgKZxO8Z16+hsOM= github.com/beorn7/perks v1.0.1/go.mod h1:G2ZrVWU2WbWT9wwq4/hrbKbnv/1ERSJQ0ibhJ6rlkpw= github.com/bsm/ginkgo/v2 v2.12.0 h1:Ny8MWAHyOepLGlLKYmXG4IEkioBysk6GpaRTLC8zwWs= @@ -13,8 +13,10 @@ github.com/cespare/xxhash/v2 v2.3.0/go.mod h1:VGX0DQ3Q6kWi7AoAeZDth3/j3BFtOZR5XL github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38= github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c= github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38= -github.com/getkin/kin-openapi v0.133.0 h1:pJdmNohVIJ97r4AUFtEXRXwESr8b0bD721u/Tz6k8PQ= -github.com/getkin/kin-openapi v0.133.0/go.mod h1:boAciF6cXk5FhPqe/NQeBTeenbjqU4LhWBf09ILVvWE= +github.com/dlclark/regexp2 v1.11.0 h1:G/nrcoOa7ZXlpoa/91N3X7mM3r8eIlMBBJZvsz/mxKI= +github.com/dlclark/regexp2 v1.11.0/go.mod h1:DHkYz0B9wPfa6wondMfaivmHpzrQ3v9q8cnmRbL6yW8= +github.com/getkin/kin-openapi v0.144.0 h1:hIRcTH+KjLfkLpYU6bSSfdFpi0fZi1fp+hSPi4aQu9Y= +github.com/getkin/kin-openapi v0.144.0/go.mod h1:3BH9M9XDe/y9M5DSvEocVYAYq1w0qrhJHjC/vZi0AaY= github.com/go-chi/chi/v5 v5.2.5 h1:Eg4myHZBjyvJmAFjFvWgrqDTXFyOzjj7YIm3L3mu6Ug= github.com/go-chi/chi/v5 v5.2.5/go.mod h1:X7Gx4mteadT3eDOMTsXzmI4/rwUpOwBHLpAfupzFJP0= github.com/go-chi/cors v1.2.2 h1:Jmey33TE+b+rB7fT8MUy1u0I4L+NARQlK6LhzKPSyQE= @@ -24,12 +26,12 @@ github.com/go-logr/logr v1.4.3 h1:CjnDlHq8ikf6E492q6eKboGOC0T8CDaOvkHCIg8idEI= github.com/go-logr/logr v1.4.3/go.mod h1:9T104GzyrTigFIr8wt5mBrctHMim0Nb2HLGrmQ40KvY= github.com/go-logr/stdr v1.2.2 h1:hSWxHoqTgW2S2qGc0LTAI563KZ5YKYRhT3MFKZMbjag= github.com/go-logr/stdr v1.2.2/go.mod h1:mMo/vtBO5dYbehREoey6XUKy/eSumjCCveDpRre4VKE= -github.com/go-openapi/jsonpointer v0.21.0 h1:YgdVicSA9vH5RiHs9TZW5oyafXZFc6+2Vc1rr/O9oNQ= -github.com/go-openapi/jsonpointer v0.21.0/go.mod h1:IUyH9l/+uyhIYQ/PXVA41Rexl+kOkAPDdXEYns6fzUY= -github.com/go-openapi/swag v0.23.0 h1:vsEVJDUo2hPJ2tu0/Xc+4noaxyEffXNIs3cOULZ+GrE= -github.com/go-openapi/swag v0.23.0/go.mod h1:esZ8ITTYEsH1V2trKHjAN8Ai7xHb8RV+YSZ577vPjgQ= -github.com/go-test/deep v1.0.8 h1:TDsG77qcSprGbC6vTN8OuXp5g+J+b5Pcguhf7Zt61VM= -github.com/go-test/deep v1.0.8/go.mod h1:5C2ZWiW0ErCdrYzpqxLbTX7MG14M9iiw8DgHncVwcsE= +github.com/go-openapi/jsonpointer v0.22.5 h1:8on/0Yp4uTb9f4XvTrM2+1CPrV05QPZXu+rvu2o9jcA= +github.com/go-openapi/jsonpointer v0.22.5/go.mod h1:gyUR3sCvGSWchA2sUBJGluYMbe1zazrYWIkWPjjMUY0= +github.com/go-openapi/swag/jsonname v0.25.5 h1:8p150i44rv/Drip4vWI3kGi9+4W9TdI3US3uUYSFhSo= +github.com/go-openapi/swag/jsonname v0.25.5/go.mod h1:jNqqikyiAK56uS7n8sLkdaNY/uq6+D2m2LANat09pKU= +github.com/go-openapi/testify/v2 v2.4.0 h1:8nsPrHVCWkQ4p8h1EsRVymA2XABB4OT40gcvAu+voFM= +github.com/go-openapi/testify/v2 v2.4.0/go.mod h1:HCPmvFFnheKK2BuwSA0TbbdxJ3I16pjwMkYkP4Ywn54= github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8= github.com/google/go-cmp v0.7.0/go.mod h1:pXiqmnSA92OHEEa9HXL2W4E7lf9JzCmGVUdgjX3N/iU= github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0= @@ -44,8 +46,6 @@ github.com/jackc/pgx/v5 v5.9.2 h1:3ZhOzMWnR4yJ+RW1XImIPsD1aNSz4T4fyP7zlQb56hw= github.com/jackc/pgx/v5 v5.9.2/go.mod h1:mal1tBGAFfLHvZzaYh77YS/eC6IX9OWbRV1QIIM0Jn4= github.com/jackc/puddle/v2 v2.2.2 h1:PR8nw+E/1w0GLuRFSmiioY6UooMp6KJv0/61nB7icHo= github.com/jackc/puddle/v2 v2.2.2/go.mod h1:vriiEXHvEE654aYKXXjOvZM39qJ0q+azkZFrfEOc3H4= -github.com/josharian/intern v1.0.0 h1:vlS4z54oSdjm0bgjRigI+G1HpF+tI+9rE5LLzOg8HmY= -github.com/josharian/intern v1.0.0/go.mod h1:5DoeVV0s6jJacbCEi61lwdGj/aVlrQvzHFFd8Hwg//Y= github.com/klauspost/compress v1.18.0 h1:c/Cqfb0r+Yi+JtIEq73FWXVkRonBlf0CRNYc8Zttxdo= github.com/klauspost/compress v1.18.0/go.mod h1:2Pp+KzxcywXVXMr50+X0Q/Lsb43OQHYWRCY2AiWywWQ= github.com/klauspost/cpuid/v2 v2.2.10 h1:tBs3QSyvjDyFTq3uoc/9xFpCuOsJQFNPiAhYdw2skhE= @@ -56,18 +56,12 @@ github.com/kr/text v0.2.0 h1:5Nx0Ya0ZqY2ygV366QzturHI13Jq95ApcVaJBhpS+AY= github.com/kr/text v0.2.0/go.mod h1:eLer722TekiGuMkidMxC/pM04lWEeraHUUmBw8l2grE= github.com/kylelemons/godebug v1.1.0 h1:RPNrshWIDI6G2gRW9EHilWtl7Z6Sb1BR0xunSBf0SNc= github.com/kylelemons/godebug v1.1.0/go.mod h1:9/0rRGxNHcop5bhtWyNeEfOS8JIWk580+fNqagV/RAw= -github.com/mailru/easyjson v0.7.7 h1:UGYAvKxe3sBsEDzO8ZeWOSlIQfWFlxbzLZe7hwFURr0= -github.com/mailru/easyjson v0.7.7/go.mod h1:xzfreul335JAWq5oZzymOObrkdz5UnU4kGfJJLY9Nlc= -github.com/mohae/deepcopy v0.0.0-20170929034955-c48cc78d4826 h1:RWengNIwukTxcDr9M+97sNutRR1RKhG96O6jWumTTnw= -github.com/mohae/deepcopy v0.0.0-20170929034955-c48cc78d4826/go.mod h1:TaXosZuwdSHYgviHp1DAtfrULt5eUgsSMsZf+YrPgl8= github.com/munnerz/goautoneg v0.0.0-20191010083416-a7dc8b61c822 h1:C3w9PqII01/Oq1c1nUAm88MOHcQC9l5mIlSMApZMrHA= github.com/munnerz/goautoneg v0.0.0-20191010083416-a7dc8b61c822/go.mod h1:+n7T8mK8HuQTcFwEeznm/DIxMOiR9yIdICNftLE1DvQ= -github.com/oasdiff/yaml v0.0.0-20250309154309-f31be36b4037 h1:G7ERwszslrBzRxj//JalHPu/3yz+De2J+4aLtSRlHiY= -github.com/oasdiff/yaml v0.0.0-20250309154309-f31be36b4037/go.mod h1:2bpvgLBZEtENV5scfDFEtB/5+1M4hkQhDQrccEJ/qGw= -github.com/oasdiff/yaml3 v0.0.0-20250309153720-d2182401db90 h1:bQx3WeLcUWy+RletIKwUIt4x3t8n2SxavmoclizMb8c= -github.com/oasdiff/yaml3 v0.0.0-20250309153720-d2182401db90/go.mod h1:y5+oSEHCPT/DGrS++Wc/479ERge0zTFxaF8PbGKcg2o= -github.com/perimeterx/marshmallow v1.1.5 h1:a2LALqQ1BlHM8PZblsDdidgv1mWi1DgC2UmX50IvK2s= -github.com/perimeterx/marshmallow v1.1.5/go.mod h1:dsXbUu8CRzfYP5a87xpp0xq9S3u0Vchtcl8we9tYaXw= +github.com/oasdiff/yaml v0.1.1 h1:6nHx+pn9gBRM6YpBlFZFQGCCd1nuvqOBtTD3KKTgGxY= +github.com/oasdiff/yaml v0.1.1/go.mod h1:EYJNoyktvWMJ0Hmhx+6qTaqMOsalUaRGT8Sj1hNcegU= +github.com/oasdiff/yaml3 v0.0.14 h1:aLJee3hxBK2H5wdXd9iPcIXb93Nty1Ge0pT171eHtkw= +github.com/oasdiff/yaml3 v0.0.14/go.mod h1:csto2xfDjYccdUn/yw/bPjj/cYTdp6HtFA0J4TWG+gg= github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM= github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4= github.com/prometheus/client_golang v1.23.2 h1:Je96obch5RDVy3FDMndoUsjAhG5Edi49h0RJWRi/o0o= @@ -82,39 +76,39 @@ github.com/redis/go-redis/v9 v9.19.0 h1:XPVaaPSnG6RhYf7p+rmSa9zZfeVAnWsH5h3lxthO github.com/redis/go-redis/v9 v9.19.0/go.mod h1:v/M13XI1PVCDcm01VtPFOADfZtHf8YW3baQf57KlIkA= github.com/rogpeppe/go-internal v1.14.1 h1:UQB4HGPB6osV0SQTLymcB4TgvyWu6ZyliaW0tI/otEQ= github.com/rogpeppe/go-internal v1.14.1/go.mod h1:MaRKkUm5W0goXpeCfT7UZI6fk/L7L7so1lCWt35ZSgc= +github.com/santhosh-tekuri/jsonschema/v6 v6.0.2 h1:KRzFb2m7YtdldCEkzs6KqmJw4nqEVZGK7IN2kJkjTuQ= +github.com/santhosh-tekuri/jsonschema/v6 v6.0.2/go.mod h1:JXeL+ps8p7/KNMjDQk3TCwPpBy0wYklyWTfbkIzdIFU= github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME= github.com/stretchr/testify v1.3.0/go.mod h1:M5WIy9Dh21IEIfnGCwXGc5bZfKNJtfHm1UVUgZn+9EI= github.com/stretchr/testify v1.7.0/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg= github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U= github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U= -github.com/ugorji/go/codec v1.2.7 h1:YPXUKf7fYbp/y8xloBqZOw2qaVggbfwMlI8WM3wZUJ0= -github.com/ugorji/go/codec v1.2.7/go.mod h1:WGN1fab3R1fzQlVQTkfxVtIBhWDRqOviHU95kRgeqEY= -github.com/woodsbury/decimal128 v1.3.0 h1:8pffMNWIlC0O5vbyHWFZAt5yWvWcrHA+3ovIIjVWss0= -github.com/woodsbury/decimal128 v1.3.0/go.mod h1:C5UTmyTjW3JftjUFzOVhC20BEQa2a4ZKOB5I6Zjb+ds= github.com/yuin/gopher-lua v1.1.1 h1:kYKnWBjvbNP4XLT3+bPEwAXJx262OhaHDWDVOPjL46M= github.com/yuin/gopher-lua v1.1.1/go.mod h1:GBR0iDaNXjAgGg9zfCvksxSRnQx76gclCIb7kdAd1Pw= github.com/zeebo/xxh3 v1.1.0 h1:s7DLGDK45Dyfg7++yxI0khrfwq9661w9EN78eP/UZVs= github.com/zeebo/xxh3 v1.1.0/go.mod h1:IisAie1LELR4xhVinxWS5+zf1lA4p0MW4T+w+W07F5s= go.opentelemetry.io/auto/sdk v1.2.1 h1:jXsnJ4Lmnqd11kwkBV2LgLoFMZKizbCi5fNZ/ipaZ64= go.opentelemetry.io/auto/sdk v1.2.1/go.mod h1:KRTj+aOaElaLi+wW1kO/DZRXwkF4C5xPbEe3ZiIhN7Y= -go.opentelemetry.io/otel v1.43.0 h1:mYIM03dnh5zfN7HautFE4ieIig9amkNANT+xcVxAj9I= -go.opentelemetry.io/otel v1.43.0/go.mod h1:JuG+u74mvjvcm8vj8pI5XiHy1zDeoCS2LB1spIq7Ay0= -go.opentelemetry.io/otel/metric v1.43.0 h1:d7638QeInOnuwOONPp4JAOGfbCEpYb+K6DVWvdxGzgM= -go.opentelemetry.io/otel/metric v1.43.0/go.mod h1:RDnPtIxvqlgO8GRW18W6Z/4P462ldprJtfxHxyKd2PY= -go.opentelemetry.io/otel/sdk v1.43.0 h1:pi5mE86i5rTeLXqoF/hhiBtUNcrAGHLKQdhg4h4V9Dg= -go.opentelemetry.io/otel/sdk v1.43.0/go.mod h1:P+IkVU3iWukmiit/Yf9AWvpyRDlUeBaRg6Y+C58QHzg= -go.opentelemetry.io/otel/trace v1.43.0 h1:BkNrHpup+4k4w+ZZ86CZoHHEkohws8AY+WTX09nk+3A= -go.opentelemetry.io/otel/trace v1.43.0/go.mod h1:/QJhyVBUUswCphDVxq+8mld+AvhXZLhe+8WVFxiFff0= +go.opentelemetry.io/otel v1.44.0 h1:JjwHmHpA4iZ3wBxluu2fbbE7j4kqlE8jXyAyPXH7HqU= +go.opentelemetry.io/otel v1.44.0/go.mod h1:BMgjTHL9WPRlRjL2oZCBTL4whCGtXch2H4BhOPIAyYc= +go.opentelemetry.io/otel/metric v1.44.0 h1:1w0gILTcHdr3YI+ixLyjemwrVnsMURbTZFrSYCdDdmc= +go.opentelemetry.io/otel/metric v1.44.0/go.mod h1:8O7hanEPBNgEMmybD3s2VBKcgWOCsA6tzHBPODAiquo= +go.opentelemetry.io/otel/sdk v1.44.0 h1:nHYwb9lK+fJPU/dnT6s7W7Z8itMWyqrnVfbheVYrZ58= +go.opentelemetry.io/otel/sdk v1.44.0/go.mod h1:Osuydd3Se74nqjAKxid74N5eC+jfEqfTegHRnq58oK0= +go.opentelemetry.io/otel/trace v1.44.0 h1:jxF5CsGYCe74MCRx2X4g7WsY/VBKRqqpNvXlX/6gtIk= +go.opentelemetry.io/otel/trace v1.44.0/go.mod h1:oLl1jrMQAVo6v3GAggN+1VH9VIz9iUSvW53sW1Q8PIE= go.uber.org/atomic v1.11.0 h1:ZvwS0R+56ePWxUNi+Atn9dWONBPp/AUETXlHW0DxSjE= go.uber.org/atomic v1.11.0/go.mod h1:LUxbIzbOniOlMKjJjyPfpl4v+PKK2cNJn91OQbhoJI0= go.uber.org/goleak v1.3.0 h1:2K3zAYmnTNqV73imy9J1T3WC+gmCePx2hEGkimedGto= go.uber.org/goleak v1.3.0/go.mod h1:CoHD4mav9JJNrW/WLlf7HGZPjdw8EucARQHekz1X6bE= go.uber.org/multierr v1.11.0 h1:blXXJkSxSSfBVBlC76pxqeO+LN3aDfLQo+309xJstO0= go.uber.org/multierr v1.11.0/go.mod h1:20+QtiLqy0Nd6FdQB9TLXag12DsQkrbs3htMFfDN80Y= -go.uber.org/zap v1.27.1 h1:08RqriUEv8+ArZRYSTXy1LeBScaMpVSTBhCeaZYfMYc= -go.uber.org/zap v1.27.1/go.mod h1:GB2qFLM7cTU87MWRP2mPIjqfIDnGu+VIO4V/SdhGo2E= +go.uber.org/zap v1.28.0 h1:IZzaP1Fv73/T/pBMLk4VutPl36uNC+OSUh3JLG3FIjo= +go.uber.org/zap v1.28.0/go.mod h1:rDLpOi171uODNm/mxFcuYWxDsqWSAVkFdX4XojSKg/Q= go.yaml.in/yaml/v2 v2.4.3 h1:6gvOSjQoTB3vt1l+CU+tSyi/HOjfOjRLJ4YwYZGwRO0= go.yaml.in/yaml/v2 v2.4.3/go.mod h1:zSxWcmIDjOzPXpjlTTbAsKokqkDNAVtZO0WOMiT90s8= +go.yaml.in/yaml/v3 v3.0.4 h1:tfq32ie2Jv2UxXFdLJdh3jXuOzWiL1fo0bu/FbuKpbc= +go.yaml.in/yaml/v3 v3.0.4/go.mod h1:DhzuOOF2ATzADvBadXxruRBLzYTpT36CKvDb3+aBEFg= golang.org/x/sync v0.20.0 h1:e0PTpb7pjO8GAtTs2dQ6jYa5BWYlMuX047Dco/pItO4= golang.org/x/sync v0.20.0/go.mod h1:9xrNwdLfx4jkKbNva9FpL6vEN7evnE43NNNJQ2LF3+0= golang.org/x/sys v0.45.0 h1:dO4czNzziLiiXplLQgBCEpCvXQ3dnkn0SdaZSYdQ+FY=