camusdb 0.6.0 → 0.7.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 (87) hide show
  1. package/README.md +193 -0
  2. package/dist/client.d.ts +42 -37
  3. package/dist/client.d.ts.map +1 -1
  4. package/dist/client.js +117 -166
  5. package/dist/client.js.map +1 -1
  6. package/dist/config.d.ts +22 -0
  7. package/dist/config.d.ts.map +1 -1
  8. package/dist/config.js +19 -0
  9. package/dist/config.js.map +1 -1
  10. package/dist/endpoint-pool.d.ts +8 -0
  11. package/dist/endpoint-pool.d.ts.map +1 -1
  12. package/dist/endpoint-pool.js +25 -0
  13. package/dist/endpoint-pool.js.map +1 -1
  14. package/dist/index.d.ts +6 -1
  15. package/dist/index.d.ts.map +1 -1
  16. package/dist/index.js +4 -0
  17. package/dist/index.js.map +1 -1
  18. package/dist/node-stats.d.ts +113 -0
  19. package/dist/node-stats.d.ts.map +1 -0
  20. package/dist/node-stats.js +90 -0
  21. package/dist/node-stats.js.map +1 -0
  22. package/dist/options.d.ts +10 -0
  23. package/dist/options.d.ts.map +1 -1
  24. package/dist/options.js +1 -0
  25. package/dist/options.js.map +1 -1
  26. package/dist/pipeline.d.ts +126 -0
  27. package/dist/pipeline.d.ts.map +1 -0
  28. package/dist/pipeline.js +363 -0
  29. package/dist/pipeline.js.map +1 -0
  30. package/dist/prepared/auto-prepare.d.ts +51 -0
  31. package/dist/prepared/auto-prepare.d.ts.map +1 -0
  32. package/dist/prepared/auto-prepare.js +150 -0
  33. package/dist/prepared/auto-prepare.js.map +1 -0
  34. package/dist/prepared/policy.d.ts +7 -0
  35. package/dist/prepared/policy.d.ts.map +1 -1
  36. package/dist/prepared/policy.js +16 -0
  37. package/dist/prepared/policy.js.map +1 -1
  38. package/dist/query-stream.d.ts +4 -1
  39. package/dist/query-stream.d.ts.map +1 -1
  40. package/dist/query-stream.js +13 -2
  41. package/dist/query-stream.js.map +1 -1
  42. package/dist/retry.d.ts +8 -0
  43. package/dist/retry.d.ts.map +1 -1
  44. package/dist/retry.js +12 -1
  45. package/dist/retry.js.map +1 -1
  46. package/dist/telemetry.d.ts +199 -0
  47. package/dist/telemetry.d.ts.map +1 -0
  48. package/dist/telemetry.js +422 -0
  49. package/dist/telemetry.js.map +1 -0
  50. package/dist/transaction.d.ts +60 -5
  51. package/dist/transaction.d.ts.map +1 -1
  52. package/dist/transaction.js +124 -24
  53. package/dist/transaction.js.map +1 -1
  54. package/dist/transport/authenticating-transport.d.ts +9 -1
  55. package/dist/transport/authenticating-transport.d.ts.map +1 -1
  56. package/dist/transport/authenticating-transport.js +13 -0
  57. package/dist/transport/authenticating-transport.js.map +1 -1
  58. package/dist/transport/grpc/batch-frames.d.ts +23 -5
  59. package/dist/transport/grpc/batch-frames.d.ts.map +1 -1
  60. package/dist/transport/grpc/batch-frames.js +29 -8
  61. package/dist/transport/grpc/batch-frames.js.map +1 -1
  62. package/dist/transport/grpc/batcher.d.ts +69 -5
  63. package/dist/transport/grpc/batcher.d.ts.map +1 -1
  64. package/dist/transport/grpc/batcher.js +217 -10
  65. package/dist/transport/grpc/batcher.js.map +1 -1
  66. package/dist/transport/grpc/grpc-transport.d.ts +35 -1
  67. package/dist/transport/grpc/grpc-transport.d.ts.map +1 -1
  68. package/dist/transport/grpc/grpc-transport.js +193 -7
  69. package/dist/transport/grpc/grpc-transport.js.map +1 -1
  70. package/dist/transport/grpc/messages.d.ts +15 -0
  71. package/dist/transport/grpc/messages.d.ts.map +1 -1
  72. package/dist/transport/grpc/messages.js +9 -0
  73. package/dist/transport/grpc/messages.js.map +1 -1
  74. package/dist/transport/rest-transport.d.ts +9 -1
  75. package/dist/transport/rest-transport.d.ts.map +1 -1
  76. package/dist/transport/rest-transport.js +24 -0
  77. package/dist/transport/rest-transport.js.map +1 -1
  78. package/dist/transport/sequential-pipeline.d.ts +21 -0
  79. package/dist/transport/sequential-pipeline.d.ts.map +1 -0
  80. package/dist/transport/sequential-pipeline.js +119 -0
  81. package/dist/transport/sequential-pipeline.js.map +1 -0
  82. package/dist/transport/transport.d.ts +94 -0
  83. package/dist/transport/transport.d.ts.map +1 -1
  84. package/dist/transport/transport.js +10 -0
  85. package/dist/transport/transport.js.map +1 -1
  86. package/package.json +10 -4
  87. package/proto/camus_sql.proto +114 -0
