Documentation
¶
Overview ¶
Package envoy implements Envoy ext_authz (HTTP and gRPC v3/v2) and ext_proc (gRPC v3 gateway server and outbound inspection callout client) using official google.golang.org/grpc and envoyproxy/go-control-plane bindings.
Index ¶
- Constants
- func ApplyModeOverride(dst, override *extprocv3http.ProcessingMode)
- func ApplySafeHeaderMutations(h http.Header, mut *extprocv3.HeaderMutation)
- func HTTPRequestToProtoHeaders(r *http.Request, destName string) *corev3.HeaderMap
- func HTTPResponseToProtoHeaders(status int, h http.Header) *corev3.HeaderMap
- func InitialProcessingMode(cfg *api.ExtProc) *extprocv3http.ProcessingMode
- func InspectJSONRPCMCPBody(body []byte) (mcpTool string, allowStreamInit bool)
- func InspectMCPHTTPRequestBody(r *http.Request) (string, bool, error)
- func IsProtectedEgressHeader(name string) bool
- type CalloutClient
- func (c *CalloutClient) Close() error
- func (c *CalloutClient) OpenStream(ctx context.Context, cfg *api.ExtProc, timeout time.Duration) (*CalloutSession, error)
- func (c *CalloutClient) RunRequestPhase(r *http.Request, cfg *api.ExtProc, destName string, reqBody []byte, ...) (*CalloutSession, *extprocv3.ImmediateResponse, []byte, error)
- type CalloutSession
- func (s *CalloutSession) Close()
- func (s *CalloutSession) CloseSend() error
- func (s *CalloutSession) NeedsResponseBuffer() bool
- func (s *CalloutSession) Recv(timeout time.Duration) (*extprocv3.ProcessingResponse, error)
- func (s *CalloutSession) RunResponsePhase(status int, respHeader http.Header, respBody []byte) (*extprocv3.ImmediateResponse, []byte, error)
- func (s *CalloutSession) Send(req *extprocv3.ProcessingRequest) error
- type CheckInput
- type CheckResult
- type Evaluator
- type GatewayServer
- func (s *GatewayServer) Check(ctx context.Context, req *authv3.CheckRequest) (*authv3.CheckResponse, error)
- func (s *GatewayServer) HandleExtAuthzHTTP(w http.ResponseWriter, r *http.Request)
- func (s *GatewayServer) Process(stream extprocv3.ExternalProcessor_ProcessServer) error
- func (s *GatewayServer) RegisterRoutes(mux *http.ServeMux)
- func (s *GatewayServer) ServeGRPC(w http.ResponseWriter, r *http.Request)
Constants ¶
const ( // DefaultMessageTimeout is the default per-phase gRPC message timeout for ext_proc callouts. DefaultMessageTimeout = 200 * time.Millisecond // DefaultMaxBufferBytes is the default body buffer cap for ext_proc callouts (1 MiB). DefaultMaxBufferBytes = 1 << 20 )
const ( // HeaderMeshMCPTool lets an external proxy (or ext_proc filter) pass the // extracted MCP tool name during an ext_authz check. HeaderMeshMCPTool = "X-Mesh-Mcp-Tool" // ExtProcMethodPath is the gRPC HTTP/2 path for Envoy ExternalProcessor.Process. ExtProcMethodPath = "/envoy.service.ext_proc.v3.ExternalProcessor/Process" // ExtAuthzV3MethodPath is the gRPC HTTP/2 path for Envoy v3 Authorization.Check. ExtAuthzV3MethodPath = "/envoy.service.auth.v3.Authorization/Check" // ExtAuthzV2MethodPath is the gRPC HTTP/2 path for Envoy v2 Authorization.Check. ExtAuthzV2MethodPath = "/envoy.service.auth.v2.Authorization/Check" // MaxGRPCMessageBytes caps gRPC message sizes for ext_authz and ext_proc (16 MiB). MaxGRPCMessageBytes = 16 << 20 // MaxHTTPBodyBytes caps HTTP ext_authz request bodies read into memory (1 MiB). MaxHTTPBodyBytes = 1 << 20 )
Variables ¶
This section is empty.
Functions ¶
func ApplyModeOverride ¶
func ApplyModeOverride(dst, override *extprocv3http.ProcessingMode)
ApplyModeOverride merges a callout server's ModeOverride into dst.
func ApplySafeHeaderMutations ¶
func ApplySafeHeaderMutations(h http.Header, mut *extprocv3.HeaderMutation)
ApplySafeHeaderMutations applies non-protected header mutations from mut to h.
func HTTPRequestToProtoHeaders ¶
HTTPRequestToProtoHeaders converts an outbound HTTP request into an Envoy HeaderMap with protected headers stripped.
func HTTPResponseToProtoHeaders ¶
HTTPResponseToProtoHeaders converts an HTTP response status and header map into an Envoy HeaderMap.
func InitialProcessingMode ¶
func InitialProcessingMode(cfg *api.ExtProc) *extprocv3http.ProcessingMode
InitialProcessingMode converts an api.ExtProc configuration into Envoy's extprocv3http.ProcessingMode.
func InspectJSONRPCMCPBody ¶
InspectJSONRPCMCPBody inspects a JSON-RPC 2.0 request body for MCP methods ("initialize", "ping", "tools/list", "tools/call") and extracts the bare tool name when present.
func InspectMCPHTTPRequestBody ¶
InspectMCPHTTPRequestBody buffers and restores r.Body up to MaxGRPCMessageBytes and extracts the MCP tool name and stream initialization flag.
func IsProtectedEgressHeader ¶
IsProtectedEgressHeader reports whether a header name is off-limits to an ext_proc inspector. Inspectors may add/modify application headers, or block a request, but must never select or overwrite credentials, host routing, or Agent Mesh identity headers.
Types ¶
type CalloutClient ¶
type CalloutClient struct {
// contains filtered or unexported fields
}
CalloutClient manages a google.golang.org/grpc client connection to an external Envoy ExternalProcessor service over unix domain sockets, h2c, or TLS/mTLS.
func NewCalloutClient ¶
func NewCalloutClient(cfg *api.ExtProc, secretsDir string) (*CalloutClient, error)
NewCalloutClient constructs a CalloutClient for cfg using google.golang.org/grpc.
func (*CalloutClient) Close ¶
func (c *CalloutClient) Close() error
Close closes the underlying gRPC ClientConn.
func (*CalloutClient) OpenStream ¶
func (c *CalloutClient) OpenStream(ctx context.Context, cfg *api.ExtProc, timeout time.Duration) (*CalloutSession, error)
OpenStream opens a new bidirectional Process stream with a stream-level deadline derived from timeout.
func (*CalloutClient) RunRequestPhase ¶
func (c *CalloutClient) RunRequestPhase( r *http.Request, cfg *api.ExtProc, destName string, reqBody []byte, attrs map[string]*structpb.Struct, ) (*CalloutSession, *extprocv3.ImmediateResponse, []byte, error)
RunRequestPhase executes the request headers and optional request body phases on a new CalloutSession.
type CalloutSession ¶
type CalloutSession struct {
// contains filtered or unexported fields
}
CalloutSession represents an active bidirectional ExternalProcessor.Process stream spanning request and optional response inspection phases.
func (*CalloutSession) Close ¶
func (s *CalloutSession) Close()
Close cancels and tears down the bidirectional stream.
func (*CalloutSession) CloseSend ¶
func (s *CalloutSession) CloseSend() error
CloseSend half-closes the client-to-server direction of the stream.
func (*CalloutSession) NeedsResponseBuffer ¶
func (s *CalloutSession) NeedsResponseBuffer() bool
NeedsResponseBuffer reports whether the session's current ProcessingMode requires buffering and inspecting upstream response headers or body.
func (*CalloutSession) Recv ¶
func (s *CalloutSession) Recv(timeout time.Duration) (*extprocv3.ProcessingResponse, error)
Recv waits for the next ProcessingResponse up to timeout (or the session's configured message_timeout if timeout <= 0).
func (*CalloutSession) RunResponsePhase ¶
func (s *CalloutSession) RunResponsePhase( status int, respHeader http.Header, respBody []byte, ) (*extprocv3.ImmediateResponse, []byte, error)
RunResponsePhase executes the response headers and optional response body phases on an active CalloutSession.
func (*CalloutSession) Send ¶
func (s *CalloutSession) Send(req *extprocv3.ProcessingRequest) error
Send transmits a ProcessingRequest on the stream.
type CheckInput ¶
type CheckInput struct {
Method string
Path string
Host string
Headers map[string]string
Body []byte
AllowMCPStreamInit bool
}
CheckInput represents a normalized authorization check request from Envoy HTTP ext_authz, gRPC ext_authz, or gRPC ext_proc.
type CheckResult ¶
type CheckResult struct {
Allowed bool
HTTPStatus int
Message string
ResponseHeaders map[string]string
}
CheckResult represents the policy decision and header mutations returned by an Evaluator for an ext_authz or ext_proc check.
type Evaluator ¶
type Evaluator func(ctx context.Context, in CheckInput) CheckResult
Evaluator evaluates a normalized CheckInput against Agent Mesh's Datalog and TAR policy.
type GatewayServer ¶
type GatewayServer struct {
authv3.UnimplementedAuthorizationServer
extprocv3.UnimplementedExternalProcessorServer
// contains filtered or unexported fields
}
GatewayServer serves Envoy HTTP ext_authz, gRPC ext_authz (v3 and v2), and gRPC ext_proc over standard net/http and google.golang.org/grpc.
func NewGatewayServer ¶
func NewGatewayServer(eval Evaluator) *GatewayServer
NewGatewayServer constructs a GatewayServer backed by a google.golang.org/grpc server registered for both AuthorizationServer and ExternalProcessorServer.
func (*GatewayServer) Check ¶
func (s *GatewayServer) Check(ctx context.Context, req *authv3.CheckRequest) (*authv3.CheckResponse, error)
Check implements envoy.service.auth.v3.AuthorizationServer.
func (*GatewayServer) HandleExtAuthzHTTP ¶
func (s *GatewayServer) HandleExtAuthzHTTP(w http.ResponseWriter, r *http.Request)
HandleExtAuthzHTTP implements Envoy's HTTP ext_authz check service on /ext_authz and /ext_authz/*.
func (*GatewayServer) Process ¶
func (s *GatewayServer) Process(stream extprocv3.ExternalProcessor_ProcessServer) error
Process implements envoy.service.ext_proc.v3.ExternalProcessorServer.
func (*GatewayServer) RegisterRoutes ¶
func (s *GatewayServer) RegisterRoutes(mux *http.ServeMux)
RegisterRoutes mounts the HTTP ext_authz, gRPC ext_authz (v3/v2), and gRPC ext_proc endpoints onto mux.
func (*GatewayServer) ServeGRPC ¶
func (s *GatewayServer) ServeGRPC(w http.ResponseWriter, r *http.Request)
ServeGRPC dispatches an incoming HTTP/2 gRPC request to the underlying google.golang.org/grpc server, normalizing Envoy v2 ext_authz paths to v3.
Source Files