cpeak 2.6.0 → 2.8.0

package/lib/internal/router.ts

@@ -0,0 +1,259 @@
+import type { Handler, RouteMiddleware, StringMap } from "../types";
+import { frameworkError, ErrorCode } from "./errors";
+
+// A node in our radix tree. Each one can hold up to three kinds of children:
+// an exact static segment, a single ":param" placeholder, or a tail "*"
+// wildcard. The handler and middleware here belong to the route whose path
+// ends at this node, if any.
+//
+// Param names are not stored on the tree edges. We capture values positionally
+// as we walk, and zip them with the param names attached to whichever leaf we
+// land on. That lets two routes share the same param slot in the tree even
+// when they use different names, like "/:id/profile" and "/:username/settings".
+interface RadixNode {
+  staticChildren: Map<string, RadixNode>;
+  paramChild?: RadixNode;
+  wildcardChild?: WildcardLeaf;
+  handler?: Handler;
+  middleware?: RouteMiddleware[];
+  // Names of params captured along the path to this leaf, in order. Only set
+  // on nodes that own a handler.
+  paramNames?: string[];
+}
+
+interface WildcardLeaf {
+  handler: Handler;
+  middleware: RouteMiddleware[];
+  // Names of params captured before reaching this wildcard, in order.
+  paramNames: string[];
+}
+
+export interface RouteMatch {
+  middleware: RouteMiddleware[];
+  handler: Handler;
+  params: StringMap;
+}
+
+function createNode(): RadixNode {
+  return { staticChildren: new Map() };
+}
+
+// We keep one radix tree per HTTP method so different methods can safely
+// share a path shape. POST /comments/:pageId and PUT /comments/:id can
+// coexist without conflict because they live in separate trees.
+export class Router {
+  #treesByMethod: Map<string, RadixNode> = new Map();
+
+  add(
+    method: string,
+    path: string,
+    middleware: RouteMiddleware[],
+    handler: Handler
+  ) {
+    const methodKey = method.toLowerCase();
+    let root = this.#treesByMethod.get(methodKey);
+    if (!root) {
+      root = createNode();
+      this.#treesByMethod.set(methodKey, root);
+    }
+
+    const segments = splitPath(path);
+    const paramNames: string[] = [];
+    let currentNode = root;
+
+    for (let i = 0; i < segments.length; i++) {
+      const segment = segments[i];
+      const isLastSegment = i === segments.length - 1;
+
+      // Named wildcards like "*name" are not a thing here. Only a bare "*"
+      // is allowed, and only as the very last segment.
+      if (segment.length > 1 && segment.startsWith("*")) {
+        throw frameworkError(
+          `Invalid route "${path}": named wildcards (e.g. "*name") are not supported. Use a plain "*" at the end of the path.`,
+          this.add,
+          ErrorCode.INVALID_ROUTE
+        );
+      }
+
+      // A "*" segment installs a tail wildcard on the current node. After
+      // that there's nothing more to walk, so we register and bail out.
+      if (segment === "*") {
+        if (!isLastSegment) {
+          throw frameworkError(
+            `Invalid route "${path}": "*" is only allowed as the final path segment.`,
+            this.add,
+            ErrorCode.INVALID_ROUTE
+          );
+        }
+        if (currentNode.wildcardChild) {
+          throw frameworkError(
+            `Duplicate route: ${method.toUpperCase()} ${path}`,
+            this.add,
+            ErrorCode.DUPLICATE_ROUTE
+          );
+        }
+        currentNode.wildcardChild = { handler, middleware, paramNames };
+        return;
+      }
+
+      // A ":name" segment walks into the param branch at this depth, or
+      // creates one. The name is collected positionally and resolved later
+      // at the leaf, so two routes can disagree on the param name here as
+      // long as their paths diverge before the leaf.
+      if (segment.startsWith(":")) {
+        const paramName = segment.slice(1);
+        if (!paramName) {
+          throw frameworkError(
+            `Invalid route "${path}": empty parameter name.`,
+            this.add,
+            ErrorCode.INVALID_ROUTE
+          );
+        }
+        paramNames.push(paramName);
+        if (!currentNode.paramChild) {
+          currentNode.paramChild = createNode();
+        }
+        currentNode = currentNode.paramChild;
+        continue;
+      }
+
+      // Plain static segment. Walk into the existing child or create a new one.
+      let staticChild = currentNode.staticChildren.get(segment);
+      if (!staticChild) {
+        staticChild = createNode();
+        currentNode.staticChildren.set(segment, staticChild);
+      }
+      currentNode = staticChild;
+    }
+
+    // We have consumed every segment of the path. The terminal node is where
+    // the handler gets attached. If something is already attached here, the
+    // user registered this exact path twice.
+    if (currentNode.handler) {
+      throw frameworkError(
+        `Duplicate route: ${method.toUpperCase()} ${path}`,
+        this.add,
+        ErrorCode.DUPLICATE_ROUTE
+      );
+    }
+    currentNode.handler = handler;
+    currentNode.middleware = middleware;
+    currentNode.paramNames = paramNames;
+  }
+
+  find(method: string, path: string): RouteMatch | null {
+    const root = this.#treesByMethod.get(method.toLowerCase());
+    if (!root) return null;
+
+    const segments = splitPath(path);
+    return matchSegments(root, segments, 0, []);
+  }
+}
+
+// Walk the tree one segment at a time, always trying static before param
+// before wildcard. That ordering is where our precedence rules come from:
+// static beats param beats wildcard. Because each branch is tried in turn
+// and recursion lets us unwind a failed path, the matcher also backtracks.
+// If the static branch dead-ends deeper down, we come back up and try the
+// param sibling with the same segment value.
+//
+// We collect captured param values positionally as we walk. The actual names
+// get zipped in at the terminal leaf, using the paramNames stored alongside
+// the handler. That way the same captured value can be called "id" on one
+// route and "username" on another without the tree caring.
+function matchSegments(
+  node: RadixNode,
+  segments: string[],
+  segmentIndex: number,
+  capturedValues: string[]
+): RouteMatch | null {
+  // Out of segments to walk. If this node has a handler, that's our match.
+  // Otherwise let a wildcard at this depth catch the empty remainder so
+  // routes like "/foo/*" still match a request to "/foo".
+  if (segmentIndex === segments.length) {
+    if (node.handler) {
+      return {
+        middleware: node.middleware!,
+        handler: node.handler,
+        params: zipParams(node.paramNames!, capturedValues)
+      };
+    }
+    if (node.wildcardChild) {
+      return {
+        middleware: node.wildcardChild.middleware,
+        handler: node.wildcardChild.handler,
+        params: zipParams(node.wildcardChild.paramNames, capturedValues)
+      };
+    }
+    return null;
+  }
+
+  const segment = segments[segmentIndex];
+
+  // Try the exact static child first. Exact matches always win.
+  const staticChild = node.staticChildren.get(segment);
+  if (staticChild) {
+    const foundMatch = matchSegments(
+      staticChild,
+      segments,
+      segmentIndex + 1,
+      capturedValues
+    );
+    if (foundMatch) return foundMatch;
+  }
+
+  // Then try the param branch. We push the captured value before recursing
+  // and pop it back off if the recursion fails, so any sibling branch (or the
+  // caller unwinding above us) sees a clean capture list.
+  if (node.paramChild) {
+    capturedValues.push(safeDecode(segment));
+    const foundMatch = matchSegments(
+      node.paramChild,
+      segments,
+      segmentIndex + 1,
+      capturedValues
+    );
+    if (foundMatch) return foundMatch;
+    capturedValues.pop();
+  }
+
+  // Last resort. A wildcard at this node swallows whatever segments remain.
+  if (node.wildcardChild) {
+    return {
+      middleware: node.wildcardChild.middleware,
+      handler: node.wildcardChild.handler,
+      params: zipParams(node.wildcardChild.paramNames, capturedValues)
+    };
+  }
+
+  return null;
+}
+
+function zipParams(names: string[], values: string[]): StringMap {
+  const params: StringMap = {};
+  for (let i = 0; i < names.length; i++) {
+    params[names[i]] = values[i];
+  }
+  return params;
+}
+
+// Decode a URL segment without ever throwing. Malformed percent encoding is
+// rare but it does happen in the wild. Falling back to the raw segment keeps
+// the request matchable instead of blowing up before the handler runs.
+// Example: safeDecode("a%20b%2Fc") returns "a b/c", while safeDecode("a%ZZb") returns "a%ZZb".
+function safeDecode(segment: string): string {
+  try {
+    return decodeURIComponent(segment);
+  } catch {
+    return segment;
+  }
+}
+
+// Split a URL path into segments with no leading slash. We treat "" and "/"
+// the same way: zero segments, meaning the root of the tree.
+// Example: "/a/b/c" becomes ["a", "b", "c"]
+function splitPath(path: string): string[] {
+  if (path === "" || path === "/") return [];
+  const withoutLeadingSlash = path.startsWith("/") ? path.slice(1) : path;
+  return withoutLeadingSlash.split("/");
+}

