@johnhenry/letterpress 0.0.3 → 0.2.0

package/rewrite.d.ts

@@ -0,0 +1,61 @@
+// Type declarations for the @johnhenry/letterpress/rewrite subpath.
+//
+// createRewriter is a request/response rewriter for target-URL/path
+// rewriting (e.g. rewriting an inbound path before it reaches a route, or
+// rewriting a proxied response's headers/status on the way back out). It
+// existed in `leroute` (the package letterpress was renamed from) but was
+// dropped during that rename; it's kept on its own subpath here (rather
+// than the main barrel) to mirror how `./fs` is isolated -- see
+// rewrite.mjs's top-of-file comment and CHANGELOG.md.
+
+export type RewriteMatch = {
+  path?: string | RegExp;
+  method?: string;
+};
+
+export type RewriteAction = {
+  setHeader?: Record<string, string>;
+  removeHeader?: string[];
+  // Replacement string for the matched path; supports `$1`-style regex
+  // capture group references when `match.path` is a RegExp.
+  rewritePath?: string;
+  // Response only.
+  setStatus?: number;
+};
+
+export type RewriteRule = {
+  match?: RewriteMatch;
+  action?: RewriteAction;
+};
+
+// The shape returned by getRules(): a rule with its index in the rule
+// list, and any RegExp `match.path` normalized back to its `.source`
+// string.
+export type RewriteRuleSnapshot = {
+  index: number;
+  match: {
+    path?: string;
+    method?: string;
+  };
+  action?: RewriteAction;
+};
+
+// Wraps a Route-shaped handler ((request, context) => Response) with
+// request/response rewriting.
+export type RewriterMiddleware = (
+  next: (request: Request, context?: Record<string, any>) => Response | Promise<Response>
+) => (request: Request, context?: Record<string, any>) => Promise<Response>;
+
+export type Rewriter = {
+  middleware: RewriterMiddleware;
+  rewriteRequest: (request: Request) => Request;
+  rewriteResponse: (response: Response, request?: Request) => Response;
+  addRule: (rule: RewriteRule) => void;
+  removeRule: (index: number) => void;
+  getRules: () => RewriteRuleSnapshot[];
+};
+
+export type CreateRewriter = (initialRules?: RewriteRule[]) => Rewriter;
+
+export declare const createRewriter: CreateRewriter;
+export default createRewriter;

package/rewrite.mjs

