fix: cap in-memory journal to prevent heap OOM under sustained load (#114)

## Summary
`Journal.entries` was unbounded — every request across 26 handlers (~179
call sites: chat completions, messages, responses, gemini, bedrock,
embeddings, images, speech, transcription, video, ollama, cohere,
search, rerank, moderation, a2a, mcp, agui, ws-*, etc.) pushed a full `{
method, path, headers, body, response }` record and never evicted. At
sustained prod traffic this grows heap ~3.8MB/sec → 4GB → OOM in ~18
minutes. Observed exactly that on `showcase-aimock` Railway service:
deterministic 0→4GB heap growth then `FATAL ERROR: Reached heap limit
Allocation failed`. Crash cascades to ~7 downstream showcase services
that route through aimock via `OPENAI_BASE_URL`.

## Fix
FIFO size cap on `Journal.entries` via new `JournalOptions.maxEntries`.
Default:
- Programmatic (`new Journal()` / `createServer()`): **unbounded**
(backwards-compat; 100+ test/library callers depend on this).
- CLI: **1000** (default for `serve` / the GHCR image). Override via
`--journal-max <N>`; `0` or omitted = unbounded.

Eviction is a single `shift()` per over-cap add. At cap=1000 ×
~5KB/entry ≈ 5MB steady-state — well under heap limits.

## Test plan
- [x] 6 new red-green tests in `src/__tests__/journal.test.ts` (cap
behavior, FIFO ordering, uncapped default, `getLast`/`findByFixture`
post-eviction, 100k-add cap invariant)
- [x] Full suite: 2449 tests pass
- [x] Lint + build + prettier clean
- [ ] Post-merge: GHCR image republishes with the fix; Railway picks up
on next drift-rebuild or manual redeploy

## Follow-ups (separate PR)
- CLI: reject negative `--journal-max` values (currently silently
treated as unbounded)
- `createServer()` default: flip to finite cap so long-running embedders
don't inherit the leak
- `fixtureMatchCountsByTestId` Map cap (narrower but also unbounded)
- Correct the "amortized O(1)" comment — `Array.shift` is O(n); true
O(1) would need a ring buffer

Author: jpr5

CHANGELOG.md

@@ -1,5 +1,11 @@
 # @copilotkit/aimock
 
+## 1.14.1
+
+### Patch Changes
+
+- Cap in-memory journal (and fixture-match-counts map) to prevent heap OOM under sustained load. `Journal.entries` was unbounded, causing heap growth ~3.8MB/sec to 4GB → OOM in ~18 minutes on production Railway deployments. Default cap for CLI (`serve`) is now 1000 entries; programmatic `createServer()` remains unbounded by default (back-compat). See `--journal-max` flag.
+
 ## 1.14.0
 
 ### Minor Changes

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "@copilotkit/aimock",
-  "version": "1.14.0",
+  "version": "1.14.1",
   "description": "Mock infrastructure for AI application testing — LLM APIs, image generation, text-to-speech, transcription, video generation, MCP tools, A2A agents, AG-UI event streams, vector databases, search, rerank, and moderation. One package, one port, zero dependencies.",
   "license": "MIT",
   "keywords": [

package.json

@@ -308,4 +308,69 @@ describe("Journal", () => {
       expect(journal.getLast()!.id).toBe(entry.id);
     });
   });
+
+  describe("maxEntries (FIFO eviction)", () => {
+    it("caps entries to maxEntries, dropping oldest (FIFO)", () => {
+      const journal = new Journal({ maxEntries: 3 });
+
+      journal.add(makeEntry({ path: "/a" }));
+      journal.add(makeEntry({ path: "/b" }));
+      journal.add(makeEntry({ path: "/c" }));
+      journal.add(makeEntry({ path: "/d" }));
+      journal.add(makeEntry({ path: "/e" }));
+
+      expect(journal.size).toBe(3);
+      const all = journal.getAll();
+      expect(all.map((e) => e.path)).toEqual(["/c", "/d", "/e"]);
+    });
+
+    it("does not cap when maxEntries is unset (backwards compat)", () => {
+      const journal = new Journal();
+      for (let i = 0; i < 5000; i++) journal.add(makeEntry({ path: `/${i}` }));
+      expect(journal.size).toBe(5000);
+    });
+
+    it("treats maxEntries = 0 or negative as uncapped", () => {
+      const journal0 = new Journal({ maxEntries: 0 });
+      const journalNeg = new Journal({ maxEntries: -1 });
+      for (let i = 0; i < 100; i++) {
+        journal0.add(makeEntry({ path: `/${i}` }));
+        journalNeg.add(makeEntry({ path: `/${i}` }));
+      }
+      expect(journal0.size).toBe(100);
+      expect(journalNeg.size).toBe(100);
+    });
+
+    it("getLast returns the most recent after eviction", () => {
+      const journal = new Journal({ maxEntries: 2 });
+      journal.add(makeEntry({ path: "/a" }));
+      journal.add(makeEntry({ path: "/b" }));
+      const last = journal.add(makeEntry({ path: "/c" }));
+      expect(journal.getLast()!.id).toBe(last.id);
+      expect(journal.getLast()!.path).toBe("/c");
+    });
+
+    it("findByFixture only returns surviving entries after eviction", () => {
+      const journal = new Journal({ maxEntries: 2 });
+      const fixture: Fixture = { match: { userMessage: "x" }, response: { content: "X" } };
+
+      journal.add(makeEntry({ response: { status: 200, fixture } }));
+      journal.add(makeEntry({ response: { status: 200, fixture } }));
+      journal.add(makeEntry({ response: { status: 200, fixture } }));
+
+      expect(journal.findByFixture(fixture)).toHaveLength(2);
+    });
+
+    it("memory does not grow unbounded under sustained load with cap", () => {
+      // Red-green anchor for the leak fix: 100k adds with cap=500 must stay at 500.
+      const journal = new Journal({ maxEntries: 500 });
+      for (let i = 0; i < 100_000; i++) {
+        journal.add(makeEntry({ path: `/${i}` }));
+      }
+      expect(journal.size).toBe(500);
+      // Last 500 paths preserved, oldest 99,500 evicted
+      expect(journal.getLast()!.path).toBe("/99999");
+      expect(journal.getAll()[0].path).toBe("/99500");
+    });
+  });
 });

