@cloudbitmaps/roaring 0.19.1 → 0.20.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.
- package/PRIVACY.md +59 -34
- package/README.md +3 -1
- package/dist/bin/export-segments.js +91 -110
- package/dist/bin/export-segments.js.map +2 -2
- package/dist/index.d.ts +110 -73
- package/dist/index.js +89 -112
- package/dist/index.js.map +2 -2
- package/dist/open-charging-storage.d.ts +3 -2
- package/dist/testing/conformance.d.ts +15 -10
- package/package.json +2 -2
package/dist/index.d.ts
CHANGED
|
@@ -23,7 +23,7 @@
|
|
|
23
23
|
* `checkConsistency`, `exportSegments` — reuse the store's own drivers, so you never re-pass them (they need the
|
|
24
24
|
* store built with a backend). See the README and the getting-started guide.
|
|
25
25
|
*/
|
|
26
|
-
import type { BudgetOption, GenerationEntry, GenerationMetadata, LoadGuard, LoadInput, LoadOptions, LoadRefusal, LoadResult, RollbackResult, Clock, StorageChunkSource, ConsistencyReport,
|
|
26
|
+
import type { BudgetOption, GenerationEntry, GenerationMetadata, LoadGuard, LoadInput, LoadOptions, LoadRefusal, LoadResult, RollbackResult, Clock, StorageChunkSource, ConsistencyReport, DropResult, ExportManifest, ExportOptions, ExportSink, IAuditSink, IStorageDriver, IKeystore, IMetricsSink, StorageBackend, RetentionPolicy, RetireExpiredOptions, RetireExpiredResult, RetryPolicy, Rng, SetRetentionResult, PinnedAt, IdRange, SegmentRef } from '@cloudbitmaps/core';
|
|
27
27
|
import type { SegmentInfo } from '@cloudbitmaps/core';
|
|
28
28
|
import type { CombineExpr, CombineManyFeedRecord, CombineManyOperandStats, CombineManyOutputStats, CombineManyStats } from '@cloudbitmaps/core';
|
|
29
29
|
import { deserializePortable } from './roaring-codec.js';
|
|
@@ -121,9 +121,11 @@ export interface CacheOptions {
|
|
|
121
121
|
* advanced.
|
|
122
122
|
*
|
|
123
123
|
* **While the registry cannot be read, the bound stretches.** A refresh that fails with a
|
|
124
|
-
* {@link TransientError} keeps serving the generation the reader
|
|
125
|
-
*
|
|
126
|
-
*
|
|
124
|
+
* {@link TransientError} keeps serving the generation of a segment still in the reader cache, and the key its reader
|
|
125
|
+
* unwrapped (a read that needs the key, where none was unwrapped before it, unwraps it from that segment's row as
|
|
126
|
+
* resolved before the outage), and is tried again 500 ms later (or after this TTL, if shorter), so the store converges
|
|
127
|
+
* within one retry of the registry answering. A segment the reader cache has let go is not served past its resolution's TTL: once that
|
|
128
|
+
* lapses, a read of it fails with the fault, as a cold read does. A refresh that fails with anything else, an access denial or a row that will not parse, is not
|
|
127
129
|
* ridden out: the read that meets it throws that error, and the reader is dropped.
|
|
128
130
|
*
|
|
129
131
|
* `0` turns this timed refresh off, and so does wiring a bare `IStorageDriver`, which has no registry. That is
|
|
@@ -138,7 +140,13 @@ export interface CacheOptions {
|
|
|
138
140
|
/**
|
|
139
141
|
* Ceiling on how many segments' `.crbm` readers (each holding a parsed index) the store keeps open at once
|
|
140
142
|
* (default 1024) — the steady-state memory bound for a long-running server that reads across many segments.
|
|
141
|
-
* Past it the least-recently-used segment's reader is evicted; re-opening it later is one cheap tail GET.
|
|
143
|
+
* Past it the least-recently-used segment's reader is evicted; re-opening it later is one cheap tail GET. With a
|
|
144
|
+
* timed refresh ({@link CacheOptions.genTtlMs} above 0, and a backend) the store also keeps up to 8 times this many
|
|
145
|
+
* segments' resolutions (what it read of each segment's row: never an unwrapped key, though the wrapped keys are in
|
|
146
|
+
* it) for `genTtlMs`, apart from their readers. An evicted segment is then reopened with no registry read, on the
|
|
147
|
+
* generation it had resolved, when a read needs its index or a chunk the chunk cache does not hold: `iterate` and the
|
|
148
|
+
* combines always do, and a `has()` of a cached chunk, a `count()` and a `stat()` do not, where the row has a summary
|
|
149
|
+
* the store can use. A reader of a small generation, one whose whole object came with its tail read,
|
|
142
150
|
* also holds its chunk bytes, so a read of it makes no chunk request until the reader is evicted or the pointer refresh
|
|
143
151
|
* moves it on; a store with no timed refresh (`genTtlMs: 0`, or no registry) keeps none.
|
|
144
152
|
* Applies whenever the store builds its own read path — a backend or a bare `IStorageDriver`. A pre-built
|
|
@@ -152,7 +160,8 @@ export interface CacheOptions {
|
|
|
152
160
|
* of the memory bound, complementing the {@link CacheOptions.readerMax} *count* bound. A wide/dense segment's
|
|
153
161
|
* parsed index can reach about 1.3 MB, so a count-only bound could let the open readers pin over a GB and blow a small
|
|
154
162
|
* heap (e.g. a 128 MB Lambda); this evicts the least-recently-used reader once the summed index footprint
|
|
155
|
-
* would exceed the ceiling — whichever of the count/byte bounds binds first.
|
|
163
|
+
* would exceed the ceiling — whichever of the count/byte bounds binds first. A sixteenth of it (4 MiB by default)
|
|
164
|
+
* bounds the segments' resolutions a store with a timed refresh keeps besides. Lower it for memory-tight
|
|
156
165
|
* deployments that read across wide segments. Applies whenever the store builds its own read path.
|
|
157
166
|
*/
|
|
158
167
|
readonly readerMaxBytes?: number;
|
|
@@ -242,8 +251,9 @@ export interface SubjectErasureEntry {
|
|
|
242
251
|
/** The generation written without the id (present whenever one was written). */
|
|
243
252
|
readonly generation?: number;
|
|
244
253
|
/**
|
|
245
|
-
* Why the id was NOT erased from this segment, when `erased` is false. `'superseded'` —
|
|
246
|
-
*
|
|
254
|
+
* Why the id was NOT erased from this segment, when `erased` is false. `'superseded'` — another writer (a load,
|
|
255
|
+
* another erasure or a rollback) moved the pointer, or replaced an object the call meant to delete, while the call
|
|
256
|
+
* was in flight, so **this call** did not erase the id;
|
|
247
257
|
* re-run against the new generation, which erases it if it is still there and reports nothing for the segment
|
|
248
258
|
* if the racing writer already removed it. `` `error: <message>` `` — an isolated per-segment fault
|
|
249
259
|
* (per-segment faults are recorded so one segment can't discard the whole ledger); re-run after fixing the
|
|
@@ -474,8 +484,9 @@ export interface MaterializeResult {
|
|
|
474
484
|
* What the destination held when the guard judged it — `null` when it had no current generation, **or when
|
|
475
485
|
* no bound needed it**. It is taken only when a bound will use it: `allowEmpty: true` with neither
|
|
476
486
|
* `guard.minRetained` nor `guard.maxGrowth` skips it, and this is `null` even though `dest` was non-empty. When the destination's row
|
|
477
|
-
* carries a summary of its current generation the count comes from the row and the object is not read; a row
|
|
478
|
-
*
|
|
487
|
+
* carries a summary of its current generation the count comes from the row and the object is not read; a row with
|
|
488
|
+
* none (one a rollback left when it could not open the key, one a registry of your own stores without one, or one this store cannot use) costs
|
|
489
|
+
* one object-header fetch.
|
|
479
490
|
*/
|
|
480
491
|
readonly cardinalityBefore: number | null;
|
|
481
492
|
/** Non-empty chunks in the generation. */
|
|
@@ -533,10 +544,11 @@ export declare class CloudRoaring {
|
|
|
533
544
|
private lifecycleDeps;
|
|
534
545
|
/**
|
|
535
546
|
* Get a handle to a segment. Validates the name (non-empty, well-formed, within the encoded-length cap). The options
|
|
536
|
-
* are `{ namespace }` and nothing else:
|
|
537
|
-
* misspelt `namespace` would otherwise address the default namespace
|
|
538
|
-
*
|
|
539
|
-
* `undefined` is read as absent, so a
|
|
547
|
+
* are a plain object holding `{ namespace }` and nothing else: any other own key, enumerable or not, is refused with
|
|
548
|
+
* {@link ValidationError}, by name, since a misspelt `namespace` would otherwise address the default namespace, and a
|
|
549
|
+
* deadline such as `expiresAt` would be left unread. A class instance, or an object built on another, is refused too,
|
|
550
|
+
* since it can carry an option no scan of its own keys sees. A key whose value is `undefined` is read as absent, so a
|
|
551
|
+
* spread of options keeps working.
|
|
540
552
|
*/
|
|
541
553
|
segment(name: string, options?: SegmentOptions): Segment;
|
|
542
554
|
/**
|
|
@@ -551,13 +563,20 @@ export declare class CloudRoaring {
|
|
|
551
563
|
* of it. A materialisation is a load whose ids happen to come from a combine instead of from upstream, so
|
|
552
564
|
* everything `load()` learned the hard way applies unchanged: the generation is written UNPUBLISHED, the
|
|
553
565
|
* guard runs while the old generation is still authoritative, the publish is fenced as above, and a refused
|
|
554
|
-
* object is reclaimed only when a re-read finds the row unchanged (the same token
|
|
555
|
-
*
|
|
556
|
-
*
|
|
557
|
-
*
|
|
558
|
-
*
|
|
559
|
-
* the
|
|
560
|
-
*
|
|
566
|
+
* object is reclaimed only when a re-read finds the row unchanged (the same token, or one that differs only in
|
|
567
|
+
* its leases), `destroyed`, or gone, or finds key material on it when the load wrote cleartext; under any other
|
|
568
|
+
* row it is kept (hard invariant 1: deleting it after a purge-and-recreate would put a live row over a missing
|
|
569
|
+
* generation).
|
|
570
|
+
*
|
|
571
|
+
* Where the row is gone, or keyed over a cleartext write, the object is proved the load's own by its footer, and
|
|
572
|
+
* the delete passes the version that read reported, so on a storage driver that reports `conditionalDelete` an
|
|
573
|
+
* object put under the number since is kept. Where the row is unchanged or `destroyed`, the check narrows the
|
|
574
|
+
* window rather than closing it: the row read and the delete are two round trips, and the delete is by number,
|
|
575
|
+
* since the write reports no version of the object it made. The other deletes a load leads to are by number too: its
|
|
576
|
+
* collection deletes what a listing, or the row's list of kept generations, names below the pointer, and a drop's
|
|
577
|
+
* sweep and a tombstoned segment's collection delete what a listing names under a `destroyed` row. The failure the
|
|
578
|
+
* checks leave when they refuse is an orphan object, which costs storage until something collects it —
|
|
579
|
+
* deliberately the cheaper side of the trade.
|
|
561
580
|
*
|
|
562
581
|
* Written and published in one step, with no guard, an empty combine — a typo'd operand, an `exclude` that
|
|
563
582
|
* swallowed everything, an operand that had not loaded yet — would silently replace `dest` with an empty
|
|
@@ -746,10 +765,14 @@ export declare class CloudRoaring {
|
|
|
746
765
|
* can still hold it, and so can one above the pointer after a {@link CloudRoaring.rollback}, which the rollback
|
|
747
766
|
* could make current again. Each holder is deleted — below the pointer by a `keep: 0` collection, above it one
|
|
748
767
|
* by one, re-proved against the row first — and the generations above the pointer that never held the id stay
|
|
749
|
-
* as rollback targets
|
|
750
|
-
*
|
|
751
|
-
*
|
|
752
|
-
*
|
|
768
|
+
* as rollback targets, but for any object no read of the segment can open, which goes whatever the id. An entry
|
|
769
|
+
* says `erased: true` only once the call has listed the bucket and read what is left: **no generation of the
|
|
770
|
+
* segment holds the id**. The returned per-segment record is your **erasure ledger** —
|
|
771
|
+
* persist it / route it to your audit sink as the proof of deletion (when you pass `audit`, an audit event is also
|
|
772
|
+
* emitted per segment erased: `segment.rewrite` for a rewrite, `segment.collect` where only other generations held
|
|
773
|
+
* the id and nothing was rewritten). A segment where the erasure deleted only objects no read of it can open (a first
|
|
774
|
+
* load's sealed under a key no row holds) found the id in none, so the ledger does not list it; the audit sink gets
|
|
775
|
+
* `segment.collect` for it with no `fromGeneration`, which is the only record of that deletion.
|
|
753
776
|
*
|
|
754
777
|
* Uses the backend's **own** two halves, so the membership check and the rewrite provably run
|
|
755
778
|
* over the same generation. Requires the store built with a **backend** (throws
|
|
@@ -771,13 +794,21 @@ export declare class CloudRoaring {
|
|
|
771
794
|
* an error, read off the row: a moved pointer is a `'superseded'` entry, which a re-run settles, and a segment
|
|
772
795
|
* that a concurrent `dropSegment` tombstoned or a retention sweep purged is left out of the ledger. A tombstoned
|
|
773
796
|
* segment is still searched: a cleartext object left under it that holds the id is deleted, with everything under
|
|
774
|
-
* the tombstone, and the entry reads `erased: true`.
|
|
797
|
+
* the tombstone, and the entry reads `erased: true`. So is a segment whose row names no generation yet (a retention
|
|
798
|
+
* policy set before its first load): a first load's object that holds the id is deleted, once the row's `pointerId`
|
|
799
|
+
* is renewed so that the load, if still running, is refused at its publish, and the entry reads `erased: true`. An
|
|
800
|
+
* encrypted first load's object there cannot be searched, so it is deleted whatever the id: on an encrypted store,
|
|
801
|
+
* an erasure of any id refuses an encrypted first load in flight that has written its object onto a segment made
|
|
802
|
+
* ahead of its data. Each such delete, and each of a holder above the pointer, names the object the erasure read:
|
|
803
|
+
* on a storage driver that reports `conditionalDelete`, another erasure of the id that deletes it first, followed by
|
|
804
|
+
* a load that takes the number freed and publishes, does not lose that load's generation to this erasure's delete,
|
|
805
|
+
* which is refused, and the entry says what the row says; on one that does not, it can.
|
|
775
806
|
*
|
|
776
807
|
* **Read `note` on any `erased: false` entry — the two reasons mean different things.** `'superseded'` means
|
|
777
|
-
* another writer (a load, another erasure, or a rollback) moved the pointer
|
|
778
|
-
* erase the id. Re-run: it erases the id if it is still there, and lists
|
|
779
|
-
* erasure of the same id already removed it. Do not read `'superseded'` as
|
|
780
|
-
* read it as "not done by this call, and the re-run settles it".
|
|
808
|
+
* another writer (a load, another erasure, or a rollback) moved the pointer, or replaced an object the call meant to
|
|
809
|
+
* delete, mid-call, so **this call** did not erase the id. Re-run: it erases the id if it is still there, and lists
|
|
810
|
+
* nothing for the segment if a racing erasure of the same id already removed it. Do not read `'superseded'` as
|
|
811
|
+
* "the id is still present" — read it as "not done by this call, and the re-run settles it".
|
|
781
812
|
* `` `error: …` `` is a per-segment fault (caught so one segment can't discard the whole ledger) and it can land
|
|
782
813
|
* on either side of the publish: if the rewrite had not published, the id is still there and a re-run erases
|
|
783
814
|
* it; if the publish succeeded and only the **collection** of the old generation failed, the id is already
|
|
@@ -899,8 +930,9 @@ export declare class CloudRoaring {
|
|
|
899
930
|
* and are then *above* `currentGen`, where collection never looks. They remain until loads pass them (the first
|
|
900
931
|
* load whose number one of them holds numbers above them all, and collection then keeps the newest `keep` of what is
|
|
901
932
|
* below its pointer), {@link CloudRoaring.dropSegment}
|
|
902
|
-
* deletes them, or {@link CloudRoaring.eraseSubject} does: all of those present when it rewrites, and
|
|
903
|
-
*
|
|
933
|
+
* deletes them, or {@link CloudRoaring.eraseSubject} does: all of those present when it rewrites, and, when the
|
|
934
|
+
* current generation does not hold the id, only those holding it and any no read of the segment can open, whatever
|
|
935
|
+
* the id. An operator who has just undone a bad load should not have the
|
|
904
936
|
* evidence collected out from under them, while a rollback target that still holds erased data would make the
|
|
905
937
|
* erasure undoable.
|
|
906
938
|
*
|
|
@@ -962,10 +994,12 @@ export declare class CloudRoaring {
|
|
|
962
994
|
* published, a retention change, a rollback or an erasure wrote the row, or the row was deleted.
|
|
963
995
|
*
|
|
964
996
|
* A refused load deletes the object it wrote before returning — it sits above `currentGen`, where generation
|
|
965
|
-
* collection deliberately never looks — but only while the segment's registry row is unchanged or
|
|
966
|
-
*
|
|
967
|
-
*
|
|
968
|
-
*
|
|
997
|
+
* collection deliberately never looks — but only while the segment's registry row is unchanged (or differs only
|
|
998
|
+
* in its leases), `destroyed` or gone, or has key material when the load wrote cleartext, which has no place in an
|
|
999
|
+
* encrypted segment's bucket. Under a row that is gone or keyed, a read of the object's footer must prove it the
|
|
1000
|
+
* load's own first. Once another write has otherwise changed the row, the generation number it holds may name
|
|
1001
|
+
* another incarnation's live object, so it leaves the orphan rather than risk deleting live data. No row's list
|
|
1002
|
+
* names it, so it takes no place in a window, and a listing deletes it once a later generation is current above it.
|
|
969
1003
|
*
|
|
970
1004
|
* **Collection is by name at any `keep` up to 64.** The segment's row records the generations a load keeps, so a load
|
|
971
1005
|
* that found nothing above the pointer deletes the generations its publish pushed out of the window and lists
|
|
@@ -1139,8 +1173,8 @@ export declare class CloudRoaring {
|
|
|
1139
1173
|
* Pass `purgeTombstones: false` to keep every tombstone, that row included. On a backend whose registry reports
|
|
1140
1174
|
* `conditionalDelete` (AWS S3, Azure Blob, the local filesystem and memory, by default; GCS when you set `conditionalDelete: true`)
|
|
1141
1175
|
* the purge removes the row from the bucket for good, by a delete the store applies only to the version it judged,
|
|
1142
|
-
* so a full sweep reads what is live or inside its grace rather than every name a namespace ever held; elsewhere
|
|
1143
|
-
*
|
|
1176
|
+
* so a full sweep reads what is live or inside its grace rather than every name a namespace ever held; elsewhere it
|
|
1177
|
+
* leaves a tombstone. Each retirement files a pointer in the due index
|
|
1144
1178
|
* under the day its tombstone's grace ends, so `scan: 'index'` purges as well as retires.
|
|
1145
1179
|
*
|
|
1146
1180
|
* Needs the store built with a **backend** (throws {@link UnsupportedError} otherwise),
|
|
@@ -1232,7 +1266,8 @@ export declare class CloudRoaring {
|
|
|
1232
1266
|
* A segment whose pointer names a missing object is the torn restore this reports; a cold `count()` of it still
|
|
1233
1267
|
* answers the number its row records, while a read of the object throws, so the count alone never shows it. With
|
|
1234
1268
|
* `summaries: true` it also opens each segment's current object (one tail read each) and reports a segment whose
|
|
1235
|
-
* row's summary says another id count or metadata than the object holds
|
|
1269
|
+
* row's summary names another object by its fingerprint, or says another id count or metadata than the object holds,
|
|
1270
|
+
* as `summary-mismatch`, which is what a
|
|
1236
1271
|
* restore of the registry from another point than the bucket leaves a count to answer. A sealed summary is held
|
|
1237
1272
|
* against its object when this store has the key, and counted in `summariesUnchecked` when it does not.
|
|
1238
1273
|
*
|
|
@@ -1259,13 +1294,6 @@ export declare class CloudRoaring {
|
|
|
1259
1294
|
* CLI wraps this with a filesystem sink.
|
|
1260
1295
|
*/
|
|
1261
1296
|
exportSegments(sink: ExportSink, options?: ExportOptions): Promise<ExportManifest>;
|
|
1262
|
-
/**
|
|
1263
|
-
* Planning cost estimate — pure, no instance/data needed: sizing, sales, what-if. For a real, grounded report
|
|
1264
|
-
* from live segment sizes, use `store.segment(name).costReport()`. See {@link CostReport}.
|
|
1265
|
-
* @deprecated Moves to `@cloudbitmaps/tools`, a package of its own, with a `size` on `stat()` so a grounded report
|
|
1266
|
-
* needs nothing internal. It is a planning tool, and its price list is as old as the release that ships it.
|
|
1267
|
-
*/
|
|
1268
|
-
static estimateCost(input: EstimateInput): CostReport;
|
|
1269
1297
|
}
|
|
1270
1298
|
/**
|
|
1271
1299
|
* Options common to every chunk-aligned combine (`intersect` / `union` / `andNot`), and the `*Into` verbs.
|
|
@@ -1432,13 +1460,22 @@ export interface PinAt {
|
|
|
1432
1460
|
/** The fingerprint of that generation's object, from the earlier pin's `pinnedAt.fingerprint`. */
|
|
1433
1461
|
readonly fingerprint: string;
|
|
1434
1462
|
}
|
|
1435
|
-
/**
|
|
1463
|
+
/**
|
|
1464
|
+
* What {@link Segment.stat} answers: the generation a handle reads, its id count, its metadata and the size of its
|
|
1465
|
+
* object.
|
|
1466
|
+
*/
|
|
1436
1467
|
export interface SegmentStat {
|
|
1437
1468
|
/** The generation read, or `null` when the segment has none. */
|
|
1438
1469
|
readonly generation: number | null;
|
|
1439
1470
|
readonly cardinality: number;
|
|
1440
1471
|
/** The metadata the generation was loaded with; absent when it has none. */
|
|
1441
1472
|
readonly metadata?: GenerationMetadata;
|
|
1473
|
+
/**
|
|
1474
|
+
* The generation's object in storage, in bytes: what the segment stores. From the registry row's summary, which
|
|
1475
|
+
* records the object's size with its checksum, or from the object's footer when the row has no summary to use.
|
|
1476
|
+
* `null` when the segment has no generation, or when the store's source cannot report a size.
|
|
1477
|
+
*/
|
|
1478
|
+
readonly sizeBytes: number | null;
|
|
1442
1479
|
}
|
|
1443
1480
|
/**
|
|
1444
1481
|
* A handle bound to one segment — the read verbs, plus the three `*Into` verbs that write a **new generation**
|
|
@@ -1639,8 +1676,8 @@ export declare class Segment {
|
|
|
1639
1676
|
* Cardinality of the generation this handle reads: **one registry read when cold, none when warm, and no read of the
|
|
1640
1677
|
* object**, with **zero payload reads**. The registry row records the id count of the generation it names, written
|
|
1641
1678
|
* by the write that made it current, and a count answers from that. A row with no summary it can use (one written
|
|
1642
|
-
*
|
|
1643
|
-
* `.crbm` index, summed with a tail read of the object. A segment whose pointer names a missing object (a torn
|
|
1679
|
+
* without it, as a registry of your own may, one that names another generation, a sealed one that does not open)
|
|
1680
|
+
* sends the count to the `.crbm` index, summed with a tail read of the object. A segment whose pointer names a missing object (a torn
|
|
1644
1681
|
* restore) still counts the row's number, while a read of the object throws; `checkConsistency` is what finds it.
|
|
1645
1682
|
*
|
|
1646
1683
|
* What this trusts: the row's summary, or the index's sum, and no payload is decoded to confirm it. The summary is
|
|
@@ -1655,17 +1692,30 @@ export declare class Segment {
|
|
|
1655
1692
|
*/
|
|
1656
1693
|
count(): Promise<number>;
|
|
1657
1694
|
/**
|
|
1658
|
-
* What the generation this handle reads is, from one resolution: its number, its id count
|
|
1659
|
-
*
|
|
1660
|
-
*
|
|
1661
|
-
*
|
|
1662
|
-
*
|
|
1663
|
-
*
|
|
1664
|
-
*
|
|
1665
|
-
*
|
|
1695
|
+
* What the generation this handle reads is, from one resolution: its number, its id count, the metadata it was
|
|
1696
|
+
* loaded with (absent when it has none), and `sizeBytes`, its object's bytes in storage. All four come from the
|
|
1697
|
+
* registry row when it has a summary this store can use, as `count()`'s do: the summary records the object's
|
|
1698
|
+
* fingerprint, its size with its checksum. That is **one registry read when cold, none when warm, and no read of the
|
|
1699
|
+
* object**. With no summary it can use, they come from the generation's object, opened once: its footer and index,
|
|
1700
|
+
* with no payload read, which is a tail read of the object more when cold (and a range read for an index longer than
|
|
1701
|
+
* the tail) and keeps the generation in the reader cache as a read does. On a pinned handle it answers for the
|
|
1702
|
+
* generation it pinned, from the pinned object. A segment with no generation answers
|
|
1703
|
+
* `{ generation: null, cardinality: 0, sizeBytes: null }`, and a store whose source cannot report a size answers
|
|
1704
|
+
* `sizeBytes: null`. A pointer that names a missing object (a torn restore) still answers from the row's summary, as
|
|
1705
|
+
* `count()` does, while a read of the object throws `NotFoundError`; with no summary to use, `stat()` throws it too.
|
|
1706
|
+
* `checkConsistency` is what finds such a row.
|
|
1707
|
+
*
|
|
1708
|
+
* Trust is as for `count()`: what the row's summary says is believed until the object is next opened. Every open of
|
|
1709
|
+
* the generation holds the object to the fingerprint the summary records, so another object under the number is
|
|
1710
|
+
* refused when it is opened, and holds its count against the summary's; a disagreement in count makes this process
|
|
1711
|
+
* stop using that summary, so `stat()` then answers from the object, whose index is checked for internal consistency
|
|
1712
|
+
* and whose count is the index's sum. A reader already open is not checked again until the row changes, it is
|
|
1713
|
+
* evicted or it is invalidated.
|
|
1714
|
+
*
|
|
1715
|
+
* `sizeBytes` is what `groundedReport` in `@cloudbitmaps/tools` prices storage from.
|
|
1666
1716
|
*
|
|
1667
1717
|
* ```ts
|
|
1668
|
-
* const { generation, cardinality, metadata } = await store.segment('active-30d').stat();
|
|
1718
|
+
* const { generation, cardinality, metadata, sizeBytes } = await store.segment('active-30d').stat();
|
|
1669
1719
|
* ```
|
|
1670
1720
|
*/
|
|
1671
1721
|
stat(): Promise<SegmentStat>;
|
|
@@ -1792,20 +1842,7 @@ export declare class Segment {
|
|
|
1792
1842
|
private andNotAs;
|
|
1793
1843
|
/** Materialize `this \ (excludes…)` as a **new generation of `dest`** — see {@link intersectInto}. */
|
|
1794
1844
|
andNotInto(dest: Segment, excludes: Segment[], options?: AndNotIntoOptions): Promise<MaterializeResult>;
|
|
1795
|
-
/**
|
|
1796
|
-
* Grounded cost report for this segment: storage cost from its **real** `.crbm` size (exact, no payload
|
|
1797
|
-
* reads); request cost from the supplied `workload` rates. A segment with no Storage generation reports zero
|
|
1798
|
-
* storage. The pointer refresh is priced at the store's own `cache.genTtlMs`, or at none when the store never
|
|
1799
|
-
* refreshes, unless the workload sets `genTtlMs`. See {@link CostReport} — it always includes a verdict (incl.
|
|
1800
|
-
* the lose-zone).
|
|
1801
|
-
* @deprecated Moves to `@cloudbitmaps/tools`, a package of its own, with a `size` on `stat()` so a grounded report
|
|
1802
|
-
* needs nothing internal. It is a planning tool, and its price list is as old as the release that ships it.
|
|
1803
|
-
*/
|
|
1804
|
-
costReport(options?: {
|
|
1805
|
-
pricing?: PricingProfile;
|
|
1806
|
-
workload?: Workload;
|
|
1807
|
-
}): Promise<CostReport>;
|
|
1808
1845
|
}
|
|
1809
1846
|
export { deserializePortable };
|
|
1810
|
-
export { MemoryStorage, LocalFsStorage, CrbmStorageChunkSource, destroySegment, eraseNamespace, excludingReservedRows, readRetentionPolicy, MIN_EXPIRES_AT_MS, LEASE_SKEW_MS, MAX_LEASE_MS, MAX_LEASES_PER_SEGMENT, InProcessKeystore, NodeAead, aadFor, CloudRoaringError, ValidationError, WriteConflictError, IntegrityError, NotFoundError, UnsupportedError, CapabilityError, TransientError, KeyUnavailableError, BudgetExceededError, LeaseExpiredError, LeaseLimitError, StaleOperandError, isCloudRoaringError, isWriteConflictError, isTransientError, isNotFoundError, isIntegrityError, isValidationError, isLeaseExpiredError, isLeaseLimitError, isStaleOperandError, isUnsupportedError, isCapabilityError, isBudgetExceededError, isKeyUnavailableError, CrbmReader, BufferReader, CountingMetricsSink, RecordingAuditSink, DEFAULT_RETRY_POLICY,
|
|
1811
|
-
export type { Aead, AeadSealed, AuditEvent, BlobReader, BlobSink, Budget, BudgetOption, ChunkRef, Clock, CodecBitmap, CodecInterface, ConsistencyErrorEntry, ConsistencyIssue, ConsistencyReport,
|
|
1847
|
+
export { MemoryStorage, LocalFsStorage, CrbmStorageChunkSource, destroySegment, eraseNamespace, excludingReservedRows, readRetentionPolicy, MIN_EXPIRES_AT_MS, LEASE_SKEW_MS, MAX_LEASE_MS, MAX_LEASES_PER_SEGMENT, InProcessKeystore, NodeAead, aadFor, CloudRoaringError, ValidationError, WriteConflictError, IntegrityError, NotFoundError, UnsupportedError, CapabilityError, TransientError, KeyUnavailableError, BudgetExceededError, LeaseExpiredError, LeaseLimitError, StaleOperandError, isCloudRoaringError, isWriteConflictError, isTransientError, isNotFoundError, isIntegrityError, isValidationError, isLeaseExpiredError, isLeaseLimitError, isStaleOperandError, isUnsupportedError, isCapabilityError, isBudgetExceededError, isKeyUnavailableError, CrbmReader, BufferReader, CountingMetricsSink, RecordingAuditSink, DEFAULT_RETRY_POLICY, } from '@cloudbitmaps/core';
|
|
1848
|
+
export type { Aead, AeadSealed, AuditEvent, BlobReader, BlobSink, Budget, BudgetOption, ChunkRef, Clock, CodecBitmap, CodecInterface, ConsistencyErrorEntry, ConsistencyIssue, ConsistencyReport, CrbmCrypto, CrbmReaderOptions, CrbmStorageChunkSourceOptions, DestroyResult, ClearRegistrySummary, DropResult, EncodedChunk, EraseDeps, ExportFailure, ExportFormat, ExportManifest, ExportOptions, ExportSink, ExportSkipped, ExportWriter, ExportedSegment, GenKey, GenerationEntry, GenerationMetadata, GovernanceMeta, IAuditSink, IKeystore, IMetricsSink, IRegistryDriver, IStorageDriver, IdRange, InProcessKeystoreOptions, LoadGuard, LoadInput, LoadOptions, LoadRefusal, LoadResult, LocalFsStorageOptions, MemoryStorageOptions, MetricEvent, MetricOpName, MetricsSnapshot, NewRegistryRecord, PinnedAt, PinnedObject, PortableBitmap, RegCaps, RegistryPatch, RegistryRecord, RegistryStatus, RegistrySummary, RegistryWriteOptions, LeaseEntry, RetentionPolicy, RetireEntry, RetireExpiredOptions, RetireExpiredResult, RetryPolicy, Rng, RollbackResult, SealedRegistrySummary, SegmentInfo, SegmentRef, SegmentSize, SetRetentionResult, StorageBackend, StorageCaps, StorageChunkSource, StorageDeleteOptions, TailRead, Token, WrappedDek, } from '@cloudbitmaps/core';
|