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

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