invariant

package
v0.12.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 25, 2026 License: Apache-2.0 Imports: 45 Imported by: 2

Documentation

Overview

Package invariant uses generated gRPC services as the canonical programming model and projects their registered implementations onto native gRPC, HTTP/Connect, MCP, and CLI adapters.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func DefaultHTTPMetadataMapper 

func DefaultHTTPMetadataMapper(r *http.Request) metadata.MD

DefaultHTTPMetadataMapper forwards only common tracing/correlation headers. Authentication middleware should validate credentials and place trusted identity in context, not copy caller-provided identity headers into metadata.

func ParseDescriptorBytes 

func ParseDescriptorBytes(data []byte) (*invpb.ParsedDescriptor, error)

ParseDescriptorBytes parses a serialized FileDescriptorSet and returns a ParsedDescriptor. Use this with go:embed to avoid runtime file dependencies.

func Validation 

func Validation() (grpc.UnaryServerInterceptor, error)

Validation returns an interceptor that runs protovalidate on each request.

Validation failures are returned as INVALID_ARGUMENT with field-level BadRequest details. Requests of types without protovalidate constraints pass through unchanged. 

v, err := invariant.Validation()
if err != nil {
    return err
}
server.Use(v)

Streaming RPCs are not covered by the unary interceptor — pair it with ValidationStream and `server.UseStream(vs)` when you have streaming methods with protovalidate constraints.

func ValidationStream 

func ValidationStream() (grpc.StreamServerInterceptor, error)

ValidationStream returns a stream interceptor that runs protovalidate on the request before opening the stream. Failures short-circuit with INVALID_ARGUMENT and never produce any response messages — the same guarantee callers expect from the unary variant.

Types

type HTTPHeaderProvider 

type HTTPHeaderProvider func(ctx context.Context, req *OutboundHTTPRequest) (map[string]string, error)

HTTPHeaderProvider returns extra outbound HTTP headers for ConnectHTTP requests. Typical use: API signatures, short-lived tokens, per-request timestamps.

type HTTPMetadataMapper 

type HTTPMetadataMapper func(*http.Request) metadata.MD

HTTPMetadataMapper selects untrusted HTTP request values that may be exposed to handlers as incoming gRPC metadata. Invariant applies a reserved-key filter after the mapper returns; identity and authorization metadata cannot be asserted by naming an HTTP header.

type MethodConfig 

type MethodConfig struct {
	// MaxUnaryRequestBytes overrides the per-server unary cap. Zero =
	// inherit. Use a positive value for methods that legitimately need
	// large bodies (e.g. an object-store Upload accepting hundreds of
	// MiB) while keeping the rest of the surface tight.
	MaxUnaryRequestBytes int64
	// MaxUnaryResponseBytes overrides the encoded unary HTTP response cap.
	// The selected wire encoding (JSON or protobuf) is measured.
	MaxUnaryResponseBytes int64
	// MaxStreamRequestBytes overrides the per-server Connect-streaming
	// request envelope cap. Zero = inherit.
	MaxStreamRequestBytes int64
	// MaxStreamResponseBytes overrides the encoded Connect response-message
	// cap. It applies independently to each message, like gRPC limits.
	MaxStreamResponseBytes int64
}

MethodConfig overrides per-server defaults for one RPC method. Zero-valued fields fall back to the server-level setting. Apply via `Server.ConfigureMethod("/pkg.Service/Method", MethodConfig{...})`.

Request and response limits are independent because protobuf and JSON wire sizes are not interchangeable.

type OutboundHTTPRequest 

type OutboundHTTPRequest struct {
	MethodPath string // e.g. "/greet.v1.GreetService/Greet"
	Method     string // e.g. "GET", "POST"
	URL        string // fully expanded URL with query string
	Body       []byte // JSON body bytes (may be empty)
}

OutboundHTTPRequest describes an HTTP request that will be sent by ConnectHTTP. It is passed to HTTPHeaderProvider so callers can compute dynamic auth headers.

