@wavehouse/chtypes 0.5.1 → 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 +47 -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 -385
  136. package/dist/registry.d.ts.map +1 -1
  137. package/dist/registry.js +94 -817
  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 -260
  165. package/dist/errors.d.ts.map +0 -1
  166. package/dist/errors.js +0 -290
  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 -400
  173. package/dist/ffi.d.ts.map +0 -1
  174. package/dist/ffi.js +0 -1091
  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 -460
  189. package/dist/results.d.ts.map +0 -1
  190. package/dist/results.js +0 -407
  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
@@ -1,393 +1,46 @@
1
1
  /**
2
- * The artifact-directory loader: one subdirectory per ClickHouse minor line,
3
- * each self-contained (docs/reference/artifact.md), plus — since #284 — every
4
- * OTHER installed exact patch of a line, in a sibling `patches/` tree:
5
- *
6
- * <registry>/25.8/{manifest.json, libchtypes.dylib, CH_VERSION, unsafe_families.txt}
7
- * <registry>/patches/25.8/25.8.28.1-lts/{manifest.json, libchtypes.dylib, ...}
8
- *
9
- * The flat `<registry>/<minor>/` slot is what a LINE request resolves to —
10
- * exactly the pre-#284 layout, so every SDK through 0.4.x keeps reading it
11
- * unchanged. Any OTHER exact patch of that line lives in
12
- * `<registry>/patches/<minor>/<clickhouse_version>/`, which no released SDK
13
- * (0.4.x and earlier) scans, fetches into or deletes (measured, issue #284
14
- * comment 5919199794): it is a new, additive tree, not a migration of the old
15
- * one. When a line fetch changes which patch occupies the flat slot, the
16
- * outgoing install is DEMOTED — an atomic, same-filesystem rename into
17
- * `patches/<minor>/<its version>/` — never deleted, so a server still on the
18
- * older patch keeps its exact match with no re-fetch.
19
- *
20
- * Two rules here were paid for and are not negotiable:
21
- *
22
- * - **The shared library's file name comes from `manifest.json`'s `library`
23
- * field.** Not from a hard-coded `libchtypes.so`, not from a glob, not from
24
- * the platform. The current tree proves why: every darwin artifact says
25
- * `libchtypes.dylib` while the *shipping* linux artifacts still say
26
- * `libchtypes_s1.so`, so a loader that constructs the name finds nothing on
27
- * the platform that matters.
28
- * - **Each artifact is loaded into its own symbol scope (`RTLD_LOCAL`).** That
29
- * is the entire mechanism by which two builds that both define
30
- * `DB::DataTypeFactory` live in one process — now routinely two builds of
31
- * the SAME minor line, one per patch. ffi-rs loads through libloading,
32
- * which uses `RTLD_LAZY | RTLD_LOCAL`; `assertLocalSymbolScope()` in the
33
- * test suite proves it from outside rather than trusting the claim.
34
- *
35
- * Where a registry IS follows the search path of docs/guides/fetch.md §1 (`paths.ts`):
36
- * the explicit directory, `CHTYPES_REGISTRY`, the per-user cache, then the
37
- * reserved system locations. Construction READS THE MANIFESTS on that path and
38
- * `dlopen`s nothing; a version is taken, on request, from the first directory
39
- * that has it. Resolution (docs/reference/bindings.md §Version selection):
40
- *
41
- * - **A line request** ("25.8") never falls back and never crosses lines: the
42
- * newest patch of the line, in the first search-path directory that holds
43
- * any patch of it (a nested install beating a flat one on a version tie),
44
- * pinned for this registry for as long as it runs.
45
- * - **A patch request** ("25.8.28.1-lts") loads that exact patch when it is
46
- * open or installed anywhere on the search path. Otherwise it falls back to
47
- * the newest installed patch of the same line, flags the result
48
- * `exact: false`, and warns once per (requested, actual) pair per process —
49
- * never another line, which stays the one §7 error, `ArtifactMissingError`.
50
- *
51
- * A patch spelled with no channel suffix matches that patch on any channel
52
- * (docs/guides/fetch.md Decision 7); ordering is numeric, channel ignored.
2
+ * `Registry`: from a version request to a loaded `Library`
3
+ * (`docs/reference/bindings-v1.md` §6, "The sequence").
4
+ *
5
+ * registry.for(request)
6
+ * 1. the registry's memo: a request opened before returns the same Library,
7
+ * for the registry's life (a line request never moves mid-process: a
8
+ * newer patch installed later is picked up by a new registry)
9
+ * 2. resolved = resolveInstalled(request, host platform, fetch options) never the network
10
+ * 3. on a miss: autofetch on -> resolved = ensure(request, fetch options) may use the network
11
+ * autofetch off -> ArtifactMissingError, naming request and platform
12
+ * 4. input = adapt(resolved): the library path, the predicate VERBATIM (never
13
+ * re-encoded: a re-encoding is a second derivation of the statement the
14
+ * signature covered) and the platform
15
+ * 5. loader steps 1-6, once per image; step 7 under the process setup
16
+ * 6. the image's Library, whose `resolved` is the record that first opened it
17
+ *
18
+ * Construction opens nothing: `Registry.open` is asynchronous only because the
19
+ * fetch layer is, and nothing opens an artifact except a request for a version
20
+ * or `preload`. The binding orders and matches no versions itself: which
21
+ * installed build a floating request means is the fetch layer's.
53
22
  */
