@dxos/protocols 0.8.4-main.f9ba587 → 0.8.4-main.fcc0d83b33

package/src/edge/registry.ts

@@ -0,0 +1,125 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Schema from 'effect/Schema';
+
+/**
+ * Hydrated plugin metadata, mirroring the @dxos/app-framework `Plugin.Meta` shape.
+ *
+ * Defined locally rather than imported from @dxos/app-framework to keep the protocols
+ * package free of UI/runtime dependencies. Consumers can treat decoded values as
+ * `Plugin.Meta` directly.
+ */
+export const PluginMetaSchema = Schema.Struct({
+  id: Schema.String.pipe(Schema.nonEmptyString()),
+  name: Schema.String.pipe(Schema.nonEmptyString()),
+  description: Schema.optional(Schema.String),
+  author: Schema.optional(Schema.String),
+  homePage: Schema.optional(Schema.String),
+  source: Schema.optional(Schema.String),
+  screenshots: Schema.optional(Schema.Array(Schema.String)),
+  tags: Schema.optional(Schema.Array(Schema.String)),
+  icon: Schema.optional(Schema.String),
+  iconHue: Schema.optional(Schema.String),
+});
+export type PluginMeta = Schema.Schema.Type<typeof PluginMetaSchema>;
+
+/**
+ * Health signal the registry service attaches to a hydrated entry when a refresh fails.
+ * Clients surface the appropriate badge or filter entries based on this field.
+ */
+export const PluginHealthSchema = Schema.Literal('ok', 'release-missing', 'manifest-invalid', 'repo-unavailable');
+export type PluginHealth = Schema.Schema.Type<typeof PluginHealthSchema>;
+
+/**
+ * Filename of the entry module every plugin must publish at the root of its bundle.
+ * The host dynamic-imports `<manifest URL base>/index.mjs` directly — no per-plugin
+ * configuration. `composerPlugin` outputs the bundle under this name so plugin authors
+ * never have to think about it.
+ */
+export const PLUGIN_ENTRY_FILENAME = 'index.mjs';
+
+/**
+ * Shape of the manifest-asset JSON the registry service fetches from each plugin's latest release.
+ *
+ * Emitted by `@dxos/app-framework/vite-plugin`'s `composerPlugin` (see
+ * `MANIFEST_ASSET_NAME`). Lists every file the plugin needs at runtime — the entry
+ * module ({@link PLUGIN_ENTRY_FILENAME}) plus any sibling CSS, code-split chunks,
+ * fonts, etc. — so the host can eagerly precache the whole bundle for offline use.
+ * Paths in `assets` are relative to the manifest's URL.
+ */
+export const PluginManifestSchema = Schema.Struct({
+  ...PluginMetaSchema.fields,
+  /** Plugin version (semver). Sourced from the publishing project's `package.json`. */
+  version: Schema.String.pipe(Schema.nonEmptyString()),
+  /**
+   * Relative paths of every file the plugin needs at runtime, including the entry.
+   * Must include {@link PLUGIN_ENTRY_FILENAME}; consumers verify on parse.
+   */
+  assets: Schema.Array(Schema.String).pipe(Schema.minItems(1)),
+});
+export type PluginManifest = Schema.Schema.Type<typeof PluginManifestSchema>;
+
+/**
+ * Single hydrated plugin entry returned by the registry service.
+ */
+export const PluginEntrySchema = Schema.Struct({
+  /** GitHub repository in `owner/name` form. Empty string for entries sourced from a `manifestUrl`. */
+  repo: Schema.String,
+  /** Plugin metadata from the repo's latest-release `manifest.json`. */
+  meta: PluginMetaSchema,
+  /**
+   * URL of the plugin's `manifest.json`. Composer's URL loader fetches this, eagerly caches
+   * every declared asset via the platform `PluginAssetCache`, then dynamic-imports the entry.
+   * The URL must be CORS-safe and have its declared assets reachable as siblings.
+   */
+  moduleUrl: Schema.String,
+  /** Release tag the entry was resolved from (e.g. `v0.1.0`). Empty string for `manifestUrl` entries. */
+  releaseTag: Schema.String,
+  /** Health signal set by the service when an entry fails to refresh. */
+  health: PluginHealthSchema,
+  /** Unix ms when this entry was last successfully hydrated. */
+  hydratedAt: Schema.Number,
+});
+export type PluginEntry = Schema.Schema.Type<typeof PluginEntrySchema>;
+
+/**
+ * Response body of `GET /registry/plugins`.
+ */
+export const GetPluginsResponseBodySchema = Schema.Struct({
+  /** Wire-format schema version, pinned to 1. */
+  version: Schema.Literal(1),
+  /** Hydrated entries. Order matches the order in the upstream catalog manifest. */
+  plugins: Schema.Array(PluginEntrySchema),
+  /** Unix ms timestamp of the most recent successful refresh cycle. */
+  refreshedAt: Schema.Number,
+});
+export type GetPluginsResponseBody = Schema.Schema.Type<typeof GetPluginsResponseBodySchema>;
+
+/**
+ * A catalog entry. Two flavours:
+ *  - `{ repo }`: the registry service hydrates from the GitHub repo's latest release.
+ *    Used by the production catalog.
+ *  - `{ manifestUrl }`: the registry service skips GitHub and fetches the manifest directly.
+ *    Used for local development against an in-progress plugin (e.g. served by `vite preview`)
+ *    so authors can iterate without publishing a release.
+ */
+export const RegistryEntrySchema = Schema.Union(
+  Schema.Struct({ repo: Schema.String.pipe(Schema.nonEmptyString()) }),
+  Schema.Struct({ manifestUrl: Schema.String.pipe(Schema.nonEmptyString()) }),
+);
+export type RegistryEntry = Schema.Schema.Type<typeof RegistryEntrySchema>;
+
+/**
+ * Shape of the catalog manifest published in the upstream community-plugins repo.
+ * Extra keys (e.g. `$schema`) are permitted.
+ */
+export const RegistryManifestSchema = Schema.Struct(
+  {
+    version: Schema.Literal(1),
+    plugins: Schema.Array(RegistryEntrySchema),
+  },
+  Schema.Record({ key: Schema.String, value: Schema.Unknown }),
+);
+export type RegistryManifest = Schema.Schema.Type<typeof RegistryManifestSchema>;

