Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
36 changes: 36 additions & 0 deletions docs/audit-listeners.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,36 @@
# Audit listeners

Audit consumers can subscribe independently with `addAuditListener(listener)` and
unsubscribe with `removeAuditListener(listener)`, exported from
`src/functions/audit.ts`. Keep the same function reference for removal. Registering
the same function twice or removing it more than once is harmless.

`setAuditRecordedListener(listener)` remains a separate, replaceable legacy slot
used by the viewer. Setting that slot to `null` does not remove independent
subscribers. Removing an independent subscription does not clear the legacy slot,
even when both contain the same function. A function registered through both
mechanisms is called once for each recorded entry.

`recordAudit()` invokes listeners after its monthly entry write and month-index
update complete. It calls the legacy listener first, followed by independent
listeners in registration order. Removing and registering a listener again moves
it to the end of that order.

Dispatch uses a snapshot taken after persistence completes. A callback added
during dispatch starts with the next entry; a callback removed during dispatch
still receives the current entry. Legacy replacement or cleanup during dispatch
also takes effect on the next entry.

The callback type keeps TypeScript's `void` convention, so existing value-returning
handlers such as `(entry) => rows.push(entry)` remain accepted. Return values are
not used, and returned promises have rejection handlers attached. A synchronous
exception or rejected promise in one callback does not prevent the other callbacks
from running or make an already written audit entry fail. Promise completion is
not awaited, so async work can overlap across entries. Callbacks should avoid
blocking synchronous work. Failure of a required entry or month-index operation
still rejects `recordAudit()` before listener delivery; `safeAudit()` keeps its
existing logging boundary.

Delivery is best effort within the current process. There is no retry queue,
cursor, or durable delivery guarantee. This listener API does not add file/stdout
sinks, backfill exports, or an export payload/deletion policy.
26 changes: 21 additions & 5 deletions src/functions/audit.ts
Original file line number Diff line number Diff line change
Expand Up @@ -153,12 +153,23 @@ export async function listAuditMonthsDesc(kv: StateKV): Promise<string[]> {
return [...months].sort().reverse();
}

let auditRecordedListener: ((entry: AuditEntry) => void) | null = null;
export type AuditListener = (entry: AuditEntry) => void;

export function setAuditRecordedListener(listener: ((entry: AuditEntry) => void) | null): void {
let auditRecordedListener: AuditListener | null = null;
const auditListeners = new Set<AuditListener>();

export function setAuditRecordedListener(listener: AuditListener | null): void {
auditRecordedListener = listener;
}

export function addAuditListener(listener: AuditListener): void {
auditListeners.add(listener);
}

export function removeAuditListener(listener: AuditListener): void {
auditListeners.delete(listener);
}

export async function recordAudit(
kv: StateKV,
operation: AuditEntry["operation"],
Expand All @@ -181,9 +192,14 @@ export async function recordAudit(
const month = auditMonthOf(entry.timestamp);
await kv.set(KV.auditMonth(month), entry.id, entry);
await markAuditMonth(kv, month);
try {
auditRecordedListener?.(entry);
} catch {}
const listeners = new Set(auditRecordedListener
? [auditRecordedListener, ...auditListeners]
: auditListeners);
for (const listener of listeners) {
try {
void Promise.resolve(listener(entry)).catch(() => {});
} catch {}
}
return entry;
}

Expand Down
Loading