cpeak 2.6.0 → 2.8.0

package/lib/index.ts

@@ -3,46 +3,32 @@ 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";
+
+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";
 
-// 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"
-}
+import type { ResolvedCompressionConfig } from "./internal/types";
 
 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)
@@ -73,14 +59,22 @@ export class CpeakIncomingMessage extends http.IncomingMessage {
 }
 
 export class CpeakServerResponse extends http.ServerResponse<CpeakIncomingMessage> {
+  // Set per-request from the Cpeak instance. Undefined when compression isn't enabled.
+  _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 {
@@ -93,6 +87,17 @@ export class CpeakServerResponse extends http.ServerResponse<CpeakIncomingMessag
         );
       }
 
+      if (this._compression) {
+        await compressAndSend(
+          this,
+          mime,
+          createReadStream(path),
+          this._compression,
+          stat.size
+        );
+        return;
+      }
+
       this.setHeader("Content-Type", mime);
       this.setHeader("Content-Length", String(stat.size));
 
@@ -136,43 +141,96 @@ export class CpeakServerResponse extends http.ServerResponse<CpeakIncomingMessag
     this.end();
   }
 
-  // Send a json data back to the client (for small json data, less than the highWaterMark)
-  json(data: any) {
-    // This is only good for bodies that their size is less than the highWaterMark value
+  // Send a json data back to the client.
+  // This is only good for bodies that their size is less than the highWaterMark value.
+  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(JSON.stringify(data));
+    this.end(body);
+    return Promise.resolve();
+  }
+
+  // Explicit compression entry point. A developer can use this in any custom handler to compress arbitrary responses
+  compress(
+    mime: string,
+    body: Buffer | string | Readable,
+    size?: number
+  ): Promise<void> {
+    if (!this._compression) {
+      throw frameworkError(
+        "compression is not enabled. Pass `compression` to cpeak({ compression: true | { ... } }) to use res.compress.",
+        this.compress,
+        ErrorCode.COMPRESSION_NOT_ENABLED
+      );
+    }
+    return compressAndSend(this, mime, body, this._compression, size);
   }
 }
 
 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() {
+  constructor(options: CpeakOptions = {}) {
     this.#server = http.createServer({
       IncomingMessage: CpeakIncomingMessage,
       ServerResponse: CpeakServerResponse
     });
-    this.#routes = {};
+    this.#router = new Router();
     this.#middleware = [];
 
+    // Resolve compression options once at app startup.
+    if (options.compression) {
+      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) => {
+        res._compression = this.#compression;
+
         // Get the url without the URL parameters (query strings)
         const qIndex = req.url?.indexOf("?");
         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
@@ -186,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);
             }
