Crate sentinel_agent_protocol

Crate sentinel_agent_protocol 

Source
Expand description

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

§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: 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§

grpc
gRPC protocol definitions generated from proto/agent.proto

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
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
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

Enums§

AgentProtocolError
Agent protocol errors
Decision
Agent decision
EventType
Agent event type
HeaderOp
Header modification operation

Constants§

MAX_MESSAGE_SIZE
Maximum message size (10MB)
PROTOCOL_VERSION
Agent protocol version

Traits§

AgentHandler
Trait for implementing agent logic