From 6052595deadb861a6e0705a26335c7b03aa74766 Mon Sep 17 00:00:00 2001 From: Bobban Rydh Date: Tue, 17 Nov 2026 19:39:43 +0100 Subject: [PATCH] Immich: inspector shows why a request was refused; server.versionCheck documented Inspect on a real Immich got data only from /server/about and /server/storage; the other four answered with a bare message, most likely a key without the permissions. The inspector now keeps the short message of any answer with HTTP 400 and up (never for a good answer) and shows it on the page and in the copied report. The permission list now includes server.versionCheck, and the docs say which endpoints have been seen live. Tests added. Co-Authored-By: Claude Sonnet 5.5 --- INTEGRATIONS.md | 4 ++-- server/src/integrations/httpJson.ts | 4 ++-- server/src/integrations/immich/adapter.ts | 4 ++-- server/src/integrations/inspector.ts | 16 ++++++++++++++++ server/test/inspector.test.ts | 16 ++++++++++++++++ web/src/api/client.ts | 2 +- web/src/components/IntegrationInspector.tsx | 2 ++ 7 files changed, 41 insertions(+), 7 deletions(-) diff --git a/INTEGRATIONS.md b/INTEGRATIONS.md index 3c7d71e..1f4691b 100644 --- a/INTEGRATIONS.md +++ b/INTEGRATIONS.md @@ -408,7 +408,7 @@ osTicket's API cannot close a ticket, so this is the one place in the app that * ### Immich - **Config fields:** the **address** of Immich (`http://host:2283`), an **API key** (Immich → Account Settings → API Keys; stored encrypted) and, for an https address with a certificate you made yourself, *insecure*. -- **Required access:** read only. Give the key just these permissions: `server.about`, `server.storage`, `server.statistics` and `job.read` (`queue.read` on newer versions) — statistics and jobs need an administrator's key. This app only ever sends GET requests; **nothing is changed, and no job is started, paused or cleared**. +- **Required access:** read only. Give the key just these permissions: `server.about`, `server.storage`, `server.versionCheck`, `server.statistics` and `job.read` (`queue.read` on newer versions) — statistics and jobs need an administrator's key. Without one of them that part is left out (and **Inspect** shows the reason Immich gave, such as *Missing required permission: server.versionCheck*). This app only ever sends GET requests; **nothing is changed, and no job is started, paused or cleared**. If one of those is refused, that part is left out and the rest still works. - **What it does:** every **five minutes** Immich is read and stored — its version (and whether a newer one is out), how full the **disk under the library** is, how many **photos and videos** there are and what they take, and the **background job queues** with how many jobs **failed** in each. **Apps → Immich** shows it. @@ -416,7 +416,7 @@ osTicket's API cannot close a ticket, so this is the one place in the app that * Failed jobs stay counted until you run them again or clear them in Immich, so the alert stays until you do). - If Immich cannot be read for 20 minutes its alerts are neither raised nor cleared, the Alerts page says it could not check, and the integration is raised as failing like any other. A part that could not be asked is *unknown*, never *none*. - `/metrics` has `homelab_immich_photos`, `homelab_immich_videos`, `homelab_immich_library_bytes`, `homelab_immich_disk_used_percent` and `homelab_immich_failed_jobs` for each Immich that was read lately. -- **Not verified against a live Immich** — the endpoints (`/api/server/about`, `/server/storage`, `/server/statistics`, `/server/version-check`, `/api/jobs`, and `/api/queues` on newer versions) and their fields are as Immich publishes them, and the reader is tried against a pretend server that answers both ways. Immich renames +- **Partly checked against a live Immich** (Inspect): `/api/server/about` and `/api/server/storage` answered as the reader expects (version, disk size, used and percent). On the first check the other four (`/server/statistics`, `/server/version-check`, `/jobs`, `/queues`) were refused with a short message instead of data — most likely a key without those permissions or not an administrator's — so photos, videos, usage, the latest version and the job queues are **not yet seen with data**. The endpoints (`/api/server/about`, `/server/storage`, `/server/statistics`, `/server/version-check`, `/api/jobs`, and `/api/queues` on newer versions) and their fields are as Immich publishes them, and the reader is tried against a pretend server that answers both ways. Immich renames these now and then; the **Diagnostic Log** has what was asked and answered if something comes back empty. Whether a *waiting* backlog is a problem is not judged: a big import has one for days. ### Nextcloud diff --git a/server/src/integrations/httpJson.ts b/server/src/integrations/httpJson.ts index 11dae6a..5d9ad5c 100644 --- a/server/src/integrations/httpJson.ts +++ b/server/src/integrations/httpJson.ts @@ -4,7 +4,7 @@ */ import * as http from "node:http"; import * as https from "node:https"; -import { isInspecting, looksLike, pathForReport, recordCall, shapeOf } from "./inspector.js"; +import { isInspecting, looksLike, pathForReport, recordCall, replyOf, shapeOf } from "./inspector.js"; export interface JsonResponse { status: number; @@ -69,7 +69,7 @@ export function requestJson( // While the inspector runs a read, what was asked and the shape of the answer (never its values) are written down. if (isInspecting()) { const contentType = String(res.headers["content-type"] ?? "").split(";")[0].trim().toLowerCase() || undefined; - recordCall({ method, path: pathForReport(parsed), status: res.statusCode ?? 0, ms: Date.now() - started, bytes: Buffer.byteLength(text), shape: json === null ? null : shapeOf(json), ...(contentType ? { contentType } : {}), ...(json === null ? { looks: looksLike(text) } : {}) }); + recordCall({ method, path: pathForReport(parsed), status: res.statusCode ?? 0, ms: Date.now() - started, bytes: Buffer.byteLength(text), shape: json === null ? null : shapeOf(json), ...(contentType ? { contentType } : {}), ...(json === null ? { looks: looksLike(text) } : {}), ...((res.statusCode ?? 0) >= 400 && replyOf(json) ? { reply: replyOf(json) } : {}) }); } resolve({ status: res.statusCode ?? 0, json, text, headers: res.headers }); }); diff --git a/server/src/integrations/immich/adapter.ts b/server/src/integrations/immich/adapter.ts index ea352e9..6b0a563 100644 --- a/server/src/integrations/immich/adapter.ts +++ b/server/src/integrations/immich/adapter.ts @@ -1,12 +1,12 @@ /** - * Immich adapter. Config: url, apiKey (made in Immich under Account Settings → API Keys; read permissions are enough: server.about, server.storage, server.statistics and + * Immich adapter. Config: url, apiKey (made in Immich under Account Settings → API Keys; read permissions are enough: server.about, server.storage, server.versionCheck, server.statistics and * job.read — or queue.read on newer versions); optional: insecure. * * Reading only: the version (and whether a newer one is out), how full the disk under the library is, how many photos and videos there are and how much space they take, and the * background job queues — above all how many jobs have **failed** (thumbnails or metadata that were never made). Nothing is sent to Immich but GET requests for these. * * Endpoints and field names are from Immich's published API (`/api/server/about`, `/server/storage`, `/server/statistics`, `/server/version-check`, `/jobs` — `/queues` on newer - * versions) and have not been checked against a live server here; every field is read defensively, and a part that cannot be read (statistics need an administrator's key) is left out. + * versions) and were checked against a live server only for `/server/about` and `/server/storage` (the others were refused for lack of permission); every field is read defensively, and a part that cannot be read (statistics need an administrator's key) is left out. */ import { requestJson } from "../httpJson.js"; import { withDiagLogging } from "../../services/diagLog.js"; diff --git a/server/src/integrations/inspector.ts b/server/src/integrations/inspector.ts index 59c432e..50cc960 100644 --- a/server/src/integrations/inspector.ts +++ b/server/src/integrations/inspector.ts @@ -19,6 +19,8 @@ export interface InspectedCall { contentType?: string; /** For an answer that was not JSON: what kind of text it is (never its words). */ looks?: string; + /** For a refusal or a failure (HTTP 400 and up): the short message the system gave ("Missing required permission: …"), so the reason is plain. Never kept for a good answer. */ + reply?: string; error?: string; } @@ -42,6 +44,20 @@ export async function inspectCalls(run: () => Promise): Promise<{ calls: I }); } +const REPLY_KEYS = ["message", "error", "error_description", "detail", "title", "reason"]; + +/** Pure: the short message in an error answer ({ message: "Forbidden" }, { error: "…" }), cut to 160 characters; none when there is no such text. */ +export function replyOf(json: unknown): string | undefined { + if (json === null || typeof json !== "object" || Array.isArray(json)) return undefined; + const o = json as Record; + for (const key of REPLY_KEYS) { + const v = o[key]; + if (typeof v === "string" && v.trim() !== "") return v.trim().replace(/\s+/g, " ").slice(0, 160); + if (Array.isArray(v) && typeof v[0] === "string") return v.filter((x) => typeof x === "string").join("; ").slice(0, 160); + } + return undefined; +} + /** Pure: what an answer that is not JSON looks like — a web page, markup, plain text — from its first characters; none of its words are kept. */ export function looksLike(text: string): string | undefined { const head = text.trimStart().slice(0, 200); diff --git a/server/test/inspector.test.ts b/server/test/inspector.test.ts index 163de50..45f1f26 100644 --- a/server/test/inspector.test.ts +++ b/server/test/inspector.test.ts @@ -72,6 +72,18 @@ describe("where it is empty", () => { }); }); +describe("the reason in a refusal", () => { + test("a short message from an error answer is kept; nothing from a good answer, and nothing that is not text", () => { + assert.equal(insp.replyOf({ message: "Missing required permission: server.statistics", statusCode: 403 }), "Missing required permission: server.statistics"); + assert.equal(insp.replyOf({ error: "invalid_token", error_description: "x" }), "invalid_token"); + assert.equal(insp.replyOf({ message: ["name must be a string", "age must be a number"] }), "name must be a string; age must be a number"); + assert.equal(insp.replyOf({ message: "a".repeat(500) })?.length, 160); + assert.equal(insp.replyOf({ data: [1] }), undefined); + assert.equal(insp.replyOf([{ message: "x" }]), undefined); + assert.equal(insp.replyOf(null), undefined); + }); +}); + describe("what an answer that is not JSON looks like", () => { test("a web page, markup, metrics text, plain text or nothing — from its first characters only", () => { assert.equal(insp.looksLike("Not found"), "an HTML page"); @@ -91,6 +103,7 @@ describe("the requests written down while a read runs", () => { res.setHeader("content-type", "application/json"); if (req.url?.startsWith("/json")) return void res.end(JSON.stringify({ items: [{ id: 1, secret: "hidden-value" }], total: 1 })); if (req.url?.startsWith("/html")) return void res.end("nope"); + if (req.url?.startsWith("/denied")) return void ((res.statusCode = 403), res.end(JSON.stringify({ message: "Missing required permission: server.statistics" }))); res.statusCode = 404; res.end("{}"); }); @@ -114,6 +127,9 @@ describe("the requests written down while a read runs", () => { assert.deepEqual([calls[0].contentType, calls[0].looks], ["application/json", undefined]); assert.deepEqual([calls[1].contentType, calls[1].looks], ["application/json", "an HTML page"], "what the text looks like, not what it says"); assert.doesNotMatch(JSON.stringify(calls), /nope/); + assert.equal(calls[0].reply, undefined, "nothing is said of a good answer"); + const denied = (await insp.inspectCalls(async () => requestJson(`${url}/denied`))).calls[0]; + assert.deepEqual([denied.status, denied.reply], [403, "Missing required permission: server.statistics"]); assert.ok(calls[0].bytes > 10 && calls[0].ms >= 0); assert.ok(calls[3].error); assert.doesNotMatch(JSON.stringify(calls), /hidden-value|hidden/); diff --git a/web/src/api/client.ts b/web/src/api/client.ts index a189ff8..01e706c 100644 --- a/web/src/api/client.ts +++ b/web/src/api/client.ts @@ -1855,7 +1855,7 @@ export interface IntegrationInspection { ok: boolean; error: string | null; ms: number; - calls: { method: string; path: string; status: number; ms: number; bytes: number; shape: string | null; contentType?: string; looks?: string; error?: string }[]; + calls: { method: string; path: string; status: number; ms: number; bytes: number; shape: string | null; contentType?: string; looks?: string; reply?: string; error?: string }[]; resultShape: string | null; empty: { path: string; what: "null" | "text" | "list" | "every-item" }[]; } diff --git a/web/src/components/IntegrationInspector.tsx b/web/src/components/IntegrationInspector.tsx index 381cced..c322fd9 100644 --- a/web/src/components/IntegrationInspector.tsx +++ b/web/src/components/IntegrationInspector.tsx @@ -27,6 +27,7 @@ function reportText(i: IntegrationSummary, r: IntegrationInspection): string { lines.push("What was asked and what came back:"); for (const c of r.calls) { lines.push(` ${c.method} ${c.path} → ${c.status === 0 ? `no answer (${c.error ?? "?"})` : c.status} · ${c.ms} ms · ${c.bytes} bytes`); + if (c.reply) lines.push(` It said: "${c.reply}"`); if (c.shape) lines.push(` ${c.shape}`); else if (c.status !== 0) lines.push(` ${notJson(c)}`); } @@ -104,6 +105,7 @@ export default function IntegrationInspector({ integration, onClose }: { integra {c.error &&
{c.error}
} + {c.reply &&
It said: “{c.reply}”
} {c.shape &&
{c.shape}
} {!c.shape && c.status !== 0 &&
{notJson(c)}
}