@dxos/client-protocol 0.8.3 → 0.8.4-main.1068cf700f

package/package.json

@@ -1,24 +1,38 @@
 {
   "name": "@dxos/client-protocol",
-  "version": "0.8.3",
+  "version": "0.8.4-main.1068cf700f",
   "description": "Core DXOS Client API.",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
-  "repository": "github:dxos/dxos",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dxos/dxos"
+  },
   "license": "MIT",
   "author": "DXOS.org",
-  "sideEffects": true,
+  "sideEffects": false,
   "type": "module",
   "exports": {
     ".": {
+      "source": "./src/index.ts",
       "types": "./dist/types/src/index.d.ts",
       "browser": "./dist/lib/browser/index.mjs",
       "node": "./dist/lib/node-esm/index.mjs"
+    },
+    "./types": {
+      "source": "./src/types/index.ts",
+      "types": "./dist/types/src/types/index.d.ts",
+      "browser": "./dist/lib/browser/types/index.mjs",
+      "node": "./dist/lib/node-esm/types/index.mjs"
     }
   },
   "types": "dist/types/src/index.d.ts",
   "typesVersions": {
-    "*": {}
+    "*": {
+      "./types": [
+        "./dist/types/src/types/index.d.ts"
+      ]
+    }
   },
   "files": [
     "dist",
@@ -26,22 +40,20 @@
   ],
   "dependencies": {
     "base-x": "~3.0.9",
-    "effect": "3.14.21",
-    "@dxos/async": "0.8.3",
-    "@dxos/config": "0.8.3",
-    "@dxos/context": "0.8.3",
-    "@dxos/credentials": "0.8.3",
-    "@dxos/echo-db": "0.8.3",
-    "@dxos/echo": "0.8.3",
-    "@dxos/echo-schema": "0.8.3",
-    "@dxos/invariant": "0.8.3",
-    "@dxos/keys": "0.8.3",
-    "@dxos/node-std": "0.8.3",
-    "@dxos/protocols": "0.8.3",
-    "@dxos/rpc": "0.8.3"
+    "effect": "3.19.16",
+    "@dxos/async": "0.8.4-main.1068cf700f",
+    "@dxos/context": "0.8.4-main.1068cf700f",
+    "@dxos/credentials": "0.8.4-main.1068cf700f",
+    "@dxos/invariant": "0.8.4-main.1068cf700f",
+    "@dxos/echo-db": "0.8.4-main.1068cf700f",
+    "@dxos/echo": "0.8.4-main.1068cf700f",
+    "@dxos/node-std": "0.8.4-main.1068cf700f",
+    "@dxos/keys": "0.8.4-main.1068cf700f",
+    "@dxos/protocols": "0.8.4-main.1068cf700f",
+    "@dxos/rpc": "0.8.4-main.1068cf700f"
   },
   "peerDependencies": {
-    "effect": "^3.13.3"
+    "effect": "3.19.16"
   },
   "publishConfig": {
     "access": "public"

package/src/config.ts

@@ -2,10 +2,10 @@
 // Copyright 2022 DXOS.org
 //
 
-import { type ConfigProto } from '@dxos/config';
+// TODO(wittjosiah): Factor out to @dxos/config.
 
-export const DEFAULT_INTERNAL_CHANNEL = 'dxos:vault';
 export const DEFAULT_CLIENT_CHANNEL = 'dxos:app';
+export const DEFAULT_INTERNAL_CHANNEL = 'dxos:vault';
 export const DEFAULT_SHELL_CHANNEL = 'dxos:shell';
 export const DEFAULT_WORKER_BROADCAST_CHANNEL = 'dxos:shared-worker';
 
@@ -14,18 +14,17 @@ export const DEFAULT_WORKER_BROADCAST_CHANNEL = 'dxos:shared-worker';
  */
 export const DEFAULT_VAULT_URL = 'https://halo.dxos.org/vault.html';
 
+/**
+ * @deprecated
+ */
+// TODO(burdon): Remove need (i.e., make undefined do the right thing).
+export const DEFAULT_PROFILE = 'default';
+
 export const EXPECTED_CONFIG_VERSION = 1;
-export const defaultConfig: ConfigProto = { version: 1 };
+export const defaultConfig = { version: 1 };
 
 // TODO(burdon): Allow override via env? Generalize since currently NodeJS only.
-const HOME = typeof process !== 'undefined' ? process?.env?.HOME ?? '' : '';
-
-// Base directories.
-// TODO(burdon): Consider Windows, Linux, OSX.
-// https://wiki.archlinux.org/title/XDG_Base_Directory
-// Each `/dx` directory should contain `/profile/<DX_PROFILE>` subdirectories.
-export const getProfilePath = (root: string, profile: string, file: string | undefined = undefined) =>
-  `${root}/profile/${profile}` + (file ? `/${file}` : '');
+const HOME = typeof process !== 'undefined' ? (process?.env?.HOME ?? '') : '';
 
 // XDG_CONFIG_HOME (Analogous to /etc.)
 export const DX_CONFIG = `${HOME}/.config/dx`;
@@ -43,7 +42,27 @@ export const DX_STATE = `${HOME}/.local/state/dx`;
 // XDG_RUNTIME_DIR (Non-essential files, sockets, etc.)
 export const DX_RUNTIME = '/tmp/dx/run';
 
-export const ENV_DX_CONFIG = 'DX_CONFIG';
-export const ENV_DX_NO_AGENT = 'DX_NO_AGENT';
-export const ENV_DX_PROFILE = 'DX_PROFILE';
-export const ENV_DX_PROFILE_DEFAULT = 'default';
+export enum DXEnv {
+  CONFIG = 'DX_CONFIG',
+  DEBUG = 'DX_DEBUG',
+  NO_AGENT = 'DX_NO_AGENT',
+  PROFILE = 'DX_PROFILE',
+}
+
+export namespace DXEnv {
+  /**
+   * Helper to get the value from process.env
+   */
+  export function get(variable: DXEnv): string | undefined;
+  export function get(variable: DXEnv, defaultValue: string): string;
+  export function get(variable: DXEnv, defaultValue?: string): string | undefined {
+    return process.env[variable] ?? defaultValue;
+  }
+}
+
+// Base directories.
+// TODO(burdon): Consider Windows, Linux, OSX.
+// https://wiki.archlinux.org/title/XDG_Base_Directory
+// Each `/dx` directory should contain `/profile/<DX_PROFILE>` subdirectories.
+export const getProfilePath = (root: string, profile: string, file: string | undefined = undefined) =>
+  `${root}/profile/${profile}` + (file ? `/${file}` : '');

package/src/echo.ts

@@ -3,26 +3,19 @@
 //
 
 import type { MulticastObservable } from '@dxos/async';
-import type { QueryFn } from '@dxos/echo-db';
+import type { Database } from '@dxos/echo';
 import type { PublicKey, SpaceId } from '@dxos/keys';
 import type { Invitation, SpaceArchive } from '@dxos/protocols/proto/dxos/client/services';
 
 import type { AuthenticatingInvitation } from './invitations';
-import type { PropertiesTypeProps } from './schema';
 import type { Space } from './space';
+import type { SpaceProperties } from './types';
 
 /**
- * TODO(burdon): Public API (move comments here).
+ * Public database API.
  */
-// TODO(wittjosiah): Rename?
-//   https://ts.dev/style/#naming-style
-//   ClientApi? ClientProtocol?
-export interface Echo extends MulticastObservable<Space[]> {
-  /**
-   * Resolves when the default space is available.
-   */
-  waitUntilReady(): Promise<void>;
-
+// TODO(wittjosiah): Rename Database (not product name).
+export interface Echo extends MulticastObservable<Space[]>, Database.Queryable {
   /**
    * Observable which indicates when the default space is available.
    */
@@ -50,10 +43,15 @@ export interface Echo extends MulticastObservable<Space[]> {
    */
   get default(): Space;
 
+  /**
+   * Resolves when the default space is available.
+   */
+  waitUntilReady(): Promise<void>;
+
   /**
    * Creates a new space.
    */
-  create(meta?: PropertiesTypeProps): Promise<Space>;
+  create(props?: Pick<SpaceProperties, 'name' | 'hue' | 'icon' | 'invocationTraceQueue'>): Promise<Space>;
 
   /**
    * Creates a space from the given archive.
@@ -66,11 +64,4 @@ export interface Echo extends MulticastObservable<Space[]> {
   join(invitation: Invitation | string): AuthenticatingInvitation;
 
   joinBySpaceKey(spaceKey: PublicKey): Promise<Space>;
-
-  /**
-   * Query all spaces.
-   * @param filter
-   * @param options
-   */
-  query: QueryFn;
 }

package/src/halo.ts

@@ -6,8 +6,8 @@ import { type MulticastObservable } from '@dxos/async';
 import { type PublicKey } from '@dxos/keys';
 import { type Contact, type Device, type Identity, type Invitation } from '@dxos/protocols/proto/dxos/client/services';
 import {
-  type DeviceProfileDocument,
   type Credential,
+  type DeviceProfileDocument,
   type Presentation,
   type ProfileDocument,
 } from '@dxos/protocols/proto/dxos/halo/credentials';

package/src/index.ts

@@ -4,11 +4,11 @@
 
 export * from './client';
 export * from './config';
-export * from './echo';
-export * from './halo';
+export type * from './echo';
+export type * from './halo';
 export * from './invitations';
-export * from './service-definitions';
-export * from './shell';
+export * from './service';
+export type * from './shell';
 export * from './space';
 export * from './timeouts';
-export * from './schema';
+export * from './types';

package/src/{service-definitions.ts → service.ts}

@@ -4,17 +4,17 @@
 
 import { type Event } from '@dxos/async';
 import { schema } from '@dxos/protocols/proto';
-import type { FunctionRegistryService } from '@dxos/protocols/proto/dxos/agent/functions';
 import type {
+  ContactsService,
   DevicesService,
+  EdgeAgentService,
   IdentityService,
   InvitationsService,
   LoggingService,
   NetworkService,
+  QueueService,
   SpacesService,
   SystemService,
-  ContactsService,
-  EdgeAgentService,
 } from '@dxos/protocols/proto/dxos/client/services';
 import type { DevtoolsHost } from '@dxos/protocols/proto/dxos/devtools/host';
 import type { QueryService } from '@dxos/protocols/proto/dxos/echo/query';
@@ -24,6 +24,8 @@ import type { BridgeService } from '@dxos/protocols/proto/dxos/mesh/bridge';
 import type { TracingService } from '@dxos/protocols/proto/dxos/tracing';
 import { type ServiceBundle, createServiceBundle } from '@dxos/rpc';
 
+export type { QueueService } from '@dxos/protocols/proto/dxos/client/services';
+
 //
 // NOTE: Should contain client/proxy dependencies only.
 //
@@ -35,15 +37,16 @@ export type ClientServices = {
 
   IdentityService: IdentityService;
   InvitationsService: InvitationsService;
-  QueryService: QueryService;
   DevicesService: DevicesService;
   SpacesService: SpacesService;
+
   DataService: DataService;
+  QueryService: QueryService;
+  QueueService: QueueService;
+
   ContactsService: ContactsService;
   EdgeAgentService: EdgeAgentService;
 
-  FunctionRegistryService: FunctionRegistryService;
-
   // TODO(burdon): Deprecated.
   DevtoolsHost: DevtoolsHost;
 
@@ -59,12 +62,26 @@ export interface ClientServicesProvider {
    * This should fire if the services disconnect unexpectedly or during a client reset.
    */
   closed: Event<Error | undefined>;
+
+  /**
+   * The underlying service connection was re-established.
+   * Fires after all reconnection callbacks have completed.
+   */
+  reconnected?: Event<void>;
+
+  /**
+   * Register a callback to be invoked when services reconnect.
+   * The callback should re-establish any RPC streams.
+   * Reconnection waits for all callbacks to complete before emitting `reconnected`.
+   */
+  onReconnect?: (callback: () => Promise<void>) => void;
+
   descriptors: ServiceBundle<ClientServices>;
   services: Partial<ClientServices>;
 
   // TODO(burdon): Should take context from parent?
-  open(): Promise<void>;
-  close(): Promise<void>;
+  open(): Promise<unknown>;
+  close(): Promise<unknown>;
 }
 
 /**
@@ -83,13 +100,10 @@ export const clientServiceBundle = createServiceBundle<ClientServices>({
   DataService: schema.getService('dxos.echo.service.DataService'),
   ContactsService: schema.getService('dxos.client.services.ContactsService'),
   EdgeAgentService: schema.getService('dxos.client.services.EdgeAgentService'),
-
-  // Agent-only.
-  FunctionRegistryService: schema.getService('dxos.agent.functions.FunctionRegistryService'),
+  QueueService: schema.getService('dxos.client.services.QueueService'),
 
   // TODO(burdon): Deprecated.
   DevtoolsHost: schema.getService('dxos.devtools.host.DevtoolsHost'),
-
   TracingService: schema.getService('dxos.tracing.TracingService'),
 });
 

package/src/shell.ts

@@ -5,8 +5,8 @@
 import { type Event } from '@dxos/async';
 import { type PublicKey } from '@dxos/keys';
 import {
-  type InvitationUrlRequest,
   type AppContextRequest,
+  type InvitationUrlRequest,
   type LayoutRequest,
   type ShellLayout,
 } from '@dxos/protocols/proto/dxos/iframe';

package/src/space.ts

@@ -2,16 +2,20 @@
 // Copyright 2021 DXOS.org
 //
 
-import { type MulticastObservable, type CleanupFn } from '@dxos/async';
+import * as Schema from 'effect/Schema';
+
+import { type MulticastObservable } from '@dxos/async';
 import { type SpecificCredential } from '@dxos/credentials';
-import { type QueueFactory, type CoreDatabase, type EchoDatabase, type AnyLiveObject } from '@dxos/echo-db';
+import { type Database, type Obj } from '@dxos/echo';
+import { type EchoDatabase, type QueueFactory, type SpaceSyncState } from '@dxos/echo-db';
 import { type PublicKey, type SpaceId } from '@dxos/keys';
+import { type Messenger } from '@dxos/protocols';
 import {
   type Contact,
   type CreateEpochRequest,
   type Invitation,
-  type Space as SpaceData,
   type SpaceArchive,
+  type Space as SpaceData,
   type SpaceMember,
   type SpaceState,
   type UpdateMemberRoleRequest,
@@ -19,9 +23,9 @@ import {
 import { type EdgeReplicationSetting } from '@dxos/protocols/proto/dxos/echo/metadata';
 import { type SpaceSnapshot } from '@dxos/protocols/proto/dxos/echo/snapshot';
 import { type Credential, type Epoch } from '@dxos/protocols/proto/dxos/halo/credentials';
-import { type GossipMessage } from '@dxos/protocols/proto/dxos/mesh/teleport/gossip';
 
 import { type CancellableInvitation } from './invitations';
+import { type SpaceProperties } from './types';
 
 export type CreateEpochOptions = {
   migration?: CreateEpochRequest.Migration;
@@ -29,17 +33,21 @@ export type CreateEpochOptions = {
 };
 
 export interface SpaceInternal {
+  get db(): EchoDatabase;
   get data(): SpaceData;
 
-  // TODO(dmaretskyi): Return epoch info.
-  createEpoch(options?: CreateEpochOptions): Promise<void>;
-
   getCredentials(): Promise<Credential[]>;
 
   getEpochs(): Promise<SpecificCredential<Epoch>[]>;
 
+  // TODO(dmaretskyi): Return epoch info.
+  createEpoch(options?: CreateEpochOptions): Promise<void>;
+
+  // TOOD(burdon): Start to factor out credentials.
   removeMember(memberKey: PublicKey): Promise<void>;
 
+  export(): Promise<SpaceArchive>;
+
   /**
    * Migrate space data to the latest version.
    */
@@ -47,15 +55,20 @@ export interface SpaceInternal {
 
   setEdgeReplicationPreference(setting: EdgeReplicationSetting): Promise<void>;
 
-  export(): Promise<SpaceArchive>;
-}
-
-// TODO(burdon): Separate public API form implementation (move comments here).
-export interface Space {
   /**
-   * Unique space identifier.
+   * Waits until the space is fully synced with EDGE.
+   * @throws If the EDGE sync is disabled.
    */
-  get id(): SpaceId;
+  syncToEdge(opts?: {
+    onProgress: (state: SpaceSyncState.PeerState | undefined) => void;
+    timeout?: number;
+  }): Promise<void>;
+}
+
+export const SPACE_TAG = Symbol('dxos.client.protocol.Space');
+
+export interface Space extends Messenger {
+  readonly [SPACE_TAG]: true;
 
   /**
    * @deprecated Use `id`.
@@ -63,29 +76,23 @@ export interface Space {
   get key(): PublicKey;
 
   /**
-   * Echo database.
+   * Unique space identifier.
    */
-  get db(): EchoDatabase;
+  get id(): SpaceId;
 
   /**
-   * Access to queues.
+   * Echo database.
    */
-  get queues(): QueueFactory;
+  get db(): Database.Database;
 
   /**
-   * Echo database CRUD API.
-   * @deprecated Use the database api with the `plain` format.
+   * Access to queues.
    */
-  // TODO(burdon): Remove.
-  get crud(): CoreDatabase;
+  get queues(): QueueFactory;
 
+  // TODO(burdon): Replace with state?
   get isOpen(): boolean;
 
-  /**
-   * Properties object.
-   */
-  get properties(): AnyLiveObject<any>;
-
   /**
    * Current state of the space.
    * The database is ready to be used in `SpaceState.SPACE_READY` state.
@@ -93,6 +100,11 @@ export interface Space {
    */
   get state(): MulticastObservable<SpaceState>;
 
+  /**
+   * Properties object.
+   */
+  get properties(): Obj.Obj<SpaceProperties>;
+
   /**
    * Current state of space pipeline.
    */
@@ -105,14 +117,14 @@ export interface Space {
   /**
    * @deprecated
    */
-  // TODO(wittjosiah): Remove. This should not be exposed.
+  // TODO(wittjosiah): Audit and remove. This should not be exposed (or marked as internal).
   get internal(): SpaceInternal;
 
-  // TODO(wittjosiah): Rename activate/deactivate?
   /**
    * Activates the space enabling the use of the database and starts replication with peers.
    * The setting is persisted on the local device.
    */
+  // TODO(wittjosiah): Rename activate/deactivate?
   open(): Promise<void>;
 
   /**
@@ -130,13 +142,17 @@ export interface Space {
   createSnapshot(): Promise<SpaceSnapshot>;
 
   // TODO(burdon): Create invitation?
+  // TODO(burdon): Factor out membership, etc.
   share(options?: Partial<Invitation>): CancellableInvitation;
-
   admitContact(contact: Contact): Promise<void>;
-
   updateMemberRole(request: Omit<UpdateMemberRoleRequest, 'spaceKey'>): Promise<void>;
-
-  // TODO(wittjosiah): Gather into messaging abstraction?
-  postMessage: (channel: string, message: any) => Promise<void>;
-  listen: (channel: string, callback: (message: GossipMessage) => void) => CleanupFn;
 }
+
+export const isSpace = (object: unknown): object is Space =>
+  typeof object === 'object' && object != null && (object as Space)[SPACE_TAG] === true;
+
+// TODO(burdon): Create lower-level definition (HasId, db, etc.) and move to @dxos/echo.
+export const SpaceSchema: Schema.Schema<Space> = Schema.Any.pipe(
+  Schema.filter((space) => isSpace(space)),
+  Schema.annotations({ title: 'Space' }),
+);

package/src/timeouts.ts

@@ -33,6 +33,11 @@ export const LOAD_PROPERTIES_TIMEOUT = 3_000;
  */
 export const CREATE_SPACE_TIMEOUT = 5_000;
 
+/**
+ * Timeout for creating new spaces.
+ */
+export const IMPORT_SPACE_TIMEOUT = 30_000;
+
 /**
  * Timeout for loading of control feeds.
  */

package/src/types/SpaceProperties.ts

@@ -0,0 +1,49 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import * as Schema from 'effect/Schema';
+
+import { Annotation, Type } from '@dxos/echo';
+import { Queue } from '@dxos/echo-db';
+
+export const SpacePropertiesSchema = Schema.Struct(
+  {
+    //
+    // System properties.
+    //
+
+    archived: Schema.optional(Schema.Boolean.annotations({ title: 'Archive Space' })),
+    // TODO(burdon): Change to mode (no booleans?)
+    // TODO(wittjosiah): Make optional with default value.
+    edgeReplication: Schema.optional(Schema.Boolean),
+    invocationTraceQueue: Schema.optional(Type.Ref(Queue)),
+
+    //
+    // User properties.
+    //
+
+    name: Schema.optional(Schema.String),
+    icon: Schema.optional(Schema.String),
+    hue: Schema.optional(Schema.String),
+  },
+  {
+    key: Schema.String,
+    value: Schema.Any,
+  },
+);
+
+export type SpacePropertiesSchema = Schema.Schema.Type<typeof SpacePropertiesSchema>;
+
+// TODO(burdon): Pipe Schem.optional, or partial to entire struct to make everything optional?
+// TODO(burdon): Is separate schema def required for forms? Can it be extracted from SpaceProperties?
+export const SpaceProperties = SpacePropertiesSchema.pipe(
+  Type.object({
+    // TODO(burdon): Rename SpaceProperties.
+    typename: 'dxos.org/type/Properties',
+    version: '0.1.0',
+  }),
+  Annotation.SystemTypeAnnotation.set(true),
+);
+
+export interface SpaceProperties extends Schema.Schema.Type<typeof SpaceProperties> {}

package/src/types/index.ts

@@ -0,0 +1,5 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export * from './SpaceProperties';