tina4-nodejs 3.12.10 → 3.13.1

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

@@ -19,6 +19,7 @@ import { createHealthRoutes } from "./health.js";
 import { rateLimiter } from "./rateLimiter.js";
 import { Log } from "./logger.js";
 import { DevAdmin, RequestInspector } from "./devAdmin.js";
+import { feedbackEnabled, injectFeedbackWidget } from "./feedback.js";
 import { I18n } from "./i18n.js";
 import { stopAllBackgroundTasks } from "./background.js";
 
@@ -913,6 +914,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");
@@ -954,7 +985,7 @@ ${reset}
       // Parse request body
       await req.parseBody();
 
-      const pathname = (req.url ?? "/").split("?")[0];
+      const pathname = req.path;
 
       // Track request start time for dev inspector
       const reqStartTime = DevAdmin.isEnabled() ? Date.now() : 0;
@@ -1001,9 +1032,10 @@ ${reset}
             };
             if (typeof chunk === "string") {
               chunk = injectDevToolbar(chunk, toolbarCtx);
+              chunk = injectFeedbackWidget(req, chunk as string);
             } else if (Buffer.isBuffer(chunk)) {
               const html = chunk.toString("utf-8");
-              chunk = injectDevToolbar(html, toolbarCtx);
+              chunk = injectFeedbackWidget(req, injectDevToolbar(html, toolbarCtx));
             }
             // Remove content-length since toolbar injection changes body size
             if (!res.raw.headersSent) {
@@ -1019,6 +1051,43 @@ ${reset}
           return originalEnd(chunk, cb);
         };
         res.raw.end = wrappedEnd;
+      } else if (
+        feedbackEnabled() &&
+        !pathname.startsWith("/__dev") &&
+        !pathname.startsWith("/__feedback")
+      ) {
+        // Production / non-dev path: still inject the feedback widget for
+        // whitelisted users. The injector itself re-checks the whitelist,
+        // path, and html marker so the wrapper is cheap when it no-ops.
+        const originalEnd = res.raw.end.bind(res.raw);
+        const wrappedEnd: typeof res.raw.end = function (
+          chunk?: unknown,
+          encodingOrCb?: BufferEncoding | (() => void),
+          cb?: () => void,
+        ) {
+          const contentType = res.raw.getHeader("content-type");
+          if (
+            typeof contentType === "string" &&
+            contentType.includes("text/html")
+          ) {
+            if (typeof chunk === "string") {
+              chunk = injectFeedbackWidget(req, chunk);
+            } else if (Buffer.isBuffer(chunk)) {
+              chunk = injectFeedbackWidget(req, chunk.toString("utf-8"));
+            }
+            if (!res.raw.headersSent) {
+              res.raw.removeHeader("content-length");
+            }
+          }
+          if (typeof encodingOrCb === "function") {
+            return originalEnd(chunk, encodingOrCb);
+          }
+          if (encodingOrCb !== undefined) {
+            return originalEnd(chunk, encodingOrCb, cb);
+          }
+          return originalEnd(chunk, cb);
+        };
+        res.raw.end = wrappedEnd;
       }
 
       // Try static files first (project public dir, src/public dir, then framework built-in)