type Projection 

type Projection struct {
	// contains filtered or unexported fields
}

Projection specifies a protocol to serve.

func CLI 

func CLI() Projection

CLI returns a projection that runs as a CLI from os.Args.

func HTTP 

func HTTP(port int) Projection

HTTP returns a projection that serves HTTP on the given port.

func MCP 

func MCP() Projection

MCP returns a projection that serves MCP over stdio.

type Server 

type Server struct {
	// contains filtered or unexported fields
}

Server holds parsed descriptors and registered tools.

func ServerFromBytes 

func ServerFromBytes(data []byte, grpcOptions ...grpc.ServerOption) (*Server, error)

ServerFromBytes parses an embedded FileDescriptorSet and returns a configured Server.

func ServerFromDescriptor 

func ServerFromDescriptor(path string, grpcOptions ...grpc.ServerOption) (*Server, error)

ServerFromDescriptor reads a descriptor file and returns a configured Server.

func (*Server) ConfigureMethod 

func (s *Server) ConfigureMethod(methodPath string, cfg MethodConfig)

ConfigureMethod registers a per-method override. The method path is the Connect/gRPC URL form — `/pkg.Service/Method`, so callers can copy-paste it from their generated full-method constant or proto schema. Zero-valued fields in `cfg` inherit from the server-level setting; non-zero fields override.

Typical use: a service has one big RPC (Upload, BulkImport) plus lots of small ones; set the server cap tight and raise just the outlier. 

srv, err := invariant.ServerFromBytes(desc)
if err != nil { return err }
srv.SetMaxUnaryRequestBytes(16 * 1024 * 1024)
srv.ConfigureMethod("/files.v1.FileService/Upload", invariant.MethodConfig{
    MaxUnaryRequestBytes: 1 << 30, // 1 GiB
})

Last write wins; re-calling overrides the previous config for that method.

func (*Server) ConnectGRPC 

func (s *Server) ConnectGRPC(conn grpc.ClientConnInterface, defaultCallOptions ...grpc.CallOption) error

ConnectGRPC registers a gRPC client connection's methods as tools. The caller creates and owns the grpc.ClientConnInterface. Default call options are applied to every projected unary call. Use Include/Exclude to filter optional projection tools; the native proxy service retains every supported unary method.

func (*Server) ConnectHTTP 

func (s *Server) ConnectHTTP(baseURL string, serviceName ...string) error

ConnectHTTP registers tools that proxy to a remote HTTP endpoint. Routes are derived from google.api.http annotations when present, otherwise fallback to canonical RPC route: POST /{serviceFullName}/{method}. With no service name it registers every service in the descriptor; one name selects that service, and more than one name is rejected.

func (*Server) Exclude 

func (s *Server) Exclude(patterns ...string)

Exclude adds glob patterns for methods to exclude. Methods matching any exclude pattern are skipped during projection registration. Exclude is applied after include. Patterns use the same syntax as Include.

func (*Server) GRPCServer 

func (s *Server) GRPCServer() *grpc.Server

GRPCServer returns the owned native grpc.Server. Access freezes Invariant registration so serving it directly cannot race projection metadata capture.

func (*Server) GetServiceInfo 

func (s *Server) GetServiceInfo() map[string]grpc.ServiceInfo

func (*Server) GracefulStop 

func (s *Server) GracefulStop()

func (*Server) HTTPHandler 

func (s *Server) HTTPHandler() http.Handler

HTTPHandler returns an http.Handler that serves all registered tools over the Connect protocol. Mount on an existing http.ServeMux or framework router instead of binding a separate port: 

mux := http.NewServeMux()
h := server.HTTPHandler()
mux.Handle("/inv/", http.StripPrefix("/inv", h))

Routes: 

