@laphilosophia/api-tape 1.2.0 → 1.3.0

package/README.md

@@ -1,22 +1,23 @@
-# 📼 API Tape
+# API Tape
 
 **Record and Replay HTTP API responses for offline development.**
 
 API Tape is a zero-config CLI tool that acts as a transparent HTTP proxy. It records API responses to local JSON files ("tapes") and replays them instantly—perfect for offline development, flaky API testing, and reproducible demos.
 
-## ✨ Features
+## Features
 
-- 🎬 **Record Mode** — Proxies requests to your target API and saves responses
-- 🔄 **Replay Mode** — Serves cached responses instantly from disk
-- 🔀 **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
-- 📦 **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
+- **Record Mode** — Proxies requests to your target API and saves responses
+- **Replay Mode** — Serves cached responses instantly from disk
+- **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
 
-## 📦 Installation
+## Installation
 
 ```bash
 npm install -g api-tape
@@ -28,7 +29,7 @@ Or use it directly with npx:
 npx api-tape --target "https://api.example.com" --mode record
 ```
 
-## 🚀 Quick Start
+## Quick Start
 
 ### Step 1: Record API Responses
 
@@ -70,7 +71,7 @@ tape --target "https://jsonplaceholder.typicode.com" --mode hybrid --record-on-m
 - If tape is missing → upstream request is proxied.
 - With `--record-on-miss true`, miss responses are automatically saved as new tapes.
 
-## ⚙️ CLI Options
+## CLI Options
 
 ### Serve command
 
@@ -85,6 +86,20 @@ Both legacy mode (`tape --target ...`) and explicit serve command (`tape serve -
 | `--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 | —         |
 
+### 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`).
+
 ### Tape management commands
 
 ```bash
@@ -94,7 +109,7 @@ tape tape clear --yes --dir ./tapes
 tape tape prune --older-than 30 --dir ./tapes
 ```
 
-## 📁 Tape Format
+## Tape Format
 
 Each tape is a JSON file named with an MD5 hash of `METHOD|URL`:
 
@@ -114,20 +129,20 @@ Each tape is a JSON file named with an MD5 hash of `METHOD|URL`:
 
 The body is base64-encoded for binary safety.
 
-## 🧪 Development
+## Development
 
 ```bash
 npm run build
 npm test
 ```
 
-## 🎯 Use Cases
+## Use Cases
 
 - **Offline Development** — Work without internet or VPN
 - **Flaky API Testing** — Eliminate network inconsistencies in tests
 - **Demo Environments** — Reproducible API responses for presentations
 - **Rate Limit Bypass** — Develop against recorded responses
 
-## 📄 License
+## License
 
 MIT © [Erdem Arslan](https://github.com/laphilosophia)

package/dist/index.js

@@ -55,6 +55,13 @@ 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
@@ -96,6 +103,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,6 +129,8 @@ 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 validModes = ["record", "replay", "hybrid"];
   if (!validModes.includes(mode)) {
     throw new Error(`Invalid mode: ${mode}. Expected one of: ${validModes.join(", ")}`);
@@ -114,6 +142,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 +165,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 +181,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) => {
+    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);
     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 +220,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,
@@ -197,6 +249,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 +284,12 @@ 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("");
   server.listen(port);
 };
@@ -288,19 +367,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);
 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.0",
+  "version": "1.3.0",
   "description": "Record and Replay HTTP API responses for offline development",
   "main": "dist/index.js",
   "bin": {