Skip to content

Turbocharge Claude Code, Cursor, Codex, Gemini & every coding agent: faster, cheaper, with contextual understanding specific to your codebase.

5.5 KB
Raw Blame
/**
 * The local event queue: one NDJSON line per event in `~/.graft/`.
 *
 * The queue exists because graft is a CLI, not an app. Every other tool we
 * studied sends from a process that is already running and can afford to wait;
 * `graft ask` lives for two seconds and its whole value proposition is being
 * faster than reading files. So nothing is ever sent inline — events are
 * appended here, and a detached child (`graft _telemetry-flush`, once a day)
 * does the network. A user who is offline for a week loses nothing; a user on a
 * hostile network never notices, because no command ever waits on a socket.
 *
 * Concurrency: appends are a single `appendFileSync` of one short line to a file
 * opened `O_APPEND`, which POSIX makes atomic below PIPE_BUF (4 KB — an event is
 * ~300 bytes). Two graft processes interleaving cannot produce a torn line.
 *
 * Draining renames the file first and reads the renamed copy, so events appended
 * during a flush land in a fresh queue instead of being dropped by the truncate.
 */
import { homedir } from 'node:os';
import { join } from 'node:path';
import { readFileSync, renameSync, rmSync, statSync } from 'node:fs';
import { appendPrivateFile, writePrivateFile } from '../util/private-file.js';

/**
 * The ceiling on the queue. An unflushable machine — permanently offline, or a
 * key that never works — must not grow a file in someone's home forever.
 *
 * Bytes are the bound, because size is the only thing cheap enough to check on
 * every append (one `statSync`); counting lines would mean reading the whole
 * file each time. {@link TRIM_TO_EVENTS} is not a second ceiling — it is how
 * FAR a trim cuts back, so a queue of unusually small events sheds a worthwhile
 * amount rather than one line at a time. Between trims the file can hold more
 * than that many events, and can exceed the byte bound by one append.
 */
export const MAX_QUEUE_BYTES = 256 * 1024;
export const TRIM_TO_EVENTS = 500;

export function queuePath(home: string = homedir()): string {
  return join(home, '.graft', 'telemetry-queue.ndjson');
}

/**
 * Append one event. Never throws — a full disk or a read-only home must not fail
 * the command the user actually ran.
 */
export function enqueue(event: unknown, home?: string): void {
  const path = queuePath(home);
  try {
    // Owner-only, folder included: it waits here to be sent.
    appendPrivateFile(path, JSON.stringify(event) + '\n');
    trim(path);
  } catch { /* unwritable home, full disk — telemetry is never worth an error */ }
}

/**
 * Enforce the cap by dropping the OLDEST events. Newest-wins because the recent
 * ones describe the version the user is on now; a year-old queue from 0.9
 * answers nothing. Only rewrites when actually over, so the common path is one
 * `statSync`.
 */
function trim(path: string): void {
  let size: number;
  try { size = statSync(path).size; } catch { return; }
  if (size <= MAX_QUEUE_BYTES) return;
  try {
    const lines = readFileSync(path, 'utf8').split('\n').filter(Boolean);
    // Walk backwards from the newest, taking lines while both budgets hold, so
    // the file left behind always satisfies the byte bound — a count-only trim
    // would leave 500 large events well over it.
    const kept: string[] = [];
    let bytes = 0;
    for (let i = lines.length - 1; i >= 0 && kept.length < TRIM_TO_EVENTS; i--) {
      bytes += Buffer.byteLength(lines[i]) + 1;
      if (bytes > MAX_QUEUE_BYTES) break;
      kept.push(lines[i]);
    }
    kept.reverse();
    writePrivateFile(path, kept.length ? kept.join('\n') + '\n' : '');
  } catch { /* leave it; the next drain clears it anyway */ }
}

/**
 * Take everything pending, leaving an empty queue behind.
 *
 * The rename is what makes this safe against a concurrent append: from the
 * instant it returns, other processes are writing to a brand-new file. Malformed
 * lines are skipped rather than poisoning the batch — a torn write from a crash
 * mid-append should cost one event, not the whole queue.
 */
export function drain(home?: string): unknown[] {
  const path = queuePath(home);
  const taken = `${path}.${process.pid}.sending`;
  try { renameSync(path, taken); } catch { return []; } // nothing queued
  let text = '';
  try { text = readFileSync(taken, 'utf8'); } catch { /* fall through to cleanup */ }
  try { rmSync(taken, { force: true }); } catch { /* best effort */ }
  const out: unknown[] = [];
  for (const line of text.split('\n')) {
    if (!line.trim()) continue;
    try { out.push(JSON.parse(line)); } catch { /* torn line — skip just this one */ }
  }
  return out;
}

/** Read without draining, for `graft telemetry debug`. */
export function peek(home?: string): unknown[] {
  const out: unknown[] = [];
  let text = '';
  try { text = readFileSync(queuePath(home), 'utf8'); } catch { return out; }
  for (const line of text.split('\n')) {
    if (!line.trim()) continue;
    try { out.push(JSON.parse(line)); } catch { /* skip */ }
  }
  return out;
}

/** Put a failed batch back, so a flush that could not reach the network does not
 *  silently discard a week of events. Oldest-first, ahead of anything queued
 *  since the drain. */
export function requeue(events: unknown[], home?: string): void {
  if (events.length === 0) return;
  const path = queuePath(home);
  try {
    const pending = (() => { try { return readFileSync(path, 'utf8'); } catch { return ''; } })();
    writePrivateFile(path, events.map((e) => JSON.stringify(e)).join('\n') + '\n' + pending);
    trim(path);
  } catch { /* best effort */ }
}