Repository navigation
Conversation
|
Important
This repository does not receive automatic reviews because it has fewer than 10 stars.
|
[Medium impact] The PR appears safe to merge, with the previous non-blocking provider-error description issue still open. Findings
Fix with agent prompt### Issue 1
crates/gateway/app/src/relay.rs:101-104
The explicit `403` response says there is no body, but a provider's `403` returns JSON with `error.code = upstream_client_error`. OpenAPI uses this explicit response instead of the `4XX` fallback, so generated clients can discard the error details.
The same overlap leaves `upstream_client_error` out of the explicit `400`, `401`, `404`, and `429` code lists. Include provider failures in each affected response, including the JSON body for `403`, and regenerate the document. This also applies to the speech and web search descriptions.
---
For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.
|
| (status = 403, description = "No body. The host wall refused a request whose authority is not the bound loopback socket."), | ||
| (status = 404, description = "The request named a model with no `[[model]]` entry.", body = ErrorEnvelope), | ||
| (status = 429, description = "The model's queue turned the request away at capacity.", body = ErrorEnvelope), | ||
| (status = "4XX", description = "The upstream backend answered with this client error status, passed through.", body = ErrorEnvelope), |
There was a problem hiding this comment.
Provider errors are described incorrectly
The explicit 403 response says there is no body, but a provider's 403 returns JSON with error.code = upstream_client_error. OpenAPI uses this explicit response instead of the 4XX fallback, so generated clients can discard the error details.
The same overlap leaves upstream_client_error out of the explicit 400, 401, 404, and 429 code lists. Include provider failures in each affected response, including the JSON body for 403, and regenerate the document. This also applies to the speech and web search descriptions.
Prompt To Fix With AI
This is a comment left during a code review.
Path: crates/gateway/app/src/relay.rs
Line: 101-104
Comment:
**Provider errors are described incorrectly**
The explicit `403` response says there is no body, but a provider's `403` returns JSON with `error.code = upstream_client_error`. OpenAPI uses this explicit response instead of the `4XX` fallback, so generated clients can discard the error details.
The same overlap leaves `upstream_client_error` out of the explicit `400`, `401`, `404`, and `429` code lists. Include provider failures in each affected response, including the JSON body for `403`, and regenerate the document. This also applies to the speech and web search descriptions.
---
For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.The Gateway had no machine-readable description of its API. This adds an OpenAPI 3.1 document that utoipa builds from attributes on the 13 public handlers and derives on their wire types, and commits it beside the gateway crate. A test regenerates it and fails when the committed copy differs, a coverage test holds it to the route registry, and a validity test checks it offline against the official OAS 3.1 schema. - `crates/gateway/app/src/openapi.rs` lists the handlers in test-only `OpenApi` derives and adds the security schemes. `build_router` is untouched, and each attribute binds its registry constant's path. - `crates/gateway/app/src/openapi/markers.rs` adds the `x-runvil-*` markers utoipa's attributes cannot carry, widens two `oneOf` unions whose branches overlap to `anyOf`, and sets the loading 503's `Retry-After` to the constant 5. - `utoipa` is a normal dependency of six crates and `jsonschema` a dev-dependency. The release binary carries the derives but never builds the document. - `crates/gateway/stt/api/src/realtime/route-errors.rs` takes `session_error` out of the route file, which the new attribute pushed past 500 lines. - `crates/gateway/app/src/registry.rs` now lists the two speech routes and the five config UI assets, adding seven debug `route mounted` lines. No status, header, or body changes. - `HealthReply`, `VoicesReply`, and `CacheDeletedReply` replace `json!` replies and serialize byte for byte as before. `ErrorEnvelope` and `CacheReadyReply` name bodies the server writes as JSON literals, and `TranscriptionUpload` and `RealtimeIntent` name inputs the handlers parse by hand; none is ever built. - `ERROR_CODES` is written by hand, and no test checks that a declared status or error code is one the route can return or that a real response matches the document. Enums lose their per-variant descriptions. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Plan: vibe/2026-11/2026-11-12-1-gateway-openapi-utoipa.md
6d5d8e4 to
fb60a7f
Compare
There was a problem hiding this comment.
🟡 Changes recommended
Exact-status OpenAPI entries override 4XX, omitting valid upstream_client_error codes and incorrectly documenting upstream 403 responses as bodyless across relay, speech, and web search.
1 open issue
What changed in this PR
This PR offers a utoipa-based alternative to #7 for describing the Gateway’s public API in OpenAPI 3.1. It derives the description from handler annotations and wire types while preserving route paths and response formats.
Changes:
- Annotates 13 public operations and their schemas, with post-processing for Gateway extensions.
- Adds document drift, route coverage, feature-shape, and offline validity checks.
- Expands the route registry and introduces three typed replies with serialization checks.
| File | Description |
|---|---|
vibe/2026-11/2026-11-12-1-gateway-openapi-utoipa.md |
Records the design, trade-offs, and verification plan. |
crates/gateway/web-search/src/service.rs |
Derives search request and response schemas. |
crates/gateway/web-search/Cargo.toml |
Adds utoipa. |
crates/gateway/stt/api/src/realtime/route.rs |
Documents the WebSocket handshake and names its path. |
crates/gateway/stt/api/src/realtime/route-errors.rs |
Holds the relocated session-error mapping. |
crates/gateway/stt/api/src/realtime/query.rs |
Adds the schema-only realtime intent enum. |
crates/gateway/stt/api/src/realtime.rs |
Exposes the route module and path constant. |
crates/gateway/stt/api/src/lib.rs |
Exports speech paths and SpeechApi. |
crates/gateway/stt/api/src/batch.rs |
Documents multipart transcription and response schemas. |
crates/gateway/stt/api/Cargo.toml |
Adds schema and error-envelope dependencies. |
crates/gateway/README.md |
Links the generated API description. |
crates/gateway/protocol/src/wire/tests/speech.rs |
Checks schema bounds against speech validation. |
crates/gateway/protocol/src/wire/speech.rs |
Derives speech schemas and declares bounds. |
crates/gateway/protocol/src/wire/rerank.rs |
Derives rerank schemas. |
crates/gateway/protocol/src/wire/envelope.rs |
Defines schema-only error-envelope types. |
crates/gateway/protocol/src/wire/embedding.rs |
Derives embedding schemas. |
crates/gateway/protocol/src/wire.rs |
Derives chat schemas and exports error types. |
crates/gateway/protocol/Cargo.toml |
Adds utoipa. |
crates/gateway/local/src/cache.rs |
Derives the cache-entry schema. |
crates/gateway/local/Cargo.toml |
Adds utoipa. |
crates/gateway/config-ui/src/routes.rs |
Centralizes and exports asset paths. |
crates/gateway/config-ui/src/lib.rs |
Re-exports asset paths for the registry. |
crates/gateway/app/tests/fixtures/oas-3.1/schema-base-2026-08-03.json |
Supplies the offline schema-validation entry point. |
crates/gateway/app/tests/fixtures/oas-3.1/schema-2026-08-03.json |
Vendors the OpenAPI document schema. |
crates/gateway/app/tests/fixtures/oas-3.1/NOTICE |
Records vendored-schema attribution. |
crates/gateway/app/tests/fixtures/oas-3.1/meta-2024-11-10.json |
Vendors OpenAPI vocabulary validation. |
crates/gateway/app/tests/fixtures/oas-3.1/LICENSE |
Includes the vendored schemas’ license. |
crates/gateway/app/tests/fixtures/oas-3.1/dialect-2024-11-10.json |
Vendors the OpenAPI schema dialect. |
crates/gateway/app/src/web_search.rs |
Annotates the web-search operation. |
crates/gateway/app/src/speech.rs |
Annotates speech routes and types the voices reply. |
crates/gateway/app/src/speech-tests.rs |
Checks voices reply serialization equivalence. |
crates/gateway/app/src/relay.rs |
Annotates chat, embeddings, and rerank operations. |
crates/gateway/app/src/registry.rs |
Registers speech routes and config UI assets. |
crates/gateway/app/src/registry-tests.rs |
Checks registered asset paths against exported paths. |
crates/gateway/app/src/openapi/markers.rs |
Adds extensions, error codes, and schema adjustments. |
crates/gateway/app/src/openapi.rs |
Assembles feature-aware documents in tests. |
crates/gateway/app/src/openapi-validity-tests.rs |
Checks offline validity, references, and overlapping unions. |
crates/gateway/app/src/openapi-tests.rs |
Checks drift, coverage, features, and conventions. |
crates/gateway/app/src/models.rs |
Documents the model catalog and its schemas. |
crates/gateway/app/src/loopback-tests.rs |
Updates comments about asset-route coverage. |
crates/gateway/app/src/lib.rs |
Wires in OpenAPI tests and updates registry comments. |
crates/gateway/app/src/health.rs |
Documents health and introduces a typed reply. |
crates/gateway/app/src/health-tests.rs |
Checks health reply serialization equivalence. |
crates/gateway/app/src/cache.rs |
Documents cache operations and types the delete reply. |
crates/gateway/app/src/cache-tests.rs |
Checks delete reply serialization equivalence. |
crates/gateway/app/src/boot/boot_speech_tests.rs |
Gates the realtime test helper on config-ui. |
crates/gateway/app/README.md |
Documents generation and verification commands. |
crates/gateway/app/Cargo.toml |
Adds utoipa and test-only JSON Schema validation. |
crates/gateway-api-types/src/metadata.rs |
Derives metadata schemas and marks extension fields. |
crates/gateway-api-types/src/lib.rs |
Updates dependency documentation. |
crates/gateway-api-types/README.md |
Explains utoipa’s role in shared types. |
crates/gateway-api-types/Cargo.toml |
Adds utoipa. |
Cargo.toml |
Declares shared OpenAPI dependencies. |
Cargo.lock |
Locks the added dependencies. |
.github/workflows/ci.yml |
Checks OpenAPI generation without default features. |
Review effort: Balanced
| ("401", AUTH), | ||
| ("404", &["model_not_found"]), | ||
| ("429", &["queue_rejected"]), | ||
| ("4XX", PASSED_THROUGH), |

