@stonyx/rest-server 0.2.1-alpha.3 → 0.2.1-alpha.4

package/.claude/project-structure.md

@@ -51,6 +51,7 @@ From `config/environment.js`. All values are overridable via environment variabl
 | 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     |

package/README.md

@@ -75,8 +75,21 @@ 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`) |
+|  `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   |
 
+### 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`.
+
+To fix this, enable the `trustProxy` option:
+
+```bash
+REST_TRUST_PROXY=true
+```
+
+This tells Express to trust the `X-Forwarded-Proto` header set by the load balancer, so `request.protocol` correctly returns `https`. This is important for any functionality that generates URLs based on the incoming request protocol, such as JSON:API relationship links.
+
 ## Request Class
 
 The `Request` class provides a structured way to define route handlers and authorization hooks. Route classes extend `Request` and define:

package/config/environment.js

@@ -3,7 +3,8 @@ const {
   REST_CORS_METHODS,
   REST_HEALTH_CHECK_DISABLE,
   REST_PORT,
-  REST_REQUEST_PATH
+  REST_REQUEST_PATH,
+  REST_TRUST_PROXY
 } = process;
 
 export default {
@@ -12,6 +13,7 @@ export default {
   methods: REST_CORS_METHODS ?? 'GET,POST,PATCH,PUT,DELETE',
   dir: REST_REQUEST_PATH ?? './requests',
   port: REST_PORT ?? 2666,
+  trustProxy: REST_TRUST_PROXY === 'true',
   logColor: 'yellow',
   logMethod: 'api'
 };

package/package.json

@@ -4,7 +4,7 @@
     "stonyx-async",
     "stonyx-module"
   ],
-  "version": "0.2.1-alpha.3",
+  "version": "0.2.1-alpha.4",
   "description": "Rest Server Module for Stonyx Framework",
   "repository": {
     "type": "git",

package/src/main.js

@@ -61,7 +61,9 @@ export default class RestServer {
   }
 
   async setupGlobalMiddleware() {
-    const { origin, methods } = config.restServer;
+    const { origin, methods, trustProxy } = config.restServer;
+
+    if (trustProxy) this.api.set('trust proxy', true);
 
     this.api.use([
       cors({ origin, methods }),
@@ -73,17 +75,12 @@ export default class RestServer {
     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));
+    const { expressInstance } = classInstance;
 
     classInstance.registerCalls();
     expressInstance.mountpath = route;
-    
+
     // Mount handler to main api instance
-    api.use(route, ...routeCalls);
+    api.use(route, expressInstance);
   }
 }

package/src/request.js

@@ -29,20 +29,10 @@ export default class Request {
     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;
-    
+    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...`);
@@ -51,9 +41,14 @@ export default class Request {
 
       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();
-          const { sendStatusResponse } = Request;
           let response;
 
           // Run middleware
@@ -64,7 +59,7 @@ export default class Request {
 
           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 { redirect } = getState(req);
           if (redirect) return res.redirect(redirect);