@wavehouse/chtypes 0.5.2 → 1.0.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 (195) hide show
  1. package/CHANGELOG.md +26 -0
  2. package/README.md +34 -38
  3. package/dist/abi1/buildinfo.d.ts +40 -0
  4. package/dist/abi1/buildinfo.d.ts.map +1 -0
  5. package/dist/abi1/buildinfo.js +83 -0
  6. package/dist/abi1/buildinfo.js.map +1 -0
  7. package/dist/abi1/calls.gen.d.ts +55 -0
  8. package/dist/abi1/calls.gen.d.ts.map +1 -0
  9. package/dist/abi1/calls.gen.js +110 -0
  10. package/dist/abi1/calls.gen.js.map +1 -0
  11. package/dist/abi1/decls.gen.d.ts +115 -0
  12. package/dist/abi1/decls.gen.d.ts.map +1 -0
  13. package/dist/abi1/decls.gen.js +1613 -0
  14. package/dist/abi1/decls.gen.js.map +1 -0
  15. package/dist/abi1/errmap.gen.d.ts +18 -0
  16. package/dist/abi1/errmap.gen.d.ts.map +1 -0
  17. package/dist/abi1/errmap.gen.js +66 -0
  18. package/dist/abi1/errmap.gen.js.map +1 -0
  19. package/dist/abi1/errors.d.ts +107 -0
  20. package/dist/abi1/errors.d.ts.map +1 -0
  21. package/dist/abi1/errors.js +134 -0
  22. package/dist/abi1/errors.js.map +1 -0
  23. package/dist/abi1/handles.d.ts +31 -0
  24. package/dist/abi1/handles.d.ts.map +1 -0
  25. package/dist/abi1/handles.js +76 -0
  26. package/dist/abi1/handles.js.map +1 -0
  27. package/dist/abi1/index.d.ts +17 -0
  28. package/dist/abi1/index.d.ts.map +1 -0
  29. package/dist/abi1/index.js +17 -0
  30. package/dist/abi1/index.js.map +1 -0
  31. package/dist/abi1/libc.d.ts +54 -0
  32. package/dist/abi1/libc.d.ts.map +1 -0
  33. package/dist/abi1/libc.gen.d.ts +12 -0
  34. package/dist/abi1/libc.gen.d.ts.map +1 -0
  35. package/dist/abi1/libc.gen.js +75 -0
  36. package/dist/abi1/libc.gen.js.map +1 -0
  37. package/dist/abi1/libc.js +109 -0
  38. package/dist/abi1/libc.js.map +1 -0
  39. package/dist/abi1/loader.d.ts +99 -0
  40. package/dist/abi1/loader.d.ts.map +1 -0
  41. package/dist/abi1/loader.js +261 -0
  42. package/dist/abi1/loader.js.map +1 -0
  43. package/dist/abi1/raw.d.ts +104 -0
  44. package/dist/abi1/raw.d.ts.map +1 -0
  45. package/dist/abi1/raw.js +296 -0
  46. package/dist/abi1/raw.js.map +1 -0
  47. package/dist/abi1/strictjson.d.ts +19 -0
  48. package/dist/abi1/strictjson.d.ts.map +1 -0
  49. package/dist/abi1/strictjson.js +78 -0
  50. package/dist/abi1/strictjson.js.map +1 -0
  51. package/dist/abi1/vocab.gen.d.ts +169 -0
  52. package/dist/abi1/vocab.gen.d.ts.map +1 -0
  53. package/dist/abi1/vocab.gen.js +306 -0
  54. package/dist/abi1/vocab.gen.js.map +1 -0
  55. package/dist/cli.d.ts +25 -26
  56. package/dist/cli.d.ts.map +1 -1
  57. package/dist/cli.js +206 -218
  58. package/dist/cli.js.map +1 -1
  59. package/dist/documents.d.ts +195 -0
  60. package/dist/documents.d.ts.map +1 -0
  61. package/dist/documents.js +389 -0
  62. package/dist/documents.js.map +1 -0
  63. package/dist/env.d.ts +16 -0
  64. package/dist/env.d.ts.map +1 -0
  65. package/dist/env.js +57 -0
  66. package/dist/env.js.map +1 -0
  67. package/dist/index.d.ts +19 -24
  68. package/dist/index.d.ts.map +1 -1
  69. package/dist/index.js +17 -23
  70. package/dist/index.js.map +1 -1
  71. package/dist/json.d.ts +11 -89
  72. package/dist/json.d.ts.map +1 -1
  73. package/dist/json.js +16 -180
  74. package/dist/json.js.map +1 -1
  75. package/dist/library.d.ts +53 -309
  76. package/dist/library.d.ts.map +1 -1
  77. package/dist/library.js +77 -315
  78. package/dist/library.js.map +1 -1
  79. package/dist/ocifetch/constants.gen.d.ts +84 -0
  80. package/dist/ocifetch/constants.gen.d.ts.map +1 -0
  81. package/dist/ocifetch/constants.gen.js +92 -0
  82. package/dist/ocifetch/constants.gen.js.map +1 -0
  83. package/dist/ocifetch/dsse.d.ts +114 -0
  84. package/dist/ocifetch/dsse.d.ts.map +1 -0
  85. package/dist/ocifetch/dsse.js +331 -0
  86. package/dist/ocifetch/dsse.js.map +1 -0
  87. package/dist/ocifetch/ensure.d.ts +65 -0
  88. package/dist/ocifetch/ensure.d.ts.map +1 -0
  89. package/dist/ocifetch/ensure.js +775 -0
  90. package/dist/ocifetch/ensure.js.map +1 -0
  91. package/dist/ocifetch/errors.d.ts +92 -0
  92. package/dist/ocifetch/errors.d.ts.map +1 -0
  93. package/dist/ocifetch/errors.js +101 -0
  94. package/dist/ocifetch/errors.js.map +1 -0
  95. package/dist/ocifetch/goldens.d.ts +44 -0
  96. package/dist/ocifetch/goldens.d.ts.map +1 -0
  97. package/dist/ocifetch/goldens.js +62 -0
  98. package/dist/ocifetch/goldens.js.map +1 -0
  99. package/dist/ocifetch/http.d.ts +124 -0
  100. package/dist/ocifetch/http.d.ts.map +1 -0
  101. package/dist/ocifetch/http.js +549 -0
  102. package/dist/ocifetch/http.js.map +1 -0
  103. package/dist/ocifetch/index.d.ts +17 -0
  104. package/dist/ocifetch/index.d.ts.map +1 -0
  105. package/dist/ocifetch/index.js +14 -0
  106. package/dist/ocifetch/index.js.map +1 -0
  107. package/dist/ocifetch/layout.d.ts +126 -0
  108. package/dist/ocifetch/layout.d.ts.map +1 -0
  109. package/dist/ocifetch/layout.js +375 -0
  110. package/dist/ocifetch/layout.js.map +1 -0
  111. package/dist/ocifetch/localverify.d.ts +43 -0
  112. package/dist/ocifetch/localverify.d.ts.map +1 -0
  113. package/dist/ocifetch/localverify.js +164 -0
  114. package/dist/ocifetch/localverify.js.map +1 -0
  115. package/dist/ocifetch/lock.d.ts +39 -0
  116. package/dist/ocifetch/lock.d.ts.map +1 -0
  117. package/dist/ocifetch/lock.js +140 -0
  118. package/dist/ocifetch/lock.js.map +1 -0
  119. package/dist/ocifetch/oci.d.ts +100 -0
  120. package/dist/ocifetch/oci.d.ts.map +1 -0
  121. package/dist/ocifetch/oci.js +323 -0
  122. package/dist/ocifetch/oci.js.map +1 -0
  123. package/dist/ocifetch/referrers.d.ts +55 -0
  124. package/dist/ocifetch/referrers.d.ts.map +1 -0
  125. package/dist/ocifetch/referrers.js +132 -0
  126. package/dist/ocifetch/referrers.js.map +1 -0
  127. package/dist/ocifetch/types.d.ts +167 -0
  128. package/dist/ocifetch/types.d.ts.map +1 -0
  129. package/dist/ocifetch/types.js +88 -0
  130. package/dist/ocifetch/types.js.map +1 -0
  131. package/dist/ocifetch/unpack.d.ts +55 -0
  132. package/dist/ocifetch/unpack.d.ts.map +1 -0
  133. package/dist/ocifetch/unpack.js +205 -0
  134. package/dist/ocifetch/unpack.js.map +1 -0
  135. package/dist/registry.d.ts +38 -387
  136. package/dist/registry.d.ts.map +1 -1
  137. package/dist/registry.js +94 -819
  138. package/dist/registry.js.map +1 -1
  139. package/dist/schema.d.ts +77 -588
  140. package/dist/schema.d.ts.map +1 -1
  141. package/dist/schema.js +87 -549
  142. package/dist/schema.js.map +1 -1
  143. package/dist/settings.d.ts +27 -36
  144. package/dist/settings.d.ts.map +1 -1
  145. package/dist/settings.js +75 -25
  146. package/dist/settings.js.map +1 -1
  147. package/dist/setup.d.ts +37 -0
  148. package/dist/setup.d.ts.map +1 -0
  149. package/dist/setup.js +60 -0
  150. package/dist/setup.js.map +1 -0
  151. package/dist/tar.d.ts +27 -11
  152. package/dist/tar.d.ts.map +1 -1
  153. package/dist/tar.js +54 -32
  154. package/dist/tar.js.map +1 -1
  155. package/package.json +2 -2
  156. package/dist/discover.d.ts +0 -142
  157. package/dist/discover.d.ts.map +0 -1
  158. package/dist/discover.js +0 -288
  159. package/dist/discover.js.map +0 -1
  160. package/dist/error-codes.d.ts +0 -80
  161. package/dist/error-codes.d.ts.map +0 -1
  162. package/dist/error-codes.js +0 -139
  163. package/dist/error-codes.js.map +0 -1
  164. package/dist/errors.d.ts +0 -284
  165. package/dist/errors.d.ts.map +0 -1
  166. package/dist/errors.js +0 -321
  167. package/dist/errors.js.map +0 -1
  168. package/dist/fetch.d.ts +0 -382
  169. package/dist/fetch.d.ts.map +0 -1
  170. package/dist/fetch.js +0 -1498
  171. package/dist/fetch.js.map +0 -1
  172. package/dist/ffi.d.ts +0 -410
  173. package/dist/ffi.d.ts.map +0 -1
  174. package/dist/ffi.js +0 -1154
  175. package/dist/ffi.js.map +0 -1
  176. package/dist/format.d.ts +0 -128
  177. package/dist/format.d.ts.map +0 -1
  178. package/dist/format.js +0 -132
  179. package/dist/format.js.map +0 -1
  180. package/dist/numeric.d.ts +0 -20
  181. package/dist/numeric.d.ts.map +0 -1
  182. package/dist/numeric.js +0 -107
  183. package/dist/numeric.js.map +0 -1
  184. package/dist/paths.d.ts +0 -55
  185. package/dist/paths.d.ts.map +0 -1
  186. package/dist/paths.js +0 -87
  187. package/dist/paths.js.map +0 -1
  188. package/dist/results.d.ts +0 -495
  189. package/dist/results.d.ts.map +0 -1
  190. package/dist/results.js +0 -406
  191. package/dist/results.js.map +0 -1
  192. package/dist/transform.d.ts +0 -73
  193. package/dist/transform.d.ts.map +0 -1
  194. package/dist/transform.js +0 -533
  195. package/dist/transform.js.map +0 -1
