@zero-server/sdk 0.9.0

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/lib/grpc/balancer.js

@@ -0,0 +1,378 @@
+/**
+ * @module grpc/balancer
+ * @description Client-side load balancing for gRPC.
+ *              Distributes requests across multiple backend addresses using
+ *              pick-first (with failover) or round-robin policies.
+ *
+ *              Manages subchannels (HTTP/2 connections) per backend with
+ *              automatic reconnection, exponential backoff, and health awareness.
+ *
+ * @example
+ *   const { GrpcClient, parseProto } = require('@zero-server/sdk');
+ *   const schema = parseProto(protoSource);
+ *
+ *   const client = new GrpcClient({
+ *       addresses: ['backend-1:50051', 'backend-2:50051', 'backend-3:50051'],
+ *       loadBalancing: 'round-robin',
+ *   }, schema, 'Greeter');
+ *
+ *   const reply = await client.call('SayHello', { name: 'World' });
+ */
+
+const http2 = require('http2');
+const { EventEmitter } = require('events');
+const log = require('../debug')('zero:grpc:balancer');
+
+// -- Subchannel States -----------------------------------------
+
+/**
+ * Connection state machine per subchannel.
+ * @enum {string}
+ */
+const SubchannelState = {
+    IDLE: 'IDLE',
+    CONNECTING: 'CONNECTING',
+    READY: 'READY',
+    TRANSIENT_FAILURE: 'TRANSIENT_FAILURE',
+    SHUTDOWN: 'SHUTDOWN',
+};
+
+// -- Subchannel ------------------------------------------------
+
+/**
+ * Represents a persistent HTTP/2 connection to a single backend.
+ *
+ * @class
+ * @private
+ */
+class Subchannel extends EventEmitter
+{
+    /**
+     * @param {string} address - Backend address (host:port or full URL).
+     * @param {object} [connectOpts] - HTTP/2 connection options (TLS, etc.).
+     */
+    constructor(address, connectOpts = {})
+    {
+        super();
+
+        /** @type {string} */
+        this.address = address;
+
+        /** @type {string} */
+        this.state = SubchannelState.IDLE;
+
+        /** @private */
+        this._connectOpts = connectOpts;
+
+        /** @private @type {import('http2').ClientHttp2Session|null} */
+        this._session = null;
+
+        /** @private */
+        this._backoff = 1000; // exponential backoff starting at 1s
+        this._maxBackoff = 30000;
+        this._reconnectTimer = null;
+
+        /** @private */
+        this._shutdown = false;
+
+        /** @private */
+        this._healthy = true;
+    }
+
+    /**
+     * Connect to the backend.
+     * @returns {import('http2').ClientHttp2Session|null}
+     */
+    connect()
+    {
+        if (this._shutdown) return null;
+        if (this._session && !this._session.closed && !this._session.destroyed)
+            return this._session;
+
+        this._setState(SubchannelState.CONNECTING);
+
+        try
+        {
+            // Normalize address to URL
+            const url = this.address.includes('://') ? this.address : `http://${this.address}`;
+            this._session = http2.connect(url, this._connectOpts);
+
+            this._session.on('connect', () =>
+            {
+                this._backoff = 1000; // reset backoff on successful connect
+                this._setState(SubchannelState.READY);
+                this._healthy = true;
+            });
+
+            this._session.on('error', (err) =>
+            {
+                log.warn('subchannel %s error: %s', this.address, err.message);
+                this._healthy = false;
+                this._setState(SubchannelState.TRANSIENT_FAILURE);
+                this._scheduleReconnect();
+            });
+
+            this._session.on('close', () =>
+            {
+                this._session = null;
+                if (!this._shutdown)
+                {
+                    this._setState(SubchannelState.IDLE);
+                    this._scheduleReconnect();
+                }
+            });
+
+            this._session.on('goaway', () =>
+            {
+                log.info('subchannel %s received GOAWAY', this.address);
+                this._healthy = false;
+                this._setState(SubchannelState.IDLE);
+            });
+
+            return this._session;
+        }
+        catch (err)
+        {
+            log.error('subchannel %s connect error: %s', this.address, err.message);
+            this._setState(SubchannelState.TRANSIENT_FAILURE);
+            this._scheduleReconnect();
+            return null;
+        }
+    }
+
+    /**
+     * Get the session, connecting if needed.
+     * @returns {import('http2').ClientHttp2Session|null}
+     */
+    getSession()
+    {
+        if (this._session && !this._session.closed && !this._session.destroyed)
+            return this._session;
+        return this.connect();
+    }
+
+    /**
+     * Whether this subchannel is ready to serve requests.
+     * @returns {boolean}
+     */
+    get isReady()
+    {
+        return this.state === SubchannelState.READY &&
+               this._session && !this._session.closed && !this._session.destroyed;
+    }
+
+    /**
+     * Whether this subchannel is considered healthy.
+     * @returns {boolean}
+     */
+    get isHealthy()
+    {
+        return this._healthy && this.isReady;
+    }
+
+    /**
+     * Schedule a reconnection with exponential backoff.
+     * @private
+     */
+    _scheduleReconnect()
+    {
+        if (this._shutdown || this._reconnectTimer) return;
+
+        this._reconnectTimer = setTimeout(() =>
+        {
+            this._reconnectTimer = null;
+            if (!this._shutdown) this.connect();
+        }, this._backoff);
+        if (this._reconnectTimer.unref) this._reconnectTimer.unref();
+
+        this._backoff = Math.min(this._backoff * 2, this._maxBackoff);
+    }
+
+    /**
+     * Update state and emit event.
+     * @private
+     */
+    _setState(state)
+    {
+        const prev = this.state;
+        this.state = state;
+        if (prev !== state)
+        {
+            log.debug('subchannel %s: %s → %s', this.address, prev, state);
+            this.emit('stateChange', state, prev);
+        }
+    }
+
+    /**
+     * Shut down this subchannel.
+     */
+    shutdown()
+    {
+        this._shutdown = true;
+        this._setState(SubchannelState.SHUTDOWN);
+        if (this._reconnectTimer)
+        {
+            clearTimeout(this._reconnectTimer);
+            this._reconnectTimer = null;
+        }
+        if (this._session)
+        {
+            try { this._session.close(); }
+            catch (_) { /* ignore */ }
+            this._session = null;
+        }
+    }
+}
+
+// -- Load Balancing Policies -----------------------------------
+
+/**
+ * Pick-first policy: use the first ready subchannel, failover to next.
+ * @private
+ * @param {Subchannel[]} subchannels
+ * @returns {Subchannel|null}
+ */
+function pickFirst(subchannels)
+{
+    // First, try the first ready subchannel
+    for (const sc of subchannels)
+    {
+        if (sc.isHealthy) return sc;
+    }
+    // Fallback: try any that's ready even if not "healthy"
+    for (const sc of subchannels)
+    {
+        if (sc.isReady) return sc;
+    }
+    // Connect the first idle one
+    for (const sc of subchannels)
+    {
+        if (sc.state === SubchannelState.IDLE)
+        {
+            sc.connect();
+            return sc;
+        }
+    }
+    return subchannels[0] || null;
+}
+
+/**
+ * Round-robin policy: distribute requests across all ready subchannels.
+ * @private
+ */
+class RoundRobinPicker
+{
+    constructor()
+    {
+        /** @private */
+        this._index = 0;
+    }
+
+    /**
+     * Pick the next subchannel.
+     * @param {Subchannel[]} subchannels
+     * @returns {Subchannel|null}
+     */
+    pick(subchannels)
+    {
+        const ready = subchannels.filter(sc => sc.isHealthy);
+        if (ready.length === 0)
+        {
+            // Fallback to any ready
+            const anyReady = subchannels.filter(sc => sc.isReady);
+            if (anyReady.length > 0)
+            {
+                this._index = (this._index + 1) % anyReady.length;
+                return anyReady[this._index];
+            }
+            // Try to connect idle ones
+            for (const sc of subchannels)
+            {
+                if (sc.state === SubchannelState.IDLE) sc.connect();
+            }
+            return subchannels[0] || null;
+        }
+
+        this._index = (this._index + 1) % ready.length;
+        return ready[this._index];
+    }
+}
+
+// -- Balancer --------------------------------------------------
+
+/**
+ * Load-balanced wrapper that manages multiple subchannels and
+ * exposes a `pickSubchannel()` method for the GrpcClient to use.
+ *
+ * @class
+ */
+class LoadBalancer extends EventEmitter
+{
+    /**
+     * @param {string[]} addresses - Backend addresses.
+     * @param {object} [opts] - Options.
+     * @param {string} [opts.policy='pick-first'] - 'pick-first' or 'round-robin'.
+     * @param {object} [opts.connectOpts] - HTTP/2 connection options.
+     */
+    constructor(addresses, opts = {})
+    {
+        super();
+
+        /** @type {Subchannel[]} */
+        this.subchannels = addresses.map(addr => new Subchannel(addr, opts.connectOpts || {}));
+
+        /** @private */
+        this._policy = opts.policy || 'pick-first';
+
+        /** @private */
+        this._rrPicker = this._policy === 'round-robin' ? new RoundRobinPicker() : null;
+
+        // Start connecting to all subchannels for round-robin
+        if (this._policy === 'round-robin')
+        {
+            for (const sc of this.subchannels) sc.connect();
+        }
+        else
+        {
+            // Pick-first: connect only to the first
+            if (this.subchannels.length > 0) this.subchannels[0].connect();
+        }
+    }
+
+    /**
+     * Pick a subchannel for the next request.
+     * @returns {Subchannel|null}
+     */
+    pick()
+    {
+        if (this._rrPicker)
+            return this._rrPicker.pick(this.subchannels);
+        return pickFirst(this.subchannels);
+    }
+
+    /**
+     * Get an HTTP/2 session from the selected subchannel.
+     * @returns {import('http2').ClientHttp2Session|null}
+     */
+    getSession()
+    {
+        const sc = this.pick();
+        if (!sc) return null;
+        return sc.getSession();
+    }
+
+    /**
+     * Shut down all subchannels.
+     */
+    shutdown()
+    {
+        for (const sc of this.subchannels) sc.shutdown();
+    }
+}
+
+module.exports = {
+    LoadBalancer,
+    Subchannel,
+    SubchannelState,
+    RoundRobinPicker,
+};