cpeak 2.5.0 → 2.7.0

package/README.md

@@ -28,12 +28,17 @@ This is an educational project that was started as part of the [Understanding No
   - [URL Variables & Parameters](#url-variables--parameters)
   - [Sending Files](#sending-files)
   - [Redirecting](#redirecting)
+  - [Compression](#compression)
   - [Error Handling](#error-handling)
   - [Listening](#listening)
   - [Util Functions](#util-functions)
     - [serveStatic](#servestatic)
     - [parseJSON](#parsejson)
     - [render](#render)
+    - [cookieParser](#cookieparser)
+    - [swagger](#swagger)
+    - [auth](#auth)
+    - [cors](#cors)
 - [Complete Example](#complete-example)
 - [Versioning Notice](#versioning-notice)
 
@@ -203,6 +208,54 @@ If you want to redirect to a new URL, you can simply do:
 res.redirect("https://whatever.com");
 ```
 
+### Compression
+
+You can enable HTTP response compression at construction time. Once enabled, `serveStatic`, `res.json()` and `res.sendFile()` will compress eligible responses automatically, and you also get a `res.compress()` method on the response for custom payloads.
+
+Fire it up with the defaults like this:
+
+```javascript
+const server = cpeak({ compression: true });
+```
+
+Or pass options to tune the behavior:
+
+```javascript
+const server = cpeak({
+  compression: {
+    threshold: 1024, // bytes — responses smaller than this are sent uncompressed. Default: 1024
+    brotli: {},      // node:zlib BrotliOptions
+    gzip: {},        // node:zlib ZlibOptions
+    deflate: {}      // node:zlib ZlibOptions
+  }
+});
+```
+
+For arbitrary payloads, like a `Buffer`, `string`, or `Readable` stream, use `res.compress`:
+
+```javascript
+server.route("get", "/report", async (req, res) => {
+  const csv = await buildCsvReport();
+  await res.compress("text/csv", csv);
+});
+```
+
+When you're streaming, you can pass a known size as the third argument. Cpeak will use it to decide eligibility against `threshold`, and to set `Content-Length` if the body ends up being sent uncompressed:
+
+```javascript
+import { Readable } from "node:stream";
+
+server.route("get", "/proxy/feed", async (req, res) => {
+  const upstream = await fetch("https://example.com/feed.xml");
+  const size = Number(upstream.headers.get("content-length"));
+  await res.compress("application/xml", Readable.fromWeb(upstream.body), size);
+});
+```
+
+You must first enable compression at construction time to use `res.compress`. 
+
+One thing to keep in mind: when compression is enabled, `res.json()` returns a `Promise` because the work runs through async streams. You don't have to await it, but you can if you want to know when the response has been fully flushed.
+
 ### Error Handling
 
 If anywhere in your route functions or route middleware functions you want to return an error, you can just throw the error and let the automatic error handler catch it:
@@ -267,6 +320,10 @@ The list of utility functions as of now:
 - serveStatic
 - parseJSON
 - render
+- cookieParser
+- swagger
+- auth
+- cors
 
 Including any one of them is done like this:
 
@@ -296,7 +353,11 @@ If you have file types in your public folder that are not one of the following,
   jpeg: "image/jpeg",
   png: "image/png",
   svg: "image/svg+xml",
+  gif: "image/gif",
+  ico: "image/x-icon",
   txt: "text/plain",
+  json: "application/json",
+  webmanifest: "application/manifest+json",
   eot: "application/vnd.ms-fontobject",
   otf: "font/otf",
   ttf: "font/ttf",
@@ -304,6 +365,16 @@ If you have file types in your public folder that are not one of the following,
   woff2: "font/woff2"
 ```
 
+You can also serve your static files under a URL prefix by passing a third argument with a `prefix` option. This is useful when you want all static assets to live under a specific path like `/static`:
+
+```javascript
+server.beforeEach(
+  serveStatic("./public", null, { prefix: "/static" })
+);
+```
+
+With this setup, a file at `./public/app.js` would be served at `/static/app.js` instead of `/app.js`. Pass `null` as the second argument if you don’t need any custom MIME types.
+
 #### parseJSON
 
 With this middleware function, you can easily read and send JSON in HTTP message bodies in route and middleware functions. Fire it up like this:
@@ -366,12 +437,219 @@ You can then inject the variables into your file in {{ variable_name }} like thi
 </html>
 ```
 
+#### cookieParser
+
+With this middleware function, you can easily read and set cookies in your route and middleware functions. Fire it up like this:
+
+```javascript
+server.beforeEach(cookieParser());
+```
+
+If you need to use signed cookies, pass a secret:
+
+```javascript
+server.beforeEach(cookieParser({ secret: "your-secret-key" }));
+```
+
+Signed cookies use HMAC to verify integrity. The original value stays readable by the client, but any tampering with it will be detected on the server side. This makes them a solid choice for session identifiers or user IDs where you want to prevent impersonation without hiding the value itself.
+
+Read incoming cookies like this:
+
+```javascript
+server.route("get", "/dashboard", (req, res) => {
+  // Regular cookies
+  const theme = req.cookies.theme;
+
+  // Signed cookies — returns false if the signature is invalid or the value was tampered with
+  const userId = req.signedCookies.userId;
+
+  res.status(200).json({ theme, userId });
+});
+```
+
+Set cookies on the response like this:
+
+```javascript
+server.route("post", "/login", (req, res) => {
+  // A plain cookie
+  res.cookie("theme", "dark", { httpOnly: true, maxAge: 7 * 24 * 60 * 60 * 1000 });
+
+  // A signed cookie
+  res.cookie("userId", "abc123", { signed: true, httpOnly: true, secure: true });
+
+  res.status(200).json({ message: "Logged in" });
+});
+```
+
+Clear a cookie like this:
+
+```javascript
+res.clearCookie("userId");
+```
+
+The full list of cookie options you can pass as the third argument to `res.cookie()`:
+
+- `signed` — sign the cookie value with HMAC using the secret you provided to `cookieParser`
+- `httpOnly` — prevents client-side JavaScript from accessing the cookie
+- `secure` — instructs the browser to send the cookie only over HTTPS
+- `sameSite` — controls cross-site cookie behavior; accepts `"strict"`, `"lax"`, or `"none"`
+- `maxAge` — cookie lifetime in milliseconds
+- `expires` — a specific expiration `Date` for the cookie
+- `path` — path the cookie is valid for (defaults to `"/"`)
+- `domain` — domain the cookie is valid for
+
+#### swagger
+
+With this middleware function, you can serve an interactive Swagger UI for your API documentation. It works alongside the `serveStatic` utility and two npm packages: `swagger-ui-dist` (the Swagger UI static assets) and `yamljs` (to load your YAML spec file).
+
+Start by installing the dependencies:
+
+```bash
+npm install swagger-ui-dist yamljs
+```
+
+Then fire it up like this:
+
+```javascript
+import cpeak, { swagger, serveStatic } from "cpeak";
+import YAML from "yamljs";
+import swaggerUiDist from "swagger-ui-dist";
+import path from "node:path";
+
+const server = cpeak();
+
+const swaggerDocument = YAML.load(
+  path.join(path.resolve(), "./src/swagger.yml")
+);
+
+server.beforeEach(swagger(swaggerDocument));
+server.beforeEach(
+  serveStatic(swaggerUiDist.getAbsoluteFSPath(), undefined, {
+    prefix: "/api-docs",
+  })
+);
+```
+
+Once set up, your Swagger UI will be available at `/api-docs`. The `swagger` middleware handles serving your spec at `/api-docs/spec.json` and wiring up the Swagger UI initializer, while `serveStatic` serves all the Swagger UI static assets under the same prefix.
+
+If you want to serve the docs under a different path, pass it as the second argument to `swagger` and match the prefix in `serveStatic`:
+
+```javascript
+server.beforeEach(swagger(swaggerDocument, "/docs"));
+server.beforeEach(
+  serveStatic(swaggerUiDist.getAbsoluteFSPath(), undefined, {
+    prefix: "/docs",
+  })
+);
+```
+
+#### auth
+
+With this middleware you can add a full-fledged authentication system to your application with emails, username and password authentication, with features such as Forgot Password, Update Password and so forth. We have no external dependencies, with timing-safe comparisons throughout. It attaches helper methods directly to `req` so your route handlers stay clean.
+
+Fire it up like this:
+
+```javascript
+import cpeak, { parseJSON, cookieParser, auth } from "cpeak";
+
+const app = cpeak();
+
+app.beforeEach(parseJSON());
+app.beforeEach(cookieParser());
+
+app.beforeEach(
+  auth({
+    // Required
+    secret: "your-secret-min-32-chars-long!!!", // used to sign token IDs with HMAC
+    saveToken: async (tokenId, userId, expiresAt) => { /* store in your DB */ },
+    findToken: async (tokenId) => { /* return { userId, expiresAt } or null */ },
+
+    // Enables req.logout()
+    revokeToken: async (tokenId) => { /* delete from your DB */ },
+
+    // Optional PBKDF2 tuning (defaults shown):
+    iterations: 210_000,  // higher = slower brute-force
+    keylen: 64,           // derived key length in bytes
+    digest: "sha512",
+    saltSize: 32,
+
+    // Optional token signing tuning (defaults shown):
+    hmacAlgorithm: "sha256",
+    tokenIdSize: 20,
+    tokenExpiry: 7 * 24 * 60 * 60 * 1000, // 7 days in ms
+  })
+);
+```
+
+Once set up, the following methods are available on `req` inside your routes and middleware:
+
+| Method | Description |
+|--------|-------------|
+| `req.hashPassword({ password })` | Hashes a password with PBKDF2. Store the result; never store plaintext. |
+| `req.login({ password, hashedPassword, userId })` | Verifies the password and if correct, creates a signed token. Returns the token string to send to the client, or `null` on wrong password. |
+| `req.verifyToken(token)` | Validates a token's HMAC signature and expiry. Returns `{ userId }` or `null`. |
+| `req.logout(token)` | Revokes the token via your `revokeToken` callback. Only available when `revokeToken` is provided. |
+
+Here are the two most common middleware patterns you'll want to set up:
+
+```javascript
+// Throws 401 if the request has no valid token. Use on protected routes.
+const requireAuth = async (req, res, next) => {
+  const token = req.headers["authorization"];
+  if (!token) throw { status: 401, message: "Unauthorized." };
+
+  const result = await req.verifyToken(token);
+  if (!result) throw { status: 401, message: "Unauthorized." };
+
+  req.user = { id: result.userId };
+  next();
+};
+
+// Silently sets req.user when a valid token is present, but lets the request through either way.
+// Useful for routes accessible by both authenticated and unauthenticated users.
+const optionalAuth = async (req, _res, next) => {
+  const token = req.headers["authorization"];
+  if (token) {
+    const result = await req.verifyToken(token);
+    if (result) req.user = { id: result.userId };
+  }
+  next();
+};
+```
+
+For complete working examples, see:
+
+- [`examples/auth-localstorage.js`](examples/auth-localstorage.js) — token sent via the `Authorization` header (suited for SPAs and mobile clients)
+- [`examples/auth-cookies.js`](examples/auth-cookies.js) — token stored in an `httpOnly` cookie (protects against XSS)
+
+#### cors
+The CORS middleware allows you to enable Cross-Origin Resource Sharing in your application.
+
+```javascript
+server.beforeEach(cors({
+  origin: "http://localhost:3000",  // string, string[], RegExp, boolean, or async (origin) => boolean. Default: "*" (all origins)
+  methods: "GET,POST,PUT,DELETE",   // allowed HTTP methods. Default: "GET,HEAD,PUT,PATCH,POST,DELETE"
+  allowedHeaders: "Content-Type",   // headers the browser may send. Default: echoes request headers for origin:"*", else "Content-Type, Authorization"
+  exposedHeaders: "X-Request-Id",   // response headers the browser may read. Default: none
+  credentials: true,                // adds Access-Control-Allow-Credentials: true. Default: false
+  maxAge: 3600,                     // seconds to cache preflight result in the browser. Default: 86400
+  preflightContinue: false,         // pass OPTIONS preflight to next middleware instead of auto-responding. Default: false
+  optionsSuccessStatus: 204         // status code for successful preflight responses. Default: 204
+}));
+```
+
+Or if you don't care and want to allow everything with the default settings, just do:
+
+```javascript
+server.beforeEach(cors());
+```
+
 ## Complete Example
 
-Here you can see all the features that Cpeak offers, in one small piece of code:
+Here you can see all the features that Cpeak offers (excluding the authentication features), in one small piece of code:
 
 ```javascript
-import cpeak, { serveStatic, parseJSON, render } from "cpeak";
+import cpeak, { serveStatic, parseJSON, render, cookieParser, cors } from "cpeak";
 
 const server = cpeak();
 
@@ -386,6 +664,16 @@ server.beforeEach(render());
 // For parsing JSON bodies
 server.beforeEach(parseJSON());
 
+// For reading and setting cookies
+server.beforeEach(cookieParser({ secret: "your-secret-key" }));
+
+// For enabling CORS
+server.beforeEach(cors({
+  origin: "http://localhost:3000",
+  credentials: true,
+  methods: "GET,POST,PUT,DELETE"
+}));
+
 // Adding custom middleware functions
 server.beforeEach((req, res, next) => {
   req.custom = "This is some string";
@@ -437,6 +725,16 @@ server.route("get", "/api/document/:title", testRouteMiddleware, (req, res) => {
   res.status(200).json({ message: "This is a test response" });
 });
 
+// Reading and setting cookies
+server.route("post", "/login", (req, res) => {
+  // Reads are available via req.cookies and req.signedCookies
+  const sessionId = req.signedCookies.sessionId;
+
+  // Set a signed session cookie
+  res.cookie("sessionId", "abc123", { signed: true, httpOnly: true, secure: true });
+  res.status(200).json({ message: "Logged in" });
+});
+
 // Sending a file response
 server.route("get", "/file", (req, res) => {
   // Make sure to specify a correct path and MIME type...

package/dist/index.d.ts

@@ -1,18 +1,75 @@
+import * as net from 'net';
 import http, { IncomingMessage, ServerResponse } from 'node:http';
+import { Readable } from 'node:stream';
+import { Buffer } from 'node:buffer';
+import * as node_zlib from 'node:zlib';
 
-type Cpeak$1 = ReturnType<typeof cpeak>;
+interface PbkdfOptions {
+    iterations?: number;
+    keylen?: number;
+    digest?: string;
+    saltSize?: number;
+}
+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>;
+}
+interface CookieOptions {
+    signed?: boolean;
+    httpOnly?: boolean;
+    secure?: boolean;
+    sameSite?: "strict" | "lax" | "none";
+    maxAge?: number;
+    expires?: Date;
+    path?: string;
+    domain?: string;
+}
+type OriginInput = string | string[] | RegExp | boolean | ((origin: string | undefined) => boolean | Promise<boolean>);
+interface CorsOptions {
+    origin?: OriginInput;
+    methods?: string | string[];
+    allowedHeaders?: string | string[];
+    exposedHeaders?: string | string[];
+    credentials?: boolean;
+    maxAge?: number;
+    preflightContinue?: boolean;
+    optionsSuccessStatus?: number;
+}
+interface CompressionOptions {
+    threshold?: number;
+    brotli?: node_zlib.BrotliOptions;
+    gzip?: node_zlib.ZlibOptions;
+    deflate?: node_zlib.ZlibOptions;
+}
+
+interface CpeakOptions {
+    compression?: boolean | CompressionOptions;
+}
 type StringMap = Record<string, string>;
 interface CpeakRequest<ReqBody = any, ReqQueries = any> extends IncomingMessage {
     params: StringMap;
     query: ReqQueries;
     body?: ReqBody;
+    cookies?: StringMap;
+    signedCookies?: Record<string, string | false>;
     [key: string]: any;
 }
 interface CpeakResponse extends ServerResponse {
     sendFile: (path: string, mime: string) => Promise<void>;
     status: (code: number) => CpeakResponse;
-    redirect: (location: string) => CpeakResponse;
-    json: (data: any) => void;
+    attachment: (filename?: string) => CpeakResponse;
+    cookie: (name: string, value: string, options?: any) => CpeakResponse;
+    redirect: (location: string) => void;
+    json: (data: any) => void | Promise<void>;
+    compress: (mime: string, body: Buffer | string | Readable, size?: number) => Promise<void>;
     [key: string]: any;
 }
 type Next = (err?: any) => void;
@@ -30,14 +87,28 @@ interface RoutesMap {
     [method: string]: Route[];
 }
 
-declare const serveStatic: (folderPath: string, newMimeTypes?: StringMap) => (req: CpeakRequest, res: CpeakResponse, next: Next) => void | Promise<void>;
-
 declare const parseJSON: (options?: {
     limit?: number;
 }) => (req: CpeakRequest, res: CpeakResponse, next: Next) => void;
 
+declare const serveStatic: (folderPath: string, newMimeTypes?: StringMap, options?: {
+    prefix?: string;
+}) => (req: CpeakRequest, res: CpeakResponse, next: Next) => void | Promise<void>;
+
 declare const render: () => (req: CpeakRequest, res: CpeakResponse, next: Next) => void;
 
+declare const swagger: (spec: object, prefix?: string) => (req: CpeakRequest, res: CpeakResponse, next: Next) => void | Promise<void>;
+
+declare function hashPassword(password: string, options?: PbkdfOptions): Promise<string>;
+declare function verifyPassword(password: string, stored: string): Promise<boolean>;
+declare function auth(options: AuthOptions): Middleware;
+
+declare function cookieParser(options?: {
+    secret?: string;
+}): (req: CpeakRequest, res: CpeakResponse, next: Next) => void;
+
+declare const cors: (options?: CorsOptions) => (req: CpeakRequest, res: CpeakResponse, next: Next) => Promise<void>;
+
 declare function frameworkError(message: string, skipFn: Function, code?: string, status?: number): Error & {
     code?: string;
     cpeak_err?: boolean;
@@ -48,34 +119,35 @@ declare enum ErrorCode {
     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"
+    PAYLOAD_TOO_LARGE = "CPEAK_ERR_PAYLOAD_TOO_LARGE",
+    WEAK_SECRET = "CPEAK_ERR_WEAK_SECRET",
+    COMPRESSION_NOT_ENABLED = "CPEAK_ERR_COMPRESSION_NOT_ENABLED"
 }
 declare class CpeakIncomingMessage extends http.IncomingMessage {
+    #private;
     body: any;
     params: StringMap;
-    private _query?;
     get query(): StringMap;
 }
 declare class CpeakServerResponse extends http.ServerResponse<CpeakIncomingMessage> {
     sendFile(path: string, mime: string): Promise<void>;
     status(code: number): this;
-    redirect(location: string): this;
-    json(data: any): void;
+    attachment(filename?: string): this;
+    redirect(location: string): void;
+    json(data: any): void | Promise<void>;
+    compress(mime: string, body: Buffer | string | Readable, size?: number): Promise<void>;
 }
 declare class Cpeak {
     #private;
-    private server;
-    private routes;
-    private middleware;
-    private _handleErr?;
-    constructor();
+    constructor(options?: CpeakOptions);
     route(method: string, path: string, ...args: (RouteMiddleware | Handler)[]): void;
     beforeEach(cb: Middleware): void;
     handleErr(cb: (err: unknown, req: CpeakRequest, res: CpeakResponse) => void): void;
     listen(port: number, cb?: () => void): http.Server<typeof CpeakIncomingMessage, typeof CpeakServerResponse>;
+    address(): string | net.AddressInfo | null;
     close(cb?: (err?: Error) => void): void;
 }
 
-declare function cpeak(): Cpeak;
+declare function cpeak(options?: CpeakOptions): Cpeak;
 
-export { type Cpeak$1 as Cpeak, type CpeakRequest, type CpeakResponse, ErrorCode, type HandleErr, type Handler, type Middleware, type Next, type RouteMiddleware, type RoutesMap, cpeak as default, frameworkError, parseJSON, render, serveStatic };
+export { type AuthOptions, type CompressionOptions, type CookieOptions, type CorsOptions, Cpeak, CpeakIncomingMessage, type CpeakOptions, type CpeakRequest, type CpeakResponse, CpeakServerResponse, ErrorCode, type HandleErr, type Handler, type Middleware, type Next, type PbkdfOptions, type RouteMiddleware, type RoutesMap, auth, cookieParser, cors, cpeak as default, frameworkError, hashPassword, parseJSON, render, serveStatic, swagger, verifyPassword };