54
- import { type EnsureOptions } from './fetch.js';
55
- import { Library } from './library.js';
56
- /** The nine fields `lib/build.sh` writes. Unknown fields are ignored. */
57
- export interface Manifest {
58
- library: string;
59
- library_bytes?: number;
60
- library_sha256?: string;
61
- clickhouse_version?: string;
62
- clickhouse_minor?: string;
63
- clickhouse_commit?: string;
64
- os?: string;
65
- arch?: string;
66
- unsafe_families?: string;
67
- }
68
- /** Options for `new Registry(dir, options)`. */
23
+ import { type Library } from './library.js';
24
+ import { type FetchV1Options, type Resolved } from './ocifetch/index.js';
25
+ /** The fetch layer's options (bases, cache directory, system directories, trusted keys, token, allow-unsigned, offline, frozen, lock path, ...) without its test-only hooks. */
26
+ export type FetchOptions = Omit<FetchV1Options, 'beforeIndexRename' | 'httpLog' | 'clock'>;
69
27
  export interface RegistryOptions {
70
- /**
71
- * The server timezone assumed for bare DateTime / DateTime64 columns. Defaults
72
- * to UTC — what a stock ClickHouse container uses — and is deliberately not
73
- * read from the environment, so the host's TZ cannot leak into results.
74
- */
75
- timezone?: string;
76
- /**
77
- * Re-hash each library and compare against `manifest.library_sha256` before
78
- * loading. SHOULD be on for an artifact that came from anywhere but a local
79
- * build, and MUST be on for one that came over a network.
80
- *
81
- * A policy on the REGISTRY, not a property of `preload`: a library's
82
- * checksum is computed immediately before that library is `dlopen`ed and at
83
- * no other time — at construction for the preloaded lines, at first use for
84
- * the rest, never for a line nobody asks for.
85
- *
86
- * What this option ADDS is the sha256 comparison. The cheaper
87
- * `manifest.library_bytes` size check that runs just before it is NOT
88
- * conditional on this option — `load()` below always makes it, on every
89
- * open, regardless (issue #82). Its timing is the same as the checksum's:
90
- * at construction for the preloaded lines, at first use for the rest.
91
- */
92
- verifyChecksums?: boolean;
93
- /**
94
- * Open these lines AT CONSTRUCTION — the one eager path, and the same option
95
- * Go spells `WithPreload(...)`, Python `preload=[...]` and Rust
96
- * `RegistryOptions::preload`.
97
- *
98
- * Each entry is a version spelling resolved exactly as `for()` resolves one:
99
- * a minor line (`'25.8'`) or an exact patch (`'25.8.28.1-lts'`), never a
100
- * path. They are opened in the order given, before the constructor returns,
101
- * and an entry no directory on the §1 search path holds is
102
- * `ArtifactMissingError` — the same §7 error the first `for()` would have
103
- * thrown, thrown earlier. A patch entry that falls back to its line warns at
104
- * construction, exactly as `for()` would.
105
- *
106
- * It NEVER fetches, even with `autofetch` on: this constructor is
107
- * synchronous and `ensure()` is not, and autofetch is a first-use behavior
108
- * in all four bindings. An empty list is exactly the default.
109
- *
110
- * Deliberately a list of lines rather than "everything in the directory": a
111
- * registry directory is whatever a fetch left behind, and each open costs
112
- * about 120 MB resident.
113
- */
114
- preload?: readonly string[] | undefined;
115
- /**
116
- * Lazy fetch on first open (docs/guides/fetch.md §6): `open()` of a version no
117
- * directory on the search path holds runs `ensure()` first, into the
118
- * directory a fetch writes to (§1), once per process per (destination,
119
- * spelling). Off by default — a production process must not begin a 250 MB
120
- * download inside a request — and `CHTYPES_AUTOFETCH=1` turns it on from the
121
- * environment. `for()` / `resolve()` stay synchronous and never fetch.
122
- */
123
- autofetch?: boolean | undefined;
124
- /** Options handed to `ensure()` by autofetch: source (`url`/`tag`), lock, keys, progress. */
125
- fetch?: EnsureOptions | undefined;
126
- }
127
- /**
128
- * What a `resolve()` / `openResolution()` call hands back: the loaded
129
- * `Library`, the caller's own spelling, what actually loaded, and whether the
130
- * two are the same patch (docs/reference/bindings.md §Version selection).
131
- * `for()` / `open()` run the same resolution and hand back only `.library`.
132
- */
133
- export interface Resolution {
134
- /** The `Library` this resolution loaded (or found already loaded). */
135
- readonly library: Library;
136
- /** The caller's own spelling, trimmed — never normalized further. */
137
- readonly requested: string;
138
- /**
139
- * What actually loaded, i.e. `library.version`. Equal to the requested
140
- * patch when `exact` is true; the newest installed/published patch of the
141
- * requested line otherwise.
142
- */
143
- readonly version: string;
144
- /**
145
- * `true` for a line request — it asked for "a patch of this line" and got
146
- * one. For a patch request, `true` only when the loaded version matches the
147
- * requested patch (a spelled channel matches only itself; an unspelled one
148
- * matches on any channel). `false` means the fallback within the line was
149
- * taken, and a warning was already issued for this (requested, actual) pair
150
- * — once per pair per process.
151
- */
152
- readonly exact: boolean;
28
+ readonly fetch?: FetchOptions | undefined;
29
+ /** Fetch on a miss. Defaults to the `CHTYPES_AUTOFETCH` environment variable, and is off when that is unset. */
30
+ readonly autofetch?: boolean | undefined;
31
+ /** Requests opened at construction, in list order. They never fetch, even with autofetch on. */
32
+ readonly preload?: readonly string[] | undefined;
153
33
  }
