@crvouga/atlas 0.4.0 → 0.5.0

package/packages/visualizer/src/live/live-stream.ts

@@ -0,0 +1,204 @@
+import { AtlasChangeSchema, type AtlasChange } from '@crvouga/atlas/schema';
+import { useSyncExternalStore } from 'react';
+
+import { runtimeConfig, runtimeUrl } from '../runtime';
+
+/** What the server tells a viewer as it happens. */
+export type LiveEvent =
+  | { readonly type: 'open' }
+  | { readonly type: 'report'; readonly report: ReportAnnouncement }
+  | { readonly type: 'change'; readonly change: AtlasChange };
+
+/** One announcement that results arrived: enough to say who sent them without asking again. */
+export type ReportAnnouncement = {
+  readonly version: string;
+  readonly totalLayers: number;
+  readonly addedTotal: number;
+  readonly added: readonly {
+    readonly id: string;
+    readonly producer: string;
+    readonly environment?: string | null;
+    readonly branch?: string | null;
+    readonly counts?: Readonly<Record<string, number>>;
+  }[];
+};
+
+/** `connecting` before the first answer, `live` while the stream is open, `reconnecting` after it was lost. */
+export type LiveStatus = 'off' | 'connecting' | 'live' | 'reconnecting';
+
+type Listener = (event: LiveEvent) => void;
+
+/** The server sends a comment every 15 seconds; this long without a word means the connection is dead. */
+const SILENCE_MS = 45_000;
+const BACKOFF_MS = [1_000, 2_000, 5_000, 10_000, 30_000] as const;
+
+type Stream = {
+  readonly url: string;
+  readonly listeners: Set<Listener>;
+  source: EventSource | null;
+  status: LiveStatus;
+  attempts: number;
+  timer: ReturnType<typeof setTimeout> | null;
+  watchdog: ReturnType<typeof setTimeout> | null;
+};
+
+const streams = new Map<string, Stream>();
+const statusListeners = new Set<() => void>();
+
+function setStatus(stream: Stream, status: LiveStatus) {
+  if (stream.status === status) return;
+  stream.status = status;
+  for (const listener of statusListeners) listener();
+}
+
+function emit(stream: Stream, event: LiveEvent) {
+  for (const listener of [...stream.listeners]) {
+    try {
+      listener(event);
+    } catch {
+      // One listener's mistake must not stop the others hearing.
+    }
+  }
+}
+
+function parse(data: string): unknown {
+  try {
+    return JSON.parse(data) as unknown;
+  } catch {
+    return null;
+  }
+}
+
+function connect(stream: Stream) {
+  if (typeof EventSource === 'undefined') return;
+  stream.timer = null;
+  const source = new EventSource(stream.url);
+  stream.source = source;
+  const heard = () => {
+    if (stream.watchdog) clearTimeout(stream.watchdog);
+    stream.watchdog = setTimeout(() => lose(stream), SILENCE_MS);
+  };
+  source.addEventListener('open', () => {
+    heard();
+    stream.attempts = 0;
+    setStatus(stream, 'live');
+    // Anything may have happened while the stream was away, so a (re)connection reads everything again.
+    emit(stream, { type: 'open' });
+  });
+  source.addEventListener('hello', heard);
+  source.addEventListener('ping', heard);
+  source.addEventListener('report', (event) => {
+    heard();
+    const report = parse((event as MessageEvent<string>).data) as ReportAnnouncement | null;
+    if (report && typeof report.version === 'string') emit(stream, { type: 'report', report: { ...report, added: Array.isArray(report.added) ? report.added : [] } });
+  });
+  source.addEventListener('atlas:change', (event) => {
+    heard();
+    const change = AtlasChangeSchema.safeParse(parse((event as MessageEvent<string>).data));
+    if (change.success) emit(stream, { type: 'change', change: change.data });
+  });
+  // The server's heartbeat is a named `ping` event, so a quiet server is told apart from a dead connection.
+  source.addEventListener('error', () => {
+    setStatus(stream, stream.attempts === 0 && stream.status === 'connecting' ? 'connecting' : 'reconnecting');
+    // The browser retries a dropped stream by itself. A refused one (401, 503) it gives up on: retry that here, slowly.
+    if (source.readyState === EventSource.CLOSED) lose(stream);
+  });
+  heard();
+}
+
+function lose(stream: Stream) {
+  if (stream.watchdog) clearTimeout(stream.watchdog);
+  stream.watchdog = null;
+  stream.source?.close();
+  stream.source = null;
+  if (!stream.listeners.size) return;
+  setStatus(stream, 'reconnecting');
+  if (stream.timer) return;
+  const wait = BACKOFF_MS[Math.min(stream.attempts, BACKOFF_MS.length - 1)]!;
+  stream.attempts += 1;
+  stream.timer = setTimeout(() => connect(stream), wait);
+}
+
+function release(stream: Stream) {
+  if (stream.listeners.size) return;
+  if (stream.timer) clearTimeout(stream.timer);
+  if (stream.watchdog) clearTimeout(stream.watchdog);
+  stream.source?.close();
+  streams.delete(stream.url);
+  setStatus(stream, 'off');
+}
+
+/**
+ * Hear what the server at `url` announces. Everything in the page that listens to one address shares one
+ * connection, which is opened with the first listener and closed with the last.
+ */
+export function listenLive(url: string, listener: Listener): () => void {
+  let stream = streams.get(url);
+  if (!stream) {
+    stream = { url, listeners: new Set(), source: null, status: 'connecting', attempts: 0, timer: null, watchdog: null };
+    streams.set(url, stream);
+    stream.listeners.add(listener);
+    connect(stream);
+    for (const notify of statusListeners) notify();
+  } else {
+    stream.listeners.add(listener);
+  }
+  const mine = stream;
+  return () => {
+    mine.listeners.delete(listener);
+    release(mine);
+  };
+}
+
+/** Changes to specs and runs, in the form the data layer already understands. */
+export function listenChanges(url: string, onChange: (change: AtlasChange) => void): () => void {
+  return listenLive(url, (event) => {
+    if (event.type === 'change') onChange(event.change);
+    // A fresh connection may have missed changes while it was away.
+    if (event.type === 'open') onChange({ scope: 'runs', files: [], runIds: [] });
+  });
+}
+
+/** The address of this server's event stream, when the page has one. */
+export const eventsAddress = () => runtimeUrl(runtimeConfig()?.eventsUrl);
+
+function snapshot(): LiveStatus {
+  const url = eventsAddress();
+  return (url && streams.get(url)?.status) || (url ? 'connecting' : 'off');
+}
+
+function subscribeStatus(listener: () => void) {
+  statusListeners.add(listener);
+  return () => statusListeners.delete(listener);
+}
+
+/** Whether the report on screen is being kept up to date by the server. `off` for a static site. */
+export function useLiveStatus(): LiveStatus {
+  return useSyncExternalStore(subscribeStatus, snapshot, () => 'off');
+}
+
+/** Test seam: forget every stream. */
+export function resetLiveStreams() {
+  for (const stream of streams.values()) {
+    stream.listeners.clear();
+    release(stream);
+  }
+  streams.clear();
+}
+
+/**
+ * `act` at once, and then no more than once per `ms` however often it is called: a call made inside the wait
+ * runs when the wait ends. The last word is never lost.
+ */
+export function throttled(act: () => void, ms: number): (() => void) & { cancel: () => void } {
+  let last = -Infinity;
+  let timer: ReturnType<typeof setTimeout> | null = null;
+  const call = () => {
+    if (timer) return;
+    const wait = last + ms - Date.now();
+    if (wait <= 0) { last = Date.now(); act(); return; }
+    timer = setTimeout(() => { timer = null; last = Date.now(); act(); }, wait);
+  };
+  call.cancel = () => { if (timer) clearTimeout(timer); timer = null; };
+  return call;
+}