@@ -0,0 +1,176 @@
+/**
+ * @file rewrite.mjs
+ * @description Create a request/response rewriter for target-URL/path
+ * rewriting -- e.g. rewriting an inbound path before it reaches a route, or
+ * rewriting a proxied response's headers/status on the way back out.
+ *
+ * This existed in `leroute` (the package letterpress was renamed from --
+ * see the README's provenance note) as `createRewriter`, but was dropped
+ * during the leroute -> @johnhenry/letterpress rename. It's ported here
+ * unchanged in behavior, discovered missing while porting a downstream
+ * consumer (`prism`, a request inspector/proxy) that relies on it for
+ * proxy-mode rewriting.
+ *
+ * Rules format:
+ *   {
+ *     match: { path?: string|RegExp, method?: string },
+ *     action: {
+ *       setHeader?: { [name]: value },
+ *       removeHeader?: string[],
+ *       rewritePath?: string,          // replacement string (supports $1 from regex)
+ *       setStatus?: number,            // response only
+ *     }
+ *   }
+ *
+ * @param {Array} [initialRules=[]]
+ */
+export const createRewriter = (initialRules = []) => {
+  const rules = [...initialRules];
+
+  const matches = (rule, request) => {
+    if (!rule.match) return true;
+    const url = new URL(request.url);
+    if (rule.match.method && rule.match.method.toUpperCase() !== request.method) {
+      return false;
+    }
+    if (rule.match.path) {
+      const pattern = rule.match.path;
+      if (pattern instanceof RegExp) {
+        return pattern.test(url.pathname);
+      }
+      // String match — treat as prefix or exact
+      if (!url.pathname.startsWith(pattern)) return false;
+    }
+    return true;
+  };
+
+  const rewriteRequest = (request) => {
+    let url = new URL(request.url);
+    let headers = new Headers(request.headers);
+    let pathChanged = false;
+
+    for (const rule of rules) {
+      if (!matches(rule, request)) continue;
+      const action = rule.action || {};
+
+      if (action.setHeader) {
+        for (const [name, value] of Object.entries(action.setHeader)) {
+          headers.set(name, value);
+        }
+      }
+      if (action.removeHeader) {
+        for (const name of action.removeHeader) {
+          headers.delete(name);
+        }
+      }
+      if (action.rewritePath) {
+        if (rule.match?.path instanceof RegExp) {
+          url.pathname = url.pathname.replace(rule.match.path, action.rewritePath);
+        } else {
+          url.pathname = action.rewritePath;
+        }
+        pathChanged = true;
+      }
+    }
+
+    if (pathChanged || !headersEqual(headers, request.headers)) {
+      return new Request(url, {
+        method: request.method,
+        headers,
+        body: request.body,
+        duplex: "half",
+      });
+    }
+    return request;
+  };
+
+  const rewriteResponse = (response, request) => {
+    let headers = new Headers(response.headers);
+    let status = response.status;
+    let statusText = response.statusText;
+    let changed = false;
+
+    for (const rule of rules) {
+      // When request is provided, filter rules through matches()
+      // Rules with no match clause still apply globally
+      if (request && !matches(rule, request)) continue;
+
+      const action = rule.action || {};
+      if (action.setHeader) {
+        for (const [name, value] of Object.entries(action.setHeader)) {
+          headers.set(name, value);
+        }
+        changed = true;
+      }
+      if (action.removeHeader) {
+        for (const name of action.removeHeader) {
+          headers.delete(name);
+        }
+        changed = true;
+      }
+      if (action.setStatus) {
+        status = action.setStatus;
+        changed = true;
+      }
+    }
+
+    if (changed) {
+      return new Response(response.body, { status, statusText, headers });
+    }
+    return response;
+  };
+
+  /**
+   * Wraps a Route-shaped handler ((request, context) => Response) with
+   * request/response rewriting: the handler receives the rewritten
+   * request, and the handler's response is then run through
+   * rewriteResponse before being returned.
+   * @param {Function} next - The next handler: (request, context) => Response
+   * @returns {Function} Wrapped handler: (request, context) => Response
+   */
+  const middleware = (next) => async (request, context) => {
+    const rewrittenReq = rewriteRequest(request);
+    const response = await next(rewrittenReq, context);
+    return rewriteResponse(response, request);
+  };
+
+  const addRule = (rule) => {
+    // Convert path string to regex if it looks like one
+    if (rule.match?.path && typeof rule.match.path === "string" && rule.match.path.startsWith("/") && rule.match.path.endsWith("/")) {
+      const inner = rule.match.path.slice(1, -1);
+      try {
+        rule.match.path = new RegExp(inner);
+      } catch {
+        throw new Error(`Invalid regex pattern: ${rule.match.path}`);
+      }
+    }
+    rules.push(rule);
+  };
+
+  const removeRule = (index) => {
+    if (index >= 0 && index < rules.length) {
+      rules.splice(index, 1);
+    }
+  };
+
+  const getRules = () =>
+    rules.map((r, i) => ({
+      index: i,
+      match: {
+        path: r.match?.path instanceof RegExp ? r.match.path.source : r.match?.path,
+        method: r.match?.method,
+      },
+      action: r.action,
+    }));
+
+  return { middleware, rewriteRequest, rewriteResponse, addRule, removeRule, getRules };
+};
+
+const headersEqual = (a, b) => {
+  const aEntries = [...a].sort(([k1], [k2]) => k1.localeCompare(k2));
+  const bEntries = [...b].sort(([k1], [k2]) => k1.localeCompare(k2));
+  if (aEntries.length !== bEntries.length) return false;
+  return aEntries.every(([k, v], i) => bEntries[i][0] === k && bEntries[i][1] === v);
+};
+
+export default createRewriter;

package/tag-request.mjs

