@ti-engine/web-framework 1.27.0 → 1.28.0

package/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 This document will contain the list of changes made to the framework. The format is based on the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) specification.
 
+## Version 1.28.0
+
+* feat(deploy): add `bin/healthcheck.js`, the container liveness probe for any `TiWebServer` application. Point a
+  Dockerfile `HEALTHCHECK` at `node /app/node_modules/@ti-engine/web-framework/bin/healthcheck.js`. It belongs here
+  rather than in each application because every input it reads is the framework's: `TI_WEB_USE_TLS`, `TI_WEB_PORT`
+  and `TI_WEB_TLS_CERT_PATH` are the framework's environment overrides, and `/health` is the framework's own route,
+  served by `webHandlers.healthHandler`. The framework has always provided the endpoint and never anything to call
+  it, which left every consumer writing an inline `node -e` — and the obvious inline version hardcodes `http://`,
+  so it reports a TLS-enabled container unhealthy forever and Docker restarts a server that is answering correctly.
+  The transport comes from the same `tools.toBool` the server uses, so the two cannot drift. With TLS on the
+  certificate is verified rather than skipped: trust is anchored to the server's own certificate and the name to
+  check is read out of it, so one issued for a public hostname passes while the probe connects to `127.0.0.1`.
+  Without a configured certificate the probe falls back to establishing that the port accepts connections — weaker,
+  but it neither disables verification nor restarts a healthy container. Arrived in competence 3.34.0 and moved
+  here unchanged in behaviour.
+
 ## Version 1.27.0
 
 Session lifetime. Two defects that together threw a signed-in user out roughly ten minutes after sign-in, however

package/README.md

@@ -17,6 +17,7 @@ The web server configuration (host, port, TLS, cookies, etc.) is normally provid
 * `TI_WEB_USE_TLS` (`true`/`false`) toggles in-app TLS. Set `false` when a reverse proxy / ingress terminates TLS.
 * `TI_WEB_TLS_CERT_PATH` / `TI_WEB_TLS_KEY_PATH` override the TLS certificate/key paths (only used when TLS is enabled).
 * `TI_WEB_COOKIE_SECRET` sets the session cookie signing secret. Set a stable, private value for durable sessions and multi-replica deployments (otherwise a random per-process value is used).
+* `TI_WEB_TLS_CERT_PATH` is also read by the container liveness probe (below), which verifies against that certificate.
 * `TI_WEB_SESSION_IDLE_TIMEOUT` (whole minutes) sets how long a signed-in session survives **without activity**, overriding `cookies.maxAge`. The window is rolling: every response re-stamps the cookie, so a session ends only after that long with no request at all. Note that a user typing into a form makes no requests, so set this comfortably longer than the longest form a user fills in one sitting. Defaults to 480 (eight hours).
 * `TI_WEB_AUTH_METHODS` (comma-separated) **replaces** the enabled authentication methods (`auth.enabledMethods`), e.g. `openid-google` or `local,openid-google`.
 * `TI_WEB_AUTH_LOCAL_USERS_PATH` overrides the local user directory's file path (`auth.local.usersPath`), which backs `local` sign-in. An explicitly empty value means *no directory*, so every local sign-in is refused. See [Local (username/password) authentication](#local-usernamepassword-authentication).
@@ -129,3 +130,24 @@ mkcert localhost 127.0.0.1 ::1
 ## License
 
 Apache-2.0 © Boris Kostadinov. See [LICENSE](LICENSE).
