Skip to content

Add explicit httpapi response specs #5

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
swetjen merged 1 commit into from
Mar 1, 2026
Merged

Add explicit httpapi response specs #5

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
36 changes: 19 additions & 17 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,20 +8,20 @@ These instructions describe how to understand and work with this repository.
- Route registration is dynamic; there is no CLI.

## Key Files
- `virtuous/rpc/router.go`: RPC route registration, guards, metadata inference.
- `virtuous/rpc/handler.go`: RPC handler adapter and signature validation.
- `virtuous/rpc/openapi.go`: RPC OpenAPI 3.0.3 document generation.
- `virtuous/rpc/client_spec.go`: RPC client spec builder shared by emitters.
- `virtuous/rpc/client_js_gen.go`: RPC JS client template and helpers.
- `virtuous/rpc/client_ts.go`: RPC TS client template and helpers.
- `virtuous/httpapi/router.go`: HTTP route registration, guards, metadata inference.
- `virtuous/httpapi/typed_handler.go`: adapter to attach request/response types and metadata.
- `virtuous/schema/registry.go`: reflection-based type registry and override logic.
- `virtuous/schema/openapi_schema.go`: OpenAPI schema generation for types.
- `virtuous/httpapi/openapi.go`: OpenAPI 3.0.3 document generation.
- `virtuous/httpapi/client_spec.go`: client spec builder shared by emitters.
- `virtuous/httpapi/client_js_gen.go`: JS client template and helpers.
- `virtuous/httpapi/client_ts.go`: TS client template and helpers.
- `rpc/router.go`: RPC route registration, guards, metadata inference.
- `rpc/handler.go`: RPC handler adapter and signature validation.
- `rpc/openapi.go`: RPC OpenAPI 3.0.3 document generation.
- `rpc/client_spec.go`: RPC client spec builder shared by emitters.
- `rpc/client_js_gen.go`: RPC JS client template and helpers.
- `rpc/client_ts.go`: RPC TS client template and helpers.
- `httpapi/router.go`: HTTP route registration, guards, metadata inference.
- `httpapi/typed_handler.go`: adapter to attach request/response types and metadata.
- `schema/registry.go`: reflection-based type registry and override logic.
- `schema/openapi_schema.go`: OpenAPI schema generation for types.
- `httpapi/openapi.go`: OpenAPI 3.0.3 document generation.
- `httpapi/client_spec.go`: client spec builder shared by emitters.
- `httpapi/client_js_gen.go`: JS client template and helpers.
- `httpapi/client_ts.go`: TS client template and helpers.
- `example/`: reference app and generated outputs.

## Architecture Notes
Expand All @@ -38,7 +38,9 @@ These instructions describe how to understand and work with this repository.
- Use `rpc.NewRouter(rpc.WithPrefix("/rpc"))` and `HandleRPC` for RPC handlers.
- Prefer method-prefixed patterns (`GET /path`) to ensure docs/clients are emitted.
- Use `Wrap` to attach request/response types to handlers.
- For no-body responses, use the sentinel types in `virtuous/types.go`.
- For optional `httpapi` request bodies, wrap request type with `httpapi.Optional[Req]()`.
- For multi-status or custom-media `httpapi` routes, declare `HandlerMeta.Responses` with `httpapi.ResponseSpec`.
- For no-body `httpapi` responses, use `httpapi.NoResponse200`, `httpapi.NoResponse204`, or `httpapi.NoResponse500`.
- Add `doc:"..."` tags to improve schema and client docs.
- Update `CHANGELOG.md` with a new version entry whenever adding functionality, fixing bugs, or changing behavior.
- For Python, do not use `from __future__ import annotations`.
Expand All @@ -58,5 +60,5 @@ These instructions describe how to understand and work with this repository.
- Custom guards for auth schemes and middleware.

## Reference Specs
- See `SPEC-RPC.md` and `SPEC-RPC-SIMPLE.md` for RPC details and examples.
- See `SPEC.md` for the legacy `httpapi` contract.
- See `docs/specs/overview.md` for current spec locations.
- Historical design specs are in `_design/SPEC-RPC.md`, `_design/SPEC-RPC-SIMPLE.md`, and `_design/SPEC.md`.
7 changes: 7 additions & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,12 @@
# Changelog

## 0.0.25

- Add typed `httpapi` response media support for `string` (`text/plain`) and `[]byte` (`application/octet-stream`) in OpenAPI and generated JS/TS/PY clients.
- Add `httpapi.Optional[Req]()` request marker to model optional JSON request bodies in OpenAPI and generated clients.
- Add `httpapi.HandlerMeta.Responses` / `httpapi.ResponseSpec` for explicit multi-status and custom-media response contracts.
- Add migration and guard documentation examples for composite OR auth semantics and typed/non-typed non-JSON migration patterns.

## 0.0.24

- Fix README license badge link to target the canonical GitHub `LICENSE` file URL.
Expand Down
Loading