@pithy-sh/audit 0.6.0 → 0.7.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +93 -0
- package/dist/accessHistory.d.ts +315 -0
- package/dist/accessHistory.d.ts.map +1 -0
- package/dist/accessHistory.js +299 -0
- package/dist/actions.d.ts +15 -1
- package/dist/actions.d.ts.map +1 -1
- package/dist/actions.js +16 -2
- package/dist/capability.d.ts +14 -0
- package/dist/capability.d.ts.map +1 -1
- package/dist/capability.js +106 -12
- package/dist/chain/append.d.ts +43 -0
- package/dist/chain/append.d.ts.map +1 -0
- package/dist/chain/append.js +110 -0
- package/dist/chain/checkpoint.d.ts +70 -0
- package/dist/chain/checkpoint.d.ts.map +1 -0
- package/dist/chain/checkpoint.js +133 -0
- package/dist/chain/lockCheck.d.ts +15 -0
- package/dist/chain/lockCheck.d.ts.map +1 -0
- package/dist/chain/lockCheck.js +75 -0
- package/dist/chain/prune.d.ts +84 -0
- package/dist/chain/prune.d.ts.map +1 -0
- package/dist/chain/prune.js +231 -0
- package/dist/chain/rows.d.ts +74 -0
- package/dist/chain/rows.d.ts.map +1 -0
- package/dist/chain/rows.js +133 -0
- package/dist/chain/tombstone.d.ts +21 -0
- package/dist/chain/tombstone.d.ts.map +1 -0
- package/dist/chain/tombstone.js +98 -0
- package/dist/chain/verify.d.ts +63 -0
- package/dist/chain/verify.d.ts.map +1 -0
- package/dist/chain/verify.js +220 -0
- package/dist/citations.d.ts +17 -0
- package/dist/citations.d.ts.map +1 -0
- package/dist/citations.js +48 -0
- package/dist/cli/emitFromCLI.d.ts +5 -0
- package/dist/cli/emitFromCLI.d.ts.map +1 -1
- package/dist/cli/emitFromCLI.js +5 -0
- package/dist/data/auditEvent.d.ts +4 -0
- package/dist/data/auditEvent.d.ts.map +1 -1
- package/dist/data/auditEvent.js +7 -3
- package/dist/data/sinkState.d.ts +23 -0
- package/dist/data/sinkState.d.ts.map +1 -0
- package/dist/data/sinkState.js +25 -0
- package/dist/data/tables.d.ts +14 -1
- package/dist/data/tables.d.ts.map +1 -1
- package/dist/data/tables.js +5 -1
- package/dist/http/guards.d.ts +39 -6
- package/dist/http/guards.d.ts.map +1 -1
- package/dist/http/guards.js +101 -17
- package/dist/http/responses.d.ts +503 -0
- package/dist/http/responses.d.ts.map +1 -1
- package/dist/http/responses.js +157 -5
- package/dist/http/routes.d.ts +25 -3
- package/dist/http/routes.d.ts.map +1 -1
- package/dist/http/routes.js +321 -15
- package/dist/http/schemas.d.ts +67 -0
- package/dist/http/schemas.d.ts.map +1 -1
- package/dist/http/schemas.js +88 -4
- package/dist/http/views.d.ts +25 -1
- package/dist/http/views.d.ts.map +1 -1
- package/dist/http/views.js +107 -2
- package/dist/migrations/0003_call_index.d.ts +21 -0
- package/dist/migrations/0003_call_index.d.ts.map +1 -0
- package/dist/migrations/0003_call_index.js +33 -0
- package/dist/migrations/0004_request_index.d.ts +16 -0
- package/dist/migrations/0004_request_index.d.ts.map +1 -0
- package/dist/migrations/0004_request_index.js +24 -0
- package/dist/migrations/0005_chain.d.ts +24 -0
- package/dist/migrations/0005_chain.d.ts.map +1 -0
- package/dist/migrations/0005_chain.js +43 -0
- package/dist/migrations/0006_sinks.d.ts +11 -0
- package/dist/migrations/0006_sinks.d.ts.map +1 -0
- package/dist/migrations/0006_sinks.js +20 -0
- package/dist/provision/resolveAuditConfig.d.ts +31 -0
- package/dist/provision/resolveAuditConfig.d.ts.map +1 -0
- package/dist/provision/resolveAuditConfig.js +43 -0
- package/dist/purge/contribution.d.ts +21 -0
- package/dist/purge/contribution.d.ts.map +1 -0
- package/dist/purge/contribution.js +41 -0
- package/dist/reach.d.ts +250 -0
- package/dist/reach.d.ts.map +1 -0
- package/dist/reach.js +244 -0
- package/dist/recorder.d.ts +11 -0
- package/dist/recorder.d.ts.map +1 -1
- package/dist/recorder.js +23 -5
- package/dist/routePattern.d.ts +60 -0
- package/dist/routePattern.d.ts.map +1 -0
- package/dist/routePattern.js +130 -0
- package/dist/seeds/example.d.ts.map +1 -1
- package/dist/seeds/example.js +23 -6
- package/dist/ship/consumer.d.ts +45 -0
- package/dist/ship/consumer.d.ts.map +1 -0
- package/dist/ship/consumer.js +141 -0
- package/dist/ship/event.d.ts +59 -0
- package/dist/ship/event.d.ts.map +1 -0
- package/dist/ship/event.js +77 -0
- package/dist/ship/health.d.ts +33 -0
- package/dist/ship/health.d.ts.map +1 -0
- package/dist/ship/health.js +80 -0
- package/dist/ship/profiles.d.ts +34 -0
- package/dist/ship/profiles.d.ts.map +1 -0
- package/dist/ship/profiles.js +62 -0
- package/dist/ship/queue.d.ts +57 -0
- package/dist/ship/queue.d.ts.map +1 -0
- package/dist/ship/queue.js +70 -0
- package/dist/ship/secrets.d.ts +7 -0
- package/dist/ship/secrets.d.ts.map +1 -0
- package/dist/ship/secrets.js +40 -0
- package/dist/ship/shipper.d.ts +15 -0
- package/dist/ship/shipper.d.ts.map +1 -0
- package/dist/ship/shipper.js +27 -0
- package/dist/ship/sinks.d.ts +54 -0
- package/dist/ship/sinks.d.ts.map +1 -0
- package/dist/ship/sinks.js +45 -0
- package/dist/ship/state.d.ts +27 -0
- package/dist/ship/state.d.ts.map +1 -0
- package/dist/ship/state.js +29 -0
- package/dist/usage.d.ts +159 -0
- package/dist/usage.d.ts.map +1 -0
- package/dist/usage.js +87 -0
- package/dist/version.generated.d.ts +1 -1
- package/dist/version.generated.js +1 -1
- package/dist/workflows/prune.d.ts +73 -0
- package/dist/workflows/prune.d.ts.map +1 -0
- package/dist/workflows/prune.js +128 -0
- package/dist/workflows/retryPolicy.d.ts +10 -0
- package/dist/workflows/retryPolicy.d.ts.map +1 -0
- package/dist/workflows/retryPolicy.js +14 -0
- package/dist/workflows/specs.d.ts +70 -0
- package/dist/workflows/specs.d.ts.map +1 -0
- package/dist/workflows/specs.js +70 -0
- package/dist/workflows/worker.d.ts +32 -0
- package/dist/workflows/worker.d.ts.map +1 -0
- package/dist/workflows/worker.js +41 -0
- package/package.json +5 -2
- package/pithy.manifest.json +36 -4
- package/src/accessHistory.ts +360 -0
- package/src/actions.ts +15 -1
- package/src/capability.ts +134 -12
- package/src/chain/append.ts +161 -0
- package/src/chain/checkpoint.ts +172 -0
- package/src/chain/lockCheck.ts +72 -0
- package/src/chain/prune.ts +340 -0
- package/src/chain/rows.ts +211 -0
- package/src/chain/tombstone.ts +104 -0
- package/src/chain/verify.ts +366 -0
- package/src/citations.ts +62 -0
- package/src/cli/emitFromCLI.ts +5 -0
- package/src/cloudflare-test.d.ts +1 -0
- package/src/data/auditEvent.ts +31 -1
- package/src/data/sinkState.ts +41 -0
- package/src/data/tables.ts +7 -1
- package/src/http/guards.ts +90 -6
- package/src/http/responses.ts +318 -3
- package/src/http/routes.ts +379 -7
- package/src/http/schemas.ts +158 -2
- package/src/http/views.ts +123 -1
- package/src/migrations/0003_call_index.ts +35 -0
- package/src/migrations/0004_request_index.ts +26 -0
- package/src/migrations/0005_chain.ts +56 -0
- package/src/migrations/0006_sinks.ts +28 -0
- package/src/provision/resolveAuditConfig.ts +60 -0
- package/src/purge/contribution.ts +39 -0
- package/src/reach.ts +454 -0
- package/src/recorder.ts +64 -42
- package/src/routePattern.ts +141 -0
- package/src/seeds/example.ts +13 -0
- package/src/ship/consumer.ts +169 -0
- package/src/ship/event.ts +86 -0
- package/src/ship/health.ts +92 -0
- package/src/ship/profiles.ts +99 -0
- package/src/ship/queue.ts +108 -0
- package/src/ship/secrets.ts +42 -0
- package/src/ship/shipper.ts +32 -0
- package/src/ship/sinks.ts +82 -0
- package/src/ship/state.ts +61 -0
- package/src/usage.ts +176 -0
- package/src/version.generated.ts +1 -1
- package/src/workflows/prune.ts +196 -0
- package/src/workflows/retryPolicy.ts +14 -0
- package/src/workflows/specs.ts +92 -0
- package/src/workflows/worker.ts +65 -0
- package/src/workflows/wrangler.jsonc +40 -0
|
@@ -0,0 +1,196 @@
|
|
|
1
|
+
// SPDX-FileCopyrightText: 2026 Pithy
|
|
2
|
+
// SPDX-License-Identifier: FSL-1.1-MIT
|
|
3
|
+
|
|
4
|
+
import type { D1Database, R2Bucket } from "@cloudflare/workers-types";
|
|
5
|
+
import { composedCapability } from "@pithy-sh/core/src/capability/composition";
|
|
6
|
+
import { InternalError } from "@pithy-sh/core/src/error/pithyError";
|
|
7
|
+
import { bindWorkflowContext, createWorkerLogger } from "@pithy-sh/core/src/logger/worker";
|
|
8
|
+
import { composedRetention } from "@pithy-sh/core/src/retention/composed";
|
|
9
|
+
import { legalHolds } from "@pithy-sh/core/src/retention/holds";
|
|
10
|
+
import { type EffectiveRetention, prunesAudit } from "@pithy-sh/core/src/retention/policy";
|
|
11
|
+
import {
|
|
12
|
+
classifiedSteps,
|
|
13
|
+
type TerminalErrorConstructor,
|
|
14
|
+
type WorkflowStepLike,
|
|
15
|
+
} from "@pithy-sh/core/src/workflow/faults";
|
|
16
|
+
import { type AuditCapability, isAuditCapability } from "../capability";
|
|
17
|
+
import { AUDIT_CHECKPOINT_BINDING } from "../chain/checkpoint";
|
|
18
|
+
import {
|
|
19
|
+
AUDIT_PRUNE_PAGE,
|
|
20
|
+
type ChainPrunePage,
|
|
21
|
+
chainTenants,
|
|
22
|
+
pruneChainPage,
|
|
23
|
+
pruneUnchainedPage,
|
|
24
|
+
type UnchainedPrunePage,
|
|
25
|
+
} from "../chain/prune";
|
|
26
|
+
import { auditDatabase } from "../data/tables";
|
|
27
|
+
import { auditWorkflowRetry } from "./retryPolicy";
|
|
28
|
+
import { AuditPruneParams } from "./specs";
|
|
29
|
+
|
|
30
|
+
/**
|
|
31
|
+
* **The retention prune's Workflow body**, run by a class the adopter's own Worker exports beside the
|
|
32
|
+
* `createEntrypoint` it already exports, because the prune reads the `retention` block that Worker resolved:
|
|
33
|
+
*
|
|
34
|
+
* // apps/api/src/index.ts
|
|
35
|
+
* import { WorkflowEntrypoint, type WorkflowEvent, type WorkflowStep } from "cloudflare:workers";
|
|
36
|
+
* import { NonRetryableError } from "cloudflare:workflows";
|
|
37
|
+
* import { runAuditPrune } from "@pithy-sh/audit/src/workflows/prune";
|
|
38
|
+
*
|
|
39
|
+
* export class AuditPruneWorkflow extends WorkflowEntrypoint<Record<string, unknown>> {
|
|
40
|
+
* override run(event: WorkflowEvent<unknown>, step: WorkflowStep) {
|
|
41
|
+
* return runAuditPrune(this.env, event, step, NonRetryableError);
|
|
42
|
+
* }
|
|
43
|
+
* }
|
|
44
|
+
*
|
|
45
|
+
* plus a `workflows` entry binding `AUDIT_PRUNE` to it and the daily cron.
|
|
46
|
+
*
|
|
47
|
+
* **A legal hold on a tenant's trail stops it.** Before every page of a chain the pass asks whether a hold stands on
|
|
48
|
+
* that tenant's trail, each ask its own step, so a hold placed while a pass runs stops it at its next page. The
|
|
49
|
+
* chain is left whole until the hold is released, and the next pass after that prunes it.
|
|
50
|
+
*/
|
|
51
|
+
|
|
52
|
+
/** What one pass reads and removes through. */
|
|
53
|
+
export interface AuditPruneRun {
|
|
54
|
+
/** Whether the policy prunes anything at all. Asked inside a step, so a replay serves the answer it got. */
|
|
55
|
+
prunes(): Promise<boolean>;
|
|
56
|
+
/** Whether a checkpoint bucket is bound. Without one nothing chained is pruned: no tombstone could be written. */
|
|
57
|
+
readonly checkpointed: boolean;
|
|
58
|
+
/** Every chain the trail holds. */
|
|
59
|
+
tenants(): Promise<(string | null)[]>;
|
|
60
|
+
/** Whether a legal hold stands on a tenant's trail. Throws when it cannot say. */
|
|
61
|
+
held(tenant: string | null): Promise<boolean>;
|
|
62
|
+
/** Prune one page of one chain. */
|
|
63
|
+
chainPage(tenant: string | null, afterSeq: number): Promise<ChainPrunePage>;
|
|
64
|
+
/** Prune one page of the rows that carry no chain. */
|
|
65
|
+
unchainedPage(afterId: number): Promise<UnchainedPrunePage>;
|
|
66
|
+
}
|
|
67
|
+
|
|
68
|
+
/** What one pass did. */
|
|
69
|
+
export interface AuditPruneOutcome {
|
|
70
|
+
/** How many chained events were removed, each run behind a tombstone. */
|
|
71
|
+
pruned: number;
|
|
72
|
+
/** How many runs were past their windows and left in place, because they did not verify. */
|
|
73
|
+
refused: number;
|
|
74
|
+
/** How many rows that carry no chain were removed. */
|
|
75
|
+
unchained: number;
|
|
76
|
+
/** How many chains a legal hold kept whole. */
|
|
77
|
+
held: number;
|
|
78
|
+
}
|
|
79
|
+
|
|
80
|
+
/** How many pages of one chain a pass takes, unless the trigger says otherwise. */
|
|
81
|
+
export const AUDIT_PRUNE_DEFAULT_PAGES = 20;
|
|
82
|
+
|
|
83
|
+
/**
|
|
84
|
+
* One pass: every chain, a page per step, each page behind its own hold check; then the unchained rows. A pass that
|
|
85
|
+
* dies part-way resumes after the step it finished, and a page repeated deletes nothing twice, because what it
|
|
86
|
+
* removed is gone and its tombstone is found rather than written again.
|
|
87
|
+
*/
|
|
88
|
+
export async function pruneAuditTrail(
|
|
89
|
+
run: AuditPruneRun,
|
|
90
|
+
step: WorkflowStepLike,
|
|
91
|
+
terminalError: TerminalErrorConstructor,
|
|
92
|
+
params: AuditPruneParams = {},
|
|
93
|
+
): Promise<AuditPruneOutcome> {
|
|
94
|
+
const outcome: AuditPruneOutcome = { pruned: 0, refused: 0, unchained: 0, held: 0 };
|
|
95
|
+
const own = classifiedSteps(step, auditWorkflowRetry, terminalError);
|
|
96
|
+
if (!(await own.do("policy", () => run.prunes()))) return outcome;
|
|
97
|
+
const pages = params.pages ?? AUDIT_PRUNE_DEFAULT_PAGES;
|
|
98
|
+
|
|
99
|
+
if (run.checkpointed) {
|
|
100
|
+
const tenants = await own.do("tenants", () => run.tenants());
|
|
101
|
+
for (const [index, tenant] of tenants.entries()) {
|
|
102
|
+
let afterSeq = 0;
|
|
103
|
+
for (let page = 1; page <= pages; page++) {
|
|
104
|
+
if (await own.do(`hold ${index + 1} ${page}`, () => run.held(tenant))) {
|
|
105
|
+
outcome.held++;
|
|
106
|
+
break;
|
|
107
|
+
}
|
|
108
|
+
const done = await own.do(`chain ${index + 1} ${page}`, () => run.chainPage(tenant, afterSeq));
|
|
109
|
+
outcome.pruned += done.pruned;
|
|
110
|
+
outcome.refused += done.refused;
|
|
111
|
+
if (done.next === null) break;
|
|
112
|
+
afterSeq = done.next;
|
|
113
|
+
}
|
|
114
|
+
}
|
|
115
|
+
}
|
|
116
|
+
|
|
117
|
+
let afterId = 0;
|
|
118
|
+
for (let page = 1; page <= pages; page++) {
|
|
119
|
+
const done = await own.do(`unchained ${page}`, () => run.unchainedPage(afterId));
|
|
120
|
+
outcome.unchained += done.deleted;
|
|
121
|
+
if (done.next === null) break;
|
|
122
|
+
afterId = done.next;
|
|
123
|
+
}
|
|
124
|
+
return outcome;
|
|
125
|
+
}
|
|
126
|
+
|
|
127
|
+
/** The pass over one env: its audit database, its checkpoint bucket, its holds, and the policy resolved at assembly. */
|
|
128
|
+
export function auditPruneRun(
|
|
129
|
+
env: Record<string, unknown>,
|
|
130
|
+
database: string,
|
|
131
|
+
policy: () => EffectiveRetention | null,
|
|
132
|
+
now: () => Date = () => new Date(),
|
|
133
|
+
): AuditPruneRun {
|
|
134
|
+
const binding = env[database];
|
|
135
|
+
if (typeof binding !== "object" || binding === null) {
|
|
136
|
+
throw new InternalError({
|
|
137
|
+
message: "The audit database is not bound, so the prune could not run.",
|
|
138
|
+
action: `Bind the ${database} D1 database to the Worker that runs the audit prune.`,
|
|
139
|
+
detail: `the audit prune found no ${database} binding on the env`,
|
|
140
|
+
});
|
|
141
|
+
}
|
|
142
|
+
const db = auditDatabase(binding as D1Database);
|
|
143
|
+
const found = env[AUDIT_CHECKPOINT_BINDING];
|
|
144
|
+
const bucket = typeof found === "object" && found !== null ? (found as R2Bucket) : null;
|
|
145
|
+
const holds = legalHolds(env);
|
|
146
|
+
const held = (tenant: string | null) => holds.held("audit", tenant);
|
|
147
|
+
return {
|
|
148
|
+
prunes: async () => {
|
|
149
|
+
const retention = policy();
|
|
150
|
+
return retention !== null && prunesAudit(retention);
|
|
151
|
+
},
|
|
152
|
+
checkpointed: bucket !== null,
|
|
153
|
+
tenants: () => chainTenants(db),
|
|
154
|
+
held,
|
|
155
|
+
chainPage: (tenant, afterSeq) => {
|
|
156
|
+
const retention = policy();
|
|
157
|
+
if (!bucket || !retention) return Promise.resolve({ pruned: 0, refused: 0, next: null });
|
|
158
|
+
return pruneChainPage(db, bucket, { tenant, retention, now: now(), afterSeq, limit: AUDIT_PRUNE_PAGE });
|
|
159
|
+
},
|
|
160
|
+
unchainedPage: (afterId) => {
|
|
161
|
+
const retention = policy();
|
|
162
|
+
if (!retention) return Promise.resolve({ deleted: 0, next: null });
|
|
163
|
+
return pruneUnchainedPage(db, { retention, now: now(), afterId, limit: AUDIT_PRUNE_PAGE, held });
|
|
164
|
+
},
|
|
165
|
+
};
|
|
166
|
+
}
|
|
167
|
+
|
|
168
|
+
/** What a Workflow event hands a body. */
|
|
169
|
+
interface PruneEvent {
|
|
170
|
+
readonly payload?: unknown;
|
|
171
|
+
readonly workflowName?: string;
|
|
172
|
+
readonly instanceId?: string;
|
|
173
|
+
}
|
|
174
|
+
|
|
175
|
+
/** The prune pass, over this Worker's composition and the `retention` block it resolved. */
|
|
176
|
+
export async function runAuditPrune(
|
|
177
|
+
env: Record<string, unknown>,
|
|
178
|
+
event: PruneEvent,
|
|
179
|
+
step: WorkflowStepLike,
|
|
180
|
+
terminalError: TerminalErrorConstructor,
|
|
181
|
+
): Promise<AuditPruneOutcome> {
|
|
182
|
+
const params = AuditPruneParams.parse(event.payload ?? {});
|
|
183
|
+
const audit = composedCapability<AuditCapability>("audit", isAuditCapability);
|
|
184
|
+
const log = bindWorkflowContext(createWorkerLogger({ name: "audit" }), {
|
|
185
|
+
workflow: event.workflowName ?? "audit:prune",
|
|
186
|
+
instance: event.instanceId ?? "unknown",
|
|
187
|
+
env: typeof env.ENVIRONMENT === "string" ? env.ENVIRONMENT : "unknown",
|
|
188
|
+
});
|
|
189
|
+
const run = auditPruneRun(env, audit.auditDatabase, composedRetention);
|
|
190
|
+
if (!run.checkpointed) {
|
|
191
|
+
log.warn("audit prune leaves the chains whole", { reason: `no ${AUDIT_CHECKPOINT_BINDING} binding` });
|
|
192
|
+
}
|
|
193
|
+
const outcome = await pruneAuditTrail(run, step, terminalError, params);
|
|
194
|
+
log.info("audit prune finished", { ...outcome });
|
|
195
|
+
return outcome;
|
|
196
|
+
}
|
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
// SPDX-FileCopyrightText: 2026 Pithy
|
|
2
|
+
// SPDX-License-Identifier: FSL-1.1-MIT
|
|
3
|
+
|
|
4
|
+
import type { WorkflowRetryPolicy } from "@pithy-sh/core/src/workflow/faults";
|
|
5
|
+
|
|
6
|
+
/**
|
|
7
|
+
* The checkpoint's retry policy: **no audit code is retried.** Core already re-drives a transient D1 fault, and an
|
|
8
|
+
* R2 write that failed is re-attempted by the next hour's run, which checkpoints the head as it then stands. A run
|
|
9
|
+
* that fails costs one hour of checkpoint coverage, never a checkpoint, because nothing is ever overwritten.
|
|
10
|
+
*/
|
|
11
|
+
export const auditWorkflowRetry: WorkflowRetryPolicy = {
|
|
12
|
+
capability: "audit",
|
|
13
|
+
retryable: {},
|
|
14
|
+
};
|
|
@@ -0,0 +1,92 @@
|
|
|
1
|
+
// SPDX-FileCopyrightText: 2026 Pithy
|
|
2
|
+
// SPDX-License-Identifier: FSL-1.1-MIT
|
|
3
|
+
|
|
4
|
+
import { workflowKey } from "@pithy-sh/core/src/workflow/naming";
|
|
5
|
+
import type { WorkflowRegistry, WorkflowSpecMap } from "@pithy-sh/core/src/workflow/spec";
|
|
6
|
+
import { z } from "zod";
|
|
7
|
+
|
|
8
|
+
/**
|
|
9
|
+
* The one durable job audit owns: the checkpoint (#822).
|
|
10
|
+
*
|
|
11
|
+
* Declared once, here. `capability.ts` derives its Workflow binding from this map, the host resolver derives the
|
|
12
|
+
* checkpoint host's `workflows` array and its cron from it, and a caller triggers it by the `audit/checkpoint` key.
|
|
13
|
+
*
|
|
14
|
+
* `optional: true` because the Workflow lives in the prebuilt checkpoint host, which exists only once the project
|
|
15
|
+
* deploys it. Until then an app composing audit records every event and verifies every link; only the checkpoints
|
|
16
|
+
* are missing, and the verify read says so.
|
|
17
|
+
*/
|
|
18
|
+
|
|
19
|
+
/** The capability name — the first segment of the dispatch key and of every deployed resource name. */
|
|
20
|
+
export const AUDIT_CAPABILITY = "audit";
|
|
21
|
+
|
|
22
|
+
/** The checkpoint's parameters: none. A cron passes none, and every run checkpoints every chain whose head moved. */
|
|
23
|
+
export const AuditCheckpointParams = z
|
|
24
|
+
.object({})
|
|
25
|
+
.describe("One checkpoint run. No parameters: a cron passes none, and a run covers every chain whose head moved.");
|
|
26
|
+
export type AuditCheckpointParams = z.infer<typeof AuditCheckpointParams>;
|
|
27
|
+
|
|
28
|
+
/**
|
|
29
|
+
* Audit's durable jobs, keyed by job name.
|
|
30
|
+
*
|
|
31
|
+
* **Hourly, on the hour's 20th minute.** The checkpoint bounds how much of a chain's tail can be rewritten unseen:
|
|
32
|
+
* everything after the last checkpoint is held only by its own links. An hour is that window. A run writes one
|
|
33
|
+
* small object per chain whose head moved and nothing for one that did not, so a quiet hour costs a listing. Offset
|
|
34
|
+
* from the other kit hosts' hourly work at `:15`.
|
|
35
|
+
*/
|
|
36
|
+
export const auditWorkflows = {
|
|
37
|
+
checkpoint: {
|
|
38
|
+
binding: "AUDIT_CHECKPOINT",
|
|
39
|
+
className: "AuditCheckpointWorkflow",
|
|
40
|
+
params: AuditCheckpointParams,
|
|
41
|
+
schedule: "20 * * * *",
|
|
42
|
+
optional: true,
|
|
43
|
+
},
|
|
44
|
+
} as const satisfies WorkflowSpecMap;
|
|
45
|
+
|
|
46
|
+
/** The binding the retention prune runs on, in the adopter's own Worker. */
|
|
47
|
+
export const AUDIT_PRUNE_BINDING = "AUDIT_PRUNE";
|
|
48
|
+
|
|
49
|
+
/** The prune's parameters. Every field optional, because a cron passes none. */
|
|
50
|
+
export const AuditPruneParams = z
|
|
51
|
+
.object({
|
|
52
|
+
pages: z
|
|
53
|
+
.number()
|
|
54
|
+
.int()
|
|
55
|
+
.min(1)
|
|
56
|
+
.max(100)
|
|
57
|
+
.optional()
|
|
58
|
+
.describe("How many pages of 500 rows one chain is pruned in this pass, at most. Defaults to 20."),
|
|
59
|
+
})
|
|
60
|
+
.describe("One retention prune pass over every chain. A cron passes no field.");
|
|
61
|
+
export type AuditPruneParams = z.infer<typeof AuditPruneParams>;
|
|
62
|
+
|
|
63
|
+
/**
|
|
64
|
+
* The job audit runs in the adopter's own Worker: the retention prune. Not in the checkpoint host, because the prune
|
|
65
|
+
* reads the Worker's `retention` block, which exists only where `createEntrypoint` resolved it. No `className`: the
|
|
66
|
+
* class is the adopter's, five lines calling `runAuditPrune` in `./prune.ts`.
|
|
67
|
+
*
|
|
68
|
+
* **Daily, at 02:00 UTC**, the trigger auth's and organization's purge passes share, so a Worker composing all three
|
|
69
|
+
* spends one cron. Windows are counted in days, so a daily pass prunes nothing later than an hourly one would.
|
|
70
|
+
*
|
|
71
|
+
* `optional: true`, so a Worker composing audit boots before the adopter has bound it. Until then nothing is pruned
|
|
72
|
+
* and the trail is kept, which is what a Worker with no `retention` block does anyway.
|
|
73
|
+
*/
|
|
74
|
+
export const auditAppWorkflows = {
|
|
75
|
+
prune: {
|
|
76
|
+
binding: AUDIT_PRUNE_BINDING,
|
|
77
|
+
params: AuditPruneParams,
|
|
78
|
+
schedule: "0 2 * * *",
|
|
79
|
+
optional: true,
|
|
80
|
+
},
|
|
81
|
+
} as const satisfies WorkflowSpecMap;
|
|
82
|
+
|
|
83
|
+
/**
|
|
84
|
+
* The checkpoint host's jobs as a dispatch registry, keyed `audit/<job>`, with core's key format. The prune is not
|
|
85
|
+
* in it: the host resolver derives the host's Workflows from this registry, and the prune is hosted elsewhere.
|
|
86
|
+
*/
|
|
87
|
+
export const auditWorkflowRegistry: WorkflowRegistry = Object.fromEntries(
|
|
88
|
+
Object.entries(auditWorkflows).map(([job, spec]) => {
|
|
89
|
+
const key = workflowKey(AUDIT_CAPABILITY, job);
|
|
90
|
+
return [key, { key, capability: AUDIT_CAPABILITY, job, spec }];
|
|
91
|
+
}),
|
|
92
|
+
);
|
|
@@ -0,0 +1,65 @@
|
|
|
1
|
+
// SPDX-FileCopyrightText: 2026 Pithy
|
|
2
|
+
// SPDX-License-Identifier: FSL-1.1-MIT
|
|
3
|
+
|
|
4
|
+
import { WorkflowEntrypoint, type WorkflowEvent, type WorkflowStep } from "cloudflare:workers";
|
|
5
|
+
import { NonRetryableError } from "cloudflare:workflows";
|
|
6
|
+
import type { D1Database, R2Bucket } from "@cloudflare/workers-types";
|
|
7
|
+
import { bindWorkflowContext, createWorkerLogger } from "@pithy-sh/core/src/logger/worker";
|
|
8
|
+
import { triggerWorkflow } from "@pithy-sh/core/src/workflow/dispatch";
|
|
9
|
+
import { classifiedSteps } from "@pithy-sh/core/src/workflow/faults";
|
|
10
|
+
import { workflowHostEntry } from "@pithy-sh/core/src/workflow/hostEntry";
|
|
11
|
+
import { workflowKey } from "@pithy-sh/core/src/workflow/naming";
|
|
12
|
+
import { writeCheckpoints } from "../chain/checkpoint";
|
|
13
|
+
import { auditDatabase } from "../data/tables";
|
|
14
|
+
import { auditWorkflowRetry } from "./retryPolicy";
|
|
15
|
+
import { AUDIT_CAPABILITY, AuditCheckpointParams, auditWorkflowRegistry } from "./specs";
|
|
16
|
+
|
|
17
|
+
/**
|
|
18
|
+
* **The prebuilt checkpoint host (#822).** It hosts the one checkpoint Workflow and fires it from its cron. The app
|
|
19
|
+
* Worker records the events; this one writes each chain's head and count to the checkpoint bucket, where nothing in
|
|
20
|
+
* the app's request path can reach to rewrite it.
|
|
21
|
+
*/
|
|
22
|
+
|
|
23
|
+
/** What the host is bound to. */
|
|
24
|
+
export interface AuditWorkerEnv {
|
|
25
|
+
/** The audit database — the app's, by default, or whichever the adopter's `audit({ database })` names. */
|
|
26
|
+
DB: D1Database;
|
|
27
|
+
/** The checkpoint bucket. Under an object-lock rule, nothing here can replace or delete what it writes. */
|
|
28
|
+
AUDIT_CHECKPOINTS: R2Bucket;
|
|
29
|
+
/** The environment served, stamped at deploy. */
|
|
30
|
+
ENVIRONMENT?: string;
|
|
31
|
+
}
|
|
32
|
+
|
|
33
|
+
export class AuditCheckpointWorkflow extends WorkflowEntrypoint<AuditWorkerEnv, AuditCheckpointParams> {
|
|
34
|
+
override async run(event: WorkflowEvent<AuditCheckpointParams>, step: WorkflowStep): Promise<void> {
|
|
35
|
+
AuditCheckpointParams.parse(event.payload ?? {});
|
|
36
|
+
const log = bindWorkflowContext(createWorkerLogger({ name: AUDIT_CAPABILITY }), {
|
|
37
|
+
workflow: event.workflowName,
|
|
38
|
+
instance: event.instanceId,
|
|
39
|
+
env: this.env.ENVIRONMENT ?? "unknown",
|
|
40
|
+
});
|
|
41
|
+
// One step. A retry re-runs the whole pass, which is safe because a pass is idempotent: a head already
|
|
42
|
+
// checkpointed is a key that exists, and the write never replaces one.
|
|
43
|
+
const run = await classifiedSteps(step, auditWorkflowRetry, NonRetryableError).do("checkpoint", async () =>
|
|
44
|
+
writeCheckpoints(auditDatabase(this.env.DB), this.env.AUDIT_CHECKPOINTS, new Date()),
|
|
45
|
+
);
|
|
46
|
+
log.info("audit checkpoint written", { written: run.written, unchanged: run.unchanged });
|
|
47
|
+
}
|
|
48
|
+
}
|
|
49
|
+
|
|
50
|
+
export default {
|
|
51
|
+
...workflowHostEntry(AUDIT_CAPABILITY),
|
|
52
|
+
/**
|
|
53
|
+
* Cron entry: start one checkpoint run per fire, through the same dispatcher an on-demand run uses, so a host
|
|
54
|
+
* deployed with its binding absent logs a skip rather than throwing inside a cron nobody is watching.
|
|
55
|
+
*/
|
|
56
|
+
async scheduled(_controller: unknown, env: AuditWorkerEnv): Promise<void> {
|
|
57
|
+
await triggerWorkflow(
|
|
58
|
+
env as unknown as Record<string, unknown>,
|
|
59
|
+
auditWorkflowRegistry,
|
|
60
|
+
workflowKey(AUDIT_CAPABILITY, "checkpoint"),
|
|
61
|
+
{},
|
|
62
|
+
createWorkerLogger({ name: AUDIT_CAPABILITY }),
|
|
63
|
+
);
|
|
64
|
+
},
|
|
65
|
+
};
|
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
{
|
|
2
|
+
// The prebuilt audit checkpoint worker (#822). Like every kit host, this is a TEMPLATE, not a wrangler
|
|
3
|
+
// env-stanza file: staging and prod are separate workers. `pithy deploy` resolves it into one complete config
|
|
4
|
+
// per environment — filling the `<...>` placeholders — and deploys each with `wrangler deploy --config <resolved>`.
|
|
5
|
+
// The adopter authors none of it.
|
|
6
|
+
//
|
|
7
|
+
// It hosts the one checkpoint Workflow. The app worker records the events; this one writes each tenant chain's
|
|
8
|
+
// head and count to the checkpoint bucket on a schedule.
|
|
9
|
+
// Resolved per project and env → <project>-staging-audit / <project>-prod-audit.
|
|
10
|
+
"name": "pithy-audit",
|
|
11
|
+
"main": "./worker.ts",
|
|
12
|
+
// The compatibility date every Worker in this repository runs on. Stated once in the repository
|
|
13
|
+
// root's `compatibility.ts` and copied here because JSONC cannot import it —
|
|
14
|
+
// `cli/src/ci/compatibilityDates.test.ts` fails on any Worker older than it.
|
|
15
|
+
"compatibility_date": "2026-06-01",
|
|
16
|
+
"compatibility_flags": ["nodejs_compat"],
|
|
17
|
+
|
|
18
|
+
// No public URL. Every audit route lives in the app worker; this one is reached only by its cron.
|
|
19
|
+
"workers_dev": false,
|
|
20
|
+
|
|
21
|
+
// The audit database — the app's, or whichever `audit({ database })` names. Read only: the host writes nothing
|
|
22
|
+
// here, and holds no credential at all.
|
|
23
|
+
"d1_databases": [{ "binding": "DB", "database_name": "pithy-app", "database_id": "<filled-at-provision>" }],
|
|
24
|
+
|
|
25
|
+
// The checkpoint bucket, the same one the app worker reads checkpoints back from. Put an object-lock rule on it;
|
|
26
|
+
// `pithy doctor` says whether one is in force.
|
|
27
|
+
"r2_buckets": [{ "binding": "AUDIT_CHECKPOINTS", "bucket_name": "<filled-at-provision>" }],
|
|
28
|
+
|
|
29
|
+
// The checkpoint Workflow. `class_name` matches the exported WorkflowEntrypoint subclass.
|
|
30
|
+
"workflows": [
|
|
31
|
+
{ "binding": "AUDIT_CHECKPOINT", "name": "pithy-audit-checkpoint", "class_name": "AuditCheckpointWorkflow" }
|
|
32
|
+
],
|
|
33
|
+
|
|
34
|
+
// Hourly. Also rewritten at deploy from the spec's `schedule`.
|
|
35
|
+
"triggers": { "crons": ["20 * * * *"] },
|
|
36
|
+
|
|
37
|
+
"vars": {
|
|
38
|
+
"ENVIRONMENT": "<filled-at-provision>"
|
|
39
|
+
}
|
|
40
|
+
}
|