@narumitw/pi-sync-daemon 0.0.0-stage → 0.3.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.
Files changed (267) hide show
  1. package/CHANGELOG.md +22 -0
  2. package/LICENSE +21 -0
  3. package/README.md +91 -2
  4. package/dist/cli.d.ts +2 -0
  5. package/dist/cli.js +127 -0
  6. package/dist/client.d.ts +57 -0
  7. package/dist/client.js +534 -0
  8. package/dist/consent.d.ts +24 -0
  9. package/dist/consent.js +205 -0
  10. package/dist/document.d.ts +10 -0
  11. package/dist/document.js +6 -0
  12. package/dist/endpoint.d.ts +8 -0
  13. package/dist/endpoint.js +91 -0
  14. package/dist/engine/backends/backend-factory.d.ts +6 -0
  15. package/dist/engine/backends/backend-factory.js +16 -0
  16. package/dist/engine/backends/backend-identity.d.ts +3 -0
  17. package/dist/engine/backends/backend-identity.js +38 -0
  18. package/dist/engine/backends/backend-types.d.ts +70 -0
  19. package/dist/engine/backends/backend-types.js +1 -0
  20. package/dist/engine/backends/git/git-backend.d.ts +55 -0
  21. package/dist/engine/backends/git/git-backend.js +700 -0
  22. package/dist/engine/backends/git/git-config.d.ts +5 -0
  23. package/dist/engine/backends/git/git-config.js +118 -0
  24. package/dist/engine/backends/git/git-runner.d.ts +25 -0
  25. package/dist/engine/backends/git/git-runner.js +232 -0
  26. package/dist/engine/backends/git/git-storage.d.ts +39 -0
  27. package/dist/engine/backends/git/git-storage.js +226 -0
  28. package/dist/engine/backends/s3/s3-backend.d.ts +32 -0
  29. package/dist/engine/backends/s3/s3-backend.js +436 -0
  30. package/dist/engine/backends/s3/s3-client.d.ts +36 -0
  31. package/dist/engine/backends/s3/s3-client.js +352 -0
  32. package/dist/engine/backends/s3/s3-conditions.d.ts +4 -0
  33. package/dist/engine/backends/s3/s3-conditions.js +66 -0
  34. package/dist/engine/backends/snapshot-pointer.d.ts +6 -0
  35. package/dist/engine/backends/snapshot-pointer.js +22 -0
  36. package/dist/engine/backends/sync-backend.d.ts +71 -0
  37. package/dist/engine/backends/sync-backend.js +23 -0
  38. package/dist/engine/backends/webdav/webdav-backend.d.ts +34 -0
  39. package/dist/engine/backends/webdav/webdav-backend.js +534 -0
  40. package/dist/engine/backends/webdav/webdav-client.d.ts +36 -0
  41. package/dist/engine/backends/webdav/webdav-client.js +326 -0
  42. package/dist/engine/backends/webdav/webdav-config.d.ts +5 -0
  43. package/dist/engine/backends/webdav/webdav-config.js +73 -0
  44. package/dist/engine/commands/command-types.d.ts +31 -0
  45. package/dist/engine/commands/command-types.js +1 -0
  46. package/dist/engine/host.d.ts +70 -0
  47. package/dist/engine/host.js +16 -0
  48. package/dist/engine/paths.d.ts +9 -0
  49. package/dist/engine/paths.js +71 -0
  50. package/dist/engine/settings/config-errors.d.ts +1 -0
  51. package/dist/engine/settings/config-errors.js +4 -0
  52. package/dist/engine/settings/config-file.d.ts +33 -0
  53. package/dist/engine/settings/config-file.js +630 -0
  54. package/dist/engine/settings/config.d.ts +24 -0
  55. package/dist/engine/settings/config.js +200 -0
  56. package/dist/engine/settings/settings-management.d.ts +24 -0
  57. package/dist/engine/settings/settings-management.js +191 -0
  58. package/dist/engine/settings/settings-store.d.ts +8 -0
  59. package/dist/engine/settings/settings-store.js +41 -0
  60. package/dist/engine/settings/settings-types.d.ts +134 -0
  61. package/dist/engine/settings/settings-types.js +1 -0
  62. package/dist/engine/settings/settings-validation.d.ts +15 -0
  63. package/dist/engine/settings/settings-validation.js +356 -0
  64. package/dist/engine/snapshot/session-paths.d.ts +12 -0
  65. package/dist/engine/snapshot/session-paths.js +91 -0
  66. package/dist/engine/snapshot/snapshot-apply.d.ts +22 -0
  67. package/dist/engine/snapshot/snapshot-apply.js +262 -0
  68. package/dist/engine/snapshot/snapshot-case-replacement.d.ts +15 -0
  69. package/dist/engine/snapshot/snapshot-case-replacement.js +82 -0
  70. package/dist/engine/snapshot/snapshot-codec.d.ts +6 -0
  71. package/dist/engine/snapshot/snapshot-codec.js +53 -0
  72. package/dist/engine/snapshot/snapshot-exclude-safety.d.ts +7 -0
  73. package/dist/engine/snapshot/snapshot-exclude-safety.js +47 -0
  74. package/dist/engine/snapshot/snapshot-mutation-queues.d.ts +9 -0
  75. package/dist/engine/snapshot/snapshot-mutation-queues.js +133 -0
  76. package/dist/engine/snapshot/snapshot-paths.d.ts +1 -0
  77. package/dist/engine/snapshot/snapshot-paths.js +11 -0
  78. package/dist/engine/snapshot/snapshot-root-transition.d.ts +25 -0
  79. package/dist/engine/snapshot/snapshot-root-transition.js +122 -0
  80. package/dist/engine/snapshot/snapshot-transaction-directory.d.ts +2 -0
  81. package/dist/engine/snapshot/snapshot-transaction-directory.js +16 -0
  82. package/dist/engine/snapshot/snapshot-transaction-plan.d.ts +12 -0
  83. package/dist/engine/snapshot/snapshot-transaction-plan.js +68 -0
  84. package/dist/engine/snapshot/snapshot-transaction.d.ts +15 -0
  85. package/dist/engine/snapshot/snapshot-transaction.js +787 -0
  86. package/dist/engine/snapshot/snapshot-types.d.ts +48 -0
  87. package/dist/engine/snapshot/snapshot-types.js +1 -0
  88. package/dist/engine/snapshot/snapshot.d.ts +30 -0
  89. package/dist/engine/snapshot/snapshot.js +364 -0
  90. package/dist/engine/state/json-file.d.ts +6 -0
  91. package/dist/engine/state/json-file.js +49 -0
  92. package/dist/engine/state/lock-policy.d.ts +2 -0
  93. package/dist/engine/state/lock-policy.js +2 -0
  94. package/dist/engine/state/lock.d.ts +20 -0
  95. package/dist/engine/state/lock.js +259 -0
  96. package/dist/engine/state/lockfile-fs.d.ts +13 -0
  97. package/dist/engine/state/lockfile-fs.js +13 -0
  98. package/dist/engine/state/merge-baseline-store.d.ts +11 -0
  99. package/dist/engine/state/merge-baseline-store.js +187 -0
  100. package/dist/engine/state/mutation-directory-sync.d.ts +5 -0
  101. package/dist/engine/state/mutation-directory-sync.js +34 -0
  102. package/dist/engine/state/operation-availability.d.ts +49 -0
  103. package/dist/engine/state/operation-availability.js +40 -0
  104. package/dist/engine/state/state-directory.d.ts +14 -0
  105. package/dist/engine/state/state-directory.js +225 -0
  106. package/dist/engine/state/state-types.d.ts +27 -0
  107. package/dist/engine/state/state-types.js +1 -0
  108. package/dist/engine/state/sync-state-store.d.ts +11 -0
  109. package/dist/engine/state/sync-state-store.js +54 -0
  110. package/dist/engine/sync/agent-candidate.d.ts +44 -0
  111. package/dist/engine/sync/agent-candidate.js +207 -0
  112. package/dist/engine/sync/agent-plan.d.ts +8 -0
  113. package/dist/engine/sync/agent-plan.js +84 -0
  114. package/dist/engine/sync/agent-policy.d.ts +9 -0
  115. package/dist/engine/sync/agent-policy.js +10 -0
  116. package/dist/engine/sync/agent-refusal-retry.d.ts +4 -0
  117. package/dist/engine/sync/agent-refusal-retry.js +39 -0
  118. package/dist/engine/sync/agent-request.d.ts +14 -0
  119. package/dist/engine/sync/agent-request.js +13 -0
  120. package/dist/engine/sync/agent-runner.d.ts +6 -0
  121. package/dist/engine/sync/agent-runner.js +183 -0
  122. package/dist/engine/sync/agent-store.d.ts +7 -0
  123. package/dist/engine/sync/agent-store.js +177 -0
  124. package/dist/engine/sync/agent-sync.d.ts +4 -0
  125. package/dist/engine/sync/agent-sync.js +132 -0
  126. package/dist/engine/sync/apply-review.d.ts +8 -0
  127. package/dist/engine/sync/apply-review.js +51 -0
  128. package/dist/engine/sync/conflict-artifact-ownership.d.ts +4 -0
  129. package/dist/engine/sync/conflict-artifact-ownership.js +53 -0
  130. package/dist/engine/sync/conflict-artifacts.d.ts +32 -0
  131. package/dist/engine/sync/conflict-artifacts.js +158 -0
  132. package/dist/engine/sync/conflict-groups.d.ts +9 -0
  133. package/dist/engine/sync/conflict-groups.js +76 -0
  134. package/dist/engine/sync/conflict-preview.d.ts +4 -0
  135. package/dist/engine/sync/conflict-preview.js +53 -0
  136. package/dist/engine/sync/conflict-resolution.d.ts +13 -0
  137. package/dist/engine/sync/conflict-resolution.js +53 -0
  138. package/dist/engine/sync/conflict-retention.d.ts +5 -0
  139. package/dist/engine/sync/conflict-retention.js +61 -0
  140. package/dist/engine/sync/conflict-review.d.ts +4 -0
  141. package/dist/engine/sync/conflict-review.js +73 -0
  142. package/dist/engine/sync/content-conflicts.d.ts +10 -0
  143. package/dist/engine/sync/content-conflicts.js +70 -0
  144. package/dist/engine/sync/continuous-errors.d.ts +14 -0
  145. package/dist/engine/sync/continuous-errors.js +66 -0
  146. package/dist/engine/sync/continuous-lease.d.ts +9 -0
  147. package/dist/engine/sync/continuous-lease.js +206 -0
  148. package/dist/engine/sync/continuous-record.d.ts +31 -0
  149. package/dist/engine/sync/continuous-record.js +199 -0
  150. package/dist/engine/sync/continuous-storage.d.ts +14 -0
  151. package/dist/engine/sync/continuous-storage.js +59 -0
  152. package/dist/engine/sync/continuous-sync.d.ts +15 -0
  153. package/dist/engine/sync/continuous-sync.js +496 -0
  154. package/dist/engine/sync/continuous-watch.d.ts +3 -0
  155. package/dist/engine/sync/continuous-watch.js +65 -0
  156. package/dist/engine/sync/exclude-policy.d.ts +5 -0
  157. package/dist/engine/sync/exclude-policy.js +79 -0
  158. package/dist/engine/sync/field-migration.d.ts +5 -0
  159. package/dist/engine/sync/field-migration.js +20 -0
  160. package/dist/engine/sync/file-merge-planner.d.ts +36 -0
  161. package/dist/engine/sync/file-merge-planner.js +123 -0
  162. package/dist/engine/sync/initialization.d.ts +12 -0
  163. package/dist/engine/sync/initialization.js +75 -0
  164. package/dist/engine/sync/json-document.d.ts +29 -0
  165. package/dist/engine/sync/json-document.js +172 -0
  166. package/dist/engine/sync/local-field-policy.d.ts +2 -0
  167. package/dist/engine/sync/local-field-policy.js +26 -0
  168. package/dist/engine/sync/local-fields.d.ts +9 -0
  169. package/dist/engine/sync/local-fields.js +116 -0
  170. package/dist/engine/sync/merge-apply.d.ts +5 -0
  171. package/dist/engine/sync/merge-apply.js +386 -0
  172. package/dist/engine/sync/merge-journal.d.ts +31 -0
  173. package/dist/engine/sync/merge-journal.js +179 -0
  174. package/dist/engine/sync/merge-transfer-error.d.ts +3 -0
  175. package/dist/engine/sync/merge-transfer-error.js +64 -0
  176. package/dist/engine/sync/merged-sync.d.ts +6 -0
  177. package/dist/engine/sync/merged-sync.js +618 -0
  178. package/dist/engine/sync/mutation-owner.d.ts +2 -0
  179. package/dist/engine/sync/mutation-owner.js +18 -0
  180. package/dist/engine/sync/package-merge.d.ts +3 -0
  181. package/dist/engine/sync/package-merge.js +82 -0
  182. package/dist/engine/sync/partial-progress.d.ts +15 -0
  183. package/dist/engine/sync/partial-progress.js +39 -0
  184. package/dist/engine/sync/remote-snapshot.d.ts +28 -0
  185. package/dist/engine/sync/remote-snapshot.js +62 -0
  186. package/dist/engine/sync/resolver-stream.d.ts +4 -0
  187. package/dist/engine/sync/resolver-stream.js +34 -0
  188. package/dist/engine/sync/session-merge.d.ts +3 -0
  189. package/dist/engine/sync/session-merge.js +178 -0
  190. package/dist/engine/sync/session-push.d.ts +5 -0
  191. package/dist/engine/sync/session-push.js +32 -0
  192. package/dist/engine/sync/settings-conflicts.d.ts +8 -0
  193. package/dist/engine/sync/settings-conflicts.js +56 -0
  194. package/dist/engine/sync/settings-merge.d.ts +13 -0
  195. package/dist/engine/sync/settings-merge.js +93 -0
  196. package/dist/engine/sync/signals.d.ts +2 -0
  197. package/dist/engine/sync/signals.js +8 -0
  198. package/dist/engine/sync/startup-timings.d.ts +11 -0
  199. package/dist/engine/sync/startup-timings.js +44 -0
  200. package/dist/engine/sync/sync-decision.d.ts +35 -0
  201. package/dist/engine/sync/sync-decision.js +66 -0
  202. package/dist/engine/sync/sync-error-guidance.d.ts +2 -0
  203. package/dist/engine/sync/sync-error-guidance.js +55 -0
  204. package/dist/engine/sync/sync-errors.d.ts +9 -0
  205. package/dist/engine/sync/sync-errors.js +18 -0
  206. package/dist/engine/sync/sync-inspection.d.ts +26 -0
  207. package/dist/engine/sync/sync-inspection.js +40 -0
  208. package/dist/engine/sync/sync-loaders.d.ts +7 -0
  209. package/dist/engine/sync/sync-loaders.js +8 -0
  210. package/dist/engine/sync/sync-local.d.ts +5 -0
  211. package/dist/engine/sync/sync-local.js +40 -0
  212. package/dist/engine/sync/sync-mutations.d.ts +30 -0
  213. package/dist/engine/sync/sync-mutations.js +589 -0
  214. package/dist/engine/sync/sync-operations.d.ts +2 -0
  215. package/dist/engine/sync/sync-operations.js +3 -0
  216. package/dist/engine/sync/sync-policy.d.ts +85 -0
  217. package/dist/engine/sync/sync-policy.js +356 -0
  218. package/dist/engine/sync/sync-queries.d.ts +7 -0
  219. package/dist/engine/sync/sync-queries.js +195 -0
  220. package/dist/engine/sync/sync-state.d.ts +31 -0
  221. package/dist/engine/sync/sync-state.js +92 -0
  222. package/dist/engine/sync/text-merge.d.ts +19 -0
  223. package/dist/engine/sync/text-merge.js +124 -0
  224. package/dist/engine/types.d.ts +5 -0
  225. package/dist/engine/types.js +2 -0
  226. package/dist/engine/ui/merge-review.d.ts +2 -0
  227. package/dist/engine/ui/merge-review.js +7 -0
  228. package/dist/engine/ui/merged-sync-summary.d.ts +25 -0
  229. package/dist/engine/ui/merged-sync-summary.js +86 -0
  230. package/dist/engine/ui/sync-format.d.ts +13 -0
  231. package/dist/engine/ui/sync-format.js +150 -0
  232. package/dist/engine/ui/sync-status.d.ts +9 -0
  233. package/dist/engine/ui/sync-status.js +30 -0
  234. package/dist/engine/ui/terminal-text.d.ts +3 -0
  235. package/dist/engine/ui/terminal-text.js +9 -0
  236. package/dist/engine/ui/transfer-changes.d.ts +12 -0
  237. package/dist/engine/ui/transfer-changes.js +24 -0
  238. package/dist/engine/ui/transfer-review.d.ts +3 -0
  239. package/dist/engine/ui/transfer-review.js +19 -0
  240. package/dist/engine-service.d.ts +14 -0
  241. package/dist/engine-service.js +322 -0
  242. package/dist/identity.d.ts +20 -0
  243. package/dist/identity.js +133 -0
  244. package/dist/idle-exit.d.ts +17 -0
  245. package/dist/idle-exit.js +77 -0
  246. package/dist/index.d.ts +8 -0
  247. package/dist/index.js +4 -0
  248. package/dist/lifecycle-log.d.ts +7 -0
  249. package/dist/lifecycle-log.js +53 -0
  250. package/dist/lifecycle.d.ts +2 -0
  251. package/dist/lifecycle.js +21 -0
  252. package/dist/model-signature.d.ts +2 -0
  253. package/dist/model-signature.js +7 -0
  254. package/dist/monitor.d.ts +14 -0
  255. package/dist/monitor.js +272 -0
  256. package/dist/participant-admission.d.ts +5 -0
  257. package/dist/participant-admission.js +30 -0
  258. package/dist/protocol.d.ts +102 -0
  259. package/dist/protocol.js +97 -0
  260. package/dist/resolver-host.d.ts +11 -0
  261. package/dist/resolver-host.js +78 -0
  262. package/dist/server.d.ts +24 -0
  263. package/dist/server.js +808 -0
  264. package/dist/service-host.d.ts +7 -0
  265. package/dist/service-host.js +174 -0
  266. package/docs/architecture.md +162 -0
  267. package/package.json +54 -4
