cpeak 2.7.0 → 2.8.0

package/lib/index.ts

@@ -2,6 +2,8 @@ import http from "node:http";
 import fs from "node:fs/promises";
 import { createReadStream } from "node:fs";
 import { pipeline } from "node:stream/promises";
+
+import type net from "node:net";
 import type { Readable } from "node:stream";
 import type { Buffer } from "node:buffer";
 
@@ -9,52 +11,25 @@ import {
   resolveCompressionOptions,
   compressAndSend
 } from "./internal/compression";
+import { MIME_TYPES } from "./internal/mimeTypes";
+import { Router } from "./internal/router";
+import { frameworkError, ErrorCode } from "./internal/errors";
+
+export { frameworkError, ErrorCode };
 
 import type {
   StringMap,
+  CpeakHttpServer,
   CpeakOptions,
   CpeakRequest,
   CpeakResponse,
   Middleware,
   RouteMiddleware,
-  Handler,
-  RoutesMap
+  Handler
 } from "./types";
 
 import type { ResolvedCompressionConfig } from "./internal/types";
 
-// A utility function to create an error with a custom stack trace
-export function frameworkError(
-  message: string,
-  skipFn: Function,
-  code?: string,
-  status?: number
-) {
-  const err = new Error(message) as Error & {
-    code?: string;
-    cpeak_err?: boolean;
-  };
-  Error.captureStackTrace(err, skipFn);
-
-  err.cpeak_err = true;
-
-  if (code) err.code = code;
-  if (status) (err as any).status = status;
-
-  return err;
-}
-
-export enum ErrorCode {
-  MISSING_MIME = "CPEAK_ERR_MISSING_MIME",
-  FILE_NOT_FOUND = "CPEAK_ERR_FILE_NOT_FOUND",
-  NOT_A_FILE = "CPEAK_ERR_NOT_A_FILE",
-  SEND_FILE_FAIL = "CPEAK_ERR_SEND_FILE_FAIL",
-  INVALID_JSON = "CPEAK_ERR_INVALID_JSON",
-  PAYLOAD_TOO_LARGE = "CPEAK_ERR_PAYLOAD_TOO_LARGE",
-  WEAK_SECRET = "CPEAK_ERR_WEAK_SECRET",
-  COMPRESSION_NOT_ENABLED = "CPEAK_ERR_COMPRESSION_NOT_ENABLED"
-}
-
 export class CpeakIncomingMessage extends http.IncomingMessage {
   // We define body and params here for better V8 optimization (not changing the shape of the object at runtime)
   public body: any = undefined;
@@ -88,13 +63,18 @@ export class CpeakServerResponse extends http.ServerResponse<CpeakIncomingMessag
   _compression?: ResolvedCompressionConfig;
 
   // Send a file back to the client
-  async sendFile(path: string, mime: string) {
+  async sendFile(path: string, mime?: string) {
     if (!mime) {
-      throw frameworkError(
-        'MIME type is missing. Use res.sendFile(path, "mime-type").',
-        this.sendFile,
-        ErrorCode.MISSING_MIME
-      );
+      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 second argument or register the extension via cpeak({ mimeTypes: { ${fileExtension || "ext"}: "..." } }).`,
+          this.sendFile,
+          ErrorCode.MISSING_MIME
+        );
+      }
     }
 
     try {
@@ -163,14 +143,14 @@ export class CpeakServerResponse extends http.ServerResponse<CpeakIncomingMessag
 
   // Send a json data back to the client.
   // This is only good for bodies that their size is less than the highWaterMark value.
-  // Branches into compressAndSend (async) when compression was enabled at cpeak() construction.
-  json(data: any): void | Promise<void> {
+  json(data: any): Promise<void> {
     const body = JSON.stringify(data);
     if (this._compression) {
       return compressAndSend(this, "application/json", body, this._compression);
     }
     this.setHeader("Content-Type", "application/json");
     this.end(body);
+    return Promise.resolve();
   }
 
   // Explicit compression entry point. A developer can use this in any custom handler to compress arbitrary responses
@@ -191,10 +171,11 @@ export class CpeakServerResponse extends http.ServerResponse<CpeakIncomingMessag
 }
 
 export class Cpeak {
-  #server: http.Server<typeof CpeakIncomingMessage, typeof CpeakServerResponse>;
-  #routes: RoutesMap;
+  #server: CpeakHttpServer;
+  #router: Router;
   #middleware: Middleware[];
   #handleErr?: (err: unknown, req: CpeakRequest, res: CpeakResponse) => void;
+  #fallback?: Handler;
   #compression?: ResolvedCompressionConfig;
 
   constructor(options: CpeakOptions = {}) {
@@ -202,7 +183,7 @@ export class Cpeak {
       IncomingMessage: CpeakIncomingMessage,
       ServerResponse: CpeakServerResponse
     });
-    this.#routes = {};
+    this.#router = new Router();
     this.#middleware = [];
 
     // Resolve compression options once at app startup.
@@ -210,6 +191,9 @@ export class Cpeak {
       this.#compression = resolveCompressionOptions(options.compression);
     }
 
+    // Merge developer-supplied mime types with the defaults once at startup
+    if (options.mimeTypes) Object.assign(MIME_TYPES, options.mimeTypes);
+
     this.#server.on(
       "request",
       async (req: CpeakRequest, res: CpeakResponse) => {
@@ -220,13 +204,33 @@ export class Cpeak {
         const urlWithoutQueries =
           qIndex === -1 ? req.url || "" : req.url?.substring(0, qIndex);
 
-        const dispatchError = (error: unknown) => {
+        // Routes every error path through the registered handleErr. Awaits
+        // handleErr so its own async work (or a rejecting res.json under
+        // compression) is caught. If handleErr itself fails, we log and send a
+        // bare 500 so the client never gets a hung socket. Returns a Promise
+        // that never rejects to avoid unhandled promise rejections in case of errors in handleErr.
+        const dispatchError = async (error: unknown) => {
           if (res.headersSent) {
             req.socket?.destroy();
             return;
           }
           res.setHeader("Connection", "close");
-          this.#handleErr?.(error, req, res);
+          try {
+            await this.#handleErr?.(error, req, res);
+          } catch (handlerFailure) {
+            console.error(
+              "[cpeak] handleErr failed while processing:",
+              error,
+              "\nReason:",
+              handlerFailure
+            );
+            if (!res.headersSent) {
+              try {
+                res.statusCode = 500;
+                res.end();
+              } catch {}
+            }
+          }
         };
 
         // Run all the specific middleware functions for that router only and then run the handler
@@ -240,29 +244,22 @@ export class Cpeak {
           // Our exit point...
           if (index === middleware.length) {
             // Call the route handler with the modified req and res objects.
-            // Also handle the promise errors by passing them to the handleErr to save developers from having to manually wrap every handler in try catch.
+            // Also handle the promise errors by passing them to handleErr to save developers from having to manually wrap every handler in try/catch.
             try {
-              await cb(req, res, dispatchError);
+              await cb(req, res);
             } catch (error) {
               dispatchError(error);
             }
           } else {
-            // Handle the promise errors by passing them to the handleErr to save developers from having to manually wrap every handler middleware in try catch.
+            // Handle the promise errors by passing them to handleErr to save developers from having to manually wrap every route middleware in try/catch.
             try {
-              await middleware[index](
-                req,
-                res,
-                // The next function
-                async (error) => {
-                  // this function only accepts an error argument to be more compatible with NPM modules that are built for express
-                  if (error) {
-                    return dispatchError(error);
-                  }
-                  await runHandler(req, res, middleware, cb, index + 1);
-                },
-                // Error handler for a route middleware
-                dispatchError
-              );
+              await middleware[index](req, res, async (error?: unknown) => {
+                // this function only accepts an error argument to be more compatible with NPM modules that are built for express
+                if (error) {
+                  return dispatchError(error);
+                }
+                await runHandler(req, res, middleware, cb, index + 1);
+              });
             } catch (error) {
               dispatchError(error);
             }
@@ -278,32 +275,30 @@ export class Cpeak {
         ) => {
           // Our exit point...
           if (index === middleware.length) {
-            const routes = this.#routes[req.method?.toLowerCase() || ""];
-            if (routes && typeof routes[Symbol.iterator] === "function")
-              for (const route of routes) {
-                const match = urlWithoutQueries?.match(route.regex);
-
-                if (match) {
-                  // Parse the URL path variables from the matched route (like /users/:id)
-                  const pathVariables = this.#extractPathVariables(
-                    route.path,
-                    match
-                  );
-
-                  // We will call this params to be more familiar with other node.js frameworks.
-                  req.params = pathVariables;
-
-                  return await runHandler(
-                    req,
-                    res,
-                    route.middleware,
-                    route.cb,
-                    0
-                  );
-                }
+            const method = req.method?.toLowerCase() || "";
+            const found = this.#router.find(method, urlWithoutQueries || "");
+
+            if (found) {
+              req.params = found.params;
+              return await runHandler(
+                req,
+                res,
+                found.middleware,
+                found.handler,
+                0
+              );
+            }
+
+            // If a fallback handler is registered, run it before falling back to the default 404
+            if (this.#fallback) {
+              try {
+                return await this.#fallback(req, res);
+              } catch (error) {
+                return dispatchError(error);
               }
+            }
 
-            // If the requested route dose not exist, return 404
+            // If the requested route dose not exist, and developer has not registered the fallback handler, return 404
             return res
               .status(404)
               .json({ error: `Cannot ${req.method} ${urlWithoutQueries}` });
@@ -327,8 +322,6 @@ export class Cpeak {
   }
 
   route(method: string, path: string, ...args: (RouteMiddleware | Handler)[]) {
-    if (!this.#routes[method]) this.#routes[method] = [];
-
     // The last argument should always be our handler
     const cb = args.pop() as Handler;
 
@@ -339,8 +332,7 @@ export class Cpeak {
     // Rest will be our middleware functions
     const middleware = args.flat() as RouteMiddleware[];
 
-    const regex = this.#pathToRegex(path);
-    this.#routes[method].push({ path, regex, middleware, cb });
+    this.#router.add(method, path, middleware, cb);
   }
 
   beforeEach(cb: Middleware) {
@@ -351,8 +343,24 @@ export class Cpeak {
     this.#handleErr = cb;
   }
 
-  listen(port: number, cb?: () => void) {
-    return this.#server.listen(port, cb);
+  // This will handle any request that doesn't match any of the routes and middleware functions
+  fallback(cb: Handler) {
+    if (this.#fallback) {
+      throw frameworkError(
+        "Fallback handler is already registered. Only one fallback can be set per app.",
+        this.fallback,
+        ErrorCode.DUPLICATE_FALLBACK
+      );
+    }
+    this.#fallback = cb;
+  }
+
+  // The first 3 listens are just TS overloads for better type inference and editor autocompletion. The last one is the actual implementation.
+  listen(port: number, cb?: () => void): CpeakHttpServer;
+  listen(port: number, host: string, cb?: () => void): CpeakHttpServer;
+  listen(options: net.ListenOptions, cb?: () => void): CpeakHttpServer;
+  listen(...args: any[]) {
+    return this.#server.listen(...args);
   }
 
   address() {
@@ -360,29 +368,12 @@ export class Cpeak {
   }
 
   close(cb?: (err?: Error) => void) {
-    this.#server.close(cb);
+    return this.#server.close(cb);
   }
 
-  // ------------------------------
-  // PRIVATE METHODS:
-  // ------------------------------
-  #pathToRegex(path: string) {
-    const regexString =
-      "^" + path.replace(/:\w+/g, "([^/]+)").replace(/\*/g, ".*") + "$";
-
-    return new RegExp(regexString);
-  }
-
-  #extractPathVariables(path: string, match: RegExpMatchArray) {
-    // Extract path url variable values from the matched route
-    const paramNames = (path.match(/:\w+/g) || []).map((param) =>
-      param.slice(1)
-    );
-    const params: StringMap = {};
-    paramNames.forEach((name, index) => {
-      params[name] = match[index + 1];
-    });
-    return params;
+  // A getter for developers who want to access the underlying http server instance for advanced use cases that aren't covered by Cpeak
+  get server() {
+    return this.#server;
   }
 }
 
@@ -409,15 +400,14 @@ export type {
 export type { CompressionOptions } from "./internal/types";
 
 export type {
+  CpeakHttpServer,
   CpeakOptions,
   CpeakRequest,
   CpeakResponse,
   Next,
-  HandleErr,
   Middleware,
   RouteMiddleware,
-  Handler,
-  RoutesMap
+  Handler
 } from "./types";
 
 export default function cpeak(options?: CpeakOptions): Cpeak {

package/lib/internal/errors.ts

@@ -0,0 +1,35 @@
+// A utility function to create an error with a custom stack trace
+export function frameworkError(
+  message: string,
+  skipFn: Function,
+  code?: string,
+  status?: number
+) {
+  const err = new Error(message) as Error & {
+    code?: string;
+    cpeak_err?: boolean;
+  };
+  Error.captureStackTrace(err, skipFn);
+
+  err.cpeak_err = true;
+
+  if (code) err.code = code;
+  if (status) (err as any).status = status;
+
+  return err;
+}
+
+export enum ErrorCode {
+  MISSING_MIME = "CPEAK_ERR_MISSING_MIME",
+  FILE_NOT_FOUND = "CPEAK_ERR_FILE_NOT_FOUND",
+  NOT_A_FILE = "CPEAK_ERR_NOT_A_FILE",
+  SEND_FILE_FAIL = "CPEAK_ERR_SEND_FILE_FAIL",
+  INVALID_JSON = "CPEAK_ERR_INVALID_JSON",
+  PAYLOAD_TOO_LARGE = "CPEAK_ERR_PAYLOAD_TOO_LARGE",
+  WEAK_SECRET = "CPEAK_ERR_WEAK_SECRET",
+  COMPRESSION_NOT_ENABLED = "CPEAK_ERR_COMPRESSION_NOT_ENABLED",
+  // For router:
+  DUPLICATE_ROUTE = "CPEAK_ERR_DUPLICATE_ROUTE",
+  INVALID_ROUTE = "CPEAK_ERR_INVALID_ROUTE",
+  DUPLICATE_FALLBACK = "CPEAK_ERR_DUPLICATE_FALLBACK"
+}

package/lib/internal/mimeTypes.ts

@@ -0,0 +1,22 @@
+import type { StringMap } from "../types";
+
+// Developers can expand this if needed in the cpeak() constructor
+export 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"
+};

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("/");
+}