Andrew asked on #7 whether a third-party crate already provides this, so we would not have to maintain it. This describes the same API with utoipa, so the two approaches can be compared side by side. Only one of the two should land.
What it does
#[utoipa::path]attributes on the 13 public handlers andToSchemaderives on their wire types.OpenApiderives collect them; the speech crate exports its two handlers through a publicSpeechApi.build_routeris not changed, and every route keeps its path.crates/gateway/app/openapi.json. A test regenerates it and fails on any difference.BLESS_OPENAPI=1 cargo test -p gateway --lib openapirewrites it.Same as #7
Paths, operations, status codes, media types, error-code lists and required fields are the same in the two committed documents.
Trade-off
utoipaandutoipa-genare new packages in the release build, because the derives sit on runtime types. Generate and pin an OpenAPI 3.1 description of the Gateway #7'sschemarswas already in it.x-runvil-*markers where utoipa drops them, pinsRetry-Afterto 5, and widens two unions fromoneOftoanyOf, because a valid response matched both branches andoneOfrejected it.Not done
x-runvil-source,x-runvil-events,x-runvil-error-types, and the event schemas of the cache download stream.Also in this commit
route mountedlines, no response changes.json!values with the same output, each with a test.session_errormoved torealtime/route-errors.rsto keeproute.rsunder the 500-line limit.boot_speech_tests.rs:realtime_upgrade_statusis now compiled only withconfig-ui. That unused-function warning in the stt-only build is already on master.Checks
Run locally on Windows on this change, on master at
fe136b4: fmt, clippy, nextest (1963 passed, 54 skipped), the headless build, the OpenAPI tests without default features and with onlystt, rustdoc, cargo deny, xtask tidy, build-xtask tests, the UI typecheck and tests. CI passed onfb60a7f, Linux and Windows.Plan:
vibe/2026-11/2026-11-12-1-gateway-openapi-utoipa.md🤖 Generated with Claude Code