node-caching-proxy 1.0.0

package/LICENCE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mohd Faizan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,87 @@
+# Caching Proxy
+
+A CLI tool that starts a proxy server. It forwards requests to a real origin
+server and caches the responses. If the same request comes in again, it's
+served straight from the cache instead of hitting the origin server.
+
+No npm dependencies — uses only Node.js's built-in `http`/`https` modules,
+so `node index.js ...` works with nothing to install.
+
+## File structure
+
+```
+caching-proxy/
+├── index.js                    entry point: parses args, picks a mode
+└── src/
+    ├── args.js                 CLI argument parsing + usage text
+    ├── state.js                shared temp-file so --clear-cache can
+    │                           find the running server's port
+    ├── cache.js                the cache store itself (Map wrapper)
+    ├── server.js               the proxy server: cache check, forward
+    │                           to origin, cache the response
+    └── clear-cache-client.js   sends the "clear cache" request to a
+                                running server
+```
+
+## Usage
+
+Start the proxy:
+
+```bash
+node index.js --port 3000 --origin http://dummyjson.com
+```
+
+Now requests to your proxy are forwarded to the origin:
+
+```bash
+curl http://localhost:3000/products/1
+```
+
+- First request  -> forwarded to `http://dummyjson.com/products/1`, response is cached.
+  Response header: `X-Cache: MISS`
+- Second request to the same path -> served from cache, origin is not hit.
+  Response header: `X-Cache: HIT`
+
+Clear the cache without restarting the server:
+
+```bash
+node index.js --clear-cache
+```
+
+## How it works
+
+1. **Parse CLI args** — `--port`, `--origin`, or `--clear-cache`.
+2. **Cache store** — an in-memory `Map` keyed by `"METHOD path+query"`
+   (e.g. `GET /products/1`), storing `{ status, headers, body }`.
+3. **On each request:**
+   - If it's a `GET` and the key is in the cache -> write back the cached
+     status/headers/body, add `X-Cache: HIT`.
+   - Otherwise -> forward the request (method, headers, body) to the origin
+     via `http`/`https`, buffer the response, store it in the cache if it
+     was a `GET`, and return it with `X-Cache: MISS`.
+4. **`--clear-cache`** — a separate CLI invocation. It reads the running
+   server's port from a small state file in the OS temp dir, then POSTs to
+   an internal `/__internal_clear_cache__` route on that same server, which
+   calls `cache.clear()`. This is what lets `--clear-cache` actually affect
+   the live server's cache rather than just this process's own (empty) one.
+
+## Design notes / things worth knowing if you extend this
+
+- Only `GET` requests are cached. Caching `POST`/`PUT`/`DELETE` responses is
+  usually wrong since those requests aren't idempotent/safe.
+- The cache key includes the query string, so `/items?page=1` and
+  `/items?page=2` are cached separately.
+- `Content-Length` from the origin is preserved as-is since we buffer the
+  full body before responding, so it stays accurate.
+- `Transfer-Encoding` is stripped from cached/forwarded headers since we're
+  sending a fixed-length buffered body, not a stream.
+- The cache is in-memory and per-process: restarting the proxy always
+  starts with an empty cache.
+
+## Possible extensions
+
+- Add a TTL (max-age) so cache entries expire automatically.
+- Add `--clear-cache` for a *specific* path instead of the whole cache.
+- Persist the cache to disk so it survives restarts.
+- Respect the origin's own `Cache-Control`/`ETag` headers instead of
+  caching everything unconditionally.

package/index.js

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+
+// Entry point: parse CLI args, then hand off to whichever module handles
+// that mode. All the real logic lives in ./src/*.
+
+import { parseArgs, printUsage } from "./src/args.js";
+import { startServer } from "./src/server.js";
+import { clearRunningCache } from "./src/clear-cache-client.js";
+
+const args = parseArgs(process.argv.slice(2));
+
+const missingRequiredFlags = !args.clearCache && (!args.port || !args.origin);
+
+if (args.help || missingRequiredFlags) {
+  printUsage();
+  process.exit(args.help ? 0 : 1);
+}
+
+if (args.clearCache) {
+  clearRunningCache();
+} else {
+  startServer(Number(args.port), args.origin);
+}

