use std::{
collections::HashMap,
error::Error,
fmt,
path::PathBuf,
sync::{
atomic::{AtomicUsize, Ordering as AtomicOrdering},
Arc, Mutex,
},
time::{Duration, Instant},
};
use serde::{Deserialize, Deserializer, Serialize, Serializer};
use subc_protocol::{BindIdentity, RouteTarget};
use tokio::time::timeout;
use crate::{CallOptions, CloseRouteOptions, RouteHandle, SubcConsumer, SubscribeOptions};
pub const DEFAULT_POLICY_RESOLVER_MODULE_ID: &str = "prefrontal-core";
const POLICY_RESOLVER_HARNESS: &str = "subc-client-rs-policy-resolver";
const POLICY_RESOLVE_OP: &str = "policy.resolve";
const POLICY_REVISION_BUMP_OP: &str = "policy.revision_bump";
const POLICY_SUBSCRIBE_OP: &str = "policy.subscribe";
#[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize)]
pub enum Subject {
#[serde(rename = "agent_id")]
AgentId(String),
#[serde(rename = "session_id")]
SessionToResolve(String),
}
impl Subject {
fn route_session(&self) -> String {
match self {
Self::AgentId(agent_id) => format!("agent:{agent_id}"),
Self::SessionToResolve(session_id) => format!("session:{session_id}"),
}
}
}
#[derive(Debug, Clone, PartialEq, Eq, Hash)]
pub enum PolicyVerdict {
Allow,
Deny,
Ask,
DenyUnknownDomain,
Unknown(String),
}
impl PolicyVerdict {
pub fn as_str(&self) -> &str {
match self {
Self::Allow => "allow",
Self::Deny => "deny",
Self::Ask => "ask",
Self::DenyUnknownDomain => "deny_unknown_domain",
Self::Unknown(value) => value,
}
}
}
impl Serialize for PolicyVerdict {
fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
where
S: Serializer,
{
serializer.serialize_str(self.as_str())
}
}
impl<'de> Deserialize<'de> for PolicyVerdict {
fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
where
D: Deserializer<'de>,
{
let value = String::deserialize(deserializer)?;
Ok(match value.as_str() {
"allow" => Self::Allow,
"deny" => Self::Deny,
"ask" => Self::Ask,
"deny_unknown_domain" => Self::DenyUnknownDomain,
_ => Self::Unknown(value),
})
}
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct PolicyResolverConfig {
pub hard_timeout: Duration,
pub ttl_floor_ms: u64,
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum PolicyResolveError {
Fault { cause: String },
}
impl PolicyResolveError {
fn fault(cause: impl Into<String>) -> Self {
Self::Fault {
cause: cause.into(),
}
}
}
impl fmt::Display for PolicyResolveError {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
match self {
Self::Fault { cause } => write!(f, "policy resolver fault: {cause}"),
}
}
}
impl Error for PolicyResolveError {}
pub struct PolicyResolver {
consumer: std::sync::Arc<SubcConsumer>,
resolver_module_id: String,
config: PolicyResolverConfig,
cache: Arc<Mutex<CacheState>>,
route_gate: tokio::sync::Mutex<()>,
live_subscriptions: Arc<AtomicUsize>,
}
type RouteIdentity = (PathBuf, String);
struct CacheState {
last_known_revision: u64,
entries: HashMap<CacheKey, CacheEntry>,
routes: HashMap<RouteIdentity, RouteState>,
next_sweep_at: Option<Instant>,
next_subscription_id: u64,
}
struct RouteState {
handle: Option<RouteHandle>,
live_until: Instant,
in_flight: usize,
subscription: Option<SubscriptionTask>,
}
struct SubscriptionTask {
id: u64,
handle: RouteHandle,
abort: tokio::task::AbortHandle,
}
impl CacheState {
fn new() -> Self {
Self {
last_known_revision: 0,
entries: HashMap::new(),
routes: HashMap::new(),
next_sweep_at: None,
next_subscription_id: 0,
}
}
fn observe_revision(&mut self, revision: u64) {
if revision > self.last_known_revision {
self.last_known_revision = revision;
self.entries.clear();
}
}
fn schedule_sweep(&mut self, at: Instant) {
self.next_sweep_at = Some(self.next_sweep_at.map_or(at, |next| next.min(at)));
}
fn sweep_due(&self, now: Instant) -> bool {
self.next_sweep_at.is_some_and(|at| at <= now)
}
fn evict_expired(&mut self, now: Instant) -> Vec<RouteHandle> {
self.entries.retain(|_, entry| entry.expires_at > now);
let mut closing = Vec::new();
self.routes.retain(|_, route| {
if route.in_flight > 0 || route.live_until > now {
return true;
}
if let Some(subscription) = route.subscription.take() {
subscription.abort.abort();
}
closing.extend(route.handle);
false
});
self.next_sweep_at = None;
let pending = self
.entries
.values()
.map(|entry| entry.expires_at)
.chain(self.routes.values().map(|route| route.live_until))
.collect::<Vec<_>>();
for at in pending {
self.schedule_sweep(at);
}
closing
}
}
struct InFlight {
cache: Arc<Mutex<CacheState>>,
route: RouteIdentity,
}
impl InFlight {
fn enter(cache: &Arc<Mutex<CacheState>>, route: RouteIdentity) -> Self {
let now = Instant::now();
let mut state = lock(cache);
state
.routes
.entry(route.clone())
.or_insert_with(|| RouteState {
handle: None,
live_until: now,
in_flight: 0,
subscription: None,
})
.in_flight += 1;
Self {
cache: Arc::clone(cache),
route,
}
}
}
impl Drop for InFlight {
fn drop(&mut self) {
let mut state = lock(&self.cache);
let Some(route) = state.routes.get_mut(&self.route) else {
return;
};
route.in_flight -= 1;
if route.in_flight == 0 {
let live_until = route.live_until;
state.schedule_sweep(live_until);
}
}
}
struct LiveSubscription(Arc<AtomicUsize>);
impl Drop for LiveSubscription {
fn drop(&mut self) {
self.0.fetch_sub(1, AtomicOrdering::SeqCst);
}
}
#[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize)]
pub enum ProjectRef {
#[serde(rename = "project_root")]
Root(String),
#[serde(rename = "project_id")]
Id(String),
}
impl ProjectRef {
fn bind_root(&self) -> PathBuf {
match self {
Self::Root(root) => PathBuf::from(root),
Self::Id(_) => PathBuf::from("/"),
}
}
}
#[derive(Clone, PartialEq, Eq, Hash)]
struct CacheKey {
domain: String,
gate_id: String,
subject: Subject,
project: ProjectRef,
}
struct CacheEntry {
verdict: PolicyVerdict,
revision: u64,
expires_at: Instant,
}
#[derive(Serialize)]
struct PolicyResolveRequest<'a> {
method: &'static str,
params: PolicyResolveParams<'a>,
}
#[derive(Serialize)]
struct PolicyResolveParams<'a> {
domain: &'a str,
gate_id: &'a str,
subject: &'a Subject,
#[serde(flatten)]
project: &'a ProjectRef,
}
#[derive(Deserialize)]
struct PolicyResolveEnvelope {
result: PolicyResolveReply,
}
#[derive(Deserialize)]
struct PolicyResolveReply {
verdict: PolicyVerdict,
revision: u64,
ttl_ms: u64,
}
#[derive(Deserialize)]
struct PolicyRevisionBumpBody {
revision: u64,
}
#[derive(Deserialize)]
struct PolicyRevisionBump {
op: String,
body: PolicyRevisionBumpBody,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct PolicyResolverFootprint {
pub entries: usize,
pub routes: usize,
pub subscriptions: usize,
}
impl PolicyResolver {
pub fn new(consumer: SubcConsumer, config: PolicyResolverConfig) -> Self {
Self::with_resolver_target(consumer, DEFAULT_POLICY_RESOLVER_MODULE_ID, config)
}
pub fn with_resolver_target(
consumer: SubcConsumer,
resolver_module_id: impl Into<String>,
config: PolicyResolverConfig,
) -> Self {
Self {
consumer: std::sync::Arc::new(consumer),
resolver_module_id: resolver_module_id.into(),
config,
cache: Arc::new(Mutex::new(CacheState::new())),
route_gate: tokio::sync::Mutex::new(()),
live_subscriptions: Arc::new(AtomicUsize::new(0)),
}
}
pub async fn resolve(
&self,
domain: &str,
gate_id: &str,
subject: Subject,
project: ProjectRef,
) -> Result<PolicyVerdict, PolicyResolveError> {
let key = CacheKey {
domain: domain.to_string(),
gate_id: gate_id.to_string(),
subject: subject.clone(),
project: project.clone(),
};
self.sweep_expired().await;
if let Some(verdict) = self.cached_verdict(&key) {
return Ok(verdict);
}
let route_id: RouteIdentity = (project.bind_root(), subject.route_session());
let _in_flight = InFlight::enter(&self.cache, route_id.clone());
let request = PolicyResolveRequest {
method: POLICY_RESOLVE_OP,
params: PolicyResolveParams {
domain,
gate_id,
subject: &subject,
project: &project,
},
};
let body = serde_json::to_vec(&request)
.map_err(|e| PolicyResolveError::fault(format!("request encode: {e}")))?;
let route_identity = BindIdentity::new(
project.bind_root(),
POLICY_RESOLVER_HARNESS.to_string(),
subject.route_session(),
);
let call_options = CallOptions {
timeout: self.config.hard_timeout,
route_retry_deadline: self.config.hard_timeout,
..CallOptions::default()
};
let wire_call = async {
let gate = self.route_gate.lock().await;
let route = self
.consumer
.open_route(
RouteTarget::ManagementSurface {
module_id: self.resolver_module_id.clone(),
},
route_identity,
call_options.clone(),
)
.await
.map_err(|e| PolicyResolveError::fault(format!("route open: {e}")))?;
drop(gate);
self.install_push_receiver(&route_id, route);
self.consumer
.request(&route, body, call_options)
.await
.map_err(|e| PolicyResolveError::fault(format!("request: {e}")))
};
let response = timeout(self.config.hard_timeout, wire_call)
.await
.map_err(|_| PolicyResolveError::fault("hard timeout elapsed"))??;
let envelope: PolicyResolveEnvelope = serde_json::from_slice(&response)
.map_err(|e| PolicyResolveError::fault(format!("reply envelope: {e}")))?;
let reply = envelope.result;
let ttl = Duration::from_millis(reply.ttl_ms.max(self.config.ttl_floor_ms));
let expires_at = Instant::now()
.checked_add(ttl)
.ok_or_else(|| PolicyResolveError::fault("ttl overflow"))?;
let mut cache = lock(&self.cache);
if reply.revision < cache.last_known_revision {
return Err(PolicyResolveError::fault(
"reply revision regressed below an observed generation",
));
}
cache.observe_revision(reply.revision);
if let Some(route) = cache.routes.get_mut(&route_id) {
route.live_until = route.live_until.max(expires_at);
}
cache.schedule_sweep(expires_at);
cache.entries.insert(
key,
CacheEntry {
verdict: reply.verdict.clone(),
revision: reply.revision,
expires_at,
},
);
Ok(reply.verdict)
}
pub fn footprint(&self) -> PolicyResolverFootprint {
let cache = lock(&self.cache);
PolicyResolverFootprint {
entries: cache.entries.len(),
routes: cache
.routes
.values()
.filter(|route| route.handle.is_some())
.count(),
subscriptions: self.live_subscriptions.load(AtomicOrdering::SeqCst),
}
}
async fn sweep_expired(&self) {
if !lock(&self.cache).sweep_due(Instant::now()) {
return;
}
let _gate = self.route_gate.lock().await;
let closing = lock(&self.cache).evict_expired(Instant::now());
for handle in closing {
let _ = self
.consumer
.close_handle(&handle, CloseRouteOptions::default())
.await;
}
}
fn cached_verdict(&self, key: &CacheKey) -> Option<PolicyVerdict> {
let mut cache = lock(&self.cache);
let entry = cache.entries.get(key)?;
if entry.expires_at > Instant::now() && entry.revision == cache.last_known_revision {
Some(entry.verdict.clone())
} else {
cache.entries.remove(key);
None
}
}
fn install_push_receiver(&self, route_id: &RouteIdentity, route: RouteHandle) {
let mut cache = lock(&self.cache);
let id = cache.next_subscription_id;
let Some(state) = cache.routes.get_mut(route_id) else {
return;
};
state.handle = Some(route);
if let Some(existing) = &state.subscription {
if existing.handle == route {
return;
}
existing.abort.abort();
}
let consumer = std::sync::Arc::clone(&self.consumer);
let task_cache = Arc::clone(&self.cache);
let task_route_id = route_id.clone();
self.live_subscriptions.fetch_add(1, AtomicOrdering::SeqCst);
let live = LiveSubscription(Arc::clone(&self.live_subscriptions));
let body = serde_json::to_vec(&serde_json::json!({
"method": POLICY_SUBSCRIBE_OP,
"params": {},
}))
.expect("static subscribe body serializes");
let task = tokio::spawn(async move {
let _live = live;
match consumer
.subscribe_route(&route, body, SubscribeOptions::default())
.await
{
Ok(mut subscription) => {
drain_revision_bumps(subscription.events(), Arc::clone(&task_cache)).await;
}
Err(_) => {
}
}
let mut cache = lock(&task_cache);
if let Some(state) = cache.routes.get_mut(&task_route_id) {
if state
.subscription
.as_ref()
.is_some_and(|task| task.id == id)
{
state.subscription = None;
}
}
});
state.subscription = Some(SubscriptionTask {
id,
handle: route,
abort: task.abort_handle(),
});
cache.next_subscription_id += 1;
}
}
async fn drain_revision_bumps(
events: &mut tokio::sync::mpsc::Receiver<Vec<u8>>,
cache: Arc<Mutex<CacheState>>,
) {
while let Some(body) = events.recv().await {
let Ok(bump) = serde_json::from_slice::<PolicyRevisionBump>(&body) else {
continue;
};
if bump.op == POLICY_REVISION_BUMP_OP {
lock(&cache).observe_revision(bump.body.revision);
}
}
}
fn lock<T>(mutex: &Mutex<T>) -> std::sync::MutexGuard<'_, T> {
mutex
.lock()
.unwrap_or_else(|poisoned| poisoned.into_inner())
}
#[cfg(test)]
mod tests {
use super::PolicyVerdict;
#[test]
fn unknown_verdict_strings_are_retained_for_forward_compatibility() {
let verdict: PolicyVerdict = serde_json::from_str("\"future_verdict\"").unwrap();
assert_eq!(
verdict,
PolicyVerdict::Unknown("future_verdict".to_string())
);
}
}