tina4-nodejs 3.12.5 → 3.12.8

package/CLAUDE.md

@@ -1,10 +1,10 @@
-# CLAUDE.md — AI Developer Guide for tina4-nodejs (v3.12.5)
+# CLAUDE.md — AI Developer Guide for tina4-nodejs (v3.12.6)
 
 > This file helps AI assistants (Claude, Copilot, Cursor, etc.) understand and work on this codebase effectively.
 
 ## What This Project Is
 
-Tina4 for Node.js/TypeScript v3.12.5 — The Intelligent Native Application 4ramework. A convention-over-configuration structural paradigm. The developer writes TypeScript; Tina4 is invisible infrastructure.
+Tina4 for Node.js/TypeScript v3.12.6 — The Intelligent Native Application 4ramework. A convention-over-configuration structural paradigm. The developer writes TypeScript; Tina4 is invisible infrastructure.
 
 The philosophy: zero ceremony, batteries included, file system as source of truth.
 

package/package.json

@@ -1,13 +1,18 @@
 {
   "name": "tina4-nodejs",
-
-
-
-  "version": "3.12.5",
-
+  "version": "3.12.8",
   "type": "module",
-  "description": "Tina4 for Node.js/TypeScript — 54 built-in features, zero dependencies",
-  "keywords": ["tina4", "framework", "web", "api", "orm", "graphql", "websocket", "typescript"],
+  "description": "Tina4 for Node.js/TypeScript \u2014 54 built-in features, zero dependencies",
+  "keywords": [
+    "tina4",
+    "framework",
+    "web",
+    "api",
+    "orm",
+    "graphql",
+    "websocket",
+    "typescript"
+  ],
   "homepage": "https://tina4.com/nodejs",
   "repository": {
     "type": "git",
@@ -59,4 +64,4 @@
     "tsx": "^4.19.0",
     "esbuild": "^0.24.0"
   }
-}
+}

package/packages/core/src/router.ts

@@ -190,6 +190,28 @@ export class Router {
     return this.addRoute({ method: "DELETE", pattern: path, handler, middlewares, meta });
   }
 
+  /**
+   * Register an explicit HEAD route. By default the framework auto-handles
+   * HEAD by falling back to the GET route and stripping the body
+   * (RFC 9110 §9.3.2). Use this only when you need a HEAD handler that
+   * does something different from GET — e.g. cheaper existence-check
+   * logic, custom validator headers without the cost of building the body.
+   * The framework still strips the response body for you on the way out.
+   */
+  head(path: string, handler: RouteHandler, middlewares?: Middleware[], meta?: RouteMeta): RouteRef {
+    return this.addRoute({ method: "HEAD", pattern: path, handler, middlewares, meta });
+  }
+
+  /**
+   * Register an explicit OPTIONS route. By default the framework auto-
+   * handles OPTIONS by building an Allow header from every method
+   * registered for the path and returning 204 (RFC 9110 §9.3.7). Use
+   * this to take over that behaviour.
+   */
+  options(path: string, handler: RouteHandler, middlewares?: Middleware[], meta?: RouteMeta): RouteRef {
+    return this.addRoute({ method: "OPTIONS", pattern: path, handler, middlewares, meta });
+  }
+
   /**
    * Register a route that matches ANY HTTP method.
    */