package/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "node-caching-proxy",
+  "version": "1.0.0",
+  "description": "A CLI caching reverse proxy that forwards requests to an origin server and caches responses, using only Node.js core modules.",
+  "type": "module",
+  "main": "index.js",
+  "bin": {
+    "caching-proxy": "./index.js"
+  },
+  "files": [
+    "index.js",
+    "src/"
+  ],
+  "keywords": ["cli", "proxy", "cache", "http", "reverse-proxy"],
+  "license": "MIT",
+  "author": "Mohd Faizan",
+  "engines": {
+    "node": ">=16"
+  }
+}

package/src/args.js

@@ -0,0 +1,30 @@
+// Turns raw CLI words (process.argv) into a clean options object.
+// e.g. ["--port", "3000", "--origin", "http://x.com"]
+//   -> { port: "3000", origin: "http://x.com", clearCache: false, help: false }
+
+export function parseArgs(argv) {
+  const args = { port: null, origin: null, clearCache: false, help: false };
+
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--port" || a === "-p") args.port = argv[++i];
+    else if (a === "--origin" || a === "-o") args.origin = argv[++i];
+    else if (a === "--clear-cache") args.clearCache = true;
+    else if (a === "--help" || a === "-h") args.help = true;
+  }
+
+  return args;
+}
+
+export function printUsage() {
+  console.log(`
+Caching Proxy CLI
+
+Usage:
+  caching-proxy --port <number> --origin <url>   Start the proxy server
+  caching-proxy --clear-cache                    Clear the cache of a running proxy
+
+Example:
+  caching-proxy --port 3000 --origin http://dummyjson.com
+`);
+}

package/src/cache.js

@@ -0,0 +1,25 @@
+// The actual cache store. Kept separate from server.js so the "what is a
+// cache entry / how do we key it" logic doesn't get tangled up with the
+// networking code.
+
+export function createCache() {
+  const store = new Map(); // key: "METHOD path" -> { status, headers, body }
+
+  return {
+    key(method, url) {
+      return `${method} ${url}`;
+    },
+    has(key) {
+      return store.has(key);
+    },
+    get(key) {
+      return store.get(key);
+    },
+    set(key, value) {
+      store.set(key, value);
+    },
+    clear() {
+      store.clear();
+    },
+  };
+}

package/src/clear-cache-client.js

@@ -0,0 +1,36 @@
+// This runs as its OWN process invocation (`node index.js --clear-cache`).
+// It has no access to a running server's in-memory cache directly, so it
+// looks up that server's port from the shared state file, then sends it
+// an HTTP request telling it to clear its own cache.
+
+import http from "http";
+import { loadServerState } from "./state.js";
+
+export function clearRunningCache() {
+  const state = loadServerState();
+
+  if (!state) {
+    console.error("No running caching-proxy server found.");
+    process.exit(1);
+  }
+
+  const req = http.request(
+    {
+      hostname: "localhost",
+      port: state.port,
+      path: "/__internal_clear_cache__",
+      method: "POST",
+    },
+    (res) => {
+      res.on("data", () => {});
+      res.on("end", () => console.log("Cache cleared successfully."));
+    }
+  );
+
+  req.on("error", (err) => {
+    console.error("Failed to reach the running proxy:", err.message);
+    process.exit(1);
+  });
+
+  req.end();
+}

package/src/server.js

