1/** Shapes and rules shared by the server and the web app; keep this free of Node imports. */
2
3export type Health = "healthy" | "degraded" | "down" | "stopped" | "deploying" | "restarting" | "starting";
4
5/** Columnar series, the layout uPlot consumes directly. Times are unix seconds. */
6export interface Series {
7 name: string;
8 t: number[];
9 v: (number | null)[];
10}
11
12export interface Me {
13 id: string;
14 name: string;
15 groups: string[];
16 sections: Section[];
17 /** An admin previewing the dashboard as `groups`. */
18 viewing: boolean;
19}
20
21/** Cookie holding the comma-separated groups an admin previews the dashboard as. */
22export const VIEW_AS = "view-as";
23
24/** The account group that opens each dashboard section; null opens it to everyone. */
25const SECTION_GROUPS = { launcher: null, admin: "infra-admin", metrics: "metrics", media: "media-manage", vms: "vm", ai: "ai" } as const;
26export type Section = keyof typeof SECTION_GROUPS;
27
28/** Admins reach everything; `access` null is open to every signed-in user. */
29export const canOpen = (groups: string[], access: string | null) =>
30 access === null || groups.includes("infra-admin") || groups.includes(access);
31
32export const sectionsOf = (groups: string[]) =>
33 (Object.keys(SECTION_GROUPS) as Section[]).filter((section) => canOpen(groups, SECTION_GROUPS[section]));
34
35export interface ServiceSummary {
36 id: string;
37 name: string;
38 health: Health;
39 url: string | null;
40 /** Versioned image URLs per color scheme; the same URL twice when the service has one image. */
41 icon: { light: string; dark: string } | null;
42 /** Account group that sees this service in the launcher; null means everyone. */
43 access: string | null;
44 /** What the app is for, in a few words, for people who don't know it by name. */
45 tagline: string | null;
46 /** Cores in use and reserved; use is null while Nomad doesn't measure it. */
47 cpu: number | null;
48 cpuLimit: number;
49 /** Bytes in use and reserved; use is null while Nomad doesn't measure it. */
50 memory: number | null;
51 memoryLimit: number;
52}
53
54/** An app the VPS agents report, keyed `vps.<name>`; usage, restarts and start time are pm2's. */
55export interface VpsService {
56 id: string;
57 name: string;
58 health: Health;
59 cpu: number | null;
60 memory: number | null;
61 restarts: number | null;
62 startedAt: number | null;
63 applicationMetrics: string[];
64}
65
66/** States that need someone to look, unlike stopped (on purpose) or the passing ones like restarting. */
67export const trouble = (health: Health) => health === "down" || health === "degraded";
68
69/** A service that is currently down or degraded. */
70export interface Issue {
71 service: Pick<ServiceSummary, "id" | "name" | "icon" | "url">;
72 health: Health;
73 /** The failing check's output while it's down or degraded. */
74 failing: string | null;
75}
76
77/** When a task runs relative to the main ones; null for a main task. */
78export type Hook = "prestart" | "poststart" | "poststop" | null;
79
80/** A Nomad task; its restarts count within the current allocation. */
81export interface Container {
82 name: string;
83 /** As configured; null for tasks that don't run an image. */
84 image: string | null;
85 hook: Hook;
86 state: "running" | "pending" | "dead";
87 restarts: number;
88 lastRestart: { t: number; reason: string } | null;
89 startedAt: number | null;
90}
91
92/** The service on the other end of a dependency, and what it provides ("database", "sign-in"). */
93export interface ServiceLink {
94 id: string;
95 name: string;
96 kind: string;
97 health: Health;
98}
99
100/** The latest restart, unless it happened before restarts were last acknowledged. */
101export function unacknowledgedRestart(service: Pick<ServiceDetail, "containers" | "restartsAcknowledged">) {
102 const last = service.containers.flatMap((container) => container.lastRestart ?? []).sort((a, b) => b.t - a.t)[0];
103 return last && (service.restartsAcknowledged === null || last.t > service.restartsAcknowledged) ? last : null;
104}
105
106/** Lists that are null come from a source the host doesn't expose yet. */
107export interface ServiceDetail extends ServiceSummary {
108 /** Application spans observed in the trace store, excluding Caddy's edge spans. */
109 applicationTraces: boolean;
110 /** Metric names ingested for this service. */
111 applicationMetrics: string[];
112 /** The release this service's job was rendered from. */
113 release: string | null;
114 /** When Nomad was last handed this job. */
115 deployedAt: number;
116 rollout: "simple" | "overlapped";
117 containers: Container[];
118 checks: { name: string; passing: boolean; output: string }[];
119 requirements: ServiceLink[] | null;
120 dependents: ServiceLink[] | null;
121 /** Generated secrets can be rotated; the rest are supplied by hand. */
122 secrets: { name: string; generated: boolean }[] | null;
123 /** `used` excludes what snapshots hold. */
124 datasets: { name: string; mountpoint: string; used: number; snapshots: number }[];
125 /** When restarts were last acknowledged; ones before it no longer need attention. */
126 restartsAcknowledged: number | null;
127 /** This service's logs in the Logs web UI; null when that UI isn't set up. */
128 logs: AppLink | null;
129}
130
131/** A service's Nomad job as submitted, one entry per task group. Durations are seconds. */
132export interface ServiceDefinition {
133 groups: {
134 name: string;
135 count: number;
136 /** Restarts allowed per `interval`, `delay` apart; once spent, `fail` gives up instead of waiting out the interval. */
137 restart: { attempts: number; interval: number; delay: number; fail: boolean };
138 services: {
139 name: string;
140 port: string;
141 /** Hostnames the router sends here; empty for a service only other services reach. */
142 hostnames: string[];
143 /** The account group that must sign in first; null for no sign-in gate. */
144 authRole: string | null;
145 /** `restartAfter` failures in a row restart `task`, counted once `grace` has passed since it started. */
146 check: {
147 task: string;
148 type: string;
149 path: string;
150 interval: number;
151 timeout: number;
152 restartAfter: { failures: number; grace: number } | null;
153 } | null;
154 }[];
155 tasks: TaskDefinition[];
156 }[];
157 /** The service file in the current release; null when the release has none. */
158 source: string | null;
159}
160
161export interface TaskDefinition {
162 name: string;
163 hook: Hook;
164 /** A hook task that keeps running beside the main ones. */
165 sidecar: boolean;
166 image: string | null;
167 /** `uid:gid`; null runs as the image's user. */
168 user: string | null;
169 /** Cores and bytes reserved; `memoryMax` is null without room to burst past `memory`. */
170 cpu: number;
171 memory: number;
172 memoryMax: number | null;
173 /** `host` is null for a port Nomad picks at each start; `network` is "loopback" or "default". */
174 ports: { label: string; container: number | null; host: number | null; network: string }[];
175 mounts: { source: string; target: string; readOnly: boolean }[];
176 tmpfs: string[];
177 devices: string[];
178 capabilities: string[];
179 hostNetwork: boolean;
180 extraHosts: string[];
181 /** Variable names only; values never leave the server. `secret` and `template` ones are filled in as the task starts. */
182 env: { name: string; from: "job" | "secret" | "template" }[];
183}
184
185/** A deep link into another app's web UI. */
186export interface AppLink {
187 app: Pick<ServiceSummary, "id" | "name" | "icon">;
188 url: string;
189}
190
191/** An OpenTelemetry span; times are unix seconds. */
192export interface Span {
193 id: string;
194 parent: string | null;
195 service: string;
196 name: string;
197 start: number;
198 duration: number;
199 /** The status message of a failed span. */
200 error: string | null;
201 attributes: Record<string, string | number>;
202}
203
204/** Spans depth first, so the root comes first and every parent precedes its children. */
205export interface Trace {
206 id: string;
207 spans: Span[];
208}
209
210/** A trace as a list shows it, without the spans under its root. */
211export interface TraceSummary {
212 id: string;
213 root: Span;
214 spans: number;
215 services: string[];
216 /** The first failed span's status message. */
217 error: string | null;
218}
219
220export interface LogLine {
221 id?: string;
222 sequence?: number;
223 t: number;
224 container: string;
225 stream: "stdout" | "stderr" | "event";
226 level: "debug" | "info" | "warn" | "error" | null;
227 text: string;
228 event?: string | null;
229 allocation?: string | null;
230}
231
232export interface HostInfo {
233 cores: number;
234 memory: number;
235 bootedAt: number;
236 /**
237 * Stretches the UPS ran on battery, oldest first, from upsmon's ONBATT and ONLINE events; `end` is null until mains
238 * returns. Null while no UPS is connected.
239 */
240 outages: { start: number; end: number | null }[] | null;
241}
242
243export interface Ups {
244 status: "online" | "battery" | "charging" | "unknown";
245 /** Seconds of battery at the current load. */
246 runtime: number;
247 /** Watts. */
248 load: number;
249 /** Battery charge in percent. */
250 charge: number;
251}
252
253/** Seconds between ticks of the live stream. */
254export const LIVE_INTERVAL = 2;
255
256/** qBittorrent's `eta` when it has no estimate. */
257export const UNKNOWN_ETA = 8640000;
258
259/** One tick of the live stream; every value is the latest sample. */
260export interface Live {
261 t: number;
262 /** `cpu` in percent of the machine; `arc` is null without ZFS; `temperature` is the CPU package's in °C, null without a sensor. */
263 host: { cpu: number; memory: number; arc: number | null; temperature: number | null };
264 /** Empty while Nomad can't be reached. */
265 services: Record<string, Pick<ServiceSummary, "cpu" | "memory" | "health">>;
266 /** Null while no UPS is connected. */
267 ups: Ups | null;
268}
269
270export const METRICS = [
271 "host.cpu", "host.memory", "host.temperature", "host.power", "host.gpu", "host.network",
272 "service.cpu", "service.memory", "vm.cpu", "vm.memory",
273] as const;
274export type Metric = (typeof METRICS)[number];
275
276export const ACTIONS = ["restart", "stop", "start"] as const;
277export type Action = (typeof ACTIONS)[number];