@@ -0,0 +1,100 @@
+import { parseHttpText } from "./utility/parse-http-text.mjs";
+
+const inferBodyContentType = (body) => {
+  if (body instanceof ReadableStream) return "application/octet-stream";
+  if (body instanceof Blob) return body.type || "application/octet-stream";
+  if (body instanceof URLSearchParams)
+    return "application/x-www-form-urlencoded";
+  if (body instanceof ArrayBuffer || body instanceof Uint8Array)
+    return "application/octet-stream";
+  return null; // FormData sets its own; plain strings get no guessed type
+};
+
+const mergeHeaderEntries = (baseHeaders, headerEntries) => {
+  const seen = new Set();
+  for (const { name, value } of headerEntries) {
+    const key = name.toLowerCase();
+    if (seen.has(key)) {
+      baseHeaders.append(name, value);
+    } else {
+      baseHeaders.set(name, value);
+      seen.add(key);
+    }
+  }
+  return baseHeaders;
+};
+
+const PASSTHROUGH_REQUEST_INIT_KEYS = [
+  "redirect",
+  "credentials",
+  "mode",
+  "referrer",
+  "referrerPolicy",
+  "signal",
+];
+
+export const tagRequest = (defaults = {}) => {
+  const baseHeaders = new Headers(defaults.headers);
+  if (defaults.host !== undefined) {
+    if (baseHeaders.has("host")) {
+      throw new TypeError(
+        "tagRequest: both the 'host' sugar key and headers.host/Host were given in defaults -- remove one"
+      );
+    }
+    baseHeaders.set("host", defaults.host);
+  }
+
+  return async function (strings, ...substitutions) {
+    const { startLine, headerEntries, body } = parseHttpText(
+      strings,
+      substitutions
+    );
+    const [method, url, httpVersion] = startLine.split(" ");
+    if (!method || !url || !httpVersion) {
+      throw new TypeError(
+        `tagRequest: template must start with a request line ("METHOD /path HTTP/1.1"), got: ${JSON.stringify(
+          startLine
+        )}`
+      );
+    }
+
+    const baseUrl = defaults.baseUrl || "http://localhost";
+    const fullUrl =
+      url.startsWith("http://") || url.startsWith("https://")
+        ? new URL(url)
+        : new URL(url.startsWith("/") ? url : `/${url}`, baseUrl);
+
+    const headers = mergeHeaderEntries(new Headers(baseHeaders), headerEntries);
+
+    const requestInit = { method, headers };
+    for (const key of PASSTHROUGH_REQUEST_INIT_KEYS) {
+      if (defaults[key] !== undefined) requestInit[key] = defaults[key];
+    }
+
+    const isBinaryBody = typeof body !== "string";
+    if (isBinaryBody) {
+      requestInit.body = body;
+      if (body instanceof ReadableStream) requestInit.duplex = "half";
+      if (!headers.has("Content-Type")) {
+        const contentType = inferBodyContentType(body);
+        if (contentType) headers.set("Content-Type", contentType);
+      }
+    } else if (body) {
+      requestInit.body = body;
+    }
+
+    if (requestInit.body && !headers.has("Content-Length")) {
+      const size =
+        requestInit.body instanceof Blob
+          ? requestInit.body.size
+          : typeof requestInit.body === "string"
+          ? new Blob([requestInit.body]).size
+          : null;
+      if (size !== null) headers.set("Content-Length", size.toString());
+    }
+
+    return new Request(fullUrl, requestInit);
+  };
+};
+
+export default tagRequest;

package/tag-response.mjs

@@ -0,0 +1,73 @@
+import { parseHttpText } from "./utility/parse-http-text.mjs";
+
+const inferBodyContentType = (body) => {
+  if (body instanceof ReadableStream) return "application/octet-stream";
+  if (body instanceof Blob) return body.type || "application/octet-stream";
+  if (body instanceof URLSearchParams)
+    return "application/x-www-form-urlencoded";
+  if (body instanceof ArrayBuffer || body instanceof Uint8Array)
+    return "application/octet-stream";
+  return null;
+};
+
+const mergeHeaderEntries = (headerEntries) => {
+  const headers = new Headers();
+  const seen = new Set();
+  for (const { name, value } of headerEntries) {
+    const key = name.toLowerCase();
+    if (seen.has(key)) {
+      headers.append(name, value);
+    } else {
+      headers.set(name, value);
+      seen.add(key);
+    }
+  }
+  return headers;
+};
+
+export const tagResponse = async function (strings, ...substitutions) {
+  const { startLine, headerEntries, body } = parseHttpText(
+    strings,
+    substitutions
+  );
+  const [httpVersion, statusCodeText, ...statusTextParts] =
+    startLine.split(" ");
+  const status = parseInt(statusCodeText, 10);
+  if (!httpVersion?.startsWith("HTTP/") || Number.isNaN(status)) {
+    throw new TypeError(
+      `tagResponse: template must start with a status line ("HTTP/1.1 200 OK"), got: ${JSON.stringify(
+        startLine
+      )}`
+    );
+  }
+  const statusText = statusTextParts.join(" ");
+
+  const headers = mergeHeaderEntries(headerEntries);
+
+  const isBinaryBody = typeof body !== "string";
+  let responseBody = body;
+  if (isBinaryBody) {
+    if (!headers.has("Content-Type")) {
+      const contentType = inferBodyContentType(body);
+      if (contentType) headers.set("Content-Type", contentType);
+    }
+  }
+
+  if (responseBody && !headers.has("Content-Length")) {
+    const size =
+      responseBody instanceof Blob
+        ? responseBody.size
+        : typeof responseBody === "string"
+        ? new Blob([responseBody]).size
+        : null;
+    if (size !== null) headers.set("Content-Length", size.toString());
+  }
+
+  return new Response(status === 204 && !responseBody ? null : responseBody, {
+    status,
+    statusText,
+    headers,
+  });
+};
+
+export default tagResponse;