+
+## Container liveness probe
+
+`bin/healthcheck.js` asks a running server whether it is still serving and exits 0 only if it says yes. Point a
+Dockerfile `HEALTHCHECK` at it:
+
+```dockerfile
+HEALTHCHECK --interval=30s --timeout=5s --start-period=40s --retries=3 \
+  CMD ["node", "/app/node_modules/@ti-engine/web-framework/bin/healthcheck.js"]
+```
+
+It reads `TI_WEB_USE_TLS` through the same `tools.toBool` the server uses, so the probe's transport cannot drift
+from the server's, and calls `/health` — the unprotected route `webHandlers.healthHandler` serves. Writing this
+inline in a Dockerfile is the mistake it exists to prevent: an `http://` URL hardcoded there reports a TLS-enabled
+container unhealthy forever, and Docker restarts a server that is answering correctly.
+
+With TLS on it verifies the certificate rather than skipping verification, anchoring trust to the server's own
+certificate at `TI_WEB_TLS_CERT_PATH` and taking the name to check from that certificate — so a certificate issued
+for a public hostname still passes while the probe connects to `127.0.0.1`. Set that variable when you terminate
+TLS inside the container. Without it there is nothing to anchor to and the probe falls back to establishing that
+the port accepts connections, which is weaker but neither disables verification nor restarts a healthy container.

package/bin/healthcheck.js

