Documentation
¶
Overview ¶
Package transport is the controller tier: the edge every inbound request enters by — a REST or RPC handler. Tier orders the tier's layers, switched and tuned per controller by the decoration config's controllers tier (decoration.controllers, built by decorate.Decorations); Base runs a controller's handlers through it. Protocol pieces live in the sub-packages.
Sub-packages ¶
- rest: HTTP response helpers (BaseController), request-to-handler adapter (Adapt)
- rpc: Connect/gRPC error mapping (ToConnectError, FromRPCError)
- jsonapi: the JSON:API REST response middleware
- docs: OpenAPI spec and Redoc handlers
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Interceptors ¶ added in v0.0.7
func Interceptors[I any]( name string, d decorate.Deps, native func(decorate.Layer) ([]I, bool), adapt func(unary, stream decorate.OpMiddleware) I, authn []I, ) []I
Interceptors lays out a server framework's interceptor chain (I is its interceptor type) as the controller tier for the controller named name over d, outermost first, so an RPC server is decorated exactly like a Base handler:
- A layer the framework implements natively — a trace extracted from the request headers, metrics labelled by status code, a status-aware access log — comes from native, which reports whether it handles the layer and returns its interceptors (none when the collaborator is absent).
- Every other run of consecutive layers becomes one interceptor, built by adapt from the run's middleware twice over: once for a unary call and once for a stream, which has no timeout so a long-lived stream outlives any call budget. A run whose layers all lack their collaborators adds nothing.
- authn, the framework's interceptors that authenticate the caller, run just before the auth layer, so it authorizes an authenticated principal.
func Tier ¶ added in v0.0.7
Tier is the controller decoration tier, outermost first: each request gets its server span, metrics and log line around everything else, so a panic, a shed or a denial is still observed (as the edge, a failure is logged at Warn for a client fault and at Error otherwise); recovery turns a panic into an INTERNAL error; the rate limit and the shedding bulkhead reject excess load before any work; auth authorizes "<controller>.<op>"; and the timeout bounds the handler.
Types ¶
type Base ¶ added in v0.0.7
type Base struct {
// Subject runs the controller's operations; it supplies Name and Exec.
decorate.Subject
}
Base runs one controller's handlers through the controller tier: each operation is one method of the controller's contract (a generated handler interface), decorated as the controller's name plus the method's snake_case name. Its embedded Exec runs a single operation; Handler decorates a whole HandlerFunc. The zero Base runs handlers undecorated.
func NewBase ¶ added in v0.0.7
NewBase returns the Base for the controller named name whose operations are the methods of its contract C, decorated from decs: the controller as the controller-tier component name, and each operation op as name+"."+op. A C that is not an interface, or a decoration that fails to resolve, is an error.
func (Base) Handler ¶ added in v0.0.7
func (b Base) Handler[Req, Resp any]( op string, fn HandlerFunc[Req, Resp], ) HandlerFunc[Req, Resp]
Handler returns fn run through the tier as the operation op.
type HandlerFunc ¶
HandlerFunc is a generic request handler function that processes a request and returns a response. This is the transport-layer equivalent of Pipeline/Workflow Execute, applied to individual handlers.
HandlerFunc is protocol-agnostic: it works with both REST and RPC transports. Base.Handler wraps one with the controller tier.
Example:
handler := func(ctx context.Context, req LoginRequest) (LoginResponse, error) {
// Validate, call workflow, serialize
return LoginResponse{Token: "..."}, nil
}
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package cobra is the command-line front-end of an operations registry (execution/ops): Command builds a Cobra command for one registered operation, its flags and positional arguments derived from the operation's input type, so a CLI and the other front-ends run the operation on the same input.
|
Package cobra is the command-line front-end of an operations registry (execution/ops): Command builds a Cobra command for one registered operation, its flags and positional arguments derived from the operation's input type, so a CLI and the other front-ends run the operation on the same input. |
|
Package connect provides a Connect/gRPC server factory that mounts proto-generated handlers on a standard net/http.ServeMux.
|
Package connect provides a Connect/gRPC server factory that mounts proto-generated handlers on a standard net/http.ServeMux. |
|
interceptors
Package interceptors provides Connect RPC interceptors for cross-cutting concerns.
|
Package interceptors provides Connect RPC interceptors for cross-cutting concerns. |
|
Package cron is the scheduled-job front-end of an operations registry (execution/ops): a job's entrypoint names one operation and its JSON arguments, and Run executes it unattended under the registry's exposure policy.
|
Package cron is the scheduled-job front-end of an operations registry (execution/ops): a job's entrypoint names one operation and its JSON arguments, and Run executes it unattended under the registry's exposure policy. |
|
Package docs provides reusable HTTP handlers for serving OpenAPI specs and Redoc UI documentation pages.
|
Package docs provides reusable HTTP handlers for serving OpenAPI specs and Redoc UI documentation pages. |
|
Package grpc builds a configured gRPC server (NewServer) and registers the gRPC health service on it; interceptors/ runs its RPCs through the controller tier.
|
Package grpc builds a configured gRPC server (NewServer) and registers the gRPC health service on it; interceptors/ runs its RPCs through the controller tier. |
|
interceptors
Package interceptors runs a gRPC server's RPCs through the controller tier (transport.Tier): ServerOptions lays the tier out as unary and stream server interceptors, with gRPC-native tracing, metrics and logging standing in for the tier's own.
|
Package interceptors runs a gRPC server's RPCs through the controller tier (transport.Tier): ServerOptions lays the tier out as unary and stream server interceptors, with gRPC-native tracing, metrics and logging standing in for the tier's own. |
|
Package jsonapi provides HTTP middleware that transforms Vanguard REST responses into [JSON:API](https://jsonapi.org/format/) envelopes with the foundation/jsonapi codec.
|
Package jsonapi provides HTTP middleware that transforms Vanguard REST responses into [JSON:API](https://jsonapi.org/format/) envelopes with the foundation/jsonapi codec. |
|
Package mcp is a Model Context Protocol front-end for an operations registry (execution/ops): it advertises one tool per operation the registry admits and runs each tool call through the registry, a bounded operation inline and a long-running one as a background run (execution/runs) that the runs.* tools observe and cancel.
|
Package mcp is a Model Context Protocol front-end for an operations registry (execution/ops): it advertises one tool per operation the registry admits and runs each tool call through the registry, a bounded operation inline and a long-running one as a background run (execution/runs) that the runs.* tools observe and cancel. |
|
Package rest provides HTTP response helpers for REST API handlers.
|
Package rest provides HTTP response helpers for REST API handlers. |
|
Package rpc provides Connect RPC utilities for bidirectional mapping between domain AppErrors and Connect/gRPC status codes.
|
Package rpc provides Connect RPC utilities for bidirectional mapping between domain AppErrors and Connect/gRPC status codes. |
|
Package server builds the ServerTransport from config: an unserved stub (the default) or Connect over net/http.
|
Package server builds the ServerTransport from config: an unserved stub (the default) or Connect over net/http. |
|
stub
Package stub is the zero-infrastructure ServerTransport: handlers register on a mux that is never served, so a graph boots and its routes can be exercised in process (httptest) without opening a port.
|
Package stub is the zero-infrastructure ServerTransport: handlers register on a mux that is never served, so a graph boots and its routes can be exercised in process (httptest) without opening a port. |