@atolljs/devtools 0.1.7 → 0.1.8

package/src/otelTransport.ts

@@ -0,0 +1,286 @@
+/**
+ * OTLP/HTTP JSON transport: a retrying `fetch` sender and the batching
+ * pipeline that drains `OtelMapper`s into it. No @atolljs/core runtime
+ * imports, so the aggregate server can forward without bundling the SDK.
+ */
+import type { EmittedDevtoolsEvent } from '@atolljs/core';
+import {
+  encodeLogs,
+  encodeMetrics,
+  encodeTraces,
+  toAttributes,
+  type KeyValue,
+  type OtelMapper,
+  type OtelSignals,
+} from './otelMap';
+import type { SessionInfo } from './protocol';
+
+export type OtlpSignal = 'traces' | 'metrics' | 'logs';
+
+export interface OtlpSenderOptions {
+  /** OTLP/HTTP base URL; `/v1/<signal>` is appended (default http://localhost:4318). */
+  endpoint?: string;
+  /** Extra request headers (auth: `x-honeycomb-team`, `authorization`, …). */
+  headers?: Record<string, string>;
+  /** fetch implementation (default: the global fetch captured at creation). */
+  fetch?: typeof fetch;
+  /** Retries per request on 429/502/503/504 or network failure (default 3). */
+  maxRetries?: number;
+  /** Exponential backoff base when no Retry-After is sent (default 500ms). */
+  retryBaseMs?: number;
+  /** Cap on any single retry delay (default 30s). */
+  retryMaxMs?: number;
+  /**
+   * Export failures (non-retryable status, retries exhausted). Never thrown
+   * into app code. Don't route this through atoll's `log()`: that tees back
+   * into the devtools stream and becomes the next export.
+   */
+  onError?: (error: Error, signal: OtlpSignal) => void;
+}
+
+export interface OtlpSender {
+  readonly endpoint: string;
+  /** POST one request body; resolves true when accepted. Never rejects. */
+  send(signal: OtlpSignal, body: unknown, opts?: { keepalive?: boolean }): Promise<boolean>;
+}
+
+/** Retryable per the OTLP/HTTP spec; every other 4xx/5xx is final. */
+const RETRYABLE = new Set([429, 502, 503, 504]);
+/** fetch keepalive bodies share a 64KiB in-flight budget. */
+const KEEPALIVE_MAX = 60_000;
+
+const sleep = (ms: number) => new Promise<void>((r) => {
+  const t = setTimeout(r, ms);
+  (t as unknown as { unref?: () => void }).unref?.();
+});
+
+/** Retry-After: delta-seconds or an HTTP-date. */
+const retryAfterMs = (h: string | null): number | undefined => {
+  if (!h) return undefined;
+  const secs = Number(h);
+  if (Number.isFinite(secs)) return Math.max(0, secs * 1000);
+  const at = Date.parse(h);
+  return Number.isNaN(at) ? undefined : Math.max(0, at - Date.now());
+};
+
+export const normalizeEndpoint = (endpoint = 'http://localhost:4318'): string => endpoint.replace(/\/+$/, '');
+
+export function createOtlpSender(opts: OtlpSenderOptions = {}): OtlpSender {
+  const endpoint = normalizeEndpoint(opts.endpoint);
+  const doFetch = opts.fetch ?? (typeof fetch === 'function' ? fetch.bind(globalThis) : undefined);
+  const maxRetries = opts.maxRetries ?? 3;
+  const base = opts.retryBaseMs ?? 500;
+  const cap = opts.retryMaxMs ?? 30_000;
+  const fail = (signal: OtlpSignal, message: string) => {
+    try {
+      opts.onError?.(new Error(message), signal);
+    } catch {
+      /* a throwing callback must not escape */
+    }
+  };
+
+  return {
+    endpoint,
+    async send(signal, body, sendOpts) {
+      if (!doFetch) {
+        fail(signal, 'otlp: no fetch available');
+        return false;
+      }
+      const text = JSON.stringify(body);
+      const keepalive = !!sendOpts?.keepalive && text.length < KEEPALIVE_MAX;
+      for (let attempt = 0; ; attempt++) {
+        let delay: number | undefined;
+        let reason: string;
+        try {
+          const res = await doFetch(`${endpoint}/v1/${signal}`, {
+            method: 'POST',
+            headers: { ...opts.headers, 'content-type': 'application/json' },
+            body: text,
+            keepalive,
+          });
+          if (res.ok) return true;
+          reason = `otlp ${signal}: HTTP ${res.status}`;
+          if (!RETRYABLE.has(res.status)) {
+            fail(signal, reason);
+            return false;
+          }
+          delay = retryAfterMs(res.headers.get('retry-after'));
+        } catch (err) {
+          reason = `otlp ${signal}: ${err instanceof Error ? err.message : String(err)}`;
+        }
+        if (attempt >= maxRetries) {
+          fail(signal, `${reason} (gave up after ${attempt + 1} attempts)`);
+          return false;
+        }
+        const backoff = base * 2 ** attempt;
+        await sleep(Math.min(cap, delay ?? backoff * (0.5 + Math.random() / 2)));
+      }
+    },
+  };
+}
+
+export interface OtelPipelineOptions {
+  sender: OtlpSender;
+  /** Builds the mapper for a key on first use ('' for a single-app exporter). */
+  newMapper: (key: string) => OtelMapper;
+  /** Periodic flush interval (default 5000ms). 0 disables the timer. */
+  flushIntervalMs?: number;
+  /** Spans / log records per request; reaching it triggers an early flush (default 512). */
+  maxBatch?: number;
+  signals?: OtelSignals;
+  /** Epoch-ms clock for metric collection (default Date.now). */
+  now?: () => number;
+}
+
+export interface OtelPipeline {
+  ingest(ev: EmittedDevtoolsEvent, recvEpochMs: number, key?: string): void;
+  /** Stop tracking a key after its queued data ships on the next flush. */
+  release(key: string): void;
+  /** Serialized: concurrent calls queue behind the in-flight flush. Never rejects. */
+  flush(opts?: { keepalive?: boolean }): Promise<void>;
+  close(): Promise<void>;
+}
+
+export function createOtelPipeline(opts: OtelPipelineOptions): OtelPipeline {
+  const { sender, newMapper } = opts;
+  const maxBatch = Math.max(1, opts.maxBatch ?? 512);
+  const now = opts.now ?? Date.now;
+  const traces = opts.signals?.traces !== false;
+  const metrics = opts.signals?.metrics !== false;
+  const logs = opts.signals?.logs !== false;
+  const mappers = new Map<string, OtelMapper>();
+  const released = new Set<string>();
+  let chain: Promise<void> = Promise.resolve();
+  let flushing = false;
+  let closed = false;
+
+  const sendQueued = async (signal: 'traces' | 'logs', keepalive: boolean): Promise<void> => {
+    for (;;) {
+      let budget = maxBatch;
+      const groups: { resource: KeyValue[]; items: unknown[] }[] = [];
+      for (const m of mappers.values()) {
+        if (budget === 0) break;
+        const items = signal === 'traces' ? m.takeSpans(budget) : m.takeLogs(budget);
+        if (items.length) {
+          groups.push({ resource: m.resource, items });
+          budget -= items.length;
+        }
+      }
+      if (groups.length === 0) return;
+      const body =
+        signal === 'traces'
+          ? encodeTraces(groups.map((g) => ({ resource: g.resource, spans: g.items as never })))
+          : encodeLogs(groups.map((g) => ({ resource: g.resource, logs: g.items as never })));
+      await sender.send(signal, body, { keepalive });
+    }
+  };
+
+  const doFlush = async (keepalive: boolean): Promise<void> => {
+    flushing = true;
+    try {
+      if (traces) await sendQueued('traces', keepalive);
+      if (logs) await sendQueued('logs', keepalive);
+      if (metrics) {
+        const t = now();
+        const groups = [...mappers.values()]
+          .map((m) => ({ resource: m.resource, metrics: m.collectMetrics(t) }))
+          .filter((g) => g.metrics.length > 0);
+        if (groups.length) await sender.send('metrics', encodeMetrics(groups), { keepalive });
+      }
+      for (const key of released) {
+        const m = mappers.get(key);
+        if (!m || (m.spans.length === 0 && m.logs.length === 0)) {
+          mappers.delete(key);
+          released.delete(key);
+        }
+      }
+    } finally {
+      flushing = false;
+    }
+  };
+
+  const flush = (f?: { keepalive?: boolean }): Promise<void> => {
+    chain = chain.then(() => doFlush(!!f?.keepalive)).catch(() => {});
+    return chain;
+  };
+
+  const interval = opts.flushIntervalMs ?? 5000;
+  const timer = interval > 0 ? setInterval(() => void flush(), interval) : undefined;
+  (timer as unknown as { unref?: () => void } | undefined)?.unref?.();
+
+  return {
+    ingest(ev, recvEpochMs, key = '') {
+      if (closed) return;
+      let m = mappers.get(key);
+      if (!m) {
+        m = newMapper(key);
+        mappers.set(key, m);
+      }
+      released.delete(key);
+      m.ingest(ev, recvEpochMs);
+      if (!flushing && (m.spans.length >= maxBatch || m.logs.length >= maxBatch)) void flush();
+    },
+    release(key) {
+      if (mappers.has(key)) released.add(key);
+    },
+    flush,
+    async close() {
+      if (closed) return chain;
+      closed = true;
+      if (timer) clearInterval(timer);
+      return flush();
+    },
+  };
+}
+
+/* ── resource ────────────────────────────────────────────────────────────── */
+
+export type ResourceAttributes = Record<string, string | number | boolean | undefined>;
+
+/** Resource attributes for this process: service.name, telemetry.sdk.*, runtime hints. */
+export function localResource(serviceName?: string, extra: ResourceAttributes = {}): KeyValue[] {
+  const g = globalThis as {
+    window?: { document?: unknown };
+    navigator?: { userAgent?: string };
+    process?: { pid?: number; versions?: { node?: string } };
+  };
+  const browser = typeof g.window !== 'undefined' && typeof g.window.document !== 'undefined';
+  const node = !browser && g.process?.versions?.node !== undefined;
+  return toAttributes({
+    'service.name': serviceName ?? 'unknown_service',
+    'telemetry.sdk.name': 'atoll',
+    'telemetry.sdk.language': node ? 'nodejs' : 'webjs',
+    ...(node
+      ? {
+          'process.pid': g.process?.pid,
+          'process.runtime.name': 'nodejs',
+          'process.runtime.version': g.process?.versions?.node,
+        }
+      : { 'user_agent.original': g.navigator?.userAgent }),
+    ...extra,
+  });
+}
+
+/**
+ * Resource attributes for a remote app session (aggregate-server
+ * forwarding): the session name is the service unless a fixed one is given.
+ */
+export function sessionResource(
+  session: SessionInfo,
+  serviceName?: string,
+  extra: ResourceAttributes = {},
+): KeyValue[] {
+  const node = session.runtime === 'node';
+  return toAttributes({
+    'service.name': serviceName ?? session.name ?? 'unknown_service',
+    'service.instance.id': session.id,
+    'telemetry.sdk.name': 'atoll',
+    'telemetry.sdk.language': node ? 'nodejs' : 'webjs',
+    ...(node
+      ? { 'process.runtime.name': 'nodejs', 'process.runtime.version': session.env?.node?.replace(/^v/, '') }
+      : { 'user_agent.original': session.env?.userAgent }),
+    'atoll.session.hint': session.hint,
+    'atoll.framework': session.framework,
+    ...extra,
+  });
+}