package/src/errors/base-errors.ts

@@ -6,37 +6,21 @@
  * NOTE: Messages should be sentences (Start with a capital letter and end with a period).
  * Errors can optionally include a JSON context object.
  */
-export class BaseError extends Error {
-  constructor(
-    readonly code: string,
-    message?: string,
-    readonly context?: Record<string, any>,
-  ) {
-    // TODO(dmaretskyi): Error.cause.
-    super(message ?? code);
-    this.name = code;
-    // NOTE: Restores prototype chain (https://stackoverflow.com/a/48342359).
-    Object.setPrototypeOf(this, new.target.prototype);
-  }
-}
-
-// TODO(dmaretskyi): Consider common error classes with error codes:
-// throw new SystemError(ERROR_CODE_OUT_OF_MEMORY, 'Out of memory', { a: 1, b: 2 });
+import { BaseError } from '@dxos/errors';
 
 /**
  * User facing API Errors.
  * E.g., something was misconfigured.
  */
-export class ApiError extends BaseError {}
+export class ApiError extends BaseError.extend('ApiError') {}
 
 /**
  * Internal system errors.
  * E.g., unexpected/unrecoverable runtime error.
  */
-export class SystemError extends BaseError {}
+export class SystemError extends BaseError.extend('SystemError') {}
 
 /**
  * Database errors.
  */
-// TODO(wittjosiah): Same as ApiError?
-export class DatabaseError extends BaseError {}
+export class DatabaseError extends BaseError.extend('DatabaseError') {}