package/lib/internal/types.ts

@@ -0,0 +1,10 @@
+export interface CompressionOptions {
+  // Responses with a Content-Length below this many bytes are sent uncompressed.
+  // Below ~1KB, TCP/TLS framing overhead can outweigh the savings.
+  threshold?: number;
+  brotli?: import("node:zlib").BrotliOptions;
+  gzip?: import("node:zlib").ZlibOptions;
+  deflate?: import("node:zlib").ZlibOptions;
+}
+
+export type ResolvedCompressionConfig = Required<CompressionOptions>;

package/lib/types.ts

@@ -1,7 +1,22 @@
-import { IncomingMessage, ServerResponse } from "node:http";
+import { IncomingMessage, ServerResponse, type Server } from "node:http";
+import type { Readable } from "node:stream";
+import type { Buffer } from "node:buffer";
+import type { CompressionOptions } from "./internal/types";
+import type { CpeakIncomingMessage, CpeakServerResponse } from "./index";
 
 export type { Cpeak } from "./index";
 
+export type CpeakHttpServer = Server<
+  typeof CpeakIncomingMessage,
+  typeof CpeakServerResponse
+>;
+
+// For constructor options passed to `cpeak()`
+export interface CpeakOptions {
+  compression?: boolean | CompressionOptions;
+  mimeTypes?: StringMap;
+}
+
 // Extending Node.js's Request and Response objects to add our custom properties
 export type StringMap = Record<string, string>;
 