package/test/exports.mjs

@@ -67,3 +67,31 @@ test("@johnhenry/letterpress (self-reference) does not carry createFSRouter", as
   const barrel = await import("@johnhenry/letterpress");
   assert.strictEqual("createFSRouter" in barrel, false);
 });
+
+// Regression tests closing the leroute -> @johnhenry/letterpress migration
+// gap: `createRewriter` existed in leroute (see rewrite.mjs's top-of-file
+// comment and CHANGELOG.md) but was never carried over during the rename.
+// It's exposed the same way createFSRouter is -- a dedicated subpath, not
+// the main barrel -- for consistency with that existing precedent.
+
+test("createRewriter is exported from rewrite.mjs directly", async () => {
+  const rewriteModule = await import("../rewrite.mjs");
+  assert.strictEqual(typeof rewriteModule.createRewriter, "function");
+});
+
+test("package.json exposes a ./rewrite subpath export for createRewriter", async () => {
+  const pkg = await import("../package.json", { with: { type: "json" } });
+  const exportsMap = pkg.default.exports;
+  assert.strictEqual(exportsMap["./rewrite"].default, "./rewrite.mjs");
+  assert.strictEqual(exportsMap["./rewrite"].types, "./rewrite.d.ts");
+});
+
+test("@johnhenry/letterpress/rewrite resolves createRewriter via self-reference", async () => {
+  const rewriteSubpath = await import("@johnhenry/letterpress/rewrite");
+  assert.strictEqual(typeof rewriteSubpath.createRewriter, "function");
+});
+
+test("@johnhenry/letterpress (self-reference) does not carry createRewriter", async () => {
+  const barrel = await import("@johnhenry/letterpress");
+  assert.strictEqual("createRewriter" in barrel, false);
+});

package/test/index.mjs

@@ -2,7 +2,9 @@ import "./router.mjs";
 import "./http-expression.mjs";
 import "./route.mjs";
 import "./req-res.mjs";
+import "./tag-req-res.mjs";
 import "./fs-router.mjs";
+import "./rewrite.mjs";
 import "./dynamic-run.mjs";
 import "./exports.mjs";
 import "./types.test.mjs";

package/test/rewrite.mjs

