@hashtree/worker 0.1.26 → 0.2.1

package/README.md

@@ -17,7 +17,7 @@ import { HashtreeWorkerClient } from '@hashtree/worker';
 import HashtreeWorker from './workers/hashtree.worker.ts?worker';
 
 const client = new HashtreeWorkerClient(HashtreeWorker, {
-  blossomServers: [{ url: 'https://upload.iris.to', read: true, write: true }],
+  blossomServers: [{ url: 'https://upload.example', read: true, write: true }],
 });
 await client.init();
 
@@ -26,19 +26,19 @@ const { hashHex } = await client.putBlob(data);
 const { data: blob } = await client.getBlob(hashHex);
 ```
 
-## Iris Worker Client
+## Relay Worker Client
 
-If you are using `@hashtree/worker/iris-entry?worker` and need Iris-specific tree-root
-metadata or subscription calls, use the dedicated Iris wrapper:
+If you are using `@hashtree/worker/relay-entry?worker` and need relay-backed tree-root
+metadata or subscription calls, use the dedicated relay wrapper:
 
 ```typescript
-import { IrisWorkerClient } from '@hashtree/worker/iris-client';
-import HashtreeWorker from '@hashtree/worker/iris-entry?worker';
+import { RelayWorkerClient } from '@hashtree/worker/relay-client';
+import HashtreeWorker from '@hashtree/worker/relay-entry?worker';
 
