@agent-watch-ai/edge 0.2.5 → 0.3.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/CHANGELOG.md +512 -0
- package/README.md +217 -96
- package/SECURITY.md +69 -0
- package/dist/billing/session-billing.d.ts +19 -0
- package/dist/billing/session-billing.js +52 -0
- package/dist/cli/args.d.ts +10 -0
- package/dist/cli/args.js +20 -0
- package/dist/cli/constants/cli.constants.d.ts +50 -4
- package/dist/cli/constants/cli.constants.js +54 -5
- package/dist/cli/context.d.ts +33 -2
- package/dist/cli/context.js +84 -14
- package/dist/cli/doctor.js +309 -32
- package/dist/cli/hook-check.d.ts +23 -0
- package/dist/cli/hook-check.js +114 -0
- package/dist/cli/hook.js +118 -7
- package/dist/cli/index.d.ts +3 -1
- package/dist/cli/index.js +3 -1
- package/dist/cli/misc.d.ts +11 -0
- package/dist/cli/misc.js +80 -4
- package/dist/cli/npx-install.d.ts +37 -0
- package/dist/cli/npx-install.js +79 -0
- package/dist/cli/open-browser.d.ts +39 -0
- package/dist/cli/open-browser.js +62 -0
- package/dist/cli/setup.d.ts +17 -8
- package/dist/cli/setup.js +439 -98
- package/dist/cli/status.js +82 -13
- package/dist/cli/toggle.d.ts +9 -0
- package/dist/cli/toggle.js +113 -0
- package/dist/cli/types/cli.types.d.ts +37 -3
- package/dist/cli/ui.d.ts +7 -0
- package/dist/cli/ui.js +10 -1
- package/dist/cli/uninstall.js +39 -2
- package/dist/cli/update.d.ts +17 -0
- package/dist/cli/update.js +76 -0
- package/dist/cli.js +100 -13
- package/dist/config/config-store.d.ts +57 -0
- package/dist/config/config-store.js +250 -12
- package/dist/config/config.d.ts +53 -6
- package/dist/config/config.js +66 -6
- package/dist/config/constants/config.constants.d.ts +113 -6
- package/dist/config/constants/config.constants.js +126 -8
- package/dist/config/destination.d.ts +24 -0
- package/dist/config/destination.js +33 -0
- package/dist/config/index.d.ts +7 -4
- package/dist/config/index.js +5 -3
- package/dist/config/repo-config.d.ts +11 -7
- package/dist/config/repo-config.js +64 -15
- package/dist/config/root-config.d.ts +72 -0
- package/dist/config/root-config.js +170 -0
- package/dist/config/schemas/config.schema.d.ts +721 -84
- package/dist/config/schemas/config.schema.js +388 -15
- package/dist/config/types/config.types.d.ts +15 -1
- package/dist/config/types/destination.types.d.ts +8 -0
- package/dist/core/async.d.ts +36 -0
- package/dist/core/async.js +68 -0
- package/dist/core/index.d.ts +1 -1
- package/dist/core/index.js +1 -1
- package/dist/core/object.d.ts +5 -0
- package/dist/core/object.js +9 -4
- package/dist/core/pipe.d.ts +0 -13
- package/dist/core/pipe.js +1 -9
- package/dist/core/types/core.types.d.ts +9 -0
- package/dist/core/types/core.types.js +0 -3
- package/dist/core/which.d.ts +14 -0
- package/dist/core/which.js +43 -3
- package/dist/credentials/budget.d.ts +9 -0
- package/dist/credentials/budget.js +16 -0
- package/dist/credentials/command-runner.d.ts +16 -0
- package/dist/credentials/command-runner.js +37 -0
- package/dist/credentials/constants/credentials.constants.d.ts +111 -0
- package/dist/credentials/constants/credentials.constants.js +112 -0
- package/dist/credentials/credential-status.d.ts +14 -0
- package/dist/credentials/credential-status.js +34 -0
- package/dist/credentials/credentials.d.ts +72 -0
- package/dist/credentials/credentials.js +253 -0
- package/dist/credentials/device-api.d.ts +64 -0
- package/dist/credentials/device-api.js +150 -0
- package/dist/credentials/device-state.d.ts +31 -0
- package/dist/credentials/device-state.js +51 -0
- package/dist/credentials/identity.d.ts +62 -0
- package/dist/credentials/identity.js +90 -0
- package/dist/credentials/index.d.ts +7 -0
- package/dist/credentials/index.js +5 -0
- package/dist/credentials/migration.d.ts +46 -0
- package/dist/credentials/migration.js +164 -0
- package/dist/credentials/schemas/device-api.schema.d.ts +77 -0
- package/dist/credentials/schemas/device-api.schema.js +33 -0
- package/dist/credentials/schemas/device-state.schema.d.ts +51 -0
- package/dist/credentials/schemas/device-state.schema.js +20 -0
- package/dist/credentials/secret-store.d.ts +54 -0
- package/dist/credentials/secret-store.js +217 -0
- package/dist/credentials/sign-in.d.ts +18 -0
- package/dist/credentials/sign-in.js +86 -0
- package/dist/credentials/token-refresher.d.ts +39 -0
- package/dist/credentials/token-refresher.js +185 -0
- package/dist/credentials/types/credentials.types.d.ts +195 -0
- package/dist/credentials/types/credentials.types.js +1 -0
- package/dist/enforcement/constants/enforcement.constants.d.ts +47 -1
- package/dist/enforcement/constants/enforcement.constants.js +56 -0
- package/dist/enforcement/decision-cache.d.ts +20 -1
- package/dist/enforcement/decision-cache.js +65 -2
- package/dist/enforcement/decision-client.d.ts +9 -8
- package/dist/enforcement/decision-client.js +62 -16
- package/dist/enforcement/enforcement.d.ts +23 -2
- package/dist/enforcement/enforcement.js +103 -15
- package/dist/enforcement/index.d.ts +4 -3
- package/dist/enforcement/index.js +3 -2
- package/dist/enforcement/types/enforcement.types.d.ts +64 -0
- package/dist/enrollment/constants/enrollment.constants.d.ts +2 -6
- package/dist/enrollment/constants/enrollment.constants.js +2 -6
- package/dist/enrollment/enrollment.d.ts +16 -0
- package/dist/enrollment/enrollment.js +54 -0
- package/dist/enrollment/index.d.ts +3 -7
- package/dist/enrollment/index.js +1 -1
- package/dist/enrollment/types/enrollment.types.d.ts +9 -13
- package/dist/events/constants/enrich.constants.d.ts +15 -0
- package/dist/events/constants/enrich.constants.js +15 -0
- package/dist/events/constants/events.constants.d.ts +6 -2
- package/dist/events/constants/events.constants.js +5 -1
- package/dist/events/enrich.js +92 -10
- package/dist/events/event-id.d.ts +0 -8
- package/dist/events/event-id.js +0 -10
- package/dist/events/index.d.ts +2 -2
- package/dist/events/index.js +1 -1
- package/dist/events/product-event.d.ts +9 -6
- package/dist/events/types/repo-snapshot.types.d.ts +7 -0
- package/dist/events/types/session-billing.types.d.ts +16 -0
- package/dist/events/types/session-billing.types.js +1 -0
- package/dist/feature/constants/feature.constants.d.ts +7 -0
- package/dist/feature/constants/feature.constants.js +7 -0
- package/dist/feature/index.d.ts +1 -1
- package/dist/feature/index.js +1 -1
- package/dist/feature/ticket-candidates.d.ts +14 -0
- package/dist/feature/ticket-candidates.js +26 -8
- package/dist/git/blob-hash.d.ts +21 -0
- package/dist/git/blob-hash.js +69 -0
- package/dist/git/checkout-root.d.ts +27 -0
- package/dist/git/checkout-root.js +75 -0
- package/dist/git/constants/git.constants.d.ts +160 -0
- package/dist/git/constants/git.constants.js +181 -0
- package/dist/git/fingerprint.d.ts +74 -0
- package/dist/git/fingerprint.js +219 -0
- package/dist/git/gate-checkout.d.ts +44 -0
- package/dist/git/gate-checkout.js +201 -0
- package/dist/git/git-context.d.ts +45 -0
- package/dist/git/git-context.js +61 -3
- package/dist/git/index.d.ts +4 -2
- package/dist/git/index.js +2 -1
- package/dist/git/manifest-repository.d.ts +13 -0
- package/dist/git/manifest-repository.js +92 -0
- package/dist/git/repo-snapshot.d.ts +29 -3
- package/dist/git/repo-snapshot.js +110 -7
- package/dist/git/repository-root.d.ts +39 -0
- package/dist/git/repository-root.js +131 -0
- package/dist/git/types/git.types.d.ts +55 -0
- package/dist/git/types/repository-root.types.d.ts +11 -0
- package/dist/git/types/repository-root.types.js +1 -0
- package/dist/git/types/snapshot.types.d.ts +9 -0
- package/dist/pipeline/constants/pipeline.constants.d.ts +7 -0
- package/dist/pipeline/constants/pipeline.constants.js +7 -0
- package/dist/pipeline/hook-pipeline.js +360 -32
- package/dist/pipeline/types/pipeline.types.d.ts +39 -4
- package/dist/privacy/constants/privacy.constants.js +15 -1
- package/dist/privacy/index.d.ts +1 -0
- package/dist/privacy/index.js +1 -0
- package/dist/privacy/product-capture.d.ts +12 -0
- package/dist/privacy/product-capture.js +73 -0
- package/dist/privacy/sanitizer.d.ts +21 -3
- package/dist/privacy/sanitizer.js +52 -8
- package/dist/process/ancestors.d.ts +39 -0
- package/dist/process/ancestors.js +121 -0
- package/dist/process/constants/process.constants.d.ts +34 -0
- package/dist/process/constants/process.constants.js +34 -0
- package/dist/process/index.d.ts +7 -0
- package/dist/process/index.js +2 -0
- package/dist/process/types/process.types.d.ts +23 -0
- package/dist/process/types/process.types.js +1 -0
- package/dist/providers/antigravity/antigravity.adapter.d.ts +12 -1
- package/dist/providers/antigravity/antigravity.adapter.js +21 -3
- package/dist/providers/antigravity/antigravity.detect.d.ts +0 -9
- package/dist/providers/antigravity/antigravity.detect.js +1 -1
- package/dist/providers/antigravity/antigravity.provider.js +3 -2
- package/dist/providers/antigravity/constants/antigravity.constants.d.ts +2 -0
- package/dist/providers/antigravity/constants/antigravity.constants.js +2 -0
- package/dist/providers/claude/claude.adapter.d.ts +11 -1
- package/dist/providers/claude/claude.adapter.js +26 -5
- package/dist/providers/claude/claude.otel.d.ts +32 -18
- package/dist/providers/claude/claude.otel.js +81 -6
- package/dist/providers/claude/claude.provider.js +5 -2
- package/dist/providers/claude/constants/claude.constants.d.ts +2 -0
- package/dist/providers/claude/constants/claude.constants.js +2 -0
- package/dist/providers/claude/constants/claude.otel.constants.d.ts +4 -0
- package/dist/providers/claude/constants/claude.otel.constants.js +8 -0
- package/dist/providers/codex/codex.adapter.d.ts +15 -1
- package/dist/providers/codex/codex.adapter.js +29 -5
- package/dist/providers/codex/codex.otel.d.ts +24 -2
- package/dist/providers/codex/codex.otel.js +147 -30
- package/dist/providers/codex/codex.provider.js +5 -2
- package/dist/providers/codex/constants/codex.constants.d.ts +2 -0
- package/dist/providers/codex/constants/codex.constants.js +16 -0
- package/dist/providers/codex/constants/codex.otel.constants.d.ts +5 -0
- package/dist/providers/codex/constants/codex.otel.constants.js +5 -0
- package/dist/providers/constants/provider.constants.d.ts +0 -3
- package/dist/providers/constants/provider.constants.js +0 -3
- package/dist/providers/cursor/constants/cursor.constants.d.ts +7 -0
- package/dist/providers/cursor/constants/cursor.constants.js +7 -0
- package/dist/providers/cursor/cursor.adapter.d.ts +33 -1
- package/dist/providers/cursor/cursor.adapter.js +52 -3
- package/dist/providers/cursor/cursor.detect.d.ts +0 -7
- package/dist/providers/cursor/cursor.detect.js +1 -1
- package/dist/providers/cursor/cursor.provider.js +5 -2
- package/dist/providers/gemini/constants/gemini.constants.d.ts +9 -0
- package/dist/providers/gemini/constants/gemini.constants.js +9 -0
- package/dist/providers/gemini/constants/gemini.otel.constants.d.ts +3 -1
- package/dist/providers/gemini/constants/gemini.otel.constants.js +3 -0
- package/dist/providers/gemini/gemini.adapter.d.ts +14 -1
- package/dist/providers/gemini/gemini.adapter.js +25 -5
- package/dist/providers/gemini/gemini.detect.d.ts +0 -7
- package/dist/providers/gemini/gemini.detect.js +1 -1
- package/dist/providers/gemini/gemini.otel.d.ts +19 -20
- package/dist/providers/gemini/gemini.otel.js +121 -17
- package/dist/providers/gemini/gemini.provider.js +2 -1
- package/dist/providers/index.d.ts +1 -1
- package/dist/providers/index.js +1 -1
- package/dist/providers/loaders.d.ts +10 -0
- package/dist/providers/loaders.js +40 -0
- package/dist/providers/provider.d.ts +11 -0
- package/dist/providers/provider.js +1 -1
- package/dist/providers/registry.d.ts +11 -8
- package/dist/providers/registry.js +11 -15
- package/dist/providers/shared/constants/hook-refusal.constants.d.ts +7 -0
- package/dist/providers/shared/constants/hook-refusal.constants.js +7 -0
- package/dist/providers/shared/constants/shell-directories.constants.d.ts +30 -0
- package/dist/providers/shared/constants/shell-directories.constants.js +39 -0
- package/dist/providers/shared/constants/tooling.constants.d.ts +18 -2
- package/dist/providers/shared/constants/tooling.constants.js +19 -3
- package/dist/providers/shared/event-builder.d.ts +12 -14
- package/dist/providers/shared/event-builder.js +20 -14
- package/dist/providers/shared/exporter-allowlist.d.ts +20 -0
- package/dist/providers/shared/exporter-allowlist.js +49 -0
- package/dist/providers/shared/hook-config.d.ts +2 -21
- package/dist/providers/shared/hook-config.js +5 -4
- package/dist/providers/shared/hook-refusal.d.ts +12 -0
- package/dist/providers/shared/hook-refusal.js +17 -1
- package/dist/providers/shared/install-record.d.ts +12 -2
- package/dist/providers/shared/install-record.js +5 -2
- package/dist/providers/shared/shell-directories.d.ts +24 -0
- package/dist/providers/shared/shell-directories.js +90 -0
- package/dist/providers/shared/tooling.d.ts +12 -1
- package/dist/providers/shared/tooling.js +18 -0
- package/dist/providers/shared/types/adapter.types.d.ts +1 -2
- package/dist/providers/types/provider.types.d.ts +57 -1
- package/dist/snapshot/constants/snapshot.constants.d.ts +32 -0
- package/dist/snapshot/constants/snapshot.constants.js +33 -0
- package/dist/snapshot/snapshot-event.js +52 -11
- package/dist/snapshot/snapshot-pipeline.js +1 -1
- package/dist/snapshot/types/snapshot.types.d.ts +2 -0
- package/dist/storage/atomic-file.d.ts +7 -0
- package/dist/storage/atomic-file.js +1 -1
- package/dist/storage/constants/storage.constants.d.ts +17 -0
- package/dist/storage/constants/storage.constants.js +17 -0
- package/dist/storage/disabled.d.ts +13 -0
- package/dist/storage/disabled.js +24 -0
- package/dist/storage/index.d.ts +2 -0
- package/dist/storage/index.js +2 -0
- package/dist/storage/paths.js +3 -2
- package/dist/storage/schemas/storage.schema.d.ts +72 -0
- package/dist/storage/schemas/storage.schema.js +6 -0
- package/dist/storage/sweep-marker.d.ts +19 -0
- package/dist/storage/sweep-marker.js +55 -0
- package/dist/storage/types/storage.types.d.ts +2 -0
- package/dist/storage/uninstalled.d.ts +58 -0
- package/dist/storage/uninstalled.js +107 -0
- package/dist/transport/auth-block.d.ts +66 -0
- package/dist/transport/auth-block.js +129 -0
- package/dist/transport/constants/transport.constants.d.ts +82 -3
- package/dist/transport/constants/transport.constants.js +83 -4
- package/dist/transport/cooldown.js +8 -1
- package/dist/transport/delivery.d.ts +14 -6
- package/dist/transport/delivery.js +80 -55
- package/dist/transport/http-transport.d.ts +1 -0
- package/dist/transport/http-transport.js +52 -10
- package/dist/transport/index.d.ts +6 -3
- package/dist/transport/index.js +3 -0
- package/dist/transport/queue-partition.d.ts +91 -0
- package/dist/transport/queue-partition.js +143 -0
- package/dist/transport/queue.d.ts +99 -20
- package/dist/transport/queue.js +210 -69
- package/dist/transport/response-body.d.ts +25 -0
- package/dist/transport/response-body.js +64 -0
- package/dist/transport/send.d.ts +11 -0
- package/dist/transport/send.js +17 -0
- package/dist/transport/types/delivery-flow.types.d.ts +19 -0
- package/dist/transport/types/delivery-flow.types.js +1 -0
- package/dist/transport/types/transport.types.d.ts +45 -0
- package/dist/turns/claude-transcript.d.ts +19 -1
- package/dist/turns/claude-transcript.js +46 -1
- package/dist/turns/codex-originator.d.ts +11 -0
- package/dist/turns/codex-originator.js +31 -0
- package/dist/turns/codex-transcript.d.ts +30 -0
- package/dist/turns/codex-transcript.js +88 -0
- package/dist/turns/constants/turns.constants.d.ts +141 -5
- package/dist/turns/constants/turns.constants.js +155 -5
- package/dist/turns/file-identity.d.ts +27 -0
- package/dist/turns/file-identity.js +48 -0
- package/dist/turns/gemini-transcript.d.ts +30 -0
- package/dist/turns/gemini-transcript.js +96 -0
- package/dist/turns/index.d.ts +3 -3
- package/dist/turns/index.js +1 -1
- package/dist/turns/inherited-checkout.d.ts +54 -0
- package/dist/turns/inherited-checkout.js +155 -0
- package/dist/turns/native-session-titles.d.ts +26 -0
- package/dist/turns/native-session-titles.js +102 -0
- package/dist/turns/transcript.d.ts +3 -2
- package/dist/turns/transcript.js +5 -1
- package/dist/turns/turn-state.d.ts +224 -3
- package/dist/turns/turn-state.js +456 -21
- package/dist/turns/turn-summary.d.ts +1 -14
- package/dist/turns/turn-summary.js +87 -51
- package/dist/turns/turn-tracker.d.ts +21 -2
- package/dist/turns/turn-tracker.js +379 -56
- package/dist/turns/types/transcript.types.d.ts +5 -0
- package/dist/turns/types/turn-state.types.d.ts +116 -5
- package/dist/turns/types/turn-summary.types.d.ts +64 -14
- package/dist/turns/types/turn-tracker.types.d.ts +27 -1
- package/dist/turns/work-checkout.d.ts +65 -0
- package/dist/turns/work-checkout.js +666 -0
- package/dist/untraced/constants/untraced.constants.d.ts +31 -0
- package/dist/untraced/constants/untraced.constants.js +63 -0
- package/dist/untraced/untraced.d.ts +35 -0
- package/dist/untraced/untraced.js +105 -0
- package/dist/update/constants/update.constants.d.ts +18 -0
- package/dist/update/constants/update.constants.js +20 -0
- package/dist/update/update-check.d.ts +52 -0
- package/dist/update/update-check.js +113 -0
- package/docs/AUDIT_PROMPT.md +129 -0
- package/docs/DATA_HANDLING.md +648 -0
- package/docs/ENTERPRISE_DEPLOYMENT.md +179 -0
- package/docs/PERFORMANCE.md +81 -0
- package/package.json +14 -4
- package/dist/enrollment/enrollment-provider.d.ts +0 -5
- package/dist/enrollment/manual-enrollment.d.ts +0 -32
- package/dist/enrollment/manual-enrollment.js +0 -72
- package/example/README.md +0 -43
- package/example/server.mjs +0 -240
- /package/dist/{enrollment/enrollment-provider.js → config/types/destination.types.js} +0 -0
|
@@ -57,6 +57,13 @@ export class BackendCooldown {
|
|
|
57
57
|
* End the cooldown after a successful send.
|
|
58
58
|
*/
|
|
59
59
|
async clear() {
|
|
60
|
-
|
|
60
|
+
try {
|
|
61
|
+
await fs.rm(this.file, { force: true });
|
|
62
|
+
}
|
|
63
|
+
catch {
|
|
64
|
+
// Same rule as `trip`: this is awaited between a proven-healthy send and
|
|
65
|
+
// the drain, so an EACCES here would abort the deliver stage and leave the
|
|
66
|
+
// backlog unsent on the one hook that just proved the backend works.
|
|
67
|
+
}
|
|
61
68
|
}
|
|
62
69
|
}
|
|
@@ -1,4 +1,5 @@
|
|
|
1
1
|
import type { ProductEvent } from '../events/product-event.js';
|
|
2
|
+
import type { BackendAuthBlock } from './auth-block.js';
|
|
2
3
|
import type { BackendCooldown } from './cooldown.js';
|
|
3
4
|
import type { DeliveryStats } from './delivery-stats.js';
|
|
4
5
|
import type { EventQueue } from './queue.js';
|
|
@@ -9,11 +10,17 @@ export type { DeliveryOutcome } from './types/transport.types.js';
|
|
|
9
10
|
* Hook-path delivery: one quick direct send, then whatever the backlog allows.
|
|
10
11
|
*
|
|
11
12
|
* Three properties this has to keep, in order of importance. It never loses a
|
|
12
|
-
* product record — a failed send always ends in the queue, never in a discard
|
|
13
|
-
*
|
|
14
|
-
*
|
|
15
|
-
*
|
|
16
|
-
*
|
|
13
|
+
* product record — a failed send always ends in the queue, never in a discard,
|
|
14
|
+
* and that holds for a refused credential too. It never blocks the agent for
|
|
15
|
+
* long — a backend that just failed is skipped entirely for the cooldown
|
|
16
|
+
* window, and one that refused the credential until the re-probe interval
|
|
17
|
+
* passes, rather than costing every hook a full timeout. And it keeps the backlog
|
|
18
|
+
* moving even on hooks that emit nothing, because those are the majority.
|
|
19
|
+
*
|
|
20
|
+
* Every path that skips a drain runs `queue.sweep` before returning, because
|
|
21
|
+
* the retention bound has to hold on exactly those paths: they are the
|
|
22
|
+
* week-long outages it exists for, a credential block only ends when a re-probe is accepted,
|
|
23
|
+
* and an endpoint the edge refuses is a state a machine can sit in for good.
|
|
17
24
|
*
|
|
18
25
|
* @param events - Product events this hook produced; often empty.
|
|
19
26
|
* @param transport - Where to send, or undefined before setup configures one.
|
|
@@ -21,6 +28,7 @@ export type { DeliveryOutcome } from './types/transport.types.js';
|
|
|
21
28
|
* @param drainBatchSize - Ceiling on events one drain pass may send.
|
|
22
29
|
* @param cooldown - Persisted circuit breaker, when enabled.
|
|
23
30
|
* @param stats - Sink for permanent losses, when enabled.
|
|
31
|
+
* @param authBlock - Persisted credential refusal, when enabled.
|
|
24
32
|
* @returns What was delivered, queued, drained and rejected.
|
|
25
33
|
*/
|
|
26
|
-
export declare function deliverEvents(events: readonly ProductEvent[], transport: EventTransport | undefined, queue: EventQueue, drainBatchSize: number, cooldown?: BackendCooldown, stats?: DeliveryStats): Promise<DeliveryOutcome>;
|
|
34
|
+
export declare function deliverEvents(events: readonly ProductEvent[], transport: EventTransport | undefined, queue: EventQueue, drainBatchSize: number, cooldown?: BackendCooldown, stats?: DeliveryStats, authBlock?: BackendAuthBlock): Promise<DeliveryOutcome>;
|
|
@@ -1,15 +1,30 @@
|
|
|
1
1
|
import { debugLog } from '../core/logger.js';
|
|
2
|
-
import {
|
|
2
|
+
import { next, runFlow, step } from '../core/pipe.js';
|
|
3
|
+
import { ANY_DESTINATION, AUTH_REJECTED_STATUSES, BACKEND_COOLDOWN_MS, DELIVERY_STAGE_NAMES } from './constants/transport.constants.js';
|
|
4
|
+
import { sendEvents } from './send.js';
|
|
3
5
|
export { BACKEND_COOLDOWN_MS } from './constants/transport.constants.js';
|
|
6
|
+
const DELIVERY_STAGES = [
|
|
7
|
+
step(DELIVERY_STAGE_NAMES.select, selectDelivery),
|
|
8
|
+
step(DELIVERY_STAGE_NAMES.send, sendCurrent),
|
|
9
|
+
step(DELIVERY_STAGE_NAMES.preserve, preserveUnsent),
|
|
10
|
+
step(DELIVERY_STAGE_NAMES.report, reportBackend),
|
|
11
|
+
step(DELIVERY_STAGE_NAMES.maintain, maintainQueue)
|
|
12
|
+
];
|
|
4
13
|
/**
|
|
5
14
|
* Hook-path delivery: one quick direct send, then whatever the backlog allows.
|
|
6
15
|
*
|
|
7
16
|
* Three properties this has to keep, in order of importance. It never loses a
|
|
8
|
-
* product record — a failed send always ends in the queue, never in a discard
|
|
9
|
-
*
|
|
10
|
-
*
|
|
11
|
-
*
|
|
12
|
-
*
|
|
17
|
+
* product record — a failed send always ends in the queue, never in a discard,
|
|
18
|
+
* and that holds for a refused credential too. It never blocks the agent for
|
|
19
|
+
* long — a backend that just failed is skipped entirely for the cooldown
|
|
20
|
+
* window, and one that refused the credential until the re-probe interval
|
|
21
|
+
* passes, rather than costing every hook a full timeout. And it keeps the backlog
|
|
22
|
+
* moving even on hooks that emit nothing, because those are the majority.
|
|
23
|
+
*
|
|
24
|
+
* Every path that skips a drain runs `queue.sweep` before returning, because
|
|
25
|
+
* the retention bound has to hold on exactly those paths: they are the
|
|
26
|
+
* week-long outages it exists for, a credential block only ends when a re-probe is accepted,
|
|
27
|
+
* and an endpoint the edge refuses is a state a machine can sit in for good.
|
|
13
28
|
*
|
|
14
29
|
* @param events - Product events this hook produced; often empty.
|
|
15
30
|
* @param transport - Where to send, or undefined before setup configures one.
|
|
@@ -17,64 +32,74 @@ export { BACKEND_COOLDOWN_MS } from './constants/transport.constants.js';
|
|
|
17
32
|
* @param drainBatchSize - Ceiling on events one drain pass may send.
|
|
18
33
|
* @param cooldown - Persisted circuit breaker, when enabled.
|
|
19
34
|
* @param stats - Sink for permanent losses, when enabled.
|
|
35
|
+
* @param authBlock - Persisted credential refusal, when enabled.
|
|
20
36
|
* @returns What was delivered, queued, drained and rejected.
|
|
21
37
|
*/
|
|
22
|
-
export async function deliverEvents(events, transport, queue, drainBatchSize, cooldown, stats) {
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
if (
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
return
|
|
42
|
-
}
|
|
43
|
-
|
|
38
|
+
export async function deliverEvents(events, transport, queue, drainBatchSize, cooldown, stats, authBlock) {
|
|
39
|
+
const flow = await runFlow(DELIVERY_STAGES, {
|
|
40
|
+
events, transport, queue, drainBatchSize, cooldown, stats, authBlock,
|
|
41
|
+
canSend: false,
|
|
42
|
+
outcome: { delivered: 0, queued: 0, drained: 0, rejected: 0 }
|
|
43
|
+
});
|
|
44
|
+
// A failed filesystem write must remain observable to the enclosing hook
|
|
45
|
+
// flow; returning a successful outcome would falsely claim durable delivery.
|
|
46
|
+
if (!flow.completed)
|
|
47
|
+
throw new Error(`delivery failed at ${flow.stoppedAt}: ${flow.reason}`, { cause: flow.cause });
|
|
48
|
+
return flow.state.outcome;
|
|
49
|
+
}
|
|
50
|
+
async function selectDelivery(state) {
|
|
51
|
+
const { transport, authBlock, cooldown } = state;
|
|
52
|
+
if (!transport)
|
|
53
|
+
return next(state);
|
|
54
|
+
if (transport.destination && authBlock && await authBlock.holds(transport.destination))
|
|
55
|
+
return next(state);
|
|
56
|
+
if (cooldown && await cooldown.active())
|
|
57
|
+
return next(state);
|
|
58
|
+
return next({ ...state, canSend: true });
|
|
59
|
+
}
|
|
60
|
+
async function sendCurrent(state) {
|
|
61
|
+
if (!state.canSend || !state.transport || state.events.length === 0)
|
|
62
|
+
return next(state);
|
|
63
|
+
const result = await sendEvents(state.transport, state.events);
|
|
64
|
+
const outcome = result.ok ? { ...state.outcome, delivered: state.events.length, rejected: result.counters?.rejected ?? 0 } : state.outcome;
|
|
65
|
+
return next({ ...state, result, outcome });
|
|
66
|
+
}
|
|
67
|
+
async function preserveUnsent(state) {
|
|
68
|
+
if (state.events.length === 0 || state.result?.ok)
|
|
69
|
+
return next(state);
|
|
70
|
+
// One queue path for absence, auth block, cooldown and transport failures.
|
|
71
|
+
// It precedes diagnostic writes so a stats failure cannot discard a record.
|
|
72
|
+
await state.queue.enqueue(state.events, state.transport?.destination ?? ANY_DESTINATION);
|
|
73
|
+
return next({ ...state, outcome: { ...state.outcome, queued: state.events.length } });
|
|
74
|
+
}
|
|
75
|
+
async function reportBackend(state) {
|
|
76
|
+
const { result, cooldown, stats, authBlock, transport } = state;
|
|
77
|
+
if (!result || result.deferred)
|
|
78
|
+
return next(state);
|
|
44
79
|
if (!result.ok) {
|
|
45
80
|
debugLog('direct send failed', result.error ?? `status ${result.status}`);
|
|
46
|
-
if (result.retryable && cooldown)
|
|
81
|
+
if (result.retryable && (result.status === undefined || result.status >= 400) && cooldown)
|
|
47
82
|
await cooldown.trip(BACKEND_COOLDOWN_MS);
|
|
48
|
-
// A refusal the transport will not retry is the whole diagnosis: without it
|
|
49
|
-
// a developer sees only a backlog that grows and then empties itself when
|
|
50
|
-
// the entries age out.
|
|
51
83
|
if (!result.retryable && stats)
|
|
52
84
|
await stats.recordRefusal(result.status);
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
return { delivered: 0, queued: events.length, drained: 0, rejected: 0 };
|
|
58
|
-
}
|
|
59
|
-
const rejected = result.counters?.rejected ?? 0;
|
|
60
|
-
if (rejected > 0) {
|
|
61
|
-
debugLog(`backend permanently rejected ${rejected} event(s) from the direct send`);
|
|
62
|
-
if (stats)
|
|
63
|
-
await stats.recordRejected(rejected);
|
|
85
|
+
if (result.status !== undefined && AUTH_REJECTED_STATUSES.has(result.status) && authBlock && transport?.destination) {
|
|
86
|
+
await authBlock.raise(transport.destination, result.status, result.refusal);
|
|
87
|
+
}
|
|
88
|
+
return next(state);
|
|
64
89
|
}
|
|
90
|
+
if (state.outcome.rejected > 0 && stats)
|
|
91
|
+
await stats.recordRejected(state.outcome.rejected);
|
|
65
92
|
if (cooldown)
|
|
66
93
|
await cooldown.clear();
|
|
67
|
-
|
|
68
|
-
|
|
94
|
+
if (authBlock)
|
|
95
|
+
await authBlock.clear();
|
|
96
|
+
return next(state);
|
|
69
97
|
}
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
if (!cooldown)
|
|
78
|
-
return false;
|
|
79
|
-
return cooldown.active();
|
|
98
|
+
async function maintainQueue(state) {
|
|
99
|
+
if (!state.canSend || !state.transport || (state.result && !state.result.ok)) {
|
|
100
|
+
await state.queue.sweep(state.stats);
|
|
101
|
+
return next(state);
|
|
102
|
+
}
|
|
103
|
+
const drained = await state.queue.drain(state.transport, state.drainBatchSize, state.stats, state.authBlock);
|
|
104
|
+
return next({ ...state, outcome: { ...state.outcome, drained: drained.sent, rejected: state.outcome.rejected + drained.rejected } });
|
|
80
105
|
}
|
|
@@ -10,6 +10,7 @@ export type { HttpTransportOptions } from './types/transport.types.js';
|
|
|
10
10
|
export declare class HttpTransport implements EventTransport {
|
|
11
11
|
private readonly options;
|
|
12
12
|
private readonly fetchFn;
|
|
13
|
+
private deadline;
|
|
13
14
|
/**
|
|
14
15
|
* Bind the transport to one backend.
|
|
15
16
|
*
|
|
@@ -1,5 +1,9 @@
|
|
|
1
|
-
import {
|
|
1
|
+
import { performance } from 'node:perf_hooks';
|
|
2
|
+
import { applyProductCapture } from '../privacy/product-capture.js';
|
|
3
|
+
import { readRefusal } from '../credentials/device-api.js';
|
|
4
|
+
import { CONTENT_TYPE_HEADER, JSON_CONTENT_TYPE, MIN_VIABLE_SEND_MS, RETRYABLE_STATUSES } from './constants/transport.constants.js';
|
|
2
5
|
import { edgeHeaders } from './headers.js';
|
|
6
|
+
import { discardResponseBody, readCappedJson } from './response-body.js';
|
|
3
7
|
/**
|
|
4
8
|
* POST `{events: [...]}` to the configured backend.
|
|
5
9
|
*
|
|
@@ -9,6 +13,7 @@ import { edgeHeaders } from './headers.js';
|
|
|
9
13
|
export class HttpTransport {
|
|
10
14
|
options;
|
|
11
15
|
fetchFn;
|
|
16
|
+
deadline;
|
|
12
17
|
/**
|
|
13
18
|
* Bind the transport to one backend.
|
|
14
19
|
*
|
|
@@ -17,6 +22,7 @@ export class HttpTransport {
|
|
|
17
22
|
constructor(options) {
|
|
18
23
|
this.options = options;
|
|
19
24
|
this.fetchFn = options.fetchFn ?? fetch;
|
|
25
|
+
this.deadline = options.deadline;
|
|
20
26
|
}
|
|
21
27
|
/**
|
|
22
28
|
* Where this transport sends events.
|
|
@@ -36,19 +42,51 @@ export class HttpTransport {
|
|
|
36
42
|
async send(events) {
|
|
37
43
|
if (events.length === 0)
|
|
38
44
|
return { ok: true, retryable: false };
|
|
45
|
+
// Current policy, not the policy the record was written under: a queued
|
|
46
|
+
// event may predate a revoked consent or capture flag.
|
|
47
|
+
const payload = [];
|
|
48
|
+
for (const event of events) {
|
|
49
|
+
const captured = applyProductCapture(event, this.options.capture);
|
|
50
|
+
if (captured)
|
|
51
|
+
payload.push(captured);
|
|
52
|
+
}
|
|
53
|
+
if (payload.length === 0)
|
|
54
|
+
return { ok: true, retryable: false };
|
|
55
|
+
if (this.options.credentialPending)
|
|
56
|
+
return { ok: false, retryable: true, deferred: true };
|
|
57
|
+
const now = this.options.nowMs?.() ?? performance.now();
|
|
58
|
+
// Only hook-owned transports opt into a pass budget. Start on first use,
|
|
59
|
+
// after selection and capture, so construction and local checks cost none.
|
|
60
|
+
if (this.deadline === undefined && this.options.budgetMs !== undefined)
|
|
61
|
+
this.deadline = now + this.options.budgetMs;
|
|
62
|
+
const remaining = this.deadline === undefined ? this.options.timeoutMs : this.deadline - now;
|
|
63
|
+
if (remaining < Math.min(MIN_VIABLE_SEND_MS, this.options.timeoutMs))
|
|
64
|
+
return { ok: false, retryable: true, deferred: true };
|
|
65
|
+
const requestMs = Math.min(this.options.timeoutMs, remaining);
|
|
39
66
|
try {
|
|
40
67
|
const response = await this.fetchFn(this.options.eventsUrl, {
|
|
41
68
|
method: 'POST',
|
|
42
69
|
headers: this.headers(),
|
|
43
|
-
body: JSON.stringify({ events }),
|
|
44
|
-
|
|
70
|
+
body: JSON.stringify({ events: payload }),
|
|
71
|
+
// A redirect would move a batch that carries a bearer to an endpoint
|
|
72
|
+
// nothing configured; refusing is the only safe answer.
|
|
73
|
+
redirect: 'error',
|
|
74
|
+
signal: AbortSignal.timeout(Math.max(1, Math.floor(requestMs)))
|
|
45
75
|
});
|
|
46
76
|
if (response.ok) {
|
|
47
77
|
return { ok: true, status: response.status, retryable: false, counters: await readCounters(response) };
|
|
48
78
|
}
|
|
49
|
-
|
|
79
|
+
const refusal = response.status === 401 ? await readRefusal(response) : undefined;
|
|
80
|
+
if (response.status !== 401)
|
|
81
|
+
discardResponseBody(response);
|
|
82
|
+
return { ok: false, status: response.status, retryable: isRetryableStatus(response.status), error: `HTTP ${response.status}`, ...(refusal ? { refusal } : {}) };
|
|
50
83
|
}
|
|
51
84
|
catch (error) {
|
|
85
|
+
// A shortened request exhausting the remainder of a pass is local
|
|
86
|
+
// scheduling pressure, not evidence that the backend is unhealthy.
|
|
87
|
+
if (requestMs < this.options.timeoutMs && error instanceof Error && error.name === 'TimeoutError') {
|
|
88
|
+
return { ok: false, retryable: true, deferred: true };
|
|
89
|
+
}
|
|
52
90
|
// Never include response or request bodies in errors: they carry event
|
|
53
91
|
// content, and this string ends up in logs.
|
|
54
92
|
return { ok: false, retryable: true, error: error.name || 'network error' };
|
|
@@ -71,15 +109,18 @@ export class HttpTransport {
|
|
|
71
109
|
*
|
|
72
110
|
* A 202 can still carry per-event rejections, and the batch "succeeding" while
|
|
73
111
|
* events inside it were dropped is exactly the case the caller must see. A
|
|
74
|
-
* backend that returns no JSON body
|
|
112
|
+
* backend that returns no JSON body — or one too large to be counters — is
|
|
113
|
+
* treated as counter-less, not failed.
|
|
75
114
|
*
|
|
76
115
|
* @param response - The backend's response.
|
|
77
116
|
* @returns The counters, or undefined when the body carried none.
|
|
78
117
|
*/
|
|
79
118
|
async function readCounters(response) {
|
|
80
119
|
try {
|
|
81
|
-
const body = (await response
|
|
82
|
-
|
|
120
|
+
const body = (await readCappedJson(response));
|
|
121
|
+
// Own properties only: this object came off the network, so a `__proto__`
|
|
122
|
+
// in the body must not answer for a counter nobody sent.
|
|
123
|
+
const numeric = (key) => (Object.hasOwn(body, key) && Number.isSafeInteger(body[key]) && body[key] >= 0 ? body[key] : 0);
|
|
83
124
|
return {
|
|
84
125
|
accepted: numeric('accepted'),
|
|
85
126
|
duplicate: numeric('duplicate'),
|
|
@@ -94,9 +135,10 @@ async function readCounters(response) {
|
|
|
94
135
|
/**
|
|
95
136
|
* Whether a failing status is worth retrying.
|
|
96
137
|
*
|
|
97
|
-
*
|
|
98
|
-
*
|
|
99
|
-
*
|
|
138
|
+
* A rate limit or a timeout is transient, so those count as retryable and are
|
|
139
|
+
* capped by `delivery.maxAttempts`. A refused *credential* is deliberately not
|
|
140
|
+
* here: see `AUTH_REJECTED_STATUSES` and `BackendAuthBlock` — the records stay
|
|
141
|
+
* queued, but re-presenting a rejected bearer on every hook does not.
|
|
100
142
|
*
|
|
101
143
|
* @param status - HTTP status.
|
|
102
144
|
* @returns True when the batch should be queued for another attempt.
|
|
@@ -1,13 +1,16 @@
|
|
|
1
1
|
/**
|
|
2
|
-
*
|
|
3
|
-
*
|
|
4
|
-
* circuit breaker, and a file-per-event offline queue behind it.
|
|
2
|
+
* Bounded delivery with durable retries: failed sends stay queued until
|
|
3
|
+
* delivered or removed by the configured retention and retry limits.
|
|
5
4
|
*/
|
|
6
5
|
export type { DeliveryCounters, DeliveryOutcome, DeliveryResult, DeliveryStatsSnapshot, DrainStats, DrainStatsRecorder, EventTransport, HttpTransportOptions, QueueEntry, QueueOptions } from './types/transport.types.js';
|
|
7
6
|
export { ANY_DESTINATION, BACKEND_COOLDOWN_MS } from './constants/transport.constants.js';
|
|
8
7
|
export { HttpTransport } from './http-transport.js';
|
|
9
8
|
export { edgeHeaders } from './headers.js';
|
|
10
9
|
export { EventQueue } from './queue.js';
|
|
10
|
+
export { identityPaths, queuePartition, settleLegacyQueue, unattributedCount, unattributedQueue } from './queue-partition.js';
|
|
11
|
+
export type { IdentityPaths } from './queue-partition.js';
|
|
11
12
|
export { BackendCooldown } from './cooldown.js';
|
|
12
13
|
export { DeliveryStats } from './delivery-stats.js';
|
|
13
14
|
export { deliverEvents } from './delivery.js';
|
|
15
|
+
export { sendEvents } from './send.js';
|
|
16
|
+
export { discardResponseBody, readCappedJson } from './response-body.js';
|
package/dist/transport/index.js
CHANGED
|
@@ -2,6 +2,9 @@ export { ANY_DESTINATION, BACKEND_COOLDOWN_MS } from './constants/transport.cons
|
|
|
2
2
|
export { HttpTransport } from './http-transport.js';
|
|
3
3
|
export { edgeHeaders } from './headers.js';
|
|
4
4
|
export { EventQueue } from './queue.js';
|
|
5
|
+
export { identityPaths, queuePartition, settleLegacyQueue, unattributedCount, unattributedQueue } from './queue-partition.js';
|
|
5
6
|
export { BackendCooldown } from './cooldown.js';
|
|
6
7
|
export { DeliveryStats } from './delivery-stats.js';
|
|
7
8
|
export { deliverEvents } from './delivery.js';
|
|
9
|
+
export { sendEvents } from './send.js';
|
|
10
|
+
export { discardResponseBody, readCappedJson } from './response-body.js';
|
|
@@ -0,0 +1,91 @@
|
|
|
1
|
+
import type { AgentWatchPaths } from '../storage/types/storage.types.js';
|
|
2
|
+
/** Everything on disk that belongs to one identity's delivery. */
|
|
3
|
+
export interface IdentityPaths {
|
|
4
|
+
/** Its queue partition. */
|
|
5
|
+
readonly queueDir: string;
|
|
6
|
+
/** Its backend circuit breaker. */
|
|
7
|
+
readonly cooldownFile: string;
|
|
8
|
+
/** Its permanent-loss tally. */
|
|
9
|
+
readonly statsFile: string;
|
|
10
|
+
/** Its standing credential refusal, when the backend raised one. */
|
|
11
|
+
readonly authBlockFile: string;
|
|
12
|
+
/** Its cached device access token (0600). */
|
|
13
|
+
readonly accessTokenFile: string;
|
|
14
|
+
/** Its device credential state: a refusal, the last exchange attempt. */
|
|
15
|
+
readonly deviceStateFile: string;
|
|
16
|
+
}
|
|
17
|
+
/**
|
|
18
|
+
* The queue directory one identity owns.
|
|
19
|
+
*
|
|
20
|
+
* A queue entry records a destination but never a bearer, so a single flat
|
|
21
|
+
* directory lets whichever hook happens to drain it send every tenant's backlog
|
|
22
|
+
* under its own token — the exact mis-attribution per-project roots exist to
|
|
23
|
+
* prevent, and unreachable only while the machine has one identity. Giving each
|
|
24
|
+
* identity its own directory makes a cross-tenant send impossible rather than
|
|
25
|
+
* unlikely: a drain lists one partition and cannot see another. The cost is that
|
|
26
|
+
* an idle tenant's backlog waits for that tenant's next hook, which is the right
|
|
27
|
+
* trade — late is recoverable, mis-attributed is not.
|
|
28
|
+
*
|
|
29
|
+
* The name is a digest, not the token: this path appears in `ls`, in backups and
|
|
30
|
+
* in every error message that quotes a file, none of which may carry a secret.
|
|
31
|
+
* The queue bound in `delivery.maxQueueEvents` therefore applies per identity.
|
|
32
|
+
*
|
|
33
|
+
* @param queueRoot - The machine's queue directory.
|
|
34
|
+
* @param token - Bearer this invocation would send with, when there is one.
|
|
35
|
+
* @returns Absolute directory this identity may read and write.
|
|
36
|
+
*/
|
|
37
|
+
export declare function queuePartition(queueRoot: string, token: string | undefined): string;
|
|
38
|
+
/**
|
|
39
|
+
* Where one identity's delivery lives: queue partition, backend cooldown, loss
|
|
40
|
+
* tally and credential block. All four per identity for the same reason — one
|
|
41
|
+
* tenant's backend outage must not put the other tenant's hooks into cooldown,
|
|
42
|
+
* one tenant's revoked token must not suspend the other tenant's sends, and
|
|
43
|
+
* `status` must not report two tenants' losses as one number.
|
|
44
|
+
*
|
|
45
|
+
* @param paths - The machine's paths.
|
|
46
|
+
* @param token - Bearer this invocation would send with, when there is one.
|
|
47
|
+
* @returns Absolute paths for this identity.
|
|
48
|
+
*/
|
|
49
|
+
export declare function identityPaths(paths: AgentWatchPaths, token: string | undefined): IdentityPaths;
|
|
50
|
+
/**
|
|
51
|
+
* Where a backlog nobody can claim waits for its owner to say what it is.
|
|
52
|
+
*
|
|
53
|
+
* @param queueRoot - The machine's queue directory.
|
|
54
|
+
* @returns Absolute directory.
|
|
55
|
+
*/
|
|
56
|
+
export declare function unattributedQueue(queueRoot: string): string;
|
|
57
|
+
/**
|
|
58
|
+
* How many entries are waiting there, so `status` and `doctor` can say so.
|
|
59
|
+
*
|
|
60
|
+
* @param queueRoot - The machine's queue directory.
|
|
61
|
+
* @returns The entry count.
|
|
62
|
+
*/
|
|
63
|
+
export declare function unattributedCount(queueRoot: string): Promise<number>;
|
|
64
|
+
/**
|
|
65
|
+
* Give the entries that belong to no partition a home, without guessing.
|
|
66
|
+
*
|
|
67
|
+
* Two sets qualify. A backlog written by a bridge that predates partitioning
|
|
68
|
+
* sits loose in the queue root, and upgrading must neither strand it in a
|
|
69
|
+
* directory nothing reads any more nor hand it to a tenant that may not own it.
|
|
70
|
+
* A backlog written before setup sits in `unconfigured/` pinned to
|
|
71
|
+
* ANY_DESTINATION, which is already a promise that the first identity
|
|
72
|
+
* configured here takes it.
|
|
73
|
+
*
|
|
74
|
+
* Those two obligations only conflict when the machine already serves several
|
|
75
|
+
* identities. When it serves one, that identity is provably the author of every
|
|
76
|
+
* entry, so it adopts them and the upgrade is invisible. When it serves more,
|
|
77
|
+
* the entries go to `unattributed/`, where they stay visible, intact and
|
|
78
|
+
* delivered to nobody until the operator says whose they are — AGENTS.md's "when
|
|
79
|
+
* ownership is unclear, refuse and tell the user", applied to a ledger rather
|
|
80
|
+
* than to an agent config.
|
|
81
|
+
*
|
|
82
|
+
* Moving is a rename, which is atomic, so no lock is needed: a hook that loses
|
|
83
|
+
* the race finds the entry already gone and moves on.
|
|
84
|
+
*
|
|
85
|
+
* @param queueRoot - The machine's queue directory.
|
|
86
|
+
* @param token - Bearer this invocation would send with; without one there is
|
|
87
|
+
* no partition worth moving anything into yet.
|
|
88
|
+
* @param sharedMachine - Whether other identities are configured here.
|
|
89
|
+
* @returns How many entries were moved.
|
|
90
|
+
*/
|
|
91
|
+
export declare function settleLegacyQueue(queueRoot: string, token: string | undefined, sharedMachine: boolean): Promise<number>;
|
|
@@ -0,0 +1,143 @@
|
|
|
1
|
+
import fs from 'node:fs/promises';
|
|
2
|
+
import path from 'node:path';
|
|
3
|
+
import { debugLog } from '../core/logger.js';
|
|
4
|
+
import { identityFingerprint } from '../credentials/identity.js';
|
|
5
|
+
import { ACCESS_TOKEN_FILE_NAME, AUTH_BLOCK_FILE_NAME, COOLDOWN_FILE_NAME, DELIVERY_STATS_FILE_NAME, DEVICE_STATE_FILE_NAME, IDENTITY_STATE_DIR_NAME, UNATTRIBUTED_PARTITION, UNCONFIGURED_PARTITION } from './constants/transport.constants.js';
|
|
6
|
+
import { listQueueFiles } from './queue.js';
|
|
7
|
+
/**
|
|
8
|
+
* The queue directory one identity owns.
|
|
9
|
+
*
|
|
10
|
+
* A queue entry records a destination but never a bearer, so a single flat
|
|
11
|
+
* directory lets whichever hook happens to drain it send every tenant's backlog
|
|
12
|
+
* under its own token — the exact mis-attribution per-project roots exist to
|
|
13
|
+
* prevent, and unreachable only while the machine has one identity. Giving each
|
|
14
|
+
* identity its own directory makes a cross-tenant send impossible rather than
|
|
15
|
+
* unlikely: a drain lists one partition and cannot see another. The cost is that
|
|
16
|
+
* an idle tenant's backlog waits for that tenant's next hook, which is the right
|
|
17
|
+
* trade — late is recoverable, mis-attributed is not.
|
|
18
|
+
*
|
|
19
|
+
* The name is a digest, not the token: this path appears in `ls`, in backups and
|
|
20
|
+
* in every error message that quotes a file, none of which may carry a secret.
|
|
21
|
+
* The queue bound in `delivery.maxQueueEvents` therefore applies per identity.
|
|
22
|
+
*
|
|
23
|
+
* @param queueRoot - The machine's queue directory.
|
|
24
|
+
* @param token - Bearer this invocation would send with, when there is one.
|
|
25
|
+
* @returns Absolute directory this identity may read and write.
|
|
26
|
+
*/
|
|
27
|
+
export function queuePartition(queueRoot, token) {
|
|
28
|
+
return path.join(queueRoot, partitionName(token));
|
|
29
|
+
}
|
|
30
|
+
/**
|
|
31
|
+
* Where one identity's delivery lives: queue partition, backend cooldown, loss
|
|
32
|
+
* tally and credential block. All four per identity for the same reason — one
|
|
33
|
+
* tenant's backend outage must not put the other tenant's hooks into cooldown,
|
|
34
|
+
* one tenant's revoked token must not suspend the other tenant's sends, and
|
|
35
|
+
* `status` must not report two tenants' losses as one number.
|
|
36
|
+
*
|
|
37
|
+
* @param paths - The machine's paths.
|
|
38
|
+
* @param token - Bearer this invocation would send with, when there is one.
|
|
39
|
+
* @returns Absolute paths for this identity.
|
|
40
|
+
*/
|
|
41
|
+
export function identityPaths(paths, token) {
|
|
42
|
+
const stateDir = path.join(paths.dataDir, IDENTITY_STATE_DIR_NAME, partitionName(token));
|
|
43
|
+
return {
|
|
44
|
+
queueDir: queuePartition(paths.queueDir, token),
|
|
45
|
+
cooldownFile: path.join(stateDir, COOLDOWN_FILE_NAME),
|
|
46
|
+
statsFile: path.join(stateDir, DELIVERY_STATS_FILE_NAME),
|
|
47
|
+
authBlockFile: path.join(stateDir, AUTH_BLOCK_FILE_NAME),
|
|
48
|
+
accessTokenFile: path.join(stateDir, ACCESS_TOKEN_FILE_NAME),
|
|
49
|
+
deviceStateFile: path.join(stateDir, DEVICE_STATE_FILE_NAME)
|
|
50
|
+
};
|
|
51
|
+
}
|
|
52
|
+
/**
|
|
53
|
+
* The directory name standing for one identity.
|
|
54
|
+
*
|
|
55
|
+
* @param token - Install key or `device:<id>` (see `identityOf`), when there is one.
|
|
56
|
+
* @returns A digest prefix, or the shared name for "no token yet".
|
|
57
|
+
*/
|
|
58
|
+
function partitionName(token) {
|
|
59
|
+
if (!token)
|
|
60
|
+
return UNCONFIGURED_PARTITION;
|
|
61
|
+
return identityFingerprint(token);
|
|
62
|
+
}
|
|
63
|
+
/**
|
|
64
|
+
* Where a backlog nobody can claim waits for its owner to say what it is.
|
|
65
|
+
*
|
|
66
|
+
* @param queueRoot - The machine's queue directory.
|
|
67
|
+
* @returns Absolute directory.
|
|
68
|
+
*/
|
|
69
|
+
export function unattributedQueue(queueRoot) {
|
|
70
|
+
return path.join(queueRoot, UNATTRIBUTED_PARTITION);
|
|
71
|
+
}
|
|
72
|
+
/**
|
|
73
|
+
* How many entries are waiting there, so `status` and `doctor` can say so.
|
|
74
|
+
*
|
|
75
|
+
* @param queueRoot - The machine's queue directory.
|
|
76
|
+
* @returns The entry count.
|
|
77
|
+
*/
|
|
78
|
+
export async function unattributedCount(queueRoot) {
|
|
79
|
+
return (await listQueueFiles(unattributedQueue(queueRoot))).length;
|
|
80
|
+
}
|
|
81
|
+
/**
|
|
82
|
+
* Give the entries that belong to no partition a home, without guessing.
|
|
83
|
+
*
|
|
84
|
+
* Two sets qualify. A backlog written by a bridge that predates partitioning
|
|
85
|
+
* sits loose in the queue root, and upgrading must neither strand it in a
|
|
86
|
+
* directory nothing reads any more nor hand it to a tenant that may not own it.
|
|
87
|
+
* A backlog written before setup sits in `unconfigured/` pinned to
|
|
88
|
+
* ANY_DESTINATION, which is already a promise that the first identity
|
|
89
|
+
* configured here takes it.
|
|
90
|
+
*
|
|
91
|
+
* Those two obligations only conflict when the machine already serves several
|
|
92
|
+
* identities. When it serves one, that identity is provably the author of every
|
|
93
|
+
* entry, so it adopts them and the upgrade is invisible. When it serves more,
|
|
94
|
+
* the entries go to `unattributed/`, where they stay visible, intact and
|
|
95
|
+
* delivered to nobody until the operator says whose they are — AGENTS.md's "when
|
|
96
|
+
* ownership is unclear, refuse and tell the user", applied to a ledger rather
|
|
97
|
+
* than to an agent config.
|
|
98
|
+
*
|
|
99
|
+
* Moving is a rename, which is atomic, so no lock is needed: a hook that loses
|
|
100
|
+
* the race finds the entry already gone and moves on.
|
|
101
|
+
*
|
|
102
|
+
* @param queueRoot - The machine's queue directory.
|
|
103
|
+
* @param token - Bearer this invocation would send with; without one there is
|
|
104
|
+
* no partition worth moving anything into yet.
|
|
105
|
+
* @param sharedMachine - Whether other identities are configured here.
|
|
106
|
+
* @returns How many entries were moved.
|
|
107
|
+
*/
|
|
108
|
+
export async function settleLegacyQueue(queueRoot, token, sharedMachine) {
|
|
109
|
+
if (!token)
|
|
110
|
+
return 0;
|
|
111
|
+
const target = sharedMachine ? unattributedQueue(queueRoot) : queuePartition(queueRoot, token);
|
|
112
|
+
const sources = [queueRoot, path.join(queueRoot, UNCONFIGURED_PARTITION)];
|
|
113
|
+
const moved = (await Promise.all(sources.map((source) => moveEntries(source, target)))).reduce((sum, n) => sum + n, 0);
|
|
114
|
+
if (moved > 0)
|
|
115
|
+
debugLog(`queue: moved ${moved} unpartitioned entr(y|ies) to ${target}`);
|
|
116
|
+
return moved;
|
|
117
|
+
}
|
|
118
|
+
/**
|
|
119
|
+
* Move every entry of one directory into another, creating it on demand. A
|
|
120
|
+
* rename that fails is a race lost to a concurrent hook, or an entry that aged
|
|
121
|
+
* out from under us: either way not this call's to move and not its to lose.
|
|
122
|
+
*
|
|
123
|
+
* @param source - Directory to empty.
|
|
124
|
+
* @param target - Partition to fill.
|
|
125
|
+
* @returns How many entries this call moved.
|
|
126
|
+
*/
|
|
127
|
+
async function moveEntries(source, target) {
|
|
128
|
+
const names = await listQueueFiles(source);
|
|
129
|
+
if (names.length === 0)
|
|
130
|
+
return 0;
|
|
131
|
+
await fs.mkdir(target, { recursive: true });
|
|
132
|
+
let moved = 0;
|
|
133
|
+
for (const name of names) {
|
|
134
|
+
try {
|
|
135
|
+
await fs.rename(path.join(source, name), path.join(target, name));
|
|
136
|
+
moved++;
|
|
137
|
+
}
|
|
138
|
+
catch {
|
|
139
|
+
// Claimed by a concurrent hook, or gone.
|
|
140
|
+
}
|
|
141
|
+
}
|
|
142
|
+
return moved;
|
|
143
|
+
}
|