fix(notary): document admin posture and config-apply 503 in OpenAPI#168
Conversation
The runtime serves GET /admin/v1/posture and a 503 config.apply_unavailable response on /admin/v1/config/apply, but the generated OpenAPI document omitted both, so the published contract did not match runtime. Register /admin/v1/posture (tier query parameter; 200 plus the 400/401/403/500/503 problem responses) and add the 503 problem response to /admin/v1/config/apply. Each problem example mirrors the exact runtime body and application/problem+json media type. Regenerate the committed artifact, preserving the pinned product version 0.6.2 (the generator emits the crate version via CARGO_PKG_VERSION; the published product/docset version is 0.6.2). Signed-off-by: Jeremi Joslin <jeremi@joslin.fr>
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: f8d213564e
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
The GET /admin/v1/posture 200 response only had a description, so spec consumers would generate the operation as returning no body even though the handler returns a registry.ops.posture.v1 document. Add an application/json example sourced from registry-platform-ops NOTARY_POSTURE_EXAMPLE_V1 (the committed schema-valid sample), mirroring the admin capabilities pattern. Addresses Codex review feedback on #168. Signed-off-by: Jeremi Joslin <jeremi@joslin.fr>
|
Addressed in 375ca43. |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 31890ce6bc
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
The identifier-domain consolidation (id.registrystack.org) landed on main while this PR was open. Merging it in left the committed OpenAPI artifact stale: the posture and config-apply problem-type examples added here still pointed at docs.registry-notary.dev, which the new identifier_domains test rejects. Regenerate the artifact from the merged generator so the six problem types resolve under https://id.registrystack.org/problems/registry-notary/. Version stays pinned at the published product version 0.6.2 (the generator emits the 0.8.3 crate version). Signed-off-by: Jeremi Joslin <jeremi@joslin.fr>
The GET /admin/v1/posture 200 response only had a description, so spec consumers would generate the operation as returning no body even though the handler returns a registry.ops.posture.v1 document. Add an application/json example sourced from registry-platform-ops NOTARY_POSTURE_EXAMPLE_V1 (the committed schema-valid sample), mirroring the admin capabilities pattern. Addresses Codex review feedback on #168. Signed-off-by: Jeremi Joslin <jeremi@joslin.fr>
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 9ce0f257ae
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| "config_trust.antirollback_state_path is not configured", | ||
| ), | ||
| ); | ||
| set_json_response( |
There was a problem hiding this comment.
Fresh evidence after the earlier comment: this now adds an application/json example, but set_json_response still does not attach any schema for the 200 posture response, so the generated artifact exposes GET /admin/v1/posture as an untyped/free-form body. OpenAPI clients generated from the published spec still cannot deserialize the registry.ops.posture.v1 contract as a typed response even though the runtime always returns that shape; add a schema/ref for the posture document alongside the example.
Useful? React with 👍 / 👎.
1 participant
What
Follow-up to the review of #166. The staff-engineer review flagged that the generated OpenAPI document omitted two surfaces the runtime actually serves, so the published contract did not match runtime.
GET /admin/v1/postureis now documented: thetierquery parameter (enumdefault/restricted) and the full response set:200redacted posture (body is aregistry.ops.posture.v1document)400registry.admin.posture.invalid_tier401auth.missing_credential403auth.scope_denied(registry_notary:ops_read)500posture.filter_failed503posture.unavailablePOST /admin/v1/config/applynow documents the503config.apply_unavailableproblem response.Each problem example mirrors the exact runtime body (admin-schema shape via
admin_problem_responseforposture.unavailable/invalid_tier; plain RFC 9457 shape forfilter_failed/config.apply_unavailable) and theapplication/problem+jsonmedia type.Verification
cargo test -p registry-notary-server: lib 318 passed + all integration binaries, 0 failures.cargo fmt -p registry-notary-server -- --check: clean.cargo run -p registry-notary -- openapi; the artifact diff is exactly the two additions.Flag: artifact version preserved at 0.6.2
Regenerating the artifact also bumps
info.version0.6.2 -> 0.8.3, because the generator emits the Rust crate version (env!("CARGO_PKG_VERSION")= 0.8.3) while the published product version is 0.6.2 (docsets.yaml,products/notary/CHANGELOG.md, release notes). To keep this PR scoped to the two surface additions and avoid silently re-pinning the published version, I reverted just the twoinfo.versionlines back to0.6.2.Consequence: re-running the generator will show a
versiondiff until the crate-vs-product version mismatch is resolved. That generator-vs-product version question is pre-existing and out of scope here. Happy to follow up (re-pin to 0.8.3, or change the generator to emit the product version) on your call.