ravensight-playtest 0.5.1 → 0.6.0

package/src/api/errors.js

@@ -65,9 +65,25 @@ const RETRYABLE_STATUSES = new Set([408, 425, 429, 500, 502, 503, 504]);
  * answer (a replay, or a charge) within a few seconds. Only retried when it
  * actually carries a `Retry-After`: without one there is no interval the
  * server has blessed, and guessing at a money path is not this layer's call.
+ *
+ * `settle_contended` is a 409 from the same family, and one that says outright
+ * that the job changed underneath the settle and nothing moved. So it is the one
+ * code safe to repeat on a POST that carries no idempotency key: see
+ * `nothingMoved`. The sweep settles the job if every try is contended.
  */
 const NEVER_RETRY_CODES = new Set(['too_many_active_jobs']);
-const CODE_RETRY_LIMITS = new Map([['charge_in_progress', 5]]);
+const CODE_RETRY_LIMITS = new Map([['charge_in_progress', 5], ['settle_contended', 4]]);
+const NOTHING_MOVED_CODES = new Set(['settle_contended']);
+
+/**
+ * Whether this refusal promises that repeating the request cannot move money
+ * twice, whatever the method.
+ * @param {unknown} error
+ * @returns {boolean}
+ */
+export function nothingMoved(error) {
+  return error instanceof ApiError && NOTHING_MOVED_CODES.has(error.code);
+}
 
 /**
  * How many retries this error's own code is allowed, independent of the

package/src/api/http.js

@@ -1,4 +1,4 @@
-import { ApiError, codeRetryLimit, isRetryable, parseRetryAfter } from './errors.js';
+import { ApiError, codeRetryLimit, isRetryable, nothingMoved, parseRetryAfter } from './errors.js';
 
 export const DEFAULT_RETRIES = 4;
 export const DEFAULT_TIMEOUT_MS = 30000;
@@ -42,19 +42,43 @@ export function buildUrl(apiUrl, path, query) {
   return url.toString();
 }
 
+/** Carries a capture hook's own error past the request loop's network catch. */
+class CaptureFailure {
+  constructor(error) { this.error = error; }
+}
+
 /**
- * Read a response body without ever throwing. A 502 from a load balancer is
+ * Read a response body without throwing for body or JSON decoding errors. A 502 from a load balancer is
  * HTML, a 204 is empty, and a JSON parse failure on the error path would
- * replace a useful status code with a useless SyntaxError.
+ * replace a useful status code with a useless SyntaxError. `cut` says the connection
+ * went before the body finished, which is not the same as an empty body.
  * @param {Response} response
- * @returns {Promise<{json: unknown, text: string}>}
+ * @returns {Promise<{json: unknown, text: string, cut?: Error}>}
  */
