Skip to content

Build your personal knowledge base with Trilium Notes

fix(healthcheck): end the probe at its deadline, and stop loading the server

Elian Doranbb9c5f637836
diff --git a/apps/server/scripts/build.ts b/apps/server/scripts/build.ts
index 2a636d7d57..bdf4b4124a 100644
--- a/apps/server/scripts/build.ts
+++ b/apps/server/scripts/build.ts
@@ -1,7 +1,13 @@
+import { statSync } from "fs";
+import { join } from "path";
+
import BuildHelper from "../../../scripts/build-utils";
const build = new BuildHelper("apps/server");
+/** Generous next to the few KB the probe needs, far below what a stray import costs. */
+const HEALTHCHECK_MAX_KB = 100;
+
async function main() {
await build.buildBackend([ "src/main.ts", "src/docker_healthcheck.ts" ])
// Its own call so it lands beside the bundle rather than under a `services/` path: the pool
@@ -28,6 +34,26 @@ async function main() {
build.copy("/node_modules/ckeditor5/dist/ckeditor5-content.css", "ckeditor5-content.css");
build.buildFrontend();
+
+ assertHealthcheckStaysSmall();
+}
+
+/**
+ * Docker runs the healthcheck every 30 seconds, and each run is a cold node process that parses
+ * the whole bundle. It resolves its target in healthcheck_target.ts rather than through config.ts
+ * so that it pulls in nothing else; importing a server service here costs megabytes and puts that
+ * cost on every probe. The limit is generous, so tripping it means a dependency crept back in.
+ */
+function assertHealthcheckStaysSmall() {
+ const bundle = join(build.outDir, "docker_healthcheck.cjs");
+ const sizeKb = statSync(bundle).size / 1024;
+
+ if (sizeKb > HEALTHCHECK_MAX_KB) {
+ throw new Error(
+ `${bundle} is ${sizeKb.toFixed(0)} KB, over the ${HEALTHCHECK_MAX_KB} KB limit. `
+ + "Something it imports now pulls in a server service; keep the probe standalone."
+ );
+ }
}
main();
diff --git a/apps/server/src/docker_healthcheck.ts b/apps/server/src/docker_healthcheck.ts
index 940b46c73f..3b450cac3c 100644
--- a/apps/server/src/docker_healthcheck.ts
+++ b/apps/server/src/docker_healthcheck.ts
@@ -1,6 +1,3 @@
-import config from "./services/config.js";
-import { probeHealth } from "./services/healthcheck.js";
-import host from "./services/host.js";
-import port from "./services/port.js";
+import { probeHealth, resolveHealthcheckTarget } from "./services/healthcheck.js";
-probeHealth({ https: config.Network.https, port, host }).then((code) => process.exit(code));
+probeHealth(resolveHealthcheckTarget()).then((code) => process.exit(code));
diff --git a/apps/server/src/services/healthcheck.spec.ts b/apps/server/src/services/healthcheck.spec.ts
index 2a0a94c78c..9cc1bcd186 100644
--- a/apps/server/src/services/healthcheck.spec.ts
+++ b/apps/server/src/services/healthcheck.spec.ts
@@ -5,9 +5,14 @@ import os from "os";
import path from "path";
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
-import { probeHealth } from "./healthcheck.js";
+import { probeHealth, resolveHealthcheckTarget } from "./healthcheck.js";
+
+//#region Probing the server
const LOCALHOST = "127.0.0.1";
+/** The probe asks for 2000 ms, so a wait past this is a wait without end. */
+const DEADLINE_ALLOWANCE_MS = 3000;
+const STILL_WAITING = "still waiting for the probe to give up";
/**
* Docker reads two things from the probe: the exit code it resolves, and whatever it prints
@@ -25,8 +30,9 @@ describe("the docker healthcheck probe", () => {
});
afterEach(async () => {
- vi.restoreAllMocks();
await stopEverything();
+ await new Promise((resolve) => setImmediate(resolve));
+ vi.restoreAllMocks();
});
it("reports healthy on 200, having asked for the health-check resource", async () => {
@@ -106,22 +112,24 @@ describe("the docker healthcheck probe", () => {
expect(await probeHealth({ https: false, port, host: LOCALHOST })).toBe(0);
});
- it("waits indefinitely on a server that accepts the connection and stays silent", async () => {
- // `timeout` only arms the socket's idle timer. Nothing listens for the event it emits,
- // so the request is never destroyed and the probe outlives its own deadline.
+ it("gives up and reports unhealthy when the server accepts but never answers", async () => {
+ // A wedged server still completes the handshake, which is the case the probe exists to
+ // catch. Its own 2000 ms deadline has to end the wait and report unhealthy.
const port = await startServer(() => { /* accepts the request, never answers */ });
- const settled = vi.fn();
- const probe = probeHealth({ https: false, port, host: LOCALHOST });
-
- void probe.then(settled);
- await new Promise((resolve) => setTimeout(resolve, 2500));
-
- expect(settled).not.toHaveBeenCalled();
-
- // Drop the connection so the probe settles here rather than during a later test.
- await stopEverything();
- expect(await probe).toBe(1);
- expect(logged).toEqual([ "ERROR" ]);
+ const started = Date.now();
+
+ let giveUp: ReturnType<typeof setTimeout> | undefined;
+ const outcome = await Promise.race([
+ probeHealth({ https: false, port, host: LOCALHOST }),
+ new Promise((resolve) => {
+ giveUp = setTimeout(() => resolve(STILL_WAITING), DEADLINE_ALLOWANCE_MS);
+ })
+ ]);
+ clearTimeout(giveUp);
+
+ expect(outcome).toBe(1);
+ expect(Date.now() - started).toBeGreaterThanOrEqual(2000);
+ expect(logged).toEqual([ "TIMEOUT after 2000 ms" ]);
});
});
@@ -197,3 +205,217 @@ async function stopEverything() {
fs.rmSync(dir, { recursive: true, force: true });
}
}
+
+//#endregion
+
+//#region Resolving where to probe
+
+/**
+ * The probe resolves its target without importing config.ts, port.ts or host.ts, so nothing but
+ * these tests keeps the two readings of the same environment and config.ini in step. The last
+ * block runs the real config modules over the same inputs and compares.
+ */
+describe("resolving the healthcheck target", () => {
+ let tempDir: string;
+ let iniPath: string;
+
+ beforeEach(() => {
+ tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "trilium-target-"));
+ iniPath = path.join(tempDir, "config.ini");
+ });
+
+ afterEach(() => {
+ fs.rmSync(tempDir, { recursive: true, force: true });
+ vi.restoreAllMocks();
+ });
+
+ it("falls back to localhost:8080 over http when nothing is configured", () => {
+ expect(resolveHealthcheckTarget(baseEnv()))
+ .toEqual({ https: false, port: 8080, host: "0.0.0.0" });
+ });
+
+ it("reads the [Network] section of config.ini", () => {
+ writeIni("[Network]\nhost=192.168.1.5\nport=9001\nhttps=true\n");
+
+ expect(resolveHealthcheckTarget(baseEnv())).toEqual({
+ https: true, port: 9001, host: "192.168.1.5"
+ });
+ });
+
+ it("lets the environment override config.ini", () => {
+ writeIni("[Network]\nhost=192.168.1.5\nport=9001\n");
+ const target = resolveHealthcheckTarget(baseEnv({
+ TRILIUM_NETWORK_HOST: "10.0.0.1",
+ TRILIUM_NETWORK_PORT: "7777"
+ }));
+
+ expect(target).toEqual({ https: false, port: 7777, host: "10.0.0.1" });
+ });
+
+ it("prefers the short TRILIUM_PORT and TRILIUM_HOST aliases over everything else", () => {
+ writeIni("[Network]\nhost=192.168.1.5\nport=9001\n");
+ const target = resolveHealthcheckTarget(baseEnv({
+ TRILIUM_NETWORK_HOST: "10.0.0.1", TRILIUM_NETWORK_PORT: "7777",
+ TRILIUM_HOST: "127.0.0.1", TRILIUM_PORT: "8082"
+ }));
+
+ expect(target).toEqual({ https: false, port: 8082, host: "127.0.0.1" });
+ });
+
+ it("takes config.ini from TRILIUM_CONFIG_INI_PATH when it is set", () => {
+ const elsewhere = path.join(tempDir, "elsewhere.ini");
+ fs.writeFileSync(elsewhere, "[Network]\nport=9100\n");
+
+ expect(resolveHealthcheckTarget({
+ TRILIUM_DATA_DIR: tempDir, TRILIUM_CONFIG_INI_PATH: elsewhere
+ }).port).toBe(9100);
+ });
+
+ it("reads https as true only for true and 1, in any case", () => {
+ for (const [ value, expected ] of [
+ [ "true", true ], [ "TRUE", true ], [ " true ", true ], [ "1", true ],
+ [ "false", false ], [ "0", false ], [ "yes", false ], [ "", false ]
+ ] as const) {
+ const target = resolveHealthcheckTarget(baseEnv({ TRILIUM_NETWORK_HTTPS: value }));
+
+ expect(target.https).toBe(expected);
+ }
+ });
+
+ it("falls back to the default port when the configured one could never be listened on", () => {
+ // port.ts exits rather than start, so the server is not listening on anything.
+ for (const port of [ "not-a-port", "70000", "-1" ]) {
+ expect(resolveHealthcheckTarget(baseEnv({ TRILIUM_PORT: port })).port).toBe(8080);
+ }
+ });
+
+ it("survives a config.ini that is missing, empty or malformed", () => {
+ expect(resolveHealthcheckTarget(baseEnv()).port).toBe(8080);
+
+ for (const contents of [ "", "not an ini file at all", "[Network]\n" ]) {
+ writeIni(contents);
+ expect(resolveHealthcheckTarget(baseEnv())).toEqual({
+ https: false, port: 8080, host: "0.0.0.0"
+ });
+ }
+ });
+
+ it("creates nothing on disk, unlike the config modules it stands in for", () => {
+ const untouched = path.join(tempDir, "absent");
+
+ resolveHealthcheckTarget({ TRILIUM_DATA_DIR: untouched });
+
+ expect(fs.existsSync(untouched)).toBe(false);
+ });
+
+ it("finds the data directory the server would use when none is configured", () => {
+ const home = path.join(tempDir, "home");
+ const dataDir = path.join(home, "trilium-data");
+ fs.mkdirSync(dataDir, { recursive: true });
+ fs.writeFileSync(path.join(dataDir, "config.ini"), "[Network]\nport=9200\n");
+ vi.spyOn(os, "homedir").mockReturnValue(home);
+
+ expect(resolveHealthcheckTarget({}).port).toBe(9200);
+ });
+
+ it("falls back to the platform's app-data directory, and to defaults without one", () => {
+ const home = path.join(tempDir, "home");
+ const appData = path.join(tempDir, "appdata");
+ fs.mkdirSync(home, { recursive: true });
+ vi.spyOn(os, "homedir").mockReturnValue(home);
+
+ const cases = [
+ { platform: "linux" as const, dir: path.join(home, ".local", "share"), env: {} },
+ { platform: "darwin" as const, env: {},
+ dir: path.join(home, "Library", "Application Support") },
+ { platform: "win32" as const, dir: appData, env: { APPDATA: appData } }
+ ];
+
+ for (const [ index, { platform, dir, env } ] of cases.entries()) {
+ const dataDir = path.join(dir, "trilium-data");
+ fs.mkdirSync(dataDir, { recursive: true });
+ fs.writeFileSync(path.join(dataDir, "config.ini"), `[Network]\nport=93${index}0\n`);
+ vi.spyOn(os, "platform").mockReturnValue(platform);
+
+ expect(resolveHealthcheckTarget(env).port).toBe(9300 + index * 10);
+ fs.rmSync(dir, { recursive: true, force: true });
+ }
+
+ // An unrecognised platform, and Windows without APPDATA, have nowhere else to look.
+ vi.spyOn(os, "platform").mockReturnValue("freebsd");
+ expect(resolveHealthcheckTarget({}).port).toBe(8080);
+
+ vi.spyOn(os, "platform").mockReturnValue("win32");
+ expect(resolveHealthcheckTarget({}).port).toBe(8080);
+ });
+
+ it("treats an unreadable config.ini as absent", () => {
+ // A directory where the file should be: it exists, and reading it throws.
+ fs.mkdirSync(iniPath);
+
+ expect(resolveHealthcheckTarget(baseEnv())).toEqual({
+ https: false, port: 8080, host: "0.0.0.0"
+ });
+ });
+
+ describe("agrees with the server's own config modules", () => {
+ const CASES = [
+ { label: "nothing configured", env: {}, ini: "" },
+ { label: "ini only", env: {},
+ ini: "[Network]\nhost=192.168.1.5\nport=9001\nhttps=true\n" },
+ { label: "standard env vars", ini: "[Network]\nport=9001\n",
+ env: { TRILIUM_NETWORK_HOST: "10.0.0.1", TRILIUM_NETWORK_PORT: "7777" } },
+ { label: "short aliases", ini: "[Network]\nport=9001\n",
+ env: { TRILIUM_HOST: "127.0.0.1", TRILIUM_PORT: "8082" } },
+ { label: "https via env", env: { TRILIUM_NETWORK_HTTPS: "true" }, ini: "" },
+ { label: "https via ini", env: {}, ini: "[Network]\nhttps=1\n" }
+ ];
+
+ for (const { label, env, ini: iniText } of CASES) {
+ it(label, async () => {
+ writeIni(iniText);
+ // config.ts and its imports need the ambient test environment to load at all, so
+ // both readings are given the same merged environment rather than a bare one.
+ const scenario = { ...process.env, ...baseEnv(env) };
+
+ const viaConfig = await resolveViaConfigModules(scenario);
+
+ expect(resolveHealthcheckTarget(scenario)).toEqual(viaConfig);
+ });
+ }
+ });
+
+ /** The env a container hands the probe, with the data dir pointed at this test's temp copy. */
+ function baseEnv(extra: NodeJS.ProcessEnv = {}): NodeJS.ProcessEnv {
+ return { TRILIUM_DATA_DIR: tempDir, ...extra };
+ }
+
+ function writeIni(contents: string) {
+ fs.writeFileSync(iniPath, contents);
+ }
+});
+
+/**
+ * Loads config.ts, port.ts and host.ts against the given environment and reports the target they
+ * describe, so the resolver can be compared against the modules it replaces rather than against
+ * hand-written expectations.
+ */
+async function resolveViaConfigModules(env: NodeJS.ProcessEnv) {
+ const original = process.env;
+
+ try {
+ process.env = { ...env };
+ vi.resetModules();
+
+ const { default: config } = await import("./config.js");
+ const { default: port } = await import("./port.js");
+ const { default: host } = await import("./host.js");
+
+ return { https: config.Network.https, port, host };
+ } finally {
+ process.env = original;
+ vi.resetModules();
+ }
+}
+
+//#endregion
diff --git a/apps/server/src/services/healthcheck.ts b/apps/server/src/services/healthcheck.ts
index c9b334906b..3738e71ad4 100644
--- a/apps/server/src/services/healthcheck.ts
+++ b/apps/server/src/services/healthcheck.ts
@@ -1,4 +1,8 @@
+import fs from "fs";
import http from "http";
+import ini from "ini";
+import os from "os";
+import path from "path";
/** Where the probe looks for the server, as the running instance resolved it. */
export interface HealthcheckTarget {
@@ -10,6 +14,8 @@ export interface HealthcheckTarget {
host: string;
}
+//#region Probing the server
+
const PROBE_PATH = "/api/health-check";
const TIMEOUT_MS = 2000;
@@ -35,6 +41,14 @@ export function probeHealth({ https, port, host }: HealthcheckTarget): Promise<n
? http.request(`http://${host}:${port}${PROBE_PATH}`, options, onResponse)
: http.request({ ...options, socketPath: host, path: PROBE_PATH }, onResponse);
+ // `timeout` only arms the socket's idle timer, so the request has to be torn down here.
+ // Without this a wedged server that still completes the handshake is waited on forever.
+ request.on("timeout", () => {
+ console.log(`TIMEOUT after ${TIMEOUT_MS} ms`);
+ request.destroy();
+ resolve(1);
+ });
+
request.on("error", () => {
console.log("ERROR");
resolve(1);
@@ -42,3 +56,133 @@ export function probeHealth({ https, port, host }: HealthcheckTarget): Promise<n
request.end();
});
}
+
+//#endregion
+
+//#region Resolving where to probe
+
+const DEFAULT_HOST = "0.0.0.0";
+const DEFAULT_PORT = 8080;
+const MAX_PORT = 65536;
+
+/**
+ * Resolves where to probe, mirroring what config.ts, port.ts and host.ts resolve for the running
+ * server. It reads the same environment variables and the same `[Network]` section of config.ini,
+ * but imports none of those modules: loading them creates the data directory, writes a config
+ * sample and can call process.exit(), none of which a healthcheck should do. The two readings are
+ * held in agreement by the tests in healthcheck.spec.ts.
+ */
+export function resolveHealthcheckTarget(env: NodeJS.ProcessEnv = process.env): HealthcheckTarget {
+ const network = readNetworkSection(env);
+
+ return {
+ https: resolveHttps(env.TRILIUM_NETWORK_HTTPS, network.https),
+ port: resolvePort(env, network.port),
+ host: env.TRILIUM_HOST || fromConfig(env.TRILIUM_NETWORK_HOST, network.host, DEFAULT_HOST)
+ };
+}
+
+/** TRILIUM_PORT wins when set, as it does in port.ts, then whatever config.ts would report. */
+function resolvePort(env: NodeJS.ProcessEnv, iniValue: unknown) {
+ const resolved = env.TRILIUM_PORT || fromConfig(env.TRILIUM_NETWORK_PORT, iniValue, "");
+ const port = parseInt(resolved, 10);
+
+ // port.ts exits on a port outside this range, so the server is not listening either way.
+ return Number.isInteger(port) && port >= 0 && port < MAX_PORT ? port : DEFAULT_PORT;
+}
+
+function resolveHttps(envValue: string | undefined, iniValue: unknown) {
+ if (envValue !== undefined) {
+ return toBoolean(envValue);
+ }
+
+ return hasIniValue(iniValue) ? toBoolean(iniValue) : false;
+}
+
+/** Mirrors getConfigValue in config.ts: the environment variable wins even when it is empty. */
+function fromConfig(envValue: string | undefined, iniValue: unknown, fallback: string) {
+ if (envValue !== undefined) {
+ return envValue;
+ }
+
+ return hasIniValue(iniValue) ? String(iniValue) : fallback;
+}
+
+function hasIniValue(value: unknown) {
+ return value !== undefined && value !== null && value !== "";
+}
+
+/** Mirrors transformBoolean in config.ts: "true"/"false" in any case, plus 1 and 0. */
+function toBoolean(value: unknown) {
+ const text = String(value).toLowerCase().trim();
+
+ if (text === "true") {
+ return true;
+ }
+ if (text === "false") {
+ return false;
+ }
+
+ return value === "1" || value === 1;
+}
+
+//#endregion
+
+//#region Reading config.ini
+
+const DATA_DIR_NAME = "trilium-data";
+
+function readNetworkSection(env: NodeJS.ProcessEnv): Record<string, unknown> {
+ const iniPath = env.TRILIUM_CONFIG_INI_PATH || path.join(resolveDataDir(env), "config.ini");
+
+ try {
+ if (!fs.existsSync(iniPath)) {
+ return {};
+ }
+
+ const section = ini.parse(fs.readFileSync(iniPath, "utf8")).Network;
+
+ return section && typeof section === "object" ? section : {};
+ } catch {
+ // An unreadable config.ini leaves the defaults in place, which still probe localhost.
+ return {};
+ }
+}
+
+/** The read-only half of getTriliumDataDir in data_dir.ts, which creates directories as it goes. */
+function resolveDataDir(env: NodeJS.ProcessEnv) {
+ if (env.TRILIUM_DATA_DIR) {
+ return env.TRILIUM_DATA_DIR;
+ }
+
+ const homePath = path.join(os.homedir(), DATA_DIR_NAME);
+ if (fs.existsSync(homePath)) {
+ return homePath;
+ }
+
+ const appDataDir = platformAppDataDir(env);
+
+ if (appDataDir && fs.existsSync(appDataDir)) {
+ return path.join(appDataDir, DATA_DIR_NAME);
+ }
+
+ return homePath;
+}
+
+function platformAppDataDir(env: NodeJS.ProcessEnv) {
+ const platform = os.platform();
+
+ if (platform === "win32") {
+ return env.APPDATA || null;
+ }
+ if (platform === "linux") {
+ return path.join(os.homedir(), ".local", "share");
+ }
+ if (platform === "darwin") {
+ return path.join(os.homedir(), "Library", "Application Support");
+ }
+
+ return null;
+}
+
+//#endregion