src/__tests__/journal.test.ts

@@ -25,6 +25,7 @@ Options:
       --record              Record mode: proxy unmatched requests and save fixtures
       --proxy-only          Proxy mode: forward unmatched requests without saving
       --strict              Strict mode: fail on unmatched requests
+      --journal-max <n>     Max request entries retained in memory (default: 1000, 0 = unbounded)
       --provider-openai <url>     Upstream URL for OpenAI (used with --record)
       --provider-anthropic <url>  Upstream URL for Anthropic
       --provider-gemini <url>     Upstream URL for Gemini
@@ -70,6 +71,7 @@ const { values } = parseArgs({
     "chaos-drop": { type: "string" },
     "chaos-malformed": { type: "string" },
     "chaos-disconnect": { type: "string" },
+    "journal-max": { type: "string", default: "1000" },
     help: { type: "boolean", default: false },
   },
   strict: true,
@@ -110,6 +112,12 @@ if (Number.isNaN(chunkSize) || chunkSize < 1) {
   process.exit(1);
 }
 
+const journalMax = Number(values["journal-max"]);
+if (Number.isNaN(journalMax) || !Number.isInteger(journalMax)) {
+  console.error(`Invalid journal-max: ${values["journal-max"]} (must be an integer)`);
+  process.exit(1);
+}
+
 const logger = new Logger(logLevel);
 
 // Parse chaos config from CLI flags
@@ -256,6 +264,7 @@ async function main() {
       metrics: values.metrics,
       record,
       strict: values.strict,
+      journalMaxEntries: journalMax,
     },
     mounts,
   );

src/cli.ts

@@ -29,9 +29,31 @@ function matchCriteriaEqual(a: FixtureMatch, b: FixtureMatch): boolean {
   );
 }
 
+export interface JournalOptions {
+  /**
+   * Maximum number of entries to retain. When exceeded, oldest entries are
+   * dropped FIFO. Set to 0 (or a negative value) for unbounded retention
+   * (the historical default — suitable for short-lived test runs only).
+   *
+   * Long-running servers (e.g. mock proxies in CI/demo environments) should
+   * always set a finite cap: every request appends an entry holding the
+   * request body + headers + fixture reference, and without a cap the
+   * journal grows until the process OOMs.
+   */
+  maxEntries?: number;
+}
+
 export class Journal {
   private entries: JournalEntry[] = [];
   private readonly fixtureMatchCountsByTestId: Map<string, Map<Fixture, number>> = new Map();
+  private readonly maxEntries: number;
+
+  constructor(options: JournalOptions = {}) {
+    // Treat 0 or negative as "unbounded" to preserve prior behavior when
+    // the option is omitted or explicitly disabled.
+    const cap = options.maxEntries;
+    this.maxEntries = cap !== undefined && cap > 0 ? cap : 0;
+  }
 
   /** Backwards-compatible accessor — returns the default (no testId) count map. */
   get fixtureMatchCounts(): Map<Fixture, number> {
@@ -45,6 +67,12 @@ export class Journal {
       ...entry,
     };
     this.entries.push(full);
+    // FIFO eviction when over capacity. shift() in a tight loop would be
+    // O(n^2); we only ever overshoot by one per add, so a single shift is
+    // amortized O(1) per request.
+    if (this.maxEntries > 0 && this.entries.length > this.maxEntries) {
+      this.entries.shift();
+    }
     return full;
   }
 

src/journal.ts

@@ -715,7 +715,7 @@ export async function createServer(
     }
   }
 
-  const journal = new Journal();
+  const journal = new Journal({ maxEntries: options?.journalMaxEntries });
   const videoStates: VideoStateMap = new Map();
 
   // Share journal and metrics registry with mounted services

src/server.ts

@@ -398,6 +398,16 @@ export interface MockServerOptions {
   strict?: boolean;
   /** Record-and-replay: proxy unmatched requests to upstream and save fixtures. */
   record?: RecordConfig;
+  /**
+   * Maximum number of request/response entries to retain in the in-memory
+   * journal. Oldest entries are dropped FIFO when the cap is exceeded.
+   * Set to 0 (or a negative value) for unbounded retention.
+   *
+   * Defaults vary by invocation path: the CLI applies a finite cap suitable
+   * for long-running servers (see `cli.ts`); programmatic callers default
+   * to unbounded to preserve prior behavior for short-lived test runs.
+   */
+  journalMaxEntries?: number;
   /**
    * Normalize requests before matching and recording. Useful for stripping
    * dynamic data (timestamps, UUIDs, session IDs) that would cause fixture