Skip to content

The fastest, cheapest, most efficient open-source agent harness. Run more than 500 agents on a $10 VPS.

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.rs
index 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.rs
index 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;