@@ -0,0 +1,21 @@
1
+ /**
2
+ * This file is part of CamusDB
3
+ *
4
+ * For the full copyright and license information, please view the LICENSE.txt
5
+ * file that was distributed with this source code.
6
+ */
7
+ import type { CamusTransport, PipelineTransportResult, TransportPipelineRequest } from './transport.js';
8
+ /**
9
+ * Runs a `TransportPipelineRequest` one exchange per step over a transport's ordinary calls:
10
+ * `BEGIN`, each statement in order, then the commit.
11
+ *
12
+ * It is the fallback that the pipeline API promises when the transport cannot send the request as
13
+ * one exchange. That is REST always, and gRPC against a server that announced no pipeline contract.
14
+ * The caller gets the same outcome shape either way, and only the exchange count differs.
15
+ *
16
+ * A failed statement ends the transaction on the server, which rolls it back. So the statements
17
+ * after it are not sent. They are reported with that same failure, which is in substance what the
18
+ * server would answer them with. The commit is then not tried, and it reports the failure too.
19
+ */
20
+ export declare function runSequentialPipeline(transport: CamusTransport, request: TransportPipelineRequest): Promise<PipelineTransportResult>;
21
+ //# sourceMappingURL=sequential-pipeline.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"sequential-pipeline.d.ts","sourceRoot":"","sources":["../../src/transport/sequential-pipeline.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,KAAK,EACV,cAAc,EAEd,uBAAuB,EAEvB,wBAAwB,EAEzB,MAAM,gBAAgB,CAAC;AAExB;;;;;;;;;;;GAWG;AACH,wBAAsB,qBAAqB,CACzC,SAAS,EAAE,cAAc,EACzB,OAAO,EAAE,wBAAwB,GAChC,OAAO,CAAC,uBAAuB,CAAC,CAkHlC"}
@@ -0,0 +1,119 @@
1
+ /**
2
+ * This file is part of CamusDB
3
+ *
4
+ * For the full copyright and license information, please view the LICENSE.txt
5
+ * file that was distributed with this source code.
6
+ */
7
+ import { CamusError } from '../errors.js';
8
+ import { CamusErrorCode } from '../error-codes.js';
9
+ /**
10
+ * Runs a `TransportPipelineRequest` one exchange per step over a transport's ordinary calls:
11
+ * `BEGIN`, each statement in order, then the commit.
12
+ *
13
+ * It is the fallback that the pipeline API promises when the transport cannot send the request as
14
+ * one exchange. That is REST always, and gRPC against a server that announced no pipeline contract.
15
+ * The caller gets the same outcome shape either way, and only the exchange count differs.
16
+ *
17
+ * A failed statement ends the transaction on the server, which rolls it back. So the statements
18
+ * after it are not sent. They are reported with that same failure, which is in substance what the
19
+ * server would answer them with. The commit is then not tried, and it reports the failure too.
20
+ */
21
+ export async function runSequentialPipeline(transport, request) {
22
+ let exchanges = 0;
23
+ let started;
24
+ let txnIdPT = request.txnIdPT;
25
+ let txnIdCounter = request.txnIdCounter;
26
+ let streamSlot = request.streamSlot;
27
+ if (request.start !== undefined) {
28
+ try {
29
+ started = await transport.startTransaction(request.endpoint, request.database, request.start, request.timeoutSeconds, request.signal);
30
+ exchanges++;
31
+ }
32
+ catch (error) {
33
+ // A rejected credential is thrown and not reported, so the authenticating wrapper can renew
34
+ // it and replay. Nothing ran, so the replay is safe.
35
+ if (isCancelled(request) || isAuthenticationFailure(error))
36
+ throw error;
37
+ const failure = toError(error);
38
+ return {
39
+ startFailure: failure,
40
+ statements: request.statements.map(() => ({ failure })),
41
+ committed: false,
42
+ commitFailure: request.commit ? failure : undefined,
43
+ exchanges,
44
+ };
45
+ }
46
+ txnIdPT = started.txnIdPT;
47
+ txnIdCounter = started.txnIdCounter;
48
+ streamSlot = started.streamSlot;
49
+ }
50
+ const outcomes = [];
51
+ let first;
52
+ for (const statement of request.statements) {
53
+ if (first !== undefined) {
54
+ outcomes.push({ failure: first });
55
+ continue;
56
+ }
57
+ const sql = {
58
+ endpoint: request.endpoint,
59
+ database: request.database,
60
+ sql: statement.sql,
61
+ parameters: statement.parameters,
62
+ txnIdPT,
63
+ txnIdCounter,
64
+ streamSlot,
65
+ timeoutSeconds: request.timeoutSeconds,
66
+ prepared: statement.prepared,
67
+ routingAcceptVersion: statement.routingAcceptVersion,
68
+ ...(statement.discardReturningRows === true ? { discardReturningRows: true } : {}),
69
+ signal: request.signal,
70
+ };
71
+ try {
72
+ outcomes.push(statement.kind === 'query'
73
+ ? { query: await transport.executeQuery(sql) }
74
+ : { nonQuery: await transport.executeNonQuery(sql) });
75
+ }
76
+ catch (error) {
77
+ if (isCancelled(request))
78
+ throw error;
79
+ first = toError(error);
80
+ outcomes.push({ failure: first });
81
+ }
82
+ exchanges++;
83
+ }
84
+ if (!request.commit)
85
+ return { started, statements: outcomes, committed: false, exchanges };
86
+ if (first !== undefined) {
87
+ return { started, statements: outcomes, committed: false, commitFailure: first, exchanges };
88
+ }
89
+ if (txnIdPT === undefined || txnIdCounter === undefined) {
90
+ const failure = new CamusError(CamusErrorCode.Generic, 'The pipeline has no transaction to commit.');
91
+ return { started, statements: outcomes, committed: false, commitFailure: failure, exchanges };
92
+ }
93
+ try {
94
+ await transport.finalizeTransaction(true, request.endpoint, request.database, txnIdPT, txnIdCounter, streamSlot, request.timeoutSeconds, request.signal);
95
+ return { started, statements: outcomes, committed: true, exchanges: exchanges + 1 };
96
+ }
97
+ catch (error) {
98
+ if (isCancelled(request))
99
+ throw error;
100
+ return {
101
+ started,
102
+ statements: outcomes,
103
+ committed: false,
104
+ commitFailure: toError(error),
105
+ exchanges: exchanges + 1,
106
+ };
107
+ }
108
+ }
109
+ /** True when the caller ended the call. That is a failure of the whole call, so it is thrown. */
110
+ function isCancelled(request) {
111
+ return request.signal?.aborted === true;
112
+ }
113
+ function isAuthenticationFailure(error) {
114
+ return CamusError.is(error) && error.code === CamusErrorCode.AuthenticationFailed;
115
+ }
116
+ function toError(error) {
117
+ return error instanceof Error ? error : new Error(String(error));
118
+ }
119
+ //# sourceMappingURL=sequential-pipeline.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"sequential-pipeline.js","sourceRoot":"","sources":["../../src/transport/sequential-pipeline.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAUnD;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,KAAK,UAAU,qBAAqB,CACzC,SAAyB,EACzB,OAAiC;IAEjC,IAAI,SAAS,GAAG,CAAC,CAAC;IAClB,IAAI,OAA2C,CAAC;IAChD,IAAI,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;IAC9B,IAAI,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC;IACxC,IAAI,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC;IAEpC,IAAI,OAAO,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;QAChC,IAAI,CAAC;YACH,OAAO,GAAG,MAAM,SAAS,CAAC,gBAAgB,CACxC,OAAO,CAAC,QAAQ,EAChB,OAAO,CAAC,QAAQ,EAChB,OAAO,CAAC,KAAK,EACb,OAAO,CAAC,cAAc,EACtB,OAAO,CAAC,MAAM,CACf,CAAC;YAEF,SAAS,EAAE,CAAC;QACd,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,4FAA4F;YAC5F,qDAAqD;YACrD,IAAI,WAAW,CAAC,OAAO,CAAC,IAAI,uBAAuB,CAAC,KAAK,CAAC;gBAAE,MAAM,KAAK,CAAC;YAExE,MAAM,OAAO,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC;YAE/B,OAAO;gBACL,YAAY,EAAE,OAAO;gBACrB,UAAU,EAAE,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC;gBACvD,SAAS,EAAE,KAAK;gBAChB,aAAa,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS;gBACnD,SAAS;aACV,CAAC;QACJ,CAAC;QAED,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;QAC1B,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC;QACpC,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC;IAClC,CAAC;IAED,MAAM,QAAQ,GAA+B,EAAE,CAAC;IAChD,IAAI,KAAwB,CAAC;IAE7B,KAAK,MAAM,SAAS,IAAI,OAAO,CAAC,UAAU,EAAE,CAAC;QAC3C,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACxB,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC,CAAC;YAClC,SAAS;QACX,CAAC;QAED,MAAM,GAAG,GAAwB;YAC/B,QAAQ,EAAE,OAAO,CAAC,QAAQ;YAC1B,QAAQ,EAAE,OAAO,CAAC,QAAQ;YAC1B,GAAG,EAAE,SAAS,CAAC,GAAG;YAClB,UAAU,EAAE,SAAS,CAAC,UAAU;YAChC,OAAO;YACP,YAAY;YACZ,UAAU;YACV,cAAc,EAAE,OAAO,CAAC,cAAc;YACtC,QAAQ,EAAE,SAAS,CAAC,QAAQ;YAC5B,oBAAoB,EAAE,SAAS,CAAC,oBAAoB;YACpD,GAAG,CAAC,SAAS,CAAC,oBAAoB,KAAK,IAAI,CAAC,CAAC,CAAC,EAAE,oBAAoB,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAClF,MAAM,EAAE,OAAO,CAAC,MAAM;SACvB,CAAC;QAEF,IAAI,CAAC;YACH,QAAQ,CAAC,IAAI,CACX,SAAS,CAAC,IAAI,KAAK,OAAO;gBACxB,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC,YAAY,CAAC,GAAG,CAAC,EAAE;gBAC9C,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC,eAAe,CAAC,GAAG,CAAC,EAAE,CACvD,CAAC;QACJ,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,WAAW,CAAC,OAAO,CAAC;gBAAE,MAAM,KAAK,CAAC;YAEtC,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC;YACvB,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC,CAAC;QACpC,CAAC;QAED,SAAS,EAAE,CAAC;IACd,CAAC;IAED,IAAI,CAAC,OAAO,CAAC,MAAM;QAAE,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,SAAS,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC;IAE3F,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QACxB,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,SAAS,EAAE,KAAK,EAAE,aAAa,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC;IAC9F,CAAC;IAED,IAAI,OAAO,KAAK,SAAS,IAAI,YAAY,KAAK,SAAS,EAAE,CAAC;QACxD,MAAM,OAAO,GAAG,IAAI,UAAU,CAAC,cAAc,CAAC,OAAO,EAAE,4CAA4C,CAAC,CAAC;QACrG,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,SAAS,EAAE,KAAK,EAAE,aAAa,EAAE,OAAO,EAAE,SAAS,EAAE,CAAC;IAChG,CAAC;IAED,IAAI,CAAC;QACH,MAAM,SAAS,CAAC,mBAAmB,CACjC,IAAI,EACJ,OAAO,CAAC,QAAQ,EAChB,OAAO,CAAC,QAAQ,EAChB,OAAO,EACP,YAAY,EACZ,UAAU,EACV,OAAO,CAAC,cAAc,EACtB,OAAO,CAAC,MAAM,CACf,CAAC;QAEF,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,SAAS,EAAE,IAAI,EAAE,SAAS,EAAE,SAAS,GAAG,CAAC,EAAE,CAAC;IACtF,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,WAAW,CAAC,OAAO,CAAC;YAAE,MAAM,KAAK,CAAC;QAEtC,OAAO;YACL,OAAO;YACP,UAAU,EAAE,QAAQ;YACpB,SAAS,EAAE,KAAK;YAChB,aAAa,EAAE,OAAO,CAAC,KAAK,CAAC;YAC7B,SAAS,EAAE,SAAS,GAAG,CAAC;SACzB,CAAC;IACJ,CAAC;AACH,CAAC;AAED,iGAAiG;AACjG,SAAS,WAAW,CAAC,OAAiC;IACpD,OAAO,OAAO,CAAC,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;AAC1C,CAAC;AAED,SAAS,uBAAuB,CAAC,KAAc;IAC7C,OAAO,UAAU,CAAC,EAAE,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,IAAI,KAAK,cAAc,CAAC,oBAAoB,CAAC;AACpF,CAAC;AAED,SAAS,OAAO,CAAC,KAAc;IAC7B,OAAO,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;AACnE,CAAC"}
@@ -5,6 +5,7 @@
5
5
  * file that was distributed with this source code.
