ravensight-playtest 0.1.0

package/src/run/state.js

@@ -0,0 +1,198 @@
+import { randomUUID } from 'node:crypto';
+import { mkdir, readFile, rename, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { jobDir, JOB_FILES } from './paths.js';
+
+/**
+ * `state.json`, the resumable job journal (spec 17 section 1.8). Written
+ * atomically after every step, so a Ctrl-C between two writes leaves the
+ * last complete journal on disk rather than half of the next one.
+ *
+ * What is NOT in here, deliberately:
+ *
+ * - **No playtest tokens.** They are JWTs, and a JWT written into a file
+ *   under the developer's repo is both a secret on disk and something this
+ *   CLI's own secret scan would refuse. `resume` gets tokens back by
+ *   replaying `POST /jobs` with `idempotency_key`: the server answers a
+ *   known `{gameId, idempotencyKey}` with the stored job and *freshly
+ *   minted* tokens, which is exactly why replay mints instead of returning
+ *   what it stored.
+ * - **No money.** `price_cents` is recorded for display, but what was
+ *   charged and what gets refunded is the server's ledger. Resume never
+ *   re-charges, because it replays the same idempotency key.
+ *
+ * The shape is shared with cli-core's `resume` command, which reads this
+ * file. Bump `SCHEMA_VERSION` if a field changes meaning; `load` refuses a
+ * journal from a newer CLI rather than guessing.
+ */
+
+/**
+ * Matches cli-core's `STATE_VERSION`, and the field is spelled the same
+ * (`state_version`), because cli-core's `resume` and `listStates` read this
+ * very file. Two version fields on one document would be two answers to one
+ * question.
+ */
+export const SCHEMA_VERSION = 1;
+
+/** Run states this journal tracks, a subset of the server's PlaytestRun states. */
+export const RUN_DONE_STATES = Object.freeze(['succeeded', 'failed', 'canceled', 'budget_exceeded', 'skipped']);
+
+export class StateVersionError extends Error {
+  constructor(found) {
+    super(`This job was written by a newer ravensight-playtest (state schema ${found}, this build understands ${SCHEMA_VERSION}). Upgrade the CLI and resume again.`);
+    this.name = 'StateVersionError';
+  }
+}
+
+/**
+ * @param {string} repoRoot
+ * @param {string} jobId
+ */
+export function stateFile(repoRoot, jobId) {
+  return path.join(jobDir(repoRoot, jobId), JOB_FILES.state);
+}
+
+/**
+ * A fresh journal for a job that has just been registered.
+ *
+ * @param {Object} init
+ * @returns {Object}
+ */
+export function newState(init) {
+  const now = new Date().toISOString();
+  return {
+    state_version: SCHEMA_VERSION,
+    job_id: init.jobId,
+    game_id: init.gameId,
+    idempotency_key: init.idempotencyKey,
+    cli_version: init.cliVersion || null,
+    pack_version: init.packVersion || null,
+    brief_version: init.briefVersion ?? null,
+    modules: init.modules || [],
+    driver: init.driver,
+    target: init.target,
+    options: init.options || {},
+    price_cents: init.priceCents ?? null,
+    created_at: now,
+    updated_at: now,
+    finished: false,
+    aggregate: { state: 'pending' },
+    runs: {}
+  };
+}
+
+/**
+ * One run's journal entry. `state` mirrors the server's run state so
+ * `resume` can tell a finished run from one that has to start over.
+ *
+ * @param {Object} init
+ * @returns {Object}
+ */
+export function newRunEntry(init) {
+  return {
+    run_id: init.runId,
+    module: init.module,
+    persona: init.persona || null,
+    state: init.state || 'queued',
+    actions_taken: 0,
+    checkpoint_step: 0,
+    quit_reason: null,
+    report_written: false,
+    completed: false,
+    uploaded: false,
+    budget_warned: false,
+    error: null
+  };
+}
+
+/**
+ * Serialises writes per journal file. Personas run in parallel, so two runs
+ * of one job finish a step at the same moment and both save; without this
+ * they interleave, and with a shared temp file name they race each other's
+ * rename outright (which is a real ENOENT, not a theoretical one).
+ *
+ * @type {Map<string, Promise<any>>}
+ */
+const writeQueues = new Map();
+
+/**
+ * Atomic write: a uniquely named temp file in the same directory, then a
+ * rename. Rename inside one directory is atomic on every platform this CLI
+ * supports, so a reader never sees a partial journal.
+ *
+ * @param {string} repoRoot
+ * @param {Object} state
+ */
+export async function save(repoRoot, state) {
+  const target = stateFile(repoRoot, state.job_id);
+  const previous = writeQueues.get(target) || Promise.resolve();
+  const next = previous.then(() => writeOnce(target, state), () => writeOnce(target, state));
+  writeQueues.set(target, next);
+  try {
+    return await next;
+  } finally {
+    if (writeQueues.get(target) === next) writeQueues.delete(target);
+  }
+}
+
+async function writeOnce(target, state) {
+  await mkdir(path.dirname(target), { recursive: true });
+  state.updated_at = new Date().toISOString();
+  const body = `${JSON.stringify(state, null, 2)}\n`;
+  const tmp = `${target}.${process.pid}.${randomUUID()}.tmp`;
+  await writeFile(tmp, body, 'utf8');
+  await rename(tmp, target);
+  return state;
+}
+
+/**
+ * @param {string} repoRoot
+ * @param {string} jobId
+ * @returns {Promise<Object|null>} null when there is no journal
+ */
+export async function load(repoRoot, jobId) {
+  let text;
+  try {
+    text = await readFile(stateFile(repoRoot, jobId), 'utf8');
+  } catch (error) {
+    if (error.code === 'ENOENT') return null;
+    throw error;
+  }
+  const state = JSON.parse(text);
+  const version = Number(state.state_version ?? state.schema_version ?? SCHEMA_VERSION);
+  if (version > SCHEMA_VERSION) throw new StateVersionError(version);
+  return state;
+}
+
+/**
+ * Record a change to one run and flush the journal. Every caller goes
+ * through here rather than mutating and saving separately, so the journal
+ * on disk is never behind the run it describes.
+ *
+ * @param {string} repoRoot
+ * @param {Object} state
+ * @param {string} runId
+ * @param {Object} patch
+ */
+export async function patchRun(repoRoot, state, runId, patch) {
+  const entry = state.runs[runId];
+  if (!entry) throw new Error(`state.json has no run ${runId}`);
+  Object.assign(entry, patch);
+  await save(repoRoot, state);
+  return entry;
+}
+
+/**
+ * Whether this run is finished as far as the journal knows. A resume keeps
+ * these and restarts everything else from the beginning: live game state
+ * cannot be restored, so a half-played persona run is worth less than a
+ * clean one (spec 17 section 1.8).
+ *
+ * @param {Object} entry
+ * @returns {boolean}
+ */
+export function isRunDone(entry) {
+  return Boolean(entry) && (entry.completed === true || RUN_DONE_STATES.includes(entry.state));
+}
+
+export default { SCHEMA_VERSION, newState, newRunEntry, save, load, patchRun, isRunDone, stateFile };

package/src/run/synthetic.js

@@ -0,0 +1,206 @@
+/**
+ * Synthetic telemetry for a playtest run (spec 08), so the dashboard can
+ * show AI personas beside real players.
+ *
+ * This is the runner side emitter, and it is a fallback: a game that has the
+ * Ravensight SDK emits its own events from the same session, tagged the same
+ * way, because the driver passes `RAVENSIGHT_PLAYTEST_TOKEN`,
+ * `RAVENSIGHT_PLAYTEST_RUN_ID`, `RAVENSIGHT_PLAYTEST_JOB_ID` and
+ * `RAVENSIGHT_PLAYTEST_PERSONA` into the game's environment and
+ * `Ravensight.gd` reads them at boot. This module covers the builds that do
+ * not have the SDK at all, which is most web builds on the first run.
+ *
+ * Two things changed from the PoC's `synthetic_events.ts`:
+ *
+ * 1. **The playtest token, not just an ingest key.** `POST /api/v1/session`
+ *    takes the ingest key for game identity (`authenticateIngestKey`, the
+ *    game is never read from the body) and the run's scoped playtest JWT in
+ *    `X-Ravensight-Playtest`. The token is what marks the session synthetic:
+ *    the server forces `deviceId` to `pt-<runId>` and `platform` to
+ *    `ravensight-playtest` whatever the body says, so two runs of one job
+ *    can never merge into one "player" and a playtest can never take over a
+ *    real device id that already has history.
+ * 2. **Synthetic events cost the customer nothing.** `reserveQuota` returns
+ *    immediately for a synthetic session, so no `Usage` or `AccountUsage`
+ *    document is written. They also ride a separate rate limit bucket
+ *    (3000/min) so a running pack cannot 429 the game's real players.
+ *
+ * Failure here never fails a run. The report is the product; telemetry is a
+ * nicety, and a dropped batch is not worth throwing away a playthrough the
+ * developer already paid for.
+ */
+
+/** Documented maximum events per `/track/batch` call. */
+export const MAX_BATCH = 50;
+
+/** Documented maximum bytes of `data` per event. */
+export const MAX_DATA_BYTES = 8000;
+
+/** How long to wait out a 429 before requeuing the batch. */
+export const BACKOFF_MS = 5000;
+
+export class SyntheticSession {
+  /**
+   * @param {Object} args
+   * @param {string} args.apiUrl
+   * @param {string} args.ingestKey the game's gt_live_ key
+   * @param {string} args.playtestToken the run's scoped token
+   * @param {{jobId: string, runId: string, persona: string, gameVersion: string}} args.context
+   * @param {Function} [args.fetchImpl] test seam
+   * @param {Function} [args.sleep] test seam
+   */
+  constructor({ apiUrl, ingestKey, playtestToken, context, fetchImpl = fetch, sleep }) {
+    this.apiUrl = String(apiUrl).replace(/\/+$/, '');
+    this.ingestKey = ingestKey;
+    this.playtestToken = playtestToken;
+    this.context = context;
+    this.fetchImpl = fetchImpl;
+    this.sleep = sleep || (ms => new Promise(resolve => setTimeout(resolve, ms)));
+    this.sessionToken = null;
+    this.queue = [];
+  }
+
+  /**
+   * The tags every synthetic event carries. The server merges the same set
+   * server side from the verified token, so these are belt and braces rather
+   * than the source of truth.
+   */
+  tags() {
+    return {
+      synthetic: true,
+      persona: this.context.persona,
+      pt_job: this.context.jobId,
+      pt_run: this.context.runId
+    };
+  }
+
+  /**
+   * @returns {Promise<boolean>} false when tracking is switched off for this
+   *   game, in which case nothing is sent
+   */
+  async open() {
+    const settings = await this.fetchImpl(`${this.apiUrl}/api/v1/settings`, {
+      headers: { 'X-API-Key': this.ingestKey }
+    });
+    if (settings.ok) {
+      const body = await settings.json();
+      // The kill switch. A game whose owner switched tracking off does not
+      // get synthetic events pushed into it either.
+      if (body && body.trackingEnabled === false) return false;
+    }
+
+    const response = await this.fetchImpl(`${this.apiUrl}/api/v1/session`, {
+      method: 'POST',
+      headers: {
+        'X-API-Key': this.ingestKey,
+        'X-Ravensight-Playtest': `Bearer ${this.playtestToken}`,
+        'Content-Type': 'application/json'
+      },
+      body: JSON.stringify({ gameVersion: this.context.gameVersion })
+    });
+    if (response.status !== 201) {
+      throw new Error(`synthetic session open failed: ${response.status}`);
+    }
+    const body = await response.json();
+    this.sessionToken = body.token;
+    return true;
+  }
+
+  /**
+   * @param {string} event
+   * @param {Object} [data]
+   */
+  track(event, data = {}) {
+    const merged = { ...data, ...this.tags() };
+    if (Buffer.byteLength(JSON.stringify(merged), 'utf8') > MAX_DATA_BYTES) {
+      throw new Error(`synthetic event ${event} data exceeds ${MAX_DATA_BYTES} bytes`);
+    }
+    this.queue.push({
+      event: String(event).slice(0, 200),
+      data: merged,
+      timestamp: Math.floor(Date.now() / 1000)
+    });
+  }
+
+  /**
+   * @returns {Promise<number>} events the server accepted
+   */
+  async flush() {
+    if (!this.sessionToken) throw new Error('synthetic session is not open');
+    let accepted = 0;
+    let retries = 0;
+    while (this.queue.length > 0) {
+      const batch = this.queue.splice(0, MAX_BATCH);
+      const response = await this.fetchImpl(`${this.apiUrl}/api/v1/track/batch`, {
+        method: 'POST',
+        headers: { 'X-Session-Token': this.sessionToken, 'Content-Type': 'application/json' },
+        body: JSON.stringify({ events: batch })
+      });
+      if (response.status === 429) {
+        this.queue.unshift(...batch);
+        retries += 1;
+        // Three tries and then give up rather than looping forever: the
+        // playtest bucket is 3000 events a minute, so hitting it repeatedly
+        // means something else is wrong.
+        if (retries > 3) return accepted;
+        await this.sleep(BACKOFF_MS);
+        continue;
+      }
+      if (response.status !== 202) throw new Error(`track/batch failed: ${response.status}`);
+      const body = await response.json();
+      accepted += Number(body && body.accepted) || 0;
+    }
+    return accepted;
+  }
+}
+
+/**
+ * Emit the three events a run produces, best effort.
+ *
+ * @param {Object} args
+ * @param {string} args.apiUrl
+ * @param {string|null} args.ingestKey
+ * @param {string|null} args.playtestToken
+ * @param {Object} args.context
+ * @param {Object} args.report the run's report.json
+ * @param {string} args.driver
+ * @param {Function} [args.fetchImpl]
+ * @param {(message: string) => void} [args.log]
+ * @returns {Promise<{sent: boolean, accepted: number, reason?: string}>}
+ */
+export async function emitRunEvents({ apiUrl, ingestKey, playtestToken, context, report, driver, fetchImpl, log }) {
+  if (!ingestKey) {
+    return { sent: false, accepted: 0, reason: 'no ingest key configured, so no synthetic telemetry was sent' };
+  }
+  if (!playtestToken) {
+    return { sent: false, accepted: 0, reason: 'no playtest token for this run, so no synthetic telemetry was sent' };
+  }
+  const session = new SyntheticSession({ apiUrl, ingestKey, playtestToken, context, fetchImpl });
+  try {
+    const opened = await session.open();
+    if (!opened) return { sent: false, accepted: 0, reason: 'tracking is switched off for this game' };
+
+    session.track('playtest_run_started', { driver });
+    for (const finding of Array.isArray(report && report.findings) ? report.findings : []) {
+      session.track('playtest_finding', {
+        finding_id: finding.id,
+        severity: finding.severity,
+        category: finding.category,
+        title: String(finding.title || '').slice(0, 120)
+      });
+    }
+    session.track('playtest_run_ended', {
+      quit_reason: report && report.quit_reason,
+      actions: report && report.actions_taken,
+      usd: report && report.usage && report.usage.total_usd
+    });
+    const accepted = await session.flush();
+    return { sent: true, accepted };
+  } catch (error) {
+    const reason = String(error && error.message ? error.message : error);
+    if (log) log(`synthetic telemetry skipped: ${reason}`);
+    return { sent: false, accepted: 0, reason };
+  }
+}
+
+export default { SyntheticSession, emitRunEvents };