claude-code-cache-fix 3.5.4 → 3.6.0

package/README.md

@@ -167,6 +167,43 @@ node "$(npm root -g)\claude-code-cache-fix\proxy\server.mjs"
 
 Stderr will print `[upstream] using proxy http://proxy.corp.example:8080 ...` on first request when the agent is wired correctly. With no proxy/CA env vars set, behavior is unchanged from earlier versions (Node default agent, system trust store).
 
+### Embedding the proxy in your own process
+
+If you ship a Node or Bun binary that wants the cache-fix proxy in-process (e.g. a Bun-compiled agent that avoids forking a Node child), import the factory from `claude-code-cache-fix/proxy/server`:
+
+```js
+import { startProxy } from "claude-code-cache-fix/proxy/server";
+
+const handle = await startProxy({
+  port: 0,        // OS-assigned ephemeral port; pass a number to pin
+  bind: "127.0.0.1",
+  watch: false,   // skip fs.watch — recommended for compiled binaries
+});
+
+console.log(`proxy listening on ${handle.address}:${handle.port}`);
+
+// ...later...
+await handle.close();
+```
+
+**`createProxyServer()` → `http.Server`** builds the request handler wired into an `http.Server`. The returned server is *not* listening and the extension pipeline has not been loaded — use this when you want to manage the lifecycle yourself.
+
+**`startProxy(options?)` → `Promise<{ server, port, address, close }>`** loads the extension pipeline, optionally starts the file watcher, and starts listening. Returns a handle with the bound port (resolved when `port: 0` is requested) and a `close()` that releases the server and the watcher.
+
+Options (all optional; all fall back to the same env vars used by the CLI):
+
+| Option | Default | Effect |
+|--------|---------|--------|
+| `port` | `CACHE_FIX_PROXY_PORT` env, else `9801` | Listen port. Pass `0` for an OS-assigned ephemeral port. |
+| `bind` | `CACHE_FIX_PROXY_BIND` env, else `127.0.0.1` | Bind address. |
+| `extensionsDir` | package `proxy/extensions/` | Directory to load `.mjs` extensions from. |
+| `extensionsConfig` | package `proxy/extensions.json` | Path to extension config. |
+| `watch` | `true` | Whether to start `fs.watch` on the extensions config. Set `false` for embedded / compiled-binary use. |
+
+**One extension registry per process.** The pipeline maintains a single shared extension registry at module scope. Hosting two `startProxy()` instances in the same process is supported (different ports, different bind addresses), but they share that registry — a subsequent `loadExtensions` call replaces it for both. If you need divergent extension configs per instance, run them in separate processes.
+
+**CLI invocation is unchanged.** `node proxy/server.mjs`, `cache-fix-proxy server`, and the wrapper's child-fork path all auto-listen and install SIGTERM/SIGINT handlers as before. Library imports never trigger that behavior — the auto-listen is gated behind a main-module check.
+
 ## Quick Start: Preload (CC v2.1.112 and earlier)
 
 If you're on a Node.js-based CC version (v2.1.112 or earlier), the preload interceptor works without a proxy:

package/package.json

