src/ops-types/sites.ts

Functions

None: it only declares types or values.

Imports

It imports no other module of this repo. Imported by src/health.ts, src/live-checks.ts, src/maintenance-deploys.ts, src/ops-cloudflare.ts, src/ops-packages.ts, src/ops-sites.ts, src/ops-snapshot.ts, src/ops-types/feed.ts, src/shared-code.ts, src/site-convergence.ts, src/site-operator.ts, src/site-repair.ts, src/site-watch.ts, src/watcher-detect.ts, src/watcher-gather.ts, src/watcher.ts.

Source

1// The Watch Floor contract: what GET /portal/api/ops returns
2// (capsid/research/design-ops-console.md). Types only, no runtime code, so the
3// dashboard app under dashboard/ imports it with `import type` and src/ never imports
4// from the app. Changing a field here changes both sides, and both typecheck against it.
5
6export type ProbeState = "ok" | "degraded" | "liveness" | "down";
7type CheckState = "clear" | "finding" | "could-not-run";
8
9export interface SiteProbe {
10  namespace: string;
11  name: string;
12  origin: string;
13  health_path: string | null;
14  platform: "cloudflare" | "vercel";
15  state: ProbeState;
16  // The status of the URL the state rests on: the health route, or the root.
17  http_status: number | null;
18  latency_ms: number | null;
19  // Reported by the site's own health route, where it reports one.
20  sha: string | null;
21  error: string | null;
22  checked_at: string;
23}
24
25export interface CfDeploy {
26  id: string;
27  created_on: string;
28  // The version serving the largest share of traffic in this deployment.
29  version_id: string | null;
30  // annotations["workers/message"] and ["workers/triggered_by"], as Cloudflare
31  // records them.
32  message: string | null;
33  triggered_by: string | null;
34  author_email: string | null;
35}
36
37export interface HourBucket {
38  // The hour's start, ISO.
39  hour: string;
40  requests: number;
41  errors: number;
42}
43
44// Cloudflare's view of one site. Every state but "ok" is shown as no data, with its
45// reason, never as zero.
46export type SiteCloudflare =
47  | { state: "no-token"; reason: string }
48  | { state: "not-cloudflare"; reason: string }
49  | { state: "unresolved"; reason: string }
50  | { state: "error"; reason: string }
51  | {
52      state: "ok";
53      script: string;
54      // Newest first, at most 10.
55      deploys: CfDeploy[];
56      // 24 hourly buckets, oldest first; null with a reason when the analytics query
57      // failed while the deployments read did not.
58      errors24: HourBucket[] | null;
59      errors_reason: string | null;
60    };
61
62export interface SiteSnapshot extends SiteProbe {
63  // '1' up, '0' down, '-' no pass, one character per half-hour slot, 7 days.
64  ring: string;
65  // The clock slot (minutes since the epoch / 30) of the ring's last character.
66  ring_slot: number;
67  // Absent on snapshots written before the Cloudflare read existed.
68  cloudflare?: SiteCloudflare;
69}
70
71export interface CiObservation {
72  namespace: string;
73  // Null when the repo's runs could not be read this pass.
74  latest: { head_sha: string; status: string; conclusion: string | null; created_at: string; url: string | null } | null;
75}
76
77export interface MirrorObservation {
78  newest_dump: string | null;
79  last_run: { at: string | null; conclusion: string | null; url: string | null } | null;
80}
81
82export interface SiteMapDrift {
83  unmapped: string[];
84  unknown: string[];
85}
86
87// One row of the Portal's site configuration (ops_sites, src/ops-sites.ts). A row with
88// no origin says its namespace serves no site; platform is null exactly then.
89export interface OpsSiteConfig {
90  namespace: string;
91  name: string;
92  origin: string | null;
93  health_path: string | null;
94  platform: "cloudflare" | "vercel" | null;
95  script: string | null;
96  // Probed in-process rather than over HTTP: Capsid's own row. Not settable from the Portal.
97  self_probe: boolean;
98  // Counts edits. site_edit and site_remove name the revision they previewed.
99  revision: number;
100  updated_at: string;
101  // The site's operator API, where it opted in (migrations/0035, src/site-operator.ts);
102  // null where it has none. operator_problem says why a stored value was not usable.
103  operator: SiteOperator | null;
104  operator_problem: string | null;
105}
106
107// A site's operator API as Capsid may use it: where it is, which Capsid Worker secret
108// holds its token (the name only), which repair each failing health check maps to (in
109// repair order), the tools run once a week, and the names of the site Worker's secrets
110// to report set or not.
111export interface SiteOperator {
112  path: string;
113  // The name of the Capsid Worker secret holding the site's operator token.
114  auth_var: string;
115  repairs: Record<string, string>;
116  weekly: string[];
117  secrets: string[];
118}
119
120export interface HealthSnapshot {
121  status: "ok" | "degraded";
122  sha: string;
123  dirty: boolean;
124  builtAt: string | null;
125  schema_version: string | null;
126  store: { d1: string; fts: string };
127  bindings: { media: string; app_kv: string };
128  backup: { last_ok: string | null; age_hours: number | null; warning?: string };
129}
130
131export interface OpsSnapshot {
132  version: 1;
133  pass_at: string;
134  pass_ms: number;
135  cadence_min: number;
136  checks: Array<{ id: string; state: CheckState; findings: string[] }>;
137  health: HealthSnapshot | null;
138  mirror: MirrorObservation | null;
139  ci: CiObservation[];
140  site_map: SiteMapDrift | null;
141  sites: SiteSnapshot[];
142  // Each configured package as this pass read it (src/ops-packages.ts). Optional, so a
143  // snapshot written before the panel existed still parses; absent or empty with no
144  // package configured.
145  packages?: PackageSnapshot[];
146}
147
148// One row of the Portal's package configuration (ops_packages, migrations/0028).
149export interface OpsPackageConfig {
150  // The npm name, the row's key.
151  name: string;
152  registry: "npm";
153  // owner/name on GitHub, or null.
154  repo: string | null;
155  // An earlier npm name whose download history is shown joined to this one, or null.
156  formerly: string | null;
157  // Counts edits. package_edit and package_remove name the revision they previewed.
158  revision: number;
159  updated_at: string;
160}
161
162// One part of a package's read: what it said, or why it could not be read. "none" is
163// an answer (no repository configured, no dependents on record), not a failure.
164type PackagePart<T> = ({ state: "ok" } & T) | { state: "none"; reason: string } | { state: "error"; reason: string };
165
166// What one watcher pass read for one package. Every source is named where it is used
167// (src/ops-packages.ts), with what it counts and what it misses.
168export interface PackageSnapshot {
169  name: string;
170  registry: "npm";
171  at: string;
172  // registry.npmjs.org, the abbreviated document.
173  npm: PackagePart<{ latest: string | null; dist_tags: Record<string, string>; versions: number; modified: string | null }>;
174  // api.npmjs.org: the last 7 and 30 days, and per version for the last 7 days only
175  // (npm keeps no per-version history). through is the last day npm has counted.
176  downloads: PackagePart<{ last_week: number; last_month: number; through: string | null; by_version_last_week: Record<string, number> }>;
177  // deps.dev v3alpha, for the default version: distinct packages that depend on it,
178  // directly or through another package. Counts only; no public API lists them.
179  dependents: PackagePart<{ version: string; direct: number; indirect: number; total: number }>;
180  // The GitHub App's read of the repository.
181  github: PackagePart<{ repo: string; stars: number; open_issues: number; open_prs: number; open_prs_capped: boolean; latest_release: { tag: string; published_at: string | null } | null }>;
182}
183
184// GET /portal/api/packages/history?name=: the daily download history of one configured
185// package, joined to its former name's, and its weekly GitHub numbers.
186export interface PortalPackageHistory {
187  name: string;
188  formerly: string | null;
189  generated: string;
190  // Served from the cache when it is younger than its TTL; the time it was fetched.
191  fetched_at: string;
192  // One entry per day with any count, oldest first; each day names which package the
193  // count came from.
194  days: Array<{ day: string; downloads: number; name: string }>;
195  first_day: string | null;
196  last_day: string | null;
197  // Why a range could not be read, and anything else a reader should know.
198  notes: string[];
199  weeks: Array<{ week: string; stars: number; open_issues: number; open_prs: number; latest_release: string | null }>;
200}