@@ -224,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}` });
@@ -273,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;
 
@@ -285,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) {
@@ -297,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() {
@@ -306,29 +368,12 @@ export class Cpeak {
   }
 
   close(cb?: (err?: Error) => void) {
-    this.#server.close(cb);
-  }
-
-  // ------------------------------
-  // PRIVATE METHODS:
-  // ------------------------------
-  #pathToRegex(path: string) {
-    const regexString =
-      "^" + path.replace(/:\w+/g, "([^/]+)").replace(/\*/g, ".*") + "$";
-
-    return new RegExp(regexString);
+    return this.#server.close(cb);
   }
 
-  #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;
   }
 }
 
@@ -341,21 +386,30 @@ export {
   auth,
   hashPassword,
   verifyPassword,
-  cookieParser
+  cookieParser,
+  cors
 } from "./utils";
-export type { AuthOptions, PbkdfOptions, CookieOptions } from "./utils";
 
 export type {
+  AuthOptions,
+  PbkdfOptions,
+  CookieOptions,
+  CorsOptions
+} from "./utils/types";
+
+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(): Cpeak {
-  return new Cpeak();
+export default function cpeak(options?: CpeakOptions): Cpeak {
+  return new Cpeak(options);
 }

package/lib/internal/compression.ts

@@ -0,0 +1,180 @@
+import zlib from "node:zlib";
+import { Readable } from "node:stream";
+import { Buffer } from "node:buffer";
+import { pipeline } from "node:stream/promises";
+import type { Transform } from "node:stream";
+import type { ServerResponse } from "node:http";
+import type { CompressionOptions, ResolvedCompressionConfig } from "./types";
+
+type Encoding = "br" | "gzip" | "deflate";
+
+const COMPRESSIBLE_TYPE = /text|json|javascript|css|xml|svg/i;
+const NO_TRANSFORM = /(?:^|,)\s*no-transform\s*(?:,|$)/i;
+
+// Parse Accept-Encoding and pick a compression algorithm the server supports.
+// Handles q=0 to disable an algorithm. Cpeak preference is fixed: br > gzip > deflate.
+function pickEncoding(header: string): Encoding | null {
+  if (!header) return null;
+
+  const accepted: Record<string, number> = {};
+  let wildcard: number | undefined;
+
+  for (const part of header.split(",")) {
+    const [rawName, ...params] = part.trim().split(";");
+    const name = rawName.trim().toLowerCase();
+    if (!name) continue;
+
+    let q = 1;
+    for (const p of params) {
+      const m = p.trim().match(/^q=([\d.]+)$/i);
+      if (m) q = Number(m[1]);
+    }
+    if (Number.isNaN(q)) q = 0;
+
+    if (name === "*") wildcard = q;
+    else accepted[name] = q;
+  }
+
+  const tryPick = (enc: Encoding): boolean => {
+    const q = enc in accepted ? accepted[enc] : wildcard;
+    return q !== undefined && q > 0;
+  };
+
+  if (tryPick("br")) return "br";
+  if (tryPick("gzip")) return "gzip";
+  if (tryPick("deflate")) return "deflate";
+  return null;
+}
+
+// Handling the Vary HTTP header
+function appendVary(res: ServerResponse, 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.some((v) => v.toLowerCase() === value.toLowerCase())
+  )
+    return;
+  res.setHeader("Vary", [...current, value].join(", "));
+}
+
+// Brotli options. Zlib uses 11 (max), which is really slow for live
+// responses. We go with 4 unless the developer specifies otherwise.
+function brotliOptsFor(config: ResolvedCompressionConfig): zlib.BrotliOptions {
+  const userBrotli = config.brotli || {};
+  return {
+    ...userBrotli,
+    params: {
+      [zlib.constants.BROTLI_PARAM_QUALITY]: 4,
+      ...(userBrotli.params || {})
+    }
+  };
+}
+
+function createCompressorStream(
+  encoding: Encoding,
+  config: ResolvedCompressionConfig
+): Transform {
+  if (encoding === "br")
+    return zlib.createBrotliCompress(brotliOptsFor(config));
+  if (encoding === "gzip") return zlib.createGzip(config.gzip);
+  return zlib.createDeflate(config.deflate);
+}
+
+// Decides what to do with this response
+function negotiate(
+  res: ServerResponse,
+  mime: string,
+  size: number,
+  config: ResolvedCompressionConfig
+): { encoding: Encoding | null; eligible: boolean } {
+  // Whether this content type is worth trying to compress at all.
+  // Some types are already compressed and don't compress well.
+  if (!COMPRESSIBLE_TYPE.test(mime)) return { encoding: null, eligible: false };
+
+  if (res.req?.method === "HEAD") return { encoding: null, eligible: false };
+
+  // RFC specification: don't transform responses that ask not to be transformed.
+  const cc = res.getHeader("Cache-Control");
+  if (cc && NO_TRANSFORM.test(String(cc)))
+    return { encoding: null, eligible: false };
+
+  const existing = res.getHeader("Content-Encoding");
+  if (existing && existing !== "identity")
+    return { encoding: null, eligible: false };
+
+  if (size < config.threshold) return { encoding: null, eligible: true };
+
+  const encoding = pickEncoding(
+    String(res.req?.headers["accept-encoding"] || "")
+  );
+  return { encoding, eligible: true };
+}
+
+// Converts into a Readable stream
+function bodyAsReadable(body: Buffer | string | Readable): Readable {
+  if (Buffer.isBuffer(body)) return Readable.from([body]);
+  if (typeof body === "string") return Readable.from([Buffer.from(body)]);
+  return body;
+}
+
+// Resolves compression options (or 'true' for defaults) into a
+// complete config. Called once at Cpeak construction.
+export function resolveCompressionOptions(
+  input: true | CompressionOptions
+): ResolvedCompressionConfig {
+  const options: CompressionOptions = input === true ? {} : input;
+  return {
+    threshold: options.threshold ?? 1024,
+    brotli: options.brotli ?? {},
+    gzip: options.gzip ?? {},
+    deflate: options.deflate ?? {}
+  };
+}
+
+// The final point used by res.compress, res.json, res.sendFile and res.render
+// when compression is enabled by the developer.
+//
+// Compression always goes through createGzip/createBrotliCompress/createDeflate
+// streams which are async and run on libuv's thread pool.
+export async function compressAndSend(
+  res: ServerResponse,
+  mime: string,
+  body: Buffer | string | Readable,
+  config: ResolvedCompressionConfig,
+  size?: number
+): Promise<void> {
+  res.setHeader("Content-Type", mime);
+
+  const knownSize: number = Buffer.isBuffer(body)
+    ? body.length
+    : typeof body === "string"
+      ? Buffer.byteLength(body)
+      : (size ?? Infinity);
+
+  const { encoding, eligible } = negotiate(res, mime, knownSize, config);
+
+  if (!encoding) {
+    if (eligible) appendVary(res, "Accept-Encoding");
+    if (Buffer.isBuffer(body) || typeof body === "string") {
+      res.setHeader("Content-Length", String(knownSize));
+      res.end(body);
+      return;
+    }
+    if (size !== undefined) res.setHeader("Content-Length", String(size));
+    await pipeline(body, res);
+    return;
+  }
+
+  res.setHeader("Content-Encoding", encoding);
+  appendVary(res, "Accept-Encoding");
+  await pipeline(
+    bodyAsReadable(body),
+    createCompressorStream(encoding, config),
+    res
+  );
+}

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