@dxos/edge-client 0.8.4-main.84f28bd → 0.8.4-main.a4bbb77

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dxos/edge-client",
-  "version": "0.8.4-main.84f28bd",
+  "version": "0.8.4-main.a4bbb77",
   "description": "EDGE Client",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
@@ -10,16 +10,19 @@
   "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"
     },
     "./muxer": {
+      "source": "./src/edge-ws-muxer.ts",
       "types": "./dist/types/src/edge-ws-muxer.d.ts",
       "browser": "./dist/lib/browser/edge-ws-muxer.mjs",
       "node": "./dist/lib/node-esm/edge-ws-muxer.mjs"
     },
     "./testing": {
+      "source": "./src/testing/index.ts",
       "types": "./dist/types/src/testing/index.d.ts",
       "browser": "./dist/lib/browser/testing/index.mjs",
       "node": "./dist/lib/node-esm/testing/index.mjs"
@@ -39,24 +42,24 @@
     "README.md"
   ],
   "dependencies": {
-    "@effect/platform": "^0.87.12",
+    "@effect/platform": "^0.92.1",
     "isomorphic-ws": "^5.0.0",
     "ws": "^8.14.2",
-    "@dxos/async": "0.8.4-main.84f28bd",
-    "@dxos/context": "0.8.4-main.84f28bd",
-    "@dxos/credentials": "0.8.4-main.84f28bd",
-    "@dxos/debug": "0.8.4-main.84f28bd",
-    "@dxos/crypto": "0.8.4-main.84f28bd",
-    "@dxos/invariant": "0.8.4-main.84f28bd",
-    "@dxos/keyring": "0.8.4-main.84f28bd",
-    "@dxos/keys": "0.8.4-main.84f28bd",
-    "@dxos/log": "0.8.4-main.84f28bd",
-    "@dxos/node-std": "0.8.4-main.84f28bd",
-    "@dxos/protocols": "0.8.4-main.84f28bd",
-    "@dxos/util": "0.8.4-main.84f28bd"
+    "@dxos/async": "0.8.4-main.a4bbb77",
+    "@dxos/context": "0.8.4-main.a4bbb77",
+    "@dxos/credentials": "0.8.4-main.a4bbb77",
+    "@dxos/crypto": "0.8.4-main.a4bbb77",
+    "@dxos/debug": "0.8.4-main.a4bbb77",
+    "@dxos/invariant": "0.8.4-main.a4bbb77",
+    "@dxos/log": "0.8.4-main.a4bbb77",
+    "@dxos/keyring": "0.8.4-main.a4bbb77",
+    "@dxos/keys": "0.8.4-main.a4bbb77",
+    "@dxos/node-std": "0.8.4-main.a4bbb77",
+    "@dxos/protocols": "0.8.4-main.a4bbb77",
+    "@dxos/util": "0.8.4-main.a4bbb77"
   },
   "devDependencies": {
-    "@dxos/test-utils": "0.8.4-main.84f28bd"
+    "@dxos/test-utils": "0.8.4-main.a4bbb77"
   },
   "peerDependencies": {
     "effect": "^3.13.3"

package/src/edge-client.ts

@@ -2,8 +2,8 @@
 // Copyright 2024 DXOS.org
 //
 
-import { Trigger, scheduleMicroTask, TriggerState, PersistentLifecycle, Event } from '@dxos/async';
-import { Resource, type Lifecycle } from '@dxos/context';
+import { Event, PersistentLifecycle, Trigger, TriggerState, scheduleMicroTask } from '@dxos/async';
+import { type Lifecycle, Resource } from '@dxos/context';
 import { log, logInfo } from '@dxos/log';
 import { type Message } from '@dxos/protocols/buf/dxos/edge/messenger_pb';
 import { EdgeStatus } from '@dxos/protocols/proto/dxos/client/services';
@@ -20,6 +20,13 @@ const DEFAULT_TIMEOUT = 10_000;
 export type MessageListener = (message: Message) => void;
 export type ReconnectListener = () => void;
 
+export type MessengerConfig = {
+  socketEndpoint: string;
+  timeout?: number;
+  protocol?: Protocol;
+  disableAuth?: boolean;
+};
+
 export interface EdgeConnection extends Required<Lifecycle> {
   statusChanged: Event<EdgeStatus>;
   get info(): any;
@@ -28,18 +35,11 @@ export interface EdgeConnection extends Required<Lifecycle> {
   get isOpen(): boolean;
   get status(): EdgeStatus;
   setIdentity(identity: EdgeIdentity): void;
+  send(message: Message): Promise<void>;
   onMessage(listener: MessageListener): () => void;
   onReconnected(listener: ReconnectListener): () => void;
-  send(message: Message): Promise<void>;
 }
 
-export type MessengerConfig = {
-  socketEndpoint: string;
-  timeout?: number;
-  protocol?: Protocol;
-  disableAuth?: boolean;
-};
-
 /**
  * Messenger client for EDGE:
  *  - While open, uses PersistentLifecycle to keep an open EdgeWsConnection, reconnecting on failures.
@@ -80,7 +80,7 @@ export class EdgeClient extends Resource implements EdgeConnection {
     };
   }
 
-  get status(): EdgeStatus {
+  get status() {
     return Boolean(this._currentConnection) && this._ready.state === TriggerState.RESOLVED
       ? EdgeStatus.CONNECTED
       : EdgeStatus.NOT_CONNECTED;
@@ -94,7 +94,7 @@ export class EdgeClient extends Resource implements EdgeConnection {
     return this._identity.peerKey;
   }
 
-  setIdentity(identity: EdgeIdentity): void {
+  setIdentity(identity: EdgeIdentity) {
     if (identity.identityKey !== this._identity.identityKey || identity.peerKey !== this._identity.peerKey) {
       log('Edge identity changed', { identity, oldIdentity: this._identity });
       this._identity = identity;
@@ -103,12 +103,36 @@ export class EdgeClient extends Resource implements EdgeConnection {
     }
   }
 
-  public onMessage(listener: MessageListener): () => void {
+  /**
+   * Send message.
+   * NOTE: The message is guaranteed to be delivered but the service must respond with a message to confirm processing.
+   */
+  public async send(message: Message) {
+    if (this._ready.state !== TriggerState.RESOLVED) {
+      log('waiting for websocket');
+      await this._ready.wait({ timeout: this._config.timeout ?? DEFAULT_TIMEOUT });
+    }
+
+    if (!this._currentConnection) {
+      throw new EdgeConnectionClosedError();
+    }
+
+    if (
+      message.source &&
+      (message.source.peerKey !== this._identity.peerKey || message.source.identityKey !== this.identityKey)
+    ) {
+      throw new EdgeIdentityChangedError();
+    }
+
+    this._currentConnection.send(message);
+  }
+
+  public onMessage(listener: MessageListener) {
     this._messageListeners.add(listener);
     return () => this._messageListeners.delete(listener);
   }
 
-  public onReconnected(listener: () => void): () => void {
+  public onReconnected(listener: () => void) {
     this._reconnectListeners.add(listener);
     if (this._ready.state === TriggerState.RESOLVED) {
       // Microtask so that listener is always called asynchronously, no matter the state of the ready trigger
@@ -123,6 +147,7 @@ export class EdgeClient extends Resource implements EdgeConnection {
         }
       });
     }
+
     return () => this._reconnectListeners.delete(listener);
   }
 
@@ -200,7 +225,6 @@ export class EdgeClient extends Resource implements EdgeConnection {
     // Race with restartRequired so that restart is not blocked by _connect execution.
     // Wait on ready to attempt a reconnect if it times out.
     await Promise.race([this._ready.wait({ timeout: this._config.timeout ?? DEFAULT_TIMEOUT }), restartRequired]);
-
     return connection;
   }
 
@@ -237,30 +261,6 @@ export class EdgeClient extends Resource implements EdgeConnection {
     }
   }
 
