@dxos/edge-client 0.8.4-main.fffef41 → 0.9.0

package/package.json

@@ -1,68 +1,69 @@
 {
   "name": "@dxos/edge-client",
-  "version": "0.8.4-main.fffef41",
+  "version": "0.9.0",
   "description": "EDGE Client",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
-  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dxos/dxos"
+  },
+  "license": "FSL-1.1-Apache-2.0",
   "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"
+      "default": "./dist/lib/neutral/index.mjs"
+    },
+    "./cors-proxy": {
+      "source": "./src/cors-proxy.ts",
+      "types": "./dist/types/src/cors-proxy.d.ts",
+      "default": "./dist/lib/neutral/cors-proxy.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"
+      "default": "./dist/lib/neutral/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"
+      "default": "./dist/lib/neutral/testing/index.mjs"
     }
   },
   "types": "dist/types/src/index.d.ts",
-  "typesVersions": {
-    "*": {
-      "testing": [
-        "dist/types/src/testing/index.d.ts"
-      ]
-    }
-  },
   "files": [
     "dist",
     "src",
     "README.md"
   ],
   "dependencies": {
-    "@effect/platform": "^0.92.1",
+    "@effect/platform": "0.96.1",
+    "@opentelemetry/api": "^1.9.1",
     "isomorphic-ws": "^5.0.0",
-    "ws": "^8.14.2",
-    "@dxos/async": "0.8.4-main.fffef41",
-    "@dxos/context": "0.8.4-main.fffef41",
-    "@dxos/credentials": "0.8.4-main.fffef41",
-    "@dxos/crypto": "0.8.4-main.fffef41",
-    "@dxos/debug": "0.8.4-main.fffef41",
-    "@dxos/invariant": "0.8.4-main.fffef41",
-    "@dxos/node-std": "0.8.4-main.fffef41",
-    "@dxos/log": "0.8.4-main.fffef41",
-    "@dxos/keys": "0.8.4-main.fffef41",
-    "@dxos/keyring": "0.8.4-main.fffef41",
-    "@dxos/protocols": "0.8.4-main.fffef41",
-    "@dxos/util": "0.8.4-main.fffef41"
+    "ws": "^8.17.1",
+    "@dxos/async": "0.9.0",
+    "@dxos/context": "0.9.0",
+    "@dxos/credentials": "0.9.0",
+    "@dxos/crypto": "0.9.0",
+    "@dxos/effect": "0.9.0",
+    "@dxos/errors": "0.9.0",
+    "@dxos/invariant": "0.9.0",
+    "@dxos/keyring": "0.9.0",
+    "@dxos/keys": "0.9.0",
+    "@dxos/log": "0.9.0",
+    "@dxos/util": "0.9.0",
+    "@dxos/node-std": "0.9.0",
+    "@dxos/protocols": "0.9.0"
   },
   "devDependencies": {
-    "@dxos/test-utils": "0.8.4-main.fffef41"
+    "@dxos/test-utils": "0.9.0"
   },
   "peerDependencies": {
-    "effect": "^3.13.3"
+    "effect": "3.21.3"
   },
   "publishConfig": {
     "access": "public"

package/src/base-http-client.ts

@@ -0,0 +1,243 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { sleep } from '@dxos/async';
+import { Context, TRACE_SPAN_ATTRIBUTE, type TraceContextData } from '@dxos/context';
+import { invariant } from '@dxos/invariant';
+import { log } from '@dxos/log';
+import { EDGE_CLIENT_TAG_HEADER, EdgeAuthChallengeError, EdgeCallFailedError, type EdgeFailure } from '@dxos/protocols';
+
+import { type EdgeIdentity, handleAuthChallenge } from './edge-identity';
+import { encodeAuthHeader } 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 = {
+  /** Number of retries, not counting the initial request. */
+  count: number;
+  /** Delay before retries in ms. */
+  timeout?: number;
+  /** Random additional delay to spread retries. */
+  jitter?: number;
+};
+
+export type EdgeHttpCallArgs = {
+  retry?: RetryConfig;
+  /**
+   * Force authentication by pre-fetching `/auth` to obtain the challenge before
+   * sending the body. Use for requests with large bodies to avoid sending twice.
+   * Not available on HubHttpClient (hub-service has no `/auth` endpoint).
+   */
+  auth?: boolean;
+};
+
+export type BaseHttpClientOptions = {
+  /**
+   * Tag included in the {@link EDGE_CLIENT_TAG_HEADER} header on every request.
+   * Used on Edge to classify traffic for metering (e.g. `ci-e2e`).
+   */
+  clientTag?: string;
+};
+
+type HttpRequestArgs = {
+  method: string;
+  retry?: RetryConfig;
+  body?: any;
+  /** @default true */
+  json?: boolean;
+  auth?: boolean;
+};
+
+export abstract class BaseHttpClient {
+  protected readonly _baseUrl: string;
+  protected readonly _clientTag: string | undefined;
+  protected _edgeIdentity: EdgeIdentity | undefined;
+  /** Auth header cached until next 401. */
+  protected _authHeader: string | undefined;
+
+  constructor(baseUrl: string, options?: BaseHttpClientOptions) {
+    this._baseUrl = getEdgeUrlWithProtocol(baseUrl, 'http');
+    this._clientTag = options?.clientTag;
+    log('created', { url: this._baseUrl });
+  }
+
+  get baseUrl() {
+    return this._baseUrl;
+  }
+
+  setIdentity(identity: EdgeIdentity): void {
+    if (this._edgeIdentity?.identityKey !== identity.identityKey || this._edgeIdentity?.peerKey !== identity.peerKey) {
+      this._edgeIdentity = identity;
+      this._authHeader = undefined;
+    }
+  }
+
+  // TODO(mykola): Extend `_call` to support streaming/raw `Response` returns so
+  // `EdgeHttpClient.anthropicAiRequest` can be absorbed here and the auth/retry loop
+  // stops being duplicated across the two paths.
+  protected async _call<T>(ctx: Context, url: URL, args: HttpRequestArgs): Promise<T> {
+    const shouldRetry = createRetryHandler(args);
+    // Log presence/size only — never log raw body contents which may contain PII.
+    log('fetch', {
+      url,
+      hasBody: args.body !== undefined,
+      bodySize: typeof args.body === 'string' ? args.body.length : undefined,
+    });
+
+    const traceHeaders = getTraceHeaders(ctx);
+
+    let handledAuth = false;
+    const tryCount = 1;
+    while (true) {
+      let processingError: EdgeCallFailedError | undefined = undefined;
+      try {
+        if (!this._authHeader && args.auth) {
+          const response = await fetch(new URL('/auth', this._baseUrl));
+          if (response.status === 401) {
+            this._authHeader = await this._handleUnauthorized(response);
+          }
+        }
+
+        const request = createRequest(args, this._authHeader, traceHeaders, this._clientTag);
+        log('call', { url, tryCount, authHeader: !!this._authHeader });
+        const response = await fetch(url, request);
+
+        if (response.ok) {
+          const contentType = response.headers.get('Content-Type') ?? '';
+          // No-content responses (204, empty body, non-JSON) — return undefined.
+          if (
+            response.status === 204 ||
+            response.headers.get('Content-Length') === '0' ||
+            !contentType.includes('application/json')
+          ) {
+            return undefined as T;
+          }
+          const body = await response.clone().json();
+          if (typeof body !== 'object' || body === null) {
+            return body;
+          }
+          if (!('success' in body)) {
+            return body;
+          }
+          if (body.success) {
+            return body.data;
+          }
+        } else if (response.status === 401 && response.headers.get('WWW-Authenticate') !== null && !handledAuth) {
+          // Only retry edge auth when the 401 came from edge's own auth layer. Edge always sets
+          // `WWW-Authenticate` on its own 401s; upstream-forwarded 401s lack it.
+          this._authHeader = await this._handleUnauthorized(response);
+          handledAuth = true;
+          continue;
+        }
+
+        const contentType = response.headers.get('Content-Type') ?? '';
+        const body: EdgeFailure = contentType.startsWith('application/json')
+          ? await response.clone().json()
+          : undefined;
+
+        invariant(!body?.success, 'Expected body to not be a failure response or undefined.');
+
+        if (body?.data?.type === 'auth_challenge' && typeof body?.data?.challenge === 'string') {
+          processingError = new EdgeAuthChallengeError(body.data.challenge, body.data);
+        } else if (body?.success === false) {
+          processingError = EdgeCallFailedError.fromUnsuccessfulResponse(response, body);
+        } else {
+          invariant(!response.ok, 'Expected response to not be ok.');
+          processingError = await EdgeCallFailedError.fromHttpFailure(response);
+        }
+      } catch (error: any) {
+        processingError = EdgeCallFailedError.fromProcessingFailureCause(error);
+      }
+
+      if (processingError?.isRetryable && (await shouldRetry(ctx, processingError.retryAfterMs))) {
+        log.verbose('retrying request', { url, processingError });
+      } else {
+        throw processingError!;
+      }
+    }
+  }
+
+  protected async _handleUnauthorized(response: Response): Promise<string> {
+    if (!this._edgeIdentity) {
+      log.warn('unauthorized response received before identity was set');
+      throw await EdgeCallFailedError.fromHttpFailure(response);
+    }
+    const challenge = await handleAuthChallenge(response, this._edgeIdentity);
+    return encodeAuthHeader(challenge);
+  }
+}
+
+const createRequest = (
+  { method, body, json = true }: HttpRequestArgs,
+  authHeader: string | undefined,
+  traceHeaders?: Record<string, string>,
+  clientTag?: string,
+): RequestInit => {
+  let requestBody: BodyInit | undefined;
+  const headers: HeadersInit = {};
+
+  if (json) {
+    requestBody = body === undefined ? undefined : 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;
+  }
+
+  if (traceHeaders) {
+    Object.assign(headers, traceHeaders);
+  }
+
+  if (clientTag) {
+    headers[EDGE_CLIENT_TAG_HEADER] = clientTag;
+  }
+
+  return { method, body: requestBody, headers };
+};
+
+const getTraceHeaders = (ctx: Context): Record<string, string> | undefined => {
+  const traceCtx = ctx.getAttribute(TRACE_SPAN_ATTRIBUTE) as TraceContextData | undefined;
+  if (!traceCtx) {
+    return undefined;
+  }
+  const headers: Record<string, string> = { traceparent: traceCtx.traceparent };
+  if (traceCtx.tracestate) {
+    headers.tracestate = traceCtx.tracestate;
+  }
+  return headers;
+};
+
+/** @deprecated */
+const createRetryHandler = ({ retry }: HttpRequestArgs) => {
+  if (!retry || retry.count < 1) {
+    return async () => false;
+  }
+  let retries = 0;
+  const maxRetries = retry.count ?? DEFAULT_MAX_RETRIES_COUNT;
+  const baseTimeout = retry.timeout ?? DEFAULT_RETRY_TIMEOUT;
+  const jitter = retry.jitter ?? DEFAULT_RETRY_JITTER;
+  return async (ctx: Context, retryAfter?: number) => {
+    if (++retries > maxRetries || ctx.disposed) {
+      return false;
+    }
+    if (retryAfter) {
+      await sleep(retryAfter);
+    } else {
+      const timeout = baseTimeout + Math.random() * jitter;
+      await sleep(timeout);
+    }
+    return true;
+  };
+};

package/src/cors-proxy.ts

@@ -0,0 +1,38 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+// Lightweight CORS-proxy helpers — intentionally free of heavy transitive
+// dependencies so they can be bundled into workerd / browser environments
+// without pulling in protobufjs or similar node-only packages.
+
+const LEGACY_CORS_PROXY_URL = 'https://cors-proxy.dxos.workers.dev';
+
+// Matches EDGE_CLIENT_TAG_HEADER from @dxos/protocols.
+// Duplicated here to avoid importing the heavy protocols bundle in edge environments.
+const EDGE_CLIENT_TAG_HEADER = 'X-DXOS-Client-Tag';
+
+const remapAuthorizationForProxy = (headers: Headers): Headers => {
+  const callerAuth = headers.get('Authorization');
+  if (callerAuth !== null) {
+    headers.delete('Authorization');
+    headers.set('X-Cors-Proxy-Authorization', callerAuth);
+  }
+  return headers;
+};
+
+/**
+ * Fetch through the legacy standalone open proxy at `cors-proxy.dxos.workers.dev`.
+ * TEMPORARY — delete when the authenticated `/proxy/*` route on edge ships.
+ */
+export const proxyFetchLegacy = (target: URL, init: RequestInit = {}, clientTag?: string): Promise<Response> => {
+  const proxyUrl = new URL(`/${target.host}${target.pathname}${target.search}`, LEGACY_CORS_PROXY_URL);
+  if (target.protocol === 'http:') {
+    proxyUrl.searchParams.set('scheme', 'http');
+  }
+  const requestHeaders = remapAuthorizationForProxy(new Headers(init.headers ?? undefined));
+  if (clientTag) {
+    requestHeaders.set(EDGE_CLIENT_TAG_HEADER, clientTag);
+  }
+  return fetch(proxyUrl, { ...init, headers: requestHeaders });
+};

package/src/edge-ai-http-client.ts

@@ -0,0 +1,129 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Headers from '@effect/platform/Headers';
+import * as HttpClient from '@effect/platform/HttpClient';
+import * as HttpClientError from '@effect/platform/HttpClientError';
+import * as HttpClientResponse from '@effect/platform/HttpClientResponse';
+import * as Effect from 'effect/Effect';
+import * as FiberRef from 'effect/FiberRef';
+import * as Layer from 'effect/Layer';
+import * as Stream from 'effect/Stream';
+
+import { BaseError, type BaseErrorOptions } from '@dxos/errors';
+import { log } from '@dxos/log';
+import { BYOK_HEADER } from '@dxos/protocols';
+
+import { type EdgeHttpClient } from './edge-http-client';
+
+export type GetEdgeHttpClient = () => EdgeHttpClient;
+
+/**
+ * Thrown by {@link EdgeAiHttpClient} when an AI request carrying {@link BYOK_HEADER} is rejected
+ * with 401/403 by the upstream provider — i.e. the user-supplied API key is invalid. Wrapped as
+ * the `cause` of an `HttpClientError.ResponseError` so it flows through `@effect/ai`'s error
+ * mapping; callers walk the cause chain (via {@link ByokError.is}) to render a useful message.
+ */
+export class ByokError extends BaseError.extend('ByokError', 'BYOK authentication failed') {
+  constructor(options: { status: number; provider: string } & BaseErrorOptions) {
+    super({ context: { status: options.status, provider: options.provider }, ...options });
+  }
+}
+
+/**
+ * Copy pasted from https://github.com/Effect-TS/effect/blob/main/packages/platform/src/internal/fetchHttpClient.ts
+ */
+export const requestInitTagKey = '@effect/platform/FetchHttpClient/FetchOptions';
+
+/**
+ * An `@effect/platform` {@link HttpClient.HttpClient} that routes requests through the
+ * authenticated EDGE AI endpoint via {@link EdgeHttpClient.anthropicAiRequest}, instead of
+ * fetching the AI service directly.
+ *
+ * Provide this layer in place of `FetchHttpClient.layer` when constructing an Anthropic client,
+ * e.g. `AnthropicClient.layer({ apiUrl: 'http://edge' }).pipe(Layer.provide(EdgeAiHttpClient.layer(() => edgeClient)))`.
+ * The `apiUrl` host is a sentinel; only the request path is forwarded (see `anthropicAiRequest`).
+ *
+ * Modeled on `FunctionsAiHttpClient` in `@dxos/functions`.
+ */
+export class EdgeAiHttpClient {
+  static make = (getClient: GetEdgeHttpClient) =>
+    HttpClient.make((request, url, signal, fiber) => {
+      const edgeClient = getClient();
+      const context = fiber.getFiberRef(FiberRef.currentContext);
+      const options: RequestInit = context.unsafeMap.get(requestInitTagKey) ?? {};
+      const headers = options.headers
+        ? Headers.merge(Headers.fromInput(options.headers), request.headers)
+        : request.headers;
+
+      const carriedByok = !!headers[BYOK_HEADER.toLowerCase()];
+
+      const send = (body: BodyInit | undefined) =>
+        Effect.tryPromise({
+          try: () =>
+            edgeClient.anthropicAiRequest(
+              new Request(url, {
+                ...options,
+                method: request.method,
+                headers,
+                body,
+                signal,
+              }),
+            ),
+          catch: (cause) => {
+            log.error('Failed to fetch', { cause });
+            return new HttpClientError.RequestError({
+              request,
+              reason: 'Transport',
+              cause,
+            });
+          },
+        }).pipe(
+          Effect.flatMap((response) => {
+            const httpResponse = HttpClientResponse.fromWeb(request, response);
+            // A 401/403 on a BYOK-carrying request means the user's upstream key was rejected.
+            // Wrap as a typed ResponseError with `cause: ByokError` so it survives AiError's
+            // `fromRequestError` mapping; callers walk the cause chain to render a useful message.
+            if (carriedByok && (response.status === 401 || response.status === 403)) {
+              return Effect.tryPromise({
+                try: () => response.clone().json() as Promise<{ error?: { message?: string } } | undefined>,
+                catch: () => undefined,
+              }).pipe(
+                Effect.orElseSucceed(() => undefined),
+                Effect.flatMap((body) =>
+                  Effect.fail(
+                    new HttpClientError.ResponseError({
+                      request,
+                      response: httpResponse,
+                      reason: 'StatusCode',
+                      cause: new ByokError({
+                        status: response.status,
+                        provider: 'anthropic.com',
+                        message: body?.error?.message ?? 'Authentication failed',
+                      }),
+                    }),
+                  ),
+                ),
+              );
+            }
+            return Effect.succeed(httpResponse);
+          }),
+        );
+
+      switch (request.body._tag) {
+        case 'Raw':
+        case 'Uint8Array':
+          return send(request.body.body as any);
+        case 'FormData':
+          return send(request.body.formData);
+        case 'Stream':
+          return Stream.toReadableStreamEffect(request.body.stream).pipe(Effect.flatMap(send));
+      }
+
+      return send(undefined);
+    });
+
+  static layer = (getClient: GetEdgeHttpClient) =>
+    Layer.succeed(HttpClient.HttpClient, EdgeAiHttpClient.make(getClient));
+}

package/src/edge-client.test.ts

@@ -5,6 +5,7 @@
 import { describe, expect, onTestFinished, test } from 'vitest';
 
 import { Trigger } from '@dxos/async';
+import { Context } from '@dxos/context';
 import { Keyring } from '@dxos/keyring';
 import { TextMessageSchema } from '@dxos/protocols/buf/dxos/edge/messenger_pb';
 import { EdgeStatus } from '@dxos/protocols/proto/dxos/client/services';
@@ -25,13 +26,13 @@ describe('EdgeClient', () => {
     onTestFinished(cleanup);
 
     const { client, reconnectTrigger } = await openNewClient(endpoint);
-    await client.send(textMessage('Hello world 1'));
+    await client.send(Context.default(), textMessage('Hello world 1'));
     expect(client.isOpen).is.true;
 
     reconnectTrigger.reset();
     await closeConnection();
     await reconnectTrigger.wait();
-    await expect(client.send(textMessage('Hello world 2'))).resolves.not.toThrow();
+    await expect(client.send(Context.default(), textMessage('Hello world 2'))).resolves.not.toThrow();
   });
 
   test('isConnected', async () => {
@@ -59,13 +60,13 @@ describe('EdgeClient', () => {
     onTestFinished(cleanup);
 
     const { client, reconnectTrigger } = await openNewClient(endpoint);
-    await client.send(textMessage('Hello world 1'));
+    await client.send(Context.default(), textMessage('Hello world 1'));
     expect(client.isOpen).is.true;
 
     reconnectTrigger.reset();
     client.setIdentity(await createEphemeralEdgeIdentity());
     await reconnectTrigger.wait();
-    await expect(client.send(textMessage('Hello world 2'))).resolves.not.toThrow();
+    await expect(client.send(Context.default(), textMessage('Hello world 2'))).resolves.not.toThrow();
   });
 
   test('send blocks until connection becomes ready', async () => {
@@ -75,7 +76,7 @@ describe('EdgeClient', () => {
 
     const { client } = await openNewClient(endpoint);
     setTimeout(() => admitConnection.wake(), 20);
-    await client.send(textMessage('Hello world 1'));
+    await client.send(Context.default(), textMessage('Hello world 1'));
     await expect.poll(() => messageSink.length).toBe(1);
   });
 
@@ -86,11 +87,13 @@ describe('EdgeClient', () => {
 
     const { client } = await openNewClient(endpoint);
     setTimeout(async () => client.setIdentity(await createEphemeralEdgeIdentity()));
-    await expect(client.send(textMessage('Hello world 1'))).rejects.toThrow(EdgeIdentityChangedError);
+    await expect(client.send(Context.default(), textMessage('Hello world 1'))).rejects.toThrow(
+      EdgeIdentityChangedError,
+    );
 
     // Test recovers.
     setTimeout(() => admitConnection.wake(), 20);
-    await client.send(textMessage('Hello world 1'));
+    await client.send(Context.default(), textMessage('Hello world 1'));
     await expect.poll(() => messageSink.length).toBe(1);
   });
 
@@ -101,7 +104,9 @@ describe('EdgeClient', () => {
 
     const { client } = await openNewClient(endpoint);
     setTimeout(() => client.close());
-    await expect(client.send(textMessage('Hello world 1'))).rejects.toThrow(EdgeConnectionClosedError);
+    await expect(client.send(Context.default(), textMessage('Hello world 1'))).rejects.toThrow(
+      EdgeConnectionClosedError,
+    );
   });
 
   test('onReconnect trigger', async () => {
@@ -129,12 +134,12 @@ describe('EdgeClient', () => {
     onTestFinished(cleanup);
 
     const { client, identity: oldIdentity } = await openNewClient(endpoint);
-    await client.send(textMessage('Hello world 1', oldIdentity));
+    await client.send(Context.default(), textMessage('Hello world 1', oldIdentity));
     expect(client.isOpen).is.true;
 
     const newIdentity = await createEphemeralEdgeIdentity();
     client.setIdentity(newIdentity);
-    await client.send(textMessage('Hello world 2', newIdentity));
+    await client.send(Context.default(), textMessage('Hello world 2', newIdentity));
     await expect.poll(() => messageSourceLog.length).toBe(2);
     expect(messageSourceLog.map((m) => m.peerKey)).toStrictEqual([oldIdentity.peerKey, newIdentity.peerKey]);
   });
@@ -147,7 +152,7 @@ describe('EdgeClient', () => {
 
     const client = new EdgeClient(identity, { socketEndpoint: process.env.EDGE_ENDPOINT! });
     await openAndClose(client);
-    await client.send(textMessage('Hello world 1'));
+    await client.send(Context.default(), textMessage('Hello world 1'));
     expect(client.isOpen).is.true;
   });