@zero-server/fetch 0.9.1 → 0.9.3

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 Tony Wiedman
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 Tony Wiedman
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/index.d.ts

@@ -1,2 +1,2 @@
 // AUTO-GENERATED by .tools/generate-package-stubs.js — edit .tools/scope-manifest.js and re-run `npm run packages:generate`.
-export { fetch } from "@zero-server/sdk";
+export * from './types/fetch';

package/index.js

@@ -1,7 +1,4 @@
 // AUTO-GENERATED by .tools/generate-package-stubs.js — edit .tools/scope-manifest.js and re-run `npm run packages:generate`.
 'use strict';
-const sdk = require("@zero-server/sdk");
-
-module.exports = {
-    fetch: sdk.fetch,
-};
+const fetch = require('./lib/fetch');
+module.exports = { fetch };

package/lib/fetch/index.js

@@ -0,0 +1,256 @@
+/**
+ * @module fetch
+ * @description Minimal, zero-dependency server-side `fetch()` replacement.
+ *              Supports HTTP/HTTPS, JSON/URLSearchParams/Buffer/stream bodies,
+ *              download & upload progress callbacks, timeouts, and AbortSignal.
+ */
+const http = require('http');
+const https = require('https');
+const { URL } = require('url');
+
+const STATUS_CODES = http.STATUS_CODES;
+
+/**
+ * Perform an HTTP(S) request.
+ *
+ * @param {string} url  - Absolute URL to fetch.
+ * @param {object} [opts] - Configuration options.
+ * @param {string}   [opts.method='GET']           - HTTP method.
+ * @param {object}   [opts.headers]                - Request headers.
+ * @param {string|Buffer|object|ReadableStream} [opts.body] - Request body.
+ * @param {number}   [opts.timeout]                - Request timeout in ms.
+ * @param {AbortSignal} [opts.signal]              - Abort signal for cancellation.
+ * @param {import('http').Agent} [opts.agent]      - Custom HTTP agent.
+ * @param {Function} [opts.onDownloadProgress]     - `({ loaded, total }) => void` download progress callback.
+ * @param {Function} [opts.onUploadProgress]       - `({ loaded, total }) => void` upload progress callback.
+ * @param {boolean}  [opts.rejectUnauthorized]     - Reject connections with unverified certs (default: Node default `true`). TLS option — passed to `https.request()`.
+ * @param {string|Buffer|Array} [opts.ca]          - Override default CA certificates.
+ * @param {string|Buffer}       [opts.cert]        - Client certificate (PEM) for mutual TLS.
+ * @param {string|Buffer}       [opts.key]         - Private key (PEM) for mutual TLS.
+ * @param {string|Buffer}       [opts.pfx]         - PFX / PKCS12 bundle (alternative to cert+key).
+ * @param {string}              [opts.passphrase]  - Passphrase for the key or PFX.
+ * @param {string}              [opts.servername]   - SNI server name override.
+ * @param {string}              [opts.ciphers]      - Colon-separated cipher list.
+ * @param {string}              [opts.secureProtocol] - SSL/TLS protocol method name.
+ * @param {string}              [opts.minVersion]   - Minimum TLS version (`'TLSv1.2'`, etc.).
+ * @param {string}              [opts.maxVersion]   - Maximum TLS version.
+ *
+ * @returns {Promise<{ status: number, statusText: string, ok: boolean, secure: boolean, url: string, headers: object, arrayBuffer: Function, text: Function, json: Function }>} Resolves with a response object containing status info, headers, and body-reading helpers (`text()`, `json()`, `arrayBuffer()`).
+ *
+ * @example
+ *   const res = await fetch('https://api.example.com/data');
+ *   const body = await res.json();
+ *
+ *   // POST with JSON body & timeout
+ *   const res2 = await fetch('https://api.example.com/items', {
+ *       method: 'POST',
+ *       body: { name: 'widget' },
+ *       timeout: 5000,
+ *   });
+ */
+function miniFetch(url, opts = {})
+{
+    return new Promise((resolve, reject) =>
+    {
+        try
+        {
+            const u = new URL(url);
+            const lib = u.protocol === 'https:' ? https : http;
+            const method = (opts.method || 'GET').toUpperCase();
+            const headers = Object.assign({}, opts.headers || {});
+
+            // Normalize body
+            let body = opts.body;
+            if (body && typeof body === 'object' && typeof body.toString === 'function' && body.constructor && body.constructor.name === 'URLSearchParams')
+            {
+                if (!headers['Content-Type'] && !headers['content-type']) headers['Content-Type'] = 'application/x-www-form-urlencoded';
+                body = body.toString();
+            }
+            else if (body && typeof body === 'object' && !Buffer.isBuffer(body) && !(body instanceof ArrayBuffer) && !(body instanceof Uint8Array) && !(body && typeof body.pipe === 'function'))
+            {
+                if (!headers['Content-Type'] && !headers['content-type']) headers['Content-Type'] = 'application/json';
+                body = Buffer.from(JSON.stringify(body), 'utf8');
+            }
+            else if (body instanceof ArrayBuffer)
+            {
+                body = Buffer.from(body);
+            }
+            else if (body instanceof Uint8Array && !Buffer.isBuffer(body))
+            {
+                body = Buffer.from(body);
+            }
+
+            // Set Content-Length for known-size bodies
+            if ((Buffer.isBuffer(body) || typeof body === 'string') && !headers['Content-Length'] && !headers['content-length'])
+            {
+                headers['Content-Length'] = String(Buffer.isBuffer(body) ? body.length : Buffer.byteLength(body));
+            }
+
+            const options = { method, headers };
+            if (opts.agent) options.agent = opts.agent;
+
+            // Pass through TLS options for HTTPS requests
+            if (lib === https)
+            {
+                const tlsKeys = [
+                    'rejectUnauthorized', 'ca', 'cert', 'key', 'pfx', 'passphrase',
+                    'servername', 'ciphers', 'secureProtocol', 'minVersion', 'maxVersion'
+                ];
+                for (const k of tlsKeys)
+                {
+                    if (opts[k] !== undefined) options[k] = opts[k];
+                }
+            }
+
+            const req = lib.request(u, options, (res) =>
+            {
+                const chunks = [];
+                let downloaded = 0;
+                const total = parseInt(res.headers['content-length'] || '0', 10) || null;
+
+                res.on('data', (c) =>
+                {
+                    chunks.push(c);
+                    downloaded += c.length;
+                    if (typeof opts.onDownloadProgress === 'function')
+                    {
+                        try { opts.onDownloadProgress({ loaded: downloaded, total }); } catch (e) { }
+                    }
+                });
+
+                res.on('end', () =>
+                {
+                    const buf = Buffer.concat(chunks);
+                    const status = res.statusCode;
+                    const rawHeaders = res.headers || {};
+                    const responseHeaders = {
+                        get(name)
+                        {
+                            if (!name) return undefined;
+                            const v = rawHeaders[name.toLowerCase()];
+                            return Array.isArray(v) ? v.join(', ') : v;
+                        },
+                        raw: rawHeaders,
+                    };
+
+                    resolve({
+                        status,
+                        statusText: STATUS_CODES[status] || '',
+                        ok: status >= 200 && status < 300,
+                        secure: u.protocol === 'https:',
+                        url: u.href,
+                        headers: responseHeaders,
+                        arrayBuffer: () => Promise.resolve(buf),
+                        text: () => Promise.resolve(buf.toString('utf8')),
+                        json: () =>
+                        {
+                            try { return Promise.resolve(JSON.parse(buf.toString('utf8'))); }
+                            catch (e) { return Promise.reject(e); }
+                        },
+                    });
+                });
+            });
+
+            req.on('error', reject);
+
+            // Timeout
+            if (typeof opts.timeout === 'number' && opts.timeout > 0)
+            {
+                req.setTimeout(opts.timeout, () =>
+                {
+                    const err = new Error('Request timed out');
+                    err.code = 'ETIMEOUT';
+                    req.destroy(err);
+                });
+            }
+
+            // AbortSignal support
+            let abortHandler;
+            if (opts.signal)
+            {
+                if (opts.signal.aborted)
+                {
+                    const err = new Error('Request aborted');
+                    err.name = 'AbortError';
+                    req.destroy(err);
+                    return;
+                }
+                abortHandler = () =>
+                {
+                    const err = new Error('Request aborted');
+                    err.name = 'AbortError';
+                    req.destroy(err);
+                };
+                if (typeof opts.signal.addEventListener === 'function') opts.signal.addEventListener('abort', abortHandler);
+                else if (typeof opts.signal.on === 'function') opts.signal.on('abort', abortHandler);
+            }
+
+            // Cleanup signal listener
+            const cleanup = () =>
+            {
+                if (opts.signal && abortHandler)
+                {
+                    try
+                    {
+                        if (typeof opts.signal.removeEventListener === 'function') opts.signal.removeEventListener('abort', abortHandler);
+                        else if (typeof opts.signal.off === 'function') opts.signal.off('abort', abortHandler);
+                    }
+                    catch (e) { }
+                }
+            };
+            req.on('close', cleanup);
+
+            // Write body
+            if (body && typeof body.pipe === 'function')
+            {
+                let uploaded = 0;
+                body.on('data', (chunk) =>
+                {
+                    uploaded += chunk.length;
+                    if (typeof opts.onUploadProgress === 'function')
+                    {
+                        try { opts.onUploadProgress({ loaded: uploaded, total: headers['Content-Length'] ? Number(headers['Content-Length']) : null }); } catch (e) { }
+                    }
+                });
+                body.on('error', (err) => req.destroy(err));
+                body.pipe(req);
+            }
+            else if (Buffer.isBuffer(body) || typeof body === 'string')
+            {
+                const buf = Buffer.isBuffer(body) ? body : Buffer.from(body);
+                const total = buf.length;
+                const CHUNK = 64 * 1024;
+                let sent = 0;
+
+                function writeNext()
+                {
+                    if (sent >= total) { req.end(); return; }
+                    const slice = buf.slice(sent, Math.min(sent + CHUNK, total));
+                    const ok = req.write(slice, () =>
+                    {
+                        sent += slice.length;
+                        if (typeof opts.onUploadProgress === 'function')
+                        {
+                            try { opts.onUploadProgress({ loaded: sent, total }); } catch (e) { }
+                        }
+                        writeNext();
+                    });
+                    if (!ok) req.once('drain', writeNext);
+                }
+                writeNext();
+            }
+            else if (body == null)
+            {
+                req.end();
+            }
+            else
+            {
+                req.write(String(body));
+                req.end();
+            }
+        }
+        catch (e) { reject(e); }
+    });
+}
+
+module.exports = miniFetch;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zero-server/fetch",
-  "version": "0.9.1",
+  "version": "0.9.3",
   "description": "Server-side fetch with mTLS, timeouts, AbortSignal.",
   "keywords": [
     "zero-server",
@@ -20,6 +20,8 @@
     "./package.json": "./package.json"
   },
   "files": [
+    "lib",
+    "types",
     "index.js",
     "index.d.ts",
     "README.md",
@@ -42,7 +44,12 @@
     "access": "public"
   },
   "sideEffects": false,