package/dist/fetch.d.ts DELETED
@@ -1,382 +0,0 @@
1
- /**
2
- * Fetching, verifying and installing artifacts — docs/guides/fetch.md, the contract
3
- * every SDK implements identically: the same source (§2), the same
4
- * verification chain (§3), the same signature policy (§4), the same lock
5
- * file (§5), the same function (§6) and the same codes (§7).
6
- *
7
- * Nothing here is a verdict but the chain. No exit code, no
8
- * `Content-Length`, no "download finished" ever is:
9
- *
10
- * 0. `SHA256SUMS.sig` — ed25519 over the exact bytes of `SHA256SUMS`, with a
11
- * trusted key. Failure stops everything; nothing is downloaded around it.
12
- * 1. `index.json` names the asset for the line/platform and its sha256 — only
13
- * ever a row at this binding's own `ABI_REVISION` (docs/guides/fetch.md §2).
14
- * 2. `SHA256SUMS` — now known-authentic — must list the same file with the
15
- * same sha256; a disagreement is a broken release, reported, not repaired.
16
- * 3. The tarball is hashed BEFORE it is unpacked.
17
- * 4. `manifest.json` inside names the library and its sha256; after the
18
- * move into `<registry>/<minor>/`, the installed library is hashed again
19
- * in place.
20
- *
21
- * The install is atomic — unpack into a temporary sibling, rename into place
22
- * — and idempotent: an installed line that hashes what the release says is
23
- * reported as installed and nothing is downloaded.
24
- *
25
- * Steady state is offline: once files are in a registry directory the loader
26
- * trusts the directory, exactly as a runtime trusts `node_modules`.
27
- * Verification is a fetch-time policy, not a load-time gate.
28
- */
29
- /** The public artifacts host (docs/guides/fetch.md §2); `CHTYPES_ARTIFACTS_URL` overrides it. */
30
- export declare const DEFAULT_ARTIFACTS_URL = "https://artifacts.wavehouse.dev";
31
- /** The rolling release every fetch reads by default; `tag` picks a frozen one. */
32
- export declare const DEFAULT_RELEASE_TAG = "artifacts";
33
- /**
34
- * The release signing key(s) — raw 32-byte ed25519 public keys, hex
35
- * (docs/guides/fetch.md §4). `CHTYPES_TRUSTED_KEYS` or the `trustedKeys` option
36
- * REPLACES this list; it is never extended silently.
37
- */
38
- export declare const RELEASE_PUBLIC_KEYS: readonly string[];
39
- /**
40
- * The lock-file schema this SDK writes, and the newest it reads
41
- * (docs/guides/fetch.md §5). Schema 1 (`<os>-<arch>/<minor>`) is still read
42
- * and is converted to schema 2 (`<os>-<arch>/<clickhouse_version>`) the first
43
- * time this SDK writes the file — schema 2 is what a two-patches-per-line
44
- * cache needs to key on, since two patches of one line share a schema-1 key.
45
- * SDKs through 0.4.x cannot read a schema-2 lock and refuse it (issue #284).
46
- */
47
- export declare const LOCK_SCHEMA = 2;
48
- /** The lock file `frozen` reads when no `lock` names one (docs/guides/fetch.md, Decisions); relative, so the working directory's. */
49
- export declare const DEFAULT_LOCK_FILE = "chtypes.lock";
50
- /** One row of a release's `index.json` (docs/guides/artifacts.md §2). */
51
- export interface IndexArtifact {
52
- readonly os: string;
53
- readonly arch: string;
54
- readonly file: string;
55
- /** sha256 of the tarball. */
56
- readonly sha256: string;
57
- /** size of the tarball. */
58
- readonly bytes: number;
59
- readonly clickhouse_version: string;
60
- readonly clickhouse_minor: string;
61
- readonly library: string;
62
- readonly library_sha256: string;
63
- /**
64
- * The wrapper build for this ClickHouse version. A rebuild of the same
65
- * version is a NEW row beside the old one, never a swap, so `build` is what
66
- * separates them. Absent from an old row, and from a file name with no
67
- * `-b<N>` suffix: both mean build 0.
68
- */
69
- readonly build: number;
70
- /** The core commit the wrapper was built from; `''` on an old row. */
71
- readonly core_commit: string;
72
- /**
73
- * The chs_* ABI revision the artifact was built from; absent when the row
74
- * declares none (or declares something that is not an integer), as many
75
- * served rows do. The artifact producer writes the field from the revision
76
- * that introduced it onward, so a row without it is an older revision. Fetch
77
- * installs only a row at this binding's own `ABI_REVISION`
78
- * (docs/guides/fetch.md §2): any other would be refused at load.
79
- */
80
- readonly abi_revision?: number;
81
- }
82
- /** A release's `index.json`, schema 1. */
83
- export interface ReleaseIndex {
84
- readonly schema: number;
85
- readonly generated_at?: string;
86
- readonly release_tag?: string;
87
- readonly license?: string;
88
- readonly license_url?: string;
89
- readonly artifacts: readonly IndexArtifact[];
90
- }
91
- /** One pinned line in a lock file: the asset that was installed and its sha256. */
92
- export interface LockEntry {
93
- readonly file: string;
94
- readonly sha256: string;
95
- /**
96
- * The ABI revision the pinned row carried when this entry was written.
97
- * Optional and additive (docs/guides/fetch.md §5): an entry written before
98
- * this SDK recorded it simply has none, absent exactly as `IndexArtifact.abi_revision`
99
- * is absent on a row built before revisions were recorded.
100
- */
101
- readonly abi_revision?: number;
102
- }
103
- /** `chtypes.lock` (docs/guides/fetch.md §5): `{"schema": 1, "artifacts": {"<os>-<arch>/<minor>": {file, sha256, abi_revision?}}}`. */
104
- export interface LockFile {
105
- readonly schema: number;
106
- readonly artifacts: Record<string, LockEntry>;
107
- }
108
- /** Progress, for a caller that wants to show it (the CLI prints these on stderr). */
109
- export type FetchEvent = {
110
- readonly type: 'status';
111
- readonly message: string;
112
- } | {
113
- readonly type: 'download';
114
- readonly file: string;
115
- readonly received: number;
116
- readonly total: number;
117
- };
118
- /** Options for `ensure`, `ensureAll`, `listArtifacts` — the §6 flags, spelled as properties. */
119
- export interface EnsureOptions {
120
- /** Where to install (`--dest`); default: the §1 write target (`CHTYPES_REGISTRY`, else the per-user cache). */
121
- readonly dest?: string | undefined;
122
- /** `<os>-<arch>` (`--platform`); default: this host (`CHTYPES_TARGET` overrides, as `scripts/fetch.sh`). */
123
- readonly platform?: string | undefined;
124
- /** A release tag on the artifacts host (`--tag`); default the rolling `artifacts`. Exclusive with `url`. */
125
- readonly tag?: string | undefined;
126
- /** Any other base (`--url`): `https://…`, `file://…`, or a plain directory. Exclusive with `tag`. */
127
- readonly url?: string | undefined;
128
- /** A lock file to record into (`--lock`), and to enforce with `frozen`. */
129
- readonly lock?: string | undefined;
130
- /** Refuse anything the lock does not pin, with `CHTYPES_ARTIFACT_PINNED` (`--frozen`). */
131
- readonly frozen?: boolean | undefined;
132
- /** Re-download even when the line is installed and verified (`--force`). */
133
- readonly force?: boolean | undefined;
134
- /** Never touch the source: installed-and-verified is fine, anything else is `CHTYPES_SOURCE_UNREACHABLE` (`--offline`). */
135
- readonly offline?: boolean | undefined;
136
- /** Raw ed25519 public keys, hex; REPLACES the embedded release key (as `CHTYPES_TRUSTED_KEYS` does). */
137
- readonly trustedKeys?: readonly string[] | undefined;
138
- /** Skip the signature (step 0) with one loud warning; never the default (as `CHTYPES_ALLOW_UNSIGNED=1`). */
139
- readonly allowUnsigned?: boolean | undefined;
140
- /** Progress events; silent when absent. */
141
- readonly onProgress?: ((event: FetchEvent) => void) | undefined;
142
- /** Aborts an in-progress download. */
143
- readonly signal?: AbortSignal | undefined;
144
- }
145
- /** What `ensure` did: where the patch is, what it is, and whether bytes moved. */
146
- export interface EnsureResult {
147
- /**
148
- * The installed directory — what `fetch` prints. A LINE request's pick
149
- * installs flat, `<registry>/<minor>`, exactly as before #284. Any other
150
- * exact patch installs at `<registry>/patches/<minor>/<clickhouse_version>`
151
- * (issue #284, the layout the artifact producer's own CI still reads
152
- * `<registry>/<minor>` directly for).
153
- */
154
- readonly dir: string;
155
- /** The registry directory the line lives in. */
156
- readonly registry: string;
157
- readonly line: string;
158
- readonly version: string;
159
- readonly platform: string;
160
- /** The asset name and its sha256 — what the lock records; empty on the offline path. */
161
- readonly file: string;
162
- readonly sha256: string;
163
- readonly library: string;
164
- readonly librarySha256: string;
165
- /** true when the tarball was downloaded and installed by this call; false when the line was already installed and verified. */
166
- readonly installed: boolean;
167
- /** The source that was consulted, or `offline`. */
168
- readonly source: string;
169
- /** Whether `SHA256SUMS` carried a signature a trusted key verified, and that key's id. */
170
- readonly signed: boolean;
171
- readonly keyId: string | null;
172
- }
173
- /** One installed PATCH, as `verify` and `list` report it — one record per patch, flat slot and `patches/` tree alike (issue #284). */
174
- export interface InstalledArtifact {
175
- readonly line: string;
176
- readonly dir: string;
177
- readonly version: string;
178
- readonly library: string;
179
- /** The manifest's sha256; what the file hashes (only `verifyInstalled` fills it in); the verdict. */
180
- readonly expected: string;
181
- readonly actual: string | null;
182
- readonly ok: boolean;
183
- readonly problem: string | null;
184
- }
185
- /** What `list` shows: what is installed, and what the release offers for the platform. */
186
- export interface ListResult {
187
- readonly registry: string;
188
- readonly platform: string;
189
- readonly installed: readonly InstalledArtifact[];
190
- /** null when offline. Only rows at this binding's ABI revision (docs/guides/fetch.md §2). */
191
- readonly offered: readonly IndexArtifact[] | null;
192
- readonly source: string | null;
193
- /**
194
- * One line naming the platform's rows at another ABI revision, which
195
- * `offered` leaves out (docs/guides/fetch.md §6); absent when none were left
196
- * out, or offline.
197
- */
198
- readonly notShown?: string;
199
- }
200
- /** How a version was asked for: the line, and the exact patch if one was typed. */
201
- export interface VersionRequest {
202
- readonly spelling: string;
203
- /** e.g. `25.8`. */
204
- readonly line: string;
205
- /** `25.8.28.1-lts` when a patch was typed (a hard requirement), else null. */
206
- readonly exact: string | null;
207
- /** The exact patch without its channel suffix, when one was typed. */
208
- readonly bare: string | null;
209
- }
210
- /**
211
- * `25.8` is a line; `25.8.28.1-lts`, `v25.8.28.1-lts` and `25.8.28.1` are an
212
- * exact patch and a hard requirement (a release that publishes another patch
213
- * of the line refuses it — ask for the line to take what was published).
214
- *
215
- * @throws {ChtypesError} when the spelling is not a ClickHouse version at all.
216
- */
217
- export declare function parseVersionSpelling(spelling: string): VersionRequest;
218
- /**
219
- * Decision 7 / R2 (issue #284): does `candidate` — a served or installed
220
- * `clickhouse_version` — match `req`? A spelled channel (`-lts` etc.) matches
221
- * only itself; an unspelled one matches that patch on any channel. This is
222
- * the ONE matching rule for every place a patch is matched: the registry, the
223
- * release, the lock and `scripts/fetch.sh`. `false` for a line request — a
224
- * line never "matches" a patch under this rule, it CONTAINS one.
225
- */
226
- export declare function patchMatches(candidate: string, req: VersionRequest): boolean;
227
- /** Numeric order over dotted versions, channel suffix ignored: 25.10 > 25.8, 25.8.30.16 > 25.8.28.1. */
228
- export declare function compareVersions(a: string, b: string): number;
229
- /** The key id docs/guides/fetch.md §4 defines: the first 16 hex characters of sha256 over the raw 32-byte public key. */
230
- export declare function keyId(rawKeyHex: string): string;
231
- /**
232
- * `keyId(RELEASE_PUBLIC_KEYS[0])`, precomputed — the id the signature file's
233
- * comment line names for the primary release key. `RELEASE_PUBLIC_KEYS` stays
234
- * the list to verify against (rotation adds a second entry); this is the one
235
- * short id go/python/rust each export as a scalar constant.
236
- */
237
- export declare const RELEASE_KEY_ID: string;
238
- /**
239
- * Verify an ed25519 signature over `message` with a raw public key, through
240
- * `node:crypto` — the key wrapped as SPKI DER, the 64-byte signature as is.
241
- * False, never a throw, for a malformed key or signature.
242
- */
243
- export declare function verifyEd25519(message: Uint8Array, signature: Uint8Array, rawKeyHex: string): boolean;
244
- /**
245
- * `SHA256SUMS.sig`: an `untrusted comment:` line, then the base64 of the
246
- * 64-byte signature. Null when the file is not in that shape.
247
- */
248
- export declare function parseSignatureFile(bytes: Uint8Array): {
249
- comment: string;
250
- signature: Buffer;
251
- } | null;
252
- /**
253
- * The keys a fetch trusts: the `trustedKeys` option, else `CHTYPES_TRUSTED_KEYS`
254
- * (`<hex>[,<hex>…]`), else the embedded release key. Each REPLACES the one
255
- * below it.
256
- *
257
- * @throws {ChtypesError} when an entry is not 64 hex characters.
258
- */
259
- export declare function trustedKeys(explicit?: readonly string[]): string[];
260
- /**
261
- * How many times {@link loadRelease} (and {@link installGoldens}'s own retry)
262
- * reads an HTTP release before giving up, and the BASE delay (ms) before the
263
- * first retry — each later retry doubles it, so the default 5 attempts sleep
264
- * 4+8+16+32 = 60s (~70s wall with network time). That is chosen to outlast
265
- * the artifacts host's edge cache (observed `Cache-Control: max-age=60` on
266
- * the mutable release objects, so a stale pairing of any of them can persist
267
- * up to 60s), while a genuine few-second mid-publish window still clears on
268
- * the second attempt.
269
- *
270
- * A mutable object, not two `const`s: an ES module's imported bindings are
271
- * read-only, so a plain exported `let` could not be reassigned from outside,
272
- * and the fetch test suite needs to shrink `delayMs` to near zero. Not
273
- * re-exported from `index.ts` — internal to this module and its test suite.
274
- */
275
- export declare const RELEASE_RETRY: {
276
- attempts: number;
277
- delayMs: number;
278
- };
279
- /**
280
- * TEST-ONLY. When `override` is set, the ABI revision fetch selects release rows
281
- * at, in place of `ABI_REVISION` (docs/guides/fetch.md §2). The fetch-fixture
282
- * suite sets it to the revision its fixture release carries — derived from that
283
- * release's own `index.json` — so a binding whose own revision has moved ahead
284
- * of the fixtures still exercises the whole chain. It changes WHICH rows are
285
- * eligible and nothing else: the default registry directory stays
286
- * `abi<ABI_REVISION>/`, and the loader still refuses an artifact of another
287
- * revision.
288
- *
289
- * A mutable object for the same reason as {@link RELEASE_RETRY}: an imported
290
- * binding is read-only. Not re-exported from `index.ts` — internal to this
291
- * module and its test suite, never part of the public contract.
292
- */
293
- export declare const FETCH_ABI_REVISION: {
294
- override: number | null;
295
- };
296
- /**
297
- * One message per line the release has for `platform` only at another ABI
298
- * revision, or only in rows that record none — the lines `ensureAll` installs
299
- * nothing for — oldest line first. Exported for the test suite only; not
300
- * re-exported from `index.ts`.
301
- */
302
- export declare function skippedLines(index: ReleaseIndex, platform: string): string[];
303
- /**
304
- * `list`'s one line naming the platform's rows at another ABI revision, which it
305
- * does not show (docs/guides/fetch.md §6); `undefined` when none were hidden.
306
- * Rows that carry no `abi_revision` are named for what they are — built before
307
- * revisions were recorded — never as a revision called "none". Exported for the
308
- * test suite only; not re-exported from `index.ts`.
309
- */
310
- export declare function notShown(index: ReleaseIndex, platform: string): string | undefined;
311
- /**
312
- * The one row for a request, or `CHTYPES_ARTIFACT_UNPUBLISHED` naming what the
313
- * release does have. Only rows at this binding's ABI revision are considered,
314
- * FIRST (docs/guides/fetch.md §2): nothing at that revision is unpublished, never
315
- * another revision's row.
316
- */
317
- export declare function selectArtifact(index: ReleaseIndex, platform: string, req: VersionRequest): IndexArtifact;
318
- /**
319
- * Every line the release publishes for the platform at this binding's ABI
320
- * revision, newest patch (then highest build) per line, oldest line first.
321
- * Nothing at that revision is `CHTYPES_ARTIFACT_UNPUBLISHED`, naming the
322
- * revision(s) the release does serve (docs/guides/fetch.md §2).
323
- */
324
- export declare function selectAll(index: ReleaseIndex, platform: string): IndexArtifact[];
325
- /**
326
- * Make one ClickHouse line available in a registry directory, through the
327
- * verification chain, and say where it is. Idempotent: installed and
328
- * verified is a no-op that downloads nothing (`force` re-downloads).
329
- *
330
- * @param spelling - a line (`"25.8"`) or an exact patch (`"25.8.28.1-lts"`, a hard requirement).
331
- * @param options - see `EnsureOptions`; every §6 flag has a property here.
332
- * @returns where the line is and what it is — `dir` is `<registry>/<minor>`.
333
- * @throws {ArtifactUntrustedError} `CHTYPES_ARTIFACT_UNTRUSTED` — no signature, or none a trusted key verifies.
334
- * @throws {ArtifactCorruptError} `CHTYPES_ARTIFACT_CORRUPT` — any hash mismatch, a release that disagrees with itself.
335
- * @throws {ArtifactPinnedError} `CHTYPES_ARTIFACT_PINNED` — `frozen` and the lock says otherwise.
336
- * @throws {ArtifactUnpublishedError} `CHTYPES_ARTIFACT_UNPUBLISHED` — nothing for this platform/line/patch.
337
- * @throws {SourceUnreachableError} `CHTYPES_SOURCE_UNREACHABLE` — the source cannot be reached, or `offline` and not installed.
338
- * @throws {ChtypesError} for a spelling that is not a version, a bad platform key, or conflicting options.
339
- */
340
- export declare function ensure(spelling: string, options?: EnsureOptions): Promise<EnsureResult>;
341
- /**
342
- * `fetch --all`: every line the release publishes for the platform at this
343
- * binding's ABI revision, each through `ensure`'s chain — installed flat, as
344
- * a line request always is. A line it has only at another revision is not
345
- * installed and is named in one loud stderr line; the rest go on.
346
- *
347
- * Under `--frozen` (F6): every line the lock pins for this platform, at its
348
- * own newest pinned patch — never a line the release has that the lock does
349
- * not pin (that is not drift in anything that was pinned). Every candidate's
350
- * ABI revision is checked (F2) before the release is even read.
351
- */
352
- export declare function ensureAll(options?: EnsureOptions): Promise<EnsureResult[]>;
353
- /**
354
- * `chtypes verify`: re-hash every installed PATCH in a registry directory —
355
- * the flat slot and every `patches/<minor>/<version>/` sibling (issue #284)
356
- * — against its own manifest. A directory whose manifest cannot be read is
357
- * not a patch (a scratch directory) and is skipped, as the loader skips it.
358
- */
359
- export declare function verifyInstalled(dest?: string, platform?: string): Promise<InstalledArtifact[]>;
360
- /** `chtypes list`: what is installed in the registry directory (one record per patch), and what the release offers for the platform. */
361
- export declare function listArtifacts(options?: EnsureOptions): Promise<ListResult>;
362
- /**
363
- * Read a lock file; `null` when it does not exist. Accepts schema 1 and
364
- * schema 2 (docs/guides/fetch.md §5); `.schema` reports the number that was
365
- * actually on disk (so a caller can tell which it read), while `.artifacts`
366
- * is ALWAYS schema-2-shaped: a schema-1 entry `<os>-<arch>/<minor>` is
367
- * converted to the schema-2 entry `<os>-<arch>/<v>`, `<v>` being the
368
- * ClickHouse version its own `file` names — the one schema-1 could not
369
- * record, because it never had two patches of a line to distinguish. Every
370
- * other reader in this module treats `.artifacts` as schema-2-keyed
371
- * unconditionally; only this doc comment and `.schema` itself ever mention
372
- * schema 1 again. Any other schema number is refused, naming both 1 and
373
- * `LOCK_SCHEMA`. An entry that does not parse, under either schema — including
374
- * a schema-2 key that names a bare line rather than an exact patch — makes the
375
- * whole lock unreadable and the error names it.
376
- */
377
- export declare function readLock(file: string): LockFile | null;
378
- /** The platform a fetch is for: the option, else `CHTYPES_TARGET`, else this host. */
379
- export declare function resolvePlatform(explicit?: string): string;
380
- /** sha256 of a file, streamed — a 300 MB library never sits in memory whole. */
381
- export declare function sha256File(file: string): Promise<string>;
382
- //# sourceMappingURL=fetch.d.ts.map
@@ -1 +0,0 @@
1
- {"version":3,"file":"fetch.d.ts","sourceRoot":"","sources":["../src/fetch.ts"],"names":[],"mappings":"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"}