@@ -1170,6 +1239,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) {
@@ -1192,7 +1291,7 @@ ${reset}
           const html500 = await renderErrorPage(500, {
             error_message: errorMessage,
             request_id: `${Date.now().toString(36)}`,
-            path: (req.url ?? "/").split("?")[0],
+            path: req.path,
           }, templatesDir);
           if (html500) {
             res.raw.writeHead(500, { "Content-Type": "text/html; charset=utf-8" });

package/packages/core/src/service.ts

@@ -161,6 +161,64 @@ function startDaemonService(svc: RegisteredService): void {
   executeHandler(svc);
 }
 
+// ─── Tina4Service base class (3.13.1) ───────────────────────────────────────
+//
+// Class-based background service pattern. Cross-framework parity with
+// Python tina4_python.service (when shipped), PHP Tina4\Service, and Ruby
+// Tina4::Service. The documentation has long taught:
+//
+//   class EmailQueueWorker extends Tina4Service {
+//     async run() {
+//       while (!this.shouldStop()) {
+//         // process work
+//       }
+//     }
+//   }
+//
+//   ServiceRunner.registerService("emails", new EmailQueueWorker());
+//   await ServiceRunner.start();
+//
+// Subclasses MUST override `run()`. Optionally override `stop()` for
+// custom shutdown; always call `super.stop()` so the internal flag
+// gets set — `shouldStop()` reads from it.
+
+export abstract class Tina4Service {
+  private _running = true;
+
+  /** Main work loop — subclasses MUST override. */
+  abstract run(): Promise<void> | void;
+
+  /**
+   * Signal this service to stop. The next `shouldStop()` check returns true.
+   * Override for custom shutdown behaviour but always call `super.stop()`.
+   */
+  stop(): void {
+    this._running = false;
+  }
+
+  /**
+   * Returns true once `stop()` has been called. Use inside `run()` loops
+   * as the exit condition:
+   *
+   *     async run() {
+   *       while (!this.shouldStop()) { ... }
+   *     }
+   */
+  shouldStop(): boolean {
+    return !this._running;
+  }
+
+  /**
+   * Return a callable that ServiceRunner can register. Used by
+   * ServiceRunner.registerService under the hood.
+   */
+  asHandler(): ServiceHandler {
+    return async () => {
+      await this.run();
+    };
+  }
+}
+
 // ─── ServiceRunner ───────────────────────────────────────────────────────────
 
 export class ServiceRunner {
@@ -187,6 +245,35 @@ export class ServiceRunner {
     });
   }
 
+  /**
+   * Register a class-based service (subclass of {@link Tina4Service}) by name.
+   *
+   * Wraps the service's `run()` method as the runner's handler. Defaults
+   * to `daemon: true` because Tina4Service subclasses manage their own
+   * loop inside `run()`. Override via `options`.
+   *
+   *     class EmailWorker extends Tina4Service { async run() { ... } }
+   *     ServiceRunner.registerService("emails", new EmailWorker());
+   *     await ServiceRunner.start();
+   *
+   * Cross-framework parity with PHP `ServiceRunner::registerService` and
+   * Ruby `Tina4::ServiceRunner.register_service`.
+   */
+  static registerService(
+    name: string,
+    service: Tina4Service,
+    options: ServiceOptions = {},
+  ): void {
+    const merged: ServiceOptions = { daemon: true, ...options };
+    this.register(name, service.asHandler(), merged);
+    // Stash the instance on the registry entry so future stop() calls
+    // can route to service.stop().
+    const entry = registry.get(name);
+    if (entry) {
+      (entry as unknown as Record<string, unknown>).instance = service;
+    }
+  }
+
   /**
    * Discover services from a directory. Each file should export
    * { name, handler, timing?, interval?, daemon?, maxRetries? }.

package/packages/core/src/static.ts

@@ -27,8 +27,15 @@ export function tryServeStatic(
   req: Tina4Request,
   res: Tina4Response
 ): boolean {
-  const url = req.url ?? "/";
-  const pathname = url.split("?")[0];
+  // Prefer req.path (always path-only, set by createRequest). Fall back to
+  // parsing req.url for hand-rolled request objects in unit tests.
+  let pathname = req.path;
+  if (!pathname) {
+    const raw = req.url ?? "/";
+    pathname = raw.startsWith("http")
+      ? new URL(raw).pathname
+      : raw.split("?")[0];
+  }
 
   // Try exact file match, then index.html for directory requests
   const candidates = [

package/packages/core/src/test.ts

@@ -0,0 +1,246 @@
+/**
+ * Tina4 — The Intelligent Native Application 4ramework
+ * Copyright 2007 - current Tina4
+ * License: MIT https://opensource.org/licenses/MIT
+ *
+ * Tina4 xUnit-style Test base class.
+ *
+ * Chapter 18 of the documentation has long shown:
+ *
+ *     class UserApiTest extends Tina4Test {
+ *       async testHealth() {
+ *         const resp = await this.get("/health");
+ *         this.assertEqual(resp.status, 200);
+ *       }
+ *     }
+ *
+ * Until 3.13.0 this class did not exist — examples crashed with
+ * "ReferenceError: Tina4Test is not defined". This is the Node.js
+ * parity of the Python `tina4_python.test.Test`, PHP `Tina4\Test`,
+ * and Ruby `Tina4::Test` classes shipped at the same time.
+ *
+ * The class has a built-in runner (`Tina4Test.runAll`) so the docs'
+ * `npx tina4nodejs test` flow can discover every subclass without
+ * an external test framework. HTTP helpers (get/post/put/patch/delete)
+ * delegate to a lazy TestClient. Positional assertions match the
+ * cross-framework (actual, expected, message) shape.
+ */
+
+import { TestClient, type TestResponse, type RequestOptions } from "./testClient.js";
+
+// Class-level registry so runAll() can discover every subclass.
+const _subclasses: Array<typeof Tina4Test> = [];
+
+/** Raised by Tina4Test assertion helpers when an assertion fails. */
+export class AssertionError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "AssertionError";
+  }
+}
+
+/** Result of running a Tina4Test subclass (or all subclasses). */
+export interface TestRunResults {
+  passed: number;
+  failed: number;
+  errors: number;
+  details: Array<{
+    suite: string;
+    test: string;
+    status: "passed" | "failed" | "error";
+    message?: string;
+  }>;
+}
+
+/**
+ * Tina4 xUnit-style test base class — class-based suites with HTTP
+ * helpers and positional assertions, zero external deps.
+ *
+ * Subclass and define `test*` methods:
+ *
+ *     class BasicTest extends Tina4Test {
+ *       async testAddition() {
+ *         this.assertEqual(2 + 2, 4, "addition works");
+ *       }
+ *       async testHttpHealth() {
+ *         const resp = await this.get("/health");
+ *         this.assertEqual(resp.status, 200);
+ *       }
+ *     }
+ *
+ *     const results = await Tina4Test.runAll();
+ *     // → { passed, failed, errors, details }
+ */
+export class Tina4Test {
+  private _client: TestClient | null = null;
+
+  // Auto-register every subclass for the runAll() discovery API.
+  // (The static block runs once when the class file loads.)
+  static {
+    // Skip the base class itself
+  }
+
+  /** snake_case lifecycle hook — runs before each test. Override in subclasses. */
+  async setUp(): Promise<void> {}
+
+  /** snake_case lifecycle hook — runs after each test. Override in subclasses. */
+  async tearDown(): Promise<void> {}
+
+  // ── HTTP test client (lazy) ─────────────────────────────────────────
+
+  /** The lazily-created TestClient instance shared by this suite's tests. */
+  protected get client(): TestClient {
+    if (this._client === null) this._client = new TestClient();
+    return this._client;
+  }
+
+  async get(path: string, options?: RequestOptions): Promise<TestResponse> {
+    return this.client.get(path, options);
+  }
+
+  async post(path: string, options?: RequestOptions): Promise<TestResponse> {
+    return this.client.post(path, options);
+  }
+
+  async put(path: string, options?: RequestOptions): Promise<TestResponse> {
+    return this.client.put(path, options);
+  }
+
+  async patch(path: string, options?: RequestOptions): Promise<TestResponse> {
+    return this.client.patch(path, options);
+  }
+
+  async delete(path: string, options?: RequestOptions): Promise<TestResponse> {
+    return this.client.delete(path, options);
+  }
+
+  // ── Positional assertions — (actual, expected, message) shape ────────
+
+  assertEqual(actual: unknown, expected: unknown, message?: string): void {
+    // Deep equality via JSON for objects, strict for primitives — matches
+    // how the Python/PHP/Ruby ports compare.
+    const eq =
+      actual === expected ||
+      (typeof actual === "object" && typeof expected === "object" &&
+        JSON.stringify(actual) === JSON.stringify(expected));
+    if (!eq) {
+      throw new AssertionError(
+        message || `Expected ${JSON.stringify(expected)}, got ${JSON.stringify(actual)}`
+      );
+    }
+  }
+
+  assertNotEqual(actual: unknown, expected: unknown, message?: string): void {
+    const eq =
+      actual === expected ||
+      (typeof actual === "object" && typeof expected === "object" &&
+        JSON.stringify(actual) === JSON.stringify(expected));
+    if (eq) {
+      throw new AssertionError(
+        message || `Expected ${JSON.stringify(actual)} != ${JSON.stringify(expected)}, but they are equal`
+      );
+    }
+  }
+
+  assertTrue(value: unknown, message?: string): void {
+    if (!value) throw new AssertionError(message || `Expected truthy, got ${JSON.stringify(value)}`);
+  }
+
+  assertFalse(value: unknown, message?: string): void {
+    if (value) throw new AssertionError(message || `Expected falsy, got ${JSON.stringify(value)}`);
+  }
+
+  assertNull(value: unknown, message?: string): void {
+    if (value !== null) throw new AssertionError(message || `Expected null, got ${JSON.stringify(value)}`);
+  }
+
+  assertNotNull(value: unknown, message?: string): void {
+    if (value === null) throw new AssertionError(message || "Expected non-null, got null");
+  }
+
+  async assertRaises(
+    expectedClass: new (...args: never[]) => Error,
+    fn: () => unknown | Promise<unknown>,
+    message?: string
+  ): Promise<void> {
+    try {
+      await fn();
+    } catch (err) {
+      if (err instanceof expectedClass) return;
+      throw new AssertionError(
+        message || `Expected ${expectedClass.name}, got ${(err as Error)?.constructor?.name}: ${String(err)}`
+      );
+    }
+    throw new AssertionError(message || `Expected ${expectedClass.name} to be raised, but nothing was`);
+  }
+
+  // ── Runner ───────────────────────────────────────────────────────────
+
+  /** Register a subclass for discovery. Called automatically via `extends Tina4Test`. */
+  static register(klass: typeof Tina4Test): void {
+    if (!_subclasses.includes(klass)) _subclasses.push(klass);
+  }
+
+  /** Run every `test*` method on this class. Returns counts and per-test details. */
+  static async run(this: typeof Tina4Test): Promise<TestRunResults> {
+    const results: TestRunResults = { passed: 0, failed: 0, errors: 0, details: [] };
+    const proto = this.prototype as unknown as Record<string, unknown>;
+    const methods = Object.getOwnPropertyNames(this.prototype)
+      .filter((m) => m.startsWith("test") && typeof proto[m] === "function")
+      .sort();
+
+    for (const method of methods) {
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      const suite = new (this as any)();
+      try {
+        await suite.setUp();
+        await suite[method]();
+        await suite.tearDown();
+        results.passed++;
+        results.details.push({ suite: this.name, test: method, status: "passed" });
+      } catch (err) {
+        if (err instanceof AssertionError) {
+          results.failed++;
+          results.details.push({ suite: this.name, test: method, status: "failed", message: err.message });
+        } else {
+          results.errors++;
+          results.details.push({
+            suite: this.name,
+            test: method,
+            status: "error",
+            message: `${(err as Error)?.constructor?.name || "Error"}: ${String(err)}`,
+          });
+        }
+      }
+    }
+    return results;
+  }
+
+  /** Run every Tina4Test subclass discovered via auto-registration. */
+  static async runAll(options: { quiet?: boolean } = {}): Promise<TestRunResults> {
+    const aggregate: TestRunResults = { passed: 0, failed: 0, errors: 0, details: [] };
+    for (const klass of _subclasses) {
+      const out = await klass.run();
+      aggregate.passed += out.passed;
+      aggregate.failed += out.failed;
+      aggregate.errors += out.errors;
+      aggregate.details.push(...out.details);
+    }
+    if (!options.quiet) {
+      // eslint-disable-next-line no-console
+      console.log(
+        `Tina4 Test results: ${aggregate.passed} passed, ${aggregate.failed} failed, ${aggregate.errors} errors`
+      );
+    }
+    return aggregate;
+  }
+
+  /** Subclasses array — read-only view used by tests. */
+  static get subclasses(): ReadonlyArray<typeof Tina4Test> {
+    return _subclasses;
+  }
+}
+
+// Auto-register subclasses by overriding the `extends` hook. Because JS
+// doesn't have a Ruby/Python-style `inherited` callback, expose `register`
+// as the explicit handshake and document it; tests can call directly.

package/packages/core/src/types.ts

@@ -20,6 +20,24 @@ export interface Tina4Session {
 export interface Tina4Request extends IncomingMessage {
   params: Record<string, string>;
   query: Record<string, string>;
+  /**
+   * Request path only — no query string. Matches `request.path` in
+   * Python/PHP/Ruby. Example: `/users/42`.
+   */
+  path: string;
+  /**
+   * Raw query string with no leading "?". Matches `request.query_string`
+   * (Python/Ruby) and `request.queryString` (PHP). Example: `"page=2"`.
+   */
+  queryString: string;
+  /**
+   * Full absolute URL — `scheme://host[:port]/path[?query]`.
+   * Honours X-Forwarded-Proto / X-Forwarded-Host. Matches PHP/Ruby/Python parity.
+   *
+   * Note: this overrides Node's native `IncomingMessage.url` (which contains
+   * only path+query). Inside Tina4 handlers, `req.url` is always the full URL.
+   */
+  url: string;
   body: unknown;
   ip: string;
   files: Record<string, UploadedFile | UploadedFile[]>;