package/src/errors/encoding.ts

@@ -2,8 +2,8 @@
 // Copyright 2023 DXOS.org
 //
 
-import { reconstructError } from './helpers.js';
-import { type Error as SerializedErrorProto } from '../proto/gen/dxos/error.js';
+import { type Error as SerializedErrorProto } from '../proto/gen/dxos/error.ts';
+import { reconstructError } from './helpers.ts';
 
 export const encodeError = (err: any): SerializedErrorProto => {
   if (typeof err === 'object' && err?.message) {

package/src/errors/errors.test.ts

@@ -4,12 +4,12 @@
 
 import { describe, expect, test } from 'vitest';
 
-import { ApiError } from './base-errors.js';
+import { ApiError } from './base-errors.ts';
 
 describe('Errors', () => {
   test('test', async () => {
     const runTest = async () => {
-      throw new ApiError('Test error');
+      throw new ApiError({ message: 'Test error' });
     };
 
     await expect(runTest()).rejects.toThrowError('Test error');

package/src/errors/errors.ts

@@ -2,207 +2,141 @@
 // Copyright 2021 DXOS.org
 //
 
+import { BaseError } from '@dxos/errors';
 import { PublicKey } from '@dxos/keys';
 
-import { ApiError, BaseError, DatabaseError, SystemError } from './base-errors.js';
-import { registerError, registerErrorMessageContext, registerErrorNoArgs } from './helpers.js';
-import type { ObjectId } from '../types.js';
+import type { ObjectId } from '../types.ts';
+import { registerError, registerErrorMessageContext, registerErrorNoArgs } from './helpers.ts';
 
 /**
  * Thrown when request was terminated because the RPC endpoint has been closed.
  */
-export class RpcClosedError extends SystemError {
-  constructor() {
-    super('RPC_CLOSED', 'Request was terminated because the RPC endpoint is closed.');
-  }
-}
+export class RpcClosedError extends BaseError.extend(
+  'RpcClosedError',
+  'Request was terminated because the RPC endpoint is closed.',
+) {}
 
-registerErrorNoArgs('RPC_CLOSED', RpcClosedError);
+registerErrorNoArgs('RpcClosedError', RpcClosedError);
 
 /**
  * Thrown when `request` is called when RPC has not been opened.
  */
-export class RpcNotOpenError extends SystemError {
-  constructor() {
-    super('RPC_NOT_OPEN', 'RPC has not been opened.');
-  }
-}
+export class RpcNotOpenError extends BaseError.extend('RpcNotOpenError', 'RPC has not been opened.') {}
 
-registerErrorNoArgs('RPC_NOT_OPEN', RpcNotOpenError);
+registerErrorNoArgs('RpcNotOpenError', RpcNotOpenError);
 
-export class CancelledError extends SystemError {
-  constructor(message?: string, context?: Record<string, any>) {
-    super('CANCELLED', message, context);
-  }
-}
+export class CancelledError extends BaseError.extend('CancelledError') {}
 
-registerErrorMessageContext('CANCELLED', CancelledError);
+registerErrorMessageContext('CancelledError', CancelledError);
 
-export class InvalidConfigError extends ApiError {
-  constructor(message?: string, context?: Record<string, any>) {
-    super('INVALID_CONFIG', message, context);
-  }
-}
+export class InvalidConfigError extends BaseError.extend('InvalidConfigError') {}
 
-registerErrorMessageContext('INVALID_CONFIG', InvalidConfigError);
+registerErrorMessageContext('InvalidConfigError', InvalidConfigError);
 
 /**
  * Explicit failure to connect with remote client services.
  */
-export class RemoteServiceConnectionError extends ApiError {
-  constructor(message?: string, context?: Record<string, any>) {
-    super('REMOTE_SERVICE_CONNECTION_ERROR', message, context);
-  }
-}
+export class RemoteServiceConnectionError extends BaseError.extend('RemoteServiceConnectionError') {}
 
-registerErrorMessageContext('REMOTE_SERVICE_CONNECTION_ERROR', RemoteServiceConnectionError);
+registerErrorMessageContext('RemoteServiceConnectionError', RemoteServiceConnectionError);
 
 /**
  * Failed to open a connection to remote client services.
  */
-export class RemoteServiceConnectionTimeout extends ApiError {
-  constructor(message?: string, context?: Record<string, any>) {
-    super('REMOTE_SERVICE_CONNECTION_TIMEOUT', message, context);
-  }
-}
+export class RemoteServiceConnectionTimeout extends BaseError.extend('RemoteServiceConnectionTimeout') {}
 
-registerErrorMessageContext('REMOTE_SERVICE_CONNECTION_TIMEOUT', RemoteServiceConnectionTimeout);
+registerErrorMessageContext('RemoteServiceConnectionTimeout', RemoteServiceConnectionTimeout);
 
-export class DataCorruptionError extends SystemError {
-  constructor(message?: string, context?: Record<string, any>) {
-    super('DATA_CORRUPTION', message, context);
-  }
-}
+export class DataCorruptionError extends BaseError.extend('DataCorruptionError') {}
 
-registerErrorMessageContext('DATA_CORRUPTION', DataCorruptionError);
+registerErrorMessageContext('DataCorruptionError', DataCorruptionError);
 
-export class InvalidInvitationExtensionRoleError extends SystemError {
-  constructor(message?: string, context?: Record<string, any>) {
-    super('INVALID_INVITATION_EXTENSION_ROLE', message, context);
-  }
-}
+export class InvalidInvitationExtensionRoleError extends BaseError.extend('InvalidInvitationExtensionRoleError') {}
 
-registerErrorMessageContext('INVALID_INVITATION_EXTENSION_ROLE', InvalidInvitationExtensionRoleError);
+registerErrorMessageContext('InvalidInvitationExtensionRoleError', InvalidInvitationExtensionRoleError);
 
-export class IdentityNotInitializedError extends DatabaseError {
-  constructor(message?: string, context?: Record<string, any>) {
-    super('IDENTITY_NOT_INITIALIZED', message, context);
-  }
-}
+export class IdentityNotInitializedError extends BaseError.extend('IdentityNotInitializedError') {}
 
-registerErrorMessageContext('IDENTITY_NOT_INITIALIZED', IdentityNotInitializedError);
+registerErrorMessageContext('IdentityNotInitializedError', IdentityNotInitializedError);
 
-export class InvalidInvitationError extends DatabaseError {
-  constructor(message?: string, context?: Record<string, any>) {
-    super('INVALID_INVITATION', message, context);
-  }
-}
+export class InvalidInvitationError extends BaseError.extend('InvalidInvitationError') {}
 
-registerErrorMessageContext('INVALID_INVITATION', InvalidInvitationError);
+registerErrorMessageContext('InvalidInvitationError', InvalidInvitationError);
 
-export class AlreadyJoinedError extends DatabaseError {
-  constructor(message?: string, context?: Record<string, any>) {
-    super('ALREADY_JOINED', message, context);
-  }
-}
+export class AlreadyJoinedError extends BaseError.extend('AlreadyJoinedError') {}
 
-registerErrorMessageContext('ALREADY_JOINED', AlreadyJoinedError);
+registerErrorMessageContext('AlreadyJoinedError', AlreadyJoinedError);
 
-export class ConnectionResetError extends BaseError {
-  constructor(message?: string, context?: any) {
-    super('CONNECTION_RESET', message, context);
-  }
-}
+export class ConnectionResetError extends BaseError.extend('ConnectionResetError') {}
 
-registerErrorMessageContext('CONNECTION_RESET', ConnectionResetError);
+registerErrorMessageContext('ConnectionResetError', ConnectionResetError);
 
-export class TimeoutError extends BaseError {
-  constructor(message?: string, context?: any) {
-    super('TIMEOUT', message, context);
-  }
-}
+export class TimeoutError extends BaseError.extend('TimeoutError') {}
 
-registerErrorMessageContext('TIMEOUT', TimeoutError);
+registerErrorMessageContext('TimeoutError', TimeoutError);
 
 // General protocol error.
-export class ProtocolError extends BaseError {
-  constructor(message?: string, context?: any) {
-    super('PROTOCOL_ERROR', message, context);
-  }
-}
+export class ProtocolError extends BaseError.extend('ProtocolError') {}
 
-registerErrorMessageContext('PROTOCOL_ERROR', ProtocolError);
+registerErrorMessageContext(ProtocolError.name, ProtocolError);
 
 // General connectivity errors.
-export class ConnectivityError extends BaseError {
-  constructor(message?: string, context?: any) {
-    super('CONNECTIVITY_ERROR', message, context);
-  }
-}
+export class ConnectivityError extends BaseError.extend('ConnectivityError') {}
 
-registerErrorMessageContext('CONNECTIVITY_ERROR', ConnectivityError);
+registerErrorMessageContext('ConnectivityError', ConnectivityError);
 
-export class RateLimitExceededError extends BaseError {
-  constructor(message?: string, context?: any) {
-    super('RATE_LIMIT_EXCEEDED', message, context);
-  }
-}
+export class RateLimitExceededError extends BaseError.extend('RateLimitExceededError') {}
 
-registerErrorMessageContext('RATE_LIMIT_EXCEEDED', RateLimitExceededError);
+registerErrorMessageContext('RateLimitExceededError', RateLimitExceededError);
 
 // TODO(nf): Rename? the protocol isn't what's unknown...
-export class UnknownProtocolError extends BaseError {
-  constructor(message?: string, innerError?: Error) {
-    super('UNKNOWN_PROTOCOL_ERROR', message, innerError);
-  }
-}
+export class UnknownProtocolError extends BaseError.extend('UnknownProtocolError') {}
 
-registerErrorMessageContext('UNKNOWN_PROTOCOL_ERROR', UnknownProtocolError);
+registerError(UnknownProtocolError.name, (message, context) => new UnknownProtocolError({ message, context }));
 
-export class InvalidStorageVersionError extends DatabaseError {
+export class InvalidStorageVersionError extends BaseError.extend(
+  'InvalidStorageVersionError',
+  'Invalid storage version.',
+) {
   constructor(expected: number, actual: number) {
-    super('INVALID_STORAGE_VERSION', 'Invalid storage version.', { expected, actual });
+    super({ context: { expected, actual } });
   }
 }
 
-registerError('INVALID_STORAGE_VERSION', (_, context) => {
+registerError('InvalidStorageVersionError', (_, context) => {
   return new InvalidStorageVersionError(context.expected ?? NaN, context.actual ?? NaN);
 });
 
-export class SpaceNotFoundError extends DatabaseError {
+export class SpaceNotFoundError extends BaseError.extend('SpaceNotFoundError', 'Space not found.') {
   constructor(spaceKey: PublicKey) {
-    super('SPACE_NOT_FOUND', 'Space not found.', { spaceKey });
+    super({ context: { spaceKey } });
   }
 }
 
-registerError('SPACE_NOT_FOUND', (_, context) => {
+registerError('SpaceNotFoundError', (_, context) => {
   return new SpaceNotFoundError(PublicKey.safeFrom(context.spaceKey) ?? PublicKey.from('00'));
 });
 
-export class EntityNotFoundError extends DatabaseError {
+export class EntityNotFoundError extends BaseError.extend('EntityNotFoundError', 'Item not found.') {
   constructor(entityId: ObjectId) {
-    super('ITEM_NOT_FOUND', 'Item not found.', { entityId });
+    super({ context: { entityId } });
   }
 }
 
-registerError('ITEM_NOT_FOUND', (_, context) => {
+registerError('EntityNotFoundError', (_, context) => {
   return new EntityNotFoundError(context.entityId);
 });
 
-export class UnknownModelError extends DatabaseError {
+export class UnknownModelError extends BaseError.extend('UnknownModelError', 'Unknown model.') {
   constructor(model: string) {
-    super('UNKNOWN_MODEL', 'Unknown model.', { model });
+    super({ context: { model } });
   }
 }
 
-registerError('UNKNOWN_MODEL', (_, context) => {
+registerError('UnknownModelError', (_, context) => {
   return new UnknownModelError(context.model);
 });
 
-export class AuthorizationError extends ApiError {
-  constructor(message?: string, context?: any) {
-    super('AUTHORIZATION_ERROR', message, context);
-  }
-}
+export class AuthorizationError extends BaseError.extend('AuthorizationError') {}
 
-registerErrorMessageContext('AUTHORIZATION_ERROR', AuthorizationError);
+registerErrorMessageContext('AuthorizationError', AuthorizationError);

package/src/errors/helpers.ts

@@ -2,10 +2,10 @@
 // Copyright 2023 DXOS.org
 //
 
+import { BaseError } from '@dxos/errors';
 import { invariant } from '@dxos/invariant';
 
-import { SystemError } from './base-errors.js';
-import { type Error as SerializedErrorProto } from '../proto/gen/dxos/error.js';
+import { type Error as SerializedErrorProto } from '../proto/gen/dxos/error.ts';
 
 export const reconstructError = (error: SerializedErrorProto) => {
   const { name, message, context } = error;
@@ -19,21 +19,21 @@ export const registerError = (code: string, make: (message?: string, context?: a
   errorRegistry.set(code, make);
 };
 
-export const registerErrorNoArgs = (code: string, Constructor: { new (): Error }) => {
+export const registerErrorNoArgs = (code: string, Constructor: { new (options?: any): Error }) => {
   registerError(code, () => new Constructor());
 };
 
 export const registerErrorMessageContext = (
   code: string,
-  Constructor: { new (message?: string, context?: any): Error },
+  Constructor: { new (options?: { message?: string; context?: any }): Error },
 ) => {
-  registerError(code, (message?: string, context?: string) => new Constructor(message, context));
+  registerError(code, (message?: string, context?: any) => new Constructor({ message, context }));
 };
 
 export const errorFromCode = (code?: string, message?: string, context?: any) => {
   if (code && errorRegistry.has(code)) {
     return errorRegistry.get(code)!(message, context);
   } else {
-    return new SystemError(code ?? 'Error', message, context);
+    return new BaseError(code ?? 'Error', { message, context });
   }
 };

package/src/errors/index.ts

@@ -2,8 +2,8 @@
 // Copyright 2022 DXOS.org
 //
 
-export * from './encoding.js';
-export * from './errors.js';
-export * from './helpers.js';
-export * from './base-errors.js';
-export * from './parameter.js';
+export * from './encoding.ts';
+export * from './errors.ts';
+export * from './helpers.ts';
+export * from './base-errors.ts';
+export * from './parameter.ts';

package/src/feed-replication.ts

@@ -12,6 +12,7 @@ export type FeedBlock = {
   }[];
   signature: Uint8Array;
 };
+
 export type GetMetadataProtocolMessage = {
   type: 'get-metadata';
   feedKey: string;

package/src/index.ts

@@ -2,15 +2,14 @@
 // Copyright 2021 DXOS.org
 //
 
-export * from './errors/index.js';
-export * from './indexing.js';
-export * from './storage.js';
-export * from './tracing.js';
-export * from './types.js';
-export * from './query.js';
-export * from './profile-archive.js';
-export * from './automerge.js';
-export * from './edge.js';
-export * 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';

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,7 +2,7 @@
 // Copyright 2024 DXOS.org
 //
 
-import { Schema } from 'effect';
+import * as Schema from 'effect/Schema';
 
 import { ParamKeyAnnotation } from '@dxos/effect';
 

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>;
+}