Skip to content

Add a Connect RPC

Connect Go v2 handlers accept and return plain protobuf messages. Register the generated service methods on a connect.Server and mount it with connecthttp.Mount. Request and response headers live in connect.CallInfo on the context. Unified server interceptors enforce authorization when each decoded request is received, before application logic runs.

  1. Add the request, response, validation rules, and service method under proto/scribe/v1.
  2. Add the protobuf scribe.v1.options.v1.authz method option. This is the runtime and generated OpenAPI source of truth. Use allow_anonymous only for intentionally public operations and session_only for browser account or workspace administration that must reject API keys and external JWTs.
  3. Assign any operation larger than the 4 MiB default to an explicit request class in internal/server/request_limits.go and add a boundary test.
  4. Run make generate; never hand-edit generated clients or handlers.
  5. Implement an application use case rather than embedding orchestration in the transport handler.
  6. Normalize errors to Connect codes and avoid leaking provider/database text.
  7. Add handler, policy, and generated-client tests. Generation fails if the RPC is absent from OpenAPI or its authorization descriptor is missing.
  8. Update the API guide. docs/api/scribe.openapi.yaml is generated by Buf.

No new REST business endpoint should be added. Public IIIF resources and OAuth callbacks remain HTTP representations where that protocol requires them.