cpeak 2.7.0 → 2.9.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/types.ts

@@ -1,13 +1,21 @@
-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 { CookieOptions } from "./utils/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
@@ -25,55 +33,51 @@ export interface CpeakRequest<
   [key: string]: any; // allow developers to add their onw extensions (e.g. req.test)
 }
 
-export interface CpeakResponse extends ServerResponse {
-  sendFile: (path: string, mime: string) => Promise<void>;
-  status: (code: number) => CpeakResponse;
-  attachment: (filename?: string) => CpeakResponse;
-  cookie: (name: string, value: string, options?: any) => CpeakResponse;
+export interface CpeakResponse<ResBody = any> extends ServerResponse {
+  sendFile: (path: string, mime?: string) => Promise<void>;
+  status: (code: number) => CpeakResponse<ResBody>;
+  attachment: (filename?: string) => CpeakResponse<ResBody>;
+  cookie: (name: string, value: string, options?: CookieOptions) => CpeakResponse<ResBody>;
   redirect: (location: string) => void;
-  json: (data: any) => void | Promise<void>; // sync when compression is off, async when enabled
+  json: (data: ResBody) => Promise<void>;
   compress: (
     mime: string,
     body: Buffer | string | Readable,
     size?: number
   ) => Promise<void>;
+  render: (
+    filePath: string,
+    data: Record<string, unknown>,
+    mime?: string
+  ) => 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)
-export type Handler<ReqBody = any, ReqParams = any> = (
+// Route handlers: (req, res)
+export type Handler<ReqBody = any, ReqParams = any, ResBody = any> = (
   req: CpeakRequest<ReqBody, ReqParams>,
-  res: CpeakResponse,
-  handleErr: HandleErr
-) => void | Promise<void>;
+  res: CpeakResponse<ResBody>
+) => 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/render.ts

@@ -1,84 +1,167 @@
-import fs from "node:fs/promises";
-import { frameworkError } from "../";
+import path from "node:path";
+import { createReadStream } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { Transform } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import type { TransformCallback } from "node:stream";
+import { frameworkError, ErrorCode } from "../";
+import { isClientDisconnect } from "../internal/errors";
 import { compressAndSend } from "../internal/compression";
+import { MIME_TYPES } from "../internal/mimeTypes";
 import type { CpeakRequest, CpeakResponse, Next } from "../types";
 
-function renderTemplate(
-  templateStr: string,
-  data: Record<string, unknown>
-): string {
-  // Initialize variables
-  let result: (string | unknown)[] = [];
-
-  let currentIndex = 0;
-
-  while (currentIndex < templateStr.length) {
-    // Find the next opening placeholder
-    const startIdx = templateStr.indexOf("{{", currentIndex);
-    if (startIdx === -1) {
-      // No more placeholders, push the remaining string
-      result.push(templateStr.slice(currentIndex));
-      break;
-    }
+export const MAX_PATTERN = 128;
 
-    // Push the part before the placeholder
-    result.push(templateStr.slice(currentIndex, startIdx));
+function escapeHtml(value: string): string {
+  return value
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&#39;");
+}
 
-    // Find the closing placeholder
-    const endIdx = templateStr.indexOf("}}", startIdx);
-    if (endIdx === -1) {
-      // No closing brace found, treat the rest as plain text
-      result.push(templateStr.slice(startIdx));
-      break;
-    }
+class TemplateTransform extends Transform {
+  private tail = "";
 
-    // Extract the variable name
-    const varName = templateStr.slice(startIdx + 2, endIdx).trim();
+  constructor(
+    private readonly data: Record<string, unknown>,
+    private readonly baseDir: string
+  ) {
+    super();
+  }
+
+  _transform(
+    chunk: Buffer,
+    _: BufferEncoding,
+    callback: TransformCallback
+  ): void {
+    const str = this.tail + chunk.toString("utf8");
+    if (str.length <= MAX_PATTERN) {
+      this.tail = str;
+      callback();
+      return;
+    }
 
-    // Replace the variable with its value from the data, or use an empty string if not found
-    const replacement = data[varName] !== undefined ? data[varName] : "";
+    let boundary = str.length - MAX_PATTERN;
+
+    // Prevent cutting a tag in two
+    for (const [opener, closer] of [
+      ["{{", "}}"],
+      ["<cpeak", ">"]
+    ]) {
+      const last = str.lastIndexOf(opener, boundary - 1);
+      if (last === -1) continue;
+      const closeIdx = str.indexOf(closer, last + opener.length);
+      if (closeIdx === -1 || closeIdx >= boundary)
+        boundary = Math.min(boundary, last);
+    }
 
-    // Push the replacement to the result array
-    result.push(replacement);
+    this.tail = str.slice(boundary);
+    const safe = str.slice(0, boundary);
+    if (safe)
+      this.process(safe)
+        .then(() => callback())
+        .catch(callback);
+    else callback();
+  }
 
-    // Move the index past the current closing placeholder
-    currentIndex = endIdx + 2;
+  _flush(callback: TransformCallback): void {
+    if (this.tail)
+      this.process(this.tail)
+        .then(() => callback())
+        .catch(callback);
+    else callback();
   }
 
-  // Join all parts into a final string
-  return result.join("");
+  private async process(str: string): Promise<void> {
+    const RE =
+      /<cpeak\s+include="([^"]+)"\s*\/?>|<cpeak\s+html=\{([^}]+)\}\s*\/?>|\{\{([^}]+)\}\}/g;
+    let last = 0;
+
+    for (const match of str.matchAll(RE)) {
+      const idx = match.index!;
+      if (idx > last) this.push(str.slice(last, idx));
+
+      const [, includeSrc, rawKey, escapedKey] = match;
+
+      if (includeSrc !== undefined) {
+        const includePath = path.resolve(this.baseDir, includeSrc);
+        const content = await readFile(includePath, "utf8");
+        const chunks: Buffer[] = [];
+        const nested = new TemplateTransform(
+          this.data,
+          path.dirname(includePath)
+        );
+        await new Promise<void>((resolve, reject) => {
+          nested.on("data", (c: Buffer) => chunks.push(c));
+          nested.on("end", resolve);
+          nested.on("error", reject);
+          nested.end(Buffer.from(content, "utf8"));
+        });
+        this.push(Buffer.concat(chunks));
+      } else if (rawKey !== undefined) {
+        const val = this.data[rawKey.trim()];
+        if (val !== undefined) this.push(String(val));
+      } else {
+        const val = this.data[escapedKey.trim()];
+        if (val !== undefined) this.push(escapeHtml(String(val)));
+      }
+
+      last = idx + match[0].length;
+    }
+
+    if (last < str.length) this.push(str.slice(last));
+  }
 }
 
-// Errors to return: recommend to not render files larger than 100KB
-// To Explore: Doing the operation in C++ and return the data as stream back to the client
-// @TODO: remove the file from static map
-// @TODO: escape the string to prevent XSS
-// @TODO: add another {{{ }}} option to not escape the string
 const render = () => {
   return function (req: CpeakRequest, res: CpeakResponse, next: Next): void {
     res.render = async (
-      path: string,
+      filePath: string,
       data: Record<string, unknown>,
-      mime: string
+      mime?: string
     ) => {
-      // check if mime is specified, if not return an error
+      if (res.headersSent) return;
       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 = filePath.lastIndexOf(".");
+        const fileExtension = dotIndex >= 0 ? filePath.slice(dotIndex + 1) : "";
+        mime = MIME_TYPES[fileExtension];
+        if (!mime) {
+          throw frameworkError(
+            `MIME type is missing for "${filePath}". Pass it as the third argument or register the extension via cpeak({ mimeTypes: { ${fileExtension || "ext"}: "..." } }).`,
+            res.render,
+            ErrorCode.MISSING_MIME
+          );
+        }
       }
 
-      let fileStr = await fs.readFile(path, "utf-8");
-      const finalStr = renderTemplate(fileStr, data);
-
-      if (res._compression) {
-        await compressAndSend(res, mime, finalStr, res._compression);
-        return;
+      const resolved = path.resolve(filePath);
+
+      try {
+        if (res._compression) {
+          const readStream = createReadStream(resolved);
+          const transform = new TemplateTransform(data, path.dirname(resolved));
+          pipeline(readStream, transform).catch(() => {});
+          await compressAndSend(res, mime, transform, res._compression);
+          return;
+        }
+
+        res.setHeader("Content-Type", mime);
+        await pipeline(
+          createReadStream(resolved),
+          new TemplateTransform(data, path.dirname(resolved)),
+          res
+        );
+      } catch (err: any) {
+        throw frameworkError(
+          `Failed to render "${filePath}." Error: ${err as Error}`,
+          res.render,
+          ErrorCode.RENDER_FAIL,
+          undefined,
+          isClientDisconnect(err)
+        );
       }
-
-      res.setHeader("Content-Type", mime);
-      res.end(finalStr);
     };
 
     next();

package/lib/utils/serveStatic.ts

@@ -1,39 +1,45 @@
 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; exclude?: string[] }
 ) => {
-  // 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);
+    const excludes = (options?.exclude ?? []).map(e => path.join(resolvedFolder, e));
+
+    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();
+      if (excludes.some(e => filePath.startsWith(e))) return next();
+
+      const stat = await fs.promises.stat(filePath).catch(() => null);
+      if (stat?.isFile()) return res.sendFile(filePath, mime);
+
+      next();
+    };
   }
 
-  const prefix = options?.prefix ?? "";
+  const resolvedFolder = path.resolve(folderPath);
+  const excludes = (options?.exclude ?? []).map(e => path.join(resolvedFolder, e));
 
   function processFolder(folderPath: string, parentFolder: string) {
     const staticFiles: string[] = [];
@@ -47,10 +53,12 @@ const serveStatic = (
 
       // Check if it's a directory
       if (fs.statSync(fullPath).isDirectory()) {
+        if (excludes.some(e => fullPath.startsWith(e))) continue;
         // If it's a directory, recursively process it
         const subfolderFiles = processFolder(fullPath, parentFolder);
         staticFiles.push(...subfolderFiles);
       } else {
+        if (excludes.some(e => fullPath.startsWith(e))) continue;
         // If it's a file, add it to the array
         const relativePath = path.relative(parentFolder, fullPath);
         const fileExtension = path.extname(file).slice(1);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cpeak",
-  "version": "2.7.0",
+  "version": "2.9.0",
   "description": "A minimal and fast Node.js HTTP framework.",
   "type": "module",
   "scripts": {