@@ -222,28 +244,65 @@ export class Router {
 
     // Try exact method first, then ANY routes are already registered under each method
     const routes = this.routes.get(upperMethod);
-    if (!routes) return null;
-
-    const direct = this.matchRoute(routes, path);
-    if (direct) return direct;
-
-    // Trailing-slash redirect — strip a single trailing "/" and retry.
-    // Root "/" is intentionally excluded (it's its own route).
-    if (
-      isTrailingSlashRedirectEnabled() &&
-      path.length > 1 &&
-      path.endsWith("/")
-    ) {
-      const stripped = path.replace(/\/+$/, "");
-      if (stripped.length > 0) {
-        const retry = this.matchRoute(routes, stripped);
-        if (retry) return retry;
+    if (routes) {
+      const direct = this.matchRoute(routes, path);
+      if (direct) return direct;
+
+      // Trailing-slash redirect — strip a single trailing "/" and retry.
+      // Root "/" is intentionally excluded (it's its own route).
+      if (
+        isTrailingSlashRedirectEnabled() &&
+        path.length > 1 &&
+        path.endsWith("/")
+      ) {
+        const stripped = path.replace(/\/+$/, "");
+        if (stripped.length > 0) {
+          const retry = this.matchRoute(routes, stripped);
+          if (retry) return retry;
+        }
+      }
+    }
+
+    // RFC 9110 §9.3.2: HEAD is identical to GET except for the absence
+    // of a response body. If no explicit HEAD route matched, fall back
+    // to the GET route — the dispatcher strips the body on the way out.
+    if (upperMethod === "HEAD") {
+      const getRoutes = this.routes.get("GET");
+      if (getRoutes) {
+        return this.matchRoute(getRoutes, path);
       }
     }
 
     return null;
   }
 
+  /**
+   * Return the list of HTTP methods registered for ``path``, in canonical
+   * order GET / POST / PUT / PATCH / DELETE / HEAD / OPTIONS. Used by the
+   * dispatcher to build the ``Allow:`` header on 405 / OPTIONS responses
+   * (RFC 9110 §10.2.1, §9.3.7).
+   *
+   * If GET is registered, HEAD is appended implicitly (HEAD auto-fallback).
+   * OPTIONS is appended whenever any method exists for the path (the
+   * framework auto-handles OPTIONS).
+   */
+  methodsAllowedForPath(path: string): string[] {
+    const order = ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"];
+    const seen = new Set<string>();
+    for (const m of order) {
+      const routes = this.routes.get(m);
+      if (!routes) continue;
+      if (this.matchRoute(routes, path)) {
+        seen.add(m);
+      }
+    }
+    if (seen.size > 0) {
+      if (seen.has("GET")) seen.add("HEAD");
+      seen.add("OPTIONS");
+    }
+    return order.filter((m) => seen.has(m));
+  }
+
   /** Inner match against a list of compiled routes, no trailing-slash logic. */
   private matchRoute(routes: CompiledRoute[], path: string): MatchResult | null {
     for (const route of routes) {

package/packages/core/src/server.ts

@@ -913,6 +913,36 @@ ${reset}
     const req = createRequest(rawReq);
     const res = createResponse(rawRes);
 
+    // RFC 9110 §9.3.2: the server MUST NOT send content in a HEAD response.
+    // Intercept rawRes.write / rawRes.end so every code path — explicit
+    // Router.head() handler, GET auto-fallback, 405 / 404 responses — drops
+    // its body. Content-Length is preserved when present, so cache
+    // validators / link checkers / monitoring probes still see the size
+    // the equivalent GET would have sent.
+    if ((rawReq.method ?? "GET").toUpperCase() === "HEAD") {
+      const origEnd = rawRes.end.bind(rawRes);
+      const origWrite = rawRes.write.bind(rawRes);
+      let accumulated = 0;
+      rawRes.write = ((chunk?: any, _enc?: any, cb?: any): boolean => {
+        if (chunk != null) {
+          accumulated += Buffer.isBuffer(chunk) ? chunk.length : Buffer.byteLength(String(chunk));
+        }
+        if (typeof cb === "function") cb();
+        return true;
+      }) as typeof rawRes.write;
+      rawRes.end = ((chunk?: any, _enc?: any, cb?: any): any => {
+        if (chunk != null && typeof chunk !== "function") {
+          accumulated += Buffer.isBuffer(chunk) ? chunk.length : Buffer.byteLength(String(chunk));
+        }
+        if (accumulated > 0 && !rawRes.headersSent && !rawRes.hasHeader("Content-Length")) {
+          rawRes.setHeader("Content-Length", String(accumulated));
+        }
+        const realCb = typeof chunk === "function" ? chunk : cb;
+        return origEnd(undefined, undefined, realCb);
+        void origWrite; // referenced to keep tsc happy
+      }) as typeof rawRes.end;
+    }
+
     // Auto-start session — read cookie, create session, save + set cookie on response end
     {
       const { Session, buildSessionCookie } = await import("./session.js");
@@ -1170,6 +1200,36 @@ ${reset}
         }
       }
 
+      // RFC 9110 conformance — before falling through to 404, check whether
+      // the PATH is registered under any OTHER method.
+      //   - OPTIONS request → 204 with Allow header (§9.3.7)
+      //   - Any other method (PUT on GET-only, TRACE, CONNECT, etc.)
+      //     → 405 with Allow header (§15.5.6 + §10.2.1)
+      const allowedMethods = router.methodsAllowedForPath(pathname);
+      if (allowedMethods.length > 0) {
+        const allowHeader = allowedMethods.join(", ");
+        const requestMethod = (req.method ?? "GET").toUpperCase();
+        if (requestMethod === "OPTIONS") {
+          res.raw.writeHead(204, undefined, { Allow: allowHeader, "Content-Length": "0" });
+          res.raw.end();
+          return;
+        }
+        const body = JSON.stringify({
+          error: "Method Not Allowed",
+          path: pathname,
+          method: requestMethod,
+          allow: allowedMethods,
+          statusCode: 405,
+        });
+        res.raw.writeHead(405, httpReason(405), {
+          Allow: allowHeader,
+          "Content-Type": "application/json",
+          "Content-Length": String(Buffer.byteLength(body)),
+        });
+        res.raw.end(body);
+        return;
+      }
+
       // 404 — pass canonical reason phrase so the status line is well-formed
       const html404 = await renderErrorPage(404, { path: pathname }, templatesDir);
       if (html404) {