@jnode/server 2.0.2 → 2.2.0

package/README.md

@@ -83,6 +83,7 @@ Also, we provide some powerful built-in routers and handlers so you can start bu
 - `options` [\<Object\>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)
   - `maxRoutingSteps` [\<number\>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#number_type) The max steps for routing; when exceeded but still getting another router, it'll throw the client a **508** error. **Default:** `50`.
   - `enableHTTP2` [\<boolean\>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#boolean_type) Enable HTTP/2 support (with `node:http2` [Compatibility API](https://nodejs.org/docs/latest/api/http2.html#compatibility-api)). **Default:** `false`.
+  - `codeHandlers` [\<Object\>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) Global status code handlers. Keys are HTTP status codes, values are [handlers-extended](#handler-extended).
   - Options in [`http.createServer()`](https://nodejs.org/docs/latest/api/http.html#httpcreateserveroptions-requestlistener), [`https.createServer()`](https://nodejs.org/docs/latest/api/https.html#httpscreateserveroptions-requestlistener), [`http2.createServer()`](https://nodejs.org/docs/latest/api/http2.html#http2createserveroptions-onrequesthandler), or [`http2.createSecureServer()`](https://nodejs.org/docs/latest/api/http2.html#http2createsecureserveroptions-onrequesthandler).
 - Returns: [\<server.Server\>](#class-serverserver)
 
@@ -264,10 +265,13 @@ We provide two methods to use them:
   - `<METHOD>/<path_segment>[/<path_segment>...]` [router](#class-serverrouter) | [handler-extended](#handler-extended) Used when the method matches; equals to `'/<path_segment>': r.Method({ '<METHOD>': <value> })`. E.G., `'GET/meow': 'Meow!'` (only works for HTTP method `'GET'`).
   - `@<METHOD>/<path_segment>[/<path_segment>...]` [router](#class-serverrouter) | [handler-extended](#handler-extended) Used when both the path resolver ends and the method matches; equals to `'/<path_segment>': r.Path(r.Method({ '<METHOD>': <value> }))`. E.G., `'@GET/meow': 'Meow!'` (only works for path `'/meow'` but not `'/meow/something'` and request method is `'GET'`).
   - `*` [router](#class-serverrouter) | [handler-extended](#handler-extended) Any path segment. E.G. `'*': h.Text('Meow? Nothing here!', { statusCode: 404 })`.
+  - `/%:<path_parameter_name>` [router](#class-serverrouter) | [handler-extended](#handler-extended) Match any segment (if exists) and save the segment to `ctx.params` by `<path_parameter_name>`. Do the similar thing as [`PathArgRouter`](#router-pathargrouterparamname-next).
 
 `PathRouter` is probably the most important router; almost every server needs it!
 
-By the way, we **DO NOT** support `'/*'` as a universal matching character, don't try this.
+Please note that when defining only `/%:arg/b` and `/a/c`, requesting `/a/b` **WILL NOT** return the value of `/%:arg/b`. Instead, it will return `404`. This limitation is in place to improve performance, and we believe in designing a great API. If you still need this functionality, you can build your own router.
+
+By the way, if you’re looking for a universal matching character, use `'/%:'` instead of `'/*'` (this will match to `'*'` in a literal sense).
 
 #### How it works?
 
@@ -283,7 +287,8 @@ map = {
   '@/a/b': 'C!',
   'GET/a': 'D!',
   '@GET/a/b': 'E!',
-  '*': 'F!'
+  '@GET/%:arg/c': 'F!',
+  '*': 'G!'
 };
 
 // we will parse into
@@ -305,11 +310,19 @@ parsed = {
       }
     }
   },
-  '*': 'F!'
+  ':': {
+    '/c': {
+      '@': {
+        'GET': 'F!',
+        '::GET': [ 'arg' ]
+      }
+    }
+  },
+  '*': 'G!'
 };
 ```
 
-This format enables fast and flexible path routing while keeping it simple for developers.
+This format allows for fast and flexible path routing while maintaining simplicity for developers. However, as mentioned earlier, some specialized path matching will not be supported.
 
 ### Router: `HostRouter(end, map)`
 
@@ -318,6 +331,7 @@ This format enables fast and flexible path routing while keeping it simple for d
   - `.<host_segment>[.<host_segment>...]` [router](#class-serverrouter) | [handler-extended](#handler-extended) A simple host segment routing (reversed). E.G., `.example.com` will match `example.com`, `.localhost` will match `localhost`.
   - `@.<host_segment>[.<host_segment>...]` [router](#class-serverrouter) | [handler-extended](#handler-extended) Used when the host resolver ends here. E.G., `@.example.com` (only works for exactly `example.com` but not `sub.example.com`).
   - `*` [router](#class-serverrouter) | [handler-extended](#handler-extended) Any host segment.
+  - `.%:<host_parameter_name>` [router](#class-serverrouter) | [handler-extended](#handler-extended) Match any segment (if exists) and save the segment to `ctx.params` by `<host_parameter_name>`.
 
 ### Router: `MethodRouter(methodMap)`
 
@@ -326,9 +340,10 @@ This format enables fast and flexible path routing while keeping it simple for d
   - `*` [router](#class-serverrouter) | [handler-extended](#handler-extended) Any method, used as fallback.
 - Returns: [\<MethodRouter\>](#router-methodroutermethodmap) Routes based on HTTP method, returns 405 if no method matches.
 
-### Router: `FunctionRouter(fn)`
+### Router: `FunctionRouter(fn, ext)`
 
-- `fn` [\<Function\>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function) A function with signature `(env, ctx) => router | handler-extended`.
+- `fn` [\<Function\>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function) A function with signature `(env, ctx, ext) => router | handler-extended`.
+- `ext` [\<any\>] Passed to `func`.
 
 A simple router that allows you to implement custom routing logic.
 
@@ -409,8 +424,9 @@ Sends a JavaScript object serialized as JSON with `Content-Type: application/jso
 
 Redirects the request to a specified location. Supports both absolute URLs and dynamic redirects based on remaining path segments.
 
-### Handler: `FunctionHandler(func)`
+### Handler: `FunctionHandler(func, ext)`
 
-- `func` [\<Function\>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function) A function with signature `(ctx, env) => void | Promise<void>`.
+- `func` [\<Function\>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function) A function with signature `(ctx, env, ext) => void | Promise<void>`.
+- `ext` [\<any\>] Passed to `func`.
 
 Allows you to implement custom request handling logic directly within a function.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jnode/server",
-  "version": "2.0.2",
+  "version": "2.2.0",
   "description": "Simple web server package for Node.js.",
   "main": "src/index.js",
   "scripts": {

package/src/handlers.js

@@ -18,28 +18,38 @@ class DataHandler {
     constructor(data, options = {}) {
         this.data = data;
         this.options = options;
-    }
 
-    async handle(ctx, env) {
+        // prebuild headers
+        this._statusCode = this.options.statusCode ?? 200;
         if (typeof this.data === 'string') { // string
-            ctx.res.writeHead(this.options.statusCode ?? 200, {
+            this.data = Buffer.from(this.data, 'utf8');
+            this._headers = {
                 'Content-Type': 'text/plain; charset=utf-8',
-                'Content-Length': Buffer.byteLength(this.data, 'utf8'),
+                'Content-Length': this.data.length,
                 ...this.options.headers
-            });
-            ctx.res.end(this.data, 'utf8');
+            };
         } else if (this.data instanceof Uint8Array) { // buffer
-            ctx.res.writeHead(this.options.statusCode ?? 200, {
+            this._headers = {
                 'Content-Type': 'application/octet-stream',
                 'Content-Length': this.data.length,
                 ...this.options.headers
-            });
-            ctx.res.end(this.data);
-        } else if (stream.isReadable(this.data)) { // stream
-            ctx.res.writeHead(this.options.statusCode ?? 200, {
+            };
+        } else if (stream.isReadable(this.data)) {
+            this._headers = {
                 'Content-Type': 'application/octet-stream',
                 ...this.options.headers
-            });
+            };
+        } else {
+            throw new Error('Unsupported data type.');
+        }
+    }
+
+    async handle(ctx, env) {
+        if (this.data instanceof Uint8Array) { // buffer
+            ctx.res.writeHead(this._statusCode, this._headers);
+            ctx.res.end(this.data);
+        } else if (stream.isReadable(this.data)) { // stream
+            ctx.res.writeHead(this._statusCode, this._headers);
 
             try {
                 await stream.promises.pipeline(this.data, ctx.res);
@@ -184,19 +194,21 @@ class FolderHandler {
 // JSON handler: JSON object
 class JSONHandler {
     constructor(obj, options = {}) {
-        this.obj = obj;
+        this.data = Buffer.from(JSON.stringify(obj), 'utf8');
         this.options = options;
-    }
 
-    handle(ctx, env) {
-        const data = JSON.stringify(this.obj);
-
-        ctx.res.writeHead(this.options.statusCode ?? 200, {
+        // prebuild headers
+        this._statusCode = this.options.statusCode ?? 200;
+        this._headers = {
             'Content-Type': 'application/json; charset=utf-8',
             'Content-Length': Buffer.byteLength(data, 'utf8'),
             ...this.options.headers
-        });
-        ctx.res.end(data, 'utf8');
+        };
+    }
+
+    handle(ctx, env) {
+        ctx.res.writeHead(this.statusCode, this._headers);
+        ctx.res.end(this.data);
     }
 }
 
@@ -205,29 +217,34 @@ class RedirectHandler {
     constructor(location, options = {}) {
         this.location = location;
         this.options = options;
-    }
 
-    handle(ctx, env) {
-        ctx.res.writeHead(this.options.statusCode ?? 307, {
+        // prebuild headers
+        this._statusCode = this.options.statusCode ?? 307;
+        this._headers = {
             'Location': this.options.base ?
                 this.options.base +
                 (this.options.base.endsWith('/') ? '' : '/') +
                 env.path.slice(env.pathPointer).map(encodeURIComponent).join('/') :
                 this.location,
             ...this.options.headers
-        });
+        };
+    }
+
+    handle(ctx, env) {
+        ctx.res.writeHead(this._statusCode, this._headers);
         ctx.res.end();
     }
 }
 
 // function handler: custom function
 class FunctionHandler {
-    constructor(func) {
+    constructor(func, ext) {
         this.func = func;
+        this.ext = ext;
     }
 
     handle(ctx, env) {
-        return this.func(ctx, env);
+        return this.func(ctx, env, this.ext);
     }
 }
 
@@ -235,12 +252,12 @@ class FunctionHandler {
 module.exports = {
     DataHandler, TextHandler: DataHandler, FileHandler, FolderHandler, JSONHandler, RedirectHandler, FunctionHandler,
     handlerConstructors: {
-        Data: (...args) => new DataHandler(...args),
-        Text: (...args) => new DataHandler(...args),
-        File: (...args) => new FileHandler(...args),
-        Folder: (...args) => new FolderHandler(...args),
-        JSON: (...args) => new JSONHandler(...args),
-        Redirect: (...args) => new RedirectHandler(...args),
-        Function: (...args) => new FunctionHandler(...args)
+        Data: (data, options) => new DataHandler(data, options),
+        Text: (data, options) => new DataHandler(data, options),
+        File: (file, options) => new FileHandler(file, options),
+        Folder: (folder, options) => new FolderHandler(folder, options),
+        JSON: (obj, options) => new JSONHandler(obj, options),
+        Redirect: (location, options) => new RedirectHandler(location, options),
+        Function: (func, ext) => new FunctionHandler(func, ext)
     }
 };

package/src/routers.js

@@ -29,20 +29,30 @@ class PathRouter {
             // key format: '[@ (path end check)][METHOD (method check)]/path/segments'
             // example: '@ GET /cat/names', 'POST /cats', '/api'
             const routeEnd = key.startsWith('@');
-            const routeMethod = key.substring(routeEnd ? 1 : 0, firstSlashIndex).trim().toUpperCase();
-            const routePath = key.substring(firstSlashIndex).split('/').slice(1).map(decodeURIComponent);
+            const routeMethod = key.substring(routeEnd ? 1 : 0, firstSlashIndex).trim();
+            const routePath = key.substring(firstSlashIndex).split('/').slice(1);
 
             // expand map
             let current = this.map;
-            for (const segment of routePath) {
-                if (!current['/' + segment]) current['/' + segment] = {};
-                current = current['/' + segment];
+            let args = [];
+            for (let segment of routePath) {
+                if (segment.startsWith('%:')) {
+                    args.push(segment.substring(2));
+                    if (!current[':']) current[':'] = {};
+                    current = current[':'];
+                    continue;
+                }
+
+                segment = '/' + decodeURIComponent(segment);
+                if (!current[segment]) current[segment] = {};
+                current = current[segment];
             }
 
             // '*' for non-end check, '@' for end check
             // '*' for any method, 'METHOD' for specific method
             if (!current[routeEnd ? '@' : '*']) current[routeEnd ? '@' : '*'] = {};
             current[routeEnd ? '@' : '*'][routeMethod || '*'] = value;
+            if (args.length > 0) current[routeEnd ? '@' : '*']['::' + (routeMethod || '*')] = args;
         }
     }
 
@@ -52,14 +62,21 @@ class PathRouter {
         let result = this.map['*'];
         let resultPointer = env.pathPointer;
         let current = this.map;
+        let currentArgs = [];
+        let resultArgNames;
         while (env.pathPointer < env.path.length) {
-            const segment = '/' + env.path[env.pathPointer];
-            if (!current[segment]) break;
+            let segment = '/' + env.path[env.pathPointer];
+            if (!current[segment] && !current[':']) break;
+            if (!current[segment]) {
+                segment = ':';
+                currentArgs.push(env.path[env.pathPointer]);
+            }
 
             // prepare fallback
             if (current[segment]['*']?.['*'] || current[segment]['*']?.[ctx.method]) {
                 result = current[segment]['*'][ctx.method] ?? current[segment]['*']['*'];
                 resultPointer = env.pathPointer + 1;
+                resultArgNames = current[segment]['*']['::' + ctx.method] ?? current[segment]['*']['::*'];
             }
 
             current = current[segment];
@@ -69,10 +86,17 @@ class PathRouter {
             if (env.pathPointer >= env.path.length && (current['@']?.['*'] || current['@']?.[ctx.method])) {
                 result = current['@'][ctx.method] ?? current['@']['*'];
                 resultPointer = env.pathPointer;
+                resultArgNames = current['@']['::' + ctx.method] ?? current['@']['::*'];
             }
         }
 
         env.pathPointer = resultPointer;
+        if (resultArgNames) {
+            const len = resultArgNames.length;
+            for (let i = 0; i < len; i++) {
+                ctx.params[resultArgNames[i]] = currentArgs[i];
+            }
+        }
         return result;
     }
 }
@@ -103,13 +127,22 @@ class HostRouter {
 
             // expand map
             let current = this.map;
+            let args = [];
             for (const segment of routeDomain) {
+                if (segment.startsWith('%:')) {
+                    args.push(segment.substring(2));
+                    if (!current[':']) current[':'] = {};
+                    current = current[':'];
+                    continue;
+                }
+
                 if (!current['.' + segment]) current['.' + segment] = {};
                 current = current['.' + segment];
             }
 
             // '*' for non-end check, '@' for end check
             current[routeEnd ? '@' : '*'] = value;
+            if (args.length > 0) current['::'] = args;
         }
     }
 
@@ -119,14 +152,21 @@ class HostRouter {
         let result = this.map['*'];
         let resultPointer = env.hostPointer;
         let current = this.map;
+        let currentArgs = [];
+        let resultArgNames;
         while (env.hostPointer < env.host.length) {
-            const segment = '.' + env.host[env.hostPointer];
-            if (!current[segment]) break;
+            let segment = '.' + env.host[env.hostPointer];
+            if (!current[segment] && !current[':']) break;
+            if (!current[segment]) {
+                segment = ':';
+                currentArgs.push(env.host[env.hostPointer]);
+            }
 
             // prepare fallback
             if (current[segment]['*']) {
                 result = current[segment]['*'];
                 resultPointer = env.hostPointer + 1;
+                resultArgNames = current[segment]['::'];
             }
 
             current = current[segment];
@@ -140,6 +180,12 @@ class HostRouter {
         }
 
         env.hostPointer = resultPointer;
+        if (resultArgNames) {
+            const len = resultArgNames.length;
+            for (let i = 0; i < len; i++) {
+                ctx.params[resultArgNames[i]] = currentArgs[i];
+            }
+        }
         return result;
     }
 }
@@ -157,12 +203,13 @@ class MethodRouter {
 
 // function router: a simple router that allows you to make custom routing logic
 class FunctionRouter {
-    constructor(fn) {
+    constructor(fn, ext) {
         this.fn = fn;
+        this.ext = ext;
     }
 
     route(env, ctx) {
-        return this.fn(env, ctx);
+        return this.fn(env, ctx, this.ext);
     }
 }
 
@@ -213,12 +260,11 @@ class SetCodeRouter {
 module.exports = {
     PathRouter, HostRouter, MethodRouter, FunctionRouter, PathArgRouter, HostArgRouter, SetCodeRouter,
     routerConstructors: {
-        Path: (...args) => new PathRouter(...args),
-        Host: (...args) => new HostRouter(...args),
-        Method: (...args) => new MethodRouter(...args),
-        Function: (...args) => new FunctionRouter(...args),
-        PathArg: (...args) => new PathArgRouter(...args),
-        HostArg: (...args) => new HostArgRouter(...args),
-        SetCode: (...args) => new SetCodeRouter(...args)
+        Path: (end, map) => new PathRouter(end, map),
+        Host: (end, map) => new HostRouter(end, map),
+        Method: (methodMap) => new MethodRouter(methodMap),
+        Function: (fn, ext) => new FunctionRouter(fn, ext),
+        PathArg: (name, next) => new PathArgRouter(name, next),
+        SetCode: (handlers, next) => new SetCodeRouter(handlers, next)
     }
 };

package/src/server.js

@@ -14,6 +14,7 @@ const http2 = require('http2');
 const path = require('path');
 const stream = require('stream');
 const EventEmitter = require('events');
+const constants = require('constants');
 
 // server class
 class Server extends EventEmitter {
@@ -106,11 +107,12 @@ class Server extends EventEmitter {
             } else if (typeof handler === 'function') { // function
                 await handler(ctx, env);
             } else if (typeof handler === 'string') { // string
+                const data = Buffer.from(handler, 'utf8');
                 ctx.res.writeHead(200, {
                     'Content-Type': 'text/plain; charset=utf-8',
-                    'Content-Length': Buffer.byteLength(handler, 'utf8')
+                    'Content-Length': data.length
                 });
-                ctx.res.end(handler, 'utf8');
+                ctx.res.end(data);
             } else if (handler instanceof Uint8Array) { // buffer
                 ctx.res.writeHead(200, {
                     'Content-Type': 'application/octet-stream',
@@ -130,11 +132,12 @@ class Server extends EventEmitter {
                 } else if (typeof handler === 'function') { // function
                     await handler(ctx, env);
                 } else if (typeof handler === 'string') { // string
+                    const data = Buffer.from(handler, 'utf8');
                     ctx.res.writeHead(code, {
                         'Content-Type': 'text/plain; charset=utf-8',
-                        'Content-Length': Buffer.byteLength(handler, 'utf8')
+                        'Content-Length': data.length
                     });
-                    ctx.res.end(handler, 'utf8');
+                    ctx.res.end(data);
                 } else if (handler instanceof Uint8Array) { // buffer
                     ctx.res.writeHead(code, {
                         'Content-Type': 'application/octet-stream',
@@ -164,11 +167,12 @@ class Server extends EventEmitter {
                 } else if (typeof handler === 'function') { // function
                     await handler(ctx, env);
                 } else if (typeof handler === 'string') { // string
+                    const data = Buffer.from(handler, 'utf8');
                     ctx.res.writeHead(code, {
                         'Content-Type': 'text/plain; charset=utf-8',
-                        'Content-Length': Buffer.byteLength(handler, 'utf8')
+                        'Content-Length': data.length
                     });
-                    ctx.res.end(handler, 'utf8');
+                    ctx.res.end(data);
                 } else if (handler instanceof Uint8Array) { // buffer
                     ctx.res.writeHead(code, {
                         'Content-Type': 'application/octet-stream',