package/packages/visualizer/src/runtime.ts

@@ -0,0 +1,19 @@
+/**
+ * The address book an Atlas server writes into the page it serves (`window.__ATLAS_CONFIG__`), so one build
+ * of the viewer works for every project and on every host. Under `atlas dev` the Vite dev server writes the
+ * same thing, so the viewer cannot tell the two apart: both are one host, with `/api` behind it.
+ */
+export type RuntimeConfig = {
+  readonly api?: string;
+  readonly reportsUrl?: string;
+  readonly dataUrl?: string;
+  readonly eventsUrl?: string;
+  readonly effective?: boolean;
+};
+
+export const runtimeConfig = (): RuntimeConfig | undefined => (globalThis as { __ATLAS_CONFIG__?: RuntimeConfig }).__ATLAS_CONFIG__;
+
+/** An address from the config, resolved against the page, as an absolute URL. */
+export function runtimeUrl(value: string | undefined): string | undefined {
+  return value ? new URL(value, window.location.href).href : undefined;
+}

package/packages/visualizer/vite/atlas-server-proxy.ts

@@ -0,0 +1,36 @@
+import type { Plugin, ProxyOptions } from 'vite';
+
+/** What the viewer is told about the server it is served with: the same words `atlas serve` writes into its page. */
+export const serverPageConfig = { api: './api', reportsUrl: './api/reports', dataUrl: './api/data/', eventsUrl: './api/events', effective: true } as const;
+
+/**
+ * Put the Atlas server behind the dev server. The browser talks to one host; `/api` goes to the server, so the
+ * page, its data and its event stream have one origin in development exactly as they do when deployed.
+ */
+export function atlasServerProxy(target: string): { readonly proxy: Record<string, ProxyOptions> } {
+  return {
+    proxy: {
+      '/api': {
+        target,
+        changeOrigin: false,
+        ws: false,
+        // The event stream stays open for hours: no timeout, and nothing may hold its bytes back.
+        timeout: 0,
+        proxyTimeout: 0,
+        configure: (proxy) => {
+          proxy.on('proxyRes', (response) => {
+            if (String(response.headers['content-type'] ?? '').startsWith('text/event-stream')) response.headers['cache-control'] = 'no-cache, no-transform';
+          });
+        }
+      }
+    }
+  };
+}
+
+/** Write the server's address book into the page the dev server serves. */
+export function atlasServerPage(): Plugin {
+  return {
+    name: 'atlas-server-page',
+    transformIndexHtml: () => [{ tag: 'script', children: `window.__ATLAS_CONFIG__=${JSON.stringify(serverPageConfig)}`, injectTo: 'head-prepend' }]
+  };
+}

