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

package/.claude/improvements.md

@@ -0,0 +1,44 @@
+# 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

@@ -0,0 +1,150 @@
+# @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

@@ -2,35 +2,15 @@ name: CI
 
 on:
   pull_request:
-    branches:
-      - dev
-      - main
+    branches: [dev, main]
 
 concurrency:
   group: ci-${{ github.head_ref || github.ref }}
   cancel-in-progress: true
 
+permissions:
+  contents: read
+
 jobs:
   test:
-    runs-on: ubuntu-latest
-
-    steps:
-      - name: Checkout code
-        uses: actions/checkout@v3
-
-      - name: Setup pnpm
-        uses: pnpm/action-setup@v4
-        with:
-          version: 9
-
-      - name: Set up Node.js
-        uses: actions/setup-node@v3
-        with:
-          node-version: 24.13.0
-          cache: 'pnpm'
-
-      - name: Install dependencies
-        run: pnpm install --frozen-lockfile
-
-      - name: Run tests
-        run: pnpm test
+    uses: abofs/stonyx-workflows/.github/workflows/ci.yml@main

package/.github/workflows/publish.yml

@@ -1,7 +1,8 @@
 name: Publish to NPM
 
 on:
-  # Manual trigger (kept for flexibility)
+  repository_dispatch:
+    types: [cascade-publish]
   workflow_dispatch:
     inputs:
       version-type:
@@ -9,7 +10,6 @@ on:
         required: true
         type: choice
         options:
-          - alpha
           - patch
           - minor
           - major
@@ -17,127 +17,35 @@ on:
         description: 'Custom version (optional, overrides version-type)'
         required: false
         type: string
-
-  # Auto-publish alpha on PR
   pull_request:
     types: [opened, synchronize, reopened]
-    branches: [main, dev]
-
-  # Auto-publish stable on merge to main
+    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  # Required for npm provenance
-  pull-requests: write  # For PR comments
+  id-token: write
+  pull-requests: write
 
 jobs:
   publish:
-    runs-on: ubuntu-latest
-
-    steps:
-      - name: Checkout code
-        uses: actions/checkout@v3
-        with:
-          fetch-depth: 0
-          # For PR events, check out the PR branch
-          ref: ${{ github.event_name == 'pull_request' && github.head_ref || github.ref }}
-
-      - name: Setup pnpm
-        uses: pnpm/action-setup@v4
-        with:
-          version: 9
-
-      - name: Set up Node.js
-        uses: actions/setup-node@v3
-        with:
-          node-version: 24.13.0
-          cache: 'pnpm'
-          registry-url: 'https://registry.npmjs.org'
-
-      - name: Install dependencies
-        run: pnpm install --frozen-lockfile
-
-      - name: Run tests
-        run: pnpm test
-
-      - name: Configure git
-        run: |
-          git config user.name "github-actions[bot]"
-          git config user.email "github-actions[bot]@users.noreply.github.com"
-
-      # Determine version type based on trigger
-      - name: Determine version bump type
-        id: version-type
-        run: |
-          if [ "${{ github.event_name }}" = "pull_request" ]; then
-            echo "type=alpha" >> $GITHUB_OUTPUT
-          elif [ "${{ github.event_name }}" = "push" ]; then
-            echo "type=patch" >> $GITHUB_OUTPUT
-          elif [ "${{ github.event.inputs.custom-version }}" != "" ]; then
-            echo "type=custom" >> $GITHUB_OUTPUT
-          else
-            echo "type=${{ github.event.inputs.version-type }}" >> $GITHUB_OUTPUT
-          fi
-
-      # Version bumping
-      - name: Bump version (custom)
-        if: steps.version-type.outputs.type == 'custom'
-        run: pnpm version ${{ github.event.inputs.custom-version }} --no-git-tag-version
-
-      - name: Bump version (alpha)
-        if: steps.version-type.outputs.type == 'alpha'
-        run: pnpm version prerelease --preid=alpha --no-git-tag-version
-
-      - name: Bump version (patch/minor/major)
-        if: steps.version-type.outputs.type == 'patch' || steps.version-type.outputs.type == 'minor' || steps.version-type.outputs.type == 'major'
-        run: pnpm version ${{ steps.version-type.outputs.type }} --no-git-tag-version
-
-      - name: Get package version
-        id: package-version
-        run: echo "version=$(node -p "require('./package.json').version")" >> $GITHUB_OUTPUT
-
-      # Publishing
-      - name: Publish to NPM (alpha)
-        if: contains(steps.package-version.outputs.version, 'alpha')
-        run: pnpm publish --tag alpha --access public --no-git-checks
-
-      - name: Publish to NPM (stable)
-        if: "!contains(steps.package-version.outputs.version, 'alpha')"
-        run: pnpm publish --access public
-
-      # Only commit and tag for stable releases (push to main or manual stable)
-      - name: Commit version bump and create tag
-        if: github.event_name == 'push' || (github.event_name == 'workflow_dispatch' && !contains(steps.package-version.outputs.version, 'alpha'))
-        run: |
-          git add package.json
-          git commit -m "chore: release v${{ steps.package-version.outputs.version }}"
-          git tag v${{ steps.package-version.outputs.version }}
-          git push origin main --tags
-
-      - name: Create GitHub Release
-        if: github.event_name == 'push' || (github.event_name == 'workflow_dispatch' && !contains(steps.package-version.outputs.version, 'alpha'))
-        uses: actions/create-release@v1
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        with:
-          tag_name: v${{ steps.package-version.outputs.version }}
-          release_name: v${{ steps.package-version.outputs.version }}
-          draft: false
-          prerelease: false
-
-      # Add PR comment with alpha version info
-      - name: Comment on PR with alpha version
-        if: github.event_name == 'pull_request'
-        uses: actions/github-script@v6
-        with:
-          script: |
-            const version = '${{ steps.package-version.outputs.version }}';
-            const packageName = require('./package.json').name;
-            github.rest.issues.createComment({
-              issue_number: context.issue.number,
-              owner: context.repo.owner,
-              repo: context.repo.repo,
-              body: `## 🚀 Alpha Version Published\n\n**Version:** \`${version}\`\n\n**Install:**\n\`\`\`bash\npnpm add ${packageName}@${version}\n# or\npnpm add ${packageName}@alpha  # latest alpha\n\`\`\`\n\nThis alpha version is now available for testing!`
-            });
+    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/README.md