POST /{package.Service}/{Method}      — invoke a tool (Connect protocol)
POST /mcp                            — MCP Streamable HTTP request
GET  /                                — tool catalog (same shape as MCP tools/list)
GET  /__invariant/tools               — tool catalog
GET  /__invariant/descriptor.binpb    — raw FileDescriptorSet bytes
GET  /healthz                         — liveness probe
GET  /readyz                          — readiness probe

func (*Server) Include 

func (s *Server) Include(patterns ...string)

Include adds glob patterns for methods to include. Only methods matching at least one include pattern are registered. Patterns are matched against the fully qualified method path: "service.full.Name.MethodName". Use "*" to match any sequence of characters (including dots). Examples: "temporal.api.workflowservice.v1.WorkflowService.*", "*.StartWorkflow*".

func (*Server) Invoke 

func (s *Server) Invoke(ctx context.Context, toolName string, req proto.Message) (proto.Message, error)

Invoke dispatches a unary request to a registered tool by name. Useful for in-process callers (workflow runtimes, tests) that don't need to spin up a projection.

Returns NOT_FOUND if the tool is unknown, and FAILED_PRECONDITION if the tool is server-streaming — use InvokeStream for those. Both errors project to the right code through every projection.

func (*Server) InvokeStream 

func (s *Server) InvokeStream(ctx context.Context, toolName string, req proto.Message, send func(proto.Message) error) error

InvokeStream dispatches a server-streaming tool by name. Each emitted response message is delivered to send; the call returns once the handler returns or send returns an error.

Like Invoke, this is the in-process entry point — no projection required.

func (*Server) RegisterService 

func (s *Server) RegisterService(desc *grpc.ServiceDesc, impl any)

RegisterService implements grpc.ServiceRegistrar. Generated Register<Service>Server functions can register directly with an Invariant server; the same descriptor and implementation are retained for HTTP, MCP, and CLI projection dispatch.

grpc.ServiceRegistrar cannot return an error, so invalid or late registrations panic with a deterministic invariant-prefixed message, just as generated registration is expected to fail during process setup.

func (*Server) Serve 

func (s *Server) Serve(listener net.Listener) error

Serve runs the native gRPC server on listener.

func (*Server) ServeProjections 

func (s *Server) ServeProjections(ctx context.Context, projections ...Projection) error

ServeProjections starts the specified optional projections and blocks until ctx is canceled or the first projection completes. 

ctx, cancel := signal.NotifyContext(context.Background(), os.Interrupt)
defer cancel()
server.ServeProjections(ctx, invariant.HTTP(8080))
server.ServeProjections(ctx, invariant.HTTP(8080), invariant.MCP())

On error or cancellation, all projections receive a graceful shutdown signal.

func (*Server) SetMaxStreamRequestBytes 

func (s *Server) SetMaxStreamRequestBytes(n int64)

SetMaxStreamRequestBytes overrides the Connect streaming request envelope cap. Pass 0 to reset to the default (16 MiB).

func (*Server) SetMaxStreamResponseBytes 

func (s *Server) SetMaxStreamResponseBytes(n int64)

SetMaxStreamResponseBytes overrides the per-message encoded Connect stream response cap. Pass 0 to reset to the default (16 MiB).

func (*Server) SetMaxUnaryRequestBytes 

func (s *Server) SetMaxUnaryRequestBytes(n int64)

SetMaxUnaryRequestBytes overrides the HTTP unary body-size cap. Pass 0 to reset to the default (16 MiB).

func (*Server) SetMaxUnaryResponseBytes 

func (s *Server) SetMaxUnaryResponseBytes(n int64)

SetMaxUnaryResponseBytes overrides the encoded HTTP unary response cap. Pass 0 to reset to the default (16 MiB).

func (*Server) Stop 

func (s *Server) Stop()

func (*Server) ToolCatalog 

func (s *Server) ToolCatalog() []map[string]any

ToolCatalog returns the canonical tool catalog (same shape as MCP `tools/list`). Used by both the HTTP `GET /` endpoint and MCP's `tools/list`.

