Files
bobbanandClaude Sonnet 5.5 0146eb8bca Jellyfin: who is watching, and don't update a machine mid-film
New Jellyfin integration (read-only, every 2 minutes): version, restart wanted,
streams and transcoding, failed scheduled tasks, item counts, failed sign-ins.
Monitoring -> Jellyfin page with a peak-streams history, three alerts, /metrics.

When Jellyfin runs on a managed server, an update run asks first if people are
streaming (409 "watching" unless startAnyway), and a patch plan waits up to two
hours for them before updating that server.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-10-24 22:01:18 +02:00

338 lines
20 KiB
TypeScript

/**
* Jellyfin: reading what its API says, what is stored and when a history point is added, what is wrong with it, who is watching (and the warning before an update run
* restarts the machine), the health pass, the page's routes and /metrics.
*
* Run with: npm test --workspace server
*/
import { test, describe, before, after } from "node:test";
import assert from "node:assert/strict";
import { createServer as createHttpServer, type Server } from "node:http";
import { mkdtempSync, rmSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import type { AddressInfo } from "node:net";
const dir = mkdtempSync(join(tmpdir(), "hm-jellyfin-"));
process.env.DATABASE_PATH = join(dir, "test.sqlite");
process.env.SESSION_DIR = join(dir, "sessions");
process.env.CREDENTIALS_ENCRYPTION_KEY = "ab".repeat(32);
process.env.HEALTH_STARTUP_GRACE_MS = "0";
const express = (await import("express")).default;
const { db } = await import("../src/db/client.js");
const { users, servers, integrations, jellyfinReadings, jellyfinState } = await import("../src/db/schema.js");
const { runMigrations } = await import("../src/db/migrate.js");
const adapter = await import("../src/integrations/jellyfin/adapter.js");
const jf = await import("../src/services/jellyfinSync.js");
const { evaluateHealth, collectSnapshot } = await import("../src/services/healthMonitor.js");
const { subjectOfConditionKey } = await import("../src/services/maintenance.js");
const { getAlerts, invalidateAlertsCache } = await import("../src/services/alerts.js");
const { startUpdateRun, UpdateRunError } = await import("../src/services/updateRuns.js");
const { jellyfinRouter } = await import("../src/routes/jellyfin.js");
const { buildMetrics } = await import("../src/services/metrics.js");
const { setInternalFlag } = await import("../src/services/settingsStore.js");
const { eq } = await import("drizzle-orm");
await runMigrations();
const MIN = 60_000;
const DAY = 86_400_000;
const SESSIONS = [
{ UserName: "Ann", Client: "Jellyfin Web", DeviceName: "Firefox", NowPlayingItem: { Name: "Dune" }, PlayState: { PlayMethod: "DirectPlay", IsPaused: false } },
{ UserName: "Bo", Client: "Android TV", DeviceName: "Shield", NowPlayingItem: { Name: "Pilot", SeriesName: "The Office" }, PlayState: { PlayMethod: "Transcode", IsPaused: true }, TranscodingInfo: { VideoCodec: "h264" } },
{ UserName: "Cy", Client: "Jellyfin Web", DeviceName: "Chrome" }, // signed in, playing nothing
];
const read = (extra: Partial<import("../src/integrations/jellyfin/adapter.js").JellyfinRead> = {}) => ({
name: "Den", version: "10.10.3", os: "Linux", pendingRestart: false, updateAvailable: false, streams: [] as import("../src/integrations/jellyfin/adapter.js").JellyfinStream[],
tasks: [] as import("../src/integrations/jellyfin/adapter.js").JellyfinTask[], counts: { movies: 120, series: 30, episodes: 900, songs: null }, failedLogins24h: 0, ...extra,
});
const stream = (user: string, extra: Partial<import("../src/integrations/jellyfin/adapter.js").JellyfinStream> = {}) => ({ user, client: "Web", device: "Firefox", title: "Dune", transcoding: false, paused: false, ...extra });
describe("what Jellyfin's API says", () => {
test("the server's own information", () => {
const i = adapter.parseSystemInfo({ ServerName: "Den", Version: "10.10.3", OperatingSystemDisplayName: "Debian", HasPendingRestart: true, HasUpdateAvailable: false });
assert.deepEqual(i, { name: "Den", version: "10.10.3", os: "Debian", pendingRestart: true, updateAvailable: false });
assert.deepEqual(adapter.parseSystemInfo(null), { name: null, version: null, os: null, pendingRestart: false, updateAvailable: false });
});
test("only the sessions playing something are streams, with the series in the title and transcoding told from the play method", () => {
const s = adapter.parseSessions(SESSIONS);
assert.deepEqual(s.map((x) => [x.user, x.title, x.transcoding, x.paused]), [["Ann", "Dune", false, false], ["Bo", "The Office — Pilot", true, true]]);
assert.deepEqual(adapter.parseSessions("nonsense"), []);
});
test("the scheduled tasks, hidden ones left out, with how they last ended", () => {
const t = adapter.parseTasks([
{ Name: "Scan media library", Category: "Library", State: "Idle", LastExecutionResult: { Status: "Failed", EndTimeUtc: "2026-10-20T03:00:00Z", ErrorMessage: "disk full" } },
{ Name: "Hidden", IsHidden: true },
{ Name: "Never run" },
]);
assert.equal(t.length, 2);
assert.deepEqual([t[0].lastStatus, t[0].error, t[0].lastEndedAt], ["Failed", "disk full", "2026-10-20T03:00:00.000Z"]);
assert.equal(t[1].lastStatus, null);
});
test("failed sign-ins in the last day, from the activity log", () => {
const now = new Date("2026-10-20T12:00:00Z");
const raw = { Items: [{ Type: "AuthenticationFailed", Date: "2026-10-20T11:00:00Z" }, { Type: "AuthenticationFailed", Date: "2026-10-18T11:00:00Z" }, { Type: "UserLoggedIn", Date: "2026-10-20T11:30:00Z" }] };
assert.equal(adapter.countFailedLogins(raw, now), 1);
assert.equal(adapter.countFailedLogins({}, now), null);
});
describe("the adapter against a Jellyfin that answers", () => {
let server: Server;
let url = "";
const seen: { path: string; token: string | undefined }[] = [];
before(async () => {
server = createHttpServer((req, res) => {
seen.push({ path: req.url ?? "", token: req.headers["x-emby-token"] as string | undefined });
const send = (code: number, body: unknown) => {
res.writeHead(code, { "content-type": "application/json" });
res.end(JSON.stringify(body));
};
if (req.headers["x-emby-token"] !== "key") return send(401, {});
const path = (req.url ?? "").split("?")[0];
if (path === "/System/Info") return send(200, { ServerName: "Den", Version: "10.10.3", HasPendingRestart: false });
if (path === "/Sessions") return send(200, SESSIONS);
if (path === "/ScheduledTasks") return send(500, {}); // the rest is worth having, not worth failing for
if (path === "/Items/Counts") return send(200, { MovieCount: 120, SeriesCount: 30 });
send(404, {});
});
await new Promise<void>((resolve) => server.listen(0, "127.0.0.1", resolve));
url = `http://127.0.0.1:${(server.address() as AddressInfo).port}`;
});
after(() => server.close());
test("it reads, sends the key, and a part that cannot be read does not fail the whole", async () => {
const r = await adapter.createJellyfinAdapter({ url: `${url}/`, apiKey: "key" }).read(new Date());
assert.equal(r.name, "Den");
assert.equal(r.streams.length, 2);
assert.deepEqual(r.tasks, [], "its tasks could not be read");
assert.deepEqual([r.counts.movies, r.counts.songs, r.failedLogins24h], [120, null, null]);
assert.ok(seen.every((s) => s.token === "key"));
});
test("a refused key and a dead address are said plainly", async () => {
const bad = await adapter.createJellyfinAdapter({ url, apiKey: "nope" }).ping();
assert.equal(bad.ok, false);
assert.match(bad.error ?? "", /did not accept the API key/);
const good = await adapter.createJellyfinAdapter({ url, apiKey: "key" }).ping();
assert.equal(good.ok, true);
const dead = await adapter.createJellyfinAdapter({ url: "http://127.0.0.1:1", apiKey: "key" }).ping();
assert.equal(dead.ok, false);
});
});
});
describe("what is stored", () => {
let id = 0;
before(async () => {
id = (await db.insert(integrations).values({ type: "jellyfin", name: "Den", baseUrl: "http://10.9.9.8:8096", config: JSON.stringify({ url: "http://10.9.9.8:8096", apiKey: "key" }) }).returning({ id: integrations.id }))[0].id;
});
const points = async () => (await db.select().from(jellyfinReadings).where(eq(jellyfinReadings.integrationId, id))).sort((a, b) => a.at.localeCompare(b.at));
test("the state is replaced at each read; a history point is added when it is time or when the number streaming changes", async () => {
const t0 = new Date(Date.now() - 60 * MIN);
await jf.storeRead(id, read({ streams: [stream("Ann")] }), t0);
await jf.storeRead(id, read({ streams: [stream("Ann")] }), new Date(t0.getTime() + 1 * MIN));
assert.equal((await points()).length, 1, "nothing changed, and it is too soon");
await jf.storeRead(id, read({ streams: [stream("Ann"), stream("Bo", { transcoding: true })] }), new Date(t0.getTime() + 2 * MIN));
assert.deepEqual((await points()).map((p) => [p.streams, p.transcodes]), [[1, 0], [2, 1]], "a change is a point at once");
await jf.storeRead(id, read({ streams: [stream("Ann"), stream("Bo", { transcoding: true })] }), new Date(t0.getTime() + 8 * MIN));
assert.equal((await points()).length, 3, "and so is the passing of five minutes");
const [state] = await db.select().from(jellyfinState).where(eq(jellyfinState.integrationId, id));
assert.equal(jf.streamsOf(state).length, 2);
assert.equal(state.movies, 120);
});
test("readings older than 35 days are dropped", async () => {
await db.insert(jellyfinReadings).values({ integrationId: id, at: new Date(Date.now() - 40 * DAY).toISOString(), streams: 5, transcodes: 0 });
await jf.storeRead(id, read(), new Date());
assert.ok((await points()).every((p) => Date.parse(p.at) > Date.now() - 36 * DAY));
});
test("a read that failed is said, and what was stored is left alone", async () => {
const ok = await jf.syncJellyfin(id, new Date(), async () => read({ name: "Den", version: "10.10.4" }));
assert.equal(ok.ok, true);
const failed = await jf.syncJellyfin(id, new Date(), async () => {
throw new Error("connection refused");
});
assert.deepEqual([failed.ok, failed.error], [false, "connection refused"]);
assert.equal(failed.at, ok.at, "the time of the last good read is kept");
const [state] = await db.select().from(jellyfinState).where(eq(jellyfinState.integrationId, id));
assert.equal(state.version, "10.10.4");
assert.equal((await jf.jellyfinSyncStatuses())[id].ok, false);
assert.equal(jf.isJellyfinFresh((await jf.jellyfinSyncStatuses())[id], Date.now()), false, "a failed read is not believed");
});
test("only a good read recent enough is fresh", () => {
const now = Date.now();
assert.equal(jf.isJellyfinFresh({ at: new Date(now - 3 * MIN).toISOString(), ok: true, error: null }, now), true);
assert.equal(jf.isJellyfinFresh({ at: new Date(now - 11 * MIN).toISOString(), ok: true, error: null }, now), false);
assert.equal(jf.isJellyfinFresh(undefined, now), false);
});
});
describe("what is wrong, and the history in peaks", () => {
const row = (extra: Partial<Parameters<typeof jf.jellyfinProblems>[2]> = {}) => ({ pendingRestart: false, tasks: "[]", failedLogins24h: 0, ...extra });
test("a restart that is wanted, a task that failed, a burst of failed sign-ins", () => {
assert.deepEqual(jf.jellyfinProblems(1, "Den", row()), []);
const p = jf.jellyfinProblems(
1,
"Den",
row({ pendingRestart: true, failedLogins24h: jf.FAILED_LOGINS_WARN, tasks: JSON.stringify([{ name: "Scan", category: null, state: "Idle", lastStatus: "Failed", lastEndedAt: null, error: "disk full" }, { name: "Clean", category: null, state: "Idle", lastStatus: "Completed", lastEndedAt: null, error: null }]) }),
);
assert.deepEqual(p.map((x) => x.key), ["jellyfin-restart:1", "jellyfin-task:1:Scan", "jellyfin-logins:1"]);
assert.match(p[1].message, /“Scan” failed — disk full/);
assert.equal(jf.jellyfinProblems(1, "Den", row({ failedLogins24h: jf.FAILED_LOGINS_WARN - 1 })).length, 0);
});
test("history is bucketed to the peak of each stretch", () => {
const from = Date.parse("2026-10-20T00:00:00Z");
const to = from + 4 * 3_600_000;
const rows = [
{ at: new Date(from + 5 * MIN).toISOString(), streams: 1, transcodes: 0 },
{ at: new Date(from + 20 * MIN).toISOString(), streams: 3, transcodes: 2 },
{ at: new Date(from + 3 * 3_600_000 + 10 * MIN).toISOString(), streams: 2, transcodes: 0 },
{ at: new Date(from - MIN).toISOString(), streams: 9, transcodes: 9 }, // before the range
];
const b = jf.bucketPeaks(rows, from, to, 4);
assert.deepEqual(b.map((p) => [p.streams, p.transcodes]), [[3, 2], [2, 0]], "an average would have hidden the evening");
assert.deepEqual(jf.bucketPeaks([], from, to, 4), []);
});
});
describe("who is watching, the warning before an update, the health pass, the page and /metrics", () => {
let jfId = 0;
let serverId = 0;
let otherId = 0;
let app: Server;
let base = "";
const fresh = () => setInternalFlag("jellyfinSync", JSON.stringify({ [jfId]: { at: new Date().toISOString(), ok: true, error: null } }));
before(async () => {
await db.insert(users).values([{ oidcSub: "viewer", name: "Vic", role: "viewer" }]);
jfId = (await db.insert(integrations).values({ type: "jellyfin", name: "Cinema", baseUrl: "http://10.9.9.9:8096", config: JSON.stringify({ url: "http://10.9.9.9:8096", apiKey: "key" }) }).returning({ id: integrations.id }))[0].id;
const mk = async (name: string, ip: string) =>
(await db.insert(servers).values({ name, apiTokenHash: name, apiTokenPrefix: name, lastSeenAt: new Date().toISOString(), ipAddresses: JSON.stringify([ip]) }).returning({ id: servers.id }))[0].id;
serverId = await mk("media", "10.9.9.9");
otherId = await mk("other", "10.9.9.10");
await jf.storeRead(jfId, read({ name: "Cinema", pendingRestart: true, streams: [stream("Ann", { title: "Dune" }), stream("Bo", { title: "The Office — Pilot", transcoding: true })] }));
await fresh();
const a = express();
a.use((req, _res, next) => {
(req as unknown as { session: unknown }).session = { user: { sub: "viewer" } };
next();
});
a.use("/api/jellyfin", jellyfinRouter);
app = await new Promise<Server>((resolve) => {
const s = a.listen(0, "127.0.0.1", () => resolve(s));
});
base = `http://127.0.0.1:${(app.address() as AddressInfo).port}/api/jellyfin`;
});
after(() => {
app.close();
try {
rmSync(dir, { recursive: true, force: true });
} catch {
// Windows keeps the database file locked until the process exits.
}
});
test("the people streaming from the Jellyfin that runs on a server, in words; none on another, none when the read is old", async () => {
const w = await jf.watchingOnServer(serverId);
assert.equal(w.length, 1);
assert.equal(jf.watchingWords(w), "2 people are streaming from Cinema (Ann: Dune, Bo: The Office — Pilot), 1 being transcoded");
assert.deepEqual(await jf.watchingOnServer(otherId), []);
await setInternalFlag("jellyfinSync", JSON.stringify({ [jfId]: { at: new Date(Date.now() - 30 * MIN).toISOString(), ok: true, error: null } }));
assert.deepEqual(await jf.watchingOnServer(serverId), [], "an old reading is not believed");
await fresh();
assert.equal(jf.watchingWords([]), "");
});
test("an update run on that machine is held back with 409 'watching' unless it is told to go ahead", async () => {
const input = { serverId, integrationId: 999_999, projectId: 1, templateId: 1, limit: "media", windowMinutes: 90, actor: "test" };
await assert.rejects(
() => startUpdateRun(input),
(err: unknown) => err instanceof UpdateRunError && err.status === 409 && err.code === "watching" && /2 people are streaming from Cinema/.test(err.message),
);
// Past the warning it carries on to the next check, which is the Semaphore that doesn't exist here.
await assert.rejects(
() => startUpdateRun({ ...input, startAnyway: true }),
(err: unknown) => err instanceof UpdateRunError && err.code === "no_semaphore",
);
// A machine nobody is streaming from is not held back.
await assert.rejects(
() => startUpdateRun({ ...input, serverId: otherId }),
(err: unknown) => err instanceof UpdateRunError && err.code === "no_semaphore",
);
});
test("the health pass judges it from what is stored, and holds it when the last read is old", async () => {
let { snapshot, held } = await collectSnapshot();
assert.deepEqual(snapshot.jellyfin?.map((j) => j.integrationId), [jfId]);
assert.equal(held.has(`jellyfin:${jfId}`), false);
const list = evaluateHealth(snapshot, { serverOfflineMinutes: 60, diskUsagePercent: 90 }, Date.now(), { skipServers: true });
const c = list.find((x) => x.key === `jellyfin-restart:${jfId}`)!;
assert.deepEqual([c.severity, c.source], ["warning", `jellyfin:${jfId}`]);
assert.equal(subjectOfConditionKey(c.key), `integration:${jfId}`, "maintenance on it silences its alerts");
await setInternalFlag("jellyfinSync", JSON.stringify({ [jfId]: { at: new Date(Date.now() - 30 * MIN).toISOString(), ok: true, error: null } }));
({ snapshot, held } = await collectSnapshot());
assert.deepEqual([snapshot.jellyfin ?? [], held.has(`jellyfin:${jfId}`)], [[], true]);
await fresh();
});
test("the Alerts page shows it, with where to look", async () => {
invalidateAlertsCache();
const report = await getAlerts(true);
const a = report.alerts.find((x) => x.id === `monitoring:jellyfin-restart:${jfId}`)!;
assert.ok(a, "the restart that is wanted is an alert");
assert.deepEqual([a.severity, a.category, a.source, a.link, a.target?.type, a.target?.id], ["warning", "monitoring", "Jellyfin", "/jellyfin", "integration", jfId]);
});
test("anyone signed in sees each Jellyfin, who is streaming and what is wrong", async () => {
const res = await fetch(base);
assert.equal(res.status, 200);
const body = (await res.json()) as { jellyfins: { id: number; fresh: boolean; runsOn: { name: string } | null; state: { streams: unknown[] } | null; problems: { key: string }[] }[] };
const j = body.jellyfins.find((x) => x.id === jfId)!;
assert.equal(j.fresh, true);
assert.equal(j.runsOn?.name, "media");
assert.equal(j.state?.streams.length, 2);
assert.ok(j.problems.some((p) => p.key === `jellyfin-restart:${jfId}`));
});
test("who is watching on a server is asked for by its id, and a wrong id is refused", async () => {
const r = (await (await fetch(`${base}/watching?serverId=${serverId}`)).json()) as { watching: unknown[]; words: string };
assert.equal(r.watching.length, 1);
assert.match(r.words, /2 people are streaming/);
const none = (await (await fetch(`${base}/watching?serverId=${otherId}`)).json()) as { watching: unknown[]; words: string };
assert.deepEqual([none.watching.length, none.words], [0, ""]);
assert.equal((await fetch(`${base}/watching?serverId=abc`)).status, 400);
});
test("the history is the peaks of the last days; a missing Jellyfin is not found", async () => {
const res = await fetch(`${base}/${jfId}/history?days=1`);
assert.equal(res.status, 200);
const body = (await res.json()) as { days: number; points: { streams: number; transcodes: number }[] };
assert.equal(body.days, 1);
assert.ok(body.points.some((p) => p.streams === 2 && p.transcodes === 1));
assert.equal((await (await fetch(`${base}/${jfId}/history?days=400`)).json() as { days: number }).days, jf.READING_KEEP_DAYS, "no further back than is kept");
assert.equal((await fetch(`${base}/999999/history`)).status, 404);
});
test("/metrics has how many are streaming, how many are transcoded and whether a restart is wanted — only while the reading is recent", async () => {
let text = await buildMetrics(new Date());
assert.match(text, /homelab_jellyfin_streams\{name="Cinema"\} 2/);
assert.match(text, /homelab_jellyfin_transcodes\{name="Cinema"\} 1/);
assert.match(text, /homelab_jellyfin_pending_restart\{name="Cinema"\} 1/);
await setInternalFlag("jellyfinSync", JSON.stringify({ [jfId]: { at: new Date(Date.now() - 30 * MIN).toISOString(), ok: true, error: null } }));
text = await buildMetrics(new Date());
assert.doesNotMatch(text, /homelab_jellyfin_streams/);
});
});