@@ -41,16 +41,13 @@ export default {
 };
 ```
 
-Then initialize the Stonyx framework, which auto-initializes all of its modules, including `@stonyx/rest-server`:
+Then run the application via the Stonyx CLI, which auto-initializes all modules including the REST server:
 
-```js
-import Stonyx from 'stonyx';
-import config from './config/environment.js';
-
-new Stonyx(config);
+```bash
+stonyx serve
 ```
 
-For further framework initialization instructions, see the [Stonyx repository](https://github.com/abofs/stonyx).
+For further framework instructions, see the [Stonyx repository](https://github.com/abofs/stonyx).
 
 ### Optional Direct Usage
 
@@ -72,12 +69,26 @@ Configuration is read from `stonyx/config` under `restServer`:
 
 |       Option      |         Type        | Default     | Description                                                |
 | :---------------: | :-----------------: | :---------- | :--------------------------------------------------------- |
-|       `dir`       |      **String**     | `undefined` | Directory containing request classes to mount as routes    |
+|       `dir`       |      **String**     | `'./requests'` | Directory containing request classes to mount as routes    |
 | `camelCaseRoutes` |     **Boolean**     | `true`      | Convert filenames to camelCase when generating route paths |
-|       `port`      |      **Number**     | `3000`      | Port to listen on                                          |
+|       `port`      |      **Number**     | `2666`      | Port to listen on                                          |
 |      `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   |
-|      `debug`      |     **Boolean**     | `false`     | Enable debug logging during route setup                    |
+
+### 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
 
@@ -135,10 +146,6 @@ project-root/
 
 The `RestServer` will automatically mount these routes using the filenames as paths (`/public` and `/private` by default, or camelCased if configured).
 
-Perfect! Here’s a self-contained **“Example Requests”** section with sample `curl` calls:
-
----
-
 ### Example Requests
 
 Assuming you have `public.js` and `private.js` routes mounted, you can test them like this:

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.0",
+  "version": "0.2.1-alpha.2",
   "description": "Rest Server Module for Stonyx Framework",
   "repository": {
     "type": "git",
@@ -27,14 +27,14 @@
   "dependencies": {
     "cors": "^2.8.5",
     "express": "^5.1.0",
-    "stonyx": "^0.2.2"
+    "stonyx": "0.2.3-beta.2"
   },
   "devDependencies": {
-    "@stonyx/utils": "^0.2.2",
+    "@stonyx/utils": "0.2.3-beta.3",
     "qunit": "^2.24.1",
     "sinon": "^21.0.0"
   },
   "scripts": {
-    "test": "qunit --require ./stonyx-bootstrap.cjs"
+    "test": "stonyx test"
   }
 }

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 }),

package/stonyx-bootstrap.cjs

@@ -1,12 +0,0 @@
-/**
- * commonJS Bootstrap loading - Stonyx must be loaded first, prior to the rest of the application
- */
-const { default:Stonyx } = require('stonyx');
-const { default:config } = require('./config/environment.js');
-
-// Override dir for tests
-config.dir = './test/sample/requests';
-
-new Stonyx(config, __dirname);
-
-module.exports = Stonyx;