@laphilosophia/api-tape 1.2.1 → 1.4.0

package/README.md

@@ -11,10 +11,12 @@ API Tape is a zero-config CLI tool that acts as a transparent HTTP proxy. It rec
 - **Hybrid Mode** — Replays cached tapes, falls back to upstream on cache miss
 - **Tape Management Commands** — List, inspect, clear, and prune tapes from CLI
 - **Header Redaction** — Mask sensitive response headers before writing tapes
+- **Runtime Metrics** — Periodic and shutdown stats for replay hit/miss, upstream calls, and latency
 - **Zero Config** — Works out of the box with sensible defaults
 - **Binary Safe** — Handles images, compressed responses, and any content type
 - **Replay Header** — Responses include `X-Api-Tape: Replayed` for easy debugging
 - **Versioned Tape Schema** — Each tape includes `schemaVersion` for compatibility checks
+- **Match Strategies** — `exact` and `normalized` matching for better replay hit rates
 
 ## Installation
 
@@ -76,14 +78,34 @@ tape --target "https://jsonplaceholder.typicode.com" --mode hybrid --record-on-m
 
 Both legacy mode (`tape --target ...`) and explicit serve command (`tape serve --target ...`) are supported.
 
-| Option                       | Description                                                    | Default   |
-| ---------------------------- | -------------------------------------------------------------- | --------- |
-| `-t, --target <url>`         | Target API URL **(required)**                                  | —         |
-| `-m, --mode <mode>`          | Operation mode: `record`, `replay`, or `hybrid`                | `replay`  |
-| `-p, --port <number>`        | Local server port                                              | `8080`    |
-| `-d, --dir <path>`           | Directory to save tapes                                        | `./tapes` |
-| `--record-on-miss <boolean>` | In hybrid mode, save upstream response when tape is missing    | `true`    |
-| `--redact-header <headers>`  | Comma-separated response header names to redact in saved tapes | —         |
+| Option                        | Description                                                    | Default   |
+| ----------------------------- | -------------------------------------------------------------- | --------- |
+| `-t, --target <url>`          | Target API URL **(required)**                                  | —         |
+| `-m, --mode <mode>`           | Operation mode: `record`, `replay`, or `hybrid`                | `replay`  |
+| `-p, --port <number>`         | Local server port                                              | `8080`    |
+| `-d, --dir <path>`            | Directory to save tapes                                        | `./tapes` |
+| `--record-on-miss <boolean>`  | In hybrid mode, save upstream response when tape is missing    | `true`    |
+| `--redact-header <headers>`   | Comma-separated response header names to redact in saved tapes | —         |
+| `--match-strategy <strategy>` | Tape matching strategy: `exact` or `normalized`                | `exact`   |
+
+### Runtime stats
+
+```bash
+tape serve --target "https://jsonplaceholder.typicode.com" --mode hybrid --stats-interval 10
+```
+
+For machine-readable output:
+
+```bash
+tape serve --target "https://jsonplaceholder.typicode.com" --stats-interval 10 --stats-json
+```
+
+On shutdown, API Tape always prints a final summary (`FINAL_STATS`).
+
+### Match strategy
+
+- `exact` (default): hashes `METHOD|URL` as-is.
+- `normalized`: sorts query params before hashing, so `/search?a=1&b=2` and `/search?b=2&a=1` map to the same tape.
 
 ### Tape management commands
 
@@ -104,7 +126,8 @@ Each tape is a JSON file named with an MD5 hash of `METHOD|URL`:
   "meta": {
     "url": "/todos/1",
     "method": "GET",
-    "timestamp": "2026-01-14T19:12:39.000Z"
+    "timestamp": "2026-01-14T19:12:39.000Z",
+    "matchStrategy": "normalized"
   },
   "statusCode": 200,
   "headers": { ... },
