@dxos/protocols 0.8.4-main.fd6878d → 0.8.4-staging.60fe92afc8

package/src/index.ts

@@ -2,15 +2,15 @@
 // Copyright 2021 DXOS.org
 //
 
-export * from './errors/index.js';
-export * from './indexing.js';
-export * from './storage.js';
-export * from './tracing.js';
-export type * from './types.js';
-export * from './query.js';
-export * from './profile-archive.js';
-export * from './automerge.js';
-export * from './edge.js';
-export type * from './queue.js';
-export * from './space-archive.js';
-export * from './edge-error.js';
+export * from './automerge.ts';
+export * from './edge/index.ts';
+export * from './errors/index.ts';
+export * from './indexing.ts';
+export * from './messenger.ts';
+export * from './profile-archive.ts';
+export * from './space-archive.ts';
+export * from './storage.ts';
+export type * from './types.ts';
+export * as FunctionProtocol from './FunctionProtocol.ts';
+export * as FeedProtocol from './FeedProtocol.ts';
+export * as TraceProtocol from './TraceProtocol.ts';

package/src/indexing.test.ts

@@ -4,7 +4,7 @@
 
 import { describe, expect, test } from 'vitest';
 
-import { ObjectPointerVersion, objectPointerCodec } from './indexing.js';
+import { ObjectPointerVersion, objectPointerCodec } from './indexing.ts';
 
 describe('Indexing object pointer codec', () => {
   test('getVersion', async () => {

package/src/indexing.ts

@@ -2,7 +2,7 @@
 // Copyright 2024 DXOS.org
 //
 
-import { Schema } from 'effect';
+import * as Schema from 'effect/Schema';
 
 export type ObjectPointerDecoded = {
   spaceKey: string | undefined;

package/src/invitation.ts

@@ -2,13 +2,13 @@
 // Copyright 2024 DXOS.org
 //
 
-import { Schema } from 'effect';
+import * as Schema from 'effect/Schema';
 
-import { ParamKeyAnnotation } from '@dxos/effect';
+import { SchemaEx } from '@dxos/effect';
 
 // TODO(burdon): Use uniformly for processing HTTP params.
 export const InvitationUrl = Schema.Struct({
   accessToken: Schema.String, // TODO(burdon): Remove.
-  deviceInvitationCode: Schema.String.pipe(ParamKeyAnnotation({ key: 'deviceInvitationCode' })),
-  spaceInvitationCode: Schema.String.pipe(ParamKeyAnnotation({ key: 'spaceInvitationCode' })),
+  deviceInvitationCode: Schema.String.pipe(SchemaEx.ParamKeyAnnotation({ key: 'deviceInvitationCode' })),
+  spaceInvitationCode: Schema.String.pipe(SchemaEx.ParamKeyAnnotation({ key: 'spaceInvitationCode' })),
 });

package/src/messenger.ts

@@ -0,0 +1,22 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { type CleanupFn } from '@dxos/async';
+
+import { type GossipMessage } from './proto/gen/dxos/mesh/teleport/gossip';
+
+/**
+ * Message passing abstraction.
+ */
+export interface Messenger {
+  /**
+   * Register channel listener.
+   */
+  listen: (channel: string, callback: (message: GossipMessage) => void) => CleanupFn;
+
+  /**
+   * Send message to channel.
+   */
+  postMessage: (channel: string, message: any) => Promise<void>;
+}

package/src/profile-archive.ts

@@ -8,17 +8,30 @@
 export type ProfileArchive = {
   meta: {
     timestamp: string;
+    /** Host (e.g. `main.composer.space`, `localhost:5173`) where the archive was exported. */
+    origin?: string;
   };
   storage: ProfileArchiveEntry[];
 };
 
 export type ProfileArchiveEntry = {
   type: ProfileArchiveEntryType;
+  /**
+   * FILE: filename in random-access storage.
+   * KEY_VALUE: binary LevelDB key.
+   * SQLITE_DATABASE: OPFS database filename (e.g. `DXOS`).
+   */
   key: string | Uint8Array;
+  /**
+   * FILE / KEY_VALUE / SQLITE_DATABASE: binary payload.
+   * SQLITE_DATABASE must be a valid SQLite file (magic `SQLite format 3`).
+   */
   value: string | Uint8Array;
 };
 
 export enum ProfileArchiveEntryType {
   FILE = 1,
   KEY_VALUE = 2,
+  /** OPFS-hosted SQLite database; `key` is the OPFS filename, `value` is raw SQLite bytes. */
+  SQLITE_DATABASE = 3,
 }

package/src/proto/dxos/client/invitation.proto

@@ -43,6 +43,9 @@ enum SpaceState {
   /// Space is active. Swarming and replication will be done.
   SPACE_ACTIVE = 6;
 
+  /// Space is tombstoned (soft-deleted). Replicated to other devices; never auto-opened.
+  SPACE_DELETED = 9;
+
   ///
   /// Runtime states:
   ///
@@ -85,8 +88,12 @@ message Invitation {
   }
 
   enum Kind {
-    DEVICE = 0;
-    SPACE = 1;
+    /// Unset / unknown. Must not be used for new invitations.
+    INVALID = 0;
+
+    DEVICE = 1;
+
+    SPACE = 2;
   }
 
   enum AuthMethod {

package/src/proto/dxos/client/queue.proto

@@ -0,0 +1,102 @@
+syntax = "proto3";
+
+package dxos.client.services;
+
+import "google/protobuf/empty.proto";
+
+
+message QueueQuery {
+  string space_id = 1;
+
+  optional string queues_namespace = 2;
+
+  /// Queries the whole space if missing.
+  repeated string queue_ids = 3;
+
+  /// Filter items after this cursor. Exclusive.
+  optional string after = 4;
+
+  /// Filter items before this cursor. Exclusive.
+  optional string before = 5;
+
+  /// Filter items after this position. Inclusive.
+  optional int64 begin_position = 6;
+
+  /// Filter items before this position. Exclusive.
+  optional int64 end_position = 7;
+
+  optional int32 limit = 8;
+  optional bool reverse = 9;
+
+  // TODO(dmaretskyi): Remove this field -- raw queues dont index object IDs anymore.
+  repeated string object_ids = 100;
+}
+
+message QueueQueryResult {
+  /// JSON-encoded object payloads. Each entry is a serialized ObjectJSON.
+  /// We use JSON strings instead of google.protobuf.Struct because Struct
+  /// coerces `undefined` to `null`, corrupting optional fields.
+  repeated string objects = 1;
+
+  /// Cursor to query the next items. Can be passed to `after` in query to keep querying.
+  string next_cursor = 2;
+
+  string prev_cursor = 3;
+}
+
+message QueryQueueRequest {
+  QueueQuery query = 1;
+}
+
+message InsertIntoQueueRequest {
+  string subspace_tag = 1;
+  string space_id = 2;
+  string queue_id = 3;
+  /// JSON-encoded object payloads. Each entry is a serialized ObjectJSON.
+  repeated string objects = 4;
+}
+
+message DeleteFromQueueRequest {
+  string subspace_tag = 1;
+  string space_id = 2;
+  string queue_id = 3;
+  repeated string object_ids = 4;
+}
+
+message SyncQueueRequest {
+  string subspace_tag = 1;
+  string space_id = 2;
+  string queue_id = 3;
+  /// Whether to push local changes to the server. Defaults to true.
+  optional bool should_push = 4;
+  /// Whether to pull remote changes from the server. Defaults to true.
+  optional bool should_pull = 5;
+}
+
+message GetSyncStateRequest {
+  string space_id = 1;
+  /// If empty, returns state for all namespaces synced by the client.
+  repeated string namespaces = 2;
+}
+
+message QueueNamespaceSyncState {
+  string namespace = 1;
+  /// Blocks still to pull from remote. 0 when caught up.
+  int64 blocks_to_pull = 2;
+  /// Unpositioned blocks still to push to remote. 0 when caught up.
+  int64 blocks_to_push = 3;
+  /// Total blocks stored locally for this namespace in the space.
+  int64 total_blocks = 4;
+}
+
+message GetSyncStateResponse {
+  repeated QueueNamespaceSyncState namespaces = 1;
+}
+
+service QueueService {
+  rpc QueryQueue(QueryQueueRequest) returns (QueueQueryResult);
+  rpc InsertIntoQueue(InsertIntoQueueRequest) returns (google.protobuf.Empty);
+  rpc DeleteFromQueue(DeleteFromQueueRequest) returns (google.protobuf.Empty);
+  rpc SyncQueue(SyncQueueRequest) returns (google.protobuf.Empty);
+  rpc GetSyncState(GetSyncStateRequest) returns (GetSyncStateResponse);
+}

package/src/proto/dxos/client/services.proto

@@ -72,6 +72,7 @@ message Platform {
     BROWSER = 0;
     SHARED_WORKER = 1;
     NODE = 2;
+    DEDICATED_WORKER = 3;
   }
 
   PLATFORM_TYPE type = 1;
@@ -145,6 +146,8 @@ message RecoverIdentityRequest {
     string recovery_code = 1;
     ExternalSignature external = 2;
     string token = 3;
+    /// One-time proof minted by edge kms-service after a successful OAuth recovery flow.
+    string recovery_proof = 4;
   }
 }
 
@@ -331,6 +334,8 @@ message Space {
   optional PipelineState pipeline = 3;
   optional dxos.error.Error error = 4;
   optional dxos.echo.metadata.EdgeReplicationSetting edge_replication = 6;
+  repeated string tags = 7;
+  dxos.halo.credentials.MembershipPolicy membership_policy = 8;
 
   repeated SpaceMember members = 10;
   optional dxos.keys.PublicKey creator = 11;
@@ -341,6 +346,11 @@ message Space {
 
 // TODO(burdon): Create type for epoch?
 
+message CreateSpaceRequest {
+  repeated string tags = 1;
+  dxos.halo.credentials.MembershipPolicy membership_policy = 2;
+}
+
 message UpdateSpaceRequest {
   dxos.keys.PublicKey space_key = 1;
 
@@ -435,12 +445,22 @@ message JoinBySpaceKeyRequest {
 }
 
 message SpaceArchive {
+  enum Format {
+    // Tar-based binary archive (default).
+    BINARY = 0;
+    // JSON encoding of {@link dxos.echo.db.SerializedSpace}.
+    JSON = 1;
+  }
+
   string filename = 1;
   bytes contents = 2;
+  optional Format format = 3;
 }
 
 message ExportSpaceRequest {
   string space_id = 1;
+  // Archive format to produce. Defaults to BINARY.
+  optional SpaceArchive.Format format = 2;
 }
 
 message ExportSpaceResponse {
@@ -449,6 +469,8 @@ message ExportSpaceResponse {
 
 message ImportSpaceRequest {
   SpaceArchive archive = 1;
+  /// Immutable tags to set on the imported space at creation time.
+  repeated string tags = 2;
 }
 
 message ImportSpaceResponse {
@@ -457,7 +479,7 @@ message ImportSpaceResponse {
 }
 
 service SpacesService {
-  rpc CreateSpace(google.protobuf.Empty) returns (Space);
+  rpc CreateSpace(CreateSpaceRequest) returns (Space);
   rpc UpdateSpace(UpdateSpaceRequest) returns (google.protobuf.Empty);
   rpc QuerySpaces(google.protobuf.Empty) returns (stream QuerySpacesResponse);
 
@@ -596,9 +618,26 @@ service EdgeAgentService {
   rpc QueryAgentStatus(google.protobuf.Empty) returns (stream QueryAgentStatusResponse);
 }
 
-enum EdgeStatus {
-  NOT_CONNECTED = 0;
-  CONNECTED = 1;
+message EdgeStatus {
+  enum ConnectionState {
+    NOT_CONNECTED = 0;
+    CONNECTED = 1;
+  }
+
+  ConnectionState state = 1;
+  /** Latency in ms */
+  int32 rtt = 2;
+
+  /** How long the connection has been up */
+  int32 uptime = 3;
+
+  /** Upload rate in bytes per second */
+  int32 rate_bytes_up = 4;
+  /** Download rate in bytes per second */
+  int32 rate_bytes_down = 5;
+
+  int32 messages_sent = 6;
+  int32 messages_received = 7;
 }
 
 message QueryEdgeStatusResponse {

package/src/proto/dxos/config.proto

@@ -12,9 +12,7 @@ package dxos.config;
 
 option go_package = "github.com/dxos/dxos/proto/def/dxos/config";
 
-extend google.protobuf.FieldOptions {
-  optional string env_var = 1000;
-}
+extend google.protobuf.FieldOptions { optional string env_var = 1000; }
 
 message Config {
   optional int32 version = 1;
@@ -58,9 +56,10 @@ message Module {
     optional google.protobuf.Struct env = 10;
   }
 
-  optional string id = 8;     // TODO(burdon): Ensured FQ (e.g., 'dxos.app.xxx')
-  optional string name = 1;   // TODO(burdon): Replace with id (or key?)
-  optional string type = 2;   // TODO(burdon): Define namespace (e.g., 'dxos.org/type/frame' vs. 'dxos.type.frame')
+  optional string id = 8;   // TODO(burdon): Ensured FQ (e.g., 'dxos.app.xxx')
+  optional string name = 1; // TODO(burdon): Replace with id (or key?)
+  optional string type = 2; // TODO(burdon): Define namespace (e.g.,
+                            // 'org.dxos.type.frame')
 
   // TODO(burdon): Developer info message.
 
@@ -74,7 +73,7 @@ message Module {
   optional bool tunnel = 7;
 
   // TODO(burdon): Start at 100.
-  repeated Module deps = 10;  // TODO(burdon): E.g., types.
+  repeated Module deps = 10; // TODO(burdon): E.g., types.
   optional Build build = 100;
   repeated Repo repos = 101;
 
@@ -85,6 +84,17 @@ message Module {
 
 message Runtime {
   message Client {
+    /// Where client services run. Drives `createClientServices` routing.
+    enum ServicesMode {
+      UNSPECIFIED_SERVICES_MODE = 0;
+      /// Run services in the same thread as the client.
+      HOST = 1;
+      /// Run services in a SharedWorker (single instance shared across tabs).
+      SHARED_WORKER = 2;
+      /// Run services in a dedicated Worker elected via a lock (leader/follower).
+      DEDICATED_WORKER = 3;
+    }
+
     message Storage {
       enum StorageDriver {
         RAM = 0;
@@ -99,6 +109,20 @@ message Runtime {
         JSONDOWN = 12;
       }
 
+      /// Storage backing for SQLite (indexes & persistent state). The caller must supply the
+      /// matching worker factory / path — `createClientServices` does not pick a mode from the
+      /// presence of options.
+      enum SqliteMode {
+        UNSPECIFIED_SQLITE_MODE = 0;
+        /// Ephemeral in-memory SQLite. Indexes are rebuilt on each start.
+        MEMORY = 1;
+        /// OPFS-backed SQLite running in a dedicated worker (browser).
+        /// Requires `createOpfsWorker` to be passed to `createClientServices`.
+        OPFS = 2;
+        /// File-backed SQLite (Node/Bun). Uses `data_root` to locate the database file.
+        FILE = 3;
+      }
+
       optional bool persistent = 1;
       optional StorageDriver key_store = 2;
       optional StorageDriver data_store = 3;
@@ -108,16 +132,21 @@ message Runtime {
        * @deprecated
        */
       optional bool space_fragmentation = 5;
+
+      /// Backing store for SQLite runtimes. Defaults to MEMORY when unset.
+      optional SqliteMode sqlite_mode = 6;
     }
 
     message Log {
-      optional string filter = 1 [(env_var) = "LOG_FILTER"];
-      optional string prefix = 2 [(env_var) = "LOG_PREFIX"];
+      optional string filter = 1 [ (env_var) = "LOG_FILTER" ];
+      optional string prefix = 2 [ (env_var) = "LOG_PREFIX" ];
     }
 
     message EdgeFeatures {
       optional bool feed_replicator = 1;
       optional bool echo_replicator = 2;
+      /// Enables Subduction sedimentree transport for Automerge document replication.
+      optional bool subduction_replicator = 5;
       optional bool signaling = 3;
       optional bool agents = 4;
     }
@@ -136,7 +165,8 @@ message Runtime {
     optional int32 invitation_expiration = 5;
 
     /// Location of the remote client host.
-    // TODO(burdon): Rename vault_endpoint (generalize http/ws; drop vault.html).
+    // TODO(burdon): Rename vault_endpoint (generalize http/ws; drop
+    // vault.html).
     optional string remote_source = 6;
 
     // Authenticate via `Sec-WebSocket-Protocol` header hack.
@@ -145,7 +175,8 @@ message Runtime {
     /// Connect to and serve client services to a remote proxy.
     optional string devtools_proxy = 7;
 
-    /// Spaces will stay in SpaceState.CLOSED until explicitly opened. Speeds up client-services initialization.
+    /// Spaces will stay in SpaceState.CLOSED until explicitly opened. Speeds up
+    /// client-services initialization.
     optional bool lazy_space_open = 9;
 
     /// Disabled automerge & hypercore replication through P2P connections.
@@ -154,6 +185,25 @@ message Runtime {
     optional bool enable_vector_indexing = 12;
 
     optional EdgeFeatures edge_features = 11;
+
+    /// Observability group attached as metadata to signaling requests.
+    /// NOTE: When running through a shared worker, subsequent client connections can refresh this
+    /// value (last-writer-wins); the first client still determines the worker's other config.
+    optional string observability_group = 13;
+
+    /// Enable telemetry metadata attached to signaling requests.
+    /// NOTE: When running through a shared worker, subsequent client connections can refresh this
+    /// value (last-writer-wins); the first client still determines the worker's other config.
+    optional bool signal_telemetry_enabled = 14;
+
+    /// Use in-process (single-client) coordinator for dedicated-worker mode.
+    /// Bypasses SharedWorker; used for WKWebView where the coordinator SharedWorker port is unreliable.
+    optional bool single_client_mode = 15;
+
+    /// Deployment mode for client services. Read by `createClientServices` to select between
+    /// in-process (HOST), SharedWorker, and dedicated Worker runtimes. Required when no
+    /// `remote_source` is configured.
+    optional ServicesMode services_mode = 16;
   }
 
   message App {
@@ -169,7 +219,7 @@ message Runtime {
     optional string org = 1;
     optional string theme = 2;
     optional string website = 3;
-    optional string public_url = 4 [(env_var) = "PUBLIC_URL"];
+    optional string public_url = 4 [ (env_var) = "PUBLIC_URL" ];
 
     optional BuildInfo build = 100;
     optional google.protobuf.Struct env = 101;
@@ -214,13 +264,9 @@ message Runtime {
     optional string channel = 7;
   }
 
-  message Props {
-    optional string title = 1;
-  }
+  message Props { optional string title = 1; }
 
-  message System {
-    optional string debug = 1;
-  }
+  message System { optional string debug = 1; }
 
   //
   // KUBE
@@ -255,9 +301,7 @@ message Runtime {
       int32 interval = 3;
     }
 
-    message Trace {
-      bool disabled = 1;
-    }
+    message Trace { bool disabled = 1; }
 
     message Telemetry {
       bool disabled = 1;
@@ -285,10 +329,10 @@ message Runtime {
 
     /// https://github.com/ipfs/kubo/blob/master/docs/config.md#apiauthorizations
     message KuboApiAuthorization {
-        /// Just for organizational purposes.
-        string name = 1;
-        string auth_secret = 2;
-        repeated string allowed_paths = 3;
+      /// Just for organizational purposes.
+      string name = 1;
+      string auth_secret = 2;
+      repeated string allowed_paths = 3;
     }
 
     // TODO(burdon): Needs documentation/
@@ -359,8 +403,9 @@ message Runtime {
     message Ipfs {
       optional string server = 1;
       optional string gateway = 2;
-      /// Used for IPFS API authentication, regardless if server is direct KUBO API (e.g. path of '/api/v0') or a reverse proxy
-      /// Same secret format as https://github.com/ipfs/kubo/blob/master/docs/config.md#apiauthorizations
+      /// Used for IPFS API authentication, regardless if server is direct KUBO
+      /// API (e.g. path of '/api/v0') or a reverse proxy Same secret format as
+      /// https://github.com/ipfs/kubo/blob/master/docs/config.md#apiauthorizations
       optional string server_auth_secret = 3;
     }
 
@@ -376,9 +421,7 @@ message Runtime {
       optional string credential = 3;
     }
 
-    message IceProvider {
-      string urls = 1;
-    }
+    message IceProvider { string urls = 1; }
 
     message Machine {
       optional string do_access_token = 1;
@@ -396,9 +439,7 @@ message Runtime {
       optional string server = 1;
     }
 
-    message Tunneling {
-      optional string server = 1;
-    }
+    message Tunneling { optional string server = 1; }
 
     message Supervisor { // TODO(burdon): Is this a service?
       optional string server = 1;
@@ -416,14 +457,13 @@ message Runtime {
       optional string type = 2;
     }
 
-    message Edge {
-      optional string url = 1;
-    }
+    message Edge { optional string url = 1; }
 
-    message Ai {
-      optional string server = 1;
-    }
+    message Ai { optional string server = 1; }
+
+    message Hub { optional string url = 1; }
 
+    /** Deprecated */
     optional Kube kube = 1;
     optional AppServer app = 2;
     optional Dxns dxns = 3;
@@ -434,12 +474,17 @@ message Runtime {
     optional Machine machine = 7;
     optional BotHost bot = 8;
     optional Publisher publisher = 9;
-    optional Supervisor supervisor = 10; // TODO(burdon): Promote to 1; start others at 10.
+    /** Deprecated */
+    optional Supervisor supervisor = 10;
+    /** Deprecated */
     optional Tunneling tunneling = 11;
+    /** Deprecated */
     optional Faasd faasd = 12;
+    /** Deprecated */
     optional AgentHosting agent_hosting = 13;
     optional Edge edge = 15;
     optional Ai ai = 16;
+    optional Hub hub = 17;
   }
 
   message Keys {

package/src/proto/dxos/devtools/host.proto

@@ -78,6 +78,13 @@ service DevtoolsHost {
   rpc SubscribeToSignalStatus(google.protobuf.Empty) returns (stream SubscribeToSignalStatusResponse);
   rpc SubscribeToSignal(google.protobuf.Empty) returns (stream SignalResponse);
   rpc SubscribeToSwarmInfo(SubscribeToSwarmInfoRequest) returns (stream SubscribeToSwarmInfoResponse);
+
+  //
+  // SQLite
+  //
+
+  rpc ExportSqliteDatabase(google.protobuf.Empty) returns (ExportSqliteDatabaseResponse);
+  rpc RunSqliteQuery(RunSqliteQueryRequest) returns (RunSqliteQueryResponse);
 }
 
 message Event {
@@ -338,3 +345,23 @@ message SubscribeToSwarmInfoRequest {}
 message SubscribeToSwarmInfoResponse {
   repeated dxos.devtools.swarm.SwarmInfo data = 1;
 }
+
+//
+// SQLite
+//
+
+message ExportSqliteDatabaseResponse {
+  bytes data = 1;
+}
+
+message RunSqliteQueryRequest {
+  string query = 1;
+  // JSON-encoded array of query parameters.
+  optional string params = 2;
+}
+
+message RunSqliteQueryResponse {
+  // JSON-encoded array of row objects.
+  string rows = 1;
+  optional string error = 2;
+}

package/src/proto/dxos/echo/metadata.proto

@@ -34,6 +34,9 @@ message EchoMetadata {
 
   // TODO(burdon): Circular dep.
   repeated dxos.client.services.Invitation invitations = 12;
+
+  /// Keys of spaces that have been tombstoned (soft-deleted). Survives restart; prevents re-acceptance.
+  repeated dxos.keys.PublicKey deleted_spaces = 13;
 }
 
 /// Per-space metadata. Frequent updates. Keep small.
@@ -54,6 +57,9 @@ message SpaceMetadata {
   /// Space key.
   dxos.keys.PublicKey key = 1;
 
+  /// Immutable tags assigned at space creation time.
+  repeated string tags = 12;
+
   /// ACTIVE, INACTIVE, etc.
   optional dxos.client.services.SpaceState state = 10;