package/src/overlay.ts

@@ -9,6 +9,11 @@
  *     connectDevtools();
  *     mountDevtoolsOverlay();
  *   }
+ *
+ * Alt+Shift+D toggles the flyout from the host page (`hotkey` option). The
+ * dashboard inside the iframe forwards the same chord via postMessage, so
+ * it works wherever focus is. "full page ↗" opens the dashboard on the
+ * view the flyout is showing (its `#/<view>…` hash route).
  */
 
 export type DevtoolsOverlayPosition =
@@ -22,13 +27,20 @@ export type DevtoolsOverlayPosition =
 export interface DevtoolsOverlayOptions {
   /** Dashboard URL — default '/__atoll/?mini=1' (vite-plugin mount, mini layout). */
   src?: string;
-  /** Start expanded (default false — a small corner toggle shows first). */
+  /** Start expanded (default: the remembered state, else collapsed to a corner toggle). */
   startOpen?: boolean;
-  /** Initial size (default 760×580). */
+  /** Initial size (default 760×580; a remembered resize wins). */
   width?: number;
   height?: number;
   /** Where the flyout (and its collapsed toggle) anchors — default 'bottomright'. */
   position?: DevtoolsOverlayPosition;
+  /**
+   * Remember position, size and open state in localStorage across reloads —
+   * default true; a string is the storage key (default 'atoll-devtools:overlay').
+   */
+  persist?: boolean | string;
+  /** Host-page shortcut that toggles the flyout — default 'Alt+Shift+D'; false disables. */
+  hotkey?: string | false;
 }
 
 export interface DevtoolsOverlay {
@@ -38,6 +50,14 @@ export interface DevtoolsOverlay {
   unmount(): void;
 }
 
+interface Saved {
+  left?: number;
+  top?: number;
+  width?: number;
+  height?: number;
+  open?: boolean;
+}
+
 const BTN_STYLE =
   'position:fixed;z-index:2147483646;' +
   'font:11px ui-monospace,monospace;color:#c9d1d9;background:#161b22;' +
@@ -57,18 +77,53 @@ const ANCHOR: Record<DevtoolsOverlayPosition, (m: number) => string> = {
   bottomright: (m) => `right:${m}px;bottom:${m}px`,
 };
 
+const MIN_W = 340;
+const MIN_H = 220;
+let seq = 0;
+
+/** 'Alt+Shift+D' → a keydown predicate. Letters/digits match on `code`, so Alt/Option layouts still hit. */
+export function parseHotkey(spec: string): (e: KeyboardEvent) => boolean {
+  const parts = spec.split('+').map((p) => p.trim().toLowerCase()).filter(Boolean);
+  const key = parts.pop() ?? '';
+  const mods = new Set(parts.map((m) => (m === 'option' ? 'alt' : m === 'cmd' || m === 'meta' ? 'meta' : m === 'control' ? 'ctrl' : m)));
+  const code = /^[a-z]$/.test(key) ? `Key${key.toUpperCase()}` : /^[0-9]$/.test(key) ? `Digit${key}` : null;
+  return (e) =>
+    e.altKey === mods.has('alt') &&
+    e.shiftKey === mods.has('shift') &&
+    e.ctrlKey === mods.has('ctrl') &&
+    e.metaKey === mods.has('meta') &&
+    (code ? e.code === code : e.key.toLowerCase() === key);
+}
+
 export function mountDevtoolsOverlay(opts: DevtoolsOverlayOptions = {}): DevtoolsOverlay {
   const src = opts.src ?? '/__atoll/?mini=1';
-  const W = opts.width ?? 760;
-  const H = opts.height ?? 580;
+  const storeKey = opts.persist === false ? null : typeof opts.persist === 'string' ? opts.persist : 'atoll-devtools:overlay';
+  const load = (): Saved => {
+    if (!storeKey) return {};
+    try { return JSON.parse(localStorage.getItem(storeKey) ?? '{}') as Saved; } catch { return {}; }
+  };
+  const saved = load();
+  const W = Math.max(MIN_W, saved.width ?? opts.width ?? 760);
+  const H = Math.max(MIN_H, saved.height ?? opts.height ?? 580);
   const anchor = ANCHOR[opts.position ?? 'bottomright'];
+  const hotkey = opts.hotkey === false ? null : opts.hotkey ?? 'Alt+Shift+D';
+  const isHotkey = hotkey ? parseHotkey(hotkey) : null;
+  const hint = hotkey ? ` (${hotkey})` : '';
+  const id = `atoll-devtools-overlay-${++seq}`;
   let open = false;
 
   const btn = document.createElement('button');
+  btn.type = 'button';
   btn.textContent = 'atoll devtools';
+  btn.title = `Open atoll devtools${hint}`;
+  btn.setAttribute('aria-controls', id);
+  btn.setAttribute('aria-expanded', 'false');
   btn.style.cssText = `${BTN_STYLE};${anchor(12)}`;
 
   const panel = document.createElement('div');
+  panel.id = id;
+  panel.setAttribute('role', 'dialog');
+  panel.setAttribute('aria-label', 'atoll devtools');
   panel.style.cssText =
     `${PANEL_STYLE};width:${W}px;height:${H}px;display:none;${anchor(16)}`;
 
@@ -77,37 +132,89 @@ export function mountDevtoolsOverlay(opts: DevtoolsOverlayOptions = {}): Devtool
     'display:flex;align-items:center;gap:8px;padding:5px 10px;flex:none;' +
     'border-bottom:1px solid #21262d;font:11px ui-monospace,monospace;' +
     'color:#8b949e;background:#161b22;cursor:move;user-select:none';
-  head.textContent = 'atoll devtools';
+  const title = document.createElement('span');
+  title.textContent = 'atoll devtools';
 
+  // Full-page dashboard = src minus its query/hash — stays relative when the
+  // caller passes a relative src (e.g. '__atoll/?mini=1' under a mounted
+  // base path where absolute /__atoll/ would escape the mount) — plus the
+  // iframe's current hash route, so the tab opens on the same view.
+  const base = src.split(/[?#]/)[0];
+  const frame = document.createElement('iframe');
+  let route = '';
+  const currentRoute = (): string => {
+    try {
+      const h = frame.contentWindow?.location.hash;
+      if (typeof h === 'string' && h.startsWith('#/')) return h;
+    } catch { /* cross-origin src: rely on posted routes */ }
+    return route;
+  };
   const pop = document.createElement('a');
-  pop.href = '/__atoll/';
+  pop.href = base;
   pop.target = '_blank';
   pop.rel = 'noopener';
   pop.textContent = 'full page ↗';
+  pop.title = 'Open this view in the full-page dashboard';
   pop.style.cssText = 'color:#58a6ff;text-decoration:none;margin-left:auto';
+  const syncPop = () => { pop.href = base + currentRoute(); };
+  pop.addEventListener('pointerenter', syncPop);
+  pop.addEventListener('focus', syncPop);
+  pop.addEventListener('click', syncPop); // runs before the default navigation
   const x = document.createElement('button');
-  x.textContent = '—';
-  x.title = 'collapse';
+  x.type = 'button';
+  x.textContent = '×';
+  x.title = `Close${hint}`;
+  x.setAttribute('aria-label', 'Close atoll devtools');
   x.style.cssText =
-    'color:#8b949e;background:none;border:none;cursor:pointer;font:inherit;padding:0 2px';
-  head.append(pop, x);
+    'color:#8b949e;background:none;border:none;cursor:pointer;font:14px/1 ui-monospace,monospace;padding:0 2px';
+  head.append(title, pop, x);
 
-  const frame = document.createElement('iframe');
   frame.src = src;
+  frame.title = 'atoll devtools dashboard';
   frame.style.cssText = 'flex:1;border:0;background:#0d1117;min-height:0';
 
   // manual resize grip — CSS `resize` doesn't work over an iframe
   const grip = document.createElement('div');
+  grip.setAttribute('aria-hidden', 'true');
   grip.style.cssText =
     'position:absolute;right:0;bottom:0;width:16px;height:16px;cursor:nwse-resize;' +
     'background:linear-gradient(135deg,transparent 50%,#30363d 50%);border-radius:0 0 7px';
   panel.append(head, frame, grip);
   document.body.append(panel, btn);
 
+  const placeAt = (left: number, top: number) => {
+    // keep at least 40px of the title bar on screen
+    panel.style.left = `${Math.min(Math.max(0, left), Math.max(0, innerWidth - 60))}px`;
+    panel.style.top = `${Math.min(Math.max(0, top), Math.max(0, innerHeight - 40))}px`;
+    panel.style.right = 'auto';
+    panel.style.bottom = 'auto';
+    panel.style.transform = 'none'; // drop the center anchor's translateX
+  };
+  if (typeof saved.left === 'number' && typeof saved.top === 'number') placeAt(saved.left, saved.top);
+
+  // Only what the user changed is remembered: an untouched size/position
+  // keeps following the options.
+  const mem: Saved = { ...saved };
+  const save = (what: 'open' | 'move' | 'size') => {
+    if (!storeKey) return;
+    if (what === 'open') mem.open = open;
+    if (what === 'size') {
+      mem.width = parseFloat(panel.style.width);
+      mem.height = parseFloat(panel.style.height);
+    }
+    if (what === 'move') {
+      mem.left = parseFloat(panel.style.left);
+      mem.top = parseFloat(panel.style.top);
+    }
+    try { localStorage.setItem(storeKey, JSON.stringify(mem)); } catch { /* storage off */ }
+  };
+
   /** Pointer-drag helper: run `move` on pointermove until pointerup. */
-  const drag = (e: PointerEvent, move: (dx: number, dy: number) => void) => {
+  const drag = (e: PointerEvent, what: 'move' | 'size', move: (dx: number, dy: number) => void) => {
     e.preventDefault();
     let lx = e.clientX, ly = e.clientY;
+    // the iframe would swallow pointermove while the cursor is over it
+    frame.style.pointerEvents = 'none';
     const mm = (ev: PointerEvent) => {
       move(ev.clientX - lx, ev.clientY - ly);
       lx = ev.clientX; ly = ev.clientY;
@@ -115,6 +222,8 @@ export function mountDevtoolsOverlay(opts: DevtoolsOverlayOptions = {}): Devtool
     const up = () => {
       removeEventListener('pointermove', mm);
       removeEventListener('pointerup', up);
+      frame.style.pointerEvents = '';
+      save(what);
     };
     addEventListener('pointermove', mm);
     addEventListener('pointerup', up);
@@ -122,42 +231,59 @@ export function mountDevtoolsOverlay(opts: DevtoolsOverlayOptions = {}): Devtool
 
   head.onpointerdown = (e) => {
     if ((e.target as HTMLElement).closest('a,button')) return;
-    drag(e, (dx, dy) => {
+    drag(e, 'move', (dx, dy) => {
       const r = panel.getBoundingClientRect();
-      // keep at least 40px of the title bar on screen
-      const left = Math.min(Math.max(0, r.left + dx), innerWidth - 60);
-      const top = Math.min(Math.max(0, r.top + dy), innerHeight - 40);
-      panel.style.left = `${left}px`;
-      panel.style.top = `${top}px`;
-      panel.style.right = 'auto';
-      panel.style.bottom = 'auto';
-      panel.style.transform = 'none'; // drop the center anchor's translateX
+      placeAt(r.left + dx, r.top + dy);
     });
   };
 
   grip.onpointerdown = (e) => {
     e.stopPropagation();
-    drag(e, (dx, dy) => {
+    drag(e, 'size', (dx, dy) => {
       const r = panel.getBoundingClientRect();
-      panel.style.width = `${Math.max(340, r.width + dx)}px`;
-      panel.style.height = `${Math.max(220, r.height + dy)}px`;
+      panel.style.width = `${Math.max(MIN_W, r.width + dx)}px`;
+      panel.style.height = `${Math.max(MIN_H, r.height + dy)}px`;
     });
   };
 
-  const set = (v: boolean) => {
+  const set = (v: boolean, focus = false, persist = true) => {
+    const hadFocus = panel.contains(document.activeElement);
     open = v;
     panel.style.display = v ? 'flex' : 'none';
     btn.style.display = v ? 'none' : 'block';
+    btn.setAttribute('aria-expanded', String(v));
+    if (v && focus) frame.focus();
+    if (!v && hadFocus) btn.focus();
+    if (persist) save('open');
   };
-  btn.onclick = () => set(true);
+  btn.onclick = () => set(true, true);
   x.onclick = () => set(false);
-  set(opts.startOpen === true);
+
+  const onKey = (e: KeyboardEvent) => {
+    if (!isHotkey?.(e)) return;
+    e.preventDefault();
+    set(!open, true);
+  };
+  const onMessage = (e: MessageEvent) => {
+    if (e.source !== frame.contentWindow || !e.data || typeof e.data !== 'object') return;
+    const d = e.data as { type?: string; hash?: unknown };
+    if (d.type === 'atoll-devtools:toggle') set(!open);
+    else if (d.type === 'atoll-devtools:route' && typeof d.hash === 'string' && d.hash.startsWith('#/')) {
+      route = d.hash;
+    }
+  };
+  if (isHotkey) addEventListener('keydown', onKey);
+  addEventListener('message', onMessage);
+
+  set(opts.startOpen ?? saved.open === true, false, false);
 
   return {
     open: () => set(true),
     close: () => set(false),
     toggle: () => set(!open),
     unmount: () => {
+      removeEventListener('keydown', onKey);
+      removeEventListener('message', onMessage);
       panel.remove();
       btn.remove();
     },