@@ -0,0 +1,136 @@
+/*
+ * The ti-engine is an open source, free to use—both for personal and commercial projects—framework for the creation of microservice-based solutions using node.js.
+ * Copyright © 2021-2026 Boris Kostadinov <kostadinov.boris@gmail.com>
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+*/
+
+/**
+ * Container liveness probe for any application built on {@link TiWebServer}: ask the server whether it is still
+ * serving, and exit 0 only if it says yes. Invoke it from a Dockerfile `HEALTHCHECK`, the way the competence image
+ * does:
+ * <br/>
+ * `HEALTHCHECK CMD ["node", "/app/node_modules/@ti-engine/web-framework/bin/healthcheck.js"]`
+ * <br/>
+ * It lives here rather than in an application because every input it reads is the framework's: `TI_WEB_USE_TLS`,
+ * `TI_WEB_PORT` and `TI_WEB_TLS_CERT_PATH` are the framework's environment overrides, `/health` is the framework's
+ * route, and the endpoint it calls is `webHandlers.healthHandler`. An application copying this file would be
+ * copying framework behaviour, and would silently keep the old behaviour when the framework's changed.
+ * <br/>
+ * The obvious implementation is an inline `node -e` in the Dockerfile, and the obvious mistake is what that
+ * encourages: hardcoding `require('http')` and an `http://` URL. That works for as long as TLS is off, and the
+ * moment an image is run with TLS on — supported, via a mounted certificate rather than terminating at a proxy —
+ * the probe speaks plain HTTP to a TLS listener, fails every time, and Docker reports a healthy container
+ * unhealthy, restarting it on a loop.
+ * <br/>
+ * The transport comes from the same variable and the same parser the server uses, so the two cannot drift:
+ * `tools.toBool` treats an unset value and `false`/`0`/`no`/`N` as false, and anything else as true.
+ * <br/>
+ * <b>On certificates.</b> The obvious way to make a loopback TLS probe work is `rejectUnauthorized: false`, and
+ * the obvious defence is that nothing can sit between a process and itself. Both are true and it is still the wrong
+ * line to write: it is the snippet that gets copied out of a health probe and into a client that does cross a
+ * network. So verification stays on and the trust anchor is narrowed instead — the server's own certificate, named
+ * by `TI_WEB_TLS_CERT_PATH`, is passed as the sole CA, and the name to verify is read out of that certificate
+ * rather than assumed to be `127.0.0.1` (a certificate issued for a public hostname is the normal case, and a probe
+ * that reported "dead" because of the name on it would be repeating the bug this file exists to fix).
+ * <br/>
+ * When no certificate path is configured there is nothing to anchor to, and the probe degrades to establishing that
+ * the port is accepting connections. That is weaker — it shows the listener is up, not that the application is
+ * answering — but it is honest, and it is the only remaining option that neither disables verification nor kills a
+ * container that is running perfectly well.
+ */
+
+const fs = require( "node:fs" );
+const net = require( "node:net" );
+const tools = require( "@ti-engine/core/tools" );
+
+const HOST = "127.0.0.1";
+const TIMEOUT_MS = 4000;   // below Docker's own --timeout, so a hung socket fails as unhealthy rather than being killed mid-probe
+const port = process.env.TI_WEB_PORT || 3000;
+const useTLS = tools.toBool( process.env.TI_WEB_USE_TLS );
+
+const alive = () => process.exit( 0 );
+const dead = () => process.exit( 1 );
+
+/**
+ * Reads the server's own certificate and works out what to trust and what name to verify against.
+ *
+ * @returns {{ca: Buffer, servername: (string|undefined)}|null} null when no certificate is configured or readable.
+ */
+function ownCertificate() {
+    const certPath = process.env.TI_WEB_TLS_CERT_PATH;
+    if ( !certPath ) {
+        return null;
+    }
+    try {
+        const pem = fs.readFileSync( certPath );
+        const certificate = new ( require( "node:crypto" ).X509Certificate )( pem );
+        // Connecting by IP verifies against an `IP Address:` entry, so a certificate that covers the loopback
+        // address needs no SNI at all. Otherwise the first DNS name it carries is the name it can satisfy; failing
+        // that, its common name.
+        const names = String( certificate.subjectAltName || "" ).split( "," ).map( ( entry ) => entry.trim() );
+        if ( names.includes( `IP Address:${ HOST }` ) ) {
+            return { ca: pem, servername: undefined };
+        }
+        const dnsName = names.find( ( entry ) => entry.startsWith( "DNS:" ) );
+        if ( dnsName ) {
+            return { ca: pem, servername: dnsName.slice( "DNS:".length ) };
+        }
+        const commonName = /CN=([^\n,]+)/.exec( String( certificate.subject || "" ) );
+        return { ca: pem, servername: commonName ? commonName[ 1 ].trim() : undefined };
+    } catch {
+        // Unreadable, or not a certificate. Nothing to anchor to.
+        return null;
+    }
+}
+
+/**
+ * Last resort when TLS is on and no certificate is available to verify against: prove the port accepts connections.
+ *
+ * @returns {void}
+ */
+function probeSocket() {
+    const socket = net.connect( { host: HOST, port: port } );
+    socket.setTimeout( TIMEOUT_MS );
+    socket.on( "connect", () => { socket.destroy(); alive(); } );
+    socket.on( "timeout", () => { socket.destroy(); dead(); } );
+    socket.on( "error", dead );
+}
+
+/**
+ * @param {Object} extraOptions Merged into the request options — the CA and server name for the TLS case.
+ * @returns {void}
+ */
+function probeHealthEndpoint( extraOptions ) {
+    const transport = useTLS ? require( "node:https" ) : require( "node:http" );
+    const request = transport.get( { host: HOST, port: port, path: "/health", ...extraOptions }, ( response ) => {
+        response.resume();
+        process.exit( response.statusCode === 200 ? 0 : 1 );
+    } );
+    request.setTimeout( TIMEOUT_MS, () => {
+        request.destroy();
+        dead();
+    } );
+    request.on( "error", dead );
+}
+
+if ( !useTLS ) {
+    probeHealthEndpoint( {} );
+} else {
+    const trust = ownCertificate();
+    if ( trust ) {
+        probeHealthEndpoint( { ca: trust.ca, servername: trust.servername } );
+    } else {
+        probeSocket();
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ti-engine/web-framework",
-  "version": "1.27.0",
+  "version": "1.28.0",
   "description": "A web-framework based on the ti-engine. It provides a customizable ready-to-use web-server microservice and a set of tools for creating web applications. NOTICE: This is still a work in progress and the full architecture, design, and functionality are not available!",
   "keywords": [
     "ti-engine",

package/types/bin/healthcheck.d.ts

@@ -0,0 +1 @@
+export {};