@tinyshed/tinystore 0.2.0-rc.1 → 0.2.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/dist/metrics.js CHANGED
@@ -4,11 +4,12 @@
4
4
  // holds of them; and a program's instruments, whose totals the store keeps.
5
5
  // A series' samples travel as two columns, an int64 time and a float64 value
6
6
  // a sample, so that every value's bits come back as they were written.
7
- import { download } from './connection.js';
8
- import { InvalidError } from './errors.js';
7
+ import { download, pieceOf } from './connection.js';
8
+ import { InvalidError, OutcomeUnknownError } from './errors.js';
9
9
  import { Counter, Gauge, Histogram, labelsOf, Timer, } from './instruments.js';
10
+ import { ConnectionLostError } from './session.js';
10
11
  import { ms, unixMs } from './time.js';
11
- import { Empty, MetricsAggregateAsked, MetricsAggregates, MetricsDamages, MetricsDeleted, MetricsDescription, MetricsExposition, MetricsIngest, MetricsLatest, MetricsNameAsked, MetricsNamePage, MetricsPageAsked, MetricsPlan, MetricsQuery, MetricsRead, MetricsSeriesNamed, MetricsTextPage, methods, } from './wire/protocol.js';
12
+ import { Empty, MetricsAggregateAsked, MetricsAggregates, MetricsDamages, MetricsDeleted, MetricsDescription, MetricsExposition, MetricsIngest, MetricsLatest, MetricsNameAsked, MetricsNamePage, MetricsPageAsked, MetricsPiece, MetricsPlan, MetricsQuery, MetricsRead, MetricsSeriesNamed, MetricsTextPage, MetricsUpload, methods, } from './wire/protocol.js';
12
13
  export { Counter, exponentialBuckets, Gauge, Histogram, Timer, Timing, } from './instruments.js';
13
14
  /**
14
15
  * A store's metrics: series by name and labels, their reads and aggregates,
@@ -43,13 +44,22 @@ export class Metrics {
43
44
  for (const [label, value] of Object.entries(options.labels ?? {})) {
44
45
  labels[label] = String(value);
45
46
  }
46
- const body = MetricsExposition.encode({
47
- text: typeof text === 'string' ? new TextEncoder().encode(text) : text,
47
+ const given = {
48
48
  labels,
49
49
  at: options.at === undefined ? undefined : unixMs(options.at),
50
50
  keep: options.keep === undefined ? undefined : ms(options.keep),
51
+ };
52
+ const bytes = typeof text === 'string' ? new TextEncoder().encode(text) : text;
53
+ await this.#link.run('write', async (connection) => {
54
+ const body = oneMessage(connection, bytes, given);
55
+ if (body !== undefined) {
56
+ await connection.session.call(methods['metrics.ingestPrometheus'], body);
57
+ return;
58
+ }
59
+ const asked = MetricsUpload.encode({ size: bytes.length, ...given });
60
+ const stream = await connection.session.open(methods['metrics.uploadPrometheus'], asked, false);
61
+ await uploaded(stream, bytes, pieceOf(connection));
51
62
  });
52
- await this.#link.run('write', connection => connection.session.call(methods['metrics.ingestPrometheus'], body));
53
63
  }
54
64
  /** The samples of each series the query finds, in its range: whole, or a limit error naming its bound. */
55
65
  async read(query) {
@@ -342,6 +352,44 @@ function newSeries(given) {
342
352
  keep: given.keep === undefined ? undefined : ms(given.keep),
343
353
  };
344
354
  }