@@ -18,49 +33,45 @@ export interface CpeakRequest<
 }
 
 export interface CpeakResponse extends ServerResponse {
-  sendFile: (path: string, mime: string) => Promise<void>;
+  sendFile: (path: string, mime?: string) => Promise<void>;
   status: (code: number) => CpeakResponse;
   attachment: (filename?: string) => CpeakResponse;
   cookie: (name: string, value: string, options?: any) => CpeakResponse;
   redirect: (location: string) => void;
-  json: (data: any) => void;
+  json: (data: any) => Promise<void>;
+  compress: (
+    mime: string,
+    body: Buffer | string | Readable,
+    size?: number
+  ) => Promise<void>;
   [key: string]: any; // allow developers to add their onw extensions (e.g. res.test)
 }
 
 export type Next = (err?: any) => void;
-export type HandleErr = (err: any) => void;
 
 // beforeEach middleware: (req, res, next)
 export type Middleware<ReqBody = any, ReqParams = any> = (
   req: CpeakRequest<ReqBody, ReqParams>,
   res: CpeakResponse,
   next: Next
-) => void;
+) => unknown;
 
-// Route middleware:      (req, res, next, handleErr)
+// Route middleware: (req, res, next)
 export type RouteMiddleware<ReqBody = any, ReqParams = any> = (
   req: CpeakRequest<ReqBody, ReqParams>,
   res: CpeakResponse,
-  next: Next,
-  handleErr: HandleErr
-) => void | Promise<void>;
+  next: Next
+) => unknown;
 