@@ -121,6 +144,10 @@ npm run build
 npm test
 ```
 
+## CI
+
+A GitHub Actions workflow runs `npm test` on both Linux and Windows for pushes and pull requests.
+
 ## Use Cases
 
 - **Offline Development** — Work without internet or VPN

package/dist/index.js

@@ -55,11 +55,47 @@ var parsePositiveInt = (value, label) => {
   }
   return parsed;
 };
+var parseNonNegativeInt = (value, label) => {
+  const parsed = parseInt(value, 10);
+  if (!Number.isInteger(parsed) || parsed < 0) {
+    throw new Error(`${label} must be a non-negative integer.`);
+  }
+  return parsed;
+};
 var parseCsv = (value) => value.split(",").map((item) => item.trim()).filter(Boolean);
 
 // src/index.ts
-var getTapeKey = (req) => {
-  const key = `${req.method}|${req.url}`;
+var normalizeUrl = (rawUrl) => {
+  if (!rawUrl) {
+    return "/";
+  }
+  const [pathname, query = ""] = rawUrl.split("?");
+  if (!query) {
+    return pathname || "/";
+  }
+  const params = new URLSearchParams(query);
+  const normalizedEntries = Array.from(params.entries()).sort(([aKey, aValue], [bKey, bValue]) => {
+    if (aKey === bKey) {
+      return aValue.localeCompare(bValue);
+    }
+    return aKey.localeCompare(bKey);
+  });
+  const normalized = new URLSearchParams();
+  normalizedEntries.forEach(([key, value]) => {
+    normalized.append(key, value);
+  });
+  const normalizedQuery = normalized.toString();
+  return normalizedQuery ? `${pathname || "/"}?${normalizedQuery}` : pathname || "/";
+};
+var buildRequestSignature = (req, matchStrategy) => {
+  const method = req.method || "GET";
+  if (matchStrategy === "normalized") {
+    return `${method}|${normalizeUrl(req.url)}`;
+  }
+  return `${method}|${req.url}`;
+};
+var getTapeKey = (req, matchStrategy) => {
+  const key = buildRequestSignature(req, matchStrategy);
   return import_crypto.default.createHash("md5").update(key).digest("hex");
 };
 var readTape = (tapePath) => import_fs_extra.default.readJsonSync(tapePath);
@@ -82,12 +118,13 @@ var ensureSchemaCompatibility = (record, tapePath) => {
     throw new Error(`Unsupported tape schema version at ${tapePath}: ${schemaVersion}`);
   }
 };
-var createTapeRecord = (req, proxyRes, bodyBuffer, redactedHeaders) => ({
+var createTapeRecord = (req, proxyRes, bodyBuffer, redactedHeaders, matchStrategy) => ({
   schemaVersion: CURRENT_SCHEMA_VERSION,
   meta: {
     url: req.url,
     method: req.method,
-    timestamp: (/* @__PURE__ */ new Date()).toISOString()
+    timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+    matchStrategy
   },
   statusCode: proxyRes.statusCode || 200,
   headers: redactHeaders(
@@ -96,6 +133,25 @@ var createTapeRecord = (req, proxyRes, bodyBuffer, redactedHeaders) => ({
   ),
   body: bodyBuffer.toString("base64")
 });
+var buildMetricsSnapshot = (metrics) => ({
+  totalRequests: metrics.totalRequests,
+  replayHits: metrics.replayHits,
+  replayMisses: metrics.replayMisses,
+  upstreamRequests: metrics.upstreamRequests,
+  upstreamErrors: metrics.upstreamErrors,
+  completedResponses: metrics.completedResponses,
+  averageLatencyMs: metrics.completedResponses === 0 ? 0 : Number((metrics.totalLatencyMs / metrics.completedResponses).toFixed(2))
+});
+var printMetrics = (metrics, asJson, prefix = "STATS") => {
+  const snapshot = buildMetricsSnapshot(metrics);
+  if (asJson) {
+    console.log(JSON.stringify({ event: prefix, ...snapshot }));
+    return;
+  }
+  console.log(
+    `${timestamp()} ${import_chalk2.default.cyan(prefix)} total=${snapshot.totalRequests} replay_hit=${snapshot.replayHits} replay_miss=${snapshot.replayMisses} upstream=${snapshot.upstreamRequests} upstream_errors=${snapshot.upstreamErrors} avg_latency_ms=${snapshot.averageLatencyMs}`
+  );
+};
 var runServe = (opts) => {
   const targetUrl = opts.target;
   const port = parsePositiveInt(opts.port, "Port");
@@ -103,10 +159,19 @@ var runServe = (opts) => {
   const tapesDir = import_path.default.resolve(opts.dir);
   const recordOnMiss = opts.recordOnMiss;
   const redactedHeaders = parseCsv(opts.redactHeader);
+  const statsIntervalSec = parseNonNegativeInt(opts.statsInterval, "stats-interval");
+  const statsJson = opts.statsJson;
+  const matchStrategy = opts.matchStrategy;
   const validModes = ["record", "replay", "hybrid"];
   if (!validModes.includes(mode)) {
     throw new Error(`Invalid mode: ${mode}. Expected one of: ${validModes.join(", ")}`);
   }
+  const validMatchStrategies = ["exact", "normalized"];
+  if (!validMatchStrategies.includes(matchStrategy)) {
+    throw new Error(
+      `Invalid match strategy: ${matchStrategy}. Expected one of: ${validMatchStrategies.join(", ")}`
+    );
+  }
   import_fs_extra.default.ensureDirSync(tapesDir);
   const proxy = import_http_proxy.default.createProxyServer({
     target: targetUrl,
@@ -114,6 +179,16 @@ var runServe = (opts) => {
     selfHandleResponse: true
   });
   const recordByRequest = /* @__PURE__ */ new WeakMap();
+  const requestStartByResponse = /* @__PURE__ */ new WeakMap();
+  const metrics = {
+    totalRequests: 0,
+    replayHits: 0,
+    replayMisses: 0,
+    upstreamRequests: 0,
+    upstreamErrors: 0,
+    totalLatencyMs: 0,
+    completedResponses: 0
+  };
   const replayTape = (req, res, tapePath) => {
     if (!import_fs_extra.default.existsSync(tapePath)) {
       return false;
@@ -127,6 +202,7 @@ var runServe = (opts) => {
       res.setHeader("X-Api-Tape", "Replayed");
       res.writeHead(tape.statusCode);
       res.end(Buffer.from(tape.body, "base64"));
+      metrics.replayHits += 1;
       console.log(`${timestamp()} ${import_chalk2.default.green("\u21BA REPLAY_HIT")} ${req.method} ${req.url}`);
       return true;
     } catch (error) {
@@ -142,19 +218,31 @@ var runServe = (opts) => {
   };
   const proxyRequest = (req, res, shouldRecord, logPrefix) => {
     recordByRequest.set(req, shouldRecord);
+    metrics.upstreamRequests += 1;
     console.log(`${timestamp()} ${logPrefix} ${req.method} ${req.url}`);
     proxy.web(req, res, {}, (error) => {
+      metrics.upstreamErrors += 1;
       console.error(import_chalk2.default.red("Proxy Error:"), error.message);
       res.statusCode = 502;
       res.end("Proxy Error");
     });
   };
   const server = import_http.default.createServer((req, res) => {
-    const tapeKey = getTapeKey(req);
+    metrics.totalRequests += 1;
+    requestStartByResponse.set(res, Date.now());
+    res.on("finish", () => {
+      const startedAt = requestStartByResponse.get(res);
+      if (typeof startedAt === "number") {
+        metrics.totalLatencyMs += Date.now() - startedAt;
+        metrics.completedResponses += 1;
+      }
+    });
+    const tapeKey = getTapeKey(req, matchStrategy);
     const tapePath = import_path.default.join(tapesDir, `${tapeKey}.json`);
     if (mode === "replay") {
       const hit2 = replayTape(req, res, tapePath);
       if (!hit2) {
+        metrics.replayMisses += 1;
         console.log(`${timestamp()} ${import_chalk2.default.red("\u2718 REPLAY_MISS")} ${req.method} ${req.url}`);
         res.statusCode = 404;
         res.end(`Tape not found for: ${req.method} ${req.url}`);
@@ -169,6 +257,7 @@ var runServe = (opts) => {
     if (hit) {
       return;
     }
+    metrics.replayMisses += 1;
     console.log(`${timestamp()} ${import_chalk2.default.yellow("\u21E2 REPLAY_MISS")} ${req.method} ${req.url}`);
     proxyRequest(
       req,
@@ -184,8 +273,8 @@ var runServe = (opts) => {
       const bodyBuffer = Buffer.concat(bodyChunks);
       const shouldRecord = recordByRequest.get(req) ?? true;
       if (shouldRecord) {
-        const tapeData = createTapeRecord(req, proxyRes, bodyBuffer, redactedHeaders);
-        const tapeKey = getTapeKey(req);
+        const tapeData = createTapeRecord(req, proxyRes, bodyBuffer, redactedHeaders, matchStrategy);
+        const tapeKey = getTapeKey(req, matchStrategy);
         const tapePath = import_path.default.join(tapesDir, `${tapeKey}.json`);
         import_fs_extra.default.writeJsonSync(tapePath, tapeData, { spaces: 2 });
         console.log(`${timestamp()} ${import_chalk2.default.cyan("\u{1F4BE} SAVED")} ${req.method} ${req.url}`);
@@ -197,6 +286,27 @@ var runServe = (opts) => {
       res.end(bodyBuffer);
     });
   });
+  let metricsTimer;
+  if (statsIntervalSec > 0) {
+    metricsTimer = setInterval(() => {
+      printMetrics(metrics, statsJson);
+    }, statsIntervalSec * 1e3);
+  }
+  const shutdown = (signal) => {
+    if (metricsTimer) {
+      clearInterval(metricsTimer);
+      metricsTimer = void 0;
+    }
+    printMetrics(metrics, statsJson, "FINAL_STATS");
+    server.close(() => {
+      process.exit(0);
+    });
+    setTimeout(() => {
+      process.exit(0);
+    }, 2e3).unref();
+  };
+  process.once("SIGINT", () => shutdown("SIGINT"));
+  process.once("SIGTERM", () => shutdown("SIGTERM"));
   console.log(import_chalk2.default.bold(`
 \u{1F4FC} API Tape Running`));
   console.log(
@@ -211,6 +321,13 @@ var runServe = (opts) => {
   if (redactedHeaders.length > 0) {
     console.log(`   ${import_chalk2.default.dim("Redact Headers:")} ${redactedHeaders.join(", ")}`);
   }
+  if (statsIntervalSec > 0) {
+    console.log(`   ${import_chalk2.default.dim("Stats Every:")} ${statsIntervalSec}s`);
+  }
+  if (statsJson) {
+    console.log(`   ${import_chalk2.default.dim("Stats Format:")} json`);
+  }
+  console.log(`   ${import_chalk2.default.dim("Match Strategy:")} ${matchStrategy}`);
   console.log("");
   server.listen(port);
 };
@@ -288,19 +405,19 @@ var addServeOptions = (command) => command.requiredOption("-t, --target <url>",
   "--redact-header <headers>",
   "Comma-separated response header names to redact before saving",
   ""
-);
+).option("--stats-interval <seconds>", "Emit runtime stats every N seconds (0 disables)", "0").option("--stats-json", "Emit stats in JSON format", false).option("--match-strategy <strategy>", "Tape matching strategy: exact or normalized", "exact");
 var run = () => {
   const argv = process.argv;
   const hasSubCommand = argv.length > 2 && ["serve", "tape"].includes(argv[2]);
   if (!hasSubCommand) {
-    const legacy = addServeOptions(new import_commander.Command()).name("api-tape").description("Record and Replay HTTP API responses for offline development.").version("1.2.0").action((options) => {
+    const legacy = addServeOptions(new import_commander.Command()).name("api-tape").description("Record and Replay HTTP API responses for offline development.").version("1.3.0").action((options) => {
       runServe(options);
     });
     legacy.parse(argv);
     return;
   }
   const program = new import_commander.Command();
-  program.name("api-tape").description("Record and Replay HTTP API responses for offline development.").version("1.2.0");
+  program.name("api-tape").description("Record and Replay HTTP API responses for offline development.").version("1.3.0");
   addServeOptions(program.command("serve").description("Run API Tape proxy server")).action(
     (options) => {
       runServe(options);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@laphilosophia/api-tape",
-  "version": "1.2.1",
+  "version": "1.4.0",
   "description": "Record and Replay HTTP API responses for offline development",
   "main": "dist/index.js",
   "bin": {