@smuzi/http-server 0.0.2 → 0.0.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 smuzi-ts
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/build/config.js

@@ -1,7 +1,7 @@
 import { HttpProtocol, None, HttpResponse, dump } from "@smuzi/std";
 function http1ErrorHandler(context, error) {
     //TODO: write error to log and remove dump()
-    dump(error);
+    dump({ msg: "http1ErrorHandler", error });
     return HttpResponse.asJson({ error: "Internal Server Error" }, 500);
 }
 export function buildHttp1ServerConfig({ host = 'localhost', port = 8080, router, cert = None(), errorHandler = http1ErrorHandler }) {

package/build/drivers/http1Server.js

@@ -3,7 +3,8 @@ import https from 'node:https';
 import { TLSSocket } from 'node:tls';
 import fs from 'node:fs';
 import { methodFromString } from "#lib/router.js";
-import { isArray, isObject, isString, matchUnknown, OptionFromNullable, Err, Ok, isNull, transformError, StdError, HttpResponse, HttpRequest, StdMap, isOption, isResult, RequestHttpHeaders, asList, asRecord, asMap, querystring, StdJson } from '@smuzi/std';
+import { isArray, isObject, isString, StdRecord, matchUnknown, OptionFromNullable, Err, Ok, isNull, transformError, StdError, HttpResponse, HttpRequest, isOption, isResult, RequestHttpHeaders, asList, asRecord, asMap, querystring, StdJson } from '@smuzi/std';
+import { log } from 'node:console';
 export class StdHttp1Server {
     #server;
     constructor(server) {
@@ -94,7 +95,7 @@ export async function http1ServerRun(config) {
                 request: new HttpRequest({
                     method: request.method,
                     path: request.path,
-                    query: () => new StdMap(urlObj.searchParams),
+                    query: () => new StdRecord(Object.fromEntries(urlObj.searchParams.entries())),
                     headers: new RequestHttpHeaders(nativeRequest.headers),
                     buffer: readRequestBodyAsBuffer(nativeRequest),
                     body: readRawBody(nativeRequest),
@@ -171,6 +172,7 @@ export async function http1ServerRun(config) {
             }
         });
         server.once('error', (nativeError) => {
+            log("Server started on", nativeError);
             resolve(Err({
                 errno: OptionFromNullable(nativeError.errno),
                 code: OptionFromNullable(nativeError.code),
@@ -181,6 +183,7 @@ export async function http1ServerRun(config) {
             }));
         });
         server.listen(config.port, () => {
+            log("Server started on " + config.protocol + "://" + config.host + ":" + config.port);
             resolve(Ok(new StdHttp1Server(server)));
         });
     });

package/build/router.js

@@ -11,7 +11,13 @@ export function contactPaths(path1, path2) {
     const path1AsRegExp = asRegExp(path1);
     const path2AsRegExp = asRegExp(path2);
     if (path1AsRegExp || path2AsRegExp) {
-        return new RegExp((path1AsRegExp ? path1.source : path1) + (path2AsRegExp ? path2.source : path2));
+        const source1 = path1AsRegExp
+            ? path1.source
+            : path1;
+        const source2 = path2AsRegExp
+            ? path2.source
+            : path2;
+        return new RegExp("^" + (source1 + source2).replaceAll('^', ''));
     }
     return path1 + path2;
 }
@@ -47,8 +53,18 @@ function http2NotFoundHandler(context) {
 }
 export function CreateHttpRouter(groupRoute, notFound) {
     const routes = new Map();
+    // Every own route/subgroup is registered ONCE at startup. We additionally
+    // remember each one's path *relative to this router* so that, if this
+    // router later gets attached to a parent via `.group()`, we can recompute
+    // every already-registered absolute path exactly once at that moment —
+    // never again on every match()/request.
+    const ownRoutes = [];
+    const ownGroups = [];
+    const computeAbsolute = (localPath) => processPath(contactPaths(groupRoute.path, localPath));
     const add = (route, action) => {
-        route.path = processPath(contactPaths(groupRoute.path, route.path));
+        const localPath = route.path;
+        route.path = computeAbsolute(localPath);
+        ownRoutes.push({ route, localPath });
         routes.set(route, (routeData) => {
             return {
                 action,
@@ -56,11 +72,26 @@ export function CreateHttpRouter(groupRoute, notFound) {
             };
         });
     };
-    const addGroup = (route, action) => {
-        route.path = processPath(contactPaths(groupRoute.path, route.path));
+    const addGroup = (localGroupPath, childRouter, action) => {
+        const route = { path: computeAbsolute(toStartWithPattern(localGroupPath)) };
+        ownGroups.push({ route, localGroupPath, childRouter });
         routes.set(route, action);
     };
-    return {
+    // Recomputes this router's own base plus every route/subgroup registered
+    // on it so far, then recurses into any already-nested group routers so
+    // the whole subtree stays consistent — called once, when this router is
+    // attached to a parent via `.group()`.
+    const rebase = (newBase) => {
+        groupRoute.path = newBase;
+        for (const entry of ownRoutes) {
+            entry.route.path = computeAbsolute(entry.localPath);
+        }
+        for (const entry of ownGroups) {
+            entry.route.path = computeAbsolute(toStartWithPattern(entry.localGroupPath));
+            entry.childRouter.__rebase(contactPaths(newBase, entry.localGroupPath));
+        }
+    };
+    const router = {
         get(path, action) {
             add({ path, method: HttpMethod.GET }, action);
         },
@@ -74,11 +105,13 @@ export function CreateHttpRouter(groupRoute, notFound) {
             add({ path, method: HttpMethod.DELETE }, action);
         },
         group(groupRouter) {
-            const groupPath = groupRouter.getGroupRoute().path;
-            const startWithPattern = toStartWithPattern(groupPath);
-            addGroup({ path: startWithPattern }, (routeData) => {
+            const localGroupPath = groupRouter.getGroupRoute().path;
+            addGroup(localGroupPath, groupRouter, (routeData) => {
                 return groupRouter.match(routeData.val);
             });
+            // Re-derive every path already registered on the nested router
+            // (and anything nested under IT) against our current absolute base.
+            groupRouter.__rebase(contactPaths(groupRoute.path, localGroupPath));
         },
         getMapRoutes() {
             return routes;
@@ -93,8 +126,10 @@ export function CreateHttpRouter(groupRoute, notFound) {
                     pathParams: routeData.params.flatByKey("path"),
                 };
             });
-        }
+        },
+        __rebase: rebase,
     };
+    return router;
 }
 export function CreateHttp1Router(groupRoute, notFound = http1NotFoundHandler) {
     return CreateHttpRouter(groupRoute, notFound);

package/package.json

@@ -1,13 +1,9 @@
 {
   "name": "@smuzi/http-server",
-  "version": "0.0.2",
+  "version": "0.0.3",
   "description": "HTTP server and routing for JavaScript and TypeScript",
-  "scripts": {
-    "test": "tsx tests/index.ts",
-    "build": "tsc --project tsconfig.build.json",
-    "prepublishOnly": "npm run build"
-  },
   "type": "module",
+  "types": "./build/index.d.ts",
   "keywords": [
     "http",
     "router",
@@ -22,21 +18,30 @@
     "access": "public"
   },
   "files": [
+    "./src",
     "./build"
   ],
   "exports": {
-    ".": "./src/index.js"
+    "./package.json": "./package.json",
+    ".": "./src/index.ts",
+    "./*": "./src/*.ts"
   },
   "imports": {
     "#lib/*": "./src/*"
   },
+  "dependencies": {
+    "@smuzi/std": "0.2.4",
+    "@smuzi/schema": "0.0.2"
+  },
   "devDependencies": {
-    "@smuzi/std": "workspace:*",
-    "@smuzi/faker": "workspace:*",
-    "@smuzi/schema": "workspace:*",
-    "@smuzi/tests": "workspace:*",
+    "@smuzi/faker": "0.0.2",
+    "@smuzi/tests": "0.0.1",
     "@types/node": "^22.15.21",
     "tsx": "^4.20.6",
     "typescript": "^7.0.2"
+  },
+  "scripts": {
+    "test": "tsx --conditions=development tests/index.ts",
+    "build": "tsc --project tsconfig.build.json"
   }
 }

package/src/config.ts

@@ -0,0 +1,60 @@
+import {Option, HttpProtocol, None, HttpResponse, transformError, dump} from "@smuzi/std";
+import {ActionErrorHandler, Context, Http1Router} from "#lib/router.js";
+import {ServerResponse} from "node:http";
+
+type Cert = Option<{
+        key: string,
+        cert: string,
+    }>
+
+export type Http1ServerConfig = {
+    host: string;
+    port: number,
+    router: Http1Router,
+    cert: Cert,
+    protocol: HttpProtocol,
+    errorHandler: ActionErrorHandler<ServerResponse>
+}
+
+type InputHttp1ServerConfig = Partial<Http1ServerConfig> & {
+    router: Http1Router,
+}
+
+function http1ErrorHandler(context: Context<ServerResponse>, error) {
+    //TODO: write error to log and remove dump()
+    dump({msg: "http1ErrorHandler", error})
+    return HttpResponse.asJson({error:"Internal Server Error"}, 500);
+}
+
+export function buildHttp1ServerConfig({host = 'localhost', port = 8080, router, cert = None(), errorHandler = http1ErrorHandler}: InputHttp1ServerConfig): Http1ServerConfig {
+    return {
+        host, 
+        port,
+        router,
+        cert,
+        protocol: cert.someOrNone(HttpProtocol.HTTPS, HttpProtocol.HTTP),
+        errorHandler,
+    };
+};
+
+type Http2BaseServerConfig = {
+    host: string;
+    port: number,
+    router: Http1Router,
+    cert?: Cert
+}
+
+export type Http2ServerConfig = Http2BaseServerConfig & {
+    cert: Cert,
+    protocol: HttpProtocol,
+}
+
+export function buildHttp2ServerConfig({host, port, router, cert = None() }: Http2BaseServerConfig): Http2ServerConfig {
+    return {
+        host, 
+        port,
+        router,
+        cert,
+        protocol: cert.someOrNone(HttpProtocol.HTTPS, HttpProtocol.HTTP)
+    };
+};

package/src/drivers/http1Server.ts

@@ -0,0 +1,263 @@
+import http, { IncomingMessage, ServerResponse } from 'node:http';
+import https from 'node:https';
+import { TLSSocket } from 'node:tls';
+import fs from 'node:fs';
+
+import { methodFromString } from "#lib/router.js";
+import {
+    isArray,
+    isObject,
+    isString,
+    match,
+    StdRecord,
+    matchUnknown,
+    OptionFromNullable,
+    Some,
+    Result,
+    Option,
+    Err,
+    Ok,
+    isNull,
+    transformError,
+    StdError,
+    dump,
+    HttpResponse,
+    HttpRequest,
+    StdMap,
+    isSome,
+    isOption,
+    isResult,
+    isIterable,
+    ResponseHttpHeaders, RequestHttpHeaders, asList, asRecord, asMap, querystring, QueryParams,
+    StdJson, uuid
+} from '@smuzi/std';
+import { HttpServer, HttpServerRunError, Http1ServerConfig } from "#lib/index.js";
+import { log } from 'node:console';
+
+type NativeServer = any
+
+export class StdHttp1Server implements HttpServer {
+    readonly #server: NativeServer
+
+    constructor(server: NativeServer) {
+        this.#server = server;
+    }
+    async close(): Promise<Result<boolean, StdError>> {
+        return new Promise(resolve => {
+            this.#server.close((err) => {
+                return resolve(isNull(err) ? Ok(true) : Err(transformError(err)));
+            })
+        })
+    }
+}
+
+function readRequestBodyAsBuffer(req: IncomingMessage): () => Promise<Result<Buffer, Error>> {
+    return async () => {
+        return new Promise((resolve, reject) => {
+            const chunks: Buffer[] = [];
+
+            req.on("data", (chunk) => {
+                chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+            });
+
+            req.on("end", () => {
+                resolve(Ok(Buffer.concat(chunks)));
+            });
+
+            req.on("error", (err) => reject(Err(err)));
+        });
+    }
+}
+
+function readRequestJson(req: IncomingMessage): <T>() => Promise<Result<Option<T>, StdError>> {
+    return async(encoding: BufferEncoding = "utf-8") => {
+        return new Promise((resolve) => {
+        let body = "";
+
+        req.setEncoding(encoding);
+
+        req.on("data", (chunk: string) => {
+            body += chunk;
+        });
+
+        req.on("end", () => {
+            resolve(StdJson.fromString(body));
+        });
+
+        req.on("error", (err) => resolve(Err(transformError(err))));
+    });
+    }
+}
+
+function readRequestInput(req: IncomingMessage): <T extends StdRecord<QueryParams>>() => Promise<Result<T, StdError>> {
+    return async(encoding: BufferEncoding = "utf-8") => {
+        return new Promise((resolve) => {
+            let body = "";
+
+            req.setEncoding(encoding);
+
+            req.on("data", (chunk: string) => {
+                body += chunk;
+            });
+
+            req.on("end", () => {
+                resolve(querystring.fromString(body));
+            });
+
+            req.on("error", (err) => resolve(Err(transformError(err))));
+        });
+    }
+}
+
+function readRawBody(req: IncomingMessage): <T>() => Promise<Result<string, StdError>> {
+    return async(encoding: BufferEncoding = "utf-8") => {
+        return new Promise((resolve) => {
+            let body = "";
+
+            req.setEncoding(encoding);
+
+            req.on("data", (chunk: string) => {
+                body += chunk;
+            });
+
+            req.on("end", () => {
+                resolve(Ok(body));
+            });
+
+            req.on("error", (err) => resolve(Err(transformError(err))));
+        });
+    }
+}
+
+let COUNTER = 0;
+
+export async function http1ServerRun(config: Http1ServerConfig): Promise<Result<StdHttp1Server, HttpServerRunError>> {
+    return new Promise((resolve) => {
+        async function handler(nativeRequest: IncomingMessage, nativeResponse: ServerResponse) {
+            const methodStr = OptionFromNullable(nativeRequest.method).unwrap();
+            const fullUrl = nativeRequest.url || "/";
+            const isHttps = nativeRequest.socket instanceof TLSSocket;
+            const urlObj = new URL(fullUrl, (isHttps ? "http" : "https") + `://${nativeRequest.headers.host}`);
+            const path = OptionFromNullable(urlObj.pathname).unwrap();
+            const request = {
+                path:  path.replace(/^\//, '').replace(/\/$/, ''),
+                method: methodFromString(methodStr).unwrap(`Error: undefined http method '${methodStr}'`),
+            };
+            
+            const routeMatched = config.router.match(request);
+
+            let context = {
+                request: new HttpRequest({
+                    method: request.method,
+                    path: request.path,
+                    query: () => new StdRecord<QueryParams>(Object.fromEntries(urlObj.searchParams.entries())),
+                    headers: new RequestHttpHeaders(nativeRequest.headers as any),
+                    buffer: readRequestBodyAsBuffer(nativeRequest),
+                    body: readRawBody(nativeRequest),
+                    json: readRequestJson(nativeRequest),
+                    form: readRequestInput(nativeRequest),
+                }),
+                response: nativeResponse,
+                pathParams: routeMatched.pathParams,
+            };
+
+            let response;
+            try {
+                response = await routeMatched.action(context)
+            } catch (error) {
+                response = await config.errorHandler(context, error);
+            }
+
+
+            if (isOption(response)) {
+                response = response.someOr("");
+            } else if(isResult(response)) {
+                response = response.unsafeSource();
+            }
+
+            if (isNull(response)) {
+                return;
+            }
+
+            const handlers = new Map();
+            
+            handlers.set(resp => isString(resp) || resp instanceof Buffer, (response) => {
+                nativeResponse.writeHead(200, {
+                    "Content-Type": "text/html; charset=utf-8",
+                });
+                nativeResponse.end(response);
+            });
+
+            handlers.set(resp => resp instanceof HttpResponse, (response: HttpResponse) => {
+                nativeResponse.statusCode = response.status;
+                nativeResponse.statusMessage = response.statusText;
+                nativeResponse.setHeaders(response.headers.unsafeSource());
+                nativeResponse.end(response.body.someOr(""));
+            });
+
+            handlers.set(resp => resp instanceof StdError, (error: StdError) => {
+                nativeResponse.statusCode = 500;
+                nativeResponse.statusMessage = error.message;
+                nativeResponse.end(error.message);
+            });
+
+            handlers.set(
+                (response) => isObject(response) || isArray(response) || asList(response) || asRecord(response) || asMap(response),
+                (response) => {
+                    //TODO: return respons on top instead of changed nativeResponse inner
+                    nativeResponse.setHeader("Content-Type", "application/json; charset=utf-8" );
+
+                    try {
+                        const resp = StdJson.toString(response).match({
+                            Ok: (jsonStr) => ({status: 200, body: jsonStr }),
+                            Err: (err) => ({status: 500 , body: '{"error":"Internal Server Error"}' }),
+                        });
+                        nativeResponse.statusCode = resp.status;
+                        nativeResponse.end(resp.body);
+                    } catch (err) {
+                        nativeResponse.statusCode = 500;
+                        nativeResponse.end('{"error":"Internal Server Error"}');
+                    }
+                }
+            );
+
+
+            matchUnknown(response, handlers, () => {
+                nativeResponse.writeHead(500, { "Content-Type": "text/html; charset=utf-8" });
+                nativeResponse.end("Internal Server Error");
+            }, false);
+        }
+
+        const server = config.cert.match({
+            Some: cert => {
+                return https.createServer({
+                    key: fs.readFileSync(cert.key),
+                    cert: fs.readFileSync(cert.cert),
+                }, handler);
+            },
+            None: () => {
+                return http.createServer(handler);
+            }
+        })
+
+
+        server.once('error', (nativeError: any) => {
+            log("Server started on", nativeError);
+            resolve(Err({
+                errno: OptionFromNullable(nativeError.errno),
+                code: OptionFromNullable(nativeError.code),
+                syscall: OptionFromNullable(nativeError.syscall),
+                path: OptionFromNullable(nativeError.path),
+                port: OptionFromNullable(nativeError.port),
+                address: OptionFromNullable(nativeError.address),
+            }));
+        });
+
+        server.listen(config.port, () => {
+            log("Server started on " + config.protocol + "://" + config.host + ":" + config.port)
+
+            resolve(Ok(new StdHttp1Server(server)));
+        });
+
+    });
+}

package/src/drivers/http2Server.ts

@@ -0,0 +1,125 @@
+import http2, { Http2SecureServer, Http2Server, IncomingHttpHeaders, ServerHttp2Stream } from 'node:http2';
+import fs from 'node:fs';
+
+import { methodFromString } from "#lib/router.js";
+import { isArray, isObject, isString, match, matchUnknown, OptionFromNullable, Some, Result, Option, Err, Ok, isNull, transformError, StdError, dump, HttpResponse, StdJson } from '@smuzi/std';
+import { HttpServer, HttpServerRunError, Http2ServerConfig } from "#lib/index.js";
+
+type NativeServer = Http2SecureServer | Http2Server;
+
+export class StdHttp2Server implements HttpServer {
+    readonly #server: NativeServer
+
+    constructor(server: NativeServer) {
+        this.#server = server;
+    }
+    async close(): Promise<Result<boolean, StdError>> {
+        return new Promise(resolve => {
+            this.#server.close((err) => {
+                return resolve(isNull(err) ? Ok(true) : Err(transformError(err)));
+            })
+        })
+    }
+}
+
+export function http2ServerRun(config: Http2ServerConfig): Promise<Result<StdHttp2Server, HttpServerRunError>> {
+    return new Promise((resolve) => {
+
+        const server = config.cert.match({
+            Some: cert => {
+                return http2.createSecureServer({
+                    key: fs.readFileSync(cert.key),
+                    cert: fs.readFileSync(cert.cert),
+                });
+            },
+            None: () => {
+                return http2.createServer();
+            }
+        })
+
+
+        server.once('error', (nativeError) => {
+            resolve(Err({
+                errno: OptionFromNullable(nativeError.errno),
+                code: OptionFromNullable(nativeError.code),
+                syscall: OptionFromNullable(nativeError.syscall),
+                path: OptionFromNullable(nativeError.path),
+                port: OptionFromNullable(nativeError.port),
+                address: OptionFromNullable(nativeError.address),
+            }));
+        });
+
+        server.on('stream', (stream: ServerHttp2Stream, headers: IncomingHttpHeaders) => {
+            const methodStr = OptionFromNullable(headers[':method']).unwrap();
+            const path = OptionFromNullable(headers[':path']).unwrap().replace(/^\//, '').replace(/\/$/, '');
+            const urlObj = new URL(path, `http://${headers[':authority']}`);
+
+            const request = {
+                path: path,
+                method: methodFromString(methodStr).unwrap(`Error: undefined http method '${methodStr}'`),
+                query: urlObj.searchParams,
+            };
+
+            const response = config.router.match(request)
+            const handlers = new Map();
+
+
+            handlers.set(isString, (response) => {
+                stream.respond({
+                    'content-type': 'text/html; charset=utf-8',
+                    ':status': 200,
+                });
+                stream.end(response)
+            });
+
+            handlers.set(resp => resp instanceof HttpResponse, (response: HttpResponse) => {
+                stream.respond({
+                    'content-type': 'application/json; charset=utf-8',
+                    ':status': response.status,
+
+                });
+            });
+            
+
+
+            handlers.set(response => isObject(response) || isArray(response), (response) => {
+                stream.respond({
+                    'content-type': 'application/json; charset=utf-8',
+                    ':status': 200,
+                });
+
+                stream.end(StdJson.toString(response).match({
+                    Ok: (json) => json,
+                    Err: (err) => {
+                        stream.respond({
+                            'content-type': 'application/json; charset=utf-8',
+                            ':status': 500,
+                        });
+
+                        return `{"error":"Internal Server Error"}`;
+                    }
+                }));
+
+            });
+
+
+            matchUnknown(
+                response,
+                handlers,
+                _ => {
+                    stream.respond({
+                        ':status': 500,
+                    })
+                    stream.end('Internal Server Error');
+                },
+                false
+            )
+
+        });
+
+        server.listen(config.port, () => {
+            resolve(Ok(new StdHttp2Server(server)));
+        });
+
+    });
+}

package/src/index.ts

@@ -0,0 +1,5 @@
+export * from "#lib/drivers/http2Server.js";
+export * from "#lib/drivers/http1Server.js";
+export * from "#lib/config.js" ;
+export * from "./router.js" ;
+export * from "#lib/types.js" ;

package/src/router.ts

@@ -0,0 +1,257 @@
+import {
+    asRegExp,
+    asString,
+    match,
+    MatchedData,
+    None,
+    Option,
+    Some,
+    HttpMethod,
+    HttpRequest,
+    Result,
+    HttpResponse,
+    StdError,
+    StdMap, StdRecord, StdList,
+} from "@smuzi/std";
+import { ServerResponse } from "node:http";
+import { ServerHttp2Stream } from "node:http2";
+
+
+type Request = { path: string, method: HttpMethod };
+type P = any;
+type ActionPrimitiveResponse = P | StdMap<string> | StdRecord<any> | StdList | Record<PropertyKey, P> | Record<PropertyKey, P>[];
+export type ActionResponse = void | ActionPrimitiveResponse | HttpResponse | Option<ActionPrimitiveResponse> | Result<ActionPrimitiveResponse, ActionPrimitiveResponse>;
+
+export type Action<Resp extends THttpResponse> = (context: Context<Resp>) => ActionResponse | Promise<ActionResponse>
+export type PathParam = string | RegExp;
+export type ActionErrorHandler<Resp extends THttpResponse> = (context: Context<Resp>, err: any) => ActionResponse | Promise<ActionResponse>
+
+type THttpResponse = ServerResponse | ServerHttp2Stream
+type Route = { path: PathParam, method: HttpMethod };
+type GroupRoute = { path: PathParam };
+type RouteMatched = MatchedData<Request, Option<{ path: Record<string, string> }>>
+type RouteMatchResult<Resp extends THttpResponse> = {
+    action: Action<Resp>,
+    pathParams: Option<Record<string, string | number | boolean>>
+}
+
+export type Router<Resp extends THttpResponse, A = Action<Resp>> = {
+    group: (groupRouter: Router<Resp>) => void
+    getMapRoutes: () => Map<Route, (routeData: RouteMatched) => RouteMatchResult<Resp>>
+    getGroupRoute(): GroupRoute
+    get: (path: PathParam, action: A) => void
+    post: (path: PathParam, action: A) => void
+    put: (path: PathParam, action: A) => void
+    delete: (path: PathParam, action: A) => void
+    match: (request: Request) => RouteMatchResult<Resp>
+}
+
+export type Http1Router = Router<ServerResponse>;
+export type Http2Router = Router<ServerHttp2Stream>;
+
+export type Context<Resp extends THttpResponse, Params = unknown,> = {
+    request: HttpRequest,
+    response: Resp,
+    pathParams: Params,
+}
+
+export function processPath(path: PathParam): PathParam {
+    if (!asString(path)) return path;
+    if (! /\{[a-zA-Z0-9_]+\}/g.test(path)) return path;
+
+    const pattern = `^${path.replace(/\{([a-zA-Z0-9_]+)\}/g, (_, name) => `(?<${name}>[^/]+)`).replace(/\//g, '\\/')}$`;
+    return new RegExp(pattern);
+
+}
+
+export function contactPaths(path1: PathParam, path2: PathParam): PathParam | never {
+    const path1AsRegExp = asRegExp(path1);
+    const path2AsRegExp = asRegExp(path2);
+
+    if (path1AsRegExp || path2AsRegExp) {
+ const source1 = path1AsRegExp
+            ? path1.source
+            : path1;
+
+        const source2 = path2AsRegExp
+            ? path2.source
+            : path2;
+
+        return new RegExp(
+            "^"+(source1 + source2).replaceAll('^', '')
+        );    
+    }
+
+    return path1 + path2;
+}
+
+
+export function toStartWithPattern(input: PathParam): RegExp {
+    if (asString(input)) {
+        const escaped = input.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+        return new RegExp(`^${escaped}.*`);
+    }
+
+    let pattern = input.source;
+
+    if (pattern.endsWith('$')) {
+        pattern = pattern.slice(0, -1);
+    }
+
+    return new RegExp(`${pattern}.*`, input.flags);
+}
+
+
+export function methodFromString(method: string): Option<HttpMethod> {
+    const handers = new Map<string, Option<HttpMethod>>([
+        ['GET', Some(HttpMethod.GET)],
+        ['POST', Some(HttpMethod.POST)],
+        ['PUT', Some(HttpMethod.PUT)],
+        ['DELETE', Some(HttpMethod.DELETE)],
+    ]);
+
+    return match(
+        method,
+        handers,
+        None(),
+        false
+    );
+}
+
+function http1NotFoundHandler(context: Context<ServerResponse>) {
+    return HttpResponse.asJson({error:"Not Found"}, 404);
+}
+
+
+function http2NotFoundHandler(context: Context<ServerHttp2Stream>) {
+    context.response.respond({
+        'content-type': 'application/json; charset=utf-8',
+        ':status': 404,
+    });
+    context.response.end();
+
+}
+
+
+
+// Internal-only surface: lets a parent router recompute a child router's
+// (and, recursively, its own nested groups') absolute paths after nesting.
+// Not part of the public `Router` type — accessed via a narrow cast.
+type Rebasable = { __rebase: (newBase: PathParam) => void };
+
+export function CreateHttpRouter<Resp extends THttpResponse, GR extends Router<Resp>>(
+    groupRoute: GroupRoute,
+    notFound: Action<Resp>,
+): Router<Resp> {
+    const routes = new Map()
+
+    // Every own route/subgroup is registered ONCE at startup. We additionally
+    // remember each one's path *relative to this router* so that, if this
+    // router later gets attached to a parent via `.group()`, we can recompute
+    // every already-registered absolute path exactly once at that moment —
+    // never again on every match()/request.
+    const ownRoutes: { route: Route; localPath: PathParam }[] = [];
+    const ownGroups: { route: GroupRoute; localGroupPath: PathParam; childRouter: Router<any> }[] = [];
+
+    const computeAbsolute = (localPath: PathParam) =>
+        processPath(contactPaths(groupRoute.path, localPath));
+
+    const add = (route: Route, action: any) => {
+        const localPath = route.path;
+        route.path = computeAbsolute(localPath);
+        ownRoutes.push({ route, localPath });
+
+        routes.set(route, (routeData: RouteMatched) => {
+            return {
+                action,
+                pathParams: routeData.params.flatByKey("path"),
+            };
+        })
+    };
+
+    const addGroup = (localGroupPath: PathParam, childRouter: Router<any>, action: any) => {
+        const route: GroupRoute = { path: computeAbsolute(toStartWithPattern(localGroupPath)) };
+        ownGroups.push({ route, localGroupPath, childRouter });
+        routes.set(route, action)
+    };
+
+    // Recomputes this router's own base plus every route/subgroup registered
+    // on it so far, then recurses into any already-nested group routers so
+    // the whole subtree stays consistent — called once, when this router is
+    // attached to a parent via `.group()`.
+    const rebase = (newBase: PathParam) => {
+        groupRoute.path = newBase;
+
+        for (const entry of ownRoutes) {
+            entry.route.path = computeAbsolute(entry.localPath);
+        }
+
+        for (const entry of ownGroups) {
+            entry.route.path = computeAbsolute(toStartWithPattern(entry.localGroupPath));
+            (entry.childRouter as unknown as Rebasable).__rebase(
+                contactPaths(newBase, entry.localGroupPath)
+            );
+        }
+    };
+
+    const router: Router<Resp> & Rebasable = {
+        get(path, action) {
+            add({ path, method: HttpMethod.GET }, action)
+        },
+        post(path, action) {
+            add({ path, method: HttpMethod.POST }, action)
+        },
+        put(path, action) {
+            add({ path, method: HttpMethod.PUT }, action)
+        },
+        delete(path, action) {
+            add({ path, method: HttpMethod.DELETE }, action)
+        },
+        group(groupRouter: GR) {
+            const localGroupPath = groupRouter.getGroupRoute().path;
+
+            addGroup(localGroupPath, groupRouter, (routeData: RouteMatched) => {
+                return groupRouter.match(routeData.val);
+            });
+
+            // Re-derive every path already registered on the nested router
+            // (and anything nested under IT) against our current absolute base.
+            (groupRouter as unknown as Rebasable).__rebase(
+                contactPaths(groupRoute.path, localGroupPath)
+            );
+        },
+        getMapRoutes() {
+            return routes;
+        },
+        getGroupRoute(): GroupRoute {
+            return groupRoute;
+        },
+        match(request: Request) {
+            return match(request, this.getMapRoutes(), (routeData: RouteMatched) => {
+                return {
+                    action: notFound,
+                    pathParams: routeData.params.flatByKey("path"),
+                } as RouteMatchResult<Resp>;
+            })
+        },
+        __rebase: rebase,
+    };
+
+    return router;
+}
+
+
+
+export function CreateHttp1Router(
+    groupRoute: GroupRoute,
+    notFound: Action<ServerResponse> = http1NotFoundHandler,
+): Http1Router {
+    return CreateHttpRouter<ServerResponse, Http1Router>(groupRoute, notFound);
+}
+
+// export function CreateHttp2Router(
+//     groupRoute: GroupRoute,
+//     notFound: Action<ServerHttp2Stream> = http2NotFoundHandler
+// ): Http2Router {
+//     return CreateHttpRouter<ServerHttp2Stream, Http2Router>(groupRoute, notFound);
+// }

package/src/types.ts

@@ -0,0 +1,14 @@
+import { Option, Result, StdError } from "@smuzi/std";
+
+export interface HttpServer {
+     close(): Promise<Result<boolean, StdError>>
+}
+
+export type HttpServerRunError = {
+    errno: Option<number>,
+    code: Option<string>,
+    syscall: Option<string>,
+    path: Option<string>,
+    port: Option<string>,
+    address: Option<string>,
+};