Streaming tools carry `_meta.streaming: true` so clients can render and consume them differently from unary tools. The MCP spec reserves `_meta` for exactly this kind of server-specific annotation.

func (*Server) Tools 

func (s *Server) Tools() map[string]*Tool

Tools returns a snapshot of the registered tool names to their Tool metadata.

func (*Server) Use 

func (s *Server) Use(interceptor grpc.UnaryServerInterceptor)

Use registers a unary interceptor. Runs in registration order (first registered = outermost) on every unary tool invocation across all projections. Stream RPCs are not affected — use UseStream for those.

func (*Server) UseHTTPHeaderProvider 

func (s *Server) UseHTTPHeaderProvider(provider HTTPHeaderProvider)

UseHTTPHeaderProvider sets an optional outbound header provider for ConnectHTTP. The current provider is called for every outbound HTTP request. Like other configuration, it may be changed until serving or invocation begins.

func (*Server) UseHTTPMetadataMapper 

func (s *Server) UseHTTPMetadataMapper(mapper HTTPMetadataMapper)

UseHTTPMetadataMapper replaces the inbound HTTP metadata mapper. Reserved protocol, authorization, tenant, principal, role, and internal identity keys are removed from the mapper's result before it reaches application code.

func (*Server) UseStream 

func (s *Server) UseStream(interceptor grpc.StreamServerInterceptor)

UseStream registers a server-streaming interceptor. Mirrors Use but for server-streaming RPCs. Same registration-order semantics.

type Tool 

type Tool struct {
	Name            string
	Description     string
	InputSchema     map[string]any
	InputType       string
	OutputType      string
	ServiceFullName string
	MethodName      string
	ServerStreaming bool
	// contains filtered or unexported fields
}

Tool represents a single registered RPC method projected as a tool.

Source Files

View all Source files

Directories

Path Synopsis
cmd
invariant-openapi command
invariant-openapi performs a one-way import of an OpenAPI document into a reviewable protobuf contract.
 invariant-openapi performs a one-way import of an OpenAPI document into a reviewable protobuf contract.
invariant-schema command
invariant-schema compiles protobuf descriptors into Invariant's canonical data-schema bundle and renders that bundle for storage systems.
 invariant-schema compiles protobuf descriptors into Invariant's canonical data-schema bundle and renders that bundle for storage systems.
Package data compiles protobuf message descriptors into Invariant's language-neutral logical data schema.
 Package data compiles protobuf message descriptors into Invariant's language-neutral logical data schema.
arrow
Package arrow projects Invariant's canonical protobuf data schema into an Apache Arrow schema.
 Package arrow projects Invariant's canonical protobuf data schema into an Apache Arrow schema.
clickhouse
Package clickhouse projects Invariant's canonical protobuf data schema into ClickHouse column and constraint declarations.
 Package clickhouse projects Invariant's canonical protobuf data schema into ClickHouse column and constraint declarations.
iceberg
Package iceberg projects Invariant's canonical protobuf data schema into an official Apache Iceberg schema.
 Package iceberg projects Invariant's canonical protobuf data schema into an official Apache Iceberg schema.
parquet
Package parquet projects Invariant's canonical protobuf data schema into an Apache Parquet schema through Arrow's official pqarrow bridge.
 Package parquet projects Invariant's canonical protobuf data schema into an Apache Parquet schema through Arrow's official pqarrow bridge.
postgres
Package postgres projects Invariant's canonical protobuf data schema into PostgreSQL DDL.
 Package postgres projects Invariant's canonical protobuf data schema into PostgreSQL DDL.
gen
invariant/data/v1
invariant/v1
internal
openapiimport
tests
gen
manual command
MCP/gRPC server entry point for the Invariant Protocol test service (Go).
 MCP/gRPC server entry point for the Invariant Protocol test service (Go).

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.