@@ -1,9 +1,12 @@
 {
   "name": "claude-code-cache-fix",
-  "version": "3.5.4",
+  "version": "3.6.0",
   "description": "Cache optimization proxy and interceptor for Claude Code. Fixes prompt cache bugs, stabilizes prefix, reduces quota burn.",
   "type": "module",
-  "exports": "./preload.mjs",
+  "exports": {
+    ".": "./preload.mjs",
+    "./proxy/server": "./proxy/server.mjs"
+  },
   "main": "./preload.mjs",
   "bin": {
     "cache-fix-proxy": "./bin/claude-via-proxy.mjs"

package/proxy/extensions/cache-telemetry.mjs

@@ -71,11 +71,15 @@ function parseHeaders(headers) {
   const overage_status = get("anthropic-ratelimit-unified-overage-status");
   const overage_util = num("anthropic-ratelimit-unified-overage-utilization");
   const overage_reset = parseInt(get("anthropic-ratelimit-unified-overage-reset")) || 0;
+  const unified_reset = parseInt(get("anthropic-ratelimit-unified-reset")) || 0;
   const fallback_pct = get("anthropic-ratelimit-unified-fallback-percentage");
   const representative = get("anthropic-ratelimit-unified-representative-claim");
   const surpassed = get("anthropic-ratelimit-unified-7d-surpassed-threshold");
 
-  if (!q5h_reset && !q7d_reset) return null;
+  // Accept any reset timestamp — accounts without 5h/7d quota windows (overage
+  // billing) return anthropic-ratelimit-unified-reset and/or
+  // anthropic-ratelimit-unified-overage-reset instead.
+  if (!q5h_reset && !q7d_reset && !unified_reset && !overage_reset) return null;
 
   const now = new Date();
   const hour = now.getUTCHours();

package/proxy/server.mjs

@@ -1,4 +1,5 @@
 import http from "node:http";
+import { pathToFileURL } from "node:url";
 import config from "./config.mjs";
 import { forwardRequest } from "./upstream.mjs";
 import { streamResponse, createTelemetryRecord } from "./stream.mjs";
@@ -138,36 +139,106 @@ function handleNotFound(_req, res) {
   res.end(JSON.stringify({ error: "not_found" }));
 }
 
-const server = http.createServer((req, res) => {
-  if (req.method === "GET" && req.url === "/health") {
-    return handleHealth(req, res);
-  }
-  if (req.method === "POST" && req.url?.startsWith("/v1/messages")) {
-    return handleMessages(req, res);
-  }
-  handleNotFound(req, res);
-});
-
-function shutdown() {
-  server.close(() => process.exit(0));
-  setTimeout(() => process.exit(1), 5000);
+/**
+ * Builds an http.Server with the proxy's request handler wired in. The
+ * returned server is **not** listening and the extension pipeline has not
+ * been initialized — callers wanting a one-call setup should use
+ * `startProxy()` instead.
+ *
+ * Exposed so callers can embed the proxy in their own process (e.g.
+ * Bun-compiled binaries, test harnesses) without forking a child or
+ * shelling out to the `cache-fix-proxy` bin.
+ */
+export function createProxyServer() {
+  return http.createServer((req, res) => {
+    if (req.method === "GET" && req.url === "/health") {
+      return handleHealth(req, res);
+    }
+    if (req.method === "POST" && req.url?.startsWith("/v1/messages")) {
+      return handleMessages(req, res);
+    }
+    handleNotFound(req, res);
+  });
 }
 
-process.on("SIGTERM", shutdown);
-process.on("SIGINT", shutdown);
-
-async function initPipeline() {
+/**
+ * Builds the server, loads the extension pipeline, optionally starts the
+ * extensions-config file watcher, and starts listening. Returns a handle
+ * with the bound port (resolved when port 0 is requested) and a `close`
+ * function for graceful shutdown.
+ *
+ * All options fall back to the same env vars / defaults used by the CLI
+ * entrypoint, so existing deployments behave identically.
+ *
+ *   await startProxy()                               // env-driven, CLI parity
+ *   await startProxy({ port: 0 })                    // OS-assigned port
+ *   await startProxy({ port: 0, watch: false })      // embedded, no fs.watch
+ */
+export async function startProxy(options = {}) {
+  const port = options.port ?? config.port;
+  const bind = options.bind ?? config.bind;
+  const extensionsDir = options.extensionsDir ?? config.extensionsDir;
+  const extensionsConfig = options.extensionsConfig ?? config.extensionsConfig;
+  const watch = options.watch !== false;
+
+  let watcher = null;
   try {
-    await loadExtensions(config.extensionsDir, config.extensionsConfig);
-    startWatcher(config.extensionsDir, config.extensionsConfig);
+    await loadExtensions(extensionsDir, extensionsConfig);
+    if (watch) watcher = startWatcher(extensionsDir, extensionsConfig);
   } catch {}
-}
 
-initPipeline().then(() => {
-  server.listen(config.port, config.bind, () => {
-    const addr = server.address();
-    process.stdout.write(`proxy listening on ${addr.address}:${addr.port}\n`);
+  const server = createProxyServer();
+  await new Promise((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(port, bind, () => {
+      server.off("error", reject);
+      resolve();
+    });
   });
-});
 
-export { server };
+  const addr = server.address();
+  return {
+    server,
+    port: addr.port,
+    address: addr.address,
+    close: () =>
+      new Promise((resolve, reject) => {
+        try {
+          if (watcher) watcher.close();
+        } catch {}
+        server.close((err) => (err ? reject(err) : resolve()));
+      }),
+  };
+}
+
+// CLI entrypoint — preserves the v3.x behavior of `node proxy/server.mjs`
+// (used by `cache-fix-proxy server` and by `fork(SERVER_PATH)` in the
+// wrapper). When this module is imported as a library, none of this runs.
+const invokedAsScript =
+  typeof process !== "undefined" &&
+  process.argv[1] &&
+  import.meta.url === pathToFileURL(process.argv[1]).href;
+
+if (invokedAsScript) {
+  let active;
+  startProxy()
+    .then((handle) => {
+      active = handle;
+      process.stdout.write(`proxy listening on ${handle.address}:${handle.port}\n`);
+    })
+    .catch((err) => {
+      process.stderr.write(`proxy failed to start: ${err.message}\n`);
+      process.exit(1);
+    });
+
+  const shutdown = () => {
+    if (!active) {
+      process.exit(0);
+      return;
+    }
+    active.close().finally(() => process.exit(0));
+    setTimeout(() => process.exit(1), 5000).unref();
+  };
+  process.on("SIGTERM", shutdown);
+  process.on("SIGINT", shutdown);
+}