-async function readBody(response) {
+async function readBody(response, onResponseRaw) {
   let text = '';
-  try {
-    text = await response.text();
-  } catch {
-    return { json: null, text: '' };
+  if (onResponseRaw) {
+    let bytes = Buffer.alloc(0), bodyComplete = false;
+    try { bytes = Buffer.from(await response.arrayBuffer()); bodyComplete = true; }
+    catch { /* Preserve a read-failure observation, never invent complete bytes. */ }
+    // Opt-in capture runs on every HTTP status BEFORE JSON parsing or an
+    // ApiError. Capture failures propagate and cannot trigger a request retry.
+    try {
+      await onResponseRaw({ status: response.status, contentType: response.headers.get('content-type'), bytes, bodyComplete });
+    } catch (error) {
+      throw new CaptureFailure(error);
+    }
+    // A capture caller owns an incomplete body: the observation says so, and it
+    // must decide from that record (an admission never POSTs again on an unknown
+    // outcome), so this is not turned into a retryable network error.
+    if (!bodyComplete) return { json: null, text: '' };
+    text = new TextDecoder().decode(bytes);
+  } else {
+    try {
+      text = await response.text();
+    } catch (cause) {
+      return { json: null, text: '', cut: cause };
+    }
   }
   if (!text) return { json: null, text: '' };
   try {
@@ -87,7 +111,8 @@ function errorFrom(response, parsed, { method, path }) {
  * Retries cover a network failure, a timeout, 408, 425, 429 and 5xx, plus the
  * two error codes whose status alone gives the wrong answer (see
  * `codeRetryLimit`): `charge_in_progress` is retried on its own `Retry-After`
- * although it is a 409, and `too_many_active_jobs` is not retried although it
+ * although it is a 409, `settle_contended` likewise and on any method because it
+ * promises nothing moved, and `too_many_active_jobs` is not retried although it
  * is a 429. A mutation is only ever retried when the caller says
  * `idempotent: true`, which in practice means a GET, a heartbeat, or a POST
  * carrying an `Idempotency-Key` the server uses to replay rather than repeat.
@@ -102,6 +127,7 @@ function errorFrom(response, parsed, { method, path }) {
  * @param {string} [options.bodyText]
  * @param {boolean} [options.idempotent]
  * @param {boolean} [options.raw] - resolve the body as text, not JSON
+ * @param {Function} [options.onResponseRaw] - await exact response-byte capture before parsing, including non-2xx
  * @param {number} [options.retries]
  * @param {number} [options.timeoutMs]
  * @param {typeof fetch} [options.fetchImpl]
@@ -119,6 +145,7 @@ export async function requestWithRetry(options) {
     bodyText,
     idempotent = false,
     raw = false,
+    onResponseRaw,
     retries = DEFAULT_RETRIES,
     timeoutMs = DEFAULT_TIMEOUT_MS,
     fetchImpl = globalThis.fetch,
@@ -140,7 +167,16 @@ export async function requestWithRetry(options) {
   for (let attempt = 1; ; attempt += 1) {
     const controller = new AbortController();
     const timer = setTimeout(() => controller.abort(), timeoutMs);
+    const unreachable = cause => new ApiError({
+      status: 0,
+      code: 'network_error',
+      message: `${method} ${path} could not reach ${new URL(url).host}: ${cause.message}`,
+      method,
+      path,
+      cause
+    });
     let response = null;
+    let parsed = null;
     try {
       response = await fetchImpl(url, {
         method,
@@ -148,21 +184,21 @@ export async function requestWithRetry(options) {
         body: bodyText === undefined ? undefined : bodyText,
         signal: controller.signal
       });
+      // The time limit covers the body too, and a success whose body never finished
+      // is no answer: reading it as an empty 200 lost the job id of a job just charged.
+      parsed = await readBody(response, onResponseRaw);
+      if (parsed.cut) {
+        lastError = unreachable(parsed.cut);
+        response = null;
+      }
     } catch (cause) {
-      lastError = new ApiError({
-        status: 0,
-        code: 'network_error',
-        message: `${method} ${path} could not reach ${new URL(url).host}: ${cause.message}`,
-        method,
-        path,
-        cause
-      });
+      if (cause instanceof CaptureFailure) throw cause.error;
+      lastError = unreachable(cause);
     } finally {
       clearTimeout(timer);
     }
 
     if (response) {
-      const parsed = await readBody(response);
       if (response.ok || response.status === 304) {
         return {
           status: response.status,
@@ -173,7 +209,7 @@ export async function requestWithRetry(options) {
       lastError = errorFrom(response, parsed, { method, path });
     }
 
-    if (!retryable) throw lastError;
+    if (!retryable && !nothingMoved(lastError)) throw lastError;
 
     const limit = codeRetryLimit(lastError);
     let canRetry;

package/src/assets/formats.js

@@ -0,0 +1,267 @@
+import { inflateSync } from 'node:zlib';
+
+/**
+ * Plain parsers for the three formats the inventory measures closely: PNG, WAV
+ * and Ogg. No dependency, because this runs inside a CLI that ships with few, and
+ * none of these needs more than a header and, for PNG, one inflate.
+ *
+ * Each parser answers what it read and `problem` when the file is damaged, and
+ * never throws on hostile bytes: a studio's folder can hold anything.
+ */
+
+const PNG_SIGNATURE = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+
+/** Above this the pixels are not decoded: the header still answers the size. */
+export const MAX_DECODED_PIXELS = 64 * 1024 * 1024;
+
+const CHANNELS = { 0: 1, 2: 3, 3: 1, 4: 2, 6: 4 };
+const VALID_DEPTHS = { 0: [1, 2, 4, 8, 16], 2: [8, 16], 3: [1, 2, 4, 8], 4: [8, 16], 6: [8, 16] };
+
+/**
+ * The PNG's chunks up to IEND, without decoding the pixels.
+ *
+ * @param {Buffer} data
+ * @returns {{width: number, height: number, bitDepth: number, colorType: number, interlaced: boolean, palette: Buffer|null, transparency: Buffer|null, idat: Buffer[], problem: string|null}|null} null when it is not a PNG at all
+ */
+export function readPngHeader(data) {
+  if (data.length < 33 || !data.subarray(0, 8).equals(PNG_SIGNATURE)) return null;
+  const out = { width: 0, height: 0, bitDepth: 0, colorType: 0, interlaced: false, palette: null, transparency: null, idat: [], problem: null };
+  let at = 8;
+  let sawHeader = false;
+  let sawEnd = false;
+  while (at + 8 <= data.length) {
+    const length = data.readUInt32BE(at);
+    const type = data.toString('latin1', at + 4, at + 8);
+    const start = at + 8;
+    if (start + length > data.length) {
+      out.problem = `the ${type} chunk runs past the end of the file`;
+      break;
+    }
+    const body = data.subarray(start, start + length);
+    if (type === 'IHDR') {
+      if (length < 13) return { ...out, problem: 'the image header is too short' };
+      out.width = body.readUInt32BE(0);
+      out.height = body.readUInt32BE(4);
+      out.bitDepth = body[8];
+      out.colorType = body[9];
+      out.interlaced = body[12] === 1;
+      sawHeader = true;
+    } else if (type === 'PLTE') out.palette = body;
+    else if (type === 'tRNS') out.transparency = body;
+    else if (type === 'IDAT') out.idat.push(body);
+    else if (type === 'IEND') { sawEnd = true; break; }
+    at = start + length + 4;
+  }
+  if (!sawHeader) return { ...out, problem: out.problem || 'there is no image header' };
+  if (!(VALID_DEPTHS[out.colorType] || []).includes(out.bitDepth)) return { ...out, problem: 'the colour type and bit depth are not valid together' };
+  if (!sawEnd && !out.problem) out.problem = 'the file ends before the image does';
+  return out;
+}
+
+/** The Paeth predictor, from the PNG specification. */
+function paeth(a, b, c) {
+  const p = a + b - c;
+  const pa = Math.abs(p - a);
+  const pb = Math.abs(p - b);
+  const pc = Math.abs(p - c);
+  if (pa <= pb && pa <= pc) return a;
+  return pb <= pc ? b : c;
+}
+
+/**
+ * Decode a non-interlaced PNG to 8-bit RGBA.
+ *
+ * @param {ReturnType<typeof readPngHeader>} header
+ * @returns {{width: number, height: number, rgba: Uint8Array}|{problem: string}|null} null for what is
+ *   not decoded on purpose: interlaced, or over MAX_DECODED_PIXELS
+ */
+export function decodePng(header) {
+  const { width, height, bitDepth, colorType } = header;
+  if (header.interlaced || width * height > MAX_DECODED_PIXELS || width * height === 0) return null;
+  const channels = CHANNELS[colorType];
+  const stride = Math.ceil((width * channels * bitDepth) / 8);
+  const bytesPerPixel = Math.max(1, (channels * bitDepth) >> 3);
+  const expected = (stride + 1) * height;
+  let raw;
+  try {
+    raw = inflateSync(Buffer.concat(header.idat), { maxOutputLength: expected + 1024 });
+  } catch {
+    return { problem: 'the pixel data does not decompress' };
+  }
+  if (raw.length < expected) return { problem: 'the pixel data is shorter than the image' };
+
+  const line = new Uint8Array(stride);
+  const previous = new Uint8Array(stride);
+  const rgba = new Uint8Array(width * height * 4);
+  const palette = header.palette;
+  const alphas = header.transparency;
+  const keyed = colorType !== 3 && alphas && alphas.length >= (colorType === 0 ? 2 : 6) ? alphas : null;
+  for (let y = 0; y < height; y += 1) {
+    const offset = y * (stride + 1);
+    const filter = raw[offset];
+    if (filter > 4) return { problem: 'a row of pixels has an unknown filter' };
+    for (let x = 0; x < stride; x += 1) {
+      const value = raw[offset + 1 + x];
+      const a = x >= bytesPerPixel ? line[x - bytesPerPixel] : 0;
+      const b = previous[x];
+      const c = x >= bytesPerPixel ? previous[x - bytesPerPixel] : 0;
+      let out = value;
+      if (filter === 1) out = value + a;
+      else if (filter === 2) out = value + b;
+      else if (filter === 3) out = value + ((a + b) >> 1);
+      else if (filter === 4) out = value + paeth(a, b, c);
+      line[x] = out & 0xff;
+    }
+    for (let x = 0; x < width; x += 1) {
+      const to = (y * width + x) * 4;
+      if (colorType === 3 || (colorType === 0 && bitDepth < 8)) {
+        const bitAt = x * bitDepth;
+        const sample = (line[bitAt >> 3] >> (8 - bitDepth - (bitAt & 7))) & ((1 << bitDepth) - 1);
+        if (colorType === 3) {
+          rgba[to] = palette ? palette[sample * 3] : 0;
+          rgba[to + 1] = palette ? palette[sample * 3 + 1] : 0;
+          rgba[to + 2] = palette ? palette[sample * 3 + 2] : 0;
+          rgba[to + 3] = alphas && sample < alphas.length ? alphas[sample] : 255;
+        } else {
+          const grey = Math.round((sample * 255) / ((1 << bitDepth) - 1));
+          rgba[to] = grey; rgba[to + 1] = grey; rgba[to + 2] = grey;
+          rgba[to + 3] = keyed && keyed.readUInt16BE(0) === sample ? 0 : 255;
+        }
+        continue;
+      }
+      // At 16 bits the high byte of each sample is what a screen shows.
+      const step = bitDepth === 16 ? 2 : 1;
+      const from = x * channels * step;
+      if (colorType === 0 || colorType === 4) {
+        const grey = line[from];
+        rgba[to] = grey; rgba[to + 1] = grey; rgba[to + 2] = grey;
+        rgba[to + 3] = colorType === 4 ? line[from + step]
+          : (keyed && (bitDepth === 16 ? (line[from] << 8) | line[from + 1] : line[from]) === keyed.readUInt16BE(0) ? 0 : 255);
+      } else {
+        rgba[to] = line[from];
+        rgba[to + 1] = line[from + step];
+        rgba[to + 2] = line[from + step * 2];
+        if (colorType === 6) rgba[to + 3] = line[from + step * 3];
+        else {
+          const sample = i => (bitDepth === 16 ? (line[from + i * 2] << 8) | line[from + i * 2 + 1] : line[from + i]);
+          rgba[to + 3] = keyed && sample(0) === keyed.readUInt16BE(0) && sample(1) === keyed.readUInt16BE(2) && sample(2) === keyed.readUInt16BE(4) ? 0 : 255;
+        }
+      }
+    }
+    previous.set(line);
+  }
+  return { width, height, rgba };
+}
+
+/** Whether a PNG can carry transparency at all, from its header. */
+export function pngHasAlphaChannel(header) {
+  return header.colorType === 4 || header.colorType === 6 || Boolean(header.transparency);
+}
+
+const WAV_FORMATS = { 1: 'pcm', 3: 'float', 6: 'a-law', 7: 'mu-law' };
+
+/**
+ * A WAV's format and length, from its `fmt ` and `data` chunks.
+ *
+ * @param {Buffer} data
+ * @returns {{codec: string, extensible: boolean, channels: number, sampleRate: number, bitsPerSample: number, durationSeconds: number|null, problem: string|null}|null} null when it is not a WAV
+ */
+export function parseWav(data) {
+  if (data.length < 12 || data.toString('latin1', 0, 4) !== 'RIFF' || data.toString('latin1', 8, 12) !== 'WAVE') return null;
+  let at = 12;
+  let format = null;
+  let dataBytes = null;
+  let problem = null;
+  while (at + 8 <= data.length) {
+    const id = data.toString('latin1', at, at + 4);
+    const length = data.readUInt32LE(at + 4);
+    const start = at + 8;
+    if (id === 'fmt ' && start + 16 <= data.length) {
+      const tag = data.readUInt16LE(start);
+      // An extensible header names the real format in the first bytes of its subformat.
+      const extended = tag === 0xfffe && start + 26 <= data.length ? data.readUInt16LE(start + 24) : null;
+      format = {
+        tag: extended ?? tag,
+        extensible: tag === 0xfffe,
+        channels: data.readUInt16LE(start + 2),
+        sampleRate: data.readUInt32LE(start + 4),
+        byteRate: data.readUInt32LE(start + 8),
+        bitsPerSample: data.readUInt16LE(start + 14)
+      };
+    } else if (id === 'data') {
+      dataBytes = length;
+      if (start + length > data.length) {
+        dataBytes = data.length - start;
+        problem = 'the sound data runs past the end of the file';
+      }
+      break;
+    }
+    at = start + length + (length & 1);
+  }
+  if (!format) return { codec: 'unknown', extensible: false, channels: 0, sampleRate: 0, bitsPerSample: 0, durationSeconds: null, problem: 'there is no format chunk' };
+  if (dataBytes === null) problem = problem || 'there is no sound data';
+  return {
+    codec: WAV_FORMATS[format.tag] || `format ${format.tag}`,
+    extensible: format.extensible,
+    channels: format.channels,
+    sampleRate: format.sampleRate,
+    bitsPerSample: format.bitsPerSample,
+    durationSeconds: dataBytes !== null && format.byteRate > 0 ? dataBytes / format.byteRate : null,
+    problem
+  };
+}
+
+/** One Ogg page: its header fields and where its body sits. */
+function oggPageAt(data, at) {
+  if (at + 27 > data.length || data.toString('latin1', at, at + 4) !== 'OggS') return null;
+  const segments = data[at + 26];
+  if (at + 27 + segments > data.length) return null;
+  let size = 0;
+  for (let i = 0; i < segments; i += 1) size += data[at + 27 + i];
+  return { granule: data.readBigInt64LE(at + 6), serial: data.readUInt32LE(at + 14), bodyStart: at + 27 + segments, next: at + 27 + segments + size };
+}
+
+/**
+ * An Ogg's codec and length: the first page names the codec, and the last page's
+ * granule position is how far the stream got. Vorbis counts samples; Opus counts
+ * at 48 kHz, less its pre-skip.
+ *
+ * @param {Buffer} data
+ * @returns {{codec: string, channels: number, sampleRate: number, bitsPerSample: null, durationSeconds: number|null, problem: string|null}|null} null when it is not an Ogg
+ */
+export function parseOgg(data) {
+  const first = oggPageAt(data, 0);
+  if (!first) return null;
+  const body = data.subarray(first.bodyStart, first.next);
+  const out = { codec: 'unknown', channels: 0, sampleRate: 0, bitsPerSample: null, durationSeconds: null, problem: null };
+  let ticksPerSecond = 0;
+  let skip = 0;
+  if (body.length >= 30 && body[0] === 1 && body.toString('latin1', 1, 7) === 'vorbis') {
+    out.codec = 'vorbis';
+    out.channels = body[11];
+    out.sampleRate = body.readUInt32LE(12);
+    ticksPerSecond = out.sampleRate;
+  } else if (body.length >= 19 && body.toString('latin1', 0, 8) === 'OpusHead') {
+    out.codec = 'opus';
+    out.channels = body[9];
+    out.sampleRate = body.readUInt32LE(12);
+    ticksPerSecond = 48000;
+    skip = body.readUInt16LE(10);
+  } else {
+    out.problem = 'the first page does not name a codec this reads';
+    return out;
+  }
+  let at = 0;
+  let lastGranule = -1n;
+  for (;;) {
+    const page = oggPageAt(data, at);
+    if (!page || page.next > data.length) break;
+    if (page.serial === first.serial && page.granule >= 0n) lastGranule = page.granule;
+    at = page.next;
+  }
+  if (at < data.length) out.problem = 'the file ends part way through a page';
+  if (lastGranule >= 0n && ticksPerSecond > 0) out.durationSeconds = Math.max(0, Number(lastGranule) - skip) / ticksPerSecond;
+  return out;
+}
+
+export default { readPngHeader, decodePng, pngHasAlphaChannel, parseWav, parseOgg, MAX_DECODED_PIXELS };