Expand description
Agent protocol for Grapsus proxy
This crate defines the protocol for communication between the proxy dataplane and external processing agents (WAF, auth, rate limiting, custom logic).
The protocol is inspired by SPOE (Stream Processing Offload Engine) and Envoy’s ext_proc, designed for bounded, predictable behavior with strong failure isolation.
§Architecture
AgentHandlerV2: Trait for implementing agent logicAgentResponse: Response from agent with decision and mutationsAgentClientV2: Client for sending events to agents from the proxyGrpcAgentServerV2: gRPC server for agentsUdsAgentServerV2: UDS server for agents
§Transports
Two transport options are supported:
§Unix Domain Sockets (Default)
Messages are length-prefixed with negotiated encoding (JSON or MessagePack):
- 4-byte big-endian length prefix
- Encoded payload (max 10MB)
§gRPC
Binary protocol using Protocol Buffers over HTTP/2:
- Better performance for high-throughput scenarios
- Native support for TLS/mTLS
- Language-agnostic (agents can be written in any language with gRPC support)
Modules§
- binary
- Binary protocol for Unix Domain Socket transport.
- buffer_
pool - Buffer pooling for message serialization/deserialization.
- grpc_v2
- gRPC v2 protocol definitions generated from proto/agent_v2.proto
- headers
- Zero-copy header types for efficient header processing.
- v2
- Protocol v2 types with bidirectional streaming, capabilities, and flow control Protocol v2 types for Agent Protocol 2.0
Structs§
- Agent
Response - Agent response message
- Audit
Metadata - Audit metadata from agent
- Binary
Request Body Chunk Event - Binary request body chunk event.
- Binary
Response Body Chunk Event - Binary response body chunk event.
- Body
Mutation - Body mutation from agent
- Guardrail
Detection - A single guardrail detection (prompt injection attempt, PII instance, etc.)
- Guardrail
Inspect Event - Guardrail inspection event
- Guardrail
Response - Guardrail inspection response from agent
- Request
Body Chunk Event - Request body chunk event
- Request
Complete Event - Request complete event (for logging/audit)
- Request
Headers Event - Request headers event
- Request
Metadata - Request metadata sent to agents
- Response
Body Chunk Event - Response body chunk event
- Response
Headers Event - Response headers event
- Text
Span - Text span indicating location in content
- WebSocket
Frame Event - WebSocket frame event
Enums§
- Agent
Protocol Error - Agent protocol errors
- Decision
- Agent decision
- Detection
Severity - Severity level for guardrail detections
- Event
Type - Agent event type
- Guardrail
Inspection Type - Type of guardrail inspection to perform
- Header
Op - Header modification operation
- WebSocket
Decision - WebSocket frame decision
- WebSocket
Opcode - WebSocket opcode
Constants§
- MAX_
MESSAGE_ SIZE - Maximum message size for gRPC transport (10MB)