@@ -0,0 +1,352 @@
1
+ import { createHash, createHmac } from "node:crypto";
2
+ import { setTimeout as sleep } from "node:timers/promises";
3
+ import { encodeKey, posixJoin } from "../../paths.js";
4
+ import { retryAfter } from "../../sync/continuous-errors.js";
5
+ const MAX_JSON_RESPONSE_BYTES = 1024 * 1024;
6
+ const MAX_SNAPSHOT_RESPONSE_BYTES = 256 * 1024 * 1024;
7
+ const MAX_ERROR_RESPONSE_BYTES = 64 * 1024;
8
+ const DEFAULT_REQUEST_TIMEOUT_MS = 30_000;
9
+ function iso8601Basic(date) {
10
+ return date.toISOString().replace(/[:-]|\.\d{3}/g, "");
11
+ }
12
+ function isCloudflareR2Endpoint(endpoint) {
13
+ const value = endpoint?.trim();
14
+ if (!value)
15
+ return false;
16
+ try {
17
+ const hostname = new URL(value).hostname.toLowerCase();
18
+ return hostname === "r2.cloudflarestorage.com" || hostname.endsWith(".r2.cloudflarestorage.com");
19
+ }
20
+ catch {
21
+ return false;
22
+ }
23
+ }
24
+ export class S3ObjectAlreadyExistsError extends Error {
25
+ key;
26
+ constructor(key) {
27
+ super(`S3 object already exists: ${key}`);
28
+ this.key = key;
29
+ this.name = "S3ObjectAlreadyExistsError";
30
+ }
31
+ }
32
+ export class S3HttpError extends Error {
33
+ status;
34
+ retryAfterMs;
35
+ constructor(message, status, retryAfterMs) {
36
+ super(message);
37
+ this.status = status;
38
+ this.retryAfterMs = retryAfterMs;
39
+ this.name = "S3HttpError";
40
+ }
41
+ }
42
+ export class S3Client {
43
+ config;
44
+ endpoint;
45
+ signal;
46
+ requestTimeoutMs;
47
+ omitSessionTokenAfterRejection = false;
48
+ constructor(config, signal, requestTimeoutMs = DEFAULT_REQUEST_TIMEOUT_MS) {
49
+ this.config = config;
50
+ this.endpoint = new URL(config.profile.endpoint);
51
+ this.signal = signal;
52
+ this.requestTimeoutMs = requestTimeoutMs;
53
+ }
54
+ /** Read-only access probe. A bare 404 cannot distinguish a missing key from a missing bucket. */
55
+ async diagnoseRead(key) {
56
+ this.signal?.throwIfAborted();
57
+ const response = await this.request("GET", key);
58
+ if (response.ok) {
59
+ await response.body?.cancel();
60
+ this.signal?.throwIfAborted();
61
+ return "readable";
62
+ }
63
+ const detail = await this.readErrorText(response);
64
+ this.signal?.throwIfAborted();
65
+ if (response.status === 404) {
66
+ const code = /<Code>\s*([A-Za-z]+)\s*<\/Code>/u.exec(detail)?.[1];
67
+ if (code === "NoSuchBucket")
68
+ return "missing-bucket";
69
+ if (code === "NoSuchKey")
70
+ return "missing-key";
71
+ return "unknown-404";
72
+ }
73
+ throw new S3HttpError(`S3 remote read failed (HTTP ${response.status}).`, response.status);
74
+ }
75
+ async getJson(key) {
76
+ const maxAttempts = 3;
77
+ let lastError;
78
+ for (let attempt = 1; attempt <= maxAttempts; attempt++) {
79
+ const object = await this.request("GET", key);
80
+ if (object.status === 404)
81
+ return { missing: true };
82
+ if (!object.ok) {
83
+ throw new S3HttpError(`S3 GET failed (${object.status}): ${await this.readErrorText(object)}`, object.status, retryAfter(object));
84
+ }
85
+ const body = await readBoundedText(object, MAX_JSON_RESPONSE_BYTES, "S3 JSON response");
86
+ // R2 can intermittently return an empty 200 body (read-after-write
87
+ // inconsistency on a long-lived keep-alive connection), which makes
88
+ // response.json() throw "JSON Parse error: Unexpected EOF" under Bun.
89
+ // Retry so the transient blip is absorbed instead of surfacing as a
90
+ // "pi-sync auto sync skipped" warning on every session start.
91
+ if (body.length > 0) {
92
+ return {
93
+ value: JSON.parse(body),
94
+ etag: normalizeEtag(object.headers.get("etag")),
95
+ missing: false,
96
+ };
97
+ }
98
+ lastError = new Error(`S3 GET returned an empty body for ${key}`);
99
+ if (attempt < maxAttempts) {
100
+ await sleep(250 * attempt, undefined, { signal: this.signal });
101
+ }
102
+ }
103
+ throw lastError;
104
+ }
105
+ async getBuffer(key) {
106
+ const maxAttempts = 3;
107
+ let lastError;
108
+ for (let attempt = 1; attempt <= maxAttempts; attempt++) {
109
+ const object = await this.request("GET", key);
110
+ if (object.status === 404)
111
+ return { missing: true };
112
+ if (!object.ok) {
113
+ throw new S3HttpError(`S3 GET failed (${object.status}): ${await this.readErrorText(object)}`, object.status, retryAfter(object));
114
+ }
115
+ const buffer = await readBoundedBuffer(object, MAX_SNAPSHOT_RESPONSE_BYTES, "S3 snapshot response");
116
+ // R2 can intermittently return an empty 200 body on a long-lived
117
+ // keep-alive connection (same root cause as the getJson retry
118
+ // above). getBuffer is only used for snapshot .json.gz payloads,
119
+ // which are always non-empty, so an empty body is a transient
120
+ // blip, not a legitimate response. Retry so the checksum guard
121
+ // downstream doesn't surface it as "Remote snapshot checksum
122
+ // mismatch".
123
+ if (buffer.length > 0) {
124
+ return { value: buffer, etag: normalizeEtag(object.headers.get("etag")), missing: false };
125
+ }
126
+ lastError = new Error(`S3 GET returned an empty body for ${key}`);
127
+ if (attempt < maxAttempts) {
128
+ await sleep(250 * attempt, undefined, { signal: this.signal });
129
+ }
130
+ }
131
+ throw lastError;
132
+ }
133
+ async putJson(key, value, options = {}) {
134
+ const body = Buffer.from(JSON.stringify(value, null, "\t"), "utf8");
135
+ await this.putBuffer(key, body, "application/json", options);
136
+ }
137
+ async putBuffer(key, body, contentType, options = {}) {
138
+ const headers = { "content-type": contentType };
139
+ if (options.ifAbsent)
140
+ headers["if-none-match"] = "*";
141
+ if (options.ifMatch)
142
+ headers["if-match"] = options.ifMatch;
143
+ const response = await this.request("PUT", key, body, headers);
144
+ if ((options.ifAbsent || options.ifMatch) && (response.status === 412 || response.status === 409)) {
145
+ await response.body?.cancel();
146
+ if (options.ifAbsent && response.status === 412)
147
+ throw new S3ObjectAlreadyExistsError(key);
148
+ if (options.ifAbsent || options.ifMatch) {
149
+ throw new S3HttpError(`S3 conditional PUT rejected (${response.status}).`, response.status);
150
+ }
151
+ }
152
+ if (!response.ok) {
153
+ throw new S3HttpError(`S3 PUT failed (${response.status}): ${await this.readErrorText(response)}`, response.status, retryAfter(response));
154
+ }
155
+ await response.body?.cancel();
156
+ }
157
+ async delete(key) {
158
+ const response = await this.request("DELETE", key);
159
+ if (!response.ok && response.status !== 404) {
160
+ throw new S3HttpError(`S3 DELETE failed (${response.status}): ${await this.readErrorText(response)}`, response.status, retryAfter(response));
161
+ }
162
+ await response.body?.cancel();
163
+ }
164
+ async request(method, key, body, extraHeaders = {}) {
165
+ const url = new URL(this.endpoint.toString());
166
+ // Preserve escaped endpoint bytes without decoding or double-encoding them.
167
+ // SigV4 requires uppercase escape hex, including existing endpoint escapes.
168
+ const endpointPath = url.pathname
169
+ .replace(/%(?![0-9A-Fa-f]{2})|[^A-Za-z0-9._~/%-]/gu, encodeKey)
170
+ .replace(/%[0-9A-Fa-f]{2}/gu, (escaped) => escaped.toUpperCase());
171
+ url.pathname = posixJoin(endpointPath, encodeKey(this.config.destination.bucket), encodeKey(key));
172
+ const send = async (sessionToken) => {
173
+ const transportSignal = this.transportSignal();
174
+ const headers = await signedHeaders({
175
+ method,
176
+ url,
177
+ body,
178
+ // Transfer compression can weaken an object's ETag (R2 JSON responses).
179
+ // Read the original representation for exact checksums and strong If-Match tokens.
180
+ extraHeaders: method === "GET" ? { ...extraHeaders, "accept-encoding": "identity" } : extraHeaders,
181
+ accessKeyId: this.config.profile.accessKeyId,
182
+ secretAccessKey: this.config.profile.secretAccessKey,
183
+ sessionToken,
184
+ region: this.config.profile.region,
185
+ });
186
+ try {
187
+ return await fetch(url, {
188
+ method,
189
+ headers,
190
+ body: body ? new Uint8Array(body) : undefined,
191
+ // Never forward signed headers or snapshot bodies to an unreviewed URL.
192
+ redirect: "error",
193
+ signal: transportSignal,
194
+ });
195
+ }
196
+ catch (error) {
197
+ if (error instanceof Error && error.name === "AbortError")
198
+ throw error;
199
+ if (error instanceof Error && error.name === "TimeoutError") {
200
+ throw new Error("S3 request timed out.", { cause: error });
201
+ }
202
+ throw new Error(`S3 request failed: ${this.redact(errorMessage(error))}`, { cause: error });
203
+ }
204
+ };
205
+ const sessionToken = this.omitSessionTokenAfterRejection ? undefined : this.config.profile.sessionToken;
206
+ const response = await send(sessionToken);
207
+ try {
208
+ if (!(await this.shouldRetryWithoutSessionToken(response, sessionToken)))
209
+ return response;
210
+ }
211
+ catch (error) {
212
+ await response.body?.cancel().catch(() => undefined);
213
+ throw error;
214
+ }
215
+ await response.body?.cancel();
216
+ const retry = await send(undefined);
217
+ if (retry.ok || retry.status === 404)
218
+ this.omitSessionTokenAfterRejection = true;
219
+ return retry;
220
+ }
221
+ transportSignal() {
222
+ const timeout = AbortSignal.timeout(this.requestTimeoutMs);
223
+ return this.signal ? AbortSignal.any([this.signal, timeout]) : timeout;
224
+ }
225
+ async shouldRetryWithoutSessionToken(response, sessionToken) {
226
+ if (!sessionToken ||
227
+ !isCloudflareR2Endpoint(this.config.profile.endpoint) ||
228
+ response.ok ||
229
+ response.status !== 400) {
230
+ return false;
231
+ }
232
+ return isSecurityTokenInvalidArgument(await readBoundedText(response.clone(), MAX_ERROR_RESPONSE_BYTES, "S3 error response"));
233
+ }
234
+ async readErrorText(response) {
235
+ try {
236
+ return this.redact(await readBoundedText(response, MAX_ERROR_RESPONSE_BYTES, "S3 error response"));
237
+ }
238
+ catch (error) {
239
+ return this.redact(errorMessage(error));
240
+ }
241
+ }
242
+ redact(value) {
243
+ let redacted = value;
244
+ let endpointUsername;
245
+ let endpointPassword;
246
+ let endpointQueryValues = [];
247
+ try {
248
+ const endpoint = new URL(this.config.profile.endpoint);
249
+ endpointUsername = endpoint.username;
250
+ endpointPassword = endpoint.password;
251
+ endpointQueryValues = [...endpoint.searchParams.values()];
252
+ }
253
+ catch {
254
+ // The constructor already validates normal runtime endpoints.
255
+ }
256
+ for (const secret of [
257
+ this.config.profile.accessKeyId,
258
+ this.config.profile.secretAccessKey,
259
+ this.config.profile.sessionToken,
260
+ endpointUsername,
261
+ endpointPassword,
262
+ ...endpointQueryValues,
263
+ ]) {
264
+ if (secret)
265
+ redacted = redacted.replaceAll(secret, "[REDACTED]");
266
+ }
267
+ return redacted;
268
+ }
269
+ }
270
+ async function readBoundedText(response, limit, label) {
271
+ return (await readBoundedBuffer(response, limit, label)).toString("utf8");
272
+ }
273
+ async function readBoundedBuffer(response, limit, label) {
274
+ const contentLength = Number(response.headers.get("content-length"));
275
+ if (Number.isFinite(contentLength) && contentLength > limit) {
276
+ // Do not await cancellation of a cloned stream before its sibling can be released.
277
+ void response.body?.cancel().catch(() => undefined);
278
+ throw new Error(`${label} exceeds the ${limit}-byte limit.`);
279
+ }
280
+ if (!response.body)
281
+ return Buffer.alloc(0);
282
+ const reader = response.body.getReader();
283
+ const chunks = [];
284
+ let total = 0;
285
+ try {
286
+ while (true) {
287
+ const { done, value } = await reader.read();
288
+ if (done)
289
+ break;
290
+ total += value.byteLength;
291
+ if (total > limit) {
292
+ void reader.cancel().catch(() => undefined);
293
+ throw new Error(`${label} exceeds the ${limit}-byte limit.`);
294
+ }
295
+ chunks.push(Buffer.from(value));
296
+ }
297
+ }
298
+ finally {
299
+ reader.releaseLock();
300
+ }
301
+ return Buffer.concat(chunks, total);
302
+ }
303
+ function errorMessage(error) {
304
+ return error instanceof Error ? error.message : String(error);
305
+ }
306
+ async function signedHeaders(input) {
307
+ const now = new Date();
308
+ const amzDate = iso8601Basic(now);
309
+ const dateStamp = amzDate.slice(0, 8);
310
+ const payloadHash = sha256(input.body ?? Buffer.alloc(0));
311
+ const headers = {
312
+ ...lowercaseKeys(input.extraHeaders),
313
+ host: input.url.host,
314
+ "x-amz-content-sha256": payloadHash,
315
+ "x-amz-date": amzDate,
316
+ };
317
+ if (input.sessionToken)
318
+ headers["x-amz-security-token"] = input.sessionToken;
319
+ const signedHeaderNames = Object.keys(headers).sort();
320
+ const canonicalHeaders = signedHeaderNames.map((name) => `${name}:${headers[name]?.trim()}\n`).join("");
321
+ const canonicalRequest = [
322
+ input.method,
323
+ input.url.pathname,
324
+ input.url.searchParams.toString(),
325
+ canonicalHeaders,
326
+ signedHeaderNames.join(";"),
327
+ payloadHash,
328
+ ].join("\n");
329
+ const scope = `${dateStamp}/${input.region}/s3/aws4_request`;
330
+ const stringToSign = ["AWS4-HMAC-SHA256", amzDate, scope, sha256(Buffer.from(canonicalRequest))].join("\n");
331
+ const signingKey = hmac(hmac(hmac(hmac(Buffer.from(`AWS4${input.secretAccessKey}`), dateStamp), input.region), "s3"), "aws4_request");
332
+ const signature = createHmac("sha256", signingKey).update(stringToSign).digest("hex");
333
+ return {
334
+ ...headers,
335
+ authorization: `AWS4-HMAC-SHA256 Credential=${input.accessKeyId}/${scope}, SignedHeaders=${signedHeaderNames.join(";")}, Signature=${signature}`,
336
+ };
337
+ }
338
+ function hmac(key, value) {
339
+ return createHmac("sha256", key).update(value).digest();
340
+ }
341
+ function sha256(value) {
342
+ return createHash("sha256").update(value).digest("hex");
343
+ }
344
+ function lowercaseKeys(value) {
345
+ return Object.fromEntries(Object.entries(value).map(([key, item]) => [key.toLowerCase(), item]));
346
+ }
347
+ function normalizeEtag(value) {
348
+ return value ?? undefined;
349
+ }
350
+ function isSecurityTokenInvalidArgument(text) {
351
+ return text.includes("<Code>InvalidArgument</Code>") && text.includes("<Message>X-Amz-Security-Token</Message>");
352
+ }
@@ -0,0 +1,4 @@
1
+ import type { ResolvedS3Backend } from "../backend-types.js";
2
+ export declare function requireS3Etag(value: string | undefined): string;
3
+ /** Never probe the active pointer or immutable snapshots; ignored conditions must not corrupt either. */
4
+ export declare function verifyS3Conditions(config: ResolvedS3Backend, signal?: AbortSignal): Promise<void>;
@@ -0,0 +1,66 @@
1
+ import { randomUUID } from "node:crypto";
2
+ import { posixJoin } from "../../paths.js";
3
+ import { S3Client, S3HttpError, S3ObjectAlreadyExistsError } from "./s3-client.js";
4
+ export function requireS3Etag(value) {
5
+ if (!value || !/^"[^"\r\n]+"$/u.test(value))
6
+ throw new Error("S3 conditional publication requires a strong ETag.");
7
+ return value;
8
+ }
9
+ /** Never probe the active pointer or immutable snapshots; ignored conditions must not corrupt either. */
10
+ export async function verifyS3Conditions(config, signal) {
11
+ const key = posixJoin(config.destination.prefix === "./" ? "" : config.destination.prefix, ".pi-sync-probes", randomUUID());
12
+ const client = new S3Client(config, signal);
13
+ let failure;
14
+ let attempted = false;
15
+ try {
16
+ signal?.throwIfAborted();
17
+ attempted = true;
18
+ await client.putBuffer(key, Buffer.from("first"), "text/plain", { ifAbsent: true });
19
+ const first = await client.getBuffer(key);
20
+ const etag = requireS3Etag(first.etag);
21
+ if (!first.value?.equals(Buffer.from("first")))
22
+ throw new Error("S3 conditional probe read did not match.");
23
+ await expectRejected(client.putBuffer(key, Buffer.from("ignored"), "text/plain", { ifAbsent: true }));
24
+ await expectRejected(client.putBuffer(key, Buffer.from("ignored"), "text/plain", { ifMatch: '"pi-sync-stale"' }));
25
+ const unchanged = await client.getBuffer(key);
26
+ if (!unchanged.value?.equals(first.value) || unchanged.etag !== etag)
27
+ throw new Error("S3 failed precondition changed the probe.");
28
+ await client.putBuffer(key, Buffer.from("second"), "text/plain", { ifMatch: etag });
29
+ const second = await client.getBuffer(key);
30
+ if (!second.value?.equals(Buffer.from("second")) || requireS3Etag(second.etag) === etag) {
31
+ throw new Error("S3 conditional write did not rotate the probe ETag.");
32
+ }
33
+ await expectRejected(client.putBuffer(key, Buffer.from("ignored"), "text/plain", { ifMatch: etag }));
34
+ const final = await client.getBuffer(key);
35
+ if (!final.value?.equals(second.value) || final.etag !== second.etag)
36
+ throw new Error("S3 stale ETag changed the probe.");
37
+ signal?.throwIfAborted();
38
+ }
39
+ catch (error) {
40
+ failure = error;
41
+ }
42
+ // Cleanup has its own bounded deadline even when the owning session was cancelled.
43
+ if (attempted) {
44
+ try {
45
+ await new S3Client(config, AbortSignal.timeout(10_000)).delete(key);
46
+ }
47
+ catch (error) {
48
+ throw new Error(`S3 probe cleanup failed; remove ${key}.`, { cause: failure ?? error });
49
+ }
50
+ }
51
+ if (failure)
52
+ throw failure;
53
+ signal?.throwIfAborted();
54
+ }
55
+ async function expectRejected(operation) {
56
+ try {
57
+ await operation;
58
+ }
59
+ catch (error) {
60
+ // 409 is retryable contention, not proof that a failed condition was enforced.
61
+ if (error instanceof S3ObjectAlreadyExistsError || (error instanceof S3HttpError && error.status === 412))
62
+ return;
63
+ throw error;
64
+ }
65
+ throw new Error("S3 server ignored a write precondition; publication stopped for safety.");
66
+ }
@@ -0,0 +1,6 @@
1
+ import type { Snapshot } from "../snapshot/snapshot-types.js";
2
+ import type { LatestPointer } from "./backend-types.js";
3
+ import type { RemoteHistoryEntry } from "./sync-backend.js";
4
+ /** Shared latest/history metadata for the S3 and WebDAV object-store format. */
5
+ export declare function createLatestPointer(namespace: string, snapshot: Snapshot, checksum: string): LatestPointer;
6
+ export declare function remoteHistoryEntry(pointer: LatestPointer): RemoteHistoryEntry;
@@ -0,0 +1,22 @@
1
+ /** Shared latest/history metadata for the S3 and WebDAV object-store format. */
2
+ export function createLatestPointer(namespace, snapshot, checksum) {
3
+ return {
4
+ version: 1,
5
+ profile: namespace,
6
+ snapshot: snapshot.id,
7
+ sha256: checksum,
8
+ createdAt: snapshot.createdAt,
9
+ machine: snapshot.machine,
10
+ syncSessions: snapshot.syncSessions === true || snapshot.files.some((file) => file.path.startsWith("sessions/")),
11
+ ...(snapshot.selection === undefined ? {} : { selection: snapshot.selection }),
12
+ };
13
+ }
14
+ export function remoteHistoryEntry(pointer) {
15
+ return {
16
+ snapshotRef: pointer.snapshot,
17
+ snapshotId: pointer.snapshot,
18
+ createdAt: pointer.createdAt,
19
+ machine: pointer.machine,
20
+ syncSessions: pointer.syncSessions === true,
21
+ };
22
+ }
@@ -0,0 +1,71 @@
1
+ import type { Snapshot, SnapshotSelection } from "../snapshot/snapshot-types.js";
2
+ export type PublicationCapability = "read-check-write-verify" | "conditional-required" | "atomic-conditional" | "lease-protected";
3
+ export interface RemoteHead {
4
+ /** Backend-owned reference used only to retrieve this immutable snapshot. */
5
+ snapshotRef: string;
6
+ /** Backend-neutral snapshot content identity retained in local sync state. */
7
+ snapshotId: string;
8
+ revision: string;
9
+ createdAt: string;
10
+ machine: string;
11
+ syncSessions: boolean;
12
+ /** Validated lightweight projection; revalidate it against the immutable snapshot before adoption. */
13
+ selection?: SnapshotSelection;
14
+ }
15
+ export interface RemoteHistoryEntry {
16
+ snapshotRef: string;
17
+ snapshotId: string;
18
+ createdAt: string;
19
+ machine: string;
20
+ syncSessions: boolean;
21
+ }
22
+ export type ExpectedRemoteHead = {
23
+ kind: "missing";
24
+ } | {
25
+ kind: "revision";
26
+ revision: string;
27
+ };
28
+ export interface PublishSnapshotOptions {
29
+ signal?: AbortSignal;
30
+ /** Called at the backend's active-head commit boundary. */
31
+ onCommit?: () => void;
32
+ }
33
+ export interface PublishSnapshotResult {
34
+ head: RemoteHead;
35
+ warnings: string[];
36
+ }
37
+ export interface BackendDiagnostic {
38
+ key: string;
39
+ level: "info" | "warning" | "error";
40
+ message: string;
41
+ }
42
+ export interface SyncBackend {
43
+ readonly identity: string;
44
+ readonly destination: string;
45
+ readonly capability: PublicationCapability;
46
+ /** Compare opaque revisions produced by this backend identity. */
47
+ sameRevision(left: string, right: string): boolean;
48
+ /** Recovery-only equivalence for retiring an inactive candidate; never authorizes publication or apply. */
49
+ matchesUncommittedRecoveryHead?(current: RemoteHead, recorded: RemoteHead): boolean;
50
+ readHead(signal?: AbortSignal): Promise<RemoteHead | undefined>;
51
+ readSnapshot(reference: string, signal?: AbortSignal): Promise<Snapshot>;
52
+ publishSnapshot(snapshot: Snapshot, expected: ExpectedRemoteHead, options?: PublishSnapshotOptions): Promise<PublishSnapshotResult>;
53
+ listHistory(signal?: AbortSignal): Promise<RemoteHistoryEntry[]>;
54
+ diagnose(signal?: AbortSignal): Promise<BackendDiagnostic[]>;
55
+ }
56
+ export declare class SyncBackendConflictError extends Error {
57
+ readonly code = "SYNC_BACKEND_CONFLICT";
58
+ readonly phase: "before-commit" | "after-commit";
59
+ readonly currentHead?: RemoteHead;
60
+ readonly candidateMayHaveBeenActive: boolean;
61
+ constructor(message: string, options?: ErrorOptions & {
62
+ phase?: "before-commit" | "after-commit";
63
+ currentHead?: RemoteHead;
64
+ candidateMayHaveBeenActive?: boolean;
65
+ });
66
+ }
67
+ export declare class SyncBackendPublicationOutcomeUnknownError extends Error {
68
+ readonly code = "SYNC_BACKEND_PUBLICATION_OUTCOME_UNKNOWN";
69
+ constructor(message: string, options?: ErrorOptions);
70
+ }
71
+ export declare function expectedRemoteHead(head: RemoteHead | undefined): ExpectedRemoteHead;
@@ -0,0 +1,23 @@
1
+ export class SyncBackendConflictError extends Error {
2
+ code = "SYNC_BACKEND_CONFLICT";
3
+ phase;
4
+ currentHead;
5
+ candidateMayHaveBeenActive;
6
+ constructor(message, options = {}) {
7
+ super(message, options);
8
+ this.name = "SyncBackendConflictError";
9
+ this.phase = options.phase ?? "before-commit";
10
+ this.currentHead = options.currentHead;
11
+ this.candidateMayHaveBeenActive = options.candidateMayHaveBeenActive ?? false;
12
+ }
13
+ }
14
+ export class SyncBackendPublicationOutcomeUnknownError extends Error {
15
+ code = "SYNC_BACKEND_PUBLICATION_OUTCOME_UNKNOWN";
16
+ constructor(message, options) {
17
+ super(message, options);
18
+ this.name = "SyncBackendPublicationOutcomeUnknownError";
19
+ }
20
+ }
21
+ export function expectedRemoteHead(head) {
22
+ return head ? { kind: "revision", revision: head.revision } : { kind: "missing" };
23
+ }
@@ -0,0 +1,34 @@
1
+ import type { Snapshot } from "../../snapshot/snapshot-types.js";
2
+ import type { ResolvedWebDavBackend } from "../backend-types.js";
3
+ import { type BackendDiagnostic, type ExpectedRemoteHead, type PublishSnapshotOptions, type PublishSnapshotResult, type RemoteHead, type RemoteHistoryEntry, type SyncBackend } from "../sync-backend.js";
4
+ export declare class WebDavSyncBackend implements SyncBackend {
5
+ private readonly config;
6
+ private readonly postCommitTimeoutMs;
7
+ readonly identity: string;
8
+ readonly destination: string;
9
+ private conditionalVerified;
10
+ private readonly checksums;
11
+ private capabilityCheck?;
12
+ constructor(config: ResolvedWebDavBackend, postCommitTimeoutMs?: number);
13
+ get capability(): "atomic-conditional" | "conditional-required";
14
+ sameRevision(left: string, right: string): boolean;
15
+ readHead(signal?: AbortSignal): Promise<RemoteHead | undefined>;
16
+ readSnapshot(reference: string, signal?: AbortSignal): Promise<Snapshot>;
17
+ publishSnapshot(snapshot: Snapshot, expected: ExpectedRemoteHead, options?: PublishSnapshotOptions): Promise<PublishSnapshotResult>;
18
+ listHistory(signal?: AbortSignal): Promise<RemoteHistoryEntry[]>;
19
+ diagnose(signal?: AbortSignal): Promise<BackendDiagnostic[]>;
20
+ private ensureAtomicConditions;
21
+ private runCapabilityProbe;
22
+ private resolveChecksum;
23
+ private registerChecksum;
24
+ private readHeadAfterCommit;
25
+ private reconcileActiveHistory;
26
+ private ensureHistoryPointer;
27
+ private updateHistorySafely;
28
+ }
29
+ export declare function rootPath(config: ResolvedWebDavBackend): string;
30
+ export declare function latestPath(config: ResolvedWebDavBackend): string;
31
+ export declare function historyPath(config: ResolvedWebDavBackend): string;
32
+ export declare function snapshotsPath(config: ResolvedWebDavBackend): string;
33
+ export declare function snapshotPath(config: ResolvedWebDavBackend, reference: string): string;
34
+ export declare function webDavBackendIdentity(config: ResolvedWebDavBackend): string;