@indigoai-us/hq-cloud 6.16.20 → 6.16.22
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/bin/sync-runner-installation-id.d.ts +66 -0
- package/dist/bin/sync-runner-installation-id.d.ts.map +1 -0
- package/dist/bin/sync-runner-installation-id.js +138 -0
- package/dist/bin/sync-runner-installation-id.js.map +1 -0
- package/dist/bin/sync-runner-manifest.d.ts +120 -0
- package/dist/bin/sync-runner-manifest.d.ts.map +1 -0
- package/dist/bin/sync-runner-manifest.js +348 -0
- package/dist/bin/sync-runner-manifest.js.map +1 -0
- package/dist/bin/sync-runner-manifest.test.d.ts +12 -0
- package/dist/bin/sync-runner-manifest.test.d.ts.map +1 -0
- package/dist/bin/sync-runner-manifest.test.js +510 -0
- package/dist/bin/sync-runner-manifest.test.js.map +1 -0
- package/dist/bin/sync-runner.d.ts +55 -0
- package/dist/bin/sync-runner.d.ts.map +1 -1
- package/dist/bin/sync-runner.js +69 -0
- package/dist/bin/sync-runner.js.map +1 -1
- package/dist/bin/sync-runner.test.js +217 -0
- package/dist/bin/sync-runner.test.js.map +1 -1
- package/dist/company-slug.d.ts +31 -0
- package/dist/company-slug.d.ts.map +1 -0
- package/dist/company-slug.js +52 -0
- package/dist/company-slug.js.map +1 -0
- package/dist/company-slug.test.d.ts +7 -0
- package/dist/company-slug.test.d.ts.map +1 -0
- package/dist/company-slug.test.js +43 -0
- package/dist/company-slug.test.js.map +1 -0
- package/dist/index.d.ts +2 -0
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +5 -0
- package/dist/index.js.map +1 -1
- package/dist/journal-ledger-index.test.d.ts +15 -0
- package/dist/journal-ledger-index.test.d.ts.map +1 -0
- package/dist/journal-ledger-index.test.js +247 -0
- package/dist/journal-ledger-index.test.js.map +1 -0
- package/dist/journal.d.ts +110 -0
- package/dist/journal.d.ts.map +1 -1
- package/dist/journal.js +253 -5
- package/dist/journal.js.map +1 -1
- package/dist/manifest/US-002.acceptance.test.d.ts +11 -0
- package/dist/manifest/US-002.acceptance.test.d.ts.map +1 -0
- package/dist/manifest/US-002.acceptance.test.js +160 -0
- package/dist/manifest/US-002.acceptance.test.js.map +1 -0
- package/dist/manifest/US-004.acceptance.test.d.ts +12 -0
- package/dist/manifest/US-004.acceptance.test.d.ts.map +1 -0
- package/dist/manifest/US-004.acceptance.test.js +173 -0
- package/dist/manifest/US-004.acceptance.test.js.map +1 -0
- package/dist/manifest/build-manifest.bench.test.d.ts +22 -0
- package/dist/manifest/build-manifest.bench.test.d.ts.map +1 -0
- package/dist/manifest/build-manifest.bench.test.js +563 -0
- package/dist/manifest/build-manifest.bench.test.js.map +1 -0
- package/dist/manifest/build-manifest.d.ts +355 -0
- package/dist/manifest/build-manifest.d.ts.map +1 -0
- package/dist/manifest/build-manifest.js +1139 -0
- package/dist/manifest/build-manifest.js.map +1 -0
- package/dist/manifest/build-manifest.test.d.ts +10 -0
- package/dist/manifest/build-manifest.test.d.ts.map +1 -0
- package/dist/manifest/build-manifest.test.js +1172 -0
- package/dist/manifest/build-manifest.test.js.map +1 -0
- package/dist/manifest/contract.d.ts +356 -0
- package/dist/manifest/contract.d.ts.map +1 -0
- package/dist/manifest/contract.js +542 -0
- package/dist/manifest/contract.js.map +1 -0
- package/dist/manifest/contract.test.d.ts +17 -0
- package/dist/manifest/contract.test.d.ts.map +1 -0
- package/dist/manifest/contract.test.js +304 -0
- package/dist/manifest/contract.test.js.map +1 -0
- package/dist/manifest/import-graph.test.d.ts +25 -0
- package/dist/manifest/import-graph.test.d.ts.map +1 -0
- package/dist/manifest/import-graph.test.js +120 -0
- package/dist/manifest/import-graph.test.js.map +1 -0
- package/dist/manifest/ledger-shard-isolation.test.d.ts +18 -0
- package/dist/manifest/ledger-shard-isolation.test.d.ts.map +1 -0
- package/dist/manifest/ledger-shard-isolation.test.js +153 -0
- package/dist/manifest/ledger-shard-isolation.test.js.map +1 -0
- package/dist/manifest/snapshot-store.d.ts +160 -0
- package/dist/manifest/snapshot-store.d.ts.map +1 -0
- package/dist/manifest/snapshot-store.js +300 -0
- package/dist/manifest/snapshot-store.js.map +1 -0
- package/dist/manifest/snapshot-store.test.d.ts +11 -0
- package/dist/manifest/snapshot-store.test.d.ts.map +1 -0
- package/dist/manifest/snapshot-store.test.js +133 -0
- package/dist/manifest/snapshot-store.test.js.map +1 -0
- package/dist/manifest/upload-manifest.d.ts +336 -0
- package/dist/manifest/upload-manifest.d.ts.map +1 -0
- package/dist/manifest/upload-manifest.js +1022 -0
- package/dist/manifest/upload-manifest.js.map +1 -0
- package/dist/manifest/upload-manifest.test.d.ts +10 -0
- package/dist/manifest/upload-manifest.test.d.ts.map +1 -0
- package/dist/manifest/upload-manifest.test.js +1116 -0
- package/dist/manifest/upload-manifest.test.js.map +1 -0
- package/dist/manifest-reconcile.d.ts.map +1 -1
- package/dist/manifest-reconcile.js +1 -26
- package/dist/manifest-reconcile.js.map +1 -1
- package/dist/posix-key.d.ts +36 -0
- package/dist/posix-key.d.ts.map +1 -0
- package/dist/posix-key.js +38 -0
- package/dist/posix-key.js.map +1 -0
- package/dist/s3.d.ts +2 -18
- package/dist/s3.d.ts.map +1 -1
- package/dist/s3.js +6 -20
- package/dist/s3.js.map +1 -1
- package/dist/sync/journal-ledger-stream.d.ts +56 -0
- package/dist/sync/journal-ledger-stream.d.ts.map +1 -0
- package/dist/sync/journal-ledger-stream.js +191 -0
- package/dist/sync/journal-ledger-stream.js.map +1 -0
- package/dist/sync/journal-ledger-stream.test.d.ts +12 -0
- package/dist/sync/journal-ledger-stream.test.d.ts.map +1 -0
- package/dist/sync/journal-ledger-stream.test.js +134 -0
- package/dist/sync/journal-ledger-stream.test.js.map +1 -0
- package/package.json +2 -1
|
@@ -0,0 +1,133 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Snapshot-store hardening regressions (US-002, Codex review).
|
|
3
|
+
*
|
|
4
|
+
* The store's contract is "tolerate corruption, return null or a clean
|
|
5
|
+
* subset" — it must never throw, and it must never hand the builder a row it
|
|
6
|
+
* would not have produced itself. That second half is the sharp edge: snapshot
|
|
7
|
+
* KEYS flow straight into the next delta's `removedPaths`, so a key the
|
|
8
|
+
* contract would reject is a claimed deletion the server cannot even parse.
|
|
9
|
+
*/
|
|
10
|
+
import * as fs from "node:fs";
|
|
11
|
+
import * as os from "node:os";
|
|
12
|
+
import * as path from "node:path";
|
|
13
|
+
import { afterEach, beforeEach, describe, expect, it } from "vitest";
|
|
14
|
+
import { validateSyncManifestUpload } from "./contract.js";
|
|
15
|
+
import { buildSyncManifest } from "./build-manifest.js";
|
|
16
|
+
import { MANIFEST_SNAPSHOT_DIRNAME, manifestSnapshotPath, manifestSnapshotScopeKey, readManifestSnapshot, } from "./snapshot-store.js";
|
|
17
|
+
const NOW_MS = Date.parse("2026-09-04T12:00:00.000Z");
|
|
18
|
+
const VALID_ROW = { hash: "a".repeat(64), size: 1, mtimeMs: NOW_MS };
|
|
19
|
+
let hqRoot;
|
|
20
|
+
let stateDir;
|
|
21
|
+
beforeEach(() => {
|
|
22
|
+
const base = fs.mkdtempSync(path.join(os.tmpdir(), "hq-manifest-snap-"));
|
|
23
|
+
hqRoot = path.join(base, "hq");
|
|
24
|
+
stateDir = path.join(base, "state");
|
|
25
|
+
fs.mkdirSync(hqRoot, { recursive: true });
|
|
26
|
+
fs.mkdirSync(stateDir, { recursive: true });
|
|
27
|
+
});
|
|
28
|
+
afterEach(() => {
|
|
29
|
+
fs.rmSync(path.dirname(hqRoot), { recursive: true, force: true });
|
|
30
|
+
});
|
|
31
|
+
/** Write a snapshot file BY HAND — the point is payloads the writer never emits. */
|
|
32
|
+
function writeRawSnapshot(scopeKey, entries) {
|
|
33
|
+
const target = manifestSnapshotPath(stateDir, scopeKey);
|
|
34
|
+
fs.mkdirSync(path.dirname(target), { recursive: true });
|
|
35
|
+
const payload = {
|
|
36
|
+
snapshotId: "snap-deadbeefdeadbeefdeadbeefdeadbeef",
|
|
37
|
+
generatedAt: new Date(NOW_MS - 60_000).toISOString(),
|
|
38
|
+
sequence: 6,
|
|
39
|
+
entries,
|
|
40
|
+
};
|
|
41
|
+
fs.writeFileSync(target, `${JSON.stringify(payload)}\n`, "utf8");
|
|
42
|
+
}
|
|
43
|
+
describe("readManifestSnapshot — key validation", () => {
|
|
44
|
+
it.each([
|
|
45
|
+
["absolute", "/etc/passwd"],
|
|
46
|
+
["parent escape", "../../etc/passwd"],
|
|
47
|
+
["dot segment", "notes/./file.md"],
|
|
48
|
+
["backslash separator", "notes\\file.md"],
|
|
49
|
+
["drive letter", "C:/secrets.md"],
|
|
50
|
+
["home relative", "~/secrets.md"],
|
|
51
|
+
["trailing slash", "notes/"],
|
|
52
|
+
["empty", ""],
|
|
53
|
+
["NFD", "notes/cafe\u0301.md"],
|
|
54
|
+
])("drops a %s key while keeping the valid rows", (_label, badKey) => {
|
|
55
|
+
writeRawSnapshot("personal", { [badKey]: VALID_ROW, "notes/keep.md": VALID_ROW });
|
|
56
|
+
const snapshot = readManifestSnapshot(stateDir, "personal");
|
|
57
|
+
expect(snapshot).not.toBeNull();
|
|
58
|
+
expect(Object.keys(snapshot?.entries ?? {})).toEqual(["notes/keep.md"]);
|
|
59
|
+
});
|
|
60
|
+
it("keeps a literal __proto__ row as an own property instead of mutating the object", () => {
|
|
61
|
+
// Built via `fromEntries` because `{ __proto__: … }` in a literal sets the
|
|
62
|
+
// prototype rather than creating the key we are trying to test.
|
|
63
|
+
writeRawSnapshot("personal", Object.fromEntries([
|
|
64
|
+
["__proto__", VALID_ROW],
|
|
65
|
+
["notes/keep.md", VALID_ROW],
|
|
66
|
+
]));
|
|
67
|
+
const snapshot = readManifestSnapshot(stateDir, "personal");
|
|
68
|
+
// `__proto__` is a perfectly legal filename AND a legal contract path, so
|
|
69
|
+
// it must survive — as a ROW. On a `{}` literal the assignment would have
|
|
70
|
+
// been swallowed by the prototype setter instead.
|
|
71
|
+
expect(Object.prototype.hasOwnProperty.call(snapshot.entries, "__proto__")).toBe(true);
|
|
72
|
+
expect(Object.getPrototypeOf(snapshot.entries)).toBeNull();
|
|
73
|
+
// Nothing leaked onto the shared prototype.
|
|
74
|
+
expect(({}.hash)).toBeUndefined();
|
|
75
|
+
expect(Object.keys(snapshot.entries).sort()).toEqual(["__proto__", "notes/keep.md"]);
|
|
76
|
+
});
|
|
77
|
+
it("still returns null (never throws) for structurally broken payloads", () => {
|
|
78
|
+
const target = manifestSnapshotPath(stateDir, "personal");
|
|
79
|
+
fs.mkdirSync(path.dirname(target), { recursive: true });
|
|
80
|
+
fs.writeFileSync(target, "{not json", "utf8");
|
|
81
|
+
expect(readManifestSnapshot(stateDir, "personal")).toBeNull();
|
|
82
|
+
});
|
|
83
|
+
});
|
|
84
|
+
describe("buildSyncManifest — a corrupt snapshot cannot poison removedPaths", () => {
|
|
85
|
+
it("never emits an unrepresentable snapshot key as a removal", async () => {
|
|
86
|
+
fs.mkdirSync(path.join(hqRoot, "notes"), { recursive: true });
|
|
87
|
+
fs.writeFileSync(path.join(hqRoot, "notes", "keep.md"), "hello", "utf8");
|
|
88
|
+
writeRawSnapshot("personal", {
|
|
89
|
+
"/etc/passwd": VALID_ROW,
|
|
90
|
+
"../../escape.md": VALID_ROW,
|
|
91
|
+
"notes/gone.md": VALID_ROW,
|
|
92
|
+
});
|
|
93
|
+
const result = await buildSyncManifest({
|
|
94
|
+
scope: { kind: "personal" },
|
|
95
|
+
hqRoot,
|
|
96
|
+
stateDir,
|
|
97
|
+
installationId: "install-abc123",
|
|
98
|
+
machineId: "machine-abc123",
|
|
99
|
+
source: "cli",
|
|
100
|
+
sequence: 7,
|
|
101
|
+
now: NOW_MS,
|
|
102
|
+
listJournalsImpl: () => [],
|
|
103
|
+
});
|
|
104
|
+
expect(result.mode).toBe("delta");
|
|
105
|
+
// Only the genuinely deleted, genuinely representable path is claimed.
|
|
106
|
+
expect(result.chunks[0].removedPaths).toEqual(["notes/gone.md"]);
|
|
107
|
+
// And the chunk is something the server can actually parse — an absolute
|
|
108
|
+
// path in `removedPaths` fails the contract outright.
|
|
109
|
+
expect(() => validateSyncManifestUpload(result.chunks[0])).not.toThrow();
|
|
110
|
+
});
|
|
111
|
+
});
|
|
112
|
+
describe("manifestSnapshotPath — tenant isolation", () => {
|
|
113
|
+
it("gives two company scopes that sanitize alike DIFFERENT snapshot files", () => {
|
|
114
|
+
// The contract's identifier rule admits `.` and `:` inside a companyUid,
|
|
115
|
+
// and the filename sanitizer collapses both to `_`. Without a disambiguator
|
|
116
|
+
// these two tenants would share one delta base — and the second scope's
|
|
117
|
+
// delta would then claim every file of the first as `removedPaths`.
|
|
118
|
+
const first = manifestSnapshotPath(stateDir, manifestSnapshotScopeKey({ kind: "company", companyUid: "acme.eu" }));
|
|
119
|
+
const second = manifestSnapshotPath(stateDir, manifestSnapshotScopeKey({ kind: "company", companyUid: "acme:eu" }));
|
|
120
|
+
expect(first).not.toBe(second);
|
|
121
|
+
});
|
|
122
|
+
it("never lets a scope key escape the snapshot directory", () => {
|
|
123
|
+
const dir = path.join(stateDir, MANIFEST_SNAPSHOT_DIRNAME);
|
|
124
|
+
for (const uid of ["../../etc/passwd", "a/b", "a\\b", ".."]) {
|
|
125
|
+
const file = manifestSnapshotPath(stateDir, `company:${uid}`);
|
|
126
|
+
expect(path.dirname(file)).toBe(dir);
|
|
127
|
+
}
|
|
128
|
+
});
|
|
129
|
+
it("keeps personal and company scopes on separate files", () => {
|
|
130
|
+
expect(manifestSnapshotPath(stateDir, manifestSnapshotScopeKey({ kind: "personal" }))).not.toBe(manifestSnapshotPath(stateDir, manifestSnapshotScopeKey({ kind: "company", companyUid: "personal" })));
|
|
131
|
+
});
|
|
132
|
+
});
|
|
133
|
+
//# sourceMappingURL=snapshot-store.test.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"snapshot-store.test.js","sourceRoot":"","sources":["../../src/manifest/snapshot-store.test.ts"],"names":[],"mappings":"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"}
|
|
@@ -0,0 +1,336 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Client-side manifest UPLOAD pass (sync-reconciliation-audit US-004).
|
|
3
|
+
*
|
|
4
|
+
* WHY THIS SEAM LIVES IN hq-cloud
|
|
5
|
+
* -------------------------------
|
|
6
|
+
* Two clients upload manifests — the desktop sync daemon (hq-sync) after a
|
|
7
|
+
* sync cycle, and `hq sync manifest` in the CLI — and the PRD's decision
|
|
8
|
+
* record settles it as "both, via shared hq-cloud code". The rules that make
|
|
9
|
+
* an upload SAFE are not obvious and must not be re-derived twice:
|
|
10
|
+
*
|
|
11
|
+
* - a snapshot may become the local delta BASE only after the server says
|
|
12
|
+
* `materialised: true` (a `completed` fold that was refused is not a base);
|
|
13
|
+
* - the delta base is the snapshotId the SERVER returns, never the local
|
|
14
|
+
* `snap-*` handle the builder minted (the server derives its own id);
|
|
15
|
+
* - `sequence` must strictly increase per (installation, scope), including
|
|
16
|
+
* across passes that failed before they uploaded anything;
|
|
17
|
+
* - every chunk of one pass must be byte-identical in the fields the server
|
|
18
|
+
* hashes into the snapshotId (`generatedAt`, `sequence`, `chunkCount`,
|
|
19
|
+
* `machineId`, `mode`, `scope`);
|
|
20
|
+
* - a `resend_full` at ANY chunk ends the pass and invalidates the base.
|
|
21
|
+
*
|
|
22
|
+
* Two implementations of those rules would drift, and the failure mode of the
|
|
23
|
+
* drift is silent server-side corruption of a scope's materialised view — the
|
|
24
|
+
* exact thing this audit exists to detect.
|
|
25
|
+
*
|
|
26
|
+
* WHAT THIS DELIBERATELY DOES NOT OWN
|
|
27
|
+
* -----------------------------------
|
|
28
|
+
* - **Auth and the base URL.** The transport is INJECTED. hq-cloud has no
|
|
29
|
+
* business deciding which API host a daemon talks to or how a JWT is
|
|
30
|
+
* minted; the clients already own both, and owning them here would force
|
|
31
|
+
* this module to import the vault client (and with it the AWS SDK) into
|
|
32
|
+
* what is otherwise a lean, hot-path module graph.
|
|
33
|
+
* - **Scheduling.** The caller decides when a pass runs; this function only
|
|
34
|
+
* refuses to run one too often (see the 24h throttle).
|
|
35
|
+
* - **Wiring.** The hq-cli `sync manifest` command, its `hq doctor` check,
|
|
36
|
+
* and the hq-sync daemon hook land SEPARATELY, in those repos, on top of
|
|
37
|
+
* {@link runManifestUploadPass} and {@link readManifestUploadStatus}.
|
|
38
|
+
*
|
|
39
|
+
* FAILURE POSTURE
|
|
40
|
+
* ---------------
|
|
41
|
+
* This never throws at the caller for anything that happens at runtime. The
|
|
42
|
+
* daemon calls it after a sync pass and must continue regardless: an audit
|
|
43
|
+
* that can break sync is strictly worse than no audit. Build errors, transport
|
|
44
|
+
* rejections, aborts and unexpected statuses all come back as
|
|
45
|
+
* `{ status: "failed" }`. Only invalid OPTIONS — a programmer error, not a
|
|
46
|
+
* runtime condition — throw.
|
|
47
|
+
*/
|
|
48
|
+
import { type BuildManifestScope, type ManifestHashPolicy } from "./build-manifest.js";
|
|
49
|
+
import type { JournalSummary } from "../journal.js";
|
|
50
|
+
import { type SyncManifestMode, type SyncManifestSource, type SyncManifestUpload } from "./contract.js";
|
|
51
|
+
import { MANIFEST_SNAPSHOT_MAX_AGE_MS } from "./snapshot-store.js";
|
|
52
|
+
/**
|
|
53
|
+
* Env var that disables manifest uploads entirely. A user (or a support
|
|
54
|
+
* engineer) must be able to switch this feature off on a machine WITHOUT
|
|
55
|
+
* downgrading hq-cloud, and the switch must short-circuit before the walk —
|
|
56
|
+
* the walk, not the POST, is the expensive half.
|
|
57
|
+
*/
|
|
58
|
+
export declare const MANIFEST_UPLOAD_DISABLED_ENV = "HQ_SYNC_MANIFEST_DISABLED";
|
|
59
|
+
/**
|
|
60
|
+
* Default minimum spacing between upload passes for one scope.
|
|
61
|
+
*
|
|
62
|
+
* The audit is a slow-moving safety net, not telemetry: a daily picture is
|
|
63
|
+
* enough to catch a wedged watcher, and a 70k-file walk per sync cycle is not
|
|
64
|
+
* something a laptop should pay for.
|
|
65
|
+
*/
|
|
66
|
+
export declare const DEFAULT_MANIFEST_UPLOAD_MIN_INTERVAL_MS: number;
|
|
67
|
+
/**
|
|
68
|
+
* Wall-clock budget for the ENTIRE upload phase (all chunks), after which the
|
|
69
|
+
* pass stops sending and reports a non-throwing failure.
|
|
70
|
+
*
|
|
71
|
+
* Why the whole phase and not per chunk: the caller's actual requirement is
|
|
72
|
+
* "the daemon's `await` returns" — the desktop daemon runs this after every
|
|
73
|
+
* sync pass, and a transport that never settles would otherwise wedge the pass
|
|
74
|
+
* (and the sync cycle behind it) forever. A per-chunk budget would not bound
|
|
75
|
+
* that: a 30-chunk manifest would still admit 30 x budget of hanging. One
|
|
76
|
+
* budget for the phase bounds the pass by construction, whatever the chunk
|
|
77
|
+
* count.
|
|
78
|
+
*
|
|
79
|
+
* 60s is generous next to a single small JSON POST and mean next to a sync
|
|
80
|
+
* cycle, so it only ever fires on a genuinely wedged transport — never on a
|
|
81
|
+
* merely slow link, where the pass would be retried next cycle anyway.
|
|
82
|
+
*
|
|
83
|
+
* Note this bounds only the UPLOAD; `maxWallMs` bounds the filesystem walk.
|
|
84
|
+
* They are separate budgets because they fail for unrelated reasons (a slow
|
|
85
|
+
* disk vs. a black-holed socket) and a caller may reasonably tune one alone.
|
|
86
|
+
*/
|
|
87
|
+
export declare const DEFAULT_MANIFEST_UPLOAD_WALL_MS = 60000;
|
|
88
|
+
/**
|
|
89
|
+
* First retry floor after a pass FAILED without reaching the server.
|
|
90
|
+
*
|
|
91
|
+
* The 24h throttle is armed by `lastUploadAt`, which only a pass that actually
|
|
92
|
+
* reached the server writes. That is correct — a network blip must not
|
|
93
|
+
* suppress the audit for a day — but taken alone it means a permanently broken
|
|
94
|
+
* endpoint (a wrong base URL, an unenrolled installation answering 403, a 5xx
|
|
95
|
+
* outage) buys a FULL tree walk, and under `hashPolicy: "auto"` a full content
|
|
96
|
+
* hash, on EVERY sync cycle. On a large vault that is minutes of IO and
|
|
97
|
+
* gigabytes of RSS per cycle, forever, for an audit that cannot succeed.
|
|
98
|
+
*
|
|
99
|
+
* So a failed pass arms its own, much shorter floor, doubling per consecutive
|
|
100
|
+
* failure up to {@link MANIFEST_FAILURE_BACKOFF_MAX_MS}. One hour keeps a
|
|
101
|
+
* transient outage cheap to recover from (the next hourly cycle retries) while
|
|
102
|
+
* capping a hard failure's cost at ~1 walk/hour instead of 1 walk/cycle.
|
|
103
|
+
*/
|
|
104
|
+
export declare const MANIFEST_FAILURE_BACKOFF_BASE_MS: number;
|
|
105
|
+
/** Ceiling for the failure backoff — the same daily spacing a healthy scope gets. */
|
|
106
|
+
export declare const MANIFEST_FAILURE_BACKOFF_MAX_MS: number;
|
|
107
|
+
/**
|
|
108
|
+
* Share of `source: "disk"` entries above which a FULL manifest is treated as
|
|
109
|
+
* an implausible picture of a scope that was previously tracked.
|
|
110
|
+
*
|
|
111
|
+
* Set hard against 1.0 rather than at a "suspicious" level like 0.9 on
|
|
112
|
+
* purpose. A legitimate manifest CAN be very disk-heavy — a user who just
|
|
113
|
+
* restored a backup, or a first pass after a journal repair — and refusing
|
|
114
|
+
* those would suppress the audit exactly when it is most useful. The failure
|
|
115
|
+
* this guards is not "mostly disk": it is "the ledger vanished", which is
|
|
116
|
+
* total. 0.995 leaves room for the handful of `ledger`/`both` entries a
|
|
117
|
+
* partially-readable ledger still contributes without admitting a merely
|
|
118
|
+
* lopsided scope.
|
|
119
|
+
*/
|
|
120
|
+
export declare const MANIFEST_IMPLAUSIBLE_DISK_RATIO = 0.995;
|
|
121
|
+
/**
|
|
122
|
+
* Floor the 413 self-heal will not halve below.
|
|
123
|
+
*
|
|
124
|
+
* The halving exists to rescue a scope whose entries are fatter than the
|
|
125
|
+
* default budget assumed; it is not a search for the smallest body the server
|
|
126
|
+
* will take. Below ~256 KiB the chunk count for a large scope climbs past
|
|
127
|
+
* `SYNC_MANIFEST_MAX_CHUNK_COUNT` and the pass would start failing for a
|
|
128
|
+
* second, unrelated reason — and a 413 that survives a budget this small is
|
|
129
|
+
* not a sizing problem at all (a proxy with its own tiny limit, a gateway
|
|
130
|
+
* refusing the route), so halving further would just burn passes hiding it.
|
|
131
|
+
*/
|
|
132
|
+
export declare const MANIFEST_CHUNK_BYTE_BUDGET_FLOOR: number;
|
|
133
|
+
/**
|
|
134
|
+
* The budget to plan the NEXT pass against after this one was refused 413.
|
|
135
|
+
*
|
|
136
|
+
* Halving, not a fixed step, because the client has no information about how
|
|
137
|
+
* far over the line it was: API Gateway's 413 is opaque, and even the
|
|
138
|
+
* server's own rejection reports its ceiling rather than the body's size. A
|
|
139
|
+
* geometric retreat reaches any workable budget in a handful of passes from
|
|
140
|
+
* any starting point, and it converges — a linear step sized for the common
|
|
141
|
+
* case is either too slow for the bad case or overshoots the common one.
|
|
142
|
+
*/
|
|
143
|
+
export declare function nextManifestChunkByteBudget(current: number): number;
|
|
144
|
+
/**
|
|
145
|
+
* Retry floor for a scope that has failed `consecutiveFailures` times in a row.
|
|
146
|
+
*
|
|
147
|
+
* `1 → 1h, 2 → 2h, 3 → 4h … capped at 24h`. Zero (or anything nonsensical)
|
|
148
|
+
* means "no floor": a scope with no failure history is governed by the normal
|
|
149
|
+
* `lastUploadAt` throttle alone.
|
|
150
|
+
*/
|
|
151
|
+
export declare function manifestFailureBackoffMs(consecutiveFailures: number): number;
|
|
152
|
+
/**
|
|
153
|
+
* Only an explicit, unambiguous value disables. Empty string, `0`, `false` and
|
|
154
|
+
* anything else mean "not set": env vars are routinely exported empty by
|
|
155
|
+
* shell wrappers, and treating that as "off" would silently disable the
|
|
156
|
+
* feature on machines nobody meant to opt out.
|
|
157
|
+
*/
|
|
158
|
+
/**
|
|
159
|
+
* The kill switch, readable by a CALLER.
|
|
160
|
+
*
|
|
161
|
+
* `runManifestUploadPass` enforces it itself, but a caller that assembles the
|
|
162
|
+
* pass (resolving identity, minting a transport, choosing scopes) needs to
|
|
163
|
+
* check it BEFORE doing any of that, so an opted-out machine pays literally
|
|
164
|
+
* nothing. Exported rather than duplicated so the two can never disagree about
|
|
165
|
+
* what counts as "disabled".
|
|
166
|
+
*/
|
|
167
|
+
export declare function isManifestUploadDisabled(env: NodeJS.ProcessEnv): boolean;
|
|
168
|
+
/** Raw HTTP response, reduced to the two things the pass reasons about. */
|
|
169
|
+
export interface ManifestUploadResponse {
|
|
170
|
+
status: number;
|
|
171
|
+
body?: unknown;
|
|
172
|
+
}
|
|
173
|
+
/**
|
|
174
|
+
* Injected by hq-sync / hq-cli: POSTs one chunk to
|
|
175
|
+
* `POST /v1/sync-manifest/upload` with the caller's own JWT and base URL.
|
|
176
|
+
*
|
|
177
|
+
* It must RESOLVE with the status for any HTTP answer (including 4xx/5xx) and
|
|
178
|
+
* may reject only for transport-level failures; a rejection is caught and
|
|
179
|
+
* reported as a failed pass either way.
|
|
180
|
+
*/
|
|
181
|
+
export type ManifestUploadTransport = (chunk: SyncManifestUpload, ctx: {
|
|
182
|
+
attempt: number;
|
|
183
|
+
}) => Promise<ManifestUploadResponse>;
|
|
184
|
+
export interface ManifestUploadLogger {
|
|
185
|
+
info?: (message: string, meta?: Record<string, unknown>) => void;
|
|
186
|
+
warn?: (message: string, meta?: Record<string, unknown>) => void;
|
|
187
|
+
error?: (message: string, meta?: Record<string, unknown>) => void;
|
|
188
|
+
}
|
|
189
|
+
export interface RunManifestUploadPassOptions {
|
|
190
|
+
scope: BuildManifestScope;
|
|
191
|
+
hqRoot: string;
|
|
192
|
+
stateDir: string;
|
|
193
|
+
/** The SAME installation id the client-health heartbeat reports. */
|
|
194
|
+
installationId: string;
|
|
195
|
+
machineId: string;
|
|
196
|
+
source: SyncManifestSource;
|
|
197
|
+
transport: ManifestUploadTransport;
|
|
198
|
+
/** Injected clock (epoch ms) — tests pin it; production omits it. */
|
|
199
|
+
now?: number;
|
|
200
|
+
/** Injected env — tests pin it; production reads `process.env`. */
|
|
201
|
+
env?: NodeJS.ProcessEnv;
|
|
202
|
+
/** `--full`: skip the delta base and send a fresh baseline. */
|
|
203
|
+
forceFull?: boolean;
|
|
204
|
+
/** `--print`: build only. Never uploads, never persists a snapshot. */
|
|
205
|
+
dryRun?: boolean;
|
|
206
|
+
/**
|
|
207
|
+
* Explicit, human-initiated invocations (`hq sync manifest`) may bypass the
|
|
208
|
+
* throttle. The DAEMON path must not — that is the whole point of it.
|
|
209
|
+
*/
|
|
210
|
+
ignoreThrottle?: boolean;
|
|
211
|
+
minIntervalMs?: number;
|
|
212
|
+
abortSignal?: AbortSignal;
|
|
213
|
+
/** Wall-clock bound on the tree WALK (forwarded to the builder). */
|
|
214
|
+
maxWallMs?: number;
|
|
215
|
+
/**
|
|
216
|
+
* Forwarded to the builder. Omitted means the builder's stat-only default,
|
|
217
|
+
* which is what the daemon must use. `full` is reserved for an explicit
|
|
218
|
+
* human invocation (`hq sync manifest --full-hash`).
|
|
219
|
+
*/
|
|
220
|
+
hashPolicy?: ManifestHashPolicy;
|
|
221
|
+
/** `auto` only, forwarded to the builder: files this pass may read. */
|
|
222
|
+
maxHashedFiles?: number;
|
|
223
|
+
/** `auto` only, forwarded to the builder: wall clock spent hashing. */
|
|
224
|
+
maxHashMs?: number;
|
|
225
|
+
/**
|
|
226
|
+
* Wall-clock bound on the whole UPLOAD phase. See
|
|
227
|
+
* {@link DEFAULT_MANIFEST_UPLOAD_WALL_MS}. Measured against the real clock,
|
|
228
|
+
* not `now` — `now` pins the manifest's CONTENT (so a pass is reproducible),
|
|
229
|
+
* while this is about how long a caller is prepared to be blocked.
|
|
230
|
+
*/
|
|
231
|
+
uploadWallMs?: number;
|
|
232
|
+
logger?: ManifestUploadLogger;
|
|
233
|
+
/** Test seam, forwarded to the builder: stands in for the real `listJournals()`. */
|
|
234
|
+
listJournalsImpl?: () => JournalSummary[];
|
|
235
|
+
/**
|
|
236
|
+
* Test seam, forwarded to the builder: entries per chunk. Production leaves
|
|
237
|
+
* it unset and gets the contract ceiling; tests shrink it so the multi-chunk
|
|
238
|
+
* paths (ordering, shared header, mid-pass abort) are actually reachable.
|
|
239
|
+
*/
|
|
240
|
+
maxEntriesPerChunk?: number;
|
|
241
|
+
/**
|
|
242
|
+
* Serialised-byte budget for one chunk.
|
|
243
|
+
*
|
|
244
|
+
* Unlike `maxEntriesPerChunk` this is NOT purely a test seam — an explicit
|
|
245
|
+
* value here overrides the self-healed budget stored on the snapshot, which
|
|
246
|
+
* is how an operator un-sticks a scope that halved its way down to the floor
|
|
247
|
+
* against a transient gateway fault. Omitted (the normal case) means "the
|
|
248
|
+
* stored budget, or the contract default".
|
|
249
|
+
*/
|
|
250
|
+
chunkByteBudget?: number;
|
|
251
|
+
}
|
|
252
|
+
export type ManifestUploadPassStatus = "disabled" | "throttled" | "locked" | "uploaded" | "printed" | "soft_skipped" | "resend_full_scheduled"
|
|
253
|
+
/**
|
|
254
|
+
* The tree walk did not finish (wall clock or abort), so the manifest
|
|
255
|
+
* describes only the part of the scope the walker reached. NOTHING is
|
|
256
|
+
* uploaded on this path: a truncated walk of a large vault can legitimately
|
|
257
|
+
* yield ZERO entries, and a full-mode manifest with zero entries tells the
|
|
258
|
+
* server this client holds nothing at all — which it would then act on. The
|
|
259
|
+
* pass burns its sequence, arms the failure backoff, and retries later.
|
|
260
|
+
*/
|
|
261
|
+
| "walk_truncated"
|
|
262
|
+
/**
|
|
263
|
+
* The built manifest is a FULL statement that this machine holds nothing it
|
|
264
|
+
* has ever tracked — every entry `source: "disk"` — while a prior local
|
|
265
|
+
* snapshot for the same scope says otherwise. NOTHING is uploaded.
|
|
266
|
+
*
|
|
267
|
+
* Found on a real machine: every generation of the scope's v3 ledger store
|
|
268
|
+
* (`snapshot-*.bin` and `wal-*.bin`) was truncated and no legacy shard
|
|
269
|
+
* existed, so the ledger read came back empty, all 188,997 files walked read
|
|
270
|
+
* as on-disk-never-tracked, and the pass uploaded that as the truth. The
|
|
271
|
+
* ledger read itself is fixed (an unreadable ledger is no longer an empty
|
|
272
|
+
* one), but this is the backstop for the class: whatever makes the ledger
|
|
273
|
+
* silently disappear next time, a scope does not go from "fully tracked" to
|
|
274
|
+
* "nothing tracked" in one cycle.
|
|
275
|
+
*/
|
|
276
|
+
| "ledger_implausible" | "failed";
|
|
277
|
+
export type ManifestUploadFailureKind = "build_error" | "transport_error" | "aborted" | "upload_timeout" | "chunk_too_large" | "manifest_too_large" | "rejected";
|
|
278
|
+
export interface ManifestUploadFailure {
|
|
279
|
+
kind: ManifestUploadFailureKind;
|
|
280
|
+
/** HTTP status, when the failure came from a response rather than a throw. */
|
|
281
|
+
status?: number;
|
|
282
|
+
/** Error CLASS name or server reason code — never a message with paths in it. */
|
|
283
|
+
detail?: string;
|
|
284
|
+
chunkIndex?: number;
|
|
285
|
+
}
|
|
286
|
+
export interface RunManifestUploadPassResult {
|
|
287
|
+
status: ManifestUploadPassStatus;
|
|
288
|
+
scopeKey: string;
|
|
289
|
+
snapshotId?: string;
|
|
290
|
+
mode?: SyncManifestMode;
|
|
291
|
+
chunkCount?: number;
|
|
292
|
+
uploadedChunks?: number;
|
|
293
|
+
/** The byte budget this pass planned against; useful in a 413 post-mortem. */
|
|
294
|
+
chunkByteBudget?: number;
|
|
295
|
+
/** True when the NEXT pass must send a full manifest. */
|
|
296
|
+
nextModeFull?: boolean;
|
|
297
|
+
/** Populated only for `dryRun` — the built chunks, unsent. */
|
|
298
|
+
chunks?: SyncManifestUpload[];
|
|
299
|
+
error?: ManifestUploadFailure;
|
|
300
|
+
}
|
|
301
|
+
/** Per-scope upload state, for `hq doctor`'s `manifest` check. */
|
|
302
|
+
export interface ManifestUploadStatus {
|
|
303
|
+
scopeKey: string;
|
|
304
|
+
lastUploadAt: string | null;
|
|
305
|
+
snapshotId: string | null;
|
|
306
|
+
sequence: number;
|
|
307
|
+
/** False when the stored record is bookkeeping-only (next pass is full). */
|
|
308
|
+
baseUsable: boolean;
|
|
309
|
+
}
|
|
310
|
+
/**
|
|
311
|
+
* The `command` recorded in the lock file. It shows up verbatim in
|
|
312
|
+
* `OperationLockedError` messages and in `hq doctor`-style lock dumps, so it
|
|
313
|
+
* names the operation a human would recognise.
|
|
314
|
+
*/
|
|
315
|
+
export declare const MANIFEST_UPLOAD_LOCK_COMMAND = "sync-manifest";
|
|
316
|
+
/**
|
|
317
|
+
* Build and upload one scope's manifest.
|
|
318
|
+
*
|
|
319
|
+
* Chunks go up SEQUENTIALLY in ascending `chunkIndex`: the server folds them
|
|
320
|
+
* into one snapshot keyed by a hash of the shared header fields, and a
|
|
321
|
+
* concurrent send would make a partial-failure state (some chunks in, some
|
|
322
|
+
* not) impossible to reason about from the client side.
|
|
323
|
+
*/
|
|
324
|
+
export declare function runManifestUploadPass(options: RunManifestUploadPassOptions): Promise<RunManifestUploadPassResult>;
|
|
325
|
+
/**
|
|
326
|
+
* Read per-scope upload state without touching the network or the disk tree.
|
|
327
|
+
*
|
|
328
|
+
* This is the seam `hq doctor`'s `manifest` check consumes: it answers "when
|
|
329
|
+
* did this machine last tell the server what it holds?" for each scope, which
|
|
330
|
+
* is the one question that distinguishes "no findings" from "no data".
|
|
331
|
+
* Missing/older snapshots report `lastUploadAt: null` — never uploaded.
|
|
332
|
+
*/
|
|
333
|
+
export declare function readManifestUploadStatus(stateDir: string, scopes: readonly BuildManifestScope[]): ManifestUploadStatus[];
|
|
334
|
+
/** Re-exported so callers do not need a second import for the staleness rule. */
|
|
335
|
+
export { MANIFEST_SNAPSHOT_MAX_AGE_MS };
|
|
336
|
+
//# sourceMappingURL=upload-manifest.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"upload-manifest.d.ts","sourceRoot":"","sources":["../../src/manifest/upload-manifest.ts"],"names":[],"mappings":"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"}
|