webhoster 0.1.0 → 0.3.0

package/.eslintrc.json

@@ -1,79 +1,95 @@
 {
-  "extends": ["airbnb-base", "plugin:node/recommended"],
-  "plugins": ["jsdoc", "babel"],
   "env": {
-    "node": true
+    "es2021": true
   },
-  "parser": "babel-eslint",
+  "extends": [
+    "airbnb-base",
+    "plugin:@typescript-eslint/recommended",
+    "plugin:jsdoc/recommended-typescript-flavor-error",
+    "plugin:n/recommended",
+    "plugin:unicorn/recommended",
+    "plugin:import/recommended"
+  ],
+  "overrides": [
+    {
+      "files": [
+        "*.cjs"
+      ],
+      "rules": {
+        "@typescript-eslint/no-var-requires": 0,
+        "import/no-nodejs-modules": 0
+      }
+    }
+  ],
+  "parser": "@typescript-eslint/parser",
   "parserOptions": {
-    "ecmaVersion": 2020,
-    "sourceType": "module",
     "ecmaFeatures": {
       "impliedStrict": true
-    }
+    },
+    "ecmaVersion": 2019,
+    "project": "./jsconfig.json",
+    "sourceType": "module"
   },
+  "plugins": [
+    "@typescript-eslint",
+    "canonical",
+    "jsdoc",
+    "n",
+    "unicorn",
+    "import"
+  ],
+  "root": true,
   "rules": {
-    "import/extensions": ["error", "always", {
-      "js": "always",
-      "mjs": "always"
-    }],
-    "import/no-useless-path-segments": ["error", {
-      "noUselessIndex": false
-    }],
-    "import/prefer-default-export": "off",
-    "import/no-anonymous-default-export": ["error"],
-    "prefer-destructuring": ["error", {
-      "VariableDeclarator": {
-        "array": false,
-        "object": true
-      },
-      "AssignmentExpression": {
-        "array": false,
-        "object": true
+    "import/extensions": [
+      "error",
+      "always",
+      {
+        "js": "always",
+        "mjs": "never"
       }
-    }, {
-      "enforceForRenamedProperties": false
-    }],
-    "max-len": ["error", 120, 2, {
-      "ignoreUrls": true,
-      "ignoreComments": true,
-      "ignoreRegExpLiterals": true,
-      "ignoreStrings": true,
-      "ignoreTemplateLiterals": true
-    }],
-    "spaced-comment": ["error", "always", {
-      "line": {
-        "exceptions": ["-", "+"],
-        "markers": ["=", "!", "/"]
-      },
-      "block": {
-        "exceptions": ["-", "+"],
-        "markers": ["=", "!", ":", "::"],
-        "balanced": true
+    ],
+    "import/no-extraneous-dependencies": "off",
+    "import/prefer-default-export": "off",
+    "jsdoc/no-defaults": "off",
+    "jsdoc/require-param-description": "off",
+    "jsdoc/require-property-description": "off",
+    "jsdoc/require-returns": "off",
+    "jsdoc/require-returns-description": "off",
+    "no-continue": "off",
+    "no-restricted-syntax": "off",
+    "no-return-await": "off",
+    "unicorn/explicit-length-check": "off",
+    "unicorn/filename-case": "off",
+    "unicorn/no-null": "off",
+    "unicorn/no-useless-switch-case": "off",
+    "unicorn/no-useless-undefined": "off",
+    "unicorn/prefer-ternary": [
+      "error",
+      "only-single-line"
+    ],
+    "unicorn/prevent-abbreviations": [
+      "error",
+      {
+        "checkFilenames": false
       }
-    }],
-    "jsdoc/require-param-description": 0,
-    "jsdoc/require-returns-description": 0,
-    "jsdoc/no-undefined-types": 0,
-    "jsdoc/valid-types": 0,
-    "jsdoc/newline-after-description": ["warn", "never"],
-    "jsdoc/require-returns": ["warn", {
-      "forceReturnsWithAsync": true,
-      "forceRequireReturn": true
-    }]
+    ],
+    "unicorn/switch-case-braces": "off",
+    "unicorn/text-encoding-identifier-case": "off"
   },
   "settings": {
     "jsdoc": {
       "preferredTypes": {
-        "object.": "Object.<>",
-        "object<>": "Object.<>",
-        "object": "Object"
+        "array": "Array",
+        "object": "Object",
+        "object.": "Object<>",
+        "object<>": "Object<>",
+        "symbol": "Symbol"
       },
       "tagNamePreference": {
         "augment": "extends",
-        "returns": "return",
+        "constant": "const",
         "property": "prop",
-        "constant": "const"
+        "returns": "return"
       }
     }
   }

package/.github/copilot-instructions.md

@@ -0,0 +1,100 @@
+<!-- Auto-generated: guidance for AI coding assistants working on this repo -->
+# Copilot / AI assistant instructions for webhoster
+
+This file gives focused, actionable guidance to quickly become productive in this repository.
+
+Overview
+- **Purpose**: `webhoster` is a stream-first, middleware-driven HTTP/HTTP2 framework for Node.js. Core classes live in `lib/` (notably `lib/HttpHandler.js`, `lib/HttpRequest.js`, `lib/HttpResponse.js`). Middleware implementations live in `middleware/` and are composed into the `HttpHandler` middleware tree.
+- **Module type**: The project is ESM (`"type": "module"` in `package.json`) and targets Node >v16.13.
+
+Key patterns and conventions
+- **Middleware tree**: Middleware can be a function, a filter, an Iterable (e.g. `Set`), or a `Map`. Branching is represented by nested arrays/iterables. See examples in `README.md` and `middleware/` files.
+- **Return values**: Middleware return values drive control flow. Use the `HttpHandler` constants or their aliases:
+  - `HttpHandler.CONTINUE` (or `true`, `undefined`, `null`) — continue the branch
+  - `HttpHandler.BREAK` (or `false`) — break this branch, move to next
+  - `HttpHandler.END` (or `0`) — terminate the middleware tree
+  - `number` — treated as an HTTP status code and ends
+- **I/O model**: Requests expose `.read()`, `.stream`, and `.body` helpers. Responses expose `.stream`, `.end()`, `.send()`, `.pipeFrom()` and may call `.pushPath()` for HTTP/2 pushes. See `lib/HttpRequest.js` and `lib/HttpResponse.js`.
+- **Locals**: Per-request state belongs on `request.locals` (or `locals`) and is passed through middleware.
+
+Developer workflows
+- **Run tests**: `npm test` (uses `c8` + `ava` for coverage). Unit tests live under `test/` (pattern: `test/**/*.js`, excluding `test/fixtures/**`).
+- **Run full/test-all scripts**: `npm run testall` (async) or `npm run testallsync` (sync). These call the scripts in `scripts/`.
+- **Debug tests**: `npm run debug-test` which runs `ava --serial`.
+- **Coverage**: Coverage created by `c8`; `posttestall`/`posttestallsync` call `c8 report`.
+
+Code style & types
+- Project uses `eslint` (Airbnb base + plugins) in devDependencies — follow existing style. There are TypeScript type hints (`types/typings.d.ts`) but the codebase is JavaScript ESM.
+
+Where to change behavior
+- Add or alter middleware in `middleware/`. Prefer small, single-responsibility modules: decoding, encoding, header transforms, routing filters (see `PathMiddleware.js`, `MethodMiddleware.js`).
+- Core runtime behavior is in `lib/HttpHandler.js`. Changes here affect branching, error handling, and how middleware results are interpreted.
+
+Testing & examples
+- Example middleware composition is in `README.md` and `test/index.js` — use those as canonical examples when adding new middleware or behavior.
+- Write tests under `test/` and avoid touching `test/fixtures/` unless updating fixture data. Use `ava` and follow existing test styles.
+\
+Example: minimal middleware
+
+```js
+// middleware/ExampleMiddleware.js
+export default class ExampleMiddleware {
+  execute(transaction) {
+    transaction.locals = transaction.locals || {};
+    transaction.locals.example = (transaction.locals.example || 0) + 1;
+    return true; // continue processing
+  }
+}
+```
+
+Test example (AVA):
+
+```js
+import test from 'ava';
+import ExampleMiddleware from '../middleware/ExampleMiddleware.js';
+
+test('ExampleMiddleware increments locals', (t) => {
+  const m = new ExampleMiddleware();
+  const transaction = { locals: {}, state: { treeIndex: [] }, request: {}, response: {} };
+  m.execute(transaction);
+  t.is(transaction.locals.example, 1);
+});
+```
+
+I added `middleware/ExampleMiddleware.js` and `test/example-middleware.js` to the repo as a runnable template. Run `npm test` to verify the example.
+
+Integration points & runtime
+- Typical integration: a server registers handlers:
+  - `http1Server.addListener('request', HttpHandler.defaultInstance.handleHttp1Request)`
+  - `http2Server.addListener('stream', HttpHandler.defaultInstance.handleHttp2Stream)`
+- Middleware may push HTTP/2 resources using `response.pushPath()` — guard with `if (response.canPushPath)`.
+
+Practical tips for PRs and edits
+- Keep changes small and focused. Prefer adding middleware modules over modifying `HttpHandler` unless implementing a framework-level feature.
+- Preserve ESM syntax and `export`/`import` styles. Respect the project's `node` engine minimum.
+- Add or update `test/*.js` for any behavioral change; run `npm test` locally to confirm.
+
+Files to inspect when in doubt
+- `lib/HttpHandler.js`, `lib/HttpRequest.js`, `lib/HttpResponse.js`
+- `middleware/*` for existing middleware primitives
+- `test/index.js` and `test/**` for test patterns and usage examples
+- `scripts/test-all.sh` and `scripts/test-all-sync.sh` for CI/test orchestration
+
+CI / Workflows
+- `/.github/workflows/test-matrix.yml`: the recommended workflow. Runs `npm ci` + `npm run test` across a Node matrix (`16.13`, `16`, `18`, `20`, `22`) using `actions/setup-node`. Prefer editing this file when you want to change supported Node versions or add reporting steps (Codecov/Upload). Each matrix job uses the display name `Test on Node <version>`.
+- `/.github/workflows/test-with-nvm.yml`: optional workflow that installs `nvm` on the runner and executes `scripts/test-all.sh` to mirror local developer behavior. Keep this for parity/debugging only; the matrix job is preferred for CI.
+
+README badges
+- `README.md` contains per-node badges that point to the `test-matrix.yml` workflow and the job names. If you rename the workflow or change the job display name, update the badges in `README.md` accordingly. Badges point to the `master` branch by default.
+
+Local & debugging notes
+- Run tests locally (fast):
+  - `npm ci`
+  - `npm test` (runs `c8 ava`)
+- Run the full multi-version script locally (requires `nvm`):
+  - `chmod +x scripts/test-all.sh`
+  - `./scripts/test-all.sh`
+- The `scripts/test-all.sh` script runs `nvm install`/`nvm use` for multiple Node versions and then executes `npx c8 --clean false -r none ava` for each version in parallel. A recent fix corrected a typo so the Node 22 step now correctly runs `nvm use 22`.
+
+If you need more
+- If anything here is unclear or you'd like more examples (specific middleware templates, test scaffolds, or a debugging recipe), ask and I'll add them.

package/.github/workflows/test-matrix.yml

@@ -0,0 +1,37 @@
+name: Test matrix
+
+on:
+  push:
+    branches: ["master"]
+  pull_request:
+    branches: ["master"]
+
+jobs:
+  test:
+    name: Test on Node ${{ matrix.node-version }}
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node-version: ["16.13", "16", "18", "20", "22"]
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run tests
+        run: npm run test
+
+      - name: Upload coverage artifact
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage-${{ matrix.node-version }}
+          path: coverage

package/.test/benchmark.js

@@ -0,0 +1,28 @@
+import HttpListener from '../helpers/HttpListener.js';
+import HttpHandler from '../lib/HttpHandler.js';
+import AutoHeadersMiddleware from '../middleware/AutoHeadersMiddleware.js';
+import SendJsonMiddleware from '../middleware/SendJsonMiddleware.js';
+import ContentLengthMiddleware from '../middleware/ContentLengthMiddleware.js';
+
+const { middleware } = HttpHandler.defaultInstance;
+middleware.push(
+  // new HeadMethodMiddleware(), // Discard body content
+  new SendJsonMiddleware(),
+  // new ContentLengthMiddleware({ delayCycle: false }), // Calculate length of anything after
+  // new AutoHeadersMiddleware(), // Send headers automatically
+  // new HashMiddleware(), // Hash anything after
+  // new ContentEncoderMiddleware(), // Compress anything after
+  // new ContentWriterMiddleware({ setCharset: true, setJSON: true }),
+  // new ContentDecoderMiddleware(),
+  // Automatically reads text, JSON, and form-url-encoded from requests
+  // new ContentReaderMiddleware({
+  //   buildString: true,
+  //   defaultMediaType: 'application/json',
+  //   parseJSON: true,
+  //   formURLEncodedFormat: 'object',
+  // }),
+  { hello: "world" },
+);
+
+const listener = new HttpListener({ insecurePort: 3000 });
+listener.startAll();

package/.test/constants.js

@@ -0,0 +1,4 @@
+export const HTTP_PORT = Number.parseInt(process.env.HTTP_PORT || process.env.PORT || '8080', 10);
+export const HTTPS_PORT = Number.parseInt(process.env.HTTPS_PORT || '8443', 10);
+export const HTTP_HOST = process.env.HTTP_HOST || process.env.HOST || '0.0.0.0';
+export const HTTPS_HOST = process.env.HTTPS_HOST || process.env.HOST || '0.0.0.0';

package/{test → .test}/http2server.js

@@ -1,4 +1,4 @@
-import http2 from 'http2';
+import http2 from 'node:http2';
 
 import { HTTPS_HOST, HTTPS_PORT } from './constants.js';
 

package/{test → .test}/httpserver.js

@@ -1,4 +1,4 @@
-import http from 'http';
+import http from 'node:http';
 
 import { HTTP_HOST, HTTP_PORT } from './constants.js';