@stonyx/rest-server 0.2.1-alpha.2 → 0.2.1-alpha.21

package/README.md

@@ -1,3 +1,7 @@
+[![CI](https://github.com/abofs/stonyx-rest-server/actions/workflows/ci.yml/badge.svg)](https://github.com/abofs/stonyx-rest-server/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/@stonyx/rest-server.svg)](https://www.npmjs.com/package/@stonyx/rest-server)
+[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+
 # @stonyx/rest-server
 
 REST server module for the [Stonyx framework](https://github.com/abofs/stonyx), providing dynamic route registration and built-in request handling with optional authentication hooks.
@@ -75,9 +79,150 @@ Configuration is read from `stonyx/config` under `restServer`:
 |      `origin`     | **String \| Array** | `'*'`       | CORS origin(s) allowed                                     |
 |    `methods`      | **String**          | `'GET,POST,PATCH,PUT,DELETE'` | CORS allowed methods                              |
 | `enableHealthCheck` |   **Boolean**     | `true`      | Register `GET /health` endpoint (disable via `REST_HEALTH_CHECK_DISABLE=true`) |
+| `caseSensitiveRoutes` | **Boolean**   | `true`      | Match route paths case-sensitively. Disable via `REST_CASE_SENSITIVE_ROUTES=false`. See [Route Matching Strictness](#route-matching-strictness) — **disabling this re-opens a security hole**. |
+| `strictRoutes`    | **Boolean**   | `true`      | Match route paths strictly, so a trailing slash does not match a route registered without one. Disable via `REST_STRICT_ROUTES=false`. See [Route Matching Strictness](#route-matching-strictness) — **disabling this re-opens a security hole**, and note `GET /health/` now 404s. |
 |  `trustProxy`   |     **Boolean**     | `false`     | Trust reverse proxy headers (e.g. `X-Forwarded-Proto`). Enable via `REST_TRUST_PROXY=true` when running behind a load balancer such as AWS ALB/ELB to ensure correct protocol detection. |
 |    `statusMap`    |      **Object**     | `{}`        | Optional mapping of HTTP status codes to custom messages   |
 
+### Route Matching Strictness
+
+Routes match **case-sensitively and strictly by default**. Two settings, both
+on, both applied at both express construction sites:
+
+| axis | setting | example that no longer matches |
+|---|---|---|
+| casing | `case sensitive routing` | `GET /users/Success` -> does not reach `/success` |
+| trailing slash | `strict routing` | `GET /users/success/` -> does not reach `/success` |
+
+Read [What this does not do](#what-this-does-not-do) and
+[Upgrading](#upgrading-behaviour-changes) before you rely on that. Two things
+the table does not say: "does not reach the handler" is not the same as "404",
+and one edge of the trailing-slash axis is **not** closed and cannot be.
+
+This is deliberate and security-relevant. Express matches both case-insensitively
+and slash-insensitively by default, which means any authorization written
+against the request URL can be walked past by changing the case of the request,
+or by appending one character:
+
+```
+GET    /owners/angela   -> 404      (correctly filtered)
+GET    /OwNeRs/angela   -> 200      (full record)     <- closed by case sensitive routing
+GET    /owners/angela/  -> 200      (full record)     <- closed by strict routing
+DELETE /ANIMALS/22      -> 204      (record destroyed)
+DELETE /animals/22/     -> 204      (record destroyed)
+```
+
+The consumer's predicate is stricter than the router that dispatched the
+request, so the router hands the handler a request the predicate would have
+rejected. Measured against this repo's own fixture, before and after:
+
+```
+                          before   after
+GET /private/failure        505      505    (auth hook fires, request blocked)
+GET /private/failure/       200      404    (auth hook never fired; now a miss)
+GET /private/FAILURE        200      200    (absorbed by /:id — see below)
+```
+
+For a handler that authorizes on `req.path`, the path it sees can now only ever
+be the exact registered spelling, in the exact registered casing, with no
+trailing slash. That closes [#47](https://github.com/abofs/stonyx-rest-server/issues/47)
+and [#50](https://github.com/abofs/stonyx-rest-server/issues/50).
+
+#### What this does not do
+
+**It does not close the trailing slash on a mount root, and no setting can.**
+This is the one edge that remains open, so do not read the section above as
+closing the class outright:
+
+```
+GET /public   -> req.path '/'   req.originalUrl '/public'
+GET /public/  -> req.path '/'   req.originalUrl '/public/'
+```
+
+Express's router applies mount-prefix matching with `strict: false`
+unconditionally (`router@2.2.0`, `index.js:400-401`), so both forms reach the
+mounted route class and both arrive with `req.path === '/'`. A hook authorizing
+on `req.path` cannot tell them apart, so for that hook there is no asymmetry to
+exploit. **A hook comparing `req.originalUrl` still sees two different strings,
+and `strictRoutes` does not change that.** If your authorization compares
+`req.originalUrl` rather than `req.path`, keep whatever URL normalization you
+have.
+
+**It does not normalize path *parameter values*.** If your `auth()` hook rejects
+`params.id === 'restricted'`, then `GET /private/RESTRICTED` still reaches the
+handler — the router matched the route correctly, and `restricted` and
+`RESTRICTED` are different values. Record ids are legitimately case-sensitive,
+so this is a comparison your application owns. Compare param values with the
+same case-handling you use when you look them up.
+
+**A sub-path that misses is not necessarily a 404.** If the route class also
+registers a param route such as `/:id`, a mis-cased sub-path is absorbed by it
+rather than rejected. `GET /private/FAILURE` misses `/failure` and is dispatched
+to `/:id` with `id="FAILURE"` — a different handler, at 200, not a miss; this
+repo's AC5 asserts exactly that. A class exposing `/orders/summary` alongside
+`/orders/:id` will send `GET /orders/SUMMARY` into the `/:id` handler and its
+database lookup. The param route's own `auth()` hook still runs, so this is an
+expectation defect rather than a bypass — but plan for a reroute, not a 404.
+
+Note the two axes differ here. A *trailing slash* is not absorbed by `/:id`,
+because `/:id` is equally strict: `GET /private/failure/` misses `/failure` and
+misses `/:id`, and is a true 404.
+
+**It does not redirect or rewrite** mixed-case or trailing-slash requests to
+their canonical form. Whether `/Users` is a typo to forgive or an attack to
+reject is an application policy decision, and encoding it here would mint
+another variant of the bug above.
+
+#### Upgrading: behaviour changes
+
+Both settings change which requests match, so both are consumer-visible.
+
+**`GET /health/` now returns 404.** `GET /health` is unaffected. This is the
+change most likely to page someone, and it is an **availability** problem rather
+than a 404 you will read about in a log: if a Kubernetes liveness probe, an ELB
+target-group health check or an uptime monitor is pointed at the trailing-slash
+form, it starts failing and the deployment gets marked unhealthy and cycled.
+This module emits no request logging, so the only symptom is the probe going
+red. **Check your probe URLs before upgrading.**
+
+Also affected:
+
+- **Param routes.** `/resource/:id/` no longer matches. Any client calling
+  `/private/restricted/` gets a 404 where it previously got the param route.
+- **Trailing-slash-normalizing proxies.** nginx `try_files`/`rewrite`, Apache
+  `DirectorySlash On` and some CDN edge rules append a slash; behind one of
+  those, every route stops matching at once.
+- **Mount paths from filenames.** With `camelCaseRoutes` truthy, `phone-number.ts`
+  mounts at `/phoneNumber`, so `GET /phonenumber` returns 404; with it falsy,
+  `Users.ts` mounts at `/Users`, so `GET /users` returns 404.
+
+A request that stops matching returns express's default `404 Cannot GET /x` with
+no log line and no stack, so it looks like a deploy that dropped a route.
+
+#### Opting out
+
+Two separate flags, one per axis:
+
+```bash
+REST_CASE_SENSITIVE_ROUTES=false   # restores case-insensitive matching (#47)
+REST_STRICT_ROUTES=false           # restores trailing-slash tolerance (#50)
+```
+
+or equivalently `restServer: { caseSensitiveRoutes: false, strictRoutes: false }`.
+
+**They are deliberately separate keys, and neither implies the other.** Slash
+tolerance is a legitimate need — a health-check URL you cannot change today is
+the common case. Casing tolerance almost never is. Folding them into one flag
+would force anyone who needs the first to accept the second, which is why a
+consumer who took the `#47` opt-out still has to set `REST_STRICT_ROUTES=false`
+separately to keep trailing slashes working.
+
+**Each flag restores the corresponding vulnerability described above** — the
+URL-based authorization in your application becomes bypassable along that axis
+again. They exist as one-line remediations for an existing deployment, not as a
+configuration to run on. Set the flag to restore service, then fix the client
+and remove the flag.
+
 ### Running Behind a Load Balancer
 
 When your application runs behind a reverse proxy or load balancer (e.g. AWS ALB/ELB), the load balancer terminates SSL and forwards requests to your server over HTTP internally. This means Express sees `http` as the protocol even though the original client request used `https`.

package/config/environment.js

@@ -1,13 +1,68 @@
 const {
+  REST_CASE_SENSITIVE_ROUTES,
   REST_CORS_ORIGIN,
   REST_CORS_METHODS,
   REST_HEALTH_CHECK_DISABLE,
   REST_PORT,
   REST_REQUEST_PATH,
+  REST_STRICT_ROUTES,
   REST_TRUST_PROXY
-} = process;
+} = process.env;
+
+const config = {
+  // Secure by default: routes match case-sensitively so a consumer's
+  // URL-based authorization cannot be walked past by changing case
+  // (abofs/stonyx-rest-server#47). Opt out with REST_CASE_SENSITIVE_ROUTES=false
+  // only as a temporary remediation for a client that relies on loose casing.
+  //
+  // DELIBERATELY NOT PINNED in test/config/environment.ts -- do not "fix" this
+  // as part of abofs/stonyx-rest-server#43. This line is the only thing the
+  // suite still checks about the SHIPPED default. Inverting it to
+  // `=== 'true'` turns AC3, AC4 and AC5 red; AC6 stays GREEN, because AC6
+  // stubs `caseSensitiveRoutes` to `undefined` and src/route-matching.ts reads
+  // `!== false`, so AC6 guards the source's read and not this default.
+  // Measured: pin `caseSensitiveRoutes: true` in test/config/environment.ts AND
+  // invert this line, and the suite reports 28 pass / 0 fail. A naive pin makes
+  // an insecure published default completely invisible to a green suite --
+  // quieter and weaker, which is the outcome pinning was supposed to prevent.
+  //
+  // The cost of leaving it unpinned is that the suite is ambient-sensitive here
+  // (`REST_CASE_SENSITIVE_ROUTES=false pnpm test` => 25 pass / 3 fail), but it
+  // fails LOUDLY, so there is no false green. Closing #43 for this key needs
+  // the subprocess-based env isolation this repo does not yet have; any fix
+  // must keep a live assertion on this default.
+  caseSensitiveRoutes: REST_CASE_SENSITIVE_ROUTES !== 'false',
+
+  // Secure by default, same polarity and same reasoning as caseSensitiveRoutes
+  // above: routes match strictly, so a trailing slash cannot walk past a
+  // consumer's URL-based authorization (abofs/stonyx-rest-server#50).
+  //
+  // BEHAVIOUR CHANGE for consumers upgrading: `/health/` now returns 404, and
+  // param routes like `/resource/:id/` no longer match. Opt out with
+  // REST_STRICT_ROUTES=false only as a temporary remediation. It is a separate
+  // key from REST_CASE_SENSITIVE_ROUTES on purpose -- opting out of slash
+  // strictness must not silently re-open #47's case bypass.
+  //
+  // DELIBERATELY NOT PINNED in test/config/environment.ts -- do not "fix" this
+  // as part of abofs/stonyx-rest-server#43. Same trap as the key above, and now
+  // measured for both: pin `strictRoutes: true` in test/config/environment.ts
+  // AND invert this line to `=== 'true'`, and the suite reports 31 pass /
+  // 0 fail. A naive pin makes an insecure published default completely
+  // invisible to a green suite.
+  //
+  // Unpinned, inverting this line alone turns #50's AC1 and AC2 red (29/2).
+  // AC3 stays GREEN under that mutation, because AC3 sets `strictRoutes` on the
+  // config object directly and so guards src/route-matching.ts's READ rather
+  // than this default -- the two assertions cover different halves and neither
+  // subsumes the other.
+  //
+  // The cost is that the suite is ambient-sensitive here
+  // (`REST_STRICT_ROUTES=false pnpm test` => 29 pass / 2 fail), but it fails
+  // LOUDLY, so there is no false green. Closing #43 for either key needs
+  // subprocess-based env isolation this repo does not have; any fix must keep a
+  // live assertion on this default.
+  strictRoutes: REST_STRICT_ROUTES !== 'false',
 
-export default {
   enableHealthCheck: REST_HEALTH_CHECK_DISABLE !== 'true',
   origin: REST_CORS_ORIGIN ?? '*',
   methods: REST_CORS_METHODS ?? 'GET,POST,PATCH,PUT,DELETE',
@@ -17,3 +72,5 @@ export default {
   logColor: 'yellow',
   logMethod: 'api'
 };
+
+export default config;

package/dist/main.d.ts

@@ -0,0 +1,18 @@
+import { type Express } from 'express';
+import type { Server } from 'http';
+export { default as Request } from './request.js';
+export default class RestServer {
+    static instance: RestServer;
+    api: Express;
+    server: Server;
+    constructor();
+    static close(): void;
+    init(): Promise<void>;
+    setupRouter(): Promise<void>;
+    setupGlobalMiddleware(): void;
+    mountRoute(routeClassUntyped: unknown, { name, options }: {
+        name: string;
+        options?: unknown;
+    }): void;
+}
+//# sourceMappingURL=main.d.ts.map

package/dist/main.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../src/main.ts"],"names":[],"mappings":"AAiBA,OAAgB,EAAE,KAAK,OAAO,EAAoE,MAAM,SAAS,CAAC;AAKlH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,MAAM,CAAC;AAEnC,OAAO,EAAE,OAAO,IAAI,OAAO,EAAE,MAAM,cAAc,CAAC;AAElD,MAAM,CAAC,OAAO,OAAO,UAAU;IAC7B,MAAM,CAAC,QAAQ,EAAE,UAAU,CAAC;IAE5B,GAAG,EAAG,OAAO,CAAC;IACd,MAAM,EAAG,MAAM,CAAC;;IAgBhB,MAAM,CAAC,KAAK,IAAI,IAAI;IAQd,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAerB,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC;IAelC,qBAAqB,IAAI,IAAI;IAW7B,UAAU,CAAC,iBAAiB,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI;CAarG"}

package/dist/main.js

@@ -0,0 +1,93 @@
+/*
+ * Copyright 2025 Stone Costa
+ *
+ * Licensed under the Apache License, Version 2.0 (the 'License');
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import cors from 'cors';
+import express from 'express';
+import config from 'stonyx/config';
+import log from 'stonyx/log';
+import { forEachFileImport } from '@stonyx/utils/file';
+import applyRouteMatching from './route-matching.js';
+export { default as Request } from './request.js';
+export default class RestServer {
+    static instance;
+    api;
+    server;
+    constructor() {
+        if (RestServer.instance)
+            return RestServer.instance;
+        RestServer.instance = this;
+        this.api = express();
+        // Closes the mount segment (/PUBLIC/...) for abofs/stonyx-rest-server#47.
+        // Must stay in the constructor: the router is materialized lazily on first
+        // route registration, so applying this after setupRouter() is silently
+        // ineffective. The matching call in Request's constructor is what closes
+        // sub-paths -- see src/route-matching.ts for why both are required.
+        applyRouteMatching(this.api);
+    }
+    static close() {
+        if (!RestServer.instance)
+            throw new Error('RestServer has not been initialized yet');
+        const { server } = RestServer.instance;
+        server.closeAllConnections();
+        server.close();
+    }
+    async init() {
+        // Self-register so log.api works even when @stonyx/rest-server is in the
+        // consumer's `dependencies` (stonyx loader only merges devDependencies).
+        const { logColor = 'yellow', logMethod = 'api' } = config.restServer;
+        log.defineType(logMethod, logColor);
+        await this.setupRouter();
+        const { port } = config.restServer;
+        // start REST server
+        this.server = this.api.listen(port);
+        log.title(`API Server is listening on port ${port}`);
+    }
+    async setupRouter() {
+        const { camelCaseRoutes, dir, enableHealthCheck } = config.restServer;
+        this.setupGlobalMiddleware();
+        try {
+            await forEachFileImport(dir, this.mountRoute.bind(this), { rawName: !camelCaseRoutes, ignoreAccessFailure: true });
+            if (enableHealthCheck)
+                this.api.get('/health', (_req, res) => res.sendStatus(200));
+        }
+        catch (error) {
+            if (config.debug)
+                console.log(error);
+            log.error(`Unable to dynamically configure routes from files in ${dir}`);
+            throw new Error(`Unable to dynamically configure routes from files in ${dir}`);
+        }
+    }
+    setupGlobalMiddleware() {
+        const { origin, methods, trustProxy } = config.restServer;
+        if (trustProxy)
+            this.api.set('trust proxy', true);
+        this.api.use([
+            cors({ origin, methods }),
+            express.json()
+        ]);
+    }
+    mountRoute(routeClassUntyped, { name, options }) {
+        const routeClass = routeClassUntyped;
+        const { api } = this;
+        const classInstance = new routeClass(options);
+        const route = name === 'index' ? '/' : `/${name}`;
+        const { expressInstance } = classInstance;
+        classInstance.registerCalls();
+        expressInstance.mountpath = route;
+        // Mount handler to main api instance
+        api.use(route, expressInstance);
+    }
+}
+//# sourceMappingURL=main.js.map

package/dist/main.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"main.js","sourceRoot":"","sources":["../src/main.ts"],"names":[],"mappings":"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"}

package/dist/request.d.ts

@@ -0,0 +1,16 @@
+import { type Request as ExpressRequest, type Response as ExpressResponse, type Express } from 'express';
+export type RequestState = Record<string, unknown>;
+export type RequestHandler = (req: ExpressRequest, state: RequestState) => unknown | Promise<unknown>;
+export type AuthHandler = (req: ExpressRequest, state: RequestState) => number | undefined;
+export type RouteHandlers = Record<string, Record<string, RequestHandler | RequestHandler[]>>;
+export default class Request {
+    static stateProp: string;
+    static getState(req: ExpressRequest): RequestState;
+    static sendStatusResponse(res: ExpressResponse, status: number): void;
+    expressInstance: Express;
+    handlers: RouteHandlers;
+    auth?: AuthHandler;
+    constructor();
+    registerCalls(): void;
+}
+//# sourceMappingURL=request.d.ts.map

package/dist/request.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"request.d.ts","sourceRoot":"","sources":["../src/request.ts"],"names":[],"mappings":"AAAA,OAAgB,EAAE,KAAK,OAAO,IAAI,cAAc,EAAE,KAAK,QAAQ,IAAI,eAAe,EAAE,KAAK,OAAO,EAAE,MAAM,SAAS,CAAC;AAOlH,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AACnD,MAAM,MAAM,cAAc,GAAG,CAAC,GAAG,EAAE,cAAc,EAAE,KAAK,EAAE,YAAY,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;AACtG,MAAM,MAAM,WAAW,GAAG,CAAC,GAAG,EAAE,cAAc,EAAE,KAAK,EAAE,YAAY,KAAK,MAAM,GAAG,SAAS,CAAC;AAC3F,MAAM,MAAM,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,GAAG,cAAc,EAAE,CAAC,CAAC,CAAC;AAE9F,MAAM,CAAC,OAAO,OAAO,OAAO;IAC1B,MAAM,CAAC,SAAS,SAAmB;IAEnC,MAAM,CAAC,QAAQ,CAAC,GAAG,EAAE,cAAc,GAAG,YAAY;IASlD,MAAM,CAAC,kBAAkB,CAAC,GAAG,EAAE,eAAe,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI;IAWrE,eAAe,EAAE,OAAO,CAAC;IACzB,QAAQ,EAAG,aAAa,CAAC;IACjB,IAAI,CAAC,EAAE,WAAW,CAAC;;IAe3B,aAAa,IAAI,IAAI;CAqDtB"}

package/dist/request.js

@@ -0,0 +1,93 @@
+import express from 'express';
+import config from 'stonyx/config';
+import { makeArray } from '@stonyx/utils/object';
+import applyRouteMatching from './route-matching.js';
+const METHODS = new Set(['get', 'post', 'put', 'delete', 'patch']);
+export default class Request {
+    static stateProp = '__stonyxState';
+    static getState(req) {
+        const { stateProp } = Request;
+        const record = req;
+        if (record[stateProp] !== undefined)
+            return record[stateProp];
+        record[stateProp] = {};
+        return record[stateProp];
+    }
+    static sendStatusResponse(res, status) {
+        const statusMap = config.restServer?.statusMap ?? {};
+        const message = statusMap[status] || '';
+        if (message) {
+            res.status(status).send(message);
+        }
+        else {
+            res.sendStatus(status);
+        }
+    }
+    expressInstance;
+    handlers;
+    constructor() {
+        const api = express();
+        api.disable('x-powered-by');
+        // Closes sub-paths (/public/SUCCESS) for abofs/stonyx-rest-server#47.
+        // Must stay in the constructor: registerCalls() materializes this router,
+        // and a set applied afterwards has no effect. The parent app's setting
+        // does not reach here -- see src/route-matching.ts.
+        applyRouteMatching(api);
+        this.expressInstance = api;
+    }
+    registerCalls() {
+        const { expressInstance } = this;
+        const { getState, sendStatusResponse } = Request;
+        for (const [method, handlers] of Object.entries(this.handlers)) {
+            if (!METHODS.has(method)) {
+                console.warn(`Method "${method}" is not a valid HTTP method. Skipping...`);
+                continue;
+            }
+            for (const [route, handler] of Object.entries(handlers)) {
+                expressInstance[method](route, async (req, res) => {
+                    // Run auth after route matching so request.params is populated
+                    if (this.auth) {
+                        const status = this.auth(req, getState(req));
+                        if (status)
+                            return sendStatusResponse(res, status);
+                    }
+                    const callStack = [...makeArray(handler)];
+                    const mainCall = callStack.pop();
+                    let response;
+                    // Run middleware
+                    while (callStack.length) {
+                        response = await callStack.shift().bind(this)(req, getState(req));
+                        if (response !== undefined)
+                            break;
+                    }
+                    if (response === undefined)
+                        response = await mainCall(req, getState(req));
+                    if (Number.isInteger(response))
+                        return sendStatusResponse(res, response);
+                    // Handle redirect if set via call state object
+                    const state = getState(req);
+                    const { redirect } = state;
+                    if (redirect)
+                        return res.redirect(redirect);
+                    // Handle pipe if set via call state object
+                    const { pipe } = state;
+                    if (pipe) {
+                        const { headers, source } = pipe;
+                        if (headers)
+                            for (const [key, value] of Object.entries(headers))
+                                res.set(key, value);
+                        return source.pipe(res);
+                    }
+                    if (response === undefined) {
+                        res.sendStatus(200);
+                        return;
+                    }
+                    if (typeof response !== 'object')
+                        return sendStatusResponse(res, 500);
+                    res.send(response);
+                });
+            }
+        }
+    }
+}
+//# sourceMappingURL=request.js.map

package/dist/request.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"request.js","sourceRoot":"","sources":["../src/request.ts"],"names":[],"mappings":"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"}

package/dist/route-matching.d.ts

@@ -0,0 +1,77 @@
+import type { Express } from 'express';
+/**
+ * Applies this module's route-matching settings to an express app.
+ *
+ * Called from BOTH express construction sites (abofs/stonyx-rest-server#47):
+ * `RestServer`'s constructor closes the mount segment (`/PUBLIC/...`), and
+ * `Request`'s constructor closes sub-paths (`/public/SUCCESS`). Neither alone
+ * is sufficient -- settings are inherited on mount, but `mountRoute()` calls
+ * `registerCalls()` before `api.use()`, so each child router is already built
+ * by the time the parent's setting could reach it.
+ *
+ * Both callers invoke this from a constructor, and must keep doing so: express
+ * materializes a router lazily on first route registration, and a setting
+ * applied afterwards is silently ineffective -- no throw, no warning.
+ *
+ * The guard is `!== false`, not a plain truthy check, and that polarity is
+ * load-bearing. `trustProxy` and `enableHealthCheck` default to the falsy
+ * direction, so a missing key fails safe for them. This flag defaults to the
+ * truthy direction, so `if (config.restServer?.caseSensitiveRoutes)` would
+ * silently fail OPEN for a consumer whose shipped config predates the key.
+ *
+ * It lives here, in one place, rather than being written out at each call
+ * site, so that a single test can anchor it. The invariant is duplicated the
+ * moment the expression is: `test/unit/request-test.ts` AC6 reaches this
+ * function through `Request`, which means the same assertion now also covers
+ * the `RestServer` half. Two copies of the predicate left the parent's copy
+ * free to drift -- inverting it, or dropping the condition entirely, kept the
+ * suite green.
+ *
+ * Note `express({ caseSensitive: true })` does NOT work: express 5's
+ * `createApplication()` takes zero arguments and forwards nothing. The app
+ * setting is the only mechanism. The same is true of `strict`.
+ *
+ * ---
+ *
+ * `strict routing` (abofs/stonyx-rest-server#50) closes the same class of
+ * authorization bypass for a TRAILING SLASH: `GET /private/failure` was denied
+ * by a consumer's auth hook while `GET /private/failure/` reached the guarded
+ * handler, because the hook compares `req.path` against `/failure`.
+ *
+ * It is a SEPARATE key from `caseSensitiveRoutes`, not a rename and not a
+ * reuse. Coupling them would force any consumer who legitimately needs
+ * trailing-slash tolerance -- a load balancer probing `/health/`, a
+ * slash-normalizing proxy -- to re-open #47's case bypass to get it. Case
+ * insensitivity is almost never intentional; slash tolerance frequently is.
+ *
+ * The two settings do NOT share the #47 split above, and this is the one thing
+ * not to carry across from that fix. For `strict routing`:
+ *
+ *   - The CHILD site (Request's constructor) closes the entire security
+ *     defect on its own. The parent site does nothing for it.
+ *   - The PARENT site (RestServer's constructor) closes exactly one thing in
+ *     this repo: `/health/`, the only route registered directly on the parent
+ *     app. It has no security role here; do not describe it as having one.
+ *
+ * The cause is concrete: router@2.2.0 `index.js:400-401` hardcodes
+ * `strict: false, end: false` for `Router.prototype.use`, so mount segments
+ * are structurally strict-immune. That is the OPPOSITE of `sensitive`, which
+ * `use()` does forward (line 399) and which is why #47's parent site closed
+ * `/PUBLIC/...`. Both sites still get both settings -- they share this
+ * function -- but the justification differs and the tests are built on the
+ * measured split, not on the analogy.
+ *
+ * Consequence worth stating so nobody "fixes" it: the mount-segment trailing
+ * slash (`/public/`) can never be closed by this setting, and does not need to
+ * be. For both `/public` and `/public/` the mounted sub-app receives
+ * `req.path === '/'`, so a `req.path` auth hook sees no difference and there is
+ * no asymmetry. A test asserting `/public/` -> 404 could never pass. The
+ * residual is `req.originalUrl`, which DOES differ; that is disclosed in the
+ * README rather than silently closed over.
+ *
+ * Both guards are `!== false` for the same reason: these flags default to the
+ * truthy direction, so a truthy check fails OPEN for a consumer whose shipped
+ * config predates the key.
+ */
+export default function applyRouteMatching(api: Express): void;
+//# sourceMappingURL=route-matching.d.ts.map

package/dist/route-matching.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"route-matching.d.ts","sourceRoot":"","sources":["../src/route-matching.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAGvC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyEG;AACH,MAAM,CAAC,OAAO,UAAU,kBAAkB,CAAC,GAAG,EAAE,OAAO,GAAG,IAAI,CAG7D"}

package/dist/route-matching.js

@@ -0,0 +1,82 @@
+import config from 'stonyx/config';
+/**
+ * Applies this module's route-matching settings to an express app.
+ *
+ * Called from BOTH express construction sites (abofs/stonyx-rest-server#47):
+ * `RestServer`'s constructor closes the mount segment (`/PUBLIC/...`), and
+ * `Request`'s constructor closes sub-paths (`/public/SUCCESS`). Neither alone
+ * is sufficient -- settings are inherited on mount, but `mountRoute()` calls
+ * `registerCalls()` before `api.use()`, so each child router is already built
+ * by the time the parent's setting could reach it.
+ *
+ * Both callers invoke this from a constructor, and must keep doing so: express
+ * materializes a router lazily on first route registration, and a setting
+ * applied afterwards is silently ineffective -- no throw, no warning.
+ *
+ * The guard is `!== false`, not a plain truthy check, and that polarity is
+ * load-bearing. `trustProxy` and `enableHealthCheck` default to the falsy
+ * direction, so a missing key fails safe for them. This flag defaults to the
+ * truthy direction, so `if (config.restServer?.caseSensitiveRoutes)` would
+ * silently fail OPEN for a consumer whose shipped config predates the key.
+ *
+ * It lives here, in one place, rather than being written out at each call
+ * site, so that a single test can anchor it. The invariant is duplicated the
+ * moment the expression is: `test/unit/request-test.ts` AC6 reaches this
+ * function through `Request`, which means the same assertion now also covers
+ * the `RestServer` half. Two copies of the predicate left the parent's copy
+ * free to drift -- inverting it, or dropping the condition entirely, kept the
+ * suite green.
+ *
+ * Note `express({ caseSensitive: true })` does NOT work: express 5's
+ * `createApplication()` takes zero arguments and forwards nothing. The app
+ * setting is the only mechanism. The same is true of `strict`.
+ *
+ * ---
+ *
+ * `strict routing` (abofs/stonyx-rest-server#50) closes the same class of
+ * authorization bypass for a TRAILING SLASH: `GET /private/failure` was denied
+ * by a consumer's auth hook while `GET /private/failure/` reached the guarded
+ * handler, because the hook compares `req.path` against `/failure`.
+ *
+ * It is a SEPARATE key from `caseSensitiveRoutes`, not a rename and not a
+ * reuse. Coupling them would force any consumer who legitimately needs
+ * trailing-slash tolerance -- a load balancer probing `/health/`, a
+ * slash-normalizing proxy -- to re-open #47's case bypass to get it. Case
+ * insensitivity is almost never intentional; slash tolerance frequently is.
+ *
+ * The two settings do NOT share the #47 split above, and this is the one thing
+ * not to carry across from that fix. For `strict routing`:
+ *
+ *   - The CHILD site (Request's constructor) closes the entire security
+ *     defect on its own. The parent site does nothing for it.
+ *   - The PARENT site (RestServer's constructor) closes exactly one thing in
+ *     this repo: `/health/`, the only route registered directly on the parent
+ *     app. It has no security role here; do not describe it as having one.
+ *
+ * The cause is concrete: router@2.2.0 `index.js:400-401` hardcodes
+ * `strict: false, end: false` for `Router.prototype.use`, so mount segments
+ * are structurally strict-immune. That is the OPPOSITE of `sensitive`, which
+ * `use()` does forward (line 399) and which is why #47's parent site closed
+ * `/PUBLIC/...`. Both sites still get both settings -- they share this
+ * function -- but the justification differs and the tests are built on the
+ * measured split, not on the analogy.
+ *
+ * Consequence worth stating so nobody "fixes" it: the mount-segment trailing
+ * slash (`/public/`) can never be closed by this setting, and does not need to
+ * be. For both `/public` and `/public/` the mounted sub-app receives
+ * `req.path === '/'`, so a `req.path` auth hook sees no difference and there is
+ * no asymmetry. A test asserting `/public/` -> 404 could never pass. The
+ * residual is `req.originalUrl`, which DOES differ; that is disclosed in the
+ * README rather than silently closed over.
+ *
+ * Both guards are `!== false` for the same reason: these flags default to the
+ * truthy direction, so a truthy check fails OPEN for a consumer whose shipped
+ * config predates the key.
+ */
+export default function applyRouteMatching(api) {
+    if (config.restServer?.caseSensitiveRoutes !== false)
+        api.set('case sensitive routing', true);
+    if (config.restServer?.strictRoutes !== false)
+        api.set('strict routing', true);
+}
+//# sourceMappingURL=route-matching.js.map

package/dist/route-matching.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"route-matching.js","sourceRoot":"","sources":["../src/route-matching.ts"],"names":[],"mappings":"AACA,OAAO,MAAM,MAAM,eAAe,CAAC;AAEnC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyEG;AACH,MAAM,CAAC,OAAO,UAAU,kBAAkB,CAAC,GAAY;IACrD,IAAI,MAAM,CAAC,UAAU,EAAE,mBAAmB,KAAK,KAAK;QAAE,GAAG,CAAC,GAAG,CAAC,wBAAwB,EAAE,IAAI,CAAC,CAAC;IAC9F,IAAI,MAAM,CAAC,UAAU,EAAE,YAAY,KAAK,KAAK;QAAE,GAAG,CAAC,GAAG,CAAC,gBAAgB,EAAE,IAAI,CAAC,CAAC;AACjF,CAAC"}

package/package.json

@@ -4,22 +4,31 @@
     "stonyx-async",
     "stonyx-module"
   ],
-  "version": "0.2.1-alpha.2",
+  "version": "0.2.1-alpha.21",
   "description": "Rest Server Module for Stonyx Framework",
   "repository": {
     "type": "git",
     "url": "https://github.com/abofs/stonyx-rest-server"
   },
-  "main": "src/main.js",
+  "main": "dist/main.js",
+  "types": "dist/main.d.ts",
   "type": "module",
   "exports": {
-    ".": "./src/main.js"
+    ".": {
+      "types": "./dist/main.d.ts",
+      "default": "./dist/main.js"
+    }
   },
   "author": "Stone Costa",
   "license": "Apache-2.0",
   "contributors": [
     "Stone Costa <stone.costa@synamicd.com>"
   ],
+  "files": [
+    "dist",
+    "config",
+    "README.md"
+  ],
   "publishConfig": {
     "access": "public",
     "provenance": true
@@ -27,14 +36,23 @@
   "dependencies": {
     "cors": "^2.8.5",
     "express": "^5.1.0",
-    "stonyx": "0.2.3-beta.2"
+    "stonyx": "0.2.3-beta.78"
   },
   "devDependencies": {
-    "@stonyx/utils": "0.2.3-beta.3",
+    "@stonyx/utils": "0.2.3-beta.26",
+    "@types/cors": "^2.8.17",
+    "@types/express": "^5.0.6",
+    "@types/node": "^25.5.2",
+    "@types/qunit": "^2.19.13",
+    "@types/sinon": "^21.0.1",
     "qunit": "^2.24.1",
-    "sinon": "^21.0.0"
+    "sinon": "^21.0.0",
+    "tsx": "^4.21.0",
+    "typescript": "^5.8.3"
   },
   "scripts": {
-    "test": "stonyx test"
+    "build": "tsc",
+    "typecheck": "tsc -p tsconfig.test.json",
+    "test": "pnpm build && pnpm typecheck && NODE_ENV=test node --import tsx/esm --import ./test/setup.ts node_modules/qunit/bin/qunit.js 'test/**/*-test.ts'"
   }
 }

package/.claude/improvements.md

@@ -1,44 +0,0 @@
-# Improvement Opportunities
-
-## 1. `new express()` in RestServer constructor
-
-**File**: `src/main.js`, line 30
-
-```js
-this.api = new express();
-```
-
-Express 5 (which this project targets via `"express": "^5.1.0"`) documents calling `express()` as a plain function, not as a constructor with `new`. While `new express()` works in practice because the function returns a new object regardless, it is unconventional and may break if Express ever enforces non-constructor semantics. Consider changing to:
-
-```js
-this.api = express();
-```
-
-Note: The `Request` class in `src/request.js` line 26 already uses the correct pattern (`const api = express();` without `new`).
-
-## 2. `setupGlobalMiddleware` is `async` but contains no awaits
-
-**File**: `src/main.js`, lines 63-70
-
-```js
-async setupGlobalMiddleware() {
-  const { origin, methods } = config.restServer;
-
-  this.api.use([
-    cors({ origin, methods }),
-    express.json()
-  ]);
-}
-```
-
-The `async` keyword is unnecessary here since the method body contains no `await` expressions and `app.use()` is synchronous. The `async` keyword causes the method to return a `Promise` wrapping `undefined`, but the caller (`setupRouter`) does not `await` it either — it calls `this.setupGlobalMiddleware()` without `await` on line 52. Removing `async` would make the intent clearer.
-
-## 3. `logMethod` config option is not used in rest-server source
-
-**File**: `config/environment.js`, line 16
-
-```js
-logMethod: 'api'
-```
-
-The `logMethod` property is defined in the default config but is never referenced anywhere in `src/main.js` or `src/request.js`. It is likely consumed by the Stonyx framework core (`stonyx/log`) for registering a named log method, but this should be verified. If it is indeed framework-level plumbing, consider documenting that it is a Stonyx convention rather than a rest-server feature. If it is unused, consider removing it to reduce config surface area.

package/.claude/project-structure.md

@@ -1,150 +0,0 @@
-# @stonyx/rest-server — Project Structure
-
-## Overview
-
-REST server module for the Stonyx framework. Provides dynamic route registration from a file directory, built-in CORS/JSON middleware, per-route authorization hooks, and a structured `Request` base class for defining handlers.
-
-- **Package**: `@stonyx/rest-server` (v0.2.1-beta.1)
-- **License**: Apache-2.0
-- **Entry point**: `src/main.js`
-- **Module type**: ESM (`"type": "module"`)
-- **Node version**: v24.13.0 (per `.nvmrc`)
-- **Package manager**: pnpm
-
-## Architecture
-
-### RestServer (src/main.js)
-
-Singleton class wrapping an Express 5 instance.
-
-- **Constructor** — enforces singleton via `RestServer.instance`; creates the Express app with `new express()`
-- **`init()`** — calls `setupRouter()`, then starts listening on the configured port
-- **`setupRouter()`** — calls `setupGlobalMiddleware()`, then uses `forEachFileImport` (from `@stonyx/utils/file`) to dynamically import all files in the configured `dir` and mount each as a route via `mountRoute()`. Optionally registers a `/health` endpoint.
-- **`setupGlobalMiddleware()`** — attaches `cors()` and `express.json()` middleware to the Express app
-- **`mountRoute(routeClass, { name, options })`** — instantiates the imported Request subclass, wires up the `authorization` middleware if present, calls `registerCalls()`, and mounts the sub-app at `/<filename>`
-- **`RestServer.close()`** — static method to close the server
-
-### Request (src/request.js)
-
-Base class for route definitions. Each file in the requests directory exports a class extending `Request`.
-
-- **Constructor** — creates a child Express instance with `x-powered-by` disabled
-- **`handlers`** — instance property: object mapping HTTP methods (`get`, `post`, `put`, `delete`, `patch`) to route-path/handler pairs
-- **`auth(req, state)`** — optional hook. Return an integer status code to reject the request; return nothing to allow it through.
-- **`authorization(req, res, next)`** — wrapper that calls `auth()` and short-circuits with a status response if it returns a code
-- **`registerCalls()`** — iterates `handlers`, registers each route on the child Express instance. Supports:
-  - Single handler function or array (last element is the main handler, preceding elements are middleware)
-  - Middleware functions are bound to the class instance and executed in order
-  - Integer return = status code response (via `sendStatusResponse`)
-  - Object return = JSON response
-  - `undefined` return = 200 OK
-  - Pipe support via `state.pipe` (sets headers and pipes a stream)
-- **`Request.getState(req)`** — attaches/retrieves a `__stonyxState` object on the Express request
-- **`Request.sendStatusResponse(res, status)`** — sends status with optional custom message from `config.restServer.statusMap`
-
-Valid HTTP methods (enforced): `get`, `post`, `put`, `delete`, `patch`
-
-## Configuration Reference
-
-From `config/environment.js`. All values are overridable via environment variables.
-
-| Option              | Type              | Default                       | Env Var                    | Description                                                     |
-|---------------------|-------------------|-------------------------------|----------------------------|-----------------------------------------------------------------|
-| `enableHealthCheck` | **Boolean**       | `true`                        | `REST_HEALTH_CHECK_DISABLE=true` to disable | Registers `GET /health` returning 200                     |
-| `trustProxy`        | **Boolean**       | `false`                       | `REST_TRUST_PROXY=true` to enable           | Trust reverse proxy headers (`X-Forwarded-Proto`) for correct protocol detection behind load balancers |
-| `origin`            | **String**        | `'*'`                         | `REST_CORS_ORIGIN`         | CORS allowed origin(s)                                          |
-| `methods`           | **String**        | `'GET,POST,PATCH,PUT,DELETE'` | `REST_CORS_METHODS`        | CORS allowed methods                                            |
-| `dir`               | **String**        | `'./requests'`                | `REST_REQUEST_PATH`        | Directory containing Request class files to mount as routes     |
-| `port`              | **Number/String** | `2666`                        | `REST_PORT`                | Port the REST server listens on                                 |
-| `logColor`          | **String**        | `'yellow'`                    | —                          | Console log color for this module (Stonyx logging integration)  |
-| `logMethod`         | **String**        | `'api'`                       | —                          | Log method name (Stonyx logging integration)                    |
-
-Additional config used (not rest-server-specific):
-- `config.debug` (top-level Stonyx config) — if truthy, logs errors during route setup
-- `config.restServer.statusMap` (optional, no default in environment.js) — maps status codes to custom message strings
-- `config.restServer.camelCaseRoutes` (optional, no default in environment.js) — when falsy, passes `rawName: true` to `forEachFileImport` so filenames are used as-is for route paths
-
-## Test Structure
-
-Tests use **QUnit** and run via `stonyx test` (the `npm test` script).
-
-### test/config/environment.js
-Overrides `restServer.dir` to `'./test/sample/requests'` so tests load sample request classes.
-
-### test/unit/request-test.js
-Unit tests for `Request` static methods:
-- `getState` — creates/returns state object on request
-- `sendStatusResponse` — sends status with optional `statusMap` message
-
-### test/integration/rest-server-test.js
-Integration tests that boot the full server and make HTTP requests:
-- 404 for non-existent routes
-- `/public` — JSON response, 200 OK default, URL params, middleware (success/failure), `this` binding for handlers and middleware
-- `/private` — authenticated success, auth hook rejection (505)
-- `/health` — health check endpoint returns 200
-
-### test/sample/requests/
-Sample Request subclasses used by integration tests:
-- `public.js` — `PublicRequest` with various GET handlers demonstrating middleware, params, binding
-- `private.js` — `PrivateRequest` with `auth()` hook that rejects `/failure` with 505
-
-## CI/CD
-
-### .github/workflows/ci.yml
-Runs on pull requests to `dev` and `main`. Delegates to shared workflow at `abofs/stonyx-workflows`.
-
-### .github/workflows/publish.yml
-Publishes to NPM. Triggered by:
-- `workflow_dispatch` with version-type selection (patch/minor/major) or custom version
-- Pull requests to `main`/`dev`
-- Pushes to `main`
-
-Delegates to `abofs/stonyx-workflows/.github/workflows/npm-publish.yml@main`.
-
-## File Structure
-
-```
-stonyx-rest-server/
-├── .claude/
-│   ├── improvements.md
-│   └── project-structure.md      # this file
-├── .github/
-│   └── workflows/
-│       ├── ci.yml                 # PR CI — delegates to shared workflow
-│       └── publish.yml            # NPM publish — delegates to shared workflow
-├── config/
-│   └── environment.js             # Default config with env var overrides
-├── src/
-│   ├── main.js                    # RestServer class (singleton, Express wrapper)
-│   └── request.js                 # Request base class (handler registration, auth hook)
-├── test/
-│   ├── config/
-│   │   └── environment.js         # Test config override (dir → test/sample/requests)
-│   ├── integration/
-│   │   └── rest-server-test.js    # Integration tests (QUnit)
-│   ├── sample/
-│   │   └── requests/
-│   │       ├── private.js         # Sample private request with auth hook
-│   │       └── public.js          # Sample public request with middleware demos
-│   └── unit/
-│       └── request-test.js        # Unit tests for Request statics (QUnit)
-├── .gitignore
-├── .npmignore
-├── .nvmrc                         # Node v24.13.0
-├── LICENSE.md                     # Apache 2.0
-├── package.json
-├── pnpm-lock.yaml
-└── README.md
-```
-
-## Dependencies
-
-### Runtime
-- `cors` ^2.8.5 — CORS middleware
-- `express` ^5.1.0 — HTTP framework
-- `stonyx` (local link) — Framework core (config, logging)
-
-### Dev
-- `@stonyx/utils` (local link) — Utility functions (file import, object helpers)
-- `qunit` ^2.24.1 — Test framework
-- `sinon` ^21.0.0 — Test stubs/spies

package/.github/workflows/ci.yml

@@ -1,16 +0,0 @@
-name: CI
-
-on:
-  pull_request:
-    branches: [dev, main]
-
-concurrency:
-  group: ci-${{ github.head_ref || github.ref }}
-  cancel-in-progress: true
-
-permissions:
-  contents: read
-
-jobs:
-  test:
-    uses: abofs/stonyx-workflows/.github/workflows/ci.yml@main

package/.github/workflows/publish.yml

@@ -1,51 +0,0 @@
-name: Publish to NPM
-
-on:
-  repository_dispatch:
-    types: [cascade-publish]
-  workflow_dispatch:
-    inputs:
-      version-type:
-        description: 'Version type'
-        required: true
-        type: choice
-        options:
-          - patch
-          - minor
-          - major
-      custom-version:
-        description: 'Custom version (optional, overrides version-type)'
-        required: false
-        type: string
-  pull_request:
-    types: [opened, synchronize, reopened]
-    branches: [main]
-  push:
-    branches: [main]
-
-concurrency:
-  group: ${{ github.event_name == 'repository_dispatch' && 'cascade-update' || format('publish-{0}', github.ref) }}
-  cancel-in-progress: false
-
-permissions:
-  contents: write
-  id-token: write
-  pull-requests: write
-
-jobs:
-  publish:
-    if: "!contains(github.event.head_commit.message, '[skip ci]')"
-    uses: abofs/stonyx-workflows/.github/workflows/npm-publish.yml@main
-    with:
-      version-type: ${{ github.event.inputs.version-type }}
-      custom-version: ${{ github.event.inputs.custom-version }}
-      cascade-source: ${{ github.event.client_payload.source_package || '' }}
-    secrets: inherit
-
-  cascade:
-    needs: publish
-    uses: abofs/stonyx-workflows/.github/workflows/cascade.yml@main
-    with:
-      package-name: ${{ needs.publish.outputs.package-name }}
-      published-version: ${{ needs.publish.outputs.published-version }}
-    secrets: inherit

package/src/main.js

@@ -1,91 +0,0 @@
-/*
- * Copyright 2025 Stone Costa
- *
- * Licensed under the Apache License, Version 2.0 (the 'License');
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- *     http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
-
-import cors from 'cors';
-import express from 'express';
-import config from 'stonyx/config';
-import log from 'stonyx/log';
-import { forEachFileImport } from '@stonyx/utils/file';
-
-export { default as Request } from './request.js';
-
-export default class RestServer {
-  constructor() {
-    if (RestServer.instance) return RestServer.instance;
-    RestServer.instance = this;
-
-    this.api = new express();
-  }
-
-  static close() {
-    if (!RestServer.instance) throw new Error('RestServer has not been initialized yet');
-
-    RestServer.instance.server.close();
-  }
-  
-  async init() {
-    await this.setupRouter();
-    
-    const { port } = config.restServer;
-
-    // start REST server
-    this.server = this.api.listen(port);
-    log.title(`API Server is listening on port ${port}`);
-  }
-
-  async setupRouter() {
-    const { camelCaseRoutes, dir, enableHealthCheck } = config.restServer;
-    this.setupGlobalMiddleware();
-
-    try {
-      await forEachFileImport(dir, this.mountRoute.bind(this), { rawName: !camelCaseRoutes, ignoreAccessFailure: true });
-
-      if (enableHealthCheck) this.api.get('/health', (_req, res) => res.sendStatus(200));
-    } catch (error) {
-      if (config.debug) console.log(error);
-      throw log.error(`Unable to dynamically configure routes from files in ${dir}`);
-    }
-  }
-
-  async setupGlobalMiddleware() {
-    const { origin, methods, trustProxy } = config.restServer;
-
-    if (trustProxy) this.api.set('trust proxy', true);
-
-    this.api.use([
-      cors({ origin, methods }),
-      express.json()
-    ]);
-  }
-
-  async mountRoute(routeClass, { name, options }) {
-    const { api } = this;
-    const classInstance = new routeClass(options);
-    const route = name === 'index' ? '/' : `/${name}`;
-    const { expressInstance, authorization } = classInstance;
-    
-    const routeCalls = [ expressInstance ];
-
-    // Assign auth callback if it exists
-    if (authorization) routeCalls.unshift(authorization.bind(classInstance));
-
-    classInstance.registerCalls();
-    expressInstance.mountpath = route;
-    
-    // Mount handler to main api instance
-    api.use(route, ...routeCalls);
-  }
-}

package/src/request.js

@@ -1,85 +0,0 @@
-import express from 'express';
-import config from 'stonyx/config';
-import { makeArray } from '@stonyx/utils/object';
-
-const METHODS = new Set(['get', 'post', 'put', 'delete', 'patch']);
-
-export default class Request {
-  static stateProp = '__stonyxState';
-
-  static getState(req) {
-    const { stateProp } = Request;
-    if (req[stateProp] !== undefined) return req[stateProp];
-    
-    req[stateProp] = {};
-    return req[stateProp];
-  }
-
-  static sendStatusResponse(res, status) {
-    const statusMap = config.restServer?.statusMap || {};
-    const message = statusMap[status] || '';
-  
-    return message ? res.status(status).send(message) : res.sendStatus(status);
-  }
-
-  constructor() {
-    const api = express();
-    api.disable('x-powered-by');
-    
-    this.expressInstance = api;
-  }
-
-  // auth hook wrapper
-  authorization(req, res, next) {
-    if (!this.auth) return next();
-
-    const status = this.auth(req, Request.getState(req));
-    if (status) return Request.sendStatusResponse(res, status);
-
-    next();
-  }
-
-  registerCalls() {
-    const { expressInstance } = this;
-    const { getState } = Request;
-    
-    for (const [method, handlers] of Object.entries(this.handlers)) {
-      if (!METHODS.has(method)) {
-        console.warn(`Method "${method}" is not a valid HTTP method. Skipping...`);
-        continue;
-      }
-
-      for (const [route, handler] of Object.entries(handlers)) {
-        expressInstance[method](route, async (req, res) => {
-          const callStack = [...makeArray(handler)];
-          const mainCall = callStack.pop();
-          const { sendStatusResponse } = Request;
-          let response;
-
-          // Run middleware
-          while(callStack.length) {
-            response = await callStack.shift().bind(this)(req, getState(req));
-            if (response !== undefined) break;
-          }
-
-          if (response === undefined) response = await mainCall(req, getState(req));
-          if (Number.isInteger(response)) return sendStatusResponse(res, response);
-          
-          // Handle pipe if set via call state object
-          const { pipe } = getState(req);
-          if (pipe) {
-            const { headers, source } = pipe;
-
-            if (headers) for (const [key, value] of Object.entries(headers)) res.set(key, value);
-            return source.pipe(res);
-          }
-
-          if (response === undefined) return res.sendStatus(200);
-          if (typeof response !== 'object') return sendStatusResponse(res, 500);
-
-          res.send(response);
-        });
-      }
-    }
-  }
-}