Crate sentinel_agent_protocol 

Agent protocol for Sentinel 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

• AgentClient: Client for sending events to agents from the proxy
• AgentServer: Server for implementing agent handlers
• AgentHandler: Trait for implementing agent logic
• AgentResponse: Response from agent with decision and mutations

Transports

Two transport options are supported:

Unix Domain Sockets (Default)

Messages are length-prefixed JSON:

• 4-byte big-endian length prefix
• JSON 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)

Example: Client Usage (Unix Socket)

use sentinel_agent_protocol::{AgentClient, EventType, RequestHeadersEvent};

let mut client = AgentClient::unix_socket("my-agent", "/tmp/agent.sock", timeout).await?;
let response = client.send_event(EventType::RequestHeaders, &event).await?;

Example: Client Usage (gRPC)

use sentinel_agent_protocol::{AgentClient, EventType, RequestHeadersEvent};

let mut client = AgentClient::grpc("my-agent", "http://localhost:50051", timeout).await?;
let response = client.send_event(EventType::RequestHeaders, &event).await?;

Example: Client Usage (gRPC with TLS)

use sentinel_agent_protocol::{AgentClient, GrpcTlsConfig, EventType, RequestHeadersEvent};

// Simple TLS (server verification only)
let tls_config = GrpcTlsConfig::new()
    .with_ca_cert_file("/etc/sentinel/certs/ca.crt").await?;

let mut client = AgentClient::grpc_tls(
    "my-agent",
    "https://agent.internal:50051",
    timeout,
    tls_config
).await?;

// mTLS (mutual authentication)
let tls_config = GrpcTlsConfig::new()
    .with_ca_cert_file("/etc/sentinel/certs/ca.crt").await?
    .with_client_cert_files(
        "/etc/sentinel/certs/client.crt",
        "/etc/sentinel/certs/client.key"
    ).await?;

let mut client = AgentClient::grpc_tls("my-agent", "https://agent.internal:50051", timeout, tls_config).await?;

Example: Client Usage (HTTP REST)

use sentinel_agent_protocol::{AgentClient, HttpTlsConfig, EventType, RequestHeadersEvent};

// Plain HTTP
let mut client = AgentClient::http("my-agent", "http://localhost:8080/agent", timeout).await?;
let response = client.send_event(EventType::RequestHeaders, &event).await?;

// HTTPS with TLS
let tls_config = HttpTlsConfig::new()
    .with_ca_cert_file("/etc/sentinel/certs/ca.crt").await?;

let mut client = AgentClient::http_tls(
    "my-agent",
    "https://agent.internal:8443/agent",
    timeout,
    tls_config
).await?;

Example: Server Implementation

use sentinel_agent_protocol::{AgentServer, AgentHandler, AgentResponse};

struct MyAgent;

#[async_trait]
impl AgentHandler for MyAgent {
    async fn on_request_headers(&self, event: RequestHeadersEvent) -> AgentResponse {
        // Implement your logic here
        AgentResponse::default_allow()
    }
}

let server = AgentServer::new("my-agent", "/tmp/agent.sock", Box::new(MyAgent));
server.run().await?;

Modules

binary

Binary protocol for Unix Domain Socket transport.

buffer_pool

Buffer pooling for message serialization/deserialization.

grpc

gRPC protocol definitions generated from proto/agent.proto

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

AgentClient

Agent client for communicating with external agents

AgentRequest

Agent request message

AgentResponse

Agent response message

AgentServer

Agent server for testing and reference implementations

AuditMetadata

Audit metadata from agent

BinaryRequestBodyChunkEvent

Binary request body chunk event.

BinaryResponseBodyChunkEvent

Binary response body chunk event.

BodyMutation

Body mutation from agent

ConfigureEvent

Configure event

DenylistAgent

Reference implementation: Denylist agent

EchoAgent

Reference implementation: Echo agent (for testing)

GrpcAgentHandler

Internal handler that implements the gRPC AgentProcessor trait

GrpcAgentServer

gRPC agent server for implementing external agents

GrpcTlsConfig

TLS configuration for gRPC agent connections

GuardrailDetection

A single guardrail detection (prompt injection attempt, PII instance, etc.)

GuardrailInspectEvent

Guardrail inspection event

GuardrailResponse

Guardrail inspection response from agent

HttpTlsConfig

TLS configuration for HTTP agent connections

RequestBodyChunkEvent

Request body chunk event

RequestCompleteEvent

Request complete event (for logging/audit)

RequestHeadersEvent

Request headers event

RequestMetadata

Request metadata sent to agents

ResponseBodyChunkEvent

Response body chunk event

ResponseHeadersEvent

Response headers event

TextSpan

Text span indicating location in content

WebSocketFrameEvent

WebSocket frame event

Enums

AgentProtocolError

Agent protocol errors

Decision

Agent decision

DetectionSeverity

Severity level for guardrail detections

EventType

Agent event type

GuardrailInspectionType

Type of guardrail inspection to perform

HeaderOp

Header modification operation

WebSocketDecision

WebSocket frame decision

WebSocketOpcode

WebSocket opcode

Constants

MAX_MESSAGE_SIZE

Maximum message size (10MB)

PROTOCOL_VERSION

Agent protocol version

Traits

AgentHandler

Trait for implementing agent logic