The fastest, cheapest, most efficient open-source agent harness. Run more than 500 agents on a $10 VPS.
Rust agent-orchestrationai-agentsai-assistantdesktopllmlocal-firstmcppersonal-aiprivacyrustsecond-braintauri
refactor(storage): introduce structured scope representation
Steven Enamakelb0c5f92f4ee7
diff --git a/crates/openhuman-core/src/storage/mod.rs b/crates/openhuman-core/src/storage/mod.rsindex bfa7c6a363..4ef7ee9d8a 100644--- a/crates/openhuman-core/src/storage/mod.rs+++ b/crates/openhuman-core/src/storage/mod.rs@@ -49,7 +49,10 @@ pub mod secrets;pub mod sessions;pub mod state_kv;-pub use scope::{scope_for_agent, scope_for_module, scope_for_profile, tenant_scope};+pub use scope::{+ scope_for_agent, scope_for_module, scope_for_profile, tenant_scope, ParsedScope, Principal,+ Scope, Tenant,+};use std::future::Future;use std::sync::{Arc, LazyLock, Mutex, OnceLock, RwLock};@@ -67,7 +70,7 @@ use std::sync::{Arc, LazyLock, Mutex, OnceLock, RwLock};/// consumers are still present, so it stays.pub use tinystoragedrivers::sqlite::rusqlite;pub use tinystoragedrivers::{- Blocking, CollectionSpec, DocumentStore, DocumentStoreExt, MemoryStorage, Precondition, Scope,+ Blocking, CollectionSpec, DocumentStore, DocumentStoreExt, MemoryStorage, Precondition,ScopedStorage, StorageBackend, StorageConfig as StorageUrl, StorageError,};diff --git a/crates/openhuman-core/src/storage/scope.rs b/crates/openhuman-core/src/storage/scope.rsindex 823e164230..2cc8bde84d 100644--- a/crates/openhuman-core/src/storage/scope.rs+++ b/crates/openhuman-core/src/storage/scope.rs@@ -1,18 +1,237 @@-//! The one scope grammar every domain store addresses its records by.+//! OpenHuman's tenant and principal scope grammar on top of TSD's opaque scope.//!-//! The grammar is tinystoragedrivers' (`Scope::tenant`, `Scope::local`,-//! `.agent(id)`, `.module(id)`): a tenant (`local` for the desktop operator,-//! `u:<profile>` for a SaaS profile) optionally narrowed to one principal-//! (`<tenant>/agent:<id>` or `<tenant>/module:<id>`). The tenant is the fence-//! and purge boundary, so every helper here derives the principal scope from-//! the tenant scope and never from a raw string. A segment that is too long or-//! holds characters outside the grammar is hashed by tsd itself.-//!-//! The v1 shapes these replace (`profile:<id>`, `<profile>~<agent>`, a raw-//! agent id, `module:<id>@<base>`, the `*-sha256:` fallbacks) are only ever-//! parsed by the one-time scope move ([`super::scope_move`]).+//! The host keeps its established `local`, `u:<profile>`, `/agent:<id>` and+//! `/module:<id>` identifiers. TSD stores these values without interpreting+//! their grammar; this module validates and encodes host-owned identifiers.+//! Invalid or oversized identity segments use the same stable SHA-256/base32+//! representation as the previous scope implementation.++use std::ops::Deref;++use serde::{Deserialize, Serialize};+use sha2::{Digest, Sha256};-use super::Scope;+use super::StorageError;++const USER_PREFIX: &str = "u:";+const AGENT_INFIX: &str = "/agent:";+const MODULE_INFIX: &str = "/module:";+const CLUSTER: &str = "cluster";+const MAX_SCOPE_SEGMENT_LEN: usize = 96;+const MAX_HASH_SEGMENT_LEN: usize = 26;+const BASE32_LOWER: &[u8; 32] = b"abcdefghijklmnopqrstuvwxyz234567";++/// A host scope whose opaque storage value is passed to TSD ports.+///+/// The wrapper keeps OpenHuman's scope constructors and parser separate from+/// the driver's opaque identifier type. `Deref` makes the contained TSD scope+/// usable directly with `StorageBackend::for_scope`.+#[derive(Debug, Clone, PartialEq, Eq, Hash, PartialOrd, Ord, Serialize, Deserialize)]+#[serde(transparent)]+pub struct Scope(tinystoragedrivers::Scope);++impl Scope {+ /// Creates an opaque scope value without requiring it to follow the host+ /// grammar. This is used while reading legacy scopes before migration.+ pub fn new(value: impl AsRef<str>) -> Result<Self, StorageError> {+ tinystoragedrivers::Scope::new(value).map(Self)+ }++ /// The host's single-operator tenant scope.+ #[must_use]+ pub fn local() -> Self {+ Self::new("local").expect("the static local scope is valid")+ }++ /// The host's tenant-less cluster scope.+ #[must_use]+ pub fn cluster() -> Self {+ Self::new(CLUSTER).expect("the static cluster scope is valid")+ }++ /// The host's tenant scope for a profile identifier.+ ///+ /// # Errors+ /// Returns an error for an empty identifier or when the resulting scope+ /// exceeds TSD's maximum serialized scope length.+ pub fn tenant(id: impl AsRef<str>) -> Result<Self, StorageError> {+ let segment = encode_segment(id.as_ref())?;+ Self::new(format!("{USER_PREFIX}{segment}"))+ }++ /// Narrows a tenant scope to an agent identity.+ ///+ /// # Errors+ /// Returns an error for an empty identity or a scope that is not an+ /// unqualified tenant.+ pub fn agent(&self, id: impl AsRef<str>) -> Result<Self, StorageError> {+ self.with_principal(AGENT_INFIX, id.as_ref())+ }++ /// Narrows a tenant scope to a module identity.+ ///+ /// # Errors+ /// Returns an error for an empty identity or a scope that is not an+ /// unqualified tenant.+ pub fn module(&self, id: impl AsRef<str>) -> Result<Self, StorageError> {+ self.with_principal(MODULE_INFIX, id.as_ref())+ }++ fn with_principal(&self, infix: &str, id: &str) -> Result<Self, StorageError> {+ let parsed = self.parsed()?;+ if matches!(parsed.tenant, Tenant::Cluster) || parsed.principal.is_some() {+ return Err(StorageError::invalid_input(format!(+ "a principal can only be added to a tenant scope without one, not {}",+ self.as_str()+ )));+ }+ let segment = encode_segment(id)?;+ Self::new(format!("{}{infix}{segment}", self.as_str()))+ }++ /// Returns the exact serialized scope value.+ #[must_use]+ pub fn as_str(&self) -> &str {+ self.0.as_str()+ }++ /// Whether this scope is the host's local operator tenant.+ #[must_use]+ pub fn is_local(&self) -> bool {+ self.as_str() == "local"+ }++ /// Whether this scope is the tenant-less cluster scope.+ #[must_use]+ pub fn is_cluster(&self) -> bool {+ self.as_str() == CLUSTER+ }++ /// Parses this value as an OpenHuman v2 scope.+ pub fn parsed(&self) -> Result<ParsedScope, StorageError> {+ ParsedScope::parse(self.as_str())+ }++ /// Returns the tenant scope that owns this scope, or `None` for cluster+ /// and legacy strings outside the host grammar.+ #[must_use]+ pub fn tenant_scope(&self) -> Option<Self> {+ let mut parsed = self.parsed().ok()?;+ if matches!(parsed.tenant, Tenant::Cluster) {+ return None;+ }+ parsed.principal = None;+ parsed.to_scope().ok()+ }+}++impl Deref for Scope {+ type Target = tinystoragedrivers::Scope;++ fn deref(&self) -> &Self::Target {+ &self.0+ }+}++impl AsRef<str> for Scope {+ fn as_ref(&self) -> &str {+ self.as_str()+ }+}++impl From<tinystoragedrivers::Scope> for Scope {+ fn from(scope: tinystoragedrivers::Scope) -> Self {+ Self(scope)+ }+}++/// A parsed host storage scope.+#[derive(Debug, Clone, PartialEq, Eq)]+pub struct ParsedScope {+ /// The tenant portion of the scope.+ pub tenant: Tenant,+ /// The optional agent or module principal.+ pub principal: Option<Principal>,+}++impl ParsedScope {+ /// Parses a string using the host's scope grammar.+ pub fn parse(value: &str) -> Result<Self, StorageError> {+ let invalid = || {+ StorageError::invalid_input(format!("{value:?} is not an OpenHuman storage scope"))+ };+ if value == CLUSTER {+ return Ok(Self {+ tenant: Tenant::Cluster,+ principal: None,+ });+ }+ let (tenant_text, principal_text) = match value.split_once('/') {+ Some((tenant, principal)) => (tenant, Some(principal)),+ None => (value, None),+ };+ let tenant = if tenant_text == "local" {+ Tenant::Local+ } else {+ let id = tenant_text.strip_prefix(USER_PREFIX).ok_or_else(invalid)?;+ if !valid_segment(id) {+ return Err(invalid());+ }+ Tenant::User(id.to_owned())+ };+ let principal = match principal_text {+ None => None,+ Some(text) => {+ let (make, id): (fn(String) -> Principal, &str) =+ if let Some(id) = text.strip_prefix(&AGENT_INFIX[1..]) {+ (Principal::Agent, id)+ } else if let Some(id) = text.strip_prefix(&MODULE_INFIX[1..]) {+ (Principal::Module, id)+ } else {+ return Err(invalid());+ };+ if !valid_segment(id) {+ return Err(invalid());+ }+ Some(make(id.to_owned()))+ }+ };+ Ok(Self { tenant, principal })+ }++ fn to_scope(&self) -> Result<Scope, StorageError> {+ let tenant = match &self.tenant {+ Tenant::Local => "local".to_owned(),+ Tenant::User(id) => format!("{USER_PREFIX}{id}"),+ Tenant::Cluster => CLUSTER.to_owned(),+ };+ match &self.principal {+ None => Scope::new(tenant),+ Some(Principal::Agent(id)) => Scope::new(format!("{tenant}{AGENT_INFIX}{id}")),+ Some(Principal::Module(id)) => Scope::new(format!("{tenant}{MODULE_INFIX}{id}")),+ }+ }+}++/// The tenant portion of a parsed storage scope.+#[derive(Debug, Clone, PartialEq, Eq)]+pub enum Tenant {+ /// The local operator installation.+ Local,+ /// A user or profile segment.+ User(String),+ /// The tenant-less shared cluster scope.+ Cluster,+}++/// The principal portion of a parsed storage scope.+#[derive(Debug, Clone, PartialEq, Eq)]+pub enum Principal {+ /// An agent identity.+ Agent(String),+ /// A loaded module identity.+ Module(String),+}/// The agent id a record with no named agent belongs to.pub const DEFAULT_AGENT: &str = "default";@@ -26,8 +245,8 @@ pub fn tenant_scope(profile: Option<&str>) -> Scope {}}-/// The storage scope profile `profile_id`'s records live under: its tenant-/// scope, `u:<id>`. Injective, hashing the id when it is not a valid segment.+/// The storage scope profile `profile_id`'s records live under: `u:<id>`.+/// Invalid or long ids are hashed to preserve a stable and bounded scope.pub fn scope_for_profile(profile_id: &str) -> Scope {Scope::tenant(profile_id).unwrap_or_else(|error| {tracing::warn!(@@ -35,14 +254,11 @@ pub fn scope_for_profile(profile_id: &str) -> Scope {%error,"[storage] unusable profile id for a scope; using the reserved empty-profile tenant");- Scope::tenant("_empty_").unwrap_or_else(|_| unreachable!("a static tenant id is valid"))+ Scope::tenant("_empty_").expect("a static tenant id is valid")})}-/// The storage scope agent `agent_id`'s records live under on the desktop:-/// `local/agent:<id>` (an empty id is the [`DEFAULT_AGENT`]). A profile's-/// agents are `scope_for_profile(profile).agent(id)`, which the session store-/// derives itself.+/// The storage scope for an agent id on the desktop: `local/agent:<id>`.pub fn scope_for_agent(agent_id: &str) -> Scope {let id = if agent_id.is_empty() {DEFAULT_AGENT@@ -51,22 +267,59 @@ pub fn scope_for_agent(agent_id: &str) -> Scope {};Scope::local().agent(id)- .unwrap_or_else(|_| unreachable!("a non-empty agent id is a valid segment"))+ .expect("a non-empty agent identity is representable as a scope")}-/// The scope module `module_id`'s records live under for the tenant of-/// `profile` (`None` for the desktop operator): `<tenant>/module:<id>`.-///-/// # Errors-///-/// When `module_id` is empty.+/// The scope for module `module_id` under `profile` (`None` for local).pub fn scope_for_module(profile: Option<&str>,module_id: &str,-) -> Result<Scope, super::StorageError> {+) -> Result<Scope, StorageError> {tenant_scope(profile).module(module_id)}+fn valid_segment(segment: &str) -> bool {+ if segment.is_empty() {+ return false;+ }+ if segment.strip_prefix('~').is_some_and(|hashed| {+ hashed.len() == MAX_HASH_SEGMENT_LEN+ && hashed+ .bytes()+ .all(|byte| byte.is_ascii_lowercase() && byte.is_ascii_alphabetic() || (b'2'..=b'7').contains(&byte))+ }) {+ return true;+ }+ segment.len() <= MAX_SCOPE_SEGMENT_LEN && segment.bytes().all(is_legal_segment_byte)+}++fn is_legal_segment_byte(byte: u8) -> bool {+ byte.is_ascii_alphanumeric() || matches!(byte, b'-' | b'_' | b'.' | b'@')+}++fn encode_segment(id: &str) -> Result<String, StorageError> {+ if id.is_empty() {+ return Err(StorageError::invalid_input("scope id must not be empty"));+ }+ if id.len() <= MAX_SCOPE_SEGMENT_LEN && id.bytes().all(is_legal_segment_byte) {+ return Ok(id.to_owned());+ }+ let digest = Sha256::digest(id.as_bytes());+ let mut encoded = String::with_capacity(52);+ let mut bits = 0u32;+ let mut bit_count = 0u8;+ for byte in digest {+ bits = (bits << 8) | u32::from(byte);+ bit_count += 8;+ while bit_count >= 5 {+ bit_count -= 5;+ encoded.push(char::from(BASE32_LOWER[((bits >> bit_count) & 0x1f) as usize]));+ }+ }+ encoded.truncate(MAX_HASH_SEGMENT_LEN);+ Ok(format!("~{encoded}"))+}+#[cfg(test)]#[path = "scope_tests.rs"]mod tests;