154
- /** TEST-ONLY: forget every warned pair, so a suite can assert a fresh warning fires. Not re-exported from index.ts. */
155
- export declare function resetPatchFallbackWarnings(): void;
156
- /**
157
- * The artifact-directory loader — the multi-version entry point of this
158
- * package.
159
- *
160
- * **Construction reads `manifest.json` files and `dlopen`s nothing**, with or
161
- * without a directory. Nothing in this package opens an artifact except a
162
- * request for a specific version (`for()` / `resolve()` / `open()` /
163
- * `openResolution()`) or an explicit `preload` — not `versions()`, not
164
- * `libraries()`, not `has()`. An open costs about 120 MB resident per patch,
165
- * which a listing call must not spend on a caller's behalf, and which grows
166
- * with every DISTINCT patch a process is asked for — libraries are never
167
- * dlclosed (docs/guides/multi-version.md).
168
- *
169
- * An open dlopens the artifact into its own symbol scope (`RTLD_LOCAL`),
170
- * verifies its ABI revision against this binding's `ABI_REVISION` (a different
171
- * nonzero revision is refused; 0 means the artifact predates the probe and
172
- * degrades per symbol), and runs that library's one-time `chs_init` with the
173
- * registry's timezone and the artifact's own `unsafe_families.txt`.
174
- *
175
- * Libraries are never dlclosed; `close()` joins background threads only.
176
- * Loading the same artifact path from two `Registry` instances shares one
177
- * loaded image, so `chs_init` still runs exactly once per artifact.
178
- */
179
34
  export declare class Registry {
180
- /**
181
- * The primary registry directory: the first on the search path that holds
182
- * artifacts — or, with `autofetch` and nothing installed anywhere, the
183
- * directory the first fetch will create.
184
- */
185
- readonly dir: string;
186
- /** The §1 search path, in order, every candidate whether or not it exists. */
187
- readonly searchPath: readonly string[];
188
- /** This host's platform key, e.g. `darwin-arm64` — the only artifacts a process can dlopen. */
189
- readonly platform: string;
190
- private readonly byPath;
191
- private readonly loaded;
192
- /** Line -> the library currently answering FOR THE LINE. Set once per line; never re-pointed while this registry runs (R3/R8). */
193
- private readonly linePins;
194
- /**
195
- * Line -> every patch the construction-time manifest scan found for it,
196
- * across the whole search path. What `versions()` answers from, and what
197
- * makes "no artifact anywhere" and a bad `preload` entry decidable at
198
- * construction without a single `dlopen`. Resolution itself re-scans the
199
- * live filesystem on every call (a patch installed after construction, by
200
- * this process or another, is used from the next call on).
201
- */
202
- private readonly known;
203
- private readonly timezone;
204
- private readonly verifyChecksums;
205
- private readonly autofetch;
206
- private readonly fetchOptions;
207
- private readonly explicit;
208
- /** (dest, line) already `Ensure()`d successfully by THIS registry's autofetch — never re-read over the network again. */
209
- private readonly ensuredLines;
210
- /** (dest, exact patch) autofetch has already confirmed CHTYPES_ARTIFACT_UNPUBLISHED for — never retried within this registry's lifetime. */
211
- private readonly unpublishedPatches;
212
- /**
213
- * Scan a registry. Reads manifests; opens nothing unless `preload` names a
214
- * version.
215
- *
216
- * @param dir - the registry root; the head of the search path. Absent, the
217
- * path is `CHTYPES_REGISTRY`, the per-user artifact cache, then the system
218
- * locations (see `registrySearchPath` / `defaultRegistryDir`).
219
- * @param options - timezone, checksum verification, autofetch, preload — see
220
- * `RegistryOptions`.
221
- * @throws {RegistryError} for what manifests can decide, and only that: a
222
- * directory named explicitly (the argument or `CHTYPES_REGISTRY`) that does
223
- * not exist, and no directory on the search path holding a readable
224
- * manifest at either slot — both suppressed when autofetch is on. A
225
- * `preload` entry no directory holds is `ArtifactMissingError`. Everything
226
- * a bad artifact can be wrong about — a failed checksum, a load failure, a
227
- * library whose ClickHouse version disagrees with its manifest — is
228
- * reported by the call that opens it, which is `preload`'s open at
229
- * construction or the first `for()` otherwise.
230
- * @throws {ChtypesError} when an artifact reports a different nonzero ABI
231
- * revision than this binding speaks, or `chs_init` fails (e.g. an unknown
232
- * timezone — the message names it); again, from the call that opens it.
233
- */
234
- constructor(dir?: string, options?: RegistryOptions);
235
- /**
236
- * Open one `preload` entry, before the constructor returns, without
237
- * fetching. Resolution is `for()`'s (minus any fetch), and so is the
238
- * failure: a version no directory holds anywhere is the same
239
- * `ArtifactMissingError`, raised earlier. A patch entry that falls back
240
- * warns here, at construction, exactly as `for()` would.
241
- */
242
- private preloadLine;
243
- /** dlopen one artifact directory, cross-check it, `chs_init` it, index it. */
244
- private load;
245
- /** Load an artifact directory whose manifest is already known-readable, or return null when it is not one. */
246
- private loadDir;
247
- /** Every patch (both slots, every search-path root) this registry can currently see for `minor` — a live scan. */
248
- private scanLine;
249
- /** R3: line request — the pin if this registry already has one, else the newest patch in the first root that holds any. */
250
- private resolveLineSync;
251
- /** R4 steps 1-2: an exact match, already open or anywhere on the search path — never a fallback. */
252
- private resolveExactPatchSync;
253
- /**
254
- * R4 in full, synchronous shape: exact, else the newest-installed fallback
255
- * within the line. R-c: the already-open check is free (no I/O) and always
256
- * current; everything past it needs a directory read per search-path entry,
257
- * so once a request has fallen back, the WHOLE re-check — retrying the exact
258
- * match and picking the fallback alike — is throttled together, at most
259
- * once per `FALLBACK_RECHECK_MS` per requested patch per process.
260
- *
261
- * §3: the warning fires as soon as the fallback patch is CHOSEN — its
262
- * version is already known from the manifest scan, before `loadDir` ever
263
- * runs — so a caller sees the warning even when the chosen directory then
264
- * fails to load (a broken artifact is still a fallback that was taken).
265
- */
266
- private resolvePatchSync;
267
- private resolveSync;
268
- /** Would `req` resolve without opening anything? Mirrors `resolveSync` with no `load()` call. */
269
- private wouldResolve;
270
- private warnFallback;
271
- /**
272
- * Every ClickHouse minor line this registry CAN ANSWER FOR, oldest first —
273
- * the ones it has opened plus the ones its construction-time manifest scan
274
- * discovered on the search path, at either slot.
275
- *
276
- * That is one meaning in all four bindings, and it is the meaning that
277
- * survives lazy loading: "the lines that happen to be open" would read as an
278
- * empty registry until the first `for()`. It opens nothing.
279
- */
280
- versions(): string[];
281
- /**
282
- * The libraries this registry has OPENED, in full numeric version order —
283
- * what is open right now, never what could be. Two patches of one line both
284
- * appear, each in its own slot in this order. A discovered patch that no
285
- * `for()` and no `preload` has opened appears in `versions()` and not here.
286
- * It opens nothing.
287
- */
35
+ #private;
36
+ private constructor();
37
+ /** Construct a registry. It opens nothing, except each `preload` request, in list order. */
38
+ static open(options?: RegistryOptions): Promise<Registry>;
39
+ /** Open a version: the installed build the request names, fetched first when autofetch is on and none is installed. */
40
+ for(request: string): Promise<Library>;
41
+ /** What is installed: the fetch layer's own listing. */
42
+ installed(): Promise<readonly Resolved[]>;
43
+ /** The libraries this registry has opened, in order of first open. */
288
44
  libraries(): readonly Library[];
289
- /**
290
- * Resolve a version to its library. A minor line ("25.8") never falls back:
291
- * the newest patch of the line, from the first search-path directory that
292
- * holds any patch of it. An exact patch ("25.8.28.1-lts") loads that patch
293
- * when it is open or installed anywhere on the search path; otherwise the
294
- * newest installed patch of the same line is loaded instead, and one
295
- * warning is written per (requested, actual) pair per process — `resolve()`
296
- * reports the same fallback as `exact: false` instead of only warning.
297
- *
298
- * **This is what opens an artifact.** Construction does not: a version is
299
- * loaded on first request, `dlopen`ed once, and joins `libraries()` from
300
- * then on. Never a fetch: this call is synchronous; `open()` /
301
- * `openResolution()` are the ones that may fetch.
302
- *
303
- * Failure is the one §7 error, never a fallback to another line: answering
304
- * 26.7 semantics from a 25.8 artifact is a lie, and silent wrongness is what
305
- * the rigs score hardest.
306
- *
307
- * @param version - a minor line (`"25.8"`) or an exact patch
308
- * (`"25.8.28.1-lts"`), e.g. what `parseVersionResult` discovered.
309
- * @returns the loaded `Library` for that version.
310
- * @throws {ArtifactMissingError} (`code` `CHTYPES_ARTIFACT_MISSING`, a
311
- * `RegistryError`) when no directory on the search path holds a matching
312
- * or fallback patch; the message names every directory looked in and the
313
- * fetch command.
314
- * @throws {ChtypesError} when `version` is not a ClickHouse version spelling at all.
315
- * @throws {RegistryError} when a directory holds a version but it does not load.
316
- */
317
- for(version: string): Library;
318
- /**
319
- * `for()`, but returns the full `Resolution` — the requested spelling, what
320
- * actually loaded, and whether the two are the same patch. Never fetches;
321
- * `openResolution()` is the async twin that may.
322
- *
323
- * @throws {ArtifactMissingError} as `for()`.
324
- * @throws {ChtypesError} when `version` is not a ClickHouse version spelling at all.
325
- */
326
- resolve(version: string): Resolution;
327
- /**
328
- * `for()`, with the lazy fetch of docs/guides/fetch.md §6 in front of it. A
329
- * LINE request no directory holds is fetched through `ensure()` and loaded.
330
- * A PATCH request tries `ensure()` of that exact patch first; on
331
- * `CHTYPES_ARTIFACT_UNPUBLISHED` (remembered for this registry, so it costs
332
- * one network round trip, not one per call) it falls back to `ensure()` of
333
- * the line and loads whatever that installs, with `exact: false` and one
334
- * warning. Any other fetch failure (untrusted, corrupt, pinned, source
335
- * unreachable) surfaces as itself and is never remembered, so a later call
336
- * retries. With `autofetch` off, this is `for()` behind a promise.
337
- *
338
- * @throws {ArtifactMissingError} when nothing is found and autofetch is off.
339
- * @throws {FetchError} the §7 fetch verdicts (`CHTYPES_ARTIFACT_UNTRUSTED`,
340
- * `…_CORRUPT`, `…_PINNED`, `…_UNPUBLISHED`, `CHTYPES_SOURCE_UNREACHABLE`).
341
- * @throws {RegistryError} when the fetched artifact does not load.
342
- */
343
- open(version: string): Promise<Library>;
344
- /** `open()`, but returns the full `Resolution` — see `resolve()` and `open()`. */
345
- openResolution(version: string): Promise<Resolution>;
346
- /** `ensure(line)`, at most once per (dest, line) over this registry's lifetime — never re-read over the network again. */
347
- private ensureLineOnce;
348
- /**
349
- * True when this registry can answer for a version without fetching or
350
- * loading: already open, or held by a directory on the search path (at
351
- * either slot) which `for()` would load. A patch resolves true when the
352
- * patch itself, or any patch of its line, is installed or open — the same
353
- * condition `for()` would resolve, fallback included. Never a fetch, and
354
- * never a load.
355
- */
356
- has(version: string): boolean;
357
- /**
358
- * Join every loaded library's background threads. `chs_init` registers
359
- * `chs_shutdown` with `atexit`, so an ordinary process needs no call; a test
360
- * that must not depend on `atexit` should make one.
361
- */
362
- close(): void;
363
- /** `using registry = new Registry(...)` closes it at scope exit. */
364
- [Symbol.dispose](): void;
365
45
  }