-// Route handlers: (req, res, handleErr)
+// Route handlers: (req, res). To signal an error, throw it.
 export type Handler<ReqBody = any, ReqParams = any> = (
   req: CpeakRequest<ReqBody, ReqParams>,
-  res: CpeakResponse,
-  handleErr: HandleErr
-) => void | Promise<void>;
+  res: CpeakResponse
+) => unknown;
 
-// For a route object value in Cpeak.routes. The key is the method name.
+// Represents a single registered route.
 export interface Route {
   path: string;
-  regex: RegExp;
   middleware: RouteMiddleware[];
   cb: Handler;
 }
-
-// For Cpeak.routes:
-export interface RoutesMap {
-  [method: string]: Route[];
-}

package/lib/utils/auth.ts

@@ -2,6 +2,7 @@ import { randomBytes, pbkdf2, createHmac, timingSafeEqual } from "node:crypto";
 import { promisify } from "node:util";
 import type { Middleware } from "../types";
 import { frameworkError, ErrorCode } from "../index";
+import type { AuthOptions, PbkdfOptions } from "./types";
 
 const pbkdf2Async = promisify(pbkdf2);
 
@@ -15,29 +16,6 @@ const DEFAULTS = {
   tokenExpiry: 7 * 24 * 60 * 60 * 1000 // 7 days in ms
 } as const;
 
