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

§Protocol

Messages are length-prefixed JSON over Unix domain sockets:

  • 4-byte big-endian length prefix
  • JSON payload (max 10MB)

§Example: Client Usage

ⓘ
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: 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?;

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