@@ -0,0 +1,113 @@
+// The proxy server: listens for client requests, serves them from cache
+// when possible, otherwise forwards to the origin server and caches the
+// result.
+
+import http from "http";
+import https from "https";
+import { URL } from "url";
+import { createCache } from "./cache.js";
+import { saveServerState } from "./state.js";
+
+const CLEAR_CACHE_ROUTE = "/__internal_clear_cache__";
+
+export function startServer(port, originUrl) {
+  const cache = createCache();
+  const origin = new URL(originUrl);
+  const client = origin.protocol === "https:" ? https : http;
+
+  const server = http.createServer((req, res) => {
+    if (isClearCacheRequest(req)) {
+      return handleClearCache(cache, res);
+    }
+
+    const cacheKey = cache.key(req.method, req.url);
+
+    if (req.method === "GET" && cache.has(cacheKey)) {
+      return serveFromCache(cache.get(cacheKey), res);
+    }
+
+    forwardToOrigin({ req, res, origin, client, cache, cacheKey });
+  });
+
+  server.listen(port, () => {
+    saveServerState({ port });
+    console.log(`Caching proxy listening on port ${port}`);
+    console.log(`Forwarding to origin: ${originUrl}`);
+  });
+
+  process.on("SIGINT", () => server.close(() => process.exit(0)));
+
+  return server;
+}
+
+function isClearCacheRequest(req) {
+  return req.method === "POST" && req.url === CLEAR_CACHE_ROUTE;
+}
+
+function handleClearCache(cache, res) {
+  cache.clear();
+  console.log("Cache cleared.");
+  res.writeHead(200);
+  res.end("Cache cleared");
+}
+
+function serveFromCache(cached, res) {
+  res.writeHead(cached.status, { ...cached.headers, "X-Cache": "HIT" });
+  res.end(cached.body);
+}
+
+function forwardToOrigin({ req, res, origin, client, cache, cacheKey }) {
+  // Request bodies arrive in chunks; buffer them fully before forwarding.
+  const chunks = [];
+  req.on("data", (c) => chunks.push(c));
+  req.on("end", () => {
+    const body = Buffer.concat(chunks);
+    sendToOrigin({ req, res, origin, client, cache, cacheKey, body });
+  });
+}
+
+function sendToOrigin({ req, res, origin, client, cache, cacheKey, body }) {
+  const forwardHeaders = { ...req.headers, host: origin.host };
+
+  const proxyReq = client.request(
+    {
+      protocol: origin.protocol,
+      hostname: origin.hostname,
+      port: origin.port || (origin.protocol === "https:" ? 443 : 80),
+      path: req.url,
+      method: req.method,
+      headers: forwardHeaders,
+    },
+    (originRes) => handleOriginResponse({ originRes, res, req, cache, cacheKey })
+  );
+
+  proxyReq.on("error", (err) => {
+    console.error("Proxy error:", err.message);
+    res.writeHead(502);
+    res.end("Bad Gateway: could not reach origin server");
+  });
+
+  if (body.length) proxyReq.write(body);
+  proxyReq.end();
+}
+
+function handleOriginResponse({ originRes, res, req, cache, cacheKey }) {
+  const resChunks = [];
+  originRes.on("data", (c) => resChunks.push(c));
+  originRes.on("end", () => {
+    const responseBody = Buffer.concat(resChunks);
+    const headers = { ...originRes.headers };
+    delete headers["transfer-encoding"];
+
+    if (req.method === "GET") {
+      cache.set(cacheKey, {
+        status: originRes.statusCode,
+        headers,
+        body: responseBody,
+      });
+    }
+
+    res.writeHead(originRes.statusCode, { ...headers, "X-Cache": "MISS" });
+    res.end(responseBody);
+  });
+}

package/src/state.js

@@ -0,0 +1,18 @@
+// A small JSON file in the OS temp dir. It's the only way two separate
+// process invocations (the running server, and a later `--clear-cache`
+// call) can find each other - they share this file, not memory.
+
+import fs from "fs";
+import os from "os";
+import path from "path";
+
+const STATE_FILE = path.join(os.tmpdir(), "caching-proxy-state.json");
+
+export function saveServerState({ port }) {
+  fs.writeFileSync(STATE_FILE, JSON.stringify({ port }));
+}
+
+export function loadServerState() {
+  if (!fs.existsSync(STATE_FILE)) return null;
+  return JSON.parse(fs.readFileSync(STATE_FILE, "utf-8"));
+}