-export interface PbkdfOptions {
-  iterations?: number;
-  keylen?: number;
-  digest?: string;
-  saltSize?: number;
-}
-
-export interface AuthOptions extends PbkdfOptions {
-  secret: string;
-  saveToken: (
-    tokenId: string,
-    userId: string,
-    expiresAt: Date
-  ) => Promise<void>;
-  findToken: (
-    tokenId: string
-  ) => Promise<{ userId: string; expiresAt: Date } | null>;
-  tokenExpiry?: number;
-  hmacAlgorithm?: string;
-  tokenIdSize?: number;
-  revokeToken?: (tokenId: string) => Promise<void>;
-}
-
 export async function hashPassword(
   password: string,
   options?: PbkdfOptions

package/lib/utils/cookieParser.ts

@@ -1,17 +1,7 @@
 import { createHmac, timingSafeEqual } from "node:crypto";
 import type { CpeakRequest, CpeakResponse, Next } from "../types";
 import { frameworkError, ErrorCode } from "../index";
-
-export interface CookieOptions {
-  signed?: boolean;
-  httpOnly?: boolean;
-  secure?: boolean;
-  sameSite?: "strict" | "lax" | "none";
-  maxAge?: number; // ms
-  expires?: Date;
-  path?: string;
-  domain?: string;
-}
+import type { CookieOptions } from "./types";
 
 // This will sign the cookie value with HMAC with the secret.
 // Ideal for data like user IDs or session IDs, where you want to ensure the integrity of the cookie value without encryption.

package/lib/utils/cors.ts

@@ -0,0 +1,109 @@
+import type { CpeakRequest, CpeakResponse, Next } from "../types";
+import type { CorsOptions, OriginInput } from "./types";
+
+// Append a value to an existing header without overwriting prior entries
+// (e.g. compression already sets `Vary: Accept-Encoding`).
+function appendVary(res: CpeakResponse, value: string) {
+  const existing = res.getHeader("Vary");
+  if (!existing) return res.setHeader("Vary", value);
+  const current = String(existing)
+    .split(",")
+    .map((s) => s.trim())
+    .filter(Boolean);
+  if (current.includes("*") || current.includes(value)) return;
+  res.setHeader("Vary", [...current, value].join(", "));
+}
+
+// Determine if the given origin is allowed based on the rule.
+// Examples of what developers can specify for the rule:
+// - `true` or `*`: allow all origins
+// - `false`: disallow all origins
+// - `"https://example.com"`: allow only this origin
+// - `["https://example.com", "https://foo.com"]`: allow these origins
+// - `/\.example\.com$/`: allow origins that match this regex
+// - `(origin) => origin === "https://example.com"`: custom function to determine if the origin is allowed
+async function isAllowed(
+  origin: string | undefined,
+  rule: OriginInput
+): Promise<boolean> {
+  if (rule === true || rule === "*") return true;
+  if (rule === false || !origin) return false;
+  if (typeof rule === "string") return rule === origin;
+  if (Array.isArray(rule)) return rule.includes(origin);
+  if (rule instanceof RegExp) return rule.test(origin);
+  if (typeof rule === "function") return await rule(origin);
+  return false;
+}
+
+const cors = (options: CorsOptions = {}) => {
+  const {
+    origin = "*",
+    methods = "GET,HEAD,PUT,PATCH,POST,DELETE",
+    allowedHeaders,
+    exposedHeaders,
+    credentials = false,
+    maxAge = 86400,
+    preflightContinue = false,
+    optionsSuccessStatus = 204
+  } = options;
+
+  const methodsStr = Array.isArray(methods) ? methods.join(",") : methods;
+  const allowedHeadersStr = Array.isArray(allowedHeaders)
+    ? allowedHeaders.join(",")
+    : allowedHeaders;
+  const exposedHeadersStr = Array.isArray(exposedHeaders)
+    ? exposedHeaders.join(",")
+    : exposedHeaders;
+
+  return async (req: CpeakRequest, res: CpeakResponse, next: Next) => {
+    const requestOrigin = req.headers.origin;
+
+    // Not a CORS request, nothing to do.
+    if (!requestOrigin) return next();
+
+    const allowed = await isAllowed(requestOrigin, origin);
+    if (!allowed) return next();
+
+    // We cannot combine Access-Control-Allow-Origin: * with
+    // Access-Control-Allow-Credentials: true. Browsers will flat-out reject it.
+    // Instead we'll reflect the origin.
+    const allowOriginValue =
+      origin === "*" && !credentials ? "*" : requestOrigin;
+    res.setHeader("Access-Control-Allow-Origin", allowOriginValue);
+    if (allowOriginValue !== "*") appendVary(res, "Origin");
+
+    if (credentials) res.setHeader("Access-Control-Allow-Credentials", "true");
+    if (exposedHeadersStr)
+      res.setHeader("Access-Control-Expose-Headers", exposedHeadersStr);
+
+    const isPreflight =
+      req.method === "OPTIONS" &&
+      req.headers["access-control-request-method"] !== undefined;
+
+    if (!isPreflight) return next();
+
+    res.setHeader("Access-Control-Allow-Methods", methodsStr);
+
+    if (allowedHeadersStr) {
+      res.setHeader("Access-Control-Allow-Headers", allowedHeadersStr);
+    } else if (origin === "*") {
+      // If origin is *, just act like an echo chamber for requested headers. Give back whatever the browser asks for.
+      const requested = req.headers["access-control-request-headers"];
+      if (requested) res.setHeader("Access-Control-Allow-Headers", requested);
+    } else {
+      res.setHeader(
+        "Access-Control-Allow-Headers",
+        "Content-Type, Authorization"
+      );
+    }
+
+    res.setHeader("Access-Control-Max-Age", String(maxAge));
+
+    if (preflightContinue) return next();
+
+    res.statusCode = optionsSuccessStatus;
+    res.end();
+  };
+};
+
+export { cors };

package/lib/utils/index.ts

@@ -3,9 +3,8 @@ import { serveStatic } from "./serveStatic";
 import { render } from "./render";
 import { swagger } from "./swagger";
 import { auth, hashPassword, verifyPassword } from "./auth";
-import type { AuthOptions, PbkdfOptions } from "./auth";
 import { cookieParser } from "./cookieParser";
-import type { CookieOptions } from "./cookieParser";
+import { cors } from "./cors";
 
 export {
   serveStatic,
@@ -15,6 +14,6 @@ export {
   auth,
   hashPassword,
   verifyPassword,
-  cookieParser
+  cookieParser,
+  cors
 };
-export type { AuthOptions, PbkdfOptions, CookieOptions };

package/lib/utils/render.ts

@@ -1,5 +1,7 @@
 import fs from "node:fs/promises";
 import { frameworkError } from "../";
+import { compressAndSend } from "../internal/compression";
+import { MIME_TYPES } from "../internal/mimeTypes";
 import type { CpeakRequest, CpeakResponse, Next } from "../types";
 
 function renderTemplate(
@@ -58,18 +60,28 @@ const render = () => {
     res.render = async (
       path: string,
       data: Record<string, unknown>,
-      mime: string
+      mime?: string
     ) => {
-      // check if mime is specified, if not return an error
       if (!mime) {
-        throw frameworkError(
-          `MIME type is missing. You called res.render("${path}", ...) but forgot to provide the third "mime" argument.`,
-          res.render
-        );
+        const dotIndex = path.lastIndexOf(".");
+        const fileExtension = dotIndex >= 0 ? path.slice(dotIndex + 1) : "";
+        mime = MIME_TYPES[fileExtension];
+        if (!mime) {
+          throw frameworkError(
+            `MIME type is missing for "${path}". Pass it as the third argument or register the extension via cpeak({ mimeTypes: { ${fileExtension || "ext"}: "..." } }).`,
+            res.render
+          );
+        }
       }
 
       let fileStr = await fs.readFile(path, "utf-8");
       const finalStr = renderTemplate(fileStr, data);
+
+      if (res._compression) {
+        await compressAndSend(res, mime, finalStr, res._compression);
+        return;
+      }
+
       res.setHeader("Content-Type", mime);
       res.end(finalStr);
     };

package/lib/utils/serveStatic.ts

@@ -1,39 +1,40 @@
 import fs from "node:fs";
 import path from "node:path";
 
-import type { StringMap, CpeakRequest, CpeakResponse, Next } from "../types";
-
-const MIME_TYPES: StringMap = {
-  html: "text/html",
-  css: "text/css",
-  js: "application/javascript",
-  jpg: "image/jpeg",
-  jpeg: "image/jpeg",
-  png: "image/png",
-  svg: "image/svg+xml",
-  txt: "text/plain",
-  eot: "application/vnd.ms-fontobject",
-  otf: "font/otf",
-  ttf: "font/ttf",
-  woff: "font/woff",
-  woff2: "font/woff2",
-  gif: "image/gif",
-  ico: "image/x-icon",
-  json: "application/json",
-  webmanifest: "application/manifest+json"
-};
+import { MIME_TYPES } from "../internal/mimeTypes";
+import type { CpeakRequest, CpeakResponse, Next } from "../types";
 
 const serveStatic = (
   folderPath: string,
-  newMimeTypes?: StringMap,
-  options?: { prefix?: string }
+  options?: { prefix?: string; live?: boolean }
 ) => {
-  // For new user defined mime types
-  if (newMimeTypes) {
-    Object.assign(MIME_TYPES, newMimeTypes);
-  }
-
   const prefix = options?.prefix ?? "";
+  const live = options?.live ?? false;
+
+  // This process the folder on every request, which is useful during development when files are changing often.
+  // In production, it's better to process the folder once and store the file paths in memory for faster access if file names are not changing often.
+  // If file names dynamically change often in production, then live option can be set to true to process the folder on every request, but it may have performance implications.
+  if (live) {
+    const resolvedFolder = path.resolve(folderPath);
+
+    return async function (req: CpeakRequest, res: CpeakResponse, next: Next) {
+      const url = req.url;
+      if (typeof url !== "string") return next();
+
+      const pathname = url.split("?")[0];
+      const unprefixed = prefix ? pathname.slice(prefix.length) : pathname;
+      const filePath = path.join(resolvedFolder, unprefixed);
+      const fileExtension = path.extname(filePath).slice(1);
+      const mime = MIME_TYPES[fileExtension];
+
+      if (!mime || !filePath.startsWith(resolvedFolder)) return next();
+
+      const stat = await fs.promises.stat(filePath).catch(() => null);
+      if (stat?.isFile()) return res.sendFile(filePath, mime);
+
+      next();
+    };
+  }
 
   function processFolder(folderPath: string, parentFolder: string) {
     const staticFiles: string[] = [];