@@ -0,0 +1,202 @@
+import { test, describe } from "node:test";
+import assert from "node:assert/strict";
+import { createRewriter } from "../rewrite.mjs";
+
+// Ported from leroute's test/rewrite.mjs. createRewriter existed in
+// leroute (the package letterpress was renamed from) but was dropped
+// during the leroute -> @johnhenry/letterpress rename; this closes that
+// migration gap -- see rewrite.mjs's top-of-file comment and
+// CHANGELOG.md. Test cases are unchanged from the leroute original.
+
+describe("Rewrite", () => {
+  test("should rewrite request path with regex capture groups", () => {
+    const rewriter = createRewriter([
+      {
+        match: { path: /^\/api\/v1\/(.*)/ },
+        action: { rewritePath: "/api/v2/$1" },
+      },
+    ]);
+
+    const req = new Request("http://localhost/api/v1/users");
+    const rewritten = rewriter.rewriteRequest(req);
+    const url = new URL(rewritten.url);
+    assert.equal(url.pathname, "/api/v2/users");
+  });
+
+  test("should set and remove request headers", () => {
+    const rewriter = createRewriter([
+      {
+        action: {
+          setHeader: { "x-custom": "hello" },
+          removeHeader: ["x-remove-me"],
+        },
+      },
+    ]);
+
+    const req = new Request("http://localhost/test", {
+      headers: { "x-remove-me": "gone" },
+    });
+    const rewritten = rewriter.rewriteRequest(req);
+    assert.equal(rewritten.headers.get("x-custom"), "hello");
+    assert.equal(rewritten.headers.get("x-remove-me"), null);
+  });
+
+  test("should set and remove response headers", () => {
+    const rewriter = createRewriter([
+      {
+        action: {
+          setHeader: { "x-powered-by": "letterpress" },
+          removeHeader: ["server"],
+        },
+      },
+    ]);
+
+    const res = new Response("ok", {
+      headers: { server: "old" },
+    });
+    const rewritten = rewriter.rewriteResponse(res);
+    assert.equal(rewritten.headers.get("x-powered-by"), "letterpress");
+    assert.equal(rewritten.headers.get("server"), null);
+  });
+
+  test("should set response status", () => {
+    const rewriter = createRewriter([
+      {
+        match: { path: "/teapot" },
+        action: { setStatus: 418 },
+      },
+    ]);
+
+    const req = new Request("http://localhost/teapot");
+    const res = new Response("ok", { status: 200 });
+    const rewritten = rewriter.rewriteResponse(res, req);
+    assert.equal(rewritten.status, 418);
+  });
+
+  test("response rules only apply when request matches (bug fix)", () => {
+    const rewriter = createRewriter([
+      {
+        match: { path: "/admin" },
+        action: { setHeader: { "x-admin": "true" } },
+      },
+    ]);
+
+    const req = new Request("http://localhost/public");
+    const res = new Response("ok");
+    const rewritten = rewriter.rewriteResponse(res, req);
+    // Rule should NOT apply because /public doesn't match /admin
+    assert.equal(rewritten.headers.get("x-admin"), null);
+    // Response should be the same object (unchanged)
+    assert.equal(rewritten, res);
+  });
+
+  test("global rules (no match clause) apply to all responses", () => {
+    const rewriter = createRewriter([
+      {
+        action: { setHeader: { "x-global": "yes" } },
+      },
+    ]);
+
+    const req = new Request("http://localhost/anything");
+    const res = new Response("ok");
+    const rewritten = rewriter.rewriteResponse(res, req);
+    assert.equal(rewritten.headers.get("x-global"), "yes");
+  });
+
+  test("middleware wraps handler correctly", async () => {
+    const rewriter = createRewriter([
+      {
+        match: { path: /^\/old\/(.*)/ },
+        action: {
+          rewritePath: "/new/$1",
+          setHeader: { "x-rewritten": "true" },
+        },
+      },
+    ]);
+
+    // A handler that echoes back the pathname it received
+    const handler = async (request) => {
+      const url = new URL(request.url);
+      return new Response(url.pathname, { status: 200 });
+    };
+
+    const wrapped = rewriter.middleware(handler);
+    const req = new Request("http://localhost/old/stuff");
+    const res = await wrapped(req, {});
+
+    // Handler should have received the rewritten path
+    const body = await res.text();
+    assert.equal(body, "/new/stuff");
+    // Response should have the rewritten header
+    assert.equal(res.headers.get("x-rewritten"), "true");
+  });
+
+  test("addRule with /regex/ string conversion", () => {
+    const rewriter = createRewriter();
+    rewriter.addRule({
+      match: { path: "/^\\/api\\/(.*)/" },
+      action: { rewritePath: "/v2/$1" },
+    });
+
+    const rules = rewriter.getRules();
+    assert.equal(rules.length, 1);
+    assert.equal(rules[0].match.path, "^\\/api\\/(.*)");
+  });
+
+  test("addRule with invalid regex throws descriptive error", () => {
+    const rewriter = createRewriter();
+    assert.throws(
+      () => {
+        rewriter.addRule({
+          match: { path: "/[invalid/" },
+          action: {},
+        });
+      },
+      (err) => {
+        assert.ok(err.message.includes("Invalid regex pattern"));
+        return true;
+      }
+    );
+  });
+
+  test("removeRule / getRules CRUD", () => {
+    const rewriter = createRewriter();
+    rewriter.addRule({ match: { path: "/a" }, action: {} });
+    rewriter.addRule({ match: { path: "/b" }, action: {} });
+    rewriter.addRule({ match: { path: "/c" }, action: {} });
+
+    assert.equal(rewriter.getRules().length, 3);
+
+    rewriter.removeRule(1);
+    const rules = rewriter.getRules();
+    assert.equal(rules.length, 2);
+    assert.equal(rules[0].match.path, "/a");
+    assert.equal(rules[1].match.path, "/c");
+  });
+
+  test("removeRule ignores out-of-bounds index", () => {
+    const rewriter = createRewriter();
+    rewriter.addRule({ match: { path: "/a" }, action: {} });
+    rewriter.removeRule(5);
+    rewriter.removeRule(-1);
+    assert.equal(rewriter.getRules().length, 1);
+  });
+
+  test("method matching", () => {
+    const rewriter = createRewriter([
+      {
+        match: { method: "POST" },
+        action: { setHeader: { "x-method": "post" } },
+      },
+    ]);
+
+    const getReq = new Request("http://localhost/test", { method: "GET" });
+    const postReq = new Request("http://localhost/test", { method: "POST" });
+
+    const getResult = rewriter.rewriteRequest(getReq);
+    const postResult = rewriter.rewriteRequest(postReq);
+
+    assert.equal(getResult.headers.get("x-method"), null);
+    assert.equal(postResult.headers.get("x-method"), "post");
+  });
+});