@wavehouse/chtypes 0.5.2 → 1.0.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +34 -0
- package/README.md +34 -38
- package/dist/abi1/buildinfo.d.ts +40 -0
- package/dist/abi1/buildinfo.d.ts.map +1 -0
- package/dist/abi1/buildinfo.js +83 -0
- package/dist/abi1/buildinfo.js.map +1 -0
- package/dist/abi1/calls.gen.d.ts +55 -0
- package/dist/abi1/calls.gen.d.ts.map +1 -0
- package/dist/abi1/calls.gen.js +110 -0
- package/dist/abi1/calls.gen.js.map +1 -0
- package/dist/abi1/decls.gen.d.ts +115 -0
- package/dist/abi1/decls.gen.d.ts.map +1 -0
- package/dist/abi1/decls.gen.js +1613 -0
- package/dist/abi1/decls.gen.js.map +1 -0
- package/dist/abi1/errmap.gen.d.ts +18 -0
- package/dist/abi1/errmap.gen.d.ts.map +1 -0
- package/dist/abi1/errmap.gen.js +66 -0
- package/dist/abi1/errmap.gen.js.map +1 -0
- package/dist/abi1/errors.d.ts +107 -0
- package/dist/abi1/errors.d.ts.map +1 -0
- package/dist/abi1/errors.js +134 -0
- package/dist/abi1/errors.js.map +1 -0
- package/dist/abi1/handles.d.ts +31 -0
- package/dist/abi1/handles.d.ts.map +1 -0
- package/dist/abi1/handles.js +76 -0
- package/dist/abi1/handles.js.map +1 -0
- package/dist/abi1/index.d.ts +17 -0
- package/dist/abi1/index.d.ts.map +1 -0
- package/dist/abi1/index.js +17 -0
- package/dist/abi1/index.js.map +1 -0
- package/dist/abi1/libc.d.ts +54 -0
- package/dist/abi1/libc.d.ts.map +1 -0
- package/dist/abi1/libc.gen.d.ts +12 -0
- package/dist/abi1/libc.gen.d.ts.map +1 -0
- package/dist/abi1/libc.gen.js +75 -0
- package/dist/abi1/libc.gen.js.map +1 -0
- package/dist/abi1/libc.js +109 -0
- package/dist/abi1/libc.js.map +1 -0
- package/dist/abi1/loader.d.ts +101 -0
- package/dist/abi1/loader.d.ts.map +1 -0
- package/dist/abi1/loader.js +274 -0
- package/dist/abi1/loader.js.map +1 -0
- package/dist/abi1/raw.d.ts +104 -0
- package/dist/abi1/raw.d.ts.map +1 -0
- package/dist/abi1/raw.js +296 -0
- package/dist/abi1/raw.js.map +1 -0
- package/dist/abi1/strictjson.d.ts +19 -0
- package/dist/abi1/strictjson.d.ts.map +1 -0
- package/dist/abi1/strictjson.js +78 -0
- package/dist/abi1/strictjson.js.map +1 -0
- package/dist/abi1/vocab.gen.d.ts +169 -0
- package/dist/abi1/vocab.gen.d.ts.map +1 -0
- package/dist/abi1/vocab.gen.js +306 -0
- package/dist/abi1/vocab.gen.js.map +1 -0
- package/dist/cli.d.ts +25 -26
- package/dist/cli.d.ts.map +1 -1
- package/dist/cli.js +206 -218
- package/dist/cli.js.map +1 -1
- package/dist/documents.d.ts +195 -0
- package/dist/documents.d.ts.map +1 -0
- package/dist/documents.js +389 -0
- package/dist/documents.js.map +1 -0
- package/dist/env.d.ts +16 -0
- package/dist/env.d.ts.map +1 -0
- package/dist/env.js +57 -0
- package/dist/env.js.map +1 -0
- package/dist/index.d.ts +19 -24
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +17 -23
- package/dist/index.js.map +1 -1
- package/dist/json.d.ts +11 -89
- package/dist/json.d.ts.map +1 -1
- package/dist/json.js +16 -180
- package/dist/json.js.map +1 -1
- package/dist/library.d.ts +53 -309
- package/dist/library.d.ts.map +1 -1
- package/dist/library.js +77 -315
- package/dist/library.js.map +1 -1
- package/dist/ocifetch/constants.gen.d.ts +84 -0
- package/dist/ocifetch/constants.gen.d.ts.map +1 -0
- package/dist/ocifetch/constants.gen.js +92 -0
- package/dist/ocifetch/constants.gen.js.map +1 -0
- package/dist/ocifetch/dsse.d.ts +114 -0
- package/dist/ocifetch/dsse.d.ts.map +1 -0
- package/dist/ocifetch/dsse.js +331 -0
- package/dist/ocifetch/dsse.js.map +1 -0
- package/dist/ocifetch/ensure.d.ts +65 -0
- package/dist/ocifetch/ensure.d.ts.map +1 -0
- package/dist/ocifetch/ensure.js +775 -0
- package/dist/ocifetch/ensure.js.map +1 -0
- package/dist/ocifetch/errors.d.ts +92 -0
- package/dist/ocifetch/errors.d.ts.map +1 -0
- package/dist/ocifetch/errors.js +101 -0
- package/dist/ocifetch/errors.js.map +1 -0
- package/dist/ocifetch/goldens.d.ts +44 -0
- package/dist/ocifetch/goldens.d.ts.map +1 -0
- package/dist/ocifetch/goldens.js +62 -0
- package/dist/ocifetch/goldens.js.map +1 -0
- package/dist/ocifetch/http.d.ts +124 -0
- package/dist/ocifetch/http.d.ts.map +1 -0
- package/dist/ocifetch/http.js +549 -0
- package/dist/ocifetch/http.js.map +1 -0
- package/dist/ocifetch/index.d.ts +17 -0
- package/dist/ocifetch/index.d.ts.map +1 -0
- package/dist/ocifetch/index.js +14 -0
- package/dist/ocifetch/index.js.map +1 -0
- package/dist/ocifetch/layout.d.ts +126 -0
- package/dist/ocifetch/layout.d.ts.map +1 -0
- package/dist/ocifetch/layout.js +375 -0
- package/dist/ocifetch/layout.js.map +1 -0
- package/dist/ocifetch/localverify.d.ts +43 -0
- package/dist/ocifetch/localverify.d.ts.map +1 -0
- package/dist/ocifetch/localverify.js +164 -0
- package/dist/ocifetch/localverify.js.map +1 -0
- package/dist/ocifetch/lock.d.ts +39 -0
- package/dist/ocifetch/lock.d.ts.map +1 -0
- package/dist/ocifetch/lock.js +140 -0
- package/dist/ocifetch/lock.js.map +1 -0
- package/dist/ocifetch/oci.d.ts +100 -0
- package/dist/ocifetch/oci.d.ts.map +1 -0
- package/dist/ocifetch/oci.js +323 -0
- package/dist/ocifetch/oci.js.map +1 -0
- package/dist/ocifetch/referrers.d.ts +55 -0
- package/dist/ocifetch/referrers.d.ts.map +1 -0
- package/dist/ocifetch/referrers.js +132 -0
- package/dist/ocifetch/referrers.js.map +1 -0
- package/dist/ocifetch/types.d.ts +167 -0
- package/dist/ocifetch/types.d.ts.map +1 -0
- package/dist/ocifetch/types.js +88 -0
- package/dist/ocifetch/types.js.map +1 -0
- package/dist/ocifetch/unpack.d.ts +55 -0
- package/dist/ocifetch/unpack.d.ts.map +1 -0
- package/dist/ocifetch/unpack.js +205 -0
- package/dist/ocifetch/unpack.js.map +1 -0
- package/dist/registry.d.ts +38 -387
- package/dist/registry.d.ts.map +1 -1
- package/dist/registry.js +95 -819
- package/dist/registry.js.map +1 -1
- package/dist/schema.d.ts +77 -588
- package/dist/schema.d.ts.map +1 -1
- package/dist/schema.js +87 -549
- package/dist/schema.js.map +1 -1
- package/dist/settings.d.ts +27 -36
- package/dist/settings.d.ts.map +1 -1
- package/dist/settings.js +75 -25
- package/dist/settings.js.map +1 -1
- package/dist/setup.d.ts +46 -0
- package/dist/setup.d.ts.map +1 -0
- package/dist/setup.js +79 -0
- package/dist/setup.js.map +1 -0
- package/dist/tar.d.ts +27 -11
- package/dist/tar.d.ts.map +1 -1
- package/dist/tar.js +54 -32
- package/dist/tar.js.map +1 -1
- package/package.json +2 -2
- package/dist/discover.d.ts +0 -142
- package/dist/discover.d.ts.map +0 -1
- package/dist/discover.js +0 -288
- package/dist/discover.js.map +0 -1
- package/dist/error-codes.d.ts +0 -80
- package/dist/error-codes.d.ts.map +0 -1
- package/dist/error-codes.js +0 -139
- package/dist/error-codes.js.map +0 -1
- package/dist/errors.d.ts +0 -284
- package/dist/errors.d.ts.map +0 -1
- package/dist/errors.js +0 -321
- package/dist/errors.js.map +0 -1
- package/dist/fetch.d.ts +0 -382
- package/dist/fetch.d.ts.map +0 -1
- package/dist/fetch.js +0 -1498
- package/dist/fetch.js.map +0 -1
- package/dist/ffi.d.ts +0 -410
- package/dist/ffi.d.ts.map +0 -1
- package/dist/ffi.js +0 -1154
- package/dist/ffi.js.map +0 -1
- package/dist/format.d.ts +0 -128
- package/dist/format.d.ts.map +0 -1
- package/dist/format.js +0 -132
- package/dist/format.js.map +0 -1
- package/dist/numeric.d.ts +0 -20
- package/dist/numeric.d.ts.map +0 -1
- package/dist/numeric.js +0 -107
- package/dist/numeric.js.map +0 -1
- package/dist/paths.d.ts +0 -55
- package/dist/paths.d.ts.map +0 -1
- package/dist/paths.js +0 -87
- package/dist/paths.js.map +0 -1
- package/dist/results.d.ts +0 -495
- package/dist/results.d.ts.map +0 -1
- package/dist/results.js +0 -406
- package/dist/results.js.map +0 -1
- package/dist/transform.d.ts +0 -73
- package/dist/transform.d.ts.map +0 -1
- package/dist/transform.js +0 -533
- package/dist/transform.js.map +0 -1
package/dist/registry.d.ts
CHANGED
|
@@ -1,395 +1,46 @@
|
|
|
1
1
|
/**
|
|
2
|
-
*
|
|
3
|
-
*
|
|
4
|
-
*
|
|
5
|
-
*
|
|
6
|
-
*
|
|
7
|
-
*
|
|
8
|
-
*
|
|
9
|
-
*
|
|
10
|
-
*
|
|
11
|
-
*
|
|
12
|
-
*
|
|
13
|
-
*
|
|
14
|
-
*
|
|
15
|
-
*
|
|
16
|
-
*
|
|
17
|
-
*
|
|
18
|
-
*
|
|
19
|
-
*
|
|
20
|
-
*
|
|
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
|
|
55
|
-
import {
|
|
56
|
-
/** The
|
|
57
|
-
export
|
|
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
|
-
|
|
72
|
-
|
|
73
|
-
|
|
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 FILE from two `Registry` instances — by one path,
|
|
177
|
-
* another spelling, a symlink or a hardlink — shares one loaded image, so
|
|
178
|
-
* `chs_init` still runs exactly once per artifact; a second timezone for an
|
|
179
|
-
* image already initialized is refused as `InitConflictError`.
|
|
180
|
-
*/
|
|
181
34
|
export declare class Registry {
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
/**
|
|
189
|
-
|
|
190
|
-
/**
|
|
191
|
-
readonly platform: string;
|
|
192
|
-
private readonly byPath;
|
|
193
|
-
private readonly loaded;
|
|
194
|
-
/** Line -> the library currently answering FOR THE LINE. Set once per line; never re-pointed while this registry runs (R3/R8). */
|
|
195
|
-
private readonly linePins;
|
|
196
|
-
/**
|
|
197
|
-
* Line -> every patch the construction-time manifest scan found for it,
|
|
198
|
-
* across the whole search path. What `versions()` answers from, and what
|
|
199
|
-
* makes "no artifact anywhere" and a bad `preload` entry decidable at
|
|
200
|
-
* construction without a single `dlopen`. Resolution itself re-scans the
|
|
201
|
-
* live filesystem on every call (a patch installed after construction, by
|
|
202
|
-
* this process or another, is used from the next call on).
|
|
203
|
-
*/
|
|
204
|
-
private readonly known;
|
|
205
|
-
private readonly timezone;
|
|
206
|
-
private readonly verifyChecksums;
|
|
207
|
-
private readonly autofetch;
|
|
208
|
-
private readonly fetchOptions;
|
|
209
|
-
private readonly explicit;
|
|
210
|
-
/** (dest, line) already `Ensure()`d successfully by THIS registry's autofetch — never re-read over the network again. */
|
|
211
|
-
private readonly ensuredLines;
|
|
212
|
-
/** (dest, exact patch) autofetch has already confirmed CHTYPES_ARTIFACT_UNPUBLISHED for — never retried within this registry's lifetime. */
|
|
213
|
-
private readonly unpublishedPatches;
|
|
214
|
-
/**
|
|
215
|
-
* Scan a registry. Reads manifests; opens nothing unless `preload` names a
|
|
216
|
-
* version.
|
|
217
|
-
*
|
|
218
|
-
* @param dir - the registry root; the head of the search path. Absent, the
|
|
219
|
-
* path is `CHTYPES_REGISTRY`, the per-user artifact cache, then the system
|
|
220
|
-
* locations (see `registrySearchPath` / `defaultRegistryDir`).
|
|
221
|
-
* @param options - timezone, checksum verification, autofetch, preload — see
|
|
222
|
-
* `RegistryOptions`.
|
|
223
|
-
* @throws {RegistryError} for what manifests can decide, and only that: a
|
|
224
|
-
* directory named explicitly (the argument or `CHTYPES_REGISTRY`) that does
|
|
225
|
-
* not exist, and no directory on the search path holding a readable
|
|
226
|
-
* manifest at either slot — both suppressed when autofetch is on. A
|
|
227
|
-
* `preload` entry no directory holds is `ArtifactMissingError`. Everything
|
|
228
|
-
* a bad artifact can be wrong about — a failed checksum, a load failure, a
|
|
229
|
-
* library whose ClickHouse version disagrees with its manifest — is
|
|
230
|
-
* reported by the call that opens it, which is `preload`'s open at
|
|
231
|
-
* construction or the first `for()` otherwise.
|
|
232
|
-
* @throws {ChtypesError} when an artifact reports a different nonzero ABI
|
|
233
|
-
* revision than this binding speaks, or `chs_init` fails (e.g. an unknown
|
|
234
|
-
* timezone — the message names it); again, from the call that opens it.
|
|
235
|
-
*/
|
|
236
|
-
constructor(dir?: string, options?: RegistryOptions);
|
|
237
|
-
/**
|
|
238
|
-
* Open one `preload` entry, before the constructor returns, without
|
|
239
|
-
* fetching. Resolution is `for()`'s (minus any fetch), and so is the
|
|
240
|
-
* failure: a version no directory holds anywhere is the same
|
|
241
|
-
* `ArtifactMissingError`, raised earlier. A patch entry that falls back
|
|
242
|
-
* warns here, at construction, exactly as `for()` would.
|
|
243
|
-
*/
|
|
244
|
-
private preloadLine;
|
|
245
|
-
/** dlopen one artifact directory, cross-check it, `chs_init` it, index it. */
|
|
246
|
-
private load;
|
|
247
|
-
/** Load an artifact directory whose manifest is already known-readable, or return null when it is not one. */
|
|
248
|
-
private loadDir;
|
|
249
|
-
/** Every patch (both slots, every search-path root) this registry can currently see for `minor` — a live scan. */
|
|
250
|
-
private scanLine;
|
|
251
|
-
/** R3: line request — the pin if this registry already has one, else the newest patch in the first root that holds any. */
|
|
252
|
-
private resolveLineSync;
|
|
253
|
-
/** R4 steps 1-2: an exact match, already open or anywhere on the search path — never a fallback. */
|
|
254
|
-
private resolveExactPatchSync;
|
|
255
|
-
/**
|
|
256
|
-
* R4 in full, synchronous shape: exact, else the newest-installed fallback
|
|
257
|
-
* within the line. R-c: the already-open check is free (no I/O) and always
|
|
258
|
-
* current; everything past it needs a directory read per search-path entry,
|
|
259
|
-
* so once a request has fallen back, the WHOLE re-check — retrying the exact
|
|
260
|
-
* match and picking the fallback alike — is throttled together, at most
|
|
261
|
-
* once per `FALLBACK_RECHECK_MS` per requested patch per process.
|
|
262
|
-
*
|
|
263
|
-
* §3: the warning fires as soon as the fallback patch is CHOSEN — its
|
|
264
|
-
* version is already known from the manifest scan, before `loadDir` ever
|
|
265
|
-
* runs — so a caller sees the warning even when the chosen directory then
|
|
266
|
-
* fails to load (a broken artifact is still a fallback that was taken).
|
|
267
|
-
*/
|
|
268
|
-
private resolvePatchSync;
|
|
269
|
-
private resolveSync;
|
|
270
|
-
/** Would `req` resolve without opening anything? Mirrors `resolveSync` with no `load()` call. */
|
|
271
|
-
private wouldResolve;
|
|
272
|
-
private warnFallback;
|
|
273
|
-
/**
|
|
274
|
-
* Every ClickHouse minor line this registry CAN ANSWER FOR, oldest first —
|
|
275
|
-
* the ones it has opened plus the ones its construction-time manifest scan
|
|
276
|
-
* discovered on the search path, at either slot.
|
|
277
|
-
*
|
|
278
|
-
* That is one meaning in all four bindings, and it is the meaning that
|
|
279
|
-
* survives lazy loading: "the lines that happen to be open" would read as an
|
|
280
|
-
* empty registry until the first `for()`. It opens nothing.
|
|
281
|
-
*/
|
|
282
|
-
versions(): string[];
|
|
283
|
-
/**
|
|
284
|
-
* The libraries this registry has OPENED, in full numeric version order —
|
|
285
|
-
* what is open right now, never what could be. Two patches of one line both
|
|
286
|
-
* appear, each in its own slot in this order. A discovered patch that no
|
|
287
|
-
* `for()` and no `preload` has opened appears in `versions()` and not here.
|
|
288
|
-
* It opens nothing.
|
|
289
|
-
*/
|
|
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. */
|
|
290
44
|
libraries(): readonly Library[];
|
|
291
|
-
/**
|
|
292
|
-
* Resolve a version to its library. A minor line ("25.8") never falls back:
|
|
293
|
-
* the newest patch of the line, from the first search-path directory that
|
|
294
|
-
* holds any patch of it. An exact patch ("25.8.28.1-lts") loads that patch
|
|
295
|
-
* when it is open or installed anywhere on the search path; otherwise the
|
|
296
|
-
* newest installed patch of the same line is loaded instead, and one
|
|
297
|
-
* warning is written per (requested, actual) pair per process — `resolve()`
|
|
298
|
-
* reports the same fallback as `exact: false` instead of only warning.
|
|
299
|
-
*
|
|
300
|
-
* **This is what opens an artifact.** Construction does not: a version is
|
|
301
|
-
* loaded on first request, `dlopen`ed once, and joins `libraries()` from
|
|
302
|
-
* then on. Never a fetch: this call is synchronous; `open()` /
|
|
303
|
-
* `openResolution()` are the ones that may fetch.
|
|
304
|
-
*
|
|
305
|
-
* Failure is the one §7 error, never a fallback to another line: answering
|
|
306
|
-
* 26.7 semantics from a 25.8 artifact is a lie, and silent wrongness is what
|
|
307
|
-
* the rigs score hardest.
|
|
308
|
-
*
|
|
309
|
-
* @param version - a minor line (`"25.8"`) or an exact patch
|
|
310
|
-
* (`"25.8.28.1-lts"`), e.g. what `parseVersionResult` discovered.
|
|
311
|
-
* @returns the loaded `Library` for that version.
|
|
312
|
-
* @throws {ArtifactMissingError} (`code` `CHTYPES_ARTIFACT_MISSING`, a
|
|
313
|
-
* `RegistryError`) when no directory on the search path holds a matching
|
|
314
|
-
* or fallback patch; the message names every directory looked in and the
|
|
315
|
-
* fetch command.
|
|
316
|
-
* @throws {ChtypesError} when `version` is not a ClickHouse version spelling at all.
|
|
317
|
-
* @throws {RegistryError} when a directory holds a version but it does not load.
|
|
318
|
-
*/
|
|
319
|
-
for(version: string): Library;
|
|
320
|
-
/**
|
|
321
|
-
* `for()`, but returns the full `Resolution` — the requested spelling, what
|
|
322
|
-
* actually loaded, and whether the two are the same patch. Never fetches;
|
|
323
|
-
* `openResolution()` is the async twin that may.
|
|
324
|
-
*
|
|
325
|
-
* @throws {ArtifactMissingError} as `for()`.
|
|
326
|
-
* @throws {ChtypesError} when `version` is not a ClickHouse version spelling at all.
|
|
327
|
-
*/
|
|
328
|
-
resolve(version: string): Resolution;
|
|
329
|
-
/**
|
|
330
|
-
* `for()`, with the lazy fetch of docs/guides/fetch.md §6 in front of it. A
|
|
331
|
-
* LINE request no directory holds is fetched through `ensure()` and loaded.
|
|
332
|
-
* A PATCH request tries `ensure()` of that exact patch first; on
|
|
333
|
-
* `CHTYPES_ARTIFACT_UNPUBLISHED` (remembered for this registry, so it costs
|
|
334
|
-
* one network round trip, not one per call) it falls back to `ensure()` of
|
|
335
|
-
* the line and loads whatever that installs, with `exact: false` and one
|
|
336
|
-
* warning. Any other fetch failure (untrusted, corrupt, pinned, source
|
|
337
|
-
* unreachable) surfaces as itself and is never remembered, so a later call
|
|
338
|
-
* retries. With `autofetch` off, this is `for()` behind a promise.
|
|
339
|
-
*
|
|
340
|
-
* @throws {ArtifactMissingError} when nothing is found and autofetch is off.
|
|
341
|
-
* @throws {FetchError} the §7 fetch verdicts (`CHTYPES_ARTIFACT_UNTRUSTED`,
|
|
342
|
-
* `…_CORRUPT`, `…_PINNED`, `…_UNPUBLISHED`, `CHTYPES_SOURCE_UNREACHABLE`).
|
|
343
|
-
* @throws {RegistryError} when the fetched artifact does not load.
|
|
344
|
-
*/
|
|
345
|
-
open(version: string): Promise<Library>;
|
|
346
|
-
/** `open()`, but returns the full `Resolution` — see `resolve()` and `open()`. */
|
|
347
|
-
openResolution(version: string): Promise<Resolution>;
|
|
348
|
-
/** `ensure(line)`, at most once per (dest, line) over this registry's lifetime — never re-read over the network again. */
|
|
349
|
-
private ensureLineOnce;
|
|
350
|
-
/**
|
|
351
|
-
* True when this registry can answer for a version without fetching or
|
|
352
|
-
* loading: already open, or held by a directory on the search path (at
|
|
353
|
-
* either slot) which `for()` would load. A patch resolves true when the
|
|
354
|
-
* patch itself, or any patch of its line, is installed or open — the same
|
|
355
|
-
* condition `for()` would resolve, fallback included. Never a fetch, and
|
|
356
|
-
* never a load.
|
|
357
|
-
*/
|
|
358
|
-
has(version: string): boolean;
|
|
359
|
-
/**
|
|
360
|
-
* Join every loaded library's background threads. `chs_init` registers
|
|
361
|
-
* `chs_shutdown` with `atexit`, so an ordinary process needs no call; a test
|
|
362
|
-
* that must not depend on `atexit` should make one.
|
|
363
|
-
*/
|
|
364
|
-
close(): void;
|
|
365
|
-
/** `using registry = new Registry(...)` closes it at scope exit. */
|
|
366
|
-
[Symbol.dispose](): void;
|
|
367
45
|
}
|
|
368
|
-
/** Numeric ordering: 25.10 is a later minor than 25.8, whatever strings say. */
|
|
369
|
-
export declare function compareMinor(a: string, b: string): number;
|
|
370
|
-
/**
|
|
371
|
-
* Where the registry is: the explicit argument, else `CHTYPES_REGISTRY`, else
|
|
372
|
-
* the first of the per-user artifact cache and the system locations that
|
|
373
|
-
* holds artifacts (docs/guides/fetch.md §1). An explicit path and the environment
|
|
374
|
-
* variable are returned as given — a wrong one must produce an error naming
|
|
375
|
-
* it, not a silent fallback — while the unnamed candidates only count if they
|
|
376
|
-
* actually hold artifacts.
|
|
377
|
-
*/
|
|
378
|
-
export declare function resolveRegistryDir(explicit?: string): string | null;
|
|
379
|
-
/**
|
|
380
|
-
* The per-user artifact cache for this host —
|
|
381
|
-
* `${XDG_CACHE_HOME:-~/.cache}/chtypes/artifacts/abi<R>/<os>-<arch>`, R this
|
|
382
|
-
* binding's `ABI_REVISION` and `<arch>` spelled the artifact way (`amd64`,
|
|
383
|
-
* `arm64`). Where `chtypes fetch` and `scripts/fetch.sh` install, and what
|
|
384
|
-
* every SDK's tests and playgrounds fall back to when `CHTYPES_REGISTRY` is
|
|
385
|
-
* unset — one directory the four SDKs at the same revision agree on. A path,
|
|
386
|
-
* not a promise: `Registry` still throws if nothing is there.
|
|
387
|
-
*/
|
|
388
|
-
export declare function defaultRegistryDir(): string;
|
|
389
|
-
/**
|
|
390
|
-
* Does this directory hold at least one artifact with a usable manifest, at
|
|
391
|
-
* either slot — the flat `<dir>/<minor>/` layout or the `<dir>/patches/<minor>/<version>/`
|
|
392
|
-
* sibling tree? A registry that holds only nested installs is not empty.
|
|
393
|
-
*/
|
|
394
|
-
export declare function looksLikeRegistry(dir: string): boolean;
|
|
395
46
|
//# sourceMappingURL=registry.d.ts.map
|
package/dist/registry.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"AAAA
|
|
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;CA6CF"}
|