[antoinetoussaint-byte]

What

Additive API, no breaking change:

• Gateway.Transcoded(ctx, prefix, method, req, resp, opts...) calls one RPC of a composed module through the gateway, using the module's own generated request and response messages over the RPC's google.api.http binding.
  • It resolves method (the generated "/pkg.Service/Method" constant) in the global registry, then picks the first binding (primary, then additional bindings) whose path lies under the consumed prefix. Path variables, query and body all come from the descriptor. Path values are escaped; set, non-path fields go into the query by proto name, or into the body the binding names.
  • It refuses before sending anything:
    • a method with no binding under the prefix (including a string-prefix-only match such as /v1/thing against /v1/things/...);
    • a method with no binding at all;
    • a multi-segment variable;
    • an empty or dot-segment path value;
    • a request or response of the wrong type;
    • a prefix that is not a clean absolute path.
  • The response is protojson-decoded with unknown fields discarded and bounded by MaxResponseBytes (8 MiB default). A non-2xx answer is a *GatewayError with the status.
• Gateway.OrgID() is the active org the gateway stamped, and the one ForModule mints in.
• Gateway.WorkContextPrincipals(ctx) returns the org, owner and current actor that accounts answered a ForModule mint with. It reuses the cached capability. A handler checking a claimed owner no longer mints its own Task with an invented session. Covered by TestWorkContextPrincipalsReportsWhomAccountsIssuedFor.
• Message[T] / MessageOf encode a generated message as protobuf JSON inside a handler's response. encoding/json would otherwise use Go struct tags.
• FieldMask / NewFieldMask / MustFieldMask / Apply form a declared allowlist over an owner's message. Unknown paths fail at declaration, and a field the owner adds later reaches no browser until someone names it.
• Operation, QueryParameter, Server.Operations, InterfaceInfo, InterfaceDocument are the documented-route declaration and its Swagger 2.0 artifact. This is moved from a consuming solution's hand-written generator. Message[T] fields are described from the descriptor, with JSON names.

Why

The gateway reaches a composed module only under the REST prefix the solution federates (/v1/<as>/*). A module's generated gRPC or Connect client therefore cannot be pointed at it. Solutions were hand-building paths, query strings and wire structs for every module read, and hand-writing their own OpenAPI generator. This is the runtime-owner half of moving a consuming solution onto generated clients.

Classification

Fix at the owner. The runtime owns "the gateway client a handler uses to read composed modules". It stays module-agnostic: nothing here names a module.

Verified

• go vet ./..., gofmt, and go test ./... pass. The new tests also pass with -race.
• transcode_test.go registers a dynamic annotated service. It covers:
  • binding selection under the prefix, escaping, query encoding (repeated and nested), and int64 decode with an unknown field present;
  • body *;
  • every refusal, asserting that nothing reached the server;
  • the 403 status kept, the response bound, and the bearer presented.
• The same file covers FieldMask (nested and repeated pruning, input not modified, unknown or scalar-descent paths refused) and Message[T] JSON.
• operations_test.go covers descriptor-based definitions (JSON names, self-reference terminating in $ref), refusal of undocumented or double-handled operations, and route registration.

Not verified

• Against a live gateway. The consuming solution's branch exercises it against the documents module's generated descriptors.
• No tag or release.

🤖 Generated with Claude Code

[antoinetoussaint-byte]

Superseded by #39, which contains all three of this PR's commits and is now based on main. Lands with #39.