355
+ /** A text's one message, when it fits the body the connection agreed; a longer text goes in pieces. */
356
+ function oneMessage(connection, text, given) {
357
+ const most = connection.session.agreed?.maxBody ?? 0;
358
+ if (text.length > most) {
359
+ return undefined;
360
+ }
361
+ const body = MetricsExposition.encode({ text, ...given });
362
+ return body.length <= most ? body : undefined;
363
+ }
364
+ /**
365
+ * Sends a text's pieces as DATA within the stream's credit, the last ending
366
+ * them, and waits for the store to write it. A connection lost before that
367
+ * last DATA left nothing written, so the text goes again on the next one;
368
+ * lost after it, whether the text was written is unknown.
369
+ */
370
+ async function uploaded(stream, text, piece) {
371
+ let ending = false;
372
+ try {
373
+ for (let at = 0; !ending; at += piece) {
374
+ ending = at + piece >= text.length;
375
+ await stream.send(MetricsPiece.encode({ bytes: text.subarray(at, at + piece) }), ending);
376
+ }
377
+ // the RESPONSE that began it, then the answer to its last piece
378
+ await stream.next();
379
+ await stream.next();
380
+ }
381
+ catch (err) {
382
+ if (err instanceof ConnectionLostError && !ending) {
383
+ // the store let go of what came and wrote nothing, so the whole text goes again
384
+ throw new ConnectionLostError(err.message, false);
385
+ }
386
+ stream.cancel();
387
+ if (err instanceof ConnectionLostError) {
388
+ throw new OutcomeUnknownError(`the connection was lost as the text was written: ${err.message}`);
389
+ }
390
+ throw err;
391
+ }
392
+ }
345
393
  function columnsOf(given) {
346
394
  if (given.samples !== undefined) {
347
395
  if (given.times !== undefined || given.values !== undefined) {
@@ -97,6 +97,13 @@ export declare const methods: {
97
97
  readonly 'metrics.flush': 1549;
98
98
  readonly 'metrics.instruments': 1550;
99
99
  readonly 'metrics.ingestPrometheus': 1551;
100
+ /**
101
+ * Answers its RESPONSE at once; the store's memory for the whole text is
102
+ * taken before a piece is kept, and the last piece is answered once the text
103
+ * is written, every series or none. A cancel or a lost connection leaves
104
+ * nothing written and lets go of what came.
105
+ */
106
+ readonly 'metrics.uploadPrometheus': 1552;
100
107
  readonly 'records.open': 1281;
101
108
  readonly 'records.append': 1282;
102
109
  readonly 'records.list': 1283;
@@ -1583,6 +1590,23 @@ export declare const MetricsExposition: import("./codec.ts").Message<{
1583
1590
  /** how long each name of the text keeps its samples */
1584
1591
  readonly keep: readonly [4, import("./codec.ts").Codec<number, number>];
1585
1592
  }>;
1593
+ /**
1594
+ * A text past what one message holds: what metrics.Exposition carries but
1595
+ * the text, whose bytes follow as the client's DATA, a metrics.Piece each.
1596
+ */
1597
+ export declare const MetricsUpload: import("./codec.ts").Message<{
1598
+ /** the text's bytes, 32 MiB at most: pieces that come to more or fewer are refused */
1599
+ readonly size: readonly [1, import("./codec.ts").Codec<number, number>];
1600
+ readonly labels: readonly [2, import("./codec.ts").Codec<Record<string, string>, Record<string, string>>];
1601
+ readonly at: readonly [3, import("./codec.ts").Codec<number, number>];
1602
+ readonly keep: readonly [4, import("./codec.ts").Codec<number, number>];
1603
+ }>;
1604
+ /**
1605
+ * A piece of an uploaded text, cut anywhere.
1606
+ */
1607
+ export declare const MetricsPiece: import("./codec.ts").Message<{
1608
+ readonly bytes: readonly [1, import("./codec.ts").Codec<Uint8Array<ArrayBufferLike>, Uint8Array<ArrayBufferLike>>];
1609
+ }>;
1586
1610
  /**
1587
1611
  * A page of names, of a name's labels or of a label's values.
1588
1612
  */
@@ -98,6 +98,13 @@ export const methods = {
98
98
  'metrics.flush': 0x060d,
99
99
  'metrics.instruments': 0x060e,
100
100
  'metrics.ingestPrometheus': 0x060f,
101
+ /**
102
+ * Answers its RESPONSE at once; the store's memory for the whole text is
103
+ * taken before a piece is kept, and the last piece is answered once the text
104
+ * is written, every series or none. A cancel or a lost connection leaves
105
+ * nothing written and lets go of what came.
106
+ */
107
+ 'metrics.uploadPrometheus': 0x0610,
101
108
  'records.open': 0x0501,
102
109
  'records.append': 0x0502,
103
110
  'records.list': 0x0503,
@@ -6296,6 +6303,100 @@ export const MetricsExposition = message('metrics.Exposition', {
6296
6303
  return { text: $text, labels: $labels, at: $at, keep: $keep };
6297
6304
  },
6298
6305
  });
6306
+ /**
6307
+ * A text past what one message holds: what metrics.Exposition carries but
6308
+ * the text, whose bytes follow as the client's DATA, a metrics.Piece each.
6309
+ */
6310
+ export const MetricsUpload = message('metrics.Upload', {
6311
+ /** the text's bytes, 32 MiB at most: pieces that come to more or fewer are refused */
6312
+ size: [1, uint],
6313
+ labels: [2, names(str)],
6314
+ at: [3, int],
6315
+ keep: [4, uint],
6316
+ }, {
6317
+ write(w, v) {
6318
+ const head = w.openMap();
6319
+ let n = 0;
6320
+ if (v.size !== undefined) {
6321
+ w.field(1);
6322
+ w.uint(v.size);
6323
+ n++;
6324
+ }
6325
+ if (v.labels !== undefined) {
6326
+ w.field(2);
6327
+ writeNames(w, v.labels, str.write);
6328
+ n++;
6329
+ }
6330
+ if (v.at !== undefined) {
6331
+ w.field(3);
6332
+ w.int(v.at);
6333
+ n++;
6334
+ }
6335
+ if (v.keep !== undefined) {
6336
+ w.field(4);
6337
+ w.uint(v.keep);
6338
+ n++;
6339
+ }
6340
+ w.closeMap(head, n);
6341
+ },
6342
+ read(r) {
6343
+ let $size;
6344
+ let $labels;
6345
+ let $at;
6346
+ let $keep;
6347
+ for (let n = r.message(); n > 0; n--) {
6348
+ switch (r.field()) {
6349
+ case 1:
6350
+ $size = r.uint();
6351
+ break;
6352
+ case 2:
6353
+ $labels = readNames(r, str.read);
6354
+ break;
6355
+ case 3:
6356
+ $at = r.int();
6357
+ break;
6358
+ case 4:
6359
+ $keep = r.uint();
6360
+ break;
6361
+ default:
6362
+ r.skip();
6363
+ }
6364
+ }
6365
+ r.leave();
6366
+ return { size: $size, labels: $labels, at: $at, keep: $keep };
6367
+ },
6368
+ });
6369
+ /**
6370
+ * A piece of an uploaded text, cut anywhere.
6371
+ */
6372
+ export const MetricsPiece = message('metrics.Piece', {
6373
+ bytes: [1, bin],
6374
+ }, {
6375
+ write(w, v) {
6376
+ const head = w.openMap();
6377
+ let n = 0;
6378
+ if (v.bytes !== undefined) {
6379
+ w.field(1);
6380
+ w.bin(v.bytes);
6381
+ n++;
6382
+ }
6383
+ w.closeMap(head, n);
6384
+ },
6385
+ read(r) {
6386
+ let $bytes;
6387
+ for (let n = r.message(); n > 0; n--) {
6388
+ switch (r.field()) {
6389
+ case 1:
6390
+ $bytes = r.bytes();
6391
+ break;
6392
+ default:
6393
+ r.skip();
6394
+ }
6395
+ }
6396
+ r.leave();
6397
+ return { bytes: $bytes };
6398
+ },
6399
+ });
6299
6400
  /**
6300
6401
  * A page of names, of a name's labels or of a label's values.
6301
6402
  */
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@tinyshed/tinystore",
3
- "version": "0.2.0-rc.1",
3
+ "version": "0.2.0",
4
4
  "description": "TinyStore for Bun and Node: kv, jobs, blobs, SQL, records and metrics in one directory, served by a sidecar",
5
5
  "license": "Apache-2.0",
6
6
  "homepage": "https://tinyshed.org/tinystore",
@@ -31,12 +31,12 @@
31
31
  "README.md"
32
32
  ],
33
33
  "optionalDependencies": {
34
- "@tinyshed/tinystore-linux-x64": "0.2.0-rc.1",
35
- "@tinyshed/tinystore-linux-arm64": "0.2.0-rc.1",
36
- "@tinyshed/tinystore-linux-x64-musl": "0.2.0-rc.1",
37
- "@tinyshed/tinystore-linux-arm64-musl": "0.2.0-rc.1",
38
- "@tinyshed/tinystore-darwin-arm64": "0.2.0-rc.1",
39
- "@tinyshed/tinystore-darwin-x64": "0.2.0-rc.1",
40
- "@tinyshed/tinystore-win32-x64": "0.2.0-rc.1"
34
+ "@tinyshed/tinystore-linux-x64": "0.2.0",
35
+ "@tinyshed/tinystore-linux-arm64": "0.2.0",
36
+ "@tinyshed/tinystore-linux-x64-musl": "0.2.0",
37
+ "@tinyshed/tinystore-linux-arm64-musl": "0.2.0",
38
+ "@tinyshed/tinystore-darwin-arm64": "0.2.0",
39
+ "@tinyshed/tinystore-darwin-x64": "0.2.0",
40
+ "@tinyshed/tinystore-win32-x64": "0.2.0"
41
41
  }
42
42
  }
package/src/metrics.ts CHANGED
@@ -5,8 +5,8 @@
5
5
  // A series' samples travel as two columns, an int64 time and a float64 value
6
6
  // a sample, so that every value's bits come back as they were written.
7
7
 
8
- import { download, type Link } from './connection.ts'
9
- import { InvalidError } from './errors.ts'
8
+ import { type Connection, download, type Link, pieceOf } from './connection.ts'
9
+ import { InvalidError, OutcomeUnknownError } from './errors.ts'
10
10
  import {
11
11
  Counter,
12
12
  Gauge,
@@ -20,6 +20,7 @@ import {
20
20
  Timer,
21
21
  type TimerOptions,
22
22
  } from './instruments.ts'
23
+ import { ConnectionLostError, type Stream } from './session.ts'
23
24
  import { type Calendar, type Duration, type DurationText, ms, type Time, unixMs } from './time.ts'
24
25
  import {
25
26
  Empty,
@@ -34,11 +35,13 @@ import {
34
35
  MetricsNameAsked,
35
36
  MetricsNamePage,
36
37
  MetricsPageAsked,
38
+ MetricsPiece,
37
39
  MetricsPlan,
38
40
  MetricsQuery,
39
41
  MetricsRead,
40
42
  MetricsSeriesNamed,
41
43
  MetricsTextPage,
44
+ MetricsUpload,
42
45
  methods,
43
46
  } from './wire/protocol.ts'
44
47
 
@@ -323,15 +326,26 @@ export class Metrics {
323
326
  for (const [label, value] of Object.entries(options.labels ?? {})) {
324
327
  labels[label] = String(value)
325
328
  }
326
- const body = MetricsExposition.encode({
327
- text: typeof text === 'string' ? new TextEncoder().encode(text) : text,
329
+ const given: ExpositionFields = {
328
330
  labels,
329
331
  at: options.at === undefined ? undefined : unixMs(options.at),
330
332
  keep: options.keep === undefined ? undefined : ms(options.keep),
333
+ }
334
+ const bytes = typeof text === 'string' ? new TextEncoder().encode(text) : text
335
+ await this.#link.run('write', async connection => {
336
+ const body = oneMessage(connection, bytes, given)
337
+ if (body !== undefined) {
338
+ await connection.session.call(methods['metrics.ingestPrometheus'], body)
339
+ return
340
+ }
341
+ const asked = MetricsUpload.encode({ size: bytes.length, ...given })
342
+ const stream = await connection.session.open(
343
+ methods['metrics.uploadPrometheus'],
344
+ asked,
345
+ false,
346
+ )
347
+ await uploaded(stream, bytes, pieceOf(connection))
331
348
  })
332
- await this.#link.run('write', connection =>
333
- connection.session.call(methods['metrics.ingestPrometheus'], body),
334
- )
335
349
  }
336
350
 
337
351
  /** The samples of each series the query finds, in its range: whole, or a limit error naming its bound. */
@@ -690,6 +704,58 @@ function newSeries(
690
704
  }
691
705
  }
692
706
 
707
+ /** What a text's ingest gives every series of it, one message or an upload. */
708
+ interface ExpositionFields {
709
+ labels: Labels
710
+ at: number | undefined
711
+ keep: number | undefined
712
+ }
713
+
714
+ /** A text's one message, when it fits the body the connection agreed; a longer text goes in pieces. */
715
+ function oneMessage(
716
+ connection: Connection,
717
+ text: Uint8Array,
718
+ given: ExpositionFields,
719
+ ): Uint8Array | undefined {
720
+ const most = connection.session.agreed?.maxBody ?? 0
721
+ if (text.length > most) {
722
+ return undefined
723
+ }
724
+ const body = MetricsExposition.encode({ text, ...given })
725
+ return body.length <= most ? body : undefined
726
+ }
727
+
728
+ /**
729
+ * Sends a text's pieces as DATA within the stream's credit, the last ending
730
+ * them, and waits for the store to write it. A connection lost before that
731
+ * last DATA left nothing written, so the text goes again on the next one;
732
+ * lost after it, whether the text was written is unknown.
733
+ */
734
+ async function uploaded(stream: Stream, text: Uint8Array, piece: number): Promise<void> {
735
+ let ending = false
736
+ try {
737
+ for (let at = 0; !ending; at += piece) {
738
+ ending = at + piece >= text.length
739
+ await stream.send(MetricsPiece.encode({ bytes: text.subarray(at, at + piece) }), ending)
740
+ }
741
+ // the RESPONSE that began it, then the answer to its last piece
742
+ await stream.next()
743
+ await stream.next()
744
+ } catch (err) {
745
+ if (err instanceof ConnectionLostError && !ending) {
746
+ // the store let go of what came and wrote nothing, so the whole text goes again
747
+ throw new ConnectionLostError(err.message, false)
748
+ }
749
+ stream.cancel()
750
+ if (err instanceof ConnectionLostError) {
751
+ throw new OutcomeUnknownError(
752
+ `the connection was lost as the text was written: ${err.message}`,
753
+ )
754
+ }
755
+ throw err
756
+ }
757
+ }
758
+
693
759
  function columnsOf(given: SeriesInput): [ArrayLike<Time>, ArrayLike<number>] {
694
760
  if (given.samples !== undefined) {
695
761
  if (given.times !== undefined || given.values !== undefined) {
@@ -119,6 +119,13 @@ export const methods = {
119
119
  'metrics.flush': 0x060d,
120
120
  'metrics.instruments': 0x060e,
121
121
  'metrics.ingestPrometheus': 0x060f,
122
+ /**
123
+ * Answers its RESPONSE at once; the store's memory for the whole text is
124
+ * taken before a piece is kept, and the last piece is answered once the text
125
+ * is written, every series or none. A cancel or a lost connection leaves
126
+ * nothing written and lets go of what came.
127
+ */
128
+ 'metrics.uploadPrometheus': 0x0610,
122
129
  'records.open': 0x0501,
123
130
  'records.append': 0x0502,
124
131
  'records.list': 0x0503,
@@ -6785,6 +6792,110 @@ export const MetricsExposition = message(
6785
6792
  },
6786
6793
  )
6787
6794
 
6795
+ /**
6796
+ * A text past what one message holds: what metrics.Exposition carries but
6797
+ * the text, whose bytes follow as the client's DATA, a metrics.Piece each.
6798
+ */
6799
+ export const MetricsUpload = message(
6800
+ 'metrics.Upload',
6801
+ {
6802
+ /** the text's bytes, 32 MiB at most: pieces that come to more or fewer are refused */
6803
+ size: [1, uint],
6804
+ labels: [2, names(str)],
6805
+ at: [3, int],
6806
+ keep: [4, uint],
6807
+ },
6808
+ {
6809
+ write(w, v) {
6810
+ const head = w.openMap()
6811
+ let n = 0
6812
+ if (v.size !== undefined) {
6813
+ w.field(1)
6814
+ w.uint(v.size)
6815
+ n++
6816
+ }
6817
+ if (v.labels !== undefined) {
6818
+ w.field(2)
6819
+ writeNames(w, v.labels, str.write)
6820
+ n++
6821
+ }
6822
+ if (v.at !== undefined) {
6823
+ w.field(3)
6824
+ w.int(v.at)
6825
+ n++
6826
+ }
6827
+ if (v.keep !== undefined) {
6828
+ w.field(4)
6829
+ w.uint(v.keep)
6830
+ n++
6831
+ }
6832
+ w.closeMap(head, n)
6833
+ },
6834
+ read(r) {
6835
+ let $size: number | undefined
6836
+ let $labels: Record<string, string> | undefined
6837
+ let $at: number | undefined
6838
+ let $keep: number | undefined
6839
+ for (let n = r.message(); n > 0; n--) {
6840
+ switch (r.field()) {
6841
+ case 1:
6842
+ $size = r.uint()
6843
+ break
6844
+ case 2:
6845
+ $labels = readNames(r, str.read)
6846
+ break
6847
+ case 3:
6848
+ $at = r.int()
6849
+ break
6850
+ case 4:
6851
+ $keep = r.uint()
6852
+ break
6853
+ default:
6854
+ r.skip()
6855
+ }
6856
+ }
6857
+ r.leave()
6858
+ return { size: $size, labels: $labels, at: $at, keep: $keep }
6859
+ },
6860
+ },
6861
+ )
6862
+
6863
+ /**
6864
+ * A piece of an uploaded text, cut anywhere.
6865
+ */
6866
+ export const MetricsPiece = message(
6867
+ 'metrics.Piece',
6868
+ {
6869
+ bytes: [1, bin],
6870
+ },
6871
+ {
6872
+ write(w, v) {
6873
+ const head = w.openMap()
6874
+ let n = 0
6875
+ if (v.bytes !== undefined) {
6876
+ w.field(1)
6877
+ w.bin(v.bytes)
6878
+ n++
6879
+ }
6880
+ w.closeMap(head, n)
6881
+ },
6882
+ read(r) {
6883
+ let $bytes: Uint8Array | undefined
6884
+ for (let n = r.message(); n > 0; n--) {
6885
+ switch (r.field()) {
6886
+ case 1:
6887
+ $bytes = r.bytes()
6888
+ break
6889
+ default:
6890
+ r.skip()
6891
+ }
6892
+ }
6893
+ r.leave()
6894
+ return { bytes: $bytes }
6895
+ },
6896
+ },
6897
+ )
6898
+
6788
6899
  /**
6789
6900
  * A page of names, of a name's labels or of a label's values.
6790
6901
  */