-  "dependencies": {
-    "@zero-server/sdk": "0.9.1"
+  "peerDependencies": {
+    "@zero-server/sdk": ">=0.9.3"
+  },
+  "peerDependenciesMeta": {
+    "@zero-server/sdk": {
+      "optional": true
+    }
   }
 }

package/types/app.d.ts

@@ -0,0 +1,223 @@
+/// <reference types="node" />
+
+import { Server as HttpServer } from 'http';
+import { Server as HttpsServer, ServerOptions as TlsOptions } from 'https';
+import { Http2Server, Http2SecureServer } from 'http2';
+import { Request } from './request';
+import { Response } from './response';
+import { RouterInstance, RouteChain, RouteInfo, RouteOptions, RouteHandler } from './router';
+import { MiddlewareFunction, ErrorHandlerFunction, NextFunction } from './middleware';
+import { WebSocketHandler, WebSocketOptions, WebSocketPool } from './websocket';
+import { SSEStream } from './sse';
+import { LifecycleState } from './lifecycle';
+import { MetricsRegistry, HealthCheckResult } from './observe';
+import { ProtoSchema, GrpcServiceOptions, GrpcInterceptor, GrpcHandler } from './grpc';
+
+export interface ListenOptions {
+    /** Create an HTTP/2 server. Combined with TLS options for h2 over TLS, or h2c (cleartext) otherwise. */
+    http2?: boolean;
+    /** Allow HTTP/1.1 fallback on HTTP/2 TLS servers (ALPN negotiation). Default: true. */
+    allowHTTP1?: boolean;
+}
+
+export interface App {
+    /** Internal router instance. */
+    router: RouterInstance;
+    /** Middleware stack. */
+    middlewares: MiddlewareFunction[];
+    /** Application-level locals, merged into every request/response locals. */
+    locals: Record<string, any>;
+
+    /**
+     * Register middleware or mount a sub-router.
+     */
+    use(fn: MiddlewareFunction): App;
+    use(path: string, fn: MiddlewareFunction): App;
+    use(path: string, router: RouterInstance): App;
+
+    /**
+     * Register a global error handler.
+     */
+    onError(fn: ErrorHandlerFunction): void;
+
+    /**
+     * Core request handler for use with `http.createServer()`.
+     */
+    handler(req: import('http').IncomingMessage, res: import('http').ServerResponse): void;
+
+    /**
+     * Start listening for connections.
+     * Pass `{ http2: true }` to create an HTTP/2 server (h2c cleartext or TLS with ALPN).
+     */
+    listen(port?: number, cb?: () => void): HttpServer;
+    listen(port: number, opts: TlsOptions, cb?: () => void): HttpsServer;
+    listen(port: number, opts: ListenOptions & { http2: true } & TlsOptions, cb?: () => void): Http2SecureServer;
+    listen(port: number, opts: ListenOptions & { http2: true }, cb?: () => void): Http2Server;
+    listen(port: number, opts: ListenOptions, cb?: () => void): HttpServer | HttpsServer | Http2Server | Http2SecureServer;
+
+    /**
+     * Gracefully close the server.
+     */
+    close(cb?: (err?: Error) => void): void;
+
+    /**
+     * Perform a full graceful shutdown.
+     */
+    shutdown(opts?: { timeout?: number }): Promise<void>;
+
+    /**
+     * Register a lifecycle event listener.
+     */
+    on(event: 'beforeShutdown' | 'shutdown', fn: () => void | Promise<void>): App;
+
+    /**
+     * Remove a lifecycle event listener.
+     */
+    off(event: 'beforeShutdown' | 'shutdown', fn: () => void | Promise<void>): App;
+
+    /**
+     * Register a WebSocket pool for graceful shutdown.
+     */
+    registerPool(pool: WebSocketPool): App;
+
+    /**
+     * Unregister a WebSocket pool from lifecycle management.
+     */
+    unregisterPool(pool: WebSocketPool): App;
+
+    /**
+     * Track an SSE stream for graceful shutdown.
+     */
+    trackSSE(stream: SSEStream): App;
+
+    /**
+     * Register an ORM Database for graceful shutdown.
+     */
+    registerDatabase(db: { close(): Promise<void> }): App;
+
+    /**
+     * Unregister an ORM Database from lifecycle management.
+     */
+    unregisterDatabase(db: { close(): Promise<void> }): App;
+
+    /**
+     * Configure the shutdown timeout in milliseconds.
+     */
+    shutdownTimeout(ms: number): App;
+
+    /**
+     * Current lifecycle state.
+     */
+    readonly lifecycleState: LifecycleState;
+
+    /**
+     * Register a liveness health check endpoint.
+     */
+    health(path?: string, checks?: Record<string, () => HealthCheckResult | boolean | Promise<HealthCheckResult | boolean>>): App;
+    health(checks?: Record<string, () => HealthCheckResult | boolean | Promise<HealthCheckResult | boolean>>): App;
+
+    /**
+     * Register a readiness health check endpoint.
+     */
+    ready(path?: string, checks?: Record<string, () => HealthCheckResult | boolean | Promise<HealthCheckResult | boolean>>): App;
+    ready(checks?: Record<string, () => HealthCheckResult | boolean | Promise<HealthCheckResult | boolean>>): App;
+
+    /**
+     * Register a custom health check.
+     */
+    addHealthCheck(name: string, fn: () => HealthCheckResult | boolean | Promise<HealthCheckResult | boolean>): App;
+
+    /**
+     * Get the application metrics registry.
+     */
+    metrics(): MetricsRegistry;
+
+    /**
+     * Mount a Prometheus metrics endpoint.
+     */
+    metricsEndpoint(path?: string, opts?: { registry?: MetricsRegistry }): App;
+
+    /**
+     * Register a WebSocket upgrade handler.
+     */
+    ws(path: string, handler: WebSocketHandler): void;
+    ws(path: string, opts: WebSocketOptions, handler: WebSocketHandler): void;
+
+    /**
+     * Register a gRPC service with handlers.
+     */
+    grpc(schema: ProtoSchema, serviceName: string, handlers: Record<string, GrpcHandler>, opts?: GrpcServiceOptions): App;
+
+    /**
+     * Add a global gRPC interceptor.
+     */
+    grpcInterceptor(fn: GrpcInterceptor): App;
+
+    /**
+     * Return a flat list of all registered routes.
+     */
+    routes(): RouteInfo[];
+
+    /**
+     * Register a route with a specific HTTP method.
+     */
+    route(method: string, path: string, ...handlers: (RouteOptions | RouteHandler)[]): App;
+
+    /**
+     * Get a setting value (1 arg) or set a setting value (2 args).
+     */
+    set(key: string): any;
+    set(key: string, val: any): App;
+
+    /**
+     * Get a setting value, or register a GET route.
+     * With 1 string arg: returns the setting value.
+     * With path + handlers: registers a GET route.
+     */
+    get(key: string): any;
+    get(path: string, ...handlers: (RouteOptions | RouteHandler)[]): App;
+
+    /**
+     * Enable a boolean setting (set to `true`).
+     */
+    enable(key: string): App;
+
+    /**
+     * Disable a boolean setting (set to `false`).
+     */
+    disable(key: string): App;
+
+    /**
+     * Check if a setting is truthy.
+     */
+    enabled(key: string): boolean;
+
+    /**
+     * Check if a setting is falsy.
+     */
+    disabled(key: string): boolean;
+
+    /**
+     * Register a parameter pre-processing handler.
+     */
+    param(name: string, fn: (req: Request, res: Response, next: NextFunction, value: string) => void): App;
+
+    /**
+     * Create a route group under a prefix with shared middleware.
+     */
+    group(prefix: string, ...args: [...MiddlewareFunction[], (router: RouterInstance) => void]): App;
+
+    /**
+     * Create a chainable route builder for the given path.
+     */
+    chain(path: string): RouteChain;
+
+    // HTTP method shortcuts
+    post(path: string, ...handlers: (RouteOptions | RouteHandler)[]): App;
+    put(path: string, ...handlers: (RouteOptions | RouteHandler)[]): App;
+    delete(path: string, ...handlers: (RouteOptions | RouteHandler)[]): App;
+    patch(path: string, ...handlers: (RouteOptions | RouteHandler)[]): App;
+    options(path: string, ...handlers: (RouteOptions | RouteHandler)[]): App;
+    head(path: string, ...handlers: (RouteOptions | RouteHandler)[]): App;
+    all(path: string, ...handlers: (RouteOptions | RouteHandler)[]): App;
+}