use std::sync::{Arc, Mutex, MutexGuard};
use lgwks_deps::rusqlite::{self, Connection, ErrorCode, params};
use lgwks_deps::sqlite::{SqliteError, migrate};
use lgwks_macros::Error;
use super::ensure;
use super::pattern::glob_match;
use super::protocol::{Attribution, AttributionKind, GovernanceEntry};
use super::time::{MAX_WINDOW_MILLIS, parse_millis};
mod snapshot;
pub use snapshot::GovernanceEntrySnapshot;
pub const MAX_RECENT_ROWS: usize = 10_000;
const SIGNED_TOP: u64 = u64::MAX.wrapping_shr(1);
const SCHEMA_VERSION: u32 = 1;
#[derive(Clone, Debug, PartialEq, Eq, Error)]
#[non_exhaustive]
pub enum GovernanceError {
#[error("duplicate governance entry: {0}")]
Duplicate(String),
#[error("unbounded governance query")]
Unbounded,
#[error("malformed governance entry: {0}")]
MalformedEntry(String),
#[error("governance store failed: {0}")]
Store(String),
#[error("unknown attribution source: {0}")]
UnknownAttribution(String),
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[non_exhaustive]
pub enum AttributionSource {
User,
Widget,
Ml,
System,
}
impl AttributionSource {
pub fn resolve(from: &str) -> Result<Self, GovernanceError> {
match from {
"ml" => Ok(Self::Ml),
"user" | "user_intent" => Ok(Self::User),
"widget" => Ok(Self::Widget),
"system" => Ok(Self::System),
other => Err(GovernanceError::UnknownAttribution(String::from(other))),
}
}
#[must_use]
pub const fn raw_value(self) -> &'static str {
match self {
Self::User => "user",
Self::Widget => "widget",
Self::Ml => "ml",
Self::System => "system",
}
}
}
#[derive(Debug, Clone, PartialEq, Eq)]
#[non_exhaustive]
pub struct GovernanceQuery {
tenant_id: String,
session_id: String,
from_ms: u64,
to_ms: u64,
attribution_filter: Option<AttributionSource>,
kind_glob: Option<String>,
}
impl GovernanceQuery {
pub fn new(
tenant_id: String,
session_id: String,
from_ms: u64,
to_ms: u64,
attribution_filter: Option<AttributionSource>,
kind_glob: Option<String>,
) -> Result<Self, GovernanceError> {
ensure(!tenant_id.is_empty() && !session_id.is_empty(), || {
GovernanceError::Unbounded
})?;
let window = to_ms
.checked_sub(from_ms)
.ok_or(GovernanceError::Unbounded)?;
ensure(window <= MAX_WINDOW_MILLIS, || GovernanceError::Unbounded)?;
Ok(Self {
tenant_id,
session_id,
from_ms,
to_ms,
attribution_filter,
kind_glob,
})
}
#[must_use]
pub fn tenant_id(&self) -> &str {
&self.tenant_id
}
#[must_use]
pub fn session_id(&self) -> &str {
&self.session_id
}
#[must_use]
pub const fn from_ms(&self) -> u64 {
self.from_ms
}
#[must_use]
pub const fn to_ms(&self) -> u64 {
self.to_ms
}
#[must_use]
pub const fn attribution_filter(&self) -> Option<AttributionSource> {
self.attribution_filter
}
#[must_use]
pub const fn kind_glob(&self) -> Option<&String> {
self.kind_glob.as_ref()
}
}
#[derive(Debug, Clone)]
pub struct GovernanceStore {
inner: Arc<Mutex<Connection>>,
}
impl GovernanceStore {
pub fn open_in_memory() -> Result<Self, GovernanceError> {
let connection = Connection::open_in_memory()
.map_err(|error| GovernanceError::Store(format!("{error}")))?;
Self::with_connection(connection)
}
pub fn open(path: &std::path::Path) -> Result<Self, GovernanceError> {
let connection =
Connection::open(path).map_err(|error| GovernanceError::Store(format!("{error}")))?;
Self::with_connection(connection)
}
fn with_connection(connection: Connection) -> Result<Self, GovernanceError> {
let store = Self {
inner: Arc::new(Mutex::new(connection)),
};
store.install_schema()?;
Ok(store)
}
fn lock(&self) -> MutexGuard<'_, Connection> {
match self.inner.lock() {
Ok(guard) => guard,
Err(poisoned) => poisoned.into_inner(),
}
}
fn install_schema(&self) -> Result<(), GovernanceError> {
let connection = self.lock();
migrate(&connection, SCHEMA_VERSION, &MIGRATIONS)
.map(|_version| ())
.map_err(migration_error)
}
pub fn append(&self, entry: &GovernanceEntry) -> Result<(), GovernanceError> {
self.append_with_policy(entry, String::new())
}
pub fn append_with_policy(
&self,
entry: &GovernanceEntry,
policy_bundle_id: String,
) -> Result<(), GovernanceError> {
ensure(!entry.signal_id().is_empty(), || {
GovernanceError::MalformedEntry(String::from("signalId must not be empty"))
})?;
ensure(!entry.tenant_id().is_empty(), || {
GovernanceError::MalformedEntry(String::from("tenantId must not be empty"))
})?;
let timestamp_ms = parse_millis(entry.recorded_at()).map_err(|error| {
GovernanceError::MalformedEntry(format!(
"unparseable recordedAt {}: {error}",
entry.recorded_at()
))
})?;
let attribution = AttributionSource::resolve(attribution_kind_raw(entry.attribution()))?;
let timestamp = i64::try_from(timestamp_ms).map_err(|error| {
GovernanceError::MalformedEntry(format!(
"recordedAt out of range {}: {error}",
entry.recorded_at()
))
})?;
let result = self.lock().execute(
"INSERT INTO governance_entries
(signal_id, session_id, source_kind, kind, attribution,
timestamp_ms, recorded_at, policy_bundle_id, work_object_id, tenant_id)
VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9, ?10)",
params![
entry.signal_id(),
entry.session_id(),
attribution_kind_raw(entry.attribution()),
entry.event_type(),
attribution.raw_value(),
timestamp,
entry.recorded_at(),
policy_bundle_id,
entry.work_object_id(),
entry.tenant_id(),
],
);
match result {
Ok(_) => Ok(()),
Err(rusqlite::Error::SqliteFailure(failure, _))
if failure.code == ErrorCode::ConstraintViolation =>
{
Err(GovernanceError::Duplicate(entry.signal_id().to_owned()))
}
Err(error) => Err(GovernanceError::Store(format!("{error}"))),
}
}
pub fn query(
&self,
query: &GovernanceQuery,
) -> Result<Vec<GovernanceEntrySnapshot>, GovernanceError> {
let rows = self.fetch(query, false, -1)?;
match query.kind_glob.as_ref() {
None => Ok(rows),
Some(glob) => Ok(rows
.into_iter()
.filter(|snapshot| glob_match(glob, snapshot.kind()))
.collect()),
}
}
pub fn recent(
&self,
query: &GovernanceQuery,
limit: usize,
) -> Result<Vec<GovernanceEntrySnapshot>, GovernanceError> {
let limit = limit.min(MAX_RECENT_ROWS);
if query.kind_glob.is_some() {
let matched = self.query(query)?;
let skip = matched.len().saturating_sub(limit);
return Ok(matched.into_iter().skip(skip).collect());
}
let bound =
i64::try_from(limit).map_err(|error| GovernanceError::Store(format!("{error}")))?;
let mut newest = self.fetch(query, true, bound)?;
newest.reverse();
Ok(newest)
}
fn fetch(
&self,
query: &GovernanceQuery,
newest_first: bool,
limit: i64,
) -> Result<Vec<GovernanceEntrySnapshot>, GovernanceError> {
let Ok(from) = i64::try_from(query.from_ms) else {
return Ok(Vec::new());
};
let to = i64::try_from(query.to_ms.min(SIGNED_TOP))
.map_err(|error| GovernanceError::Store(format!("{error}")))?;
let direction = if newest_first { "DESC" } else { "ASC" };
let sql = format!(
"SELECT signal_id, session_id, source_kind, kind, attribution,
timestamp_ms, recorded_at, policy_bundle_id, work_object_id
FROM governance_entries
WHERE tenant_id = ?1 AND session_id = ?2
AND timestamp_ms >= ?3 AND timestamp_ms <= ?4
AND (?5 IS NULL OR attribution = ?5)
ORDER BY timestamp_ms {direction}, rowid {direction}
LIMIT ?6"
);
let filter = query.attribution_filter.map(AttributionSource::raw_value);
self.select(
&sql,
params![query.tenant_id, query.session_id, from, to, filter, limit],
)
}
fn select(
&self,
sql: &str,
params: &[&dyn rusqlite::ToSql],
) -> Result<Vec<GovernanceEntrySnapshot>, GovernanceError> {
let connection = self.lock();
let mut statement = connection
.prepare(sql)
.map_err(|error| GovernanceError::Store(format!("{error}")))?;
let rows = statement
.query_map(params, |row| {
let timestamp: i64 = row.get(5)?;
let timestamp_ms = u64::try_from(timestamp).map_err(|error| {
rusqlite::Error::FromSqlConversionFailure(
5,
rusqlite::types::Type::Integer,
Box::new(error),
)
})?;
let mut snapshot = GovernanceEntrySnapshot::new(
row.get(1)?,
row.get(0)?,
row.get(2)?,
row.get(3)?,
row.get(4)?,
timestamp_ms,
row.get(6)?,
);
snapshot.set_policy_bundle_id(row.get(7)?);
snapshot.set_work_object_id(row.get(8)?);
Ok(snapshot)
})
.map_err(|error| GovernanceError::Store(format!("{error}")))?;
let mut snapshots = Vec::new();
for row in rows {
snapshots.push(row.map_err(|error| GovernanceError::Store(format!("{error}")))?);
}
Ok(snapshots)
}
pub fn count(&self, tenant_id: &str, session_id: &str) -> Result<u64, GovernanceError> {
let count: i64 = self
.lock()
.query_row(
"SELECT COUNT(*) FROM governance_entries
WHERE tenant_id = ?1 AND session_id = ?2",
params![tenant_id, session_id],
|row| row.get(0),
)
.map_err(|error| GovernanceError::Store(format!("{error}")))?;
u64::try_from(count).map_err(|error| GovernanceError::Store(format!("{error}")))
}
}
const MIGRATION_V1: &str = "DROP INDEX IF EXISTS idx_governance_scope_time;
CREATE TABLE IF NOT EXISTS governance_entries (
signal_id TEXT NOT NULL PRIMARY KEY,
tenant_id TEXT NOT NULL,
session_id TEXT NOT NULL,
source_kind TEXT NOT NULL,
kind TEXT NOT NULL,
attribution TEXT NOT NULL,
timestamp_ms INTEGER NOT NULL,
recorded_at TEXT NOT NULL,
policy_bundle_id TEXT NOT NULL,
work_object_id TEXT NOT NULL
);
ALTER TABLE governance_entries RENAME TO governance_entries_legacy;
CREATE TABLE governance_entries (
signal_id TEXT NOT NULL,
tenant_id TEXT NOT NULL,
session_id TEXT NOT NULL,
source_kind TEXT NOT NULL,
kind TEXT NOT NULL,
attribution TEXT NOT NULL,
timestamp_ms INTEGER NOT NULL,
recorded_at TEXT NOT NULL,
policy_bundle_id TEXT NOT NULL,
work_object_id TEXT NOT NULL,
PRIMARY KEY (tenant_id, signal_id)
);
CREATE INDEX idx_governance_scope_time
ON governance_entries (tenant_id, session_id, timestamp_ms);
INSERT INTO governance_entries
(signal_id, tenant_id, session_id, source_kind, kind, attribution,
timestamp_ms, recorded_at, policy_bundle_id, work_object_id)
SELECT signal_id, tenant_id, session_id, source_kind, kind, attribution,
timestamp_ms, recorded_at, policy_bundle_id, work_object_id
FROM governance_entries_legacy ORDER BY rowid;
DROP TABLE governance_entries_legacy;";
const MIGRATIONS: [&str; 1] = [MIGRATION_V1];
fn migration_error(error: SqliteError) -> GovernanceError {
match error {
SqliteError::Downgrade { found, wanted } => GovernanceError::Store(format!(
"governance schema version {found} is newer than this build's {wanted}"
)),
other => GovernanceError::Store(format!("{other}")),
}
}
fn attribution_kind_raw(attribution: &Attribution) -> &'static str {
match attribution.kind() {
AttributionKind::User => "user",
AttributionKind::Widget => "widget",
AttributionKind::Ml => "ml",
AttributionKind::System => "system",
}
}