-  /**
-   * Send message.
-   * NOTE: The message is guaranteed to be delivered but the service must respond with a message to confirm processing.
-   */
-  public async send(message: Message): Promise<void> {
-    if (this._ready.state !== TriggerState.RESOLVED) {
-      log('waiting for websocket to become ready');
-      await this._ready.wait({ timeout: this._config.timeout ?? DEFAULT_TIMEOUT });
-    }
-
-    if (!this._currentConnection) {
-      throw new EdgeConnectionClosedError();
-    }
-
-    if (
-      message.source &&
-      (message.source.peerKey !== this._identity.peerKey || message.source.identityKey !== this.identityKey)
-    ) {
-      throw new EdgeIdentityChangedError();
-    }
-
-    this._currentConnection.send(message);
-  }
-
   private async _createAuthHeader(path: string): Promise<string | undefined> {
     const httpUrl = new URL(path, this._baseHttpUrl);
     httpUrl.protocol = getEdgeUrlWithProtocol(this._baseWsUrl.toString(), 'http');
@@ -277,7 +277,7 @@ export class EdgeClient extends Resource implements EdgeConnection {
 }
 
 const encodePresentationWsAuthHeader = (encodedPresentation: Uint8Array): string => {
-  // = and / characters are not allowed in the WebSocket subprotocol header.
+  // '=' and '/' characters are not allowed in the WebSocket subprotocol header.
   const encodedToken = Buffer.from(encodedPresentation).toString('base64').replace(/=*$/, '').replaceAll('/', '|');
   return `base64url.bearer.authorization.dxos.org.${encodedToken}`;
 };

package/src/edge-http-client.ts

@@ -10,39 +10,43 @@ import { Context } from '@dxos/context';
 import { type PublicKey, type SpaceId } from '@dxos/keys';
 import { log } from '@dxos/log';
 import {
-  type CreateAgentResponseBody,
   type CreateAgentRequestBody,
+  type CreateAgentResponseBody,
   type CreateSpaceRequest,
   type CreateSpaceResponseBody,
   EdgeAuthChallengeError,
   EdgeCallFailedError,
   type EdgeHttpResponse,
+  type EdgeStatus,
   type ExecuteWorkflowResponseBody,
+  type ExportBundleRequest,
+  type ExportBundleResponse,
   type GetAgentStatusResponseBody,
   type GetNotarizationResponseBody,
+  type ImportBundleRequest,
   type InitiateOAuthFlowRequest,
   type InitiateOAuthFlowResponse,
   type JoinSpaceRequest,
   type JoinSpaceResponseBody,
-  type RecoverIdentityRequest,
-  type RecoverIdentityResponseBody,
   type ObjectId,
   type PostNotarizationRequestBody,
-  type QueueQuery,
   type QueryResult,
+  type QueueQuery,
+  type RecoverIdentityRequest,
+  type RecoverIdentityResponseBody,
   type UploadFunctionRequest,
   type UploadFunctionResponseBody,
-  type EdgeStatus,
 } from '@dxos/protocols';
 import { createUrl } from '@dxos/util';
 
 import { type EdgeIdentity, handleAuthChallenge } from './edge-identity';
-import { encodeAuthHeader, HttpConfig, withLogging, withRetryConfig } from './http-client';
+import { HttpConfig, encodeAuthHeader, withLogging, withRetryConfig } from './http-client';
 import { getEdgeUrlWithProtocol } from './utils';
 
 const DEFAULT_RETRY_TIMEOUT = 1500;
 const DEFAULT_RETRY_JITTER = 500;
 const DEFAULT_MAX_RETRIES_COUNT = 3;
+const WARNING_BODY_SIZE = 10 * 1024 * 1024; // 10MB
 
 export type RetryConfig = {
   /**
@@ -64,6 +68,15 @@ type EdgeHttpRequestArgs = {
   context?: Context;
   retry?: RetryConfig;
   body?: any;
+  /**
+   * @default true
+   */
+  json?: boolean;
+
+  /**
+   * Do not expect a standard EDGE JSON response with a `success` field.
+   */
+  rawResponse?: boolean;
 };
 
 export type EdgeHttpGetArgs = Pick<EdgeHttpRequestArgs, 'context' | 'retry'>;
@@ -246,8 +259,63 @@ export class EdgeHttpClient {
     body: UploadFunctionRequest,
     args?: EdgeHttpGetArgs,
   ): Promise<UploadFunctionResponseBody> {
+    const formData = new FormData();
+    formData.append('name', body.name ?? '');
+    formData.append('version', body.version);
+    formData.append('ownerPublicKey', body.ownerPublicKey);
+    formData.append('entryPoint', body.entryPoint);
+    for (const [filename, content] of Object.entries(body.assets)) {
+      formData.append(
+        'assets',
+        new Blob([content as Uint8Array<ArrayBuffer>], { type: getFileMimeType(filename) }),
+        filename,
+      );
+    }
+
     const path = ['functions', ...(pathParts.functionId ? [pathParts.functionId] : [])].join('/');
-    return this._call(new URL(path, this.baseUrl), { ...args, body, method: 'PUT' });
+    return this._call(new URL(path, this.baseUrl), {
+      ...args,
+      body: formData,
+      method: 'PUT',
+      json: false,
+    });
+  }
+
+  public async listFunctions(args?: EdgeHttpGetArgs): Promise<any> {
+    return this._call(new URL('/functions', this.baseUrl), { ...args, method: 'GET' });
+  }
+
+  public async invokeFunction(
+    params: {
+      functionId: string;
+      version?: string;
+      spaceId?: SpaceId;
+      cpuTimeLimit?: number;
+      subrequestsLimit?: number;
+    },
+    input: unknown,
+    args?: EdgeHttpGetArgs,
+  ): Promise<any> {
+    const url = new URL(`/functions/${params.functionId}`, this.baseUrl);
+    if (params.version) {
+      url.searchParams.set('version', params.version);
+    }
+    if (params.spaceId) {
+      url.searchParams.set('spaceId', params.spaceId.toString());
+    }
+    if (params.cpuTimeLimit) {
+      url.searchParams.set('cpuTimeLimit', params.cpuTimeLimit.toString());
+    }
+    if (params.subrequestsLimit) {
+      url.searchParams.set('subrequestsLimit', params.subrequestsLimit.toString());
+    }
+
+    return this._call(url, {
+      ...args,
+      body: input,
+      method: 'POST',
+      rawResponse: true,
+    });
   }
 
   //
@@ -267,6 +335,38 @@ export class EdgeHttpClient {
     });
   }
 