6
6
  */
7
7
  import type { CamusCacheMetadata } from '../cache.js';
8
+ import type { CamusNodeStats } from '../node-stats.js';
8
9
  import type { ColumnValue } from '../column-value.js';
9
10
  import type { CamusProtocol } from '../config.js';
10
11
  import type { CamusTransactionOptions } from '../options.js';
@@ -121,6 +122,87 @@ export interface NonQueryTransportResult {
121
122
  */
122
123
  readonly returning?: CamusResultSet | undefined;
123
124
  }
125
+ /** What one pipelined statement produces: a result set, or an affected-row count. */
126
+ export type PipelineStatementKind = 'query' | 'nonQuery';
127
+ /**
128
+ * One statement of a `TransportPipelineRequest`. It joins the pipeline's transaction, so it carries
129
+ * no handle of its own. Everything else is what a `TransportSqlRequest` carries for a statement
130
+ * inside a transaction.
131
+ */
132
+ export interface TransportPipelineStatement {
133
+ readonly kind: PipelineStatementKind;
134
+ readonly sql: string;
135
+ readonly parameters?: ReadonlyMap<string, ColumnValue> | undefined;
136
+ /** See `TransportSqlRequest.prepared`. */
137
+ readonly prepared: boolean;
138
+ /** See `TransportSqlRequest.discardReturningRows`. */
139
+ readonly discardReturningRows?: boolean | undefined;
140
+ /** See `TransportSqlRequest.routingAcceptVersion`. */
141
+ readonly routingAcceptVersion: number;
142
+ }
143
+ /**
144
+ * Several statements of one transaction, handed to a transport together and answered together.
145
+ *
146
+ * The steps are: the transaction's `BEGIN` first when `start` is set, then the statements in
147
+ * order, then a commit when `commit` is set. The commit happens only if every statement succeeded.
148
+ * A transport that can send the whole request as one exchange does so. That is gRPC, to a server
149
+ * that reads the pipeline contract. Any other transport runs it one exchange per step with the same
150
+ * outcome shape, so the caller never has to know.
151
+ */
152
+ export interface TransportPipelineRequest {
153
+ readonly endpoint: string;
154
+ readonly database: string;
155
+ /**
156
+ * The options of the transaction to begin as the first step. It is `undefined` when the
157
+ * transaction that `txnIdPT` and `txnIdCounter` name has already begun.
158
+ */
159
+ readonly start?: CamusTransactionOptions | undefined;
160
+ /** The transaction every statement joins, when it has already begun. See `start`. */
161
+ readonly txnIdPT?: bigint | undefined;
162
+ readonly txnIdCounter?: number | undefined;
163
+ /** See `TransportSqlRequest.streamSlot`. */
164
+ readonly streamSlot?: number | undefined;
165
+ readonly statements: readonly TransportPipelineStatement[];
166
+ /** Commit the transaction after the statements, but only if every one of them succeeded. */
167
+ readonly commit: boolean;
168
+ readonly timeoutSeconds: number;
169
+ readonly signal?: AbortSignal | undefined;
170
+ }
171
+ /** The outcome of one pipelined statement. Exactly one of the three fields is set. */
172
+ export interface PipelineStatementOutcome {
173
+ readonly query?: QueryTransportResult | undefined;
174
+ readonly nonQuery?: NonQueryTransportResult | undefined;
175
+ readonly failure?: Error | undefined;
176
+ }
177
+ /**
178
+ * What a `TransportPipelineRequest` came back with, step by step.
179
+ *
180
+ * A failed step is reported here and not thrown. The steps after it were still answered, by the
181
+ * server or by the transport for it, and the caller owns one result per statement. Only a failure
182
+ * of the whole call is thrown: a cancellation, a deadline, or a transport fault before anything was
183
+ * sent.
184
+ */
185
+ export interface PipelineTransportResult {
186
+ /** The transaction the pipeline began, when `start` was set and the `BEGIN` succeeded. */
187
+ readonly started?: StartTransactionResult | undefined;
188
+ /** Why the `BEGIN` failed. Every statement and the commit then carry the same failure. */
189
+ readonly startFailure?: Error | undefined;
190
+ readonly statements: readonly PipelineStatementOutcome[];
191
+ /** True when the pipeline asked for a commit and the transaction committed. */
192
+ readonly committed: boolean;
193
+ /**
194
+ * Why the commit did not happen: the first failed step, or the commit's own failure. It is
195
+ * `undefined` when no commit was asked for, or when the commit succeeded.
196
+ */
197
+ readonly commitFailure?: Error | undefined;
198
+ /**
199
+ * The stream messages (gRPC) or HTTP round trips this pipeline cost. It is the number that the
200
+ * pipeline exists to lower.
201
+ */
202
+ readonly exchanges: number;
203
+ }
204
+ /** The first thing that went wrong in a pipeline, in step order, or `undefined`. */
205
+ export declare function firstPipelineFailure(result: PipelineTransportResult): Error | undefined;
124
206
  /** A statement the server registered: the placeholder names it declares, in binding order. */
