vouchington-tooling 3.0.1 → 3.1.0
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/dist/agent-blackboard/feedback-delivery.d.mts +11 -4
- package/dist/agent-blackboard/feedback-delivery.mjs +22 -5
- package/dist/agent-blackboard/feedback-failure-parse.d.mts +3 -0
- package/dist/agent-blackboard/feedback-failure-parse.mjs +39 -0
- package/dist/agent-blackboard/feedback-failure.d.mts +32 -0
- package/dist/agent-blackboard/feedback-failure.mjs +48 -0
- package/dist/agent-blackboard/feedback-online-error.d.mts +5 -1
- package/dist/agent-blackboard/feedback-online-error.mjs +8 -1
- package/dist/agent-blackboard/feedback-online.mjs +3 -2
- package/dist/agent-blackboard/feedback-outbox-failure.d.mts +16 -0
- package/dist/agent-blackboard/feedback-outbox-failure.mjs +41 -0
- package/dist/agent-blackboard/feedback-outbox-read.d.mts +11 -0
- package/dist/agent-blackboard/feedback-outbox-read.mjs +33 -0
- package/dist/agent-blackboard/feedback-outbox-rejected.d.mts +14 -5
- package/dist/agent-blackboard/feedback-outbox-rejected.mjs +45 -19
- package/dist/agent-blackboard/feedback-outbox-write.d.mts +2 -0
- package/dist/agent-blackboard/feedback-outbox-write.mjs +26 -0
- package/dist/agent-blackboard/feedback-outbox.d.mts +2 -7
- package/dist/agent-blackboard/feedback-outbox.mjs +7 -52
- package/dist/agent-blackboard/feedback-types.d.mts +1 -1
- package/dist/agent-blackboard/index.d.mts +2 -0
- package/dist/agent-blackboard/index.mjs +2 -0
- package/dist/host-lock/with-host-lock-diagnostics.test-helpers.d.mts +10 -0
- package/dist/host-lock/with-host-lock-diagnostics.test-helpers.mjs +27 -0
- package/dist/host-lock/with-host-lock.test-helpers.d.mts +0 -10
- package/dist/host-lock/with-host-lock.test-helpers.mjs +7 -28
- package/dist/mcp-server/dispatch.mjs +3 -1
- package/dist/mcp-server/handlers-outbox.d.mts +1 -0
- package/dist/mcp-server/handlers-outbox.mjs +31 -2
- package/dist/mcp-server/tools-outbox.d.mts +2 -0
- package/dist/mcp-server/tools-outbox.mjs +31 -0
- package/dist/mcp-server/tools.mjs +2 -8
- package/docs/mcp-server.md +28 -15
- package/package.json +1 -1
- package/scripts/__pycache__/run_bounded_process.cpython-314.pyc +0 -0
- package/skills/blackboard/SKILL.md +10 -1
- package/skills/manifest.json +9 -9
- package/skills/retrospective-distill/SKILL.md +3 -1
- package/skills/triage-loop/SKILL.md +71 -21
- package/skills/triage-sweep/SKILL.md +32 -11
|
@@ -1,10 +1,18 @@
|
|
|
1
1
|
import type { BlackboardClientDependencies } from './client.mts';
|
|
2
|
+
import { type FeedbackCause } from './feedback-failure.mts';
|
|
3
|
+
import { type FeedbackFailureReport } from './feedback-outbox-failure.mts';
|
|
2
4
|
import type { FeedbackDeliveryOptions, FeedbackDeliveryResult, FeedbackDiagnostic, FeedbackOnlineOptions } from './feedback-types.mts';
|
|
3
5
|
export { FeedbackDeliveryError } from './feedback-online-error.mts';
|
|
4
6
|
export declare function writeFeedback(input: FeedbackDeliveryOptions): Promise<FeedbackDeliveryResult>;
|
|
5
7
|
export declare function verifyFreshFeedback(input: FeedbackOnlineOptions): Promise<Extract<FeedbackDeliveryResult, {
|
|
6
8
|
status: 'delivered';
|
|
7
9
|
}>>;
|
|
10
|
+
type FeedbackRejected = {
|
|
11
|
+
sourceEventId: string;
|
|
12
|
+
diagnostic: FeedbackDiagnostic;
|
|
13
|
+
} & FeedbackCause & {
|
|
14
|
+
attempts?: number;
|
|
15
|
+
};
|
|
8
16
|
export declare function flushFeedbackOutbox(input: {
|
|
9
17
|
directory: string;
|
|
10
18
|
env?: NodeJS.ProcessEnv;
|
|
@@ -14,9 +22,8 @@ export declare function flushFeedbackOutbox(input: {
|
|
|
14
22
|
pendingCount: number;
|
|
15
23
|
deliveredCount: number;
|
|
16
24
|
diagnostic?: FeedbackDiagnostic;
|
|
17
|
-
rejected?:
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
}>;
|
|
25
|
+
rejected?: FeedbackRejected[];
|
|
26
|
+
/** Records still pending that failed this flush, with their non-secret cause and attempt count. */
|
|
27
|
+
failures?: FeedbackFailureReport[];
|
|
21
28
|
cleanupDiagnostic?: 'outbox-cleanup-failed';
|
|
22
29
|
}>;
|
|
@@ -1,7 +1,9 @@
|
|
|
1
1
|
import { createFeedbackEnvelope, validateFeedbackEnvelope } from "./feedback-codec.mjs";
|
|
2
2
|
import { validateFeedbackIdentity } from "./feedback-identity.mjs";
|
|
3
3
|
import { deliverFeedbackOnline } from "./feedback-online.mjs";
|
|
4
|
-
import { feedbackDiagnostic } from "./feedback-online-error.mjs";
|
|
4
|
+
import { feedbackDiagnostic, feedbackFailure } from "./feedback-online-error.mjs";
|
|
5
|
+
import { isTransientCause } from "./feedback-failure.mjs";
|
|
6
|
+
import { recordFeedbackFailure } from "./feedback-outbox-failure.mjs";
|
|
5
7
|
import { feedbackOutboxStatus, listFeedbackOutbox, persistFeedbackOutbox, removeFeedbackOutbox, } from "./feedback-outbox.mjs";
|
|
6
8
|
import { rejectFeedbackOutbox } from "./feedback-outbox-rejected.mjs";
|
|
7
9
|
export { FeedbackDeliveryError } from "./feedback-online-error.mjs";
|
|
@@ -33,7 +35,10 @@ export async function writeFeedback(input) {
|
|
|
33
35
|
catch (error) {
|
|
34
36
|
const diagnostic = feedbackDiagnostic(error);
|
|
35
37
|
if (PERMANENT.includes(diagnostic)) {
|
|
36
|
-
rejectFeedbackOutbox(input.outboxDirectory, record
|
|
38
|
+
rejectFeedbackOutbox(input.outboxDirectory, record, {
|
|
39
|
+
diagnostic,
|
|
40
|
+
...feedbackFailure(error),
|
|
41
|
+
});
|
|
37
42
|
throw error;
|
|
38
43
|
}
|
|
39
44
|
return {
|
|
@@ -55,6 +60,7 @@ export async function flushFeedbackOutbox(input) {
|
|
|
55
60
|
let diagnostic;
|
|
56
61
|
let cleanupDiagnostic;
|
|
57
62
|
const rejected = [];
|
|
63
|
+
const failures = [];
|
|
58
64
|
for (const record of listFeedbackOutbox(input.directory)) {
|
|
59
65
|
try {
|
|
60
66
|
await deliverFeedbackOnline({
|
|
@@ -68,13 +74,23 @@ export async function flushFeedbackOutbox(input) {
|
|
|
68
74
|
}
|
|
69
75
|
catch (error) {
|
|
70
76
|
const current = feedbackDiagnostic(error);
|
|
77
|
+
const cause = feedbackFailure(error);
|
|
78
|
+
const sourceEventId = record.envelope.sourceEventId;
|
|
71
79
|
if (PERMANENT.includes(current)) {
|
|
72
|
-
rejectFeedbackOutbox(input.directory, record);
|
|
73
|
-
rejected.push({ sourceEventId
|
|
80
|
+
rejectFeedbackOutbox(input.directory, record, { diagnostic: current, ...cause });
|
|
81
|
+
rejected.push({ sourceEventId, diagnostic: current, ...cause });
|
|
82
|
+
continue;
|
|
83
|
+
}
|
|
84
|
+
const { failure, quarantined } = recordFeedbackFailure(input.directory, record, cause);
|
|
85
|
+
if (quarantined) {
|
|
86
|
+
rejected.push({ sourceEventId, diagnostic: 'delivery-quarantined', ...failure });
|
|
74
87
|
continue;
|
|
75
88
|
}
|
|
89
|
+
failures.push({ sourceEventId, ...failure });
|
|
76
90
|
diagnostic = current;
|
|
77
|
-
|
|
91
|
+
// A record-specific failure must not starve the records behind it; an outage ends the flush.
|
|
92
|
+
if (isTransientCause(cause.cause))
|
|
93
|
+
break;
|
|
78
94
|
}
|
|
79
95
|
}
|
|
80
96
|
return {
|
|
@@ -83,6 +99,7 @@ export async function flushFeedbackOutbox(input) {
|
|
|
83
99
|
...(cleanupDiagnostic === undefined ? {} : { cleanupDiagnostic }),
|
|
84
100
|
...(diagnostic === undefined ? {} : { diagnostic }),
|
|
85
101
|
...(rejected.length === 0 ? {} : { rejected }),
|
|
102
|
+
...(failures.length === 0 ? {} : { failures }),
|
|
86
103
|
};
|
|
87
104
|
}
|
|
88
105
|
function prepareEnvelope(input) {
|
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
import { isObject } from "./snapshot-partition-guards.mjs";
|
|
2
|
+
import { CAUSE, CODE, MAX_ATTEMPTS, } from "./feedback-failure.mjs";
|
|
3
|
+
// Parsers for the failure and rejection metadata persisted in outbox records.
|
|
4
|
+
function integer(value, min, max) {
|
|
5
|
+
return typeof value === 'number' && Number.isInteger(value) && value >= min && value <= max
|
|
6
|
+
? value
|
|
7
|
+
: undefined;
|
|
8
|
+
}
|
|
9
|
+
function parseCause(value) {
|
|
10
|
+
const { cause, httpStatus, code } = value;
|
|
11
|
+
const status = httpStatus === undefined ? undefined : integer(httpStatus, 100, 599);
|
|
12
|
+
if ((cause !== undefined && !(typeof cause === 'string' && CAUSE.test(cause))) ||
|
|
13
|
+
(code !== undefined && !(typeof code === 'string' && CODE.test(code))) ||
|
|
14
|
+
(httpStatus !== undefined && status === undefined))
|
|
15
|
+
throw new Error('invalid feedback outbox failure');
|
|
16
|
+
return {
|
|
17
|
+
...(typeof cause === 'string' ? { cause } : {}),
|
|
18
|
+
...(status === undefined ? {} : { httpStatus: status }),
|
|
19
|
+
...(typeof code === 'string' ? { code } : {}),
|
|
20
|
+
};
|
|
21
|
+
}
|
|
22
|
+
export function parseFailure(value) {
|
|
23
|
+
const attempts = isObject(value) ? integer(value.attempts, 1, MAX_ATTEMPTS) : undefined;
|
|
24
|
+
if (!isObject(value) || attempts === undefined || typeof value.cause !== 'string')
|
|
25
|
+
throw new Error('invalid feedback outbox failure');
|
|
26
|
+
return { ...parseCause(value), attempts };
|
|
27
|
+
}
|
|
28
|
+
export function parseRejection(value) {
|
|
29
|
+
if (!isObject(value) || typeof value.diagnostic !== 'string' || !CAUSE.test(value.diagnostic))
|
|
30
|
+
throw new Error('invalid feedback outbox rejection');
|
|
31
|
+
const attempts = value.attempts === undefined ? undefined : integer(value.attempts, 1, MAX_ATTEMPTS);
|
|
32
|
+
if (value.attempts !== undefined && attempts === undefined)
|
|
33
|
+
throw new Error('invalid feedback outbox rejection');
|
|
34
|
+
return {
|
|
35
|
+
...parseCause(value),
|
|
36
|
+
diagnostic: value.diagnostic,
|
|
37
|
+
...(attempts === undefined ? {} : { attempts }),
|
|
38
|
+
};
|
|
39
|
+
}
|
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Why one delivery attempt failed, in a closed vocabulary with no messages, URLs, headers, or bodies
|
|
3
|
+
* so it can never echo a secret: `network`, `timeout`, `http-5xx`, `http-4xx`, `http-401`,
|
|
4
|
+
* `http-403`, `http-408`, `http-429`, `missing-env:<NAME>`, `invalid-url`, `client-unavailable`,
|
|
5
|
+
* `error:<ClassName>`, or the diagnostic itself for conflicts and archived sessions.
|
|
6
|
+
*/
|
|
7
|
+
export type FeedbackCause = {
|
|
8
|
+
cause: string;
|
|
9
|
+
httpStatus?: number;
|
|
10
|
+
code?: string;
|
|
11
|
+
};
|
|
12
|
+
/** A pending record's persisted failure; `attempts` counts consecutive flushes with this cause. */
|
|
13
|
+
export type FeedbackFailure = FeedbackCause & {
|
|
14
|
+
attempts: number;
|
|
15
|
+
};
|
|
16
|
+
/** What a `.rejected` record keeps about why it was refused. */
|
|
17
|
+
export type FeedbackRejection = Partial<FeedbackCause> & {
|
|
18
|
+
diagnostic: string;
|
|
19
|
+
attempts?: number;
|
|
20
|
+
};
|
|
21
|
+
export declare const QUARANTINE_ATTEMPTS = 5;
|
|
22
|
+
/** The highest persisted attempt count; later attempts saturate here. */
|
|
23
|
+
export declare const MAX_ATTEMPTS = 1000;
|
|
24
|
+
export declare const CAUSE: RegExp;
|
|
25
|
+
export declare const CODE: RegExp;
|
|
26
|
+
/** Transient or environmental causes never quarantine; only a record-specific cause can. */
|
|
27
|
+
export declare function isTransientCause(cause: string): boolean;
|
|
28
|
+
/** A missing connection variable is named; any other configuration fault is an invalid URL. */
|
|
29
|
+
export declare function configurationCause(env?: NodeJS.ProcessEnv): FeedbackCause;
|
|
30
|
+
export declare function statusCause(status: number): FeedbackCause;
|
|
31
|
+
/** Classifies a raw delivery error. Only the status, the error name, and a system code are read. */
|
|
32
|
+
export declare function causeOfError(error: unknown): FeedbackCause;
|
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
import { isObject } from "./snapshot-partition-guards.mjs";
|
|
2
|
+
export const QUARANTINE_ATTEMPTS = 5;
|
|
3
|
+
/** The highest persisted attempt count; later attempts saturate here. */
|
|
4
|
+
export const MAX_ATTEMPTS = 1000;
|
|
5
|
+
export const CAUSE = /^[A-Za-z0-9_:.-]{1,80}$/;
|
|
6
|
+
export const CODE = /^[A-Z][A-Z0-9_]{1,40}$/;
|
|
7
|
+
// Healing without touching the record: outages, throttling, credentials, and the environment.
|
|
8
|
+
const HEALS = /^(network|timeout|http-5xx|http-(401|403|408|429)|missing-env:.*|invalid-url)$/;
|
|
9
|
+
const HEALS_TOO = /^(client-unavailable|readback-unconfirmed|delivery-timeout)$/;
|
|
10
|
+
/** Transient or environmental causes never quarantine; only a record-specific cause can. */
|
|
11
|
+
export function isTransientCause(cause) {
|
|
12
|
+
return HEALS.test(cause) || HEALS_TOO.test(cause);
|
|
13
|
+
}
|
|
14
|
+
/** A missing connection variable is named; any other configuration fault is an invalid URL. */
|
|
15
|
+
export function configurationCause(env = process.env) {
|
|
16
|
+
const name = ['AGENT_BLACKBOARD_URL', 'AGENT_BLACKBOARD_TOKEN'].find((key) => !env[key]);
|
|
17
|
+
return { cause: name === undefined ? 'invalid-url' : `missing-env:${name}` };
|
|
18
|
+
}
|
|
19
|
+
export function statusCause(status) {
|
|
20
|
+
if (status >= 500)
|
|
21
|
+
return { cause: 'http-5xx', httpStatus: status };
|
|
22
|
+
const exact = [401, 403, 408, 429].includes(status);
|
|
23
|
+
return {
|
|
24
|
+
cause: exact ? `http-${status}` : status >= 400 ? 'http-4xx' : 'http-other',
|
|
25
|
+
httpStatus: status,
|
|
26
|
+
};
|
|
27
|
+
}
|
|
28
|
+
/** Classifies a raw delivery error. Only the status, the error name, and a system code are read. */
|
|
29
|
+
export function causeOfError(error) {
|
|
30
|
+
if (!isObject(error))
|
|
31
|
+
return { cause: 'error:unknown' };
|
|
32
|
+
const status = error.status ?? error.statusCode;
|
|
33
|
+
if (typeof status === 'number' && Number.isInteger(status) && status >= 100 && status <= 599)
|
|
34
|
+
return statusCause(status);
|
|
35
|
+
const nested = isObject(error.cause) ? error.cause : undefined;
|
|
36
|
+
const raw = error.code ?? nested?.code;
|
|
37
|
+
const code = typeof raw === 'string' && CODE.test(raw) ? raw : undefined;
|
|
38
|
+
const { name, message } = error;
|
|
39
|
+
if (code !== undefined)
|
|
40
|
+
return { cause: 'network', code };
|
|
41
|
+
if (name === 'TypeError' && message === 'fetch failed')
|
|
42
|
+
return { cause: 'network' };
|
|
43
|
+
return {
|
|
44
|
+
cause: typeof name === 'string' && /^[A-Za-z0-9]{1,40}$/.test(name)
|
|
45
|
+
? `error:${name}`
|
|
46
|
+
: 'error:unknown',
|
|
47
|
+
};
|
|
48
|
+
}
|
|
@@ -1,7 +1,11 @@
|
|
|
1
|
+
import { type FeedbackCause } from './feedback-failure.mts';
|
|
1
2
|
import type { FeedbackDiagnostic } from './feedback-types.mts';
|
|
2
3
|
export declare class FeedbackDeliveryError extends Error {
|
|
3
4
|
readonly status = "blocked";
|
|
4
5
|
readonly diagnostic: FeedbackDiagnostic;
|
|
5
|
-
|
|
6
|
+
/** The non-secret cause; it defaults to the diagnostic itself. */
|
|
7
|
+
readonly failure: FeedbackCause;
|
|
8
|
+
constructor(diagnostic: FeedbackDiagnostic, detail?: string, failure?: FeedbackCause);
|
|
6
9
|
}
|
|
7
10
|
export declare function feedbackDiagnostic(error: unknown): FeedbackDiagnostic;
|
|
11
|
+
export declare function feedbackFailure(error: unknown): FeedbackCause;
|
|
@@ -1,11 +1,15 @@
|
|
|
1
1
|
import { isObject } from "./snapshot-partition-guards.mjs";
|
|
2
|
+
import { causeOfError } from "./feedback-failure.mjs";
|
|
2
3
|
export class FeedbackDeliveryError extends Error {
|
|
3
4
|
status = 'blocked';
|
|
4
5
|
diagnostic;
|
|
5
|
-
|
|
6
|
+
/** The non-secret cause; it defaults to the diagnostic itself. */
|
|
7
|
+
failure;
|
|
8
|
+
constructor(diagnostic, detail, failure) {
|
|
6
9
|
super(`Blackboard feedback blocked: ${diagnostic}${detail === undefined ? '' : `: ${detail}`}`);
|
|
7
10
|
this.name = 'FeedbackDeliveryError';
|
|
8
11
|
this.diagnostic = diagnostic;
|
|
12
|
+
this.failure = failure ?? { cause: diagnostic };
|
|
9
13
|
}
|
|
10
14
|
}
|
|
11
15
|
export function feedbackDiagnostic(error) {
|
|
@@ -21,3 +25,6 @@ export function feedbackDiagnostic(error) {
|
|
|
21
25
|
return 'identity-conflict';
|
|
22
26
|
return 'blackboard-unavailable';
|
|
23
27
|
}
|
|
28
|
+
export function feedbackFailure(error) {
|
|
29
|
+
return error instanceof FeedbackDeliveryError ? error.failure : causeOfError(error);
|
|
30
|
+
}
|
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
import { feedbackDeadline } from "./feedback-deadline.mjs";
|
|
2
2
|
import { FeedbackDeliveryError, feedbackDiagnostic } from "./feedback-online-error.mjs";
|
|
3
|
+
import { causeOfError, configurationCause } from "./feedback-failure.mjs";
|
|
3
4
|
import { canonicalFeedback, canonicalFeedbackEvent } from "./feedback-canonical.mjs";
|
|
4
5
|
import { loadClient, resolveBlackboardConnection } from "./client.mjs";
|
|
5
6
|
import { normalizeRepositories, validateFeedbackEnvelope } from "./feedback-codec.mjs";
|
|
@@ -93,7 +94,7 @@ export async function deliverFeedbackOnline(input, fresh = false) {
|
|
|
93
94
|
throw new Error('invalid connection URL');
|
|
94
95
|
}
|
|
95
96
|
catch {
|
|
96
|
-
throw new FeedbackDeliveryError('configuration-invalid');
|
|
97
|
+
throw new FeedbackDeliveryError('configuration-invalid', undefined, configurationCause(input.env));
|
|
97
98
|
}
|
|
98
99
|
let client;
|
|
99
100
|
try {
|
|
@@ -157,7 +158,7 @@ export async function deliverFeedbackOnline(input, fresh = false) {
|
|
|
157
158
|
catch (error) {
|
|
158
159
|
throw error instanceof FeedbackDeliveryError
|
|
159
160
|
? error
|
|
160
|
-
: new FeedbackDeliveryError(feedbackDiagnostic(error));
|
|
161
|
+
: new FeedbackDeliveryError(feedbackDiagnostic(error), undefined, causeOfError(error));
|
|
161
162
|
}
|
|
162
163
|
}, input.timeoutMs);
|
|
163
164
|
}
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
import { type FeedbackCause, type FeedbackFailure } from './feedback-failure.mts';
|
|
2
|
+
import type { FeedbackOutboxRecord } from './feedback-types.mts';
|
|
3
|
+
export type FeedbackFailureReport = FeedbackFailure & {
|
|
4
|
+
sourceEventId: string;
|
|
5
|
+
};
|
|
6
|
+
/**
|
|
7
|
+
* Persists one failed flush attempt with the record. The attempt count continues only while the
|
|
8
|
+
* cause repeats. A record-specific (non-transient) cause on {@link QUARANTINE_ATTEMPTS} consecutive
|
|
9
|
+
* attempts moves the record to the rejected area with that cause as its diagnostic.
|
|
10
|
+
*/
|
|
11
|
+
export declare function recordFeedbackFailure(directory: string, record: FeedbackOutboxRecord, cause: FeedbackCause): {
|
|
12
|
+
failure: FeedbackFailure;
|
|
13
|
+
quarantined: boolean;
|
|
14
|
+
};
|
|
15
|
+
/** Every pending record's last failed flush, without creating the outbox directory. */
|
|
16
|
+
export declare function readFeedbackFailures(directory: string): FeedbackFailureReport[];
|
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
import { join } from 'node:path';
|
|
2
|
+
import { withFileLock } from "../private-files/lock.mjs";
|
|
3
|
+
import { canonicalFeedback } from "./feedback-canonical.mjs";
|
|
4
|
+
import { ensureOutboxDirectory } from "./feedback-outbox-directory.mjs";
|
|
5
|
+
import { MAX_ATTEMPTS, QUARANTINE_ATTEMPTS, isTransientCause, } from "./feedback-failure.mjs";
|
|
6
|
+
import { moveToRejected } from "./feedback-outbox-rejected.mjs";
|
|
7
|
+
import { writeOutboxFile } from "./feedback-outbox-write.mjs";
|
|
8
|
+
import { filename, outboxDirectory, records, syncDirectory } from "./feedback-outbox.mjs";
|
|
9
|
+
/**
|
|
10
|
+
* Persists one failed flush attempt with the record. The attempt count continues only while the
|
|
11
|
+
* cause repeats. A record-specific (non-transient) cause on {@link QUARANTINE_ATTEMPTS} consecutive
|
|
12
|
+
* attempts moves the record to the rejected area with that cause as its diagnostic.
|
|
13
|
+
*/
|
|
14
|
+
export function recordFeedbackFailure(directory, record, cause) {
|
|
15
|
+
const path = outboxDirectory(directory, true);
|
|
16
|
+
return withFileLock(join(path, '.records'), () => {
|
|
17
|
+
const existing = records(path).find((item) => item.path === join(path, filename(record)));
|
|
18
|
+
const attempts = existing?.failure?.cause === cause.cause
|
|
19
|
+
? Math.min(existing.failure.attempts + 1, MAX_ATTEMPTS)
|
|
20
|
+
: 1;
|
|
21
|
+
const failure = { ...cause, attempts };
|
|
22
|
+
if (!existing)
|
|
23
|
+
return { failure, quarantined: false };
|
|
24
|
+
if (canonicalFeedback(existing.record) !== canonicalFeedback(record))
|
|
25
|
+
throw new Error('feedback outbox changed during delivery');
|
|
26
|
+
if (!isTransientCause(cause.cause) && attempts >= QUARANTINE_ATTEMPTS) {
|
|
27
|
+
moveToRejected(path, record, { ...failure, diagnostic: 'delivery-quarantined' });
|
|
28
|
+
return { failure, quarantined: true };
|
|
29
|
+
}
|
|
30
|
+
writeOutboxFile(path, filename(record), { ...record, failure });
|
|
31
|
+
syncDirectory(path);
|
|
32
|
+
return { failure, quarantined: false };
|
|
33
|
+
});
|
|
34
|
+
}
|
|
35
|
+
/** Every pending record's last failed flush, without creating the outbox directory. */
|
|
36
|
+
export function readFeedbackFailures(directory) {
|
|
37
|
+
const path = outboxDirectory(directory, false);
|
|
38
|
+
if (!ensureOutboxDirectory(path, false))
|
|
39
|
+
return [];
|
|
40
|
+
return withFileLock(join(path, '.records'), () => records(path).flatMap(({ record, failure }) => failure ? [{ sourceEventId: record.envelope.sourceEventId, ...failure }] : []));
|
|
41
|
+
}
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
import type { FeedbackFailure, FeedbackRejection } from './feedback-failure.mts';
|
|
2
|
+
import type { FeedbackOutboxRecord } from './feedback-types.mts';
|
|
3
|
+
export declare const RECORD_MAX_BYTES = 18000;
|
|
4
|
+
export type LoadedRecord = {
|
|
5
|
+
record: FeedbackOutboxRecord;
|
|
6
|
+
/** The record payload size, excluding failure and rejection notes, as admission measures it. */
|
|
7
|
+
bytes: number;
|
|
8
|
+
failure?: FeedbackFailure;
|
|
9
|
+
rejection?: FeedbackRejection;
|
|
10
|
+
};
|
|
11
|
+
export declare function readRecord(path: string): LoadedRecord;
|
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
import { closeSync, constants, fstatSync } from 'node:fs';
|
|
2
|
+
import { openLogFile, readLogContent } from "../private-files/log-file.mjs";
|
|
3
|
+
import { validateFeedbackEnvelope } from "./feedback-codec.mjs";
|
|
4
|
+
import { parseFailure, parseRejection } from "./feedback-failure-parse.mjs";
|
|
5
|
+
import { validateFeedbackIdentity } from "./feedback-identity.mjs";
|
|
6
|
+
import { isObject } from "./snapshot-partition-guards.mjs";
|
|
7
|
+
export const RECORD_MAX_BYTES = 18_000;
|
|
8
|
+
// A stored failure or rejection note rides along with a record at its size limit.
|
|
9
|
+
const NOTE_MAX_BYTES = 1_000;
|
|
10
|
+
const RECORD_KEYS = ['identity', 'envelope', 'failure', 'rejection'];
|
|
11
|
+
export function readRecord(path) {
|
|
12
|
+
const descriptor = openLogFile(path, constants.O_RDONLY);
|
|
13
|
+
try {
|
|
14
|
+
const limit = RECORD_MAX_BYTES + NOTE_MAX_BYTES;
|
|
15
|
+
if (fstatSync(descriptor).size > limit)
|
|
16
|
+
throw new Error('feedback outbox record is too large');
|
|
17
|
+
const value = JSON.parse(readLogContent(descriptor, limit));
|
|
18
|
+
if (!isObject(value) || Object.keys(value).some((key) => !RECORD_KEYS.includes(key)))
|
|
19
|
+
throw new Error('invalid feedback outbox record');
|
|
20
|
+
validateFeedbackIdentity(value.identity);
|
|
21
|
+
validateFeedbackEnvelope(value.envelope);
|
|
22
|
+
const record = { identity: value.identity, envelope: value.envelope };
|
|
23
|
+
return {
|
|
24
|
+
record,
|
|
25
|
+
bytes: Buffer.byteLength(JSON.stringify(record)),
|
|
26
|
+
...(value.failure === undefined ? {} : { failure: parseFailure(value.failure) }),
|
|
27
|
+
...(value.rejection === undefined ? {} : { rejection: parseRejection(value.rejection) }),
|
|
28
|
+
};
|
|
29
|
+
}
|
|
30
|
+
finally {
|
|
31
|
+
closeSync(descriptor);
|
|
32
|
+
}
|
|
33
|
+
}
|
|
@@ -1,9 +1,18 @@
|
|
|
1
|
+
import type { FeedbackRejection } from './feedback-failure.mts';
|
|
1
2
|
import type { FeedbackOutboxRecord } from './feedback-types.mts';
|
|
2
3
|
/**
|
|
3
|
-
* Moves a permanently rejected record out of the pending set into the rejected area of the outbox
|
|
4
|
-
* The content is kept, never deleted, so a corrected
|
|
5
|
-
* rejected note stays inspectable. A record that is
|
|
4
|
+
* Moves a permanently rejected record out of the pending set into the rejected area of the outbox,
|
|
5
|
+
* with the rejection diagnostic stored beside it. The content is kept, never deleted, so a corrected
|
|
6
|
+
* retry of the same event is accepted while the rejected note stays inspectable. A record that is
|
|
7
|
+
* no longer pending is left alone. The caller must hold the outbox lock.
|
|
6
8
|
*/
|
|
7
|
-
export declare function
|
|
8
|
-
|
|
9
|
+
export declare function moveToRejected(path: string, record: FeedbackOutboxRecord, rejection: FeedbackRejection): boolean;
|
|
10
|
+
export declare function rejectFeedbackOutbox(directory: string, record: FeedbackOutboxRecord, rejection: FeedbackRejection): void;
|
|
11
|
+
/** Reads the rejected records and their stored diagnostics without creating the outbox directory. */
|
|
12
|
+
export declare function readRejectedDetails(directory: string): Array<{
|
|
13
|
+
record: FeedbackOutboxRecord;
|
|
14
|
+
rejection?: FeedbackRejection;
|
|
15
|
+
}>;
|
|
9
16
|
export declare function readRejectedFeedbackOutbox(directory: string): FeedbackOutboxRecord[];
|
|
17
|
+
/** Deletes rejected records last written at least `olderThanDays` days ago; 0 deletes them all. */
|
|
18
|
+
export declare function pruneRejectedFeedbackOutbox(directory: string, olderThanDays: number): number;
|
|
@@ -1,34 +1,60 @@
|
|
|
1
|
-
import { readdirSync,
|
|
1
|
+
import { readdirSync, statSync, unlinkSync } from 'node:fs';
|
|
2
2
|
import { join } from 'node:path';
|
|
3
3
|
import { withFileLock } from "../private-files/lock.mjs";
|
|
4
4
|
import { canonicalFeedback } from "./feedback-canonical.mjs";
|
|
5
5
|
import { ensureOutboxDirectory } from "./feedback-outbox-directory.mjs";
|
|
6
|
-
import {
|
|
6
|
+
import { readRecord } from "./feedback-outbox-read.mjs";
|
|
7
|
+
import { writeOutboxFile } from "./feedback-outbox-write.mjs";
|
|
8
|
+
import { filename, outboxDirectory, records, syncDirectory } from "./feedback-outbox.mjs";
|
|
9
|
+
const REJECTED = /^[a-f0-9]{64}\.rejected$/;
|
|
7
10
|
const rejectedName = (record) => filename(record).replace(/\.json$/, '.rejected');
|
|
8
11
|
/**
|
|
9
|
-
* Moves a permanently rejected record out of the pending set into the rejected area of the outbox
|
|
10
|
-
* The content is kept, never deleted, so a corrected
|
|
11
|
-
* rejected note stays inspectable. A record that is
|
|
12
|
+
* Moves a permanently rejected record out of the pending set into the rejected area of the outbox,
|
|
13
|
+
* with the rejection diagnostic stored beside it. The content is kept, never deleted, so a corrected
|
|
14
|
+
* retry of the same event is accepted while the rejected note stays inspectable. A record that is
|
|
15
|
+
* no longer pending is left alone. The caller must hold the outbox lock.
|
|
12
16
|
*/
|
|
13
|
-
export function
|
|
17
|
+
export function moveToRejected(path, record, rejection) {
|
|
18
|
+
const existing = records(path).find((item) => item.path === join(path, filename(record)));
|
|
19
|
+
if (!existing)
|
|
20
|
+
return false;
|
|
21
|
+
if (canonicalFeedback(existing.record) !== canonicalFeedback(record))
|
|
22
|
+
throw new Error('feedback outbox changed during delivery');
|
|
23
|
+
writeOutboxFile(path, rejectedName(record), { ...existing.record, rejection });
|
|
24
|
+
unlinkSync(existing.path);
|
|
25
|
+
syncDirectory(path);
|
|
26
|
+
return true;
|
|
27
|
+
}
|
|
28
|
+
export function rejectFeedbackOutbox(directory, record, rejection) {
|
|
14
29
|
const path = outboxDirectory(directory, true);
|
|
15
|
-
withFileLock(join(path, '.records'), () =>
|
|
16
|
-
const existing = records(path).find((item) => item.path === join(path, filename(record)));
|
|
17
|
-
if (!existing)
|
|
18
|
-
return;
|
|
19
|
-
if (canonicalFeedback(existing.record) !== canonicalFeedback(record))
|
|
20
|
-
throw new Error('feedback outbox changed during delivery');
|
|
21
|
-
renameSync(existing.path, join(path, rejectedName(record)));
|
|
22
|
-
syncDirectory(path);
|
|
23
|
-
});
|
|
30
|
+
withFileLock(join(path, '.records'), () => void moveToRejected(path, record, rejection));
|
|
24
31
|
}
|
|
25
|
-
/** Reads the rejected records without creating the outbox directory. */
|
|
26
|
-
export function
|
|
32
|
+
/** Reads the rejected records and their stored diagnostics without creating the outbox directory. */
|
|
33
|
+
export function readRejectedDetails(directory) {
|
|
27
34
|
const path = outboxDirectory(directory, false);
|
|
28
35
|
if (!ensureOutboxDirectory(path, false))
|
|
29
36
|
return [];
|
|
30
37
|
return withFileLock(join(path, '.records'), () => readdirSync(path)
|
|
31
|
-
.filter((name) =>
|
|
38
|
+
.filter((name) => REJECTED.test(name))
|
|
32
39
|
.sort()
|
|
33
|
-
.map((name) => readRecord(join(path, name))
|
|
40
|
+
.map((name) => readRecord(join(path, name)))
|
|
41
|
+
.map(({ record, rejection }) => ({ record, ...(rejection ? { rejection } : {}) })));
|
|
42
|
+
}
|
|
43
|
+
export function readRejectedFeedbackOutbox(directory) {
|
|
44
|
+
return readRejectedDetails(directory).map((item) => item.record);
|
|
45
|
+
}
|
|
46
|
+
/** Deletes rejected records last written at least `olderThanDays` days ago; 0 deletes them all. */
|
|
47
|
+
export function pruneRejectedFeedbackOutbox(directory, olderThanDays) {
|
|
48
|
+
const path = outboxDirectory(directory, false);
|
|
49
|
+
if (!ensureOutboxDirectory(path, false))
|
|
50
|
+
return 0;
|
|
51
|
+
const cutoff = Date.now() - olderThanDays * 86_400_000;
|
|
52
|
+
return withFileLock(join(path, '.records'), () => {
|
|
53
|
+
const old = readdirSync(path).filter((name) => REJECTED.test(name) && statSync(join(path, name)).mtimeMs <= cutoff);
|
|
54
|
+
for (const name of old)
|
|
55
|
+
unlinkSync(join(path, name));
|
|
56
|
+
if (old.length > 0)
|
|
57
|
+
syncDirectory(path);
|
|
58
|
+
return old.length;
|
|
59
|
+
});
|
|
34
60
|
}
|
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
import { closeSync, constants, fsyncSync, openSync, renameSync, unlinkSync } from 'node:fs';
|
|
2
|
+
import { randomUUID } from 'node:crypto';
|
|
3
|
+
import { join } from 'node:path';
|
|
4
|
+
import { writeAll } from "../private-files/log-file.mjs";
|
|
5
|
+
/** Writes one outbox file durably: a private temporary file, fsync, then an atomic rename. */
|
|
6
|
+
export function writeOutboxFile(directory, name, value) {
|
|
7
|
+
const temporary = join(directory, `.persist-${randomUUID()}`);
|
|
8
|
+
const descriptor = openSync(temporary, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY | constants.O_NOFOLLOW, 0o600);
|
|
9
|
+
try {
|
|
10
|
+
writeAll(descriptor, JSON.stringify(value));
|
|
11
|
+
fsyncSync(descriptor);
|
|
12
|
+
closeSync(descriptor);
|
|
13
|
+
renameSync(temporary, join(directory, name));
|
|
14
|
+
}
|
|
15
|
+
catch (error) {
|
|
16
|
+
try {
|
|
17
|
+
closeSync(descriptor);
|
|
18
|
+
}
|
|
19
|
+
catch { }
|
|
20
|
+
try {
|
|
21
|
+
unlinkSync(temporary);
|
|
22
|
+
}
|
|
23
|
+
catch { }
|
|
24
|
+
throw error;
|
|
25
|
+
}
|
|
26
|
+
}
|
|
@@ -1,13 +1,8 @@
|
|
|
1
|
+
import { type LoadedRecord } from './feedback-outbox-read.mts';
|
|
1
2
|
import type { FeedbackOutboxRecord, FeedbackOutboxStatus } from './feedback-types.mts';
|
|
2
3
|
export declare function outboxDirectory(directory: string, create: boolean): string;
|
|
3
4
|
export declare function filename(record: FeedbackOutboxRecord): string;
|
|
4
|
-
export declare function
|
|
5
|
-
record: FeedbackOutboxRecord;
|
|
6
|
-
bytes: number;
|
|
7
|
-
};
|
|
8
|
-
export declare function records(directory: string): Array<{
|
|
9
|
-
record: FeedbackOutboxRecord;
|
|
10
|
-
bytes: number;
|
|
5
|
+
export declare function records(directory: string): Array<LoadedRecord & {
|
|
11
6
|
path: string;
|
|
12
7
|
}>;
|
|
13
8
|
export declare function syncDirectory(directory: string): void;
|
|
@@ -1,16 +1,15 @@
|
|
|
1
1
|
import { canonicalFeedback, canonicalFeedbackEvent } from "./feedback-canonical.mjs";
|
|
2
|
-
import { createHash
|
|
3
|
-
import { closeSync, constants, fsyncSync,
|
|
2
|
+
import { createHash } from 'node:crypto';
|
|
3
|
+
import { closeSync, constants, fsyncSync, openSync, readdirSync, unlinkSync } from 'node:fs';
|
|
4
4
|
import { isAbsolute, join, resolve } from 'node:path';
|
|
5
5
|
import { ensureOutboxDirectory } from "./feedback-outbox-directory.mjs";
|
|
6
6
|
import { withFileLock } from "../private-files/lock.mjs";
|
|
7
|
-
import {
|
|
7
|
+
import { writeOutboxFile } from "./feedback-outbox-write.mjs";
|
|
8
8
|
import { validateFeedbackEnvelope } from "./feedback-codec.mjs";
|
|
9
|
+
import { RECORD_MAX_BYTES, readRecord } from "./feedback-outbox-read.mjs";
|
|
9
10
|
import { validateFeedbackIdentity } from "./feedback-identity.mjs";
|
|
10
|
-
import { isObject } from "./snapshot-partition-guards.mjs";
|
|
11
11
|
const FEEDBACK_OUTBOX_MAX_RECORDS = 128;
|
|
12
12
|
const FEEDBACK_OUTBOX_MAX_BYTES = 2_000_000;
|
|
13
|
-
const RECORD_MAX_BYTES = 18_000;
|
|
14
13
|
export function outboxDirectory(directory, create) {
|
|
15
14
|
if (typeof directory !== 'string' || directory.length > 4096 || !isAbsolute(directory))
|
|
16
15
|
throw new Error('feedback outbox requires an absolute directory');
|
|
@@ -23,25 +22,6 @@ export function filename(record) {
|
|
|
23
22
|
.update(JSON.stringify([record.identity.sessionId, record.envelope.sourceEventId]))
|
|
24
23
|
.digest('hex')}.json`;
|
|
25
24
|
}
|
|
26
|
-
export function readRecord(path) {
|
|
27
|
-
const descriptor = openLogFile(path, constants.O_RDONLY);
|
|
28
|
-
try {
|
|
29
|
-
const status = fstatSync(descriptor);
|
|
30
|
-
const bytes = status.size;
|
|
31
|
-
if (bytes > RECORD_MAX_BYTES)
|
|
32
|
-
throw new Error('feedback outbox record is too large');
|
|
33
|
-
const value = JSON.parse(readLogContent(descriptor, RECORD_MAX_BYTES));
|
|
34
|
-
if (!isObject(value) ||
|
|
35
|
-
Object.keys(value).some((key) => !['identity', 'envelope'].includes(key)))
|
|
36
|
-
throw new Error('invalid feedback outbox record');
|
|
37
|
-
validateFeedbackIdentity(value.identity);
|
|
38
|
-
validateFeedbackEnvelope(value.envelope);
|
|
39
|
-
return { record: { identity: value.identity, envelope: value.envelope }, bytes };
|
|
40
|
-
}
|
|
41
|
-
finally {
|
|
42
|
-
closeSync(descriptor);
|
|
43
|
-
}
|
|
44
|
-
}
|
|
45
25
|
export function records(directory) {
|
|
46
26
|
const paths = readdirSync(directory).filter((name) => !name.endsWith('.rejected') && !name.startsWith('.records.lock'));
|
|
47
27
|
if (paths.length > FEEDBACK_OUTBOX_MAX_RECORDS)
|
|
@@ -102,7 +82,6 @@ export function persistFeedbackOutbox(directory, record) {
|
|
|
102
82
|
const current = records(path);
|
|
103
83
|
const name = filename(record);
|
|
104
84
|
const existing = current.find((item) => item.path === join(path, name));
|
|
105
|
-
const serialized = JSON.stringify(record);
|
|
106
85
|
if (existing) {
|
|
107
86
|
// A version-only difference is the same event: delivery accepts it into the stored session.
|
|
108
87
|
const { version: _retained, ...retainedIdentity } = existing.record.identity;
|
|
@@ -112,37 +91,13 @@ export function persistFeedbackOutbox(directory, record) {
|
|
|
112
91
|
throw new Error('feedback source event conflicts with a retained unsent record');
|
|
113
92
|
return existing.record;
|
|
114
93
|
}
|
|
115
|
-
const bytes = Buffer.byteLength(
|
|
94
|
+
const bytes = Buffer.byteLength(JSON.stringify(record));
|
|
116
95
|
if (bytes > RECORD_MAX_BYTES ||
|
|
117
96
|
current.length >= FEEDBACK_OUTBOX_MAX_RECORDS ||
|
|
118
97
|
current.reduce((sum, item) => sum + item.bytes, 0) + bytes > FEEDBACK_OUTBOX_MAX_BYTES)
|
|
119
98
|
throw new Error('feedback outbox is full; unsent records retained');
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
try {
|
|
123
|
-
writeAll(descriptor, serialized);
|
|
124
|
-
fsyncSync(descriptor);
|
|
125
|
-
}
|
|
126
|
-
catch (error) {
|
|
127
|
-
closeSync(descriptor);
|
|
128
|
-
try {
|
|
129
|
-
unlinkSync(temporary);
|
|
130
|
-
}
|
|
131
|
-
catch { }
|
|
132
|
-
throw error;
|
|
133
|
-
}
|
|
134
|
-
closeSync(descriptor);
|
|
135
|
-
try {
|
|
136
|
-
renameSync(temporary, join(path, name));
|
|
137
|
-
syncDirectory(path);
|
|
138
|
-
}
|
|
139
|
-
catch (error) {
|
|
140
|
-
try {
|
|
141
|
-
unlinkSync(temporary);
|
|
142
|
-
}
|
|
143
|
-
catch { }
|
|
144
|
-
throw error;
|
|
145
|
-
}
|
|
99
|
+
writeOutboxFile(path, name, record);
|
|
100
|
+
syncDirectory(path);
|
|
146
101
|
return record;
|
|
147
102
|
});
|
|
148
103
|
}
|