+  //
+  // Triggers
+  //
+
+  public async getCronTriggers(spaceId: SpaceId) {
+    return this._call(new URL(`/test/functions/${spaceId}/triggers/crons`, this.baseUrl), { method: 'GET' });
+  }
+
+  //
+  // Import/Export space.
+  //
+
+  public async importBundle(
+    spaceId: SpaceId, //
+    body: ImportBundleRequest,
+    args?: EdgeHttpGetArgs,
+  ): Promise<void> {
+    return this._call(new URL(`/spaces/${spaceId}/import`, this.baseUrl), { ...args, body, method: 'PUT' });
+  }
+
+  public async exportBundle(
+    spaceId: SpaceId,
+    body: ExportBundleRequest,
+    args?: EdgeHttpGetArgs,
+  ): Promise<ExportBundleResponse> {
+    return this._call(new URL(`/spaces/${spaceId}/export`, this.baseUrl), {
+      ...args,
+      body,
+      method: 'POST',
+    });
+  }
+
   //
   // Internal
   //
@@ -291,7 +391,7 @@ export class EdgeHttpClient {
 
     let handledAuth = false;
     while (true) {
-      let processingError: EdgeCallFailedError;
+      let processingError: EdgeCallFailedError | undefined = undefined;
       let retryAfterHeaderValue: number = Number.NaN;
       try {
         const request = createRequest(args, this._authHeader);
@@ -299,6 +399,15 @@ export class EdgeHttpClient {
         retryAfterHeaderValue = Number(response.headers.get('Retry-After'));
         if (response.ok) {
           const body = (await response.json()) as EdgeHttpResponse<T>;
+
+          if (args.rawResponse) {
+            return body as any;
+          }
+
+          if (!('success' in body)) {
+            return body;
+          }
+
           if (body.success) {
             return body.data;
           }
@@ -306,7 +415,7 @@ export class EdgeHttpClient {
           log.warn('unsuccessful edge response', { url, body });
           if (body.errorData?.type === 'auth_challenge' && typeof body.errorData?.challenge === 'string') {
             processingError = new EdgeAuthChallengeError(body.errorData.challenge, body.errorData);
-          } else {
+          } else if (body.errorData) {
             processingError = EdgeCallFailedError.fromUnsuccessfulResponse(response, body);
           }
         } else if (response.status === 401 && !handledAuth) {
@@ -314,16 +423,16 @@ export class EdgeHttpClient {
           handledAuth = true;
           continue;
         } else {
-          processingError = EdgeCallFailedError.fromHttpFailure(response);
+          processingError = await EdgeCallFailedError.fromHttpFailure(response);
         }
       } catch (error: any) {
         processingError = EdgeCallFailedError.fromProcessingFailureCause(error);
       }
 
-      if (processingError.isRetryable && (await shouldRetry(requestContext, retryAfterHeaderValue))) {
+      if (processingError?.isRetryable && (await shouldRetry(requestContext, retryAfterHeaderValue))) {
         log('retrying edge request', { url, processingError });
       } else {
-        throw processingError;
+        throw processingError!;
       }
     }
   }
@@ -331,7 +440,7 @@ export class EdgeHttpClient {
   private async _handleUnauthorized(response: Response): Promise<string> {
     if (!this._edgeIdentity) {
       log.warn('unauthorized response received before identity was set');
-      throw EdgeCallFailedError.fromHttpFailure(response);
+      throw await EdgeCallFailedError.fromHttpFailure(response);
     }
 
     const challenge = await handleAuthChallenge(response, this._edgeIdentity);
@@ -339,11 +448,32 @@ export class EdgeHttpClient {
   }
 }
 
-const createRequest = ({ method, body }: EdgeHttpRequestArgs, authHeader: string | undefined): RequestInit => {
+const createRequest = (
+  { method, body, json = true }: EdgeHttpRequestArgs,
+  authHeader: string | undefined,
+): RequestInit => {
+  let requestBody: BodyInit | undefined;
+  const headers: HeadersInit = {};
+
+  if (json) {
+    requestBody = body && JSON.stringify(body);
+    headers['Content-Type'] = 'application/json';
+  } else {
+    requestBody = body;
+  }
+
+  if (typeof requestBody === 'string' && requestBody.length > WARNING_BODY_SIZE) {
+    log.warn('Request with large body', { bodySize: requestBody.length });
+  }
+
+  if (authHeader) {
+    headers['Authorization'] = authHeader;
+  }
+
   return {
     method,
-    body: body && JSON.stringify(body),
-    headers: authHeader ? { Authorization: authHeader } : undefined,
+    body: requestBody,
+    headers,
   };
 };
 
@@ -374,3 +504,10 @@ const createRetryHandler = ({ retry }: EdgeHttpRequestArgs) => {
     return true;
   };
 };
+
+const getFileMimeType = (filename: string) =>
+  ['.js', '.mjs'].some((codeExtension) => filename.endsWith(codeExtension))
+    ? 'application/javascript+module'
+    : filename.endsWith('.wasm')
+      ? 'application/wasm'
+      : 'application/octet-stream';

package/src/edge-ws-connection.ts

@@ -10,7 +10,7 @@ import { invariant } from '@dxos/invariant';
 import { log, logInfo } from '@dxos/log';
 import { EdgeWebsocketProtocol } from '@dxos/protocols';
 import { buf } from '@dxos/protocols/buf';
-import { MessageSchema, type Message } from '@dxos/protocols/buf/dxos/edge/messenger_pb';
+import { type Message, MessageSchema } from '@dxos/protocols/buf/dxos/edge/messenger_pb';
 
 import { protocol } from './defs';
 import { type EdgeIdentity } from './edge-identity';
@@ -30,6 +30,7 @@ export class EdgeWsConnection extends Resource {
   private _inactivityTimeoutCtx: Context | undefined;
   private _ws: WebSocket | undefined;
   private _wsMuxer: WebSocketMuxer | undefined;
+  private _lastReceivedMessageTimestamp = Date.now();
 
   constructor(
     private readonly _identity: EdgeIdentity,
@@ -111,6 +112,7 @@ export class EdgeWsConnection extends Resource {
         log.verbose('message ignored on closed connection', { event: event.type });
         return;
       }
+      this._lastReceivedMessageTimestamp = Date.now();
       if (event.data === '__pong__') {
         this._rescheduleHeartbeatTimeout();
         return;
@@ -172,8 +174,14 @@ export class EdgeWsConnection extends Resource {
       this._inactivityTimeoutCtx,
       () => {
         if (this.isOpen) {
-          log.warn('restart due to inactivity timeout');
-          this._callbacks.onRestartRequired();
+          if (Date.now() - this._lastReceivedMessageTimestamp > SIGNAL_KEEPALIVE_TIMEOUT) {
+            log.warn('restart due to inactivity timeout', {
+              lastReceivedMessageTimestamp: this._lastReceivedMessageTimestamp,
+            });
+            this._callbacks.onRestartRequired();
+          } else {
+            this._rescheduleHeartbeatTimeout();
+          }
         }
       },
       SIGNAL_KEEPALIVE_TIMEOUT,

package/src/edge-ws-muxer.ts

@@ -5,7 +5,7 @@
 import { Trigger } from '@dxos/async';
 import { log } from '@dxos/log';
 import { buf } from '@dxos/protocols/buf';
-import { MessageSchema, type Message } from '@dxos/protocols/buf/dxos/edge/messenger_pb';
+import { type Message, MessageSchema } from '@dxos/protocols/buf/dxos/edge/messenger_pb';
 
 import { protocol } from './defs';
 

package/src/http-client.test.ts

@@ -18,14 +18,14 @@ describe('HttpClient', () => {
     server = await createTestServer(responseHandler((attempt) => (attempt > 2 ? { value: 100 } : false)));
   });
 
-  // eslint-disable-next-line mocha/no-top-level-hooks
   afterEach(() => {
     server?.close();
     server = undefined;
   });
 
-  // TODO(burdon): Auth headers.
+  // TODO(burdon): Auth headers/API key for admin.
   // TODO(burdon): Add request/response schema type checking.
+  // TODO(burdon): Test swarm.
   it.skipIf(process.env.CI)('should retry', async ({ expect }) => {
     invariant(server);
 

package/src/index.ts

@@ -4,11 +4,12 @@
 
 export * from '@dxos/protocols/buf/dxos/edge/messenger_pb';
 
-export * from './edge-client';
+export * from './auth';
 export * from './defs';
-export * from './protocol';
+export * from './edge-client';
 export * from './errors';
-export * from './auth';
+export * from './protocol';
 export * from './edge-http-client';
 export * from './edge-identity';
 export * from './edge-ws-muxer';
+export * from './http-client';

package/src/testing/test-utils.ts

@@ -8,7 +8,7 @@ import { Trigger } from '@dxos/async';
 import { log } from '@dxos/log';
 import { EdgeWebsocketProtocol } from '@dxos/protocols';
 import { buf } from '@dxos/protocols/buf';
-import { MessageSchema, TextMessageSchema, type Message } from '@dxos/protocols/buf/dxos/edge/messenger_pb';
+import { type Message, MessageSchema, TextMessageSchema } from '@dxos/protocols/buf/dxos/edge/messenger_pb';
 
 import { protocol } from '../defs';
 import { WebSocketMuxer } from '../edge-ws-muxer';

package/src/websocket.test.ts

@@ -3,7 +3,7 @@
 //
 
 import WebSocket from 'isomorphic-ws';
-import { describe, expect, test, onTestFinished } from 'vitest';
+import { describe, expect, onTestFinished, test } from 'vitest';
 
 import { Trigger, TriggerState } from '@dxos/async';