Skip to content

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

feat(storage): add host invocation storage module

Steven Enamakel4ad77e2bef19
diff --git a/crates/openhuman-core/src/modules/storage_host_invocation.rs b/crates/openhuman-core/src/modules/storage_host_invocation.rs
new file mode 100644
index 0000000000..4529dc60b0
--- /dev/null
+++ b/crates/openhuman-core/src/modules/storage_host_invocation.rs
@@ -0,0 +1,199 @@
+//! Invocation-scoped, Documents-only storage callbacks for module imports.
+//!
+//! Unlike the long-lived storage host, this endpoint is bound to the exact
+//! ready module instance that will make one import call. Its `Storage` is
+//! supplied by the caller and therefore retains the captured profile and
+//! import-claim conditions. The endpoint has no Secrets capability and does
+//! not expose data operations on the other ports.
+
+use std::sync::atomic::{AtomicBool, AtomicU64, Ordering};
+use std::sync::Arc;
+
+use async_trait::async_trait;
+use serde_json::{Value, json};
+use tinybus::module::ModuleRuntime;
+use tinybus::{BusName, ObjectPath};
+use tinystoragedrivers_api::BlobReader;
+use tinystoragedrivers_bus::{
+ BlobCapabilities, BlobKeyRequest, BlobStreamHead, CapabilitiesReply, KvCapabilitiesReply,
+ PutBlobStreamRequest, QueueFeaturesReply, StorageFailure, StorageKind, WatchChanged,
+};
+use tinystoragedrivers_busproxy::{
+ Admission, HostFailure, Object, ServedStorage, StorageAddress, StorageCall, StorageEndpoint,
+ StorageServer,
+};
+use tokio::sync::broadcast;
+
+use crate::storage::Storage;
+
+static NEXT_INVOCATION: AtomicU64 = AtomicU64::new(1);
+
+/// The callback address fields used by the transport-neutral owner request.
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub(crate) struct CallbackAddress {
+ pub host: String,
+ pub object_root: String,
+}
+
+/// Owns an invocation's temporary Documents endpoint and its registrations.
+///
+/// Keep this value alive for the entire module RPC. Dropping it closes dispatch
+/// before the TSD guard unregisters the invocation's paths.
+pub(crate) struct InvocationStorageBinding {
+ address: CallbackAddress,
+ active: Arc<AtomicBool>,
+ served: Option<ServedStorage>,
+}
+
+impl InvocationStorageBinding {
+ /// Serve the supplied claim-bound storage to this exact, currently ready
+ /// module instance.
+ pub(crate) async fn serve(
+ runtime: &ModuleRuntime,
+ module_descriptor_name: &str,
+ storage: Storage,
+ ) -> anyhow::Result<Self> {
+ let expected_peer = runtime
+ .host()
+ .authenticated_peer(module_descriptor_name)
+ .ok_or_else(|| anyhow::anyhow!("module is not a live admitted instance"))?;
+ let connection = runtime.connection();
+ let host = connection
+ .unique_name()
+ .ok_or_else(|| anyhow::anyhow!("module runtime connection has no unique bus name"))?;
+ let serial = NEXT_INVOCATION.fetch_add(1, Ordering::Relaxed);
+ let object_root = ObjectPath::new(format!(
+ "{}/call-{serial}",
+ tinystoragedrivers_busproxy::INVOCATION_OBJECT_ROOT
+ ))?;
+ let address = StorageAddress::try_new(host, object_root)?;
+ let active = Arc::new(AtomicBool::new(true));
+ let endpoint = Arc::new(DocumentsOnlyEndpoint {
+ expected_peer,
+ active: Arc::clone(&active),
+ server: StorageServer::new(storage),
+ });
+ let served = tinystoragedrivers_busproxy::serve_at_address(
+ connection,
+ address.clone(),
+ endpoint,
+ )
+ .await?;
+ Ok(Self {
+ address: CallbackAddress {
+ host: address.host().to_string(),
+ object_root: address.object_root().to_string(),
+ },
+ active,
+ served: Some(served),
+ })
+ }
+
+ /// The address for the owner request. It conveys routing only; it carries
+ /// no scope, grant, or write-condition authority.
+ pub(crate) fn address(&self) -> &CallbackAddress {
+ &self.address
+ }
+
+ /// Synchronously revoke calls and unregister the invocation paths.
+ pub(crate) async fn close(mut self) -> anyhow::Result<()> {
+ self.active.store(false, Ordering::Release);
+ if let Some(served) = self.served.take() {
+ served.shutdown().await?;
+ }
+ Ok(())
+ }
+}
+
+impl Drop for InvocationStorageBinding {
+ fn drop(&mut self) {
+ self.active.store(false, Ordering::Release);
+ // `ServedStorage::drop` schedules path removal on the module runtime.
+ // Keeping it in this binding ties registration lifetime to the import
+ // call, including error and cancellation paths.
+ self.served.take();
+ }
+}
+
+struct DocumentsOnlyEndpoint {
+ expected_peer: BusName,
+ active: Arc<AtomicBool>,
+ server: StorageServer,
+}
+
+impl DocumentsOnlyEndpoint {
+ fn authorize(&self, sender: Option<&BusName>) -> Result<(), HostFailure> {
+ if !self.active.load(Ordering::Acquire) {
+ return Err(HostFailure::Denied("storage-endpoint-closed"));
+ }
+ match sender {
+ Some(sender) if sender == &self.expected_peer => Ok(()),
+ Some(_) => Err(HostFailure::Denied("wrong-module-instance")),
+ None => Err(HostFailure::Denied("unauthenticated-caller")),
+ }
+ }
+
+ fn unsupported() -> HostFailure {
+ HostFailure::Storage(StorageFailure {
+ kind: StorageKind::Unsupported,
+ })
+ }
+
+ fn denied() -> HostFailure {
+ HostFailure::Denied("documents-only-invocation")
+ }
+}
+
+#[async_trait]
+impl StorageEndpoint for DocumentsOnlyEndpoint {
+ async fn call(&self, call: StorageCall<'_>) -> Result<Value, HostFailure> {
+ // Authenticate before even answering capability negotiation. An
+ // address is routing information, never proof of module identity.
+ self.authorize(call.sender)?;
+ match (call.object, call.selector) {
+ (Object::Documents, _) => self
+ .server
+ .handle(
+ Admission::Private,
+ Object::Documents.as_str(),
+ call.selector,
+ call.request,
+ )
+ .await
+ .map_err(HostFailure::Storage),
+ (Object::Streams, "Capabilities") => {
+ Ok(json!(CapabilitiesReply::default()))
+ }
+ (Object::Blobs, "Capabilities") => Ok(json!(BlobCapabilities::default())),
+ (Object::Kv, "Capabilities") => Ok(json!(KvCapabilitiesReply::default())),
+ (Object::Queues, "Features") => Ok(json!(QueueFeaturesReply::default())),
+ (Object::Secrets, _) => Err(Self::unsupported()),
+ (Object::Streams | Object::Blobs | Object::Kv | Object::Queues, _) => {
+ Err(Self::denied())
+ }
+ }
+ }
+
+ async fn put_blob_stream(
+ &self,
+ sender: Option<&BusName>,
+ _head: PutBlobStreamRequest,
+ _body: BlobReader,
+ ) -> Result<Value, HostFailure> {
+ self.authorize(sender)?;
+ Err(Self::denied())
+ }
+
+ async fn get_blob_stream(
+ &self,
+ sender: Option<&BusName>,
+ _request: BlobKeyRequest,
+ ) -> Result<Option<(BlobStreamHead, BlobReader)>, HostFailure> {
+ self.authorize(sender)?;
+ Err(Self::denied())
+ }
+
+ fn watch_signals(&self, _sender: &BusName) -> Option<broadcast::Receiver<WatchChanged>> {
+ None
+ }
+}