125
207
  export interface PreparedStatementInfo {
126
208
  readonly parameterNames: readonly string[];
@@ -168,6 +250,16 @@ export interface CamusTransport {
168
250
  * `RETURNING` list unless the request set `discardReturningRows`.
169
251
  */
170
252
  executeNonQuery(request: TransportSqlRequest): Promise<NonQueryTransportResult>;
253
+ /**
254
+ * Runs several statements of one transaction and answers them together. The `BEGIN` can come
255
+ * first and a commit can come last.
256
+ *
257
+ * A transport that can send the request as one exchange does so. Any other runs it one exchange
258
+ * per step, with `runSequentialPipeline`. A failed step is reported in the result and not thrown,
259
+ * because every step gets an outcome. Only a failure of the whole call is thrown. By design, this
260
+ * is not "exactly one round trip" like the other methods: the result reports the exchange count.
261
+ */
262
+ executePipeline(request: TransportPipelineRequest): Promise<PipelineTransportResult>;
171
263
  /**
172
264
  * Inserts one row through the server's typed row-level surface — the same operation `INSERT INTO`
173
265
  * performs, written as a table plus a column-to-value map instead of SQL text.
@@ -199,6 +291,8 @@ export interface CamusTransport {
199
291
  closePrepared(endpoint: string, database: string, sql: string, signal?: AbortSignal): Promise<void>;
200
292
  /** A liveness check. Reports true when the server answers. */
201
293
  ping(endpoint: string, timeoutSeconds: number, signal?: AbortSignal): Promise<boolean>;
294
+ /** The disk, CPU, and memory of the node at `endpoint`. */
295
+ getNodeStats(endpoint: string, timeoutSeconds: number, signal?: AbortSignal): Promise<CamusNodeStats>;
202
296
  /** Creates a database. It is a single attempt: the caller owns the transient-retry loop. */
203
297
  createDatabase(endpoint: string, database: string, ifNotExists: boolean, timeoutSeconds: number, signal?: AbortSignal): Promise<void>;
204
298
  /** Creates a copy-on-write branch database. A single attempt, like `createDatabase`. */
@@ -1 +1 @@
1
- {"version":3,"file":"transport.d.ts","sourceRoot":"","sources":["../../src/transport/transport.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"transport.d.ts","sourceRoot":"","sources":["../../src/transport/transport.ts"],"names":[],"mappings":"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"}
@@ -4,6 +4,16 @@
4
4
  * For the full copyright and license information, please view the LICENSE.txt
5
5
  * file that was distributed with this source code.
6
6
  */
7
+ /** The first thing that went wrong in a pipeline, in step order, or `undefined`. */
8
+ export function firstPipelineFailure(result) {
9
+ if (result.startFailure !== undefined)
10
+ return result.startFailure;
11
+ for (const outcome of result.statements) {
12
+ if (outcome.failure !== undefined)
13
+ return outcome.failure;
14
+ }
15
+ return result.commitFailure;
16
+ }
7
17
  /** True when a transaction handle is present on a request. */
8
18
  export function hasTransaction(request) {
9
19
  return request.txnIdPT !== undefined && request.txnIdCounter !== undefined;
@@ -1 +1 @@
1
- {"version":3,"file":"transport.js","sourceRoot":"","sources":["../../src/transport/transport.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAqSH,8DAA8D;AAC9D,MAAM,UAAU,cAAc,CAC5B,OAA8D;IAE9D,OAAO,OAAO,CAAC,OAAO,KAAK,SAAS,IAAI,OAAO,CAAC,YAAY,KAAK,SAAS,CAAC;AAC7E,CAAC"}
1
+ {"version":3,"file":"transport.js","sourceRoot":"","sources":["../../src/transport/transport.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AA0OH,oFAAoF;AACpF,MAAM,UAAU,oBAAoB,CAAC,MAA+B;IAClE,IAAI,MAAM,CAAC,YAAY,KAAK,SAAS;QAAE,OAAO,MAAM,CAAC,YAAY,CAAC;IAElE,KAAK,MAAM,OAAO,IAAI,MAAM,CAAC,UAAU,EAAE,CAAC;QACxC,IAAI,OAAO,CAAC,OAAO,KAAK,SAAS;YAAE,OAAO,OAAO,CAAC,OAAO,CAAC;IAC5D,CAAC;IAED,OAAO,MAAM,CAAC,aAAa,CAAC;AAC9B,CAAC;AA8KD,8DAA8D;AAC9D,MAAM,UAAU,cAAc,CAC5B,OAA8D;IAE9D,OAAO,OAAO,CAAC,OAAO,KAAK,SAAS,IAAI,OAAO,CAAC,YAAY,KAAK,SAAS,CAAC;AAC7E,CAAC"}
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "camusdb",
3
- "version": "0.6.0",
4
- "description": "CamusDB connector for Node.js — REST and gRPC transports, transactions, prepared statements, learned routing, and online backups.",
3
+ "version": "0.7.0",
4
+ "description": "CamusDB connector for Node.js — REST and gRPC transports, transactions, pipelines, prepared statements, learned routing, OpenTelemetry, and online backups.",
5
5
  "license": "MIT",
6
6
  "author": "CamusDB",
7
7
  "homepage": "https://github.com/camusdb/camusdb-ts",
@@ -18,7 +18,8 @@
18
18
  "sql",
19
19
  "driver",
20
20
  "connector",
21
- "grpc"
21
+ "grpc",
22
+ "opentelemetry"
22
23
  ],
23
24
  "type": "module",
24
25
  "main": "./dist/index.js",
@@ -58,7 +59,8 @@
58
59
  },
59
60
  "peerDependencies": {
60
61
  "@grpc/grpc-js": "^1.12.0",
61
- "@grpc/proto-loader": "^0.7.13"
62
+ "@grpc/proto-loader": "^0.7.13",
63
+ "@opentelemetry/api": "^1.4.0"
62
64
  },
63
65
  "peerDependenciesMeta": {
64
66
  "@grpc/grpc-js": {
@@ -66,12 +68,16 @@
66
68
  },
67
69
  "@grpc/proto-loader": {
68
70
  "optional": true
71
+ },
72
+ "@opentelemetry/api": {
73
+ "optional": true
69
74
  }
70
75
  },
71
76
  "devDependencies": {
72
77
  "@eslint/js": "^9.15.0",
73
78
  "@grpc/grpc-js": "^1.12.2",
74
79
  "@grpc/proto-loader": "^0.7.13",
80
+ "@opentelemetry/api": "^1.9.1",
75
81
  "@types/node": "^22.9.0",
76
82
  "@vitest/coverage-v8": "^4.1.11",
77
83
  "eslint": "^9.15.0",
@@ -234,6 +234,14 @@ enum BatchStatementKind {
234
234
  // support on this stream's response headers: a server built before frames runs an unknown kind
235
235
  // as a NON_QUERY, so a probe would be executed as SQL.
236
236
  BATCH_STATEMENT_KIND_FRAME = 8;
237
+ // A conditional COMMIT: commits request.txn_handle (or the transaction named by txn_start_ref)
238
+ // only when every earlier op of that transaction on this stream succeeded; otherwise it rolls the
239
+ // transaction back (a no-op when the failed statement already did) and answers with the FIRST
240
+ // failure's code and message instead of a commit_reply. It is what lets a client put the commit
241
+ // in the same frame as the statements it depends on, since a frame itself gives no atomicity.
242
+ // Contract version 2: NEVER sent to a server that announced a lower version, which would run it
243
+ // as a NON_QUERY and leave the transaction open.
244
+ BATCH_STATEMENT_KIND_COMMIT_IF_OK = 9;
237
245
  }
238
246
 
239
247
  // PREPARE terminator. The client MUST await this reply before sending any op that references the
@@ -278,6 +286,17 @@ message BatchExecuteRequest {
278
286
  // `items` is read, on every other kind only `request` is read. A message that sets `items` with a
279
287
  // kind other than FRAME, or sets `request` on a FRAME, is invalid.
280
288
  repeated BatchExecuteRequest items = 4;
289
+ // Items of a FRAME only (contract version 2): the request_id of a START item EARLIER in the same
290
+ // frame whose transaction this op belongs to. The handle does not exist when the frame is sent,
291
+ // so the op names the START instead of a txn_handle; the server resolves it once the START has
292
+ // answered and runs the op on that transaction, chained behind the START and the earlier ops that
293
+ // name it. Rules: it must be unset (0) on a message outside a frame; it must name a START that
294
+ // precedes this item in the same frame; it may not be combined with request.txn_handle; a START,
295
+ // PREPARE or CLOSE may not carry one. A violation refuses the op with CADB0400 and runs nothing.
296
+ // When the START itself fails, every op that names it is answered with the START's error and
297
+ // runs nothing. NEVER sent to a server that announced a lower version: it would ignore the field
298
+ // and run the op as an autocommit statement.
299
+ int32 txn_start_ref = 5;
281
300
  }
282
301
 
283
302
  // Response-side frame. A wrapper message because a oneof cannot hold a repeated field.
@@ -467,6 +486,99 @@ message PingReply {
467
486
  string message = 1;
468
487
  }
469
488
 
489
+ // ─── Node stats ───────────────────────────────────────────────────────────────
490
+ // The resource state of the node that receives the call (not the cluster): disk, CPU and memory.
491
+ // Every size is bytes and every number is plain. A value the node cannot read is -1, never 0, and
492
+ // has an entry in `errors`; one failed probe never fails the call. See docs/node-stats.md.
493
+ //
494
+ // Authorization: with authentication on, a superuser or a holder of the MONITOR privilege
495
+ // (GRANT MONITOR ON *.* TO <user>); anyone else gets PERMISSION_DENIED (CADB0517). With
496
+ // authentication off, anyone. The same answer is served over REST at GET /v1/admin/stats.
497
+
498
+ message NodeStatsRequest {}
499
+
500
+ message NodeIdentity {
501
+ // The node's Raft node id; empty early in boot.
502
+ string node_id = 1;
503
+ // The node's Raft endpoint (host:port); empty early in boot.
504
+ string endpoint = 2;
505
+ string version = 3;
506
+ bool cluster_mode = 4;
507
+ int64 uptime_seconds = 5;
508
+ // When the reply was built — Unix epoch milliseconds, UTC.
509
+ int64 sampled_at_unix_ms = 6;
510
+ }
511
+
512
+ message DiskVolumeStats {
513
+ // "data" for the volume that holds data_dir. "wal" for the Raft WAL directory, present only when
514
+ // that directory is on a different volume.
515
+ string role = 1;
516
+ string path = 2;
517
+ // The mount point holding `path`; empty when not known yet.
518
+ string mount_point = 3;
519
+ int64 total_bytes = 4;
520
+ // Raw free space of the volume.
521
+ int64 free_bytes = 5;
522
+ // Free space this server's user may write; what the watermark compares.
523
+ int64 available_bytes = 6;
524
+ int64 used_bytes = 7;
525
+ // The write-admission watermark (min_free_disk_bytes) for this volume. The gate watches the data
526
+ // volume only, so a "wal" entry reports 0.
527
+ int64 min_free_disk_bytes = 8;
528
+ // True while the write gate refuses writes because of this volume — the gate's own answer, from
529
+ // the same cached probe. Always false on a "wal" entry.
530
+ bool below_watermark = 9;
531
+ // Bytes of the storage engine's files on this volume (key/value store, plus the WAL when it shares
532
+ // the volume). Measured off the request path, refreshed every minute; 0 for an in-memory engine.
533
+ int64 engine_bytes = 10;
534
+ }
535
+
536
+ message CpuStats {
537
+ // Process CPU as a share of the whole node (all processor_count processors), 0-100.
538
+ double process_cpu_percent = 1;
539
+ // The window process_cpu_percent is averaged over: up to one minute of background samples.
540
+ int64 process_cpu_window_ms = 2;
541
+ // Processors as the runtime sees them, with container CPU limits applied.
542
+ int32 processor_count = 3;
543
+ // Host load averages (Linux, macOS); -1 elsewhere.
544
+ double load_average_1m = 4;
545
+ double load_average_5m = 5;
546
+ double load_average_15m = 6;
547
+ }
548
+
549
+ message MemoryStats {
550
+ int64 process_working_set_bytes = 1;
551
+ // Managed heap size as of the last garbage collection (before the first one, the bytes
552
+ // allocated so far).
553
+ int64 gc_heap_bytes = 2;
554
+ // Memory the garbage collector holds committed as of the last collection; -1 until the first
555
+ // collection completes.
556
+ int64 gc_committed_bytes = 3;
557
+ // The managed heap hard limit in force (explicit, or the runtime's default inside a memory-limited
558
+ // container). 0 means no limit is in force.
559
+ int64 gc_memory_limit_bytes = 4;
560
+ // The cgroup memory limit when one applies, else the host's physical memory.
561
+ int64 host_total_bytes = 5;
562
+ // Of host_total_bytes, how much is still available.
563
+ int64 host_available_bytes = 6;
564
+ }
565
+
566
+ // Why one field is -1. `field` is the field's path in this reply, e.g. "cpu.load_average_1m" or
567
+ // "disks[wal].engine_bytes".
568
+ message NodeStatsError {
569
+ string field = 1;
570
+ string message = 2;
571
+ }
572
+
573
+ message NodeStatsReply {
574
+ NodeIdentity node = 1;
575
+ // The data volume first; a "wal" entry follows only when the WAL is on its own volume.
576
+ repeated DiskVolumeStats disks = 2;
577
+ CpuStats cpu = 3;
578
+ MemoryStats memory = 4;
579
+ repeated NodeStatsError errors = 5;
580
+ }
581
+
470
582
  // SQL-centric service: mirrors /execute-sql-query, /execute-sql-non-query,
471
583
  // /execute-sql-ddl, and the transaction lifecycle endpoints.
472
584
  service CamusSql {
@@ -482,6 +594,8 @@ service CamusSql {
482
594
  rpc CommitTransaction (TxnHandle) returns (CommitReply);
483
595
  rpc RollbackTransaction(TxnHandle) returns (RollbackReply);
484
596
  rpc Ping (PingRequest) returns (PingReply);
597
+ // The receiving node's disk, CPU and memory. Read-only and cheap enough to poll every minute.
598
+ rpc GetNodeStats (NodeStatsRequest) returns (NodeStatsReply);
485
599
  }
486
600
 
487
601
  // ─── CamusAuth service ────────────────────────────────────────────────────────