-const client = new IrisWorkerClient(HashtreeWorker, {
-  storeName: 'iris-sites-worker',
+const client = new RelayWorkerClient(HashtreeWorker, {
+  storeName: 'demo-sites-worker',
   relays: ['wss://relay.damus.io'],
-  blossomServers: [{ url: 'https://upload.iris.to', read: false, write: true }],
+  blossomServers: [{ url: 'https://upload.example', read: false, write: true }],
   pubkey: '336f319763657d6b0e65a5b5876719e8c8dcdcf9396852be71ee26b73368b29b',
 });
 
@@ -49,10 +49,10 @@ const stop = client.onTreeRootUpdate((update) => {
 });
 ```
 
-## Iris-Compatible Runtime Defaults
+## Browser Runtime Defaults
 
 When the app runs inside Iris or another shell that injects `window.__HTREE_SERVER_URL__`
-(or the launch URL carries `iris_htree_server`), the main app-facing API should be
+(or the launch URL carries `htree_server`), the main app-facing API should be
 `createHtreeRuntime(...)`:
 
 ```typescript
@@ -68,8 +68,8 @@ const DEFAULT_RELAYS = [
 ];
 
 const DEFAULT_BLOSSOM_SERVERS = [
-  { url: 'https://upload.iris.to', read: false, write: true },
-  { url: 'https://cdn.iris.to', read: true, write: false },
+  { url: 'https://upload.example', read: false, write: true },
+  { url: 'https://cdn.example', read: true, write: false },
 ];
 
 const runtime = createHtreeRuntime({
@@ -118,7 +118,7 @@ channel.
 Behavior:
 
 - In plain web mode, `runtime.endpoints` keeps your configured public relays and Blossom servers.
-- In Iris/native child runtimes, `runtime.endpoints` and `runtime.getWorkerConfig()` switch transport defaults to the local daemon endpoints.
+- In native child runtimes, `runtime.endpoints` and `runtime.getWorkerConfig()` switch transport defaults to the local daemon endpoints.
 - `runtime.urls.media(...)` handles `/htree/...` URL generation plus the per-client `htree_c` and optional `htree_t` query params.
 - `runtime.media.ensureReady(...)` handles the common page-side service-worker/media-port handshake.
 
@@ -130,12 +130,12 @@ If your service worker intercepts `/htree/...` media requests and forwards them
 - `runtime.urls.media(..., { clientScoped: true })` appends it as the `htree_c` query param.
 - `runtime.media.ensureReady(...)` sends the same key in `REGISTER_WORKER_PORT` and `PING_WORKER_PORT`.
 
-That lets the service worker map fetches back to the correct worker port when multiple tabs or isolated Iris child webviews are active at once, without falling back to a single global port.
+That lets the service worker map fetches back to the correct worker port when multiple tabs or isolated child webviews are active at once, without falling back to a single global port.
 
 ## Exports
 
 - `@hashtree/worker` — `createHtreeRuntime`, `resolveRuntimeEndpoints`, and `HashtreeWorkerClient`
-- `@hashtree/worker/iris-client` — `IrisWorkerClient` plus Iris-specific tree-root metadata types
+- `@hashtree/worker/relay-client` — `RelayWorkerClient` plus relay-backed tree-root metadata types
 - `@hashtree/worker/worker` — `attachHashtreeWorker(...)` for embedding the worker protocol into a custom worker
 - `@hashtree/worker/p2p` — `WebRTCController` / `WebRTCProxy` for P2P data channel management
 - `@hashtree/worker/entry` — Worker entry point

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hashtree/worker",
-  "version": "0.1.26",
+  "version": "0.2.1",
   "description": "Modular browser worker for hashtree blob caching, tree-root state, and Blossom connectivity",
   "type": "module",
   "main": "dist/index.js",
@@ -14,9 +14,9 @@
       "types": "./dist/client.d.ts",
       "import": "./dist/client.js"
     },
-    "./iris-client": {
-      "types": "./dist/iris-client.d.ts",
-      "import": "./dist/iris-client.js"
+    "./relay-client": {
+      "types": "./dist/relay-client.d.ts",
+      "import": "./dist/relay-client.js"
     },
     "./p2p": {
       "types": "./dist/p2p/index.d.ts",
@@ -30,9 +30,9 @@
       "types": "./dist/worker.d.ts",
       "import": "./dist/worker.js"
     },
-    "./iris-entry": {
-      "types": "./dist/iris-entry.d.ts",
-      "import": "./dist/iris-entry.js"
+    "./relay-entry": {
+      "types": "./dist/relay-entry.d.ts",
+      "import": "./dist/relay-entry.js"
     },
     "./protocol": {
       "types": "./dist/protocol.d.ts",
@@ -56,11 +56,17 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "src"
   ],
   "publishConfig": {
     "access": "public"
   },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
   "keywords": [
     "hashtree",
     "worker",
@@ -69,7 +75,10 @@
   ],
   "author": "Martti Malmi",
   "license": "MIT",
-  "repository": "https://git.iris.to/#/npub1xdhnr9mrv47kkrn95k6cwecearydeh8e895990n3acntwvmgk2dsdeeycm/hashtree",
+  "repository": {
+    "type": "git",
+    "url": "https://git.iris.to/#/npub1xdhnr9mrv47kkrn95k6cwecearydeh8e895990n3acntwvmgk2dsdeeycm/hashtree"
+  },
   "homepage": "https://git.iris.to/#/npub1xdhnr9mrv47kkrn95k6cwecearydeh8e895990n3acntwvmgk2dsdeeycm/hashtree/ts/packages/hashtree-worker",
   "bugs": {
     "url": "https://git.iris.to/#/npub1xdhnr9mrv47kkrn95k6cwecearydeh8e895990n3acntwvmgk2dsdeeycm/hashtree?tab=issues"
@@ -99,15 +108,10 @@
     }
   },
   "devDependencies": {
+    "ndk": "workspace:*",
+    "ndk-cache": "workspace:*",
+    "nostr-social-graph": "workspace:*",
     "typescript": "^5.3.0",
-    "vitest": "^2.1.9",
-    "ndk": "0.1.1",
-    "ndk-cache": "0.1.1",
-    "nostr-social-graph": "1.0.36"
-  },
-  "scripts": {
-    "build": "tsc",
-    "test": "vitest run",
-    "test:watch": "vitest"
+    "vitest": "^2.1.9"
   }
-}
+}

package/src/app-runtime.ts

@@ -0,0 +1,393 @@
+import type { WorkerConfig, BlossomServerConfig } from './protocol.js';
+import type { HtreeRuntimeWindowLike } from './runtime.js';
+import type { ParsedHtreeUrl, ResolveHtreeRequestUrlOptions } from './htree-url.js';
+import type { HtreeClientIdStorageLike } from './client-id.js';
+import {
+  appendHtreeClientId,
+  appendHtreeQueryParam,
+  getOrCreateHtreeClientId,
+} from './client-id.js';
+import { resolveHtreeRequestUrl } from './htree-url.js';
+import { canUseInjectedHtreeServerUrl, canUseSameOriginHtreeProtocolStreaming } from './runtime.js';
+import { resolveRuntimeEndpoints, type RuntimeEndpoints } from './runtime-network.js';
+
+export type RuntimeValueSource<T> = T | (() => T);
+
+export interface HtreeRuntimeEndpointOverrides {
+  relays?: readonly string[];
+  blossomServers?: readonly BlossomServerConfig[];
+}
+
+export interface HtreeRuntimeOptions {
+  appId?: string | null;
+  fallbackBaseUrl?: string | null;
+  windowLike?: HtreeRuntimeWindowLike;
+  storage?: HtreeClientIdStorageLike | null;
+  clientIdFactory?: () => string;
+  clientIdStorageKey?: string;
+  clientIdPrefix?: string;
+  serviceWorker?: ServiceWorkerContainer | null;
+  relays?: RuntimeValueSource<readonly string[]>;
+  blossomServers?: RuntimeValueSource<readonly BlossomServerConfig[]>;
+}
+
+export interface HtreeRuntimeRequestUrlOptions extends Omit<ResolveHtreeRequestUrlOptions, 'windowLike' | 'fallbackBaseUrl'> {}
+
+export interface HtreeRuntimeMediaUrlOptions extends HtreeRuntimeRequestUrlOptions {
+  clientScoped?: boolean;
+  mimeType?: string | null | undefined;
+  query?: Record<string, string | number | boolean | null | undefined>;
+}
+
+export interface HtreeRuntimeWorkerConfigOptions extends Omit<WorkerConfig, 'relays' | 'blossomServers'> {
+  relays?: readonly string[];
+  blossomServers?: readonly BlossomServerConfig[];
+}
+
+export interface HtreeRuntimeMediaPortOptions {
+  registerMediaPort: (port: MessagePort, debug?: boolean) => Promise<void> | void;
+  debug?: boolean;
+  attempts?: number;
+  delayMs?: number;
+  pingTimeoutMs?: number;
+  registrationTimeoutMs?: number;
+  controllerTimeoutMs?: number;
+}
+
+export interface HtreeRuntime {
+  readonly appId: string | null;
+  readonly clientId: string | null;
+  readonly endpoints: RuntimeEndpoints;
+  getEndpoints(overrides?: HtreeRuntimeEndpointOverrides): RuntimeEndpoints;
+  getWorkerConfig(options?: HtreeRuntimeWorkerConfigOptions): WorkerConfig;
+  urls: {
+    request: (input: string | ParsedHtreeUrl, options?: HtreeRuntimeRequestUrlOptions) => string;
+    media: (input: string | ParsedHtreeUrl, options?: HtreeRuntimeMediaUrlOptions) => string;
+    appendClientId: (url: string) => string;
+  };
+  media: {
+    ensureReady: (options: HtreeRuntimeMediaPortOptions) => Promise<boolean>;
+    reset: () => void;
+  };
+}
+
+const DEFAULT_FALLBACK_BASE_URL = '';
+const DEFAULT_MEDIA_PORT_ATTEMPTS = 3;
+const DEFAULT_MEDIA_PORT_DELAY_MS = 500;
+const DEFAULT_MEDIA_PORT_PING_TIMEOUT_MS = 1_500;
+const DEFAULT_MEDIA_PORT_REGISTRATION_TIMEOUT_MS = 5_000;
+const DEFAULT_MEDIA_PORT_CONTROLLER_TIMEOUT_MS = 5_000;
+const RECONNECT_REQUEST_COOLDOWN_MS = 1_000;
+
+function resolveRuntimeValue<T>(value: RuntimeValueSource<T> | undefined, fallback: T): T {
+  if (typeof value === 'function') {
+    return (value as () => T)();
+  }
+  return value ?? fallback;
+}
+
+function getServiceWorkerContainer(
+  serviceWorker?: ServiceWorkerContainer | null,
+): ServiceWorkerContainer | null {
+  if (typeof serviceWorker !== 'undefined') {
+    return serviceWorker;
+  }
+  if (typeof navigator === 'undefined') {
+    return null;
+  }
+  return navigator.serviceWorker ?? null;
+}
+
+function isDirectMediaRuntime(windowLike?: HtreeRuntimeWindowLike): boolean {
+  return canUseInjectedHtreeServerUrl(windowLike)
+    || canUseSameOriginHtreeProtocolStreaming(windowLike);
+}
+
+function createMessageId(prefix: string): string {
+  return `${prefix}-${Date.now()}-${Math.random().toString(16).slice(2)}`;
+}
+
+export function createHtreeRuntime(options: HtreeRuntimeOptions = {}): HtreeRuntime {
+  const appId = options.appId?.trim() || null;
+  const fallbackBaseUrl = options.fallbackBaseUrl ?? DEFAULT_FALLBACK_BASE_URL;
+  const windowLike = options.windowLike;
+  const storage = typeof options.storage === 'undefined' ? undefined : options.storage;
+  const storageKey = options.clientIdStorageKey ?? (appId ? `${appId}.mediaClientId` : 'htree.mediaClientId');
+  const clientIdPrefix = options.clientIdPrefix ?? (
+    appId ? appId.replace(/[^a-z0-9]+/gi, '').toLowerCase() || 'htree' : 'htree'
+  );
+  const serviceWorker = getServiceWorkerContainer(options.serviceWorker);
+
+  let setupPromise: Promise<boolean> | null = null;
+  let mediaReady = false;
+  let activeController: ServiceWorker | null = null;
+  let controllerListenerAttached = false;
+  let messageListenerAttached = false;
+  let reconnectPromise: Promise<void> | null = null;
+  let lastReconnectRequestAt = 0;
+  let lastEnsureOptions: HtreeRuntimeMediaPortOptions | null = null;
+
+  const getClientId = (): string | null => getOrCreateHtreeClientId({
+    storage,
+    storageKey,
+    prefix: clientIdPrefix,
+    uuidFactory: options.clientIdFactory,
+  });
+
+  const getEndpoints = (overrides: HtreeRuntimeEndpointOverrides = {}): RuntimeEndpoints => {
+    const relays = overrides.relays ?? resolveRuntimeValue(options.relays, []);
+    const blossomServers = overrides.blossomServers ?? resolveRuntimeValue(options.blossomServers, []);
+    return resolveRuntimeEndpoints({
+      windowLike,
+      relays,
+      blossomServers,
+    });
+  };
+
+  const appendRuntimeClientId = (url: string): string => appendHtreeClientId(url, getClientId());
+
+  const resolveRequestUrl = (
+    input: string | ParsedHtreeUrl,
+    urlOptions: HtreeRuntimeRequestUrlOptions = {},
+  ): string => resolveHtreeRequestUrl(input, {
+    ...urlOptions,
+    windowLike,
+    fallbackBaseUrl,
+  });
+
+  const resolveMediaUrl = (
+    input: string | ParsedHtreeUrl,
+    mediaOptions: HtreeRuntimeMediaUrlOptions = {},
+  ): string => {
+    let url = resolveRequestUrl(input, mediaOptions);
+
+    if (mediaOptions.clientScoped) {
+      url = appendRuntimeClientId(url);
+    }
+
+    url = appendHtreeQueryParam(url, 'htree_t', mediaOptions.mimeType);
+
+    for (const [key, value] of Object.entries(mediaOptions.query ?? {})) {
+      url = appendHtreeQueryParam(url, key, value == null ? value : String(value));
+    }
+
+    return url;
+  };
+
+  const getWorkerConfig = (configOptions: HtreeRuntimeWorkerConfigOptions = {}): WorkerConfig => {
+    const { relays, blossomServers, ...rest } = configOptions;
+    const endpoints = getEndpoints({ relays, blossomServers });
+    return {
+      ...rest,
+      relays: endpoints.nostrRelays,
+      blossomServers: endpoints.blossomServers,
+    };
+  };
+
+  const resetMedia = (): void => {
+    mediaReady = false;
+    setupPromise = null;
+    activeController = null;
+  };
+
+  const ensureControllerListener = (): void => {
+    if (controllerListenerAttached || !serviceWorker) return;
+    controllerListenerAttached = true;
+    serviceWorker.addEventListener('controllerchange', () => {
+      resetMedia();
+    });
+  };
+
+  const requestMediaReconnect = (requestedClientKey?: string | null): void => {
+    const clientId = getClientId();
+    if (!lastEnsureOptions) return;
+    if (requestedClientKey && clientId && requestedClientKey !== clientId) {
+      return;
+    }
+
+    const now = Date.now();
+    if (reconnectPromise || now - lastReconnectRequestAt < RECONNECT_REQUEST_COOLDOWN_MS) {
+      return;
+    }
+
+    lastReconnectRequestAt = now;
+    resetMedia();
+    reconnectPromise = ensureMediaPortReady(lastEnsureOptions)
+      .then(() => undefined)
+      .catch(() => undefined)
+      .finally(() => {
+        reconnectPromise = null;
+      });
+  };
+
+  const ensureMessageListener = (): void => {
+    if (messageListenerAttached || !serviceWorker) return;
+    messageListenerAttached = true;
+    serviceWorker.addEventListener('message', (event: MessageEvent) => {
+      const data = event.data as { type?: string; clientKey?: string | null } | null;
+      if (data?.type !== 'REQUEST_WORKER_PORT_RECONNECT') {
+        return;
+      }
+      requestMediaReconnect(data.clientKey ?? null);
+    });
+  };
+
+  const waitForController = async (timeoutMs: number): Promise<ServiceWorker | null> => {
+    if (!serviceWorker) return null;
+    if (serviceWorker.controller) return serviceWorker.controller;
+
+    await serviceWorker.ready.catch(() => undefined);
+    if (serviceWorker.controller) return serviceWorker.controller;
+
+    return await new Promise<ServiceWorker | null>((resolve) => {
+      const timeoutId = setTimeout(() => resolve(serviceWorker.controller ?? null), timeoutMs);
+      serviceWorker.addEventListener('controllerchange', () => {
+        clearTimeout(timeoutId);
+        resolve(serviceWorker.controller ?? null);
+      }, { once: true });
+    });
+  };
+
+  const pingMediaPort = async (
+    clientKey: string,
+    controller: ServiceWorker,
+    timeoutMs: number,
+  ): Promise<boolean> => {
+    if (!serviceWorker) return false;
+    const requestId = createMessageId('media-ping');
+    const ackPromise = new Promise<boolean>((resolve) => {
+      const timeoutId = setTimeout(() => {
+        serviceWorker.removeEventListener('message', onMessage);
+        resolve(false);
+      }, timeoutMs);
+      const onMessage = (event: MessageEvent): void => {
+        const data = event.data as { type?: string; requestId?: string; ok?: boolean } | null;
+        if (data?.type === 'WORKER_PORT_PONG' && data.requestId === requestId) {
+          clearTimeout(timeoutId);
+          serviceWorker.removeEventListener('message', onMessage);
+          resolve(!!data.ok);
+        }
+      };
+      serviceWorker.addEventListener('message', onMessage);
+    });
+
+    controller.postMessage({ type: 'PING_WORKER_PORT', requestId, clientKey });
+    return await ackPromise;
+  };
+
+  const setupMediaPort = async (portOptions: HtreeRuntimeMediaPortOptions): Promise<boolean> => {
+    if (!serviceWorker) {
+      return false;
+    }
+
+    ensureControllerListener();
+    ensureMessageListener();
+    const controller = await waitForController(portOptions.controllerTimeoutMs ?? DEFAULT_MEDIA_PORT_CONTROLLER_TIMEOUT_MS);
+    if (!controller) {
+      return false;
+    }
+
+    const clientKey = getClientId() ?? undefined;
+    if (mediaReady && activeController === controller) {
+      if (!clientKey) {
+        return true;
+      }
+      const alive = await pingMediaPort(
+        clientKey,
+        controller,
+        portOptions.pingTimeoutMs ?? DEFAULT_MEDIA_PORT_PING_TIMEOUT_MS,
+      );
+      if (alive) {
+        return true;
+      }
+      resetMedia();
+    }
+
+    const channel = new MessageChannel();
+    const requestId = createMessageId('media');
+    const ackPromise = new Promise<boolean>((resolve) => {
+      const timeoutId = setTimeout(() => {
+        serviceWorker.removeEventListener('message', onMessage);
+        resolve(false);
+      }, portOptions.registrationTimeoutMs ?? DEFAULT_MEDIA_PORT_REGISTRATION_TIMEOUT_MS);
+      const onMessage = (event: MessageEvent): void => {
+        const data = event.data as { type?: string; requestId?: string } | null;
+        if (data?.type === 'WORKER_PORT_READY' && data.requestId === requestId) {
+          clearTimeout(timeoutId);
+          serviceWorker.removeEventListener('message', onMessage);
+          resolve(true);
+        }
+      };
+      serviceWorker.addEventListener('message', onMessage);
+    });
+
+    controller.postMessage(
+      {
+        type: 'REGISTER_WORKER_PORT',
+        port: channel.port1,
+        requestId,
+        clientKey,
+        debug: !!portOptions.debug,
+      },
+      [channel.port1],
+    );
+    await portOptions.registerMediaPort(channel.port2, !!portOptions.debug);
+
+    const acked = await ackPromise;
+    mediaReady = acked;
+    activeController = acked ? controller : null;
+    return acked;
+  };
+
+  const ensureMediaPortReady = async (portOptions: HtreeRuntimeMediaPortOptions): Promise<boolean> => {
+    lastEnsureOptions = portOptions;
+    if (isDirectMediaRuntime(windowLike)) {
+      return true;
+    }
+
+    const attempts = portOptions.attempts ?? DEFAULT_MEDIA_PORT_ATTEMPTS;
+    const delayMs = portOptions.delayMs ?? DEFAULT_MEDIA_PORT_DELAY_MS;
+
+    for (let attempt = 0; attempt < attempts; attempt += 1) {
+      if (!setupPromise) {
+        setupPromise = setupMediaPort(portOptions).finally(() => {
+          if (!mediaReady) {
+            setupPromise = null;
+          }
+        });
+      }
+
+      const ready = await setupPromise.catch(() => false);
+      if (ready) {
+        return true;
+      }
+
+      if (attempt < attempts - 1) {
+        await new Promise((resolve) => setTimeout(resolve, delayMs));
+      }
+    }
+
+    return false;
+  };
+
+  return {
+    appId,
+    get clientId(): string | null {
+      return getClientId();
+    },
+    get endpoints(): RuntimeEndpoints {
+      return getEndpoints();
+    },
+    getEndpoints,
+    getWorkerConfig,
+    urls: {
+      request: resolveRequestUrl,
+      media: resolveMediaUrl,
+      appendClientId: appendRuntimeClientId,
+    },
+    media: {
+      ensureReady: ensureMediaPortReady,
+      reset: resetMedia,
+    },
+  };
+}

package/src/capabilities/blossomBandwidthTracker.ts

@@ -0,0 +1,74 @@
+import type { BlossomLogEntry } from '@hashtree/core';
+
+export interface BlossomBandwidthServerStats {
+  url: string;
+  bytesSent: number;
+  bytesReceived: number;
+}
+
+export interface BlossomBandwidthStats {
+  totalBytesSent: number;
+  totalBytesReceived: number;
+  updatedAt: number;
+  servers: BlossomBandwidthServerStats[];
+}
+
+export type BlossomBandwidthUpdateHandler = (stats: BlossomBandwidthStats) => void;
+
+export class BlossomBandwidthTracker {
+  private totalBytesSent = 0;
+  private totalBytesReceived = 0;
+  private readonly serverBandwidth = new Map<string, { bytesSent: number; bytesReceived: number }>();
+  private readonly onUpdate?: BlossomBandwidthUpdateHandler;
+  private readonly now: () => number;
+
+  constructor(onUpdate?: BlossomBandwidthUpdateHandler, now: () => number = () => Date.now()) {
+    this.onUpdate = onUpdate;
+    this.now = now;
+  }
+
+  apply(entry: BlossomLogEntry): void {
+    const bytes = entry.bytes ?? 0;
+    if (!entry.success || bytes <= 0) return;
+
+    const serverStats = this.serverBandwidth.get(entry.server) ?? { bytesSent: 0, bytesReceived: 0 };
+
+    if (entry.operation === 'put') {
+      this.totalBytesSent += bytes;
+      serverStats.bytesSent += bytes;
+    } else if (entry.operation === 'get') {
+      this.totalBytesReceived += bytes;
+      serverStats.bytesReceived += bytes;
+    } else {
+      return;
+    }
+
+    this.serverBandwidth.set(entry.server, serverStats);
+    this.onUpdate?.(this.getStats());
+  }
+
+  getStats(): BlossomBandwidthStats {
+    return {
+      totalBytesSent: this.totalBytesSent,
+      totalBytesReceived: this.totalBytesReceived,
+      updatedAt: this.now(),
+      servers: this.getOrderedServerBandwidth(),
+    };
+  }
+
+  reset(): void {
+    this.totalBytesSent = 0;
+    this.totalBytesReceived = 0;
+    this.serverBandwidth.clear();
+  }
+
+  private getOrderedServerBandwidth(): BlossomBandwidthServerStats[] {
+    return Array.from(this.serverBandwidth.entries())
+      .map(([url, stats]) => ({
+        url,
+        bytesSent: stats.bytesSent,
+        bytesReceived: stats.bytesReceived,
+      }))
+      .sort((a, b) => a.url.localeCompare(b.url));
+  }
+}