366
- /** Numeric ordering: 25.10 is a later minor than 25.8, whatever strings say. */
367
- export declare function compareMinor(a: string, b: string): number;
368
- /**
369
- * Where the registry is: the explicit argument, else `CHTYPES_REGISTRY`, else
370
- * the first of the per-user artifact cache and the system locations that
371
- * holds artifacts (docs/guides/fetch.md §1). An explicit path and the environment
372
- * variable are returned as given — a wrong one must produce an error naming
373
- * it, not a silent fallback — while the unnamed candidates only count if they
374
- * actually hold artifacts.
375
- */
376
- export declare function resolveRegistryDir(explicit?: string): string | null;
377
- /**
378
- * The per-user artifact cache for this host —
379
- * `${XDG_CACHE_HOME:-~/.cache}/chtypes/artifacts/abi<R>/<os>-<arch>`, R this
380
- * binding's `ABI_REVISION` and `<arch>` spelled the artifact way (`amd64`,
381
- * `arm64`). Where `chtypes fetch` and `scripts/fetch.sh` install, and what
382
- * every SDK's tests and playgrounds fall back to when `CHTYPES_REGISTRY` is
383
- * unset — one directory the four SDKs at the same revision agree on. A path,
384
- * not a promise: `Registry` still throws if nothing is there.
385
- */
386
- export declare function defaultRegistryDir(): string;
387
- /**
388
- * Does this directory hold at least one artifact with a usable manifest, at
389
- * either slot — the flat `<dir>/<minor>/` layout or the `<dir>/patches/<minor>/<version>/`
390
- * sibling tree? A registry that holds only nested installs is not empty.
391
- */
392
- export declare function looksLikeRegistry(dir: string): boolean;
393
46
  //# sourceMappingURL=registry.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAKH,OAAO,EAAE,KAAK,OAAO,EAAa,MAAM,cAAc,CAAC;AACvD,OAAO,EAGL,KAAK,cAAc,EAInB,KAAK,QAAQ,EAEd,MAAM,qBAAqB,CAAC;AAK7B,gLAAgL;AAChL,MAAM,MAAM,YAAY,GAAG,IAAI,CAAC,cAAc,EAAE,mBAAmB,GAAG,SAAS,GAAG,OAAO,CAAC,CAAC;AAE3F,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,KAAK,CAAC,EAAE,YAAY,GAAG,SAAS,CAAC;IAC1C,gHAAgH;IAChH,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACzC,gGAAgG;IAChG,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC;CAClD;AAiBD,qBAAa,QAAQ;;IAMnB,OAAO,eAGN;IAED,4FAA4F;IAC5F,OAAa,IAAI,CAAC,OAAO,GAAE,eAAoB,GAAG,OAAO,CAAC,QAAQ,CAAC,CAOlE;IAED,uHAAuH;IACjH,GAAG,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAG3C;IAED,wDAAwD;IAClD,SAAS,IAAI,OAAO,CAAC,SAAS,QAAQ,EAAE,CAAC,CAE9C;IAED,sEAAsE;IACtE,SAAS,IAAI,SAAS,OAAO,EAAE,CAE9B;CA4CF"}