@aplaytest/store-azure 0.1.0

package/dist/layout.js

@@ -0,0 +1,115 @@
+/**
+ * The blob naming scheme — the whole concurrency story, encoded in a path.
+ *
+ * The store this replaces was one SQLite file on a blob: download it, ingest,
+ * upload it back under an ETag precondition. That works exactly until two runs
+ * overlap, at which point the loser either fails the step or discards the
+ * winner's attempts, and it re-uploads the entire history to record thirty
+ * seconds of it.
+ *
+ * Here a run record is an object and the container is an append-only log:
+ *
+ *   <prefix>v1/runs/2026/08/30/<runId>/<shard>.json.gz
+ *
+ * Three properties follow directly from the name, with no locking:
+ *
+ *   · IDEMPOTENT. A re-ingested shard computes the same name and overwrites
+ *     itself. The scoped-delete and UPSERT gymnastics the SQL driver needs to
+ *     avoid double-counting are a naming rule here.
+ *   · CONCURRENT. Two shards of one run, and two overlapping main-branch runs,
+ *     write different names. Nothing races, so nothing needs a precondition.
+ *   · CHEAP TO WINDOW. The date is in the path, so a 90-day read filters the
+ *     LISTING and downloads only what it will score, and the run id is in the
+ *     path, so counting runs needs no downloads at all.
+ *
+ * All pure string work: no client, no credential, no network.
+ */
+/** Bumped only for a change no existing reader can parse. Old prefixes stay readable. */
+export const LAYOUT_VERSION = 'v1';
+const RUNS_ROOT = `${LAYOUT_VERSION}/runs`;
+const SUFFIX = '.json.gz';
+/**
+ * Run ids come from `ATEST_RUN_ID`, which in CI is whatever the pipeline puts
+ * there — `github.run_id`, a pipeline id, a branch name. A `/` in one would
+ * silently add a directory level and break parsing; a space or a `#` would
+ * survive one SDK and not the next. Encode to a conservative alphabet and keep
+ * it reversible, so the run id can still be read back out of a listing.
+ */
+const SAFE = /^[A-Za-z0-9._-]$/;
+export function encodeSegment(value) {
+    let out = '';
+    for (const char of value) {
+        if (SAFE.test(char)) {
+            out += char;
+            continue;
+        }
+        for (const byte of new TextEncoder().encode(char)) {
+            out += `~${byte.toString(16).padStart(2, '0')}`;
+        }
+    }
+    return out;
+}
+export function decodeSegment(value) {
+    const bytes = [];
+    for (let i = 0; i < value.length; i += 1) {
+        if (value[i] === '~' && i + 2 < value.length) {
+            bytes.push(Number.parseInt(value.slice(i + 1, i + 3), 16));
+            i += 2;
+            continue;
+        }
+        bytes.push(...new TextEncoder().encode(value[i] ?? ''));
+    }
+    return new TextDecoder().decode(Uint8Array.from(bytes));
+}
+export class LayoutError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'LayoutError';
+    }
+}
+const ISO_DATE = /^(\d{4})-(\d{2})-(\d{2})/;
+/**
+ * The date partition a run belongs to, taken from `startedAt`.
+ *
+ * Thrown rather than defaulted. A record whose timestamp cannot be read has no
+ * place in a time-windowed store: filed under today it would look current
+ * forever and never prune, and filed under the epoch it would vanish from
+ * every window. `ingestDirectory` catches this and reports the file as
+ * skipped, which is the visible failure the silent ones are worth trading for.
+ */
+export function partitionOf(startedAt) {
+    const match = ISO_DATE.exec(startedAt ?? '');
+    if (match === null) {
+        throw new LayoutError(`startedAt "${String(startedAt)}" is not an ISO 8601 timestamp, so the run has no date partition.`);
+    }
+    return `${match[1]}/${match[2]}/${match[3]}`;
+}
+export function runBlobName(prefix, startedAt, runId, shardKey) {
+    return `${prefix}${RUNS_ROOT}/${partitionOf(startedAt)}/${encodeSegment(runId)}/${encodeSegment(shardKey)}${SUFFIX}`;
+}
+/** Everything a listing needs to answer, so the common queries need no downloads. */
+export function parseRunBlobName(prefix, name) {
+    if (!name.startsWith(`${prefix}${RUNS_ROOT}/`) || !name.endsWith(SUFFIX))
+        return null;
+    const rest = name.slice(`${prefix}${RUNS_ROOT}/`.length, -SUFFIX.length);
+    const parts = rest.split('/');
+    // YYYY / MM / DD / runId / shardKey. Anything else is not ours — a stray
+    // upload or a future layout, and either way not something to guess at.
+    if (parts.length !== 5)
+        return null;
+    const [year, month, day, runId, shardKey] = parts;
+    if (year === undefined || month === undefined || day === undefined)
+        return null;
+    if (runId === undefined || shardKey === undefined)
+        return null;
+    return {
+        runId: decodeSegment(runId),
+        shardKey: decodeSegment(shardKey),
+        date: `${year}-${month}-${day}`,
+    };
+}
+/** Prefix every run blob shares, so a listing can skip anything else in the container. */
+export function runsPrefix(prefix) {
+    return `${prefix}${RUNS_ROOT}/`;
+}
+//# sourceMappingURL=layout.js.map

package/dist/layout.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"layout.js","sourceRoot":"","sources":["../src/layout.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@aplaytest/store-azure",
+  "version": "0.1.0",
+  "description": "Azure Blob Storage history store for atest \u2014 an append-only log of run records, so flake statistics outlive the run that produced them",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc --build",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@aplaytest/core": "^0.1.0",
+    "@azure/core-auth": "^1.11.0",
+    "@azure/identity": "^4.13.0",
+    "@azure/storage-blob": "^12.30.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ianoflynnautomation/aplaytest.git",
+    "directory": "packages/store-azure"
+  },
+  "homepage": "https://github.com/ianoflynnautomation/aplaytest#readme",
+  "bugs": {
+    "url": "https://github.com/ianoflynnautomation/aplaytest/issues"
+  }
+}