package/packages/visualizer/vite.config.ts

@@ -8,14 +8,22 @@ import { resolveRoots } from './vite/atlas-files';
 import { servesExampleReports } from './vite/example-reports';
 import { reportsDevPlugin } from './vite/reports-dev-plugin';
 import { atlasDevPlugin } from './vite/atlas-dev-plugin';
+import { atlasServerPage, atlasServerProxy } from './vite/atlas-server-proxy';
 
 const appRoot = path.dirname(fileURLToPath(import.meta.url));
-const reportsModule = process.env.ATLAS_REPORTS_MODULE || (servesExampleReports(resolveRoots().specs) ? path.join(appRoot, 'vite/example-reports.ts') : '');
+
+// `atlas dev` runs the Atlas server on a port of its own and tells this config where. The browser then talks to
+// this dev server alone: `/api` is proxied to the server, and the page gets the same address book a served
+// build gets, so the viewer cannot tell the two apart. Without a server, the viewer reads the working tree.
+const serverUrl = process.env.ATLAS_API_URL || '';
+const reportsModule = serverUrl ? '' : process.env.ATLAS_REPORTS_MODULE || (servesExampleReports(resolveRoots().specs) ? path.join(appRoot, 'vite/example-reports.ts') : '');
 
 export default defineConfig({
   base: './',
-  plugins: [react(), atlasDevPlugin(), ...(reportsModule ? [reportsDevPlugin({ repoRoot: process.env.INIT_CWD || process.cwd(), appModule: reportsModule })] : [])],
+  plugins: serverUrl
+    ? [react(), atlasServerPage()]
+    : [react(), atlasDevPlugin(), ...(reportsModule ? [reportsDevPlugin({ repoRoot: process.env.INIT_CWD || process.cwd(), appModule: reportsModule })] : [])],
   worker: { format: 'es' },
-  server: { port: Number(process.env.PORT ?? 5180), strictPort: false },
+  server: { port: Number(process.env.PORT ?? 5180), strictPort: false, ...(serverUrl ? atlasServerProxy(serverUrl) : {}) },
   build: { outDir: 'dist', emptyOutDir: true, chunkSizeWarningLimit: 2_500 }
 });