expediate 1.0.0 → 1.0.1

package/dist/apis.js

@@ -1,250 +0,0 @@
-/* Copyright 2021 Fabien Bavent
- *
- * 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.
- */
-'use strict';
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.apiBuilder = apiBuilder;
-const router_js_1 = __importDefault(require("./router.js"));
-// ---------------------------------------------------------------------------
-// Internal helpers
-// ---------------------------------------------------------------------------
-/**
- * Instantiate a new service module for the given scope `key`.
- *
- * The lifecycle is:
- * 1. **`data(key)`** — create the initial state object (or use `{ $key: key }`
- *    when `data` is not defined).
- * 2. **Mix in methods** — each entry in `service.methods` is copied onto the
- *    instance as a regular function bound to `this`.
- * 3. **`setup()`** — called once on the new instance; may be async.
- *
- * @param service - The service definition.
- * @param key     - The scope key (`'singleton'`, `null`, or a session ID).
- * @returns A fully initialised service instance.
- */
-function buildModule(service, key) {
-    const instance = service.data
-        ? service.data(key)
-        : { $key: key };
-    // Mix service methods into the instance, bound to `this = instance`.
-    // BUG FIX: the original used arrow functions `() => method.apply(module, arguments)`.
-    // Arrow functions do NOT have their own `arguments` object — they inherit it
-    // from the enclosing `buildModule` scope (which holds `(service, key)`).
-    // Any arguments forwarded to the method were therefore silently dropped.
-    // Corrected to a regular function expression that captures its own `arguments`
-    // via a rest parameter spread.
-    if (service.methods) {
-        for (const methodName of Object.keys(service.methods)) {
-            const method = service.methods[methodName];
-            instance[methodName] = function (...args) {
-                return method.apply(instance, args);
-            };
-        }
-    }
-    if (service.setup)
-        service.setup.apply(instance, []);
-    return instance;
-}
-/**
- * Resolve the correct service instance for an incoming request.
- *
- * Instance lifecycle by scope:
- * - **Singleton** (`scope` absent): always returns `modules['singleton']`.
- * - **Keyed** (`scope` returns a string): look up `modules[key]`; create and
- *   cache a new instance on first access.
- * - **Ephemeral** (`scope` returns `null`): create a fresh instance every time;
- *   never cached.
- *
- * @param service - The service definition.
- * @param modules - The instance cache (mutated when a new keyed instance is created).
- * @param req     - The incoming request.
- * @returns The service instance to use for this request.
- */
-function resolveInstance(service, modules, req) {
-    if (typeof service.scope !== 'function') {
-        // Singleton — always the same global instance.
-        return modules['singleton'];
-    }
-    // BUG FIX: the original called `service.key(req)` which does not exist on
-    // the service definition. The correct method is `service.scope(req)`.
-    const key = service.scope(req);
-    if (key === null) {
-        // Ephemeral — create a fresh, uncached instance for every request.
-        return buildModule(service, null);
-    }
-    // Keyed — retrieve from cache or create and store.
-    if (!modules[key])
-        modules[key] = buildModule(service, key);
-    return modules[key];
-}
-// ---------------------------------------------------------------------------
-// Response helpers
-// ---------------------------------------------------------------------------
-/**
- * Send a JSON response with the appropriate `Content-Type` header.
- *
- * @param res  - The outgoing response.
- * @param data - Any JSON-serialisable value.
- */
-function sendJson(res, data) {
-    // BUG FIX: the original called `res.send(JSON.stringify(val))` without
-    // setting a `Content-Type` header. Clients had no way to detect that the
-    // response body was JSON. Corrected by setting the header explicitly.
-    res.setHeader('Content-Type', 'application/json; charset=utf-8');
-    res.send(JSON.stringify(data));
-}
-/**
- * Translate a caught error (thrown or rejected by a service method) into an
- * HTTP error response.
- *
- * Expected shape: `{ httpStatus?, data?, message? }` (see {@link ApiError}).
- * Any other thrown value is treated as an opaque 500 Internal Server Error.
- *
- * @param res - The outgoing response.
- * @param err - The caught value.
- */
-function sendError(res, err) {
-    const e = err;
-    const status = e?.httpStatus ?? 500;
-    if (e?.data !== undefined) {
-        res.setHeader('Content-Type', 'application/json; charset=utf-8');
-        res.status(status).send(JSON.stringify(e.data));
-    }
-    else {
-        res.status(status).send(e?.message ?? 'Internal error');
-    }
-}
-// ---------------------------------------------------------------------------
-// Public API
-// ---------------------------------------------------------------------------
-/**
- * Build an Express-compatible router from a service definition object.
- *
- * The returned router is suitable for mounting via `app.use()`:
- *
- * ```ts
- * import myService from './my-service.js';
- *
- * app.use('/api', apiBuilder(myService));
- * ```
- *
- * **Route handlers** declared in `service.GET`, `service.POST`, etc. are
- * called with `this` bound to the service instance.  They receive two
- * arguments:
- * 1. `params` — merged route + query-string parameters from `req.params`.
- * 2. `body`   — the parsed request body from `req.body` (requires a
- *    body-parsing middleware such as `json()` to run first).
- *
- * **Return values:**
- * - A **truthy value** (or a `Promise` resolving to one) → serialised as JSON
- *   with status `200 OK`.
- * - A **falsy value** (`undefined`, `null`, `false`, `0`, `''`) or a
- *   `Promise` resolving to one → `201 No Content` (useful for mutations).
- *
- * **Error handling:**
- * - Throwing or rejecting with `{ httpStatus, message }` sends the
- *   corresponding HTTP error.
- * - Throwing or rejecting with `{ httpStatus, data }` sends the `data` object
- *   as a JSON body.
- * - Any other thrown value produces `500 Internal Server Error`.
- *
- * @param service - The service definition (see {@link ServiceDefinition}).
- * @returns A router instance pre-configured with all declared routes.
- */
-function apiBuilder(service) {
-    const api = (0, router_js_1.default)();
-    const modules = {};
-    // Pre-build the singleton instance eagerly so `setup()` runs at startup.
-    if (typeof service.scope !== 'function')
-        // BUG FIX: the original called `buildModule(service)` without a key,
-        // passing `undefined` to `data()` and leaving `$key` as `undefined`.
-        // Corrected to pass `'singleton'` as the canonical key.
-        modules['singleton'] = buildModule(service, 'singleton');
-    /**
-     * Register all route handlers from a route map for a given HTTP method.
-     *
-     * Each handler:
-     * 1. Resolves the correct service instance (singleton / keyed / ephemeral).
-     * 2. Invokes the service method with `(params, body)`.
-     * 3. Sends the return value as JSON (or 201 if falsy).
-     * 4. Catches thrown / rejected {@link ApiError} objects and translates them
-     *    into the appropriate HTTP error response.
-     *
-     * @param routeMap - Map of path patterns to service methods (`undefined` = skip).
-     * @param register - Registers a handler on the router for the current HTTP method.
-     */
-    function buildRoutes(routeMap, register) {
-        if (!routeMap)
-            return;
-        // Sort routes by decreasing specificity so that more precise patterns
-        // (more segments, fewer parameters) are registered first in the router.
-        // Without this, a plain path like '/items' would match '/items/1' as a
-        // prefix and steal requests intended for '/items/:id'.
-        // Specificity = (segment count * 100) - (parameter count * 10).
-        const sortedPaths = Object.keys(routeMap).sort((a, b) => {
-            const score = (p) => {
-                const segs = p.split('/').filter(s => s.length > 0);
-                return segs.length * 100 - segs.filter(s => s.startsWith(':')).length * 10;
-            };
-            return score(b) - score(a) || b.localeCompare(a);
-        });
-        for (const path of sortedPaths) {
-            const method = routeMap[path];
-            register(path, (req, res) => {
-                const params = req.params;
-                const body = req.body;
-                try {
-                    const instance = resolveInstance(service, modules, req);
-                    const ret = method.apply(instance, [params, body]);
-                    if (ret instanceof Promise) {
-                        ret
-                            .then((val) => {
-                            if (val !== undefined && val !== null && val !== false && val !== 0 && val !== '')
-                                sendJson(res, val);
-                            else
-                                res.status(201).end();
-                        })
-                            .catch((err) => sendError(res, err));
-                    }
-                    else {
-                        if (ret !== undefined && ret !== null && ret !== false && ret !== 0 && ret !== '')
-                            sendJson(res, ret);
-                        else
-                            res.status(201).end();
-                    }
-                }
-                catch (err) {
-                    sendError(res, err);
-                }
-            });
-        }
-    }
-    buildRoutes(service.GET, (path, h) => api.get(path, h));
-    buildRoutes(service.POST, (path, h) => api.post(path, h));
-    buildRoutes(service.PUT, (path, h) => api.put(path, h));
-    buildRoutes(service.DELETE, (path, h) => api.delete(path, h));
-    buildRoutes(service.PATCH, (path, h) => api.patch(path, h));
-    return api;
-}
-exports.default = apiBuilder;
-//# sourceMappingURL=apis.js.map

package/dist/git.js

@@ -1,244 +0,0 @@
-/* Copyright 2021 Fabien Bavent
- *
- * 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.
- */
-'use strict';
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.gitHandler = gitHandler;
-const child_process_1 = require("child_process");
-const zlib_1 = require("zlib");
-// ---------------------------------------------------------------------------
-// PKT-LINE helpers
-// ---------------------------------------------------------------------------
-/**
- * Encode a string as a Git PKT-LINE frame.
- *
- * The Git Smart HTTP protocol wraps each line in a 4-hex-digit length prefix
- * that counts the total frame length (4 bytes for the prefix itself plus the
- * payload bytes, **not** characters).
- *
- * @param str - The plain-text payload to wrap (must be ASCII or UTF-8).
- * @returns The framed string, e.g. `"001e# service=git-upload-pack\n"`.
- *
- * @see https://git-scm.com/docs/pack-protocol#_pkt_line_format
- *
- * @example
- * ```ts
- * pktLine('# service=git-upload-pack\n')
- * // → '001e# service=git-upload-pack\n'
- * //    ^^^^  4 + 26 = 30 = 0x1e
- * ```
- */
-function pktLine(str) {
-    // BUG FIX: the original used `str.length` (character count / UTF-16 code
-    // units) instead of the actual byte length. The Git PKT-LINE spec requires
-    // the 4-hex-digit prefix to represent the *byte* count of the whole frame
-    // (prefix + payload). For ASCII-only service names this difference is zero,
-    // but using Buffer.byteLength is correct and future-proof.
-    const byteLen = Buffer.byteLength(str, 'utf8') + 4; // +4 for the 4-char hex prefix itself
-    return byteLen.toString(16).padStart(4, '0') + str;
-}
-/**
- * The Git PKT-LINE flush packet.
- * Signals the end of a list of PKT-LINE records.
- */
-const PKT_FLUSH = '0000';
-// ---------------------------------------------------------------------------
-// Middleware factory
-// ---------------------------------------------------------------------------
-/**
- * Middleware factory that exposes a Git repository over the **Git Smart HTTP
- * protocol** (read-only fetch / clone, via `git-upload-pack`).
- *
- * Mount this handler at the root of a repository-scoped path so that the two
- * sub-paths it handles (`/info/refs` and `/git-upload-pack`) are reachable:
- *
- * ```ts
- * app.use('/repos/:repo', gitHandler({
- *   repository: (req) => path.join('/srv/git', req.params.repo + '.git'),
- * }));
- * ```
- *
- * **Supported endpoints:**
- *
- * | Method | Path              | Purpose                                      |
- * |--------|-------------------|----------------------------------------------|
- * | GET    | `/info/refs`      | Smart HTTP capability advertisement          |
- * | POST   | `/git-upload-pack`| Pack-file negotiation and transfer           |
- *
- * Only `git-upload-pack` (fetch / clone) is implemented.
- * `git-receive-pack` (push) is intentionally excluded.
- *
- * **Compression:** gzip-compressed POST bodies are transparently decompressed
- * before being piped to `git-upload-pack`.
- *
- * @param opt - Handler configuration (see {@link GitHandlerOptions}).
- * @returns An Express-compatible middleware function `(req, res) => void`.
- * @throws {TypeError} When `opt.repository` is not a function.
- */
-function gitHandler(opt) {
-    if (typeof opt.repository !== 'function')
-        throw new TypeError('gitHandler: opt.repository must be a function');
-    const gitBin = (opt.gitPath ?? '') + 'git-upload-pack';
-    return (req, res) => {
-        // Resolve the repository path for this request.
-        const gitDirectory = opt.repository(req);
-        if (!gitDirectory)
-            return void res.status(404).send('Repository not found');
-        const urlPath = req.path; // sub-path after the mount prefix
-        // ── GET /info/refs?service=git-upload-pack ──────────────────────────
-        if (req.method === 'GET' && urlPath === '/info/refs') {
-            // BUG FIX: `req.queries.url` can be undefined when no query parameters
-            // are present, causing `req.queries.url.service` to throw a TypeError.
-            const service = req.queries?.url?.service;
-            if (service !== 'git-upload-pack')
-                return void res.status(403).send('Only git-upload-pack is supported');
-            res.setHeader('Content-Type', `application/x-${service}-advertisement`);
-            res.setHeader('Cache-Control', 'no-cache');
-            // The Smart HTTP advertisement starts with a PKT-LINE service banner
-            // followed by a flush packet (0000), then the git-upload-pack output.
-            res.write(pktLine(`# service=${service}\n`));
-            res.write(PKT_FLUSH);
-            const args = buildArgs(opt, ['--stateless-rpc', '--advertise-refs', gitDirectory]);
-            const proc = (0, child_process_1.spawn)(gitBin, args, {
-                env: { ...process.env, GIT_PROTOCOL: req.headers['git-protocol'] || '' },
-            });
-            // BUG FIX: the original did not listen for spawn errors (e.g. ENOENT
-            // when git is not installed). Without this handler, a missing binary
-            // causes an uncaught exception that crashes the server process.
-            proc.on('error', (err) => {
-                console.error('[git-upload-pack refs] spawn error:', err.message);
-                if (!res.writableEnded)
-                    res.status(500).send(`git-upload-pack unavailable: ${err.message}`);
-            });
-            proc.stdout.pipe(res);
-            proc.stdout.on('error', (err) => {
-                console.warn('[git-upload-pack refs] stdout error:', err.message);
-            });
-            proc.stderr.on('data', (d) => console.error('[git-upload-pack refs]', d.toString()));
-            proc.on('close', (code) => {
-                if (code !== 0) {
-                    console.error(`[git-upload-pack refs] exited with code ${code}`);
-                    if (!res.writableEnded)
-                        res.status(500).send('git-upload-pack failed');
-                }
-                // When code === 0, proc.stdout has already piped all data and called
-                // res.end() automatically (default pipe behaviour).
-            });
-            return;
-        }
-        // ── POST /git-upload-pack ───────────────────────────────────────────
-        if (req.method === 'POST' && urlPath === '/git-upload-pack') {
-            const contentType = req.headers['content-type'] || '';
-            // BUG FIX: the original called `res.send(415).send(...)`. Our router's
-            // `res.send()` signature is `send(body?)` — passing 415 as the body
-            // writes the number as a string, then the chained `.send()` fails
-            // because `res.send()` already ended the response. Corrected to
-            // `res.status(415).send(...)`.
-            if (contentType !== 'application/x-git-upload-pack-request')
-                return void res.status(415).send('Unsupported Media Type');
-            res.setHeader('Content-Type', 'application/x-git-upload-pack-result');
-            res.setHeader('Cache-Control', 'no-cache');
-            const args = buildArgs(opt, ['--stateless-rpc', gitDirectory]);
-            const proc = (0, child_process_1.spawn)(gitBin, args, {
-                env: { ...process.env, GIT_PROTOCOL: req.headers['git-protocol'] || '' },
-            });
-            // BUG FIX: same missing spawn-error handler as the GET branch.
-            proc.on('error', (err) => {
-                console.error('[git-upload-pack pack] spawn error:', err.message);
-                if (!res.writableEnded)
-                    res.status(500).send(`git-upload-pack unavailable: ${err.message}`);
-            });
-            // Transparently decompress gzip-encoded request bodies.
-            const encoding = req.headers['content-encoding'];
-            if (encoding === 'gzip') {
-                const gunzip = (0, zlib_1.createGunzip)();
-                gunzip.on('error', (err) => {
-                    console.warn('[git-upload-pack pack] gunzip error:', err.message);
-                    if (!res.writableEnded)
-                        res.status(400).send('Failed to decompress request body');
-                });
-                req.pipe(gunzip).pipe(proc.stdin);
-            }
-            else {
-                req.pipe(proc.stdin);
-            }
-            proc.stdout.pipe(res);
-            proc.stdout.on('error', (err) => {
-                console.warn('[git-upload-pack pack] stdout error:', err.message);
-            });
-            // BUG FIX: the original tagged the POST stderr with the same label as
-            // the GET branch ('[git-upload-pack refs]'), making log messages from
-            // the two branches indistinguishable. Corrected to '[git-upload-pack pack]'.
-            proc.stderr.on('data', (d) => console.error('[git-upload-pack pack]', d.toString()));
-            proc.on('close', (code) => {
-                if (code !== 0) {
-                    console.error(`[git-upload-pack pack] exited with code ${code}`);
-                    if (!res.writableEnded)
-                        res.status(500).send('git-upload-pack failed');
-                }
-            });
-            proc.stdin.on('error', (err) => {
-                // EPIPE is expected when the client disconnects mid-stream; it is not
-                // a server-side fault and does not require an error response.
-                if (err.code !== 'EPIPE')
-                    console.warn('[git-upload-pack pack] stdin error:', err.message);
-            });
-            return;
-        }
-        // Unrecognised path inside the repository mount.
-        res.status(404).send('Not found');
-    };
-}
-// ---------------------------------------------------------------------------
-// Internal helpers
-// ---------------------------------------------------------------------------
-/**
- * Build the argument list for `git-upload-pack`.
- *
- * Prepends an optional `--timeout=<n>` argument when configured, then
- * inserts the `--strict` / `--no-strict` flag, followed by any additional
- * arguments the caller provides.
- *
- * @param opt      - Handler options.
- * @param trailing - Arguments appended after the strict flag
- *                   (e.g. `['--stateless-rpc', '--advertise-refs', dir]`).
- * @returns The complete argument array ready for `spawn`.
- */
-function buildArgs(opt, trailing) {
-    const args = [];
-    if (opt.timeout) {
-        // BUG FIX: `parseInt` without an explicit radix may misinterpret strings
-        // that start with '0' as octal in some environments. Always pass base 10.
-        const seconds = parseInt(String(opt.timeout), 10);
-        if (!isNaN(seconds) && seconds > 0)
-            args.push(`--timeout=${seconds}`);
-    }
-    // BUG FIX: the original used `opt.bareOnly ? '--strict' : '--no-strict'`.
-    // `git-upload-pack` does not accept `--strict` — that flag belongs to
-    // `git-receive-pack`. The correct option for upload-pack is `--no-strict`
-    // (which relaxes the requirement that the path must be a bare repository).
-    // When the caller sets `strict: true` we simply omit `--no-strict`; when
-    // `strict` is false (default) we pass `--no-strict` to allow non-bare repos.
-    if (!opt.strict)
-        args.push('--no-strict');
-    return [...args, ...trailing];
-}
-exports.default = gitHandler;
-//# sourceMappingURL=git.js.map