@amritk/nish-aarch64-darwin 0.35.0 → 0.37.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/INSTALL.md +73 -59
- package/bin/nish +0 -0
- package/docs/AI.md +50 -4
- package/package.json +1 -1
- package/runtime/async.d.mts +2 -0
- package/runtime/async.mjs +7 -0
- package/runtime/nish.d.ts +4849 -430
- package/runtime/nish.h +25 -0
- package/runtime/page.d.ts +53 -0
- package/runtime/page.mjs +146 -0
- package/runtime/runtime-async.c +557 -0
- package/runtime/runtime-wasm.c +63 -7
- package/runtime/vite.d.ts +30 -0
- package/runtime/vite.mjs +150 -0
- package/scripts/build.sh +252 -15
- package/std/README.md +107 -82
- package/std/base64.ts +34 -5
- package/std/bytes.ts +279 -59
- package/std/cli-args.ts +296 -70
- package/std/cli-flags.ts +184 -19
- package/std/cli.ts +475 -54
- package/std/collections.ts +121 -23
- package/std/compress/checksum.ts +44 -14
- package/std/compress/deflate.ts +224 -111
- package/std/compress/gzip.ts +217 -53
- package/std/compress/zlib.ts +63 -7
- package/std/crypto/aes.ts +128 -52
- package/std/crypto/base64url.ts +29 -5
- package/std/crypto/bcrypt-batch.ts +101 -34
- package/std/crypto/bcrypt.ts +93 -27
- package/std/crypto/chacha20poly1305.ts +69 -14
- package/std/crypto/ct.ts +32 -13
- package/std/crypto/ed25519.ts +66 -16
- package/std/crypto/hkdf.ts +198 -13
- package/std/crypto/hmac.ts +242 -37
- package/std/crypto/jwt.ts +204 -72
- package/std/crypto/p256.ts +222 -72
- package/std/crypto/p384.ts +51 -23
- package/std/crypto/pki-roots.ts +32 -2
- package/std/crypto/pki.ts +99 -30
- package/std/crypto/rsa.ts +56 -22
- package/std/crypto/sha1.ts +3 -0
- package/std/crypto/sha256.ts +24 -1
- package/std/crypto/sha512.ts +99 -14
- package/std/crypto/x25519.ts +163 -24
- package/std/crypto/x509-random.ts +10 -0
- package/std/crypto/x509.ts +133 -66
- package/std/host/ring.ts +124 -0
- package/std/json-equal.ts +31 -11
- package/std/json-format.ts +112 -13
- package/std/json-number.ts +76 -26
- package/std/json-pointer.ts +23 -1
- package/std/json-tokenizer.ts +126 -51
- package/std/json-typed.ts +757 -96
- package/std/json-value.ts +438 -157
- package/std/json.ts +170 -38
- package/std/map.ts +25 -7
- package/std/math.ts +36 -4
- package/std/net/buffer-pool.ts +42 -11
- package/std/net/dns-config.ts +109 -23
- package/std/net/dns-message.ts +62 -7
- package/std/net/dns-resolver.ts +247 -53
- package/std/net/dns.ts +203 -35
- package/std/net/fetch.ts +1267 -290
- package/std/net/handler.ts +296 -80
- package/std/net/hpack.ts +290 -77
- package/std/net/http-compress.ts +152 -36
- package/std/net/http-fields.ts +85 -9
- package/std/net/http1-client-codec.ts +129 -44
- package/std/net/http1-codec.ts +279 -114
- package/std/net/http1-server.ts +409 -139
- package/std/net/http2-frame.ts +289 -51
- package/std/net/http2-tls.ts +152 -49
- package/std/net/http2.ts +314 -160
- package/std/net/http3-frame.ts +165 -27
- package/std/net/http3-server.ts +282 -131
- package/std/net/http3.ts +377 -173
- package/std/net/outbound.ts +37 -3
- package/std/net/postgres-carrier.ts +144 -8
- package/std/net/postgres.ts +898 -260
- package/std/net/prefork.ts +202 -65
- package/std/net/qpack.ts +120 -32
- package/std/net/quic-conn-ack.ts +60 -12
- package/std/net/quic-conn-cid.ts +135 -27
- package/std/net/quic-conn-params.ts +109 -22
- package/std/net/quic-datagram.ts +50 -3
- package/std/net/quic-frame.ts +333 -23
- package/std/net/quic-listener.ts +161 -75
- package/std/net/quic-packet.ts +373 -73
- package/std/net/quic-recovery.ts +287 -65
- package/std/net/quic-stream.ts +436 -146
- package/std/net/quic.ts +693 -323
- package/std/net/router.ts +87 -40
- package/std/net/tls/client.ts +167 -51
- package/std/net/tls/codec.ts +494 -68
- package/std/net/tls/record-client.ts +140 -73
- package/std/net/tls/record-server.ts +233 -105
- package/std/net/tls/record.ts +142 -36
- package/std/net/tls/schedule.ts +235 -26
- package/std/net/tls/ticket.ts +161 -40
- package/std/net/tls/verify.ts +57 -10
- package/std/net/tls-tcp.ts +308 -95
- package/std/net/tls.ts +276 -102
- package/std/net/upstream.ts +81 -45
- package/std/net/url.ts +109 -22
- package/std/net/websocket.ts +140 -26
- package/std/net/webtransport.ts +243 -106
- package/std/pair.ts +10 -2
- package/std/random.ts +42 -15
- package/std/regex.ts +422 -257
- package/std/region.ts +70 -15
- package/std/secret.ts +52 -11
- package/std/sort.ts +17 -2
- package/std/sqlite.ts +256 -35
- package/std/sync/ring.ts +229 -56
- package/std/sync/shm.ts +203 -23
- package/std/term-io.ts +154 -78
- package/std/term-pixels.ts +144 -19
- package/std/term-probe.ts +77 -35
- package/std/term-rate.ts +199 -118
- package/std/term.ts +400 -175
- package/std/testing.ts +130 -32
- package/std/text.ts +84 -17
- package/std/threads.ts +248 -56
- package/std/yaml-json.ts +111 -97
- package/std/yaml-lines.ts +47 -15
- package/std/yaml-write.ts +45 -30
- package/std/yaml.ts +764 -384
package/std/net/postgres.ts
CHANGED
|
@@ -4,12 +4,17 @@
|
|
|
4
4
|
* messages into an output buffer and reads the backend's from an input
|
|
5
5
|
* buffer, for a program that owns its socket (`nish:net`) and its loop.
|
|
6
6
|
*
|
|
7
|
+
* import { PG_FAILED, PG_NEED_MORE, PgConfig, PgConnection } from "nish/net/postgres";
|
|
8
|
+
* import { secret, wipe } from "nish:secret";
|
|
9
|
+
*
|
|
7
10
|
* const config = new PgConfig();
|
|
8
11
|
* config.user = "app";
|
|
9
12
|
* config.database = "app";
|
|
10
13
|
* const nonce = new Array<u8>(18);
|
|
11
14
|
* crypto.getRandomValues(nonce);
|
|
15
|
+
* const password = secret(passwordBytes); // a u8[] the program read from its secret store
|
|
12
16
|
* const conn = new PgConnection(config, password, nonce);
|
|
17
|
+
* wipe(password); // the connection keeps its own copy
|
|
13
18
|
* // write conn.outputBuffer()[conn.outputStart() .. conn.outputEnd()), then conn.sent(n)
|
|
14
19
|
* // read into conn.inputBuffer() at conn.inputEnd(), up to conn.inputRoom() bytes, then conn.received(n)
|
|
15
20
|
* let event: i32 = conn.next();
|
|
@@ -25,18 +30,22 @@
|
|
|
25
30
|
* event = conn.next();
|
|
26
31
|
* }
|
|
27
32
|
*
|
|
28
|
-
* **Events.**
|
|
29
|
-
*
|
|
30
|
-
*
|
|
31
|
-
*
|
|
32
|
-
*
|
|
33
|
-
*
|
|
34
|
-
* (`
|
|
35
|
-
*
|
|
36
|
-
* `
|
|
37
|
-
*
|
|
38
|
-
*
|
|
39
|
-
*
|
|
33
|
+
* **Events.**
|
|
34
|
+
*
|
|
35
|
+
* `next()` answers `PG_READY` once, when the server has authenticated the
|
|
36
|
+
* connection and is ready for queries; `PG_DESCRIBED` when a prepared statement
|
|
37
|
+
* has been described (`columns` and `columnType(c)` say what its rows hold,
|
|
38
|
+
* `columns` is 0 when it returns none); `PG_ROW` for each row, its columns as
|
|
39
|
+
* windows into the input buffer (`colStart(c)`, `colLength(c)`, -1 for NULL);
|
|
40
|
+
* `PG_COMPLETE` when an execution has finished (`tagIs("UPDATE")`,
|
|
41
|
+
* `tagRows()`); `PG_ERROR` when a statement in the current group failed
|
|
42
|
+
* (`lastError`); `PG_NOTICE` for a notice (`lastNotice`); `PG_GROUP_DONE` when
|
|
43
|
+
* a group has been answered to its end (`groupFailed`, `txStatus`); and
|
|
44
|
+
* `PG_FAILED`, final: the connection broke a rule or the server ended it,
|
|
45
|
+
* `failure` says which and `lastError` holds the server's reason when it gave
|
|
46
|
+
* one.
|
|
47
|
+
*
|
|
48
|
+
* `PG_NEED_MORE` asks for more input.
|
|
40
49
|
*
|
|
41
50
|
* **Windows and buffers.** A column's window, the tag `tagIs` and `tagRows`
|
|
42
51
|
* read are valid until the next `next()`,
|
|
@@ -53,93 +62,101 @@
|
|
|
53
62
|
* In a failed group, `PG_DESCRIBED` comes once for each `prepare` the server
|
|
54
63
|
* parsed before the error: a program that counts them knows which statements
|
|
55
64
|
* exist (named ones last past the group) and which must be prepared again.
|
|
56
|
-
* Up to `maxInFlight` groups may wait for their answers at once; `canSend()`
|
|
57
|
-
* says whether another may start, and the builder calls refuse (and write
|
|
58
|
-
* nothing) when it may not. Nothing waits for a round trip that the protocol
|
|
59
|
-
* does not need: a program prepares a statement and executes it in the same
|
|
60
|
-
* flight.
|
|
61
65
|
*
|
|
62
|
-
*
|
|
63
|
-
*
|
|
64
|
-
*
|
|
65
|
-
*
|
|
66
|
-
*
|
|
67
|
-
*
|
|
68
|
-
*
|
|
69
|
-
*
|
|
70
|
-
*
|
|
71
|
-
*
|
|
72
|
-
*
|
|
73
|
-
*
|
|
74
|
-
*
|
|
66
|
+
* Up to `maxInFlight` groups may wait for their answers at once; `canSend()`
|
|
67
|
+
* says whether another may start, and the builder calls refuse (and write
|
|
68
|
+
* nothing) when it may not. Nothing waits for a round trip that the protocol
|
|
69
|
+
* does not need: a program prepares a statement and executes it in the same
|
|
70
|
+
* flight.
|
|
71
|
+
*
|
|
72
|
+
* **Text results, no copies.** Every parameter is in text format unless it is
|
|
73
|
+
* one of the binary integer arrays below, and every result column is text
|
|
74
|
+
* unless the bind asks otherwise. A row is read where it lies in the input
|
|
75
|
+
* buffer: `next()` frames each message once, validates its layout, and records
|
|
76
|
+
* each column's start and length in two reused arrays, so a row costs no
|
|
77
|
+
* allocation. `int`, `bool`, `isNull` and `PgText.timestamp` decode a column in
|
|
78
|
+
* place; `PgArrayWalker` walks a one-dimensional `text[]` in place.
|
|
79
|
+
* `columnText(c)` is the one that allocates, a string.
|
|
80
|
+
*
|
|
81
|
+
* An array parameter is a text array literal too: `paramIntArray` writes an
|
|
82
|
+
* `int8[]` from an `i64[]` window, and `arrayStart`, `arrayElement`,
|
|
83
|
+
* `arrayInt`, `arrayNull` and `arrayEnd` build an array one element at a time
|
|
84
|
+
* into the Bind, so a list needs no string built first. A program whose element
|
|
85
|
+
* was refused for room can drop the whole bind, unsent, with `bindCancel`.
|
|
75
86
|
*
|
|
76
87
|
* **Binary integer arrays.** `paramInt4Array` and `paramInt8Array` send an
|
|
77
|
-
* `i64[]` window as an `int4[]` or `int8[]` in PostgreSQL's binary layout:
|
|
78
|
-
*
|
|
79
|
-
* benchmark (`bench/postgres/arrays.mjs`) measured at about a tenth of the
|
|
80
|
-
*
|
|
81
|
-
*
|
|
82
|
-
* `
|
|
83
|
-
*
|
|
84
|
-
*
|
|
85
|
-
*
|
|
86
|
-
*
|
|
87
|
-
*
|
|
88
|
-
*
|
|
89
|
-
*
|
|
88
|
+
* `i64[]` window as an `int4[]` or `int8[]` in PostgreSQL's binary layout: four
|
|
89
|
+
* or eight bytes an element and no digits to write or parse, which the
|
|
90
|
+
* benchmark (`bench/postgres/arrays.mjs`) measured at about a tenth of the text
|
|
91
|
+
* encoder's client CPU, and at 1,000 elements a 51% cut in the server's on
|
|
92
|
+
* `unnest` for `int8[]`, 30% for `int4[]`. `binaryArrayStart(oid)`,
|
|
93
|
+
* `binaryArrayInt` and `binaryArrayNull` build one element at a time, NULLs
|
|
94
|
+
* included, and `arrayEnd` closes it.
|
|
95
|
+
*
|
|
96
|
+
* The Bind's format codes stay a single zero word while every parameter is
|
|
97
|
+
* text; the first binary one makes `bindEnd` write a code for each, so an
|
|
98
|
+
* all-text bind costs nothing more. An `int4` element outside `int4` panics
|
|
99
|
+
* rather than wrapping. The element type must match the statement's parameter:
|
|
100
|
+
* the server answers a mismatch with `ErrorResponse` (42804) for that
|
|
101
|
+
* execution, and the connection goes on.
|
|
90
102
|
*
|
|
91
103
|
* **Binary results.** A bind opened with `bindStartBinary` instead of
|
|
92
|
-
* `bindStart` asks for every result column in binary format: an `int8` is
|
|
93
|
-
*
|
|
94
|
-
*
|
|
95
|
-
* `
|
|
96
|
-
* `
|
|
97
|
-
*
|
|
98
|
-
*
|
|
99
|
-
*
|
|
100
|
-
*
|
|
101
|
-
*
|
|
102
|
-
*
|
|
103
|
-
*
|
|
104
|
-
*
|
|
104
|
+
* `bindStart` asks for every result column in binary format: an `int8` is eight
|
|
105
|
+
* bytes, a `timestamptz` eight bytes of microseconds since 2000, a `bool` one
|
|
106
|
+
* byte, so there is nothing to parse and less on the wire. `binaryInt`,
|
|
107
|
+
* `binaryBool` and `binaryFloat` read them in place, and `PgBinary`'s
|
|
108
|
+
* `timestamp` and `iso` write a time as `PgText.timestamp` does. A `text`
|
|
109
|
+
* column is the same bytes in either format, so `columnText` and the column
|
|
110
|
+
* windows read it unchanged.
|
|
111
|
+
*
|
|
112
|
+
* The program knows which of its binds asked for which, and reads each
|
|
113
|
+
* execution's rows with the matching decoders. A `PgBatcher` with `binary` set
|
|
114
|
+
* opens each batch this way and reads its routing ordinal with `binaryInt`, so
|
|
115
|
+
* its rows are binary too. `PgBinaryArray` walks a one-dimensional `int2[]`,
|
|
116
|
+
* `int4[]` or `int8[]` column in its binary layout, and refuses any other array
|
|
117
|
+
* (a `text[]` or a multi-dimensional one among them).
|
|
105
118
|
*
|
|
106
|
-
* **Authentication.** SCRAM-SHA-256 (RFC 5802, RFC 7677) or none (`trust`).
|
|
107
|
-
*
|
|
108
|
-
*
|
|
109
|
-
*
|
|
110
|
-
*
|
|
111
|
-
*
|
|
112
|
-
*
|
|
113
|
-
*
|
|
114
|
-
*
|
|
115
|
-
*
|
|
116
|
-
*
|
|
117
|
-
*
|
|
118
|
-
*
|
|
119
|
+
* **Authentication.** SCRAM-SHA-256 (RFC 5802, RFC 7677) or none (`trust`). The
|
|
120
|
+
* password arrives as a `Secret<u8[]>`; the connection keeps a copy in a holder
|
|
121
|
+
* that is wiped as soon as the proof is computed, or when the connection fails
|
|
122
|
+
* or is disposed. The server's signature is checked in constant time before
|
|
123
|
+
* `AuthenticationOk` is believed, and an `AuthenticationOk` that skips the end
|
|
124
|
+
* of an exchange SCRAM began is refused.
|
|
125
|
+
*
|
|
126
|
+
* Cleartext and MD5 passwords, and SASL mechanisms other than SCRAM-SHA-256,
|
|
127
|
+
* are refused: with no TLS here the first sends the password as it is, and the
|
|
128
|
+
* second is a hash any eavesdropper can replay. The password's bytes are used
|
|
129
|
+
* as they are, without SASLprep (RFC 4013): an ASCII password works, and a
|
|
130
|
+
* non-ASCII one works only when it is already in the form SASLprep would give
|
|
131
|
+
* (PostgreSQL itself falls back to the raw bytes when it cannot prepare one).
|
|
132
|
+
* `docs/security/postgres.md` is the record.
|
|
119
133
|
*
|
|
120
134
|
* **Caps.** `PgConfig` bounds what a server can make the client hold: the
|
|
121
135
|
* longest message (`maxMessage`), the widest row (`maxColumns`) and the SCRAM
|
|
122
136
|
* iteration count (`minIterations`, `maxIterations`); and what a program can
|
|
123
|
-
* queue unsent (`maxOutput`), past which a builder call answers false.
|
|
124
|
-
*
|
|
125
|
-
*
|
|
126
|
-
*
|
|
127
|
-
* `
|
|
128
|
-
*
|
|
129
|
-
*
|
|
137
|
+
* queue unsent (`maxOutput`), past which a builder call answers false.
|
|
138
|
+
*
|
|
139
|
+
* A message longer than the cap, a length below 4, a layout that does not add
|
|
140
|
+
* up, a message the protocol does not allow at that point (COPY among them), an
|
|
141
|
+
* encoding other than UTF-8, and a `DateStyle` other than ISO or a `TimeZone`
|
|
142
|
+
* other than UTC (at startup or after a `SET`), each fail the connection with
|
|
143
|
+
* their own `failure` code. The constructor panics on a cap out of range, as on
|
|
144
|
+
* a missing user or a short nonce.
|
|
130
145
|
*
|
|
131
146
|
* **Pools.** `PgPool` holds up to `size` connections to one server and a FIFO
|
|
132
147
|
* queue of up to `queueSize` requests, still sans-IO: `wanted()` names a slot
|
|
133
148
|
* that needs a socket, `connect(slot, nonce)` starts its connection, and the
|
|
134
|
-
* program moves its bytes as above through `connection(slot)`.
|
|
135
|
-
*
|
|
136
|
-
*
|
|
137
|
-
*
|
|
138
|
-
*
|
|
139
|
-
*
|
|
140
|
-
*
|
|
141
|
-
* `
|
|
142
|
-
*
|
|
149
|
+
* program moves its bytes as above through `connection(slot)`.
|
|
150
|
+
*
|
|
151
|
+
* A request is a ticket from `request()`; `dispatch()` gives the oldest to the
|
|
152
|
+
* ready connection with the fewest groups in flight (or, with `PgConfig.pack`,
|
|
153
|
+
* to the first ready one with room, so a burst fills few connections in fuller
|
|
154
|
+
* writes), the program builds its group and ends it with `send()`, and
|
|
155
|
+
* `next(slot)` reads that connection's events with `ticket` naming the request.
|
|
156
|
+
* Statements given to `register` are prepared on each connection ahead of its
|
|
157
|
+
* first request. A connection that fails reports `PG_LOST` for each request it
|
|
158
|
+
* took, then `PG_FAILED`; the program closes the socket and the slot is built
|
|
159
|
+
* again on its next use.
|
|
143
160
|
*
|
|
144
161
|
* **Carrier.** `PgCarrier`, in `nish/net/postgres-carrier`, moves a pool's
|
|
145
162
|
* bytes on an `HttpHandler`'s loop, so a route handler queries without
|
|
@@ -148,23 +165,25 @@
|
|
|
148
165
|
*
|
|
149
166
|
* **Batching.** `PgBatcher` turns many reads of one row shape by key — a user
|
|
150
167
|
* by id, an article by slug — into one execution of a statement over
|
|
151
|
-
* `unnest($1) with ordinality`.
|
|
152
|
-
*
|
|
153
|
-
*
|
|
154
|
-
*
|
|
155
|
-
*
|
|
156
|
-
*
|
|
157
|
-
*
|
|
158
|
-
*
|
|
159
|
-
*
|
|
160
|
-
* `
|
|
161
|
-
*
|
|
162
|
-
*
|
|
163
|
-
*
|
|
164
|
-
*
|
|
165
|
-
*
|
|
166
|
-
*
|
|
167
|
-
* the
|
|
168
|
+
* `unnest($1) with ordinality`.
|
|
169
|
+
*
|
|
170
|
+
* `addInt` or `addText` queues a request's key and tag; `take(conn)` binds the
|
|
171
|
+
* oldest waiting, each distinct key once (past `PG_BATCH_PROBES` slots of its
|
|
172
|
+
* table probe, a key is bound again), up to `maxRequests` and `maxBytes`, and
|
|
173
|
+
* answers a run's handle; `row`, `end` and `fail` take that execution's events
|
|
174
|
+
* (a handle already answered makes them a no-op counted in `stray`, so a
|
|
175
|
+
* server's late event cannot panic), routing each row by its ordinal (checked
|
|
176
|
+
* first: a server's ordinal is refused before it routes anything), and
|
|
177
|
+
* `next(run)` answers `PG_BATCH_ROW`, then `PG_BATCH_DONE`, `PG_BATCH_MISSING`
|
|
178
|
+
* or `PG_BATCH_FAILED`, for each request.
|
|
179
|
+
*
|
|
180
|
+
* The statement orders its rows by ordinal, so a key's last events come as soon
|
|
181
|
+
* as a later key's row does; with `sorted` false it does not (no Sort node,
|
|
182
|
+
* when `orderBy` is ""), rows are answered in whatever order they come, and
|
|
183
|
+
* every last event waits for the execution's end. It reads no clock, and the
|
|
184
|
+
* batcher itself allocates only in its constructor (the connection's output
|
|
185
|
+
* buffer a take writes into may still grow, up to its `maxOutput`); when to
|
|
186
|
+
* take is the program's.
|
|
168
187
|
*
|
|
169
188
|
* **Batch timing.** `PgBatchClock` is one answer to when: given the time in
|
|
170
189
|
* microseconds, `check(now, inFlight)` says a batch is due once
|
|
@@ -334,7 +353,11 @@ export class PgConfig {
|
|
|
334
353
|
|
|
335
354
|
/** A server's ErrorResponse or NoticeResponse: the fields a program acts on. */
|
|
336
355
|
export class PgError {
|
|
337
|
-
/**
|
|
356
|
+
/**
|
|
357
|
+
* ERROR, FATAL or PANIC; WARNING, NOTICE, DEBUG, INFO or LOG for a notice.
|
|
358
|
+
* Never localised, unless the server sent no `V` field (before 9.6) and the
|
|
359
|
+
* localised `S` field stands in for it.
|
|
360
|
+
*/
|
|
338
361
|
readonly severity: string
|
|
339
362
|
/** The SQLSTATE, five characters: `23505` is a unique violation. */
|
|
340
363
|
readonly code: string
|
|
@@ -349,6 +372,19 @@ export class PgError {
|
|
|
349
372
|
/** The 1-based character position in the statement's text, or "". */
|
|
350
373
|
readonly position: string
|
|
351
374
|
|
|
375
|
+
/**
|
|
376
|
+
* Builds the record from the fields of one ErrorResponse or
|
|
377
|
+
* NoticeResponse; a program reads it from `lastError` or `lastNotice`
|
|
378
|
+
* rather than building one.
|
|
379
|
+
* @param severity The `V` field, never localised; the `S` field, which may be
|
|
380
|
+
* localised, when the server sent no `V` (servers before 9.6).
|
|
381
|
+
* @param code The SQLSTATE, the `C` field.
|
|
382
|
+
* @param message The primary message, the `M` field.
|
|
383
|
+
* @param detail The `D` field, or "" when the server sent none.
|
|
384
|
+
* @param hint The `H` field, or "".
|
|
385
|
+
* @param constraint The `n` field, or "".
|
|
386
|
+
* @param position The `P` field, a 1-based character position as text, or "".
|
|
387
|
+
*/
|
|
352
388
|
constructor(
|
|
353
389
|
severity: string,
|
|
354
390
|
code: string,
|
|
@@ -390,19 +426,25 @@ const pgAllZero = (bytes: u8[]): boolean => {
|
|
|
390
426
|
* The holder outlives the wipe, so that `wiped()` reads the very bytes.
|
|
391
427
|
*/
|
|
392
428
|
class PgPassword {
|
|
429
|
+
/** @internal Used by `PgConnection.scramContinue` and `PgPool.connect` in this module. */
|
|
393
430
|
readonly bytes: Secret<u8[]>
|
|
394
|
-
/**
|
|
431
|
+
/**
|
|
432
|
+
* Whether `wipe()` has run; the bytes are no longer a password.
|
|
433
|
+
* @internal Used by `PgConnection.dispose`, `PgConnection.scramContinue`, `PgPool.connect` and `PgPool.dispose` in this module.
|
|
434
|
+
*/
|
|
395
435
|
gone: boolean = false
|
|
396
436
|
|
|
397
437
|
constructor(password: Secret<u8[]>) {
|
|
398
438
|
this.bytes = secret(expose(password, pgCopyBytes))
|
|
399
439
|
}
|
|
400
440
|
|
|
441
|
+
/** @internal Used by `PgConnection.dispose` and `PgPool.dispose` in this module. */
|
|
401
442
|
wipe(): void {
|
|
402
443
|
wipe(this.bytes)
|
|
403
444
|
this.gone = true
|
|
404
445
|
}
|
|
405
446
|
|
|
447
|
+
/** @internal Used by `PgConnection.passwordWiped` and `PgPool.passwordWiped` in this module. */
|
|
406
448
|
wiped(): boolean {
|
|
407
449
|
return expose(this.bytes, pgAllZero)
|
|
408
450
|
}
|
|
@@ -669,7 +711,15 @@ export class PgText {
|
|
|
669
711
|
this.failed = false
|
|
670
712
|
}
|
|
671
713
|
|
|
672
|
-
/**
|
|
714
|
+
/**
|
|
715
|
+
* An `int2`, `int4` or `int8` column: an optional `-` and its digits, in
|
|
716
|
+
* place. Leading zeros are allowed; a value outside `i64` is an overflow.
|
|
717
|
+
* @param b The buffer the column lies in, usually `conn.inputBuffer()`.
|
|
718
|
+
* @param start The column's first byte, as `colStart(c)` gives it.
|
|
719
|
+
* @param length The column's length in bytes; NULL's -1 is refused.
|
|
720
|
+
* @returns The value, or 0 with `failed` set for an empty or out-of-range
|
|
721
|
+
* window, a byte that is not a digit, or an overflow.
|
|
722
|
+
*/
|
|
673
723
|
int(b: u8[], start: i32, length: i32): i64 {
|
|
674
724
|
const end: i32 = start + length
|
|
675
725
|
if (length <= 0 || start < 0 || end < start || end > toI32(b.length)) {
|
|
@@ -707,7 +757,13 @@ export class PgText {
|
|
|
707
757
|
return negative ? acc : -acc
|
|
708
758
|
}
|
|
709
759
|
|
|
710
|
-
/**
|
|
760
|
+
/**
|
|
761
|
+
* A `bool` column: `t` or `f`, in place.
|
|
762
|
+
* @param b The buffer the column lies in.
|
|
763
|
+
* @param start The column's first byte.
|
|
764
|
+
* @param length The column's length in bytes; anything but 1 is refused.
|
|
765
|
+
* @returns True for `t`, false for `f`; false with `failed` set otherwise.
|
|
766
|
+
*/
|
|
711
767
|
bool(b: u8[], start: i32, length: i32): boolean {
|
|
712
768
|
if (length === 1 && start >= 0 && start < toI32(b.length)) {
|
|
713
769
|
const c: i32 = toI32(b[start])
|
|
@@ -728,7 +784,14 @@ export class PgText {
|
|
|
728
784
|
* `timestamp` column (the same without `+00`), written to `out[at, at + 24)`
|
|
729
785
|
* as `2024-01-02T03:04:05.123Z`, the fraction cut to milliseconds. Answers
|
|
730
786
|
* 24, or -1 and `failed` for anything else: a year outside 0001–9999, BC,
|
|
731
|
-
* `infinity`, an offset other than `+00`.
|
|
787
|
+
* `infinity`, an offset other than `+00`. Nothing is allocated.
|
|
788
|
+
* @param b The buffer the column lies in.
|
|
789
|
+
* @param start The column's first byte.
|
|
790
|
+
* @param length The column's length in bytes, at least 19.
|
|
791
|
+
* @param out The buffer to write the 24 ISO 8601 bytes into; the caller owns it.
|
|
792
|
+
* @param at Where in `out` the time starts; `out` needs 24 bytes from there.
|
|
793
|
+
* @returns 24, the bytes written; -1 with `failed` set, and `out` untouched,
|
|
794
|
+
* for a column it does not read or no room in `out`.
|
|
732
795
|
*/
|
|
733
796
|
timestamp(b: u8[], start: i32, length: i32, out: u8[], at: i32): i32 {
|
|
734
797
|
if (
|
|
@@ -854,6 +917,10 @@ export class PgBinary {
|
|
|
854
917
|
* bytes, big-endian two's complement); 0 and `failed` for any other length,
|
|
855
918
|
* NULL's -1 among them. A `timestamptz` or `timestamp` reads as an `int8`:
|
|
856
919
|
* microseconds since 2000-01-01 00:00:00 UTC, which `iso` writes out.
|
|
920
|
+
* @param b The buffer the column lies in, usually `conn.inputBuffer()`.
|
|
921
|
+
* @param start The column's first byte, as `colStart(c)` gives it.
|
|
922
|
+
* @param length The column's length in bytes: 2, 4 or 8.
|
|
923
|
+
* @returns The value, sign-extended to 64 bits, or 0 with `failed` set.
|
|
857
924
|
*/
|
|
858
925
|
int(b: u8[], start: i32, length: i32): i64 {
|
|
859
926
|
if ((length !== 2 && length !== 4 && length !== 8) || !this.inside(b, start, length)) {
|
|
@@ -870,7 +937,13 @@ export class PgBinary {
|
|
|
870
937
|
return toI64(v >= 32768 ? v - 65536 : v)
|
|
871
938
|
}
|
|
872
939
|
|
|
873
|
-
/**
|
|
940
|
+
/**
|
|
941
|
+
* A `bool` column: one byte, 1 or 0.
|
|
942
|
+
* @param b The buffer the column lies in.
|
|
943
|
+
* @param start The column's first byte.
|
|
944
|
+
* @param length The column's length in bytes; anything but 1 is refused.
|
|
945
|
+
* @returns True for 1, false for 0; false with `failed` set otherwise.
|
|
946
|
+
*/
|
|
874
947
|
bool(b: u8[], start: i32, length: i32): boolean {
|
|
875
948
|
if (length === 1 && this.inside(b, start, length)) {
|
|
876
949
|
const c: i32 = toI32(b[start])
|
|
@@ -885,7 +958,15 @@ export class PgBinary {
|
|
|
885
958
|
return false
|
|
886
959
|
}
|
|
887
960
|
|
|
888
|
-
/**
|
|
961
|
+
/**
|
|
962
|
+
* A `float8` column: eight bytes, IEEE 754 big-endian. A `float4` (four
|
|
963
|
+
* bytes) is refused.
|
|
964
|
+
* @param b The buffer the column lies in.
|
|
965
|
+
* @param start The column's first byte.
|
|
966
|
+
* @param length The column's length in bytes; anything but 8 is refused.
|
|
967
|
+
* @returns The value, NaN and the infinities included; 0 with `failed` set
|
|
968
|
+
* for a column that is not eight bytes inside `b`.
|
|
969
|
+
*/
|
|
889
970
|
float(b: u8[], start: i32, length: i32): f64 {
|
|
890
971
|
if (length !== 8 || !this.inside(b, start, length)) {
|
|
891
972
|
this.failed = true
|
|
@@ -898,6 +979,12 @@ export class PgBinary {
|
|
|
898
979
|
* A `timestamptz` or `timestamp` column, written to `out[at, at + 24)` as
|
|
899
980
|
* `iso` writes it. Answers 24, or -1 and `failed` for a column that is not
|
|
900
981
|
* eight bytes or a time `iso` refuses.
|
|
982
|
+
* @param b The buffer the column lies in.
|
|
983
|
+
* @param start The column's first byte.
|
|
984
|
+
* @param length The column's length in bytes; anything but 8 is refused.
|
|
985
|
+
* @param out The buffer to write the 24 ISO 8601 bytes into; the caller owns it.
|
|
986
|
+
* @param at Where in `out` the time starts; `out` needs 24 bytes from there.
|
|
987
|
+
* @returns 24, the bytes written, or -1 with `failed` set.
|
|
901
988
|
*/
|
|
902
989
|
timestamp(b: u8[], start: i32, length: i32, out: u8[], at: i32): i32 {
|
|
903
990
|
if (length !== 8 || !this.inside(b, start, length)) {
|
|
@@ -913,6 +1000,11 @@ export class PgBinary {
|
|
|
913
1000
|
* not rounded, to milliseconds, as `PgText.timestamp` cuts the same time.
|
|
914
1001
|
* Answers 24, or -1 and `failed` with `out` untouched for a year outside
|
|
915
1002
|
* 0001–9999 (`infinity` and `-infinity` among them) or no room in `out`.
|
|
1003
|
+
* Nothing is allocated.
|
|
1004
|
+
* @param micros Microseconds since 2000-01-01 00:00:00 UTC; negative is before 2000.
|
|
1005
|
+
* @param out The buffer to write into; the caller owns it.
|
|
1006
|
+
* @param at Where in `out` the time starts; `out` needs 24 bytes from there.
|
|
1007
|
+
* @returns 24, the bytes written, or -1 with `failed` set.
|
|
916
1008
|
*/
|
|
917
1009
|
iso(micros: i64, out: u8[], at: i32): i32 {
|
|
918
1010
|
if (at < 0 || at > toI32(out.length) - 24) {
|
|
@@ -963,16 +1055,17 @@ export class PgBinary {
|
|
|
963
1055
|
|
|
964
1056
|
/**
|
|
965
1057
|
* A walk over a one-dimensional `int2[]`, `int4[]` or `int8[]` column in
|
|
966
|
-
* PostgreSQL's binary array layout, in place: `begin` the column, then
|
|
967
|
-
*
|
|
968
|
-
*
|
|
969
|
-
*
|
|
970
|
-
*
|
|
971
|
-
*
|
|
972
|
-
*
|
|
973
|
-
*
|
|
974
|
-
*
|
|
975
|
-
*
|
|
1058
|
+
* PostgreSQL's binary array layout, in place: `begin` the column, then `next()`
|
|
1059
|
+
* until `PG_ARRAY_END` or `PG_ARRAY_BAD`, and `int()` decodes the current
|
|
1060
|
+
* element through `binary`. The header is `ndim`, `hasnull` and the element
|
|
1061
|
+
* OID, then for `ndim` 1 the dimension's length and lower bound (the bound is
|
|
1062
|
+
* read and not used); each element is a length word and its bytes, and a NULL
|
|
1063
|
+
* is a length of -1 with no bytes. `ndim` 0 is the empty array.
|
|
1064
|
+
*
|
|
1065
|
+
* Every refusal sets `binary.failed`: an `ndim` above 1, another element type,
|
|
1066
|
+
* an element whose length is not its type's size, a NULL when `hasnull` is 0, a
|
|
1067
|
+
* column cut short, or bytes after the last element. The walk allocates
|
|
1068
|
+
* nothing, and it reads nothing outside the column.
|
|
976
1069
|
*/
|
|
977
1070
|
export class PgBinaryArray {
|
|
978
1071
|
/** The number of elements the header gives: 0 for an empty array. */
|
|
@@ -980,9 +1073,9 @@ export class PgBinaryArray {
|
|
|
980
1073
|
/** The element type's OID, 20, 21 or 23, once `begin` has read a header it accepts. */
|
|
981
1074
|
elementOid: i32 = 0
|
|
982
1075
|
/** The current element's first byte in the buffer. */
|
|
983
|
-
start: i32 = 0
|
|
1076
|
+
private start: i32 = 0
|
|
984
1077
|
/** The current element's length: its type's size, or 0 for a NULL. */
|
|
985
|
-
length: i32 = 0
|
|
1078
|
+
private length: i32 = 0
|
|
986
1079
|
private binary: PgBinary
|
|
987
1080
|
private b: u8[]
|
|
988
1081
|
private pos: i32 = 0
|
|
@@ -992,12 +1085,26 @@ export class PgBinaryArray {
|
|
|
992
1085
|
private hasNull: boolean = false
|
|
993
1086
|
private bad: boolean = true
|
|
994
1087
|
|
|
1088
|
+
/**
|
|
1089
|
+
* A walker with nothing begun; `next()` answers `PG_ARRAY_BAD` until `begin`.
|
|
1090
|
+
* @param binary The decoders `int()` reads through and whose `failed` every
|
|
1091
|
+
* refusal sets; usually `conn.binary`.
|
|
1092
|
+
*/
|
|
995
1093
|
constructor(binary: PgBinary) {
|
|
996
1094
|
this.binary = binary
|
|
997
1095
|
this.b = []
|
|
998
1096
|
}
|
|
999
1097
|
|
|
1000
|
-
/**
|
|
1098
|
+
/**
|
|
1099
|
+
* Starts a walk over `b[start, start + length)`, reading its header; a
|
|
1100
|
+
* header this walker does not read is refused, which sets `binary.failed`
|
|
1101
|
+
* and makes `next()` answer `PG_ARRAY_BAD`. The walker keeps `b` and reads
|
|
1102
|
+
* it until the next `begin`, so the window must stay valid that long: for a
|
|
1103
|
+
* column, until the connection's next `next()`.
|
|
1104
|
+
* @param b The buffer the column lies in, usually `conn.inputBuffer()`.
|
|
1105
|
+
* @param start The column's first byte, as `colStart(c)` gives it.
|
|
1106
|
+
* @param length The column's length in bytes; NULL's -1 is refused.
|
|
1107
|
+
*/
|
|
1001
1108
|
begin(b: u8[], start: i32, length: i32): void {
|
|
1002
1109
|
this.b = b
|
|
1003
1110
|
this.count = 0
|
|
@@ -1050,7 +1157,13 @@ export class PgBinaryArray {
|
|
|
1050
1157
|
return PG_ARRAY_BAD
|
|
1051
1158
|
}
|
|
1052
1159
|
|
|
1053
|
-
/**
|
|
1160
|
+
/**
|
|
1161
|
+
* Steps to the next element, which `int()` then reads.
|
|
1162
|
+
* @returns `PG_ARRAY_ELEMENT`, `PG_ARRAY_NULL`, `PG_ARRAY_END` once all
|
|
1163
|
+
* `count` elements have been read and the column ends there, or
|
|
1164
|
+
* `PG_ARRAY_BAD` (with `binary.failed` set) for a layout it refuses; a
|
|
1165
|
+
* refused walk answers `PG_ARRAY_BAD` from then on.
|
|
1166
|
+
*/
|
|
1054
1167
|
next(): i32 {
|
|
1055
1168
|
if (this.bad) {
|
|
1056
1169
|
return PG_ARRAY_BAD
|
|
@@ -1084,7 +1197,13 @@ export class PgBinaryArray {
|
|
|
1084
1197
|
return PG_ARRAY_ELEMENT
|
|
1085
1198
|
}
|
|
1086
1199
|
|
|
1087
|
-
/**
|
|
1200
|
+
/**
|
|
1201
|
+
* The current element as an integer, through `PgBinary.int`; a NULL, or a
|
|
1202
|
+
* walk that was refused, sets `binary.failed`.
|
|
1203
|
+
* @returns The element, sign-extended to 64 bits, or 0 when this call is
|
|
1204
|
+
* refused, which sets `binary.failed`. The flag is sticky and shared, so
|
|
1205
|
+
* an earlier refusal leaves it set without making this call answer 0.
|
|
1206
|
+
*/
|
|
1088
1207
|
int(): i64 {
|
|
1089
1208
|
if (this.bad) {
|
|
1090
1209
|
this.binary.failed = true
|
|
@@ -1095,7 +1214,7 @@ export class PgBinaryArray {
|
|
|
1095
1214
|
}
|
|
1096
1215
|
|
|
1097
1216
|
/**
|
|
1098
|
-
* A walk over a one-dimensional `text[]` column in place: `
|
|
1217
|
+
* A walk over a one-dimensional `text[]` column in place: `begin` the
|
|
1099
1218
|
* column, then `next()` until `PG_ARRAY_END` or `PG_ARRAY_BAD`. Each element
|
|
1100
1219
|
* is the window `[start, start + length)` of the column's buffer; a quoted
|
|
1101
1220
|
* element with a backslash escape in it has `escaped` set, and `copy` writes
|
|
@@ -1115,11 +1234,20 @@ export class PgArrayWalker {
|
|
|
1115
1234
|
private bad: boolean = false
|
|
1116
1235
|
private b: u8[]
|
|
1117
1236
|
|
|
1237
|
+
/** A walker with nothing begun; `next()` answers `PG_ARRAY_END` until `begin`. */
|
|
1118
1238
|
constructor() {
|
|
1119
1239
|
this.b = []
|
|
1120
1240
|
}
|
|
1121
1241
|
|
|
1122
|
-
/**
|
|
1242
|
+
/**
|
|
1243
|
+
* Starts a walk over `b[start, start + length)`, which must be a `{...}`
|
|
1244
|
+
* literal; anything else makes `next()` answer `PG_ARRAY_BAD`. The walker
|
|
1245
|
+
* keeps `b` and reads it until the next `begin`, so for a column the walk
|
|
1246
|
+
* must end before the connection's next `next()`.
|
|
1247
|
+
* @param b The buffer the column lies in, usually `conn.inputBuffer()`.
|
|
1248
|
+
* @param start The column's first byte, as `colStart(c)` gives it.
|
|
1249
|
+
* @param length The column's length in bytes, braces included.
|
|
1250
|
+
*/
|
|
1123
1251
|
begin(b: u8[], start: i32, length: i32): void {
|
|
1124
1252
|
this.b = b
|
|
1125
1253
|
this.first = true
|
|
@@ -1136,7 +1264,12 @@ export class PgArrayWalker {
|
|
|
1136
1264
|
return PG_ARRAY_BAD
|
|
1137
1265
|
}
|
|
1138
1266
|
|
|
1139
|
-
/**
|
|
1267
|
+
/**
|
|
1268
|
+
* Steps to the next element, setting `start`, `length` and `escaped`.
|
|
1269
|
+
* @returns `PG_ARRAY_ELEMENT`, `PG_ARRAY_NULL`, `PG_ARRAY_END` or
|
|
1270
|
+
* `PG_ARRAY_BAD`; once `PG_ARRAY_BAD`, the walk answers it until the next
|
|
1271
|
+
* `begin`.
|
|
1272
|
+
*/
|
|
1140
1273
|
next(): i32 {
|
|
1141
1274
|
if (this.bad) {
|
|
1142
1275
|
return PG_ARRAY_BAD
|
|
@@ -1210,7 +1343,14 @@ export class PgArrayWalker {
|
|
|
1210
1343
|
return PG_ARRAY_ELEMENT
|
|
1211
1344
|
}
|
|
1212
1345
|
|
|
1213
|
-
/**
|
|
1346
|
+
/**
|
|
1347
|
+
* Writes the current element, unescaped (each backslash dropped and the
|
|
1348
|
+
* byte after it kept), to `out[at, ...)`. Nothing is allocated.
|
|
1349
|
+
* @param out The buffer to write into; the caller owns it.
|
|
1350
|
+
* @param at Where in `out` the element starts.
|
|
1351
|
+
* @returns The bytes written, at most `length`; -1 when it does not fit,
|
|
1352
|
+
* in which case `out` may hold part of it.
|
|
1353
|
+
*/
|
|
1214
1354
|
copy(out: u8[], at: i32): i32 {
|
|
1215
1355
|
const b: u8[] = this.b
|
|
1216
1356
|
let n: i32 = 0
|
|
@@ -1307,7 +1447,14 @@ export class PgConnection {
|
|
|
1307
1447
|
* A connection that has queued its startup message. `password` is copied,
|
|
1308
1448
|
* so the caller may wipe its own; `nonce` must be at least 18 bytes from a
|
|
1309
1449
|
* cryptographic random source (`crypto.getRandomValues`), and is fixed only
|
|
1310
|
-
* in a test.
|
|
1450
|
+
* in a test. Panics on a `PgConfig` that is a mistake (no user, a cap out
|
|
1451
|
+
* of range, a NUL in a startup parameter) or a nonce shorter than 18 bytes.
|
|
1452
|
+
* @param config The caps and startup parameters; kept, and read for the
|
|
1453
|
+
* connection's life, so do not change it afterwards.
|
|
1454
|
+
* @param password The role's password as UTF-8 bytes, without SASLprep;
|
|
1455
|
+
* copied into a holder the connection wipes once the SCRAM proof is
|
|
1456
|
+
* computed, or when it fails or is disposed. It may be empty for `trust`.
|
|
1457
|
+
* @param nonce The client nonce: its first 18 bytes are used, base64-encoded.
|
|
1311
1458
|
*/
|
|
1312
1459
|
constructor(config: PgConfig, password: Secret<u8[]>, nonce: u8[]) {
|
|
1313
1460
|
if (toI32(nonce.length) < PG_NONCE_BYTES) {
|
|
@@ -1354,22 +1501,38 @@ export class PgConnection {
|
|
|
1354
1501
|
|
|
1355
1502
|
// --- Buffers -----------------------------------------------------------------
|
|
1356
1503
|
|
|
1357
|
-
/**
|
|
1504
|
+
/**
|
|
1505
|
+
* The input buffer: read from the socket into it at `inputEnd()`. The
|
|
1506
|
+
* connection owns it, and `next()` may replace it with a larger one, so
|
|
1507
|
+
* fetch it again after every `next()`.
|
|
1508
|
+
* @returns The buffer itself, not a copy.
|
|
1509
|
+
*/
|
|
1358
1510
|
inputBuffer(): u8[] {
|
|
1359
1511
|
return this.input
|
|
1360
1512
|
}
|
|
1361
1513
|
|
|
1362
|
-
/**
|
|
1514
|
+
/**
|
|
1515
|
+
* Where the next byte read goes.
|
|
1516
|
+
* @returns An index into `inputBuffer()`.
|
|
1517
|
+
*/
|
|
1363
1518
|
inputEnd(): i32 {
|
|
1364
1519
|
return this.inEnd
|
|
1365
1520
|
}
|
|
1366
1521
|
|
|
1367
|
-
/**
|
|
1522
|
+
/**
|
|
1523
|
+
* How many bytes may be read into the input buffer now.
|
|
1524
|
+
* @returns The bytes free from `inputEnd()` to the buffer's end; 0 when it
|
|
1525
|
+
* is full, which `next()` mends by compacting or growing it.
|
|
1526
|
+
*/
|
|
1368
1527
|
inputRoom(): i32 {
|
|
1369
1528
|
return toI32(this.input.length) - this.inEnd
|
|
1370
1529
|
}
|
|
1371
1530
|
|
|
1372
|
-
/**
|
|
1531
|
+
/**
|
|
1532
|
+
* Records that `n` bytes were read into the input buffer at `inputEnd()`.
|
|
1533
|
+
* Panics on a negative `n` or one past `inputRoom()`.
|
|
1534
|
+
* @param n The bytes the read wrote, from 0 to `inputRoom()`.
|
|
1535
|
+
*/
|
|
1373
1536
|
received(n: i32): void {
|
|
1374
1537
|
if (n < 0 || n > this.inputRoom()) {
|
|
1375
1538
|
panic("nish/net/postgres: received more than inputRoom()")
|
|
@@ -1377,7 +1540,16 @@ export class PgConnection {
|
|
|
1377
1540
|
this.inEnd += n
|
|
1378
1541
|
}
|
|
1379
1542
|
|
|
1380
|
-
/**
|
|
1543
|
+
/**
|
|
1544
|
+
* Copies what fits of `src[start, start + length)` into the input buffer at
|
|
1545
|
+
* `inputEnd()`, for a program whose bytes arrive in a buffer of its own.
|
|
1546
|
+
* Panics on a window outside `src`.
|
|
1547
|
+
* @param src The bytes to take; the caller keeps them.
|
|
1548
|
+
* @param start The window's first byte in `src`.
|
|
1549
|
+
* @param length The window's length in bytes.
|
|
1550
|
+
* @returns The bytes copied, at most `inputRoom()`; the rest are the
|
|
1551
|
+
* caller's to give again after `next()`.
|
|
1552
|
+
*/
|
|
1381
1553
|
receive(src: u8[], start: i32, length: i32): i32 {
|
|
1382
1554
|
if (start < 0 || length < 0 || length > toI32(src.length) - start) {
|
|
1383
1555
|
panic("nish/net/postgres: receive() outside its source")
|
|
@@ -1389,22 +1561,39 @@ export class PgConnection {
|
|
|
1389
1561
|
return n
|
|
1390
1562
|
}
|
|
1391
1563
|
|
|
1392
|
-
/**
|
|
1564
|
+
/**
|
|
1565
|
+
* The output buffer: write `[outputStart(), outputEnd())` to the socket.
|
|
1566
|
+
* The connection owns it, and a builder call or `sent` may grow or compact
|
|
1567
|
+
* it, so fetch it again after each.
|
|
1568
|
+
* @returns The buffer itself, not a copy.
|
|
1569
|
+
*/
|
|
1393
1570
|
outputBuffer(): u8[] {
|
|
1394
1571
|
return this.out
|
|
1395
1572
|
}
|
|
1396
1573
|
|
|
1397
|
-
/**
|
|
1574
|
+
/**
|
|
1575
|
+
* The first byte not yet sent.
|
|
1576
|
+
* @returns An index into `outputBuffer()`.
|
|
1577
|
+
*/
|
|
1398
1578
|
outputStart(): i32 {
|
|
1399
1579
|
return this.outStart
|
|
1400
1580
|
}
|
|
1401
1581
|
|
|
1402
|
-
/**
|
|
1582
|
+
/**
|
|
1583
|
+
* One past the last byte that may be sent: a Bind still open is held back
|
|
1584
|
+
* until `bindEnd()` has written its lengths.
|
|
1585
|
+
* @returns An index into `outputBuffer()`; equal to `outputStart()` when
|
|
1586
|
+
* there is nothing to send.
|
|
1587
|
+
*/
|
|
1403
1588
|
outputEnd(): i32 {
|
|
1404
1589
|
return this.bindAt >= 0 ? this.bindAt : this.outEnd
|
|
1405
1590
|
}
|
|
1406
1591
|
|
|
1407
|
-
/**
|
|
1592
|
+
/**
|
|
1593
|
+
* Records that `n` bytes from `outputStart()` were written to the socket.
|
|
1594
|
+
* Panics on a negative `n` or one past `outputEnd() - outputStart()`.
|
|
1595
|
+
* @param n The bytes the write took.
|
|
1596
|
+
*/
|
|
1408
1597
|
sent(n: i32): void {
|
|
1409
1598
|
if (n < 0 || n > this.outputEnd() - this.outStart) {
|
|
1410
1599
|
panic("nish/net/postgres: sent more than was queued")
|
|
@@ -1418,7 +1607,12 @@ export class PgConnection {
|
|
|
1418
1607
|
}
|
|
1419
1608
|
}
|
|
1420
1609
|
|
|
1421
|
-
/**
|
|
1610
|
+
/**
|
|
1611
|
+
* Reports the end of the stream (a read of 0 bytes, or a socket error):
|
|
1612
|
+
* unless it already has, the connection fails with `PG_ERR_CLOSED`, which
|
|
1613
|
+
* wipes the password. Input already received and not yet read is dropped.
|
|
1614
|
+
* @returns `PG_FAILED`, as every later `next()` does.
|
|
1615
|
+
*/
|
|
1422
1616
|
closed(): i32 {
|
|
1423
1617
|
if (this.state !== PG_STATE_FAILED) {
|
|
1424
1618
|
return this.fail(PG_ERR_CLOSED)
|
|
@@ -1431,12 +1625,17 @@ export class PgConnection {
|
|
|
1431
1625
|
* once the proof is computed, the connection has failed or `dispose()` has
|
|
1432
1626
|
* run (and for an empty password). It reads the copy itself, so a test can
|
|
1433
1627
|
* see the wipe happen; a program has no use for it.
|
|
1628
|
+
* @returns True when the copy holds only zero bytes.
|
|
1434
1629
|
*/
|
|
1435
1630
|
passwordWiped(): boolean {
|
|
1436
1631
|
return this.password.wiped()
|
|
1437
1632
|
}
|
|
1438
1633
|
|
|
1439
|
-
/**
|
|
1634
|
+
/**
|
|
1635
|
+
* Wipes the password if the connection still holds it. A program that drops
|
|
1636
|
+
* a connection before it is ready calls this. It does not close anything or
|
|
1637
|
+
* queue a Terminate: that is `terminate()`, and the socket is the program's.
|
|
1638
|
+
*/
|
|
1440
1639
|
dispose(): void {
|
|
1441
1640
|
if (!this.password.gone) {
|
|
1442
1641
|
this.password.wipe()
|
|
@@ -1445,7 +1644,16 @@ export class PgConnection {
|
|
|
1445
1644
|
|
|
1446
1645
|
// --- Reading -----------------------------------------------------------------
|
|
1447
1646
|
|
|
1448
|
-
/**
|
|
1647
|
+
/**
|
|
1648
|
+
* Reads input until it has an event to answer. Each call may move the
|
|
1649
|
+
* unread input to the start of the buffer or replace the buffer, which ends
|
|
1650
|
+
* the windows the last event gave (`colStart`, the tag) and calls for a
|
|
1651
|
+
* fresh `inputBuffer()`.
|
|
1652
|
+
* @returns `PG_NEED_MORE` when it needs more input; `PG_READY`, `PG_ROW`,
|
|
1653
|
+
* `PG_COMPLETE`, `PG_ERROR`, `PG_GROUP_DONE`, `PG_NOTICE` or
|
|
1654
|
+
* `PG_DESCRIBED` (the module header says what each means); or `PG_FAILED`,
|
|
1655
|
+
* final, with `failure` saying why.
|
|
1656
|
+
*/
|
|
1449
1657
|
next(): i32 {
|
|
1450
1658
|
while (true) {
|
|
1451
1659
|
if (this.state === PG_STATE_FAILED) {
|
|
@@ -2106,7 +2314,12 @@ export class PgConnection {
|
|
|
2106
2314
|
setI32BE(this.out, at + 1, this.outEnd - at - 1)
|
|
2107
2315
|
}
|
|
2108
2316
|
|
|
2109
|
-
/**
|
|
2317
|
+
/**
|
|
2318
|
+
* Whether another group may start, or the open one take another message.
|
|
2319
|
+
* @returns True once the connection is ready (after `PG_READY`, until
|
|
2320
|
+
* `PG_FAILED`) and either a group is open or fewer than `maxInFlight`
|
|
2321
|
+
* wait for their answers. Room under `maxOutput` is not part of it.
|
|
2322
|
+
*/
|
|
2110
2323
|
canSend(): boolean {
|
|
2111
2324
|
return this.state === PG_STATE_READY && (this.groupOpen || this.inFlight < this.config.maxInFlight)
|
|
2112
2325
|
}
|
|
@@ -2128,8 +2341,16 @@ export class PgConnection {
|
|
|
2128
2341
|
* unnamed one), its parameters' types given by `paramTypes` (OIDs, 0 to let
|
|
2129
2342
|
* the server infer one, and parameters past the array are inferred too).
|
|
2130
2343
|
* The server answers `PG_DESCRIBED`. False, and nothing written, when
|
|
2131
|
-
* `canSend()` is false, a bind is open, `name` or `sql` holds a NUL,
|
|
2132
|
-
* message would pass `maxOutput`.
|
|
2344
|
+
* `canSend()` is false, a bind is open, `name` or `sql` holds a NUL, more
|
|
2345
|
+
* than 65535 types are given, or the message would pass `maxOutput`. It
|
|
2346
|
+
* opens a group when none is open; `sync()` ends it.
|
|
2347
|
+
* @param name The statement's name; a named statement lasts until
|
|
2348
|
+
* `closeStatement` or the connection's end, the unnamed one until the next
|
|
2349
|
+
* `prepare("")`.
|
|
2350
|
+
* @param sql The statement's text, `$1`, `$2`, ... for its parameters.
|
|
2351
|
+
* @param paramTypes The parameters' type OIDs (23 `int4`, 20 `int8`, 25
|
|
2352
|
+
* `text`), or 0 for one the server infers; read, not kept.
|
|
2353
|
+
* @returns True when the Parse and Describe were queued.
|
|
2133
2354
|
*/
|
|
2134
2355
|
prepare(name: string, sql: string, paramTypes: i32[]): boolean {
|
|
2135
2356
|
const nameLength: i32 = toI32(name.length)
|
|
@@ -2156,7 +2377,13 @@ export class PgConnection {
|
|
|
2156
2377
|
return true
|
|
2157
2378
|
}
|
|
2158
2379
|
|
|
2159
|
-
/**
|
|
2380
|
+
/**
|
|
2381
|
+
* Close: forgets the prepared statement `name` on the server. False, and
|
|
2382
|
+
* nothing written, as `prepare` is. It opens a group when none is open.
|
|
2383
|
+
* @param name The statement to close; closing one that does not exist is
|
|
2384
|
+
* not an error to the server.
|
|
2385
|
+
* @returns True when the Close was queued.
|
|
2386
|
+
*/
|
|
2160
2387
|
closeStatement(name: string): boolean {
|
|
2161
2388
|
if (pgHasNul(name) || toI32(name.length) > PG_MAX_CAP || !this.canOpen(7 + toI32(name.length))) {
|
|
2162
2389
|
return false
|
|
@@ -2170,7 +2397,12 @@ export class PgConnection {
|
|
|
2170
2397
|
|
|
2171
2398
|
/**
|
|
2172
2399
|
* Starts a Bind of the prepared statement `name`; its parameters follow, in
|
|
2173
|
-
* order, then `bindEnd()`. False as `prepare` is.
|
|
2400
|
+
* order, then `bindEnd()`. False, and nothing written, as `prepare` is. It
|
|
2401
|
+
* opens a group when none is open. Until `bindEnd()` or `bindCancel()`,
|
|
2402
|
+
* `outputEnd()` holds the Bind's bytes back.
|
|
2403
|
+
* @param name A statement prepared on this connection, in this group or an
|
|
2404
|
+
* earlier one.
|
|
2405
|
+
* @returns True when the Bind was opened.
|
|
2174
2406
|
*/
|
|
2175
2407
|
bindStart(name: string): boolean {
|
|
2176
2408
|
return this.openBind(name, false)
|
|
@@ -2188,6 +2420,8 @@ export class PgConnection {
|
|
|
2188
2420
|
* with this when its `binary` is set, and reads their routing ordinals with
|
|
2189
2421
|
* `binaryInt`. Its `bindEnd()` writes two bytes more, kept free under
|
|
2190
2422
|
* `maxOutput` from here on. False as `prepare` is.
|
|
2423
|
+
* @param name A statement prepared on this connection.
|
|
2424
|
+
* @returns True when the Bind was opened.
|
|
2191
2425
|
*/
|
|
2192
2426
|
bindStartBinary(name: string): boolean {
|
|
2193
2427
|
return this.openBind(name, true)
|
|
@@ -2271,7 +2505,12 @@ export class PgConnection {
|
|
|
2271
2505
|
// open, the bind has 65535 parameters already, or the parameter would pass
|
|
2272
2506
|
// `maxOutput`; a program that checked `bindStart()` meets only the last.
|
|
2273
2507
|
|
|
2274
|
-
/**
|
|
2508
|
+
/**
|
|
2509
|
+
* A text parameter: the string's bytes as they are. Panics while an array
|
|
2510
|
+
* parameter is open.
|
|
2511
|
+
* @param value The parameter's text; "" is an empty string, not NULL.
|
|
2512
|
+
* @returns True when it was written; false as every `param...` call is.
|
|
2513
|
+
*/
|
|
2275
2514
|
paramText(value: string): boolean {
|
|
2276
2515
|
const at: i32 = this.startParam(toI32(value.length))
|
|
2277
2516
|
if (at < 0) {
|
|
@@ -2282,7 +2521,16 @@ export class PgConnection {
|
|
|
2282
2521
|
return true
|
|
2283
2522
|
}
|
|
2284
2523
|
|
|
2285
|
-
/**
|
|
2524
|
+
/**
|
|
2525
|
+
* A text parameter from `bytes[start, start + length)`, UTF-8, copied into
|
|
2526
|
+
* the Bind so the caller may reuse `bytes` at once. Panics while an array
|
|
2527
|
+
* parameter is open.
|
|
2528
|
+
* @param bytes The buffer the text lies in.
|
|
2529
|
+
* @param start The text's first byte.
|
|
2530
|
+
* @param length The text's length in bytes.
|
|
2531
|
+
* @returns True when it was written; false as every `param...` call is, and
|
|
2532
|
+
* when the window is not inside `bytes`.
|
|
2533
|
+
*/
|
|
2286
2534
|
paramBytes(bytes: u8[], start: i32, length: i32): boolean {
|
|
2287
2535
|
this.noArrayOpen()
|
|
2288
2536
|
if (start < 0 || length < 0 || length > toI32(bytes.length) - start) {
|
|
@@ -2299,7 +2547,11 @@ export class PgConnection {
|
|
|
2299
2547
|
return true
|
|
2300
2548
|
}
|
|
2301
2549
|
|
|
2302
|
-
/**
|
|
2550
|
+
/**
|
|
2551
|
+
* A NULL parameter, of whatever type the statement gives it. Panics while
|
|
2552
|
+
* an array parameter is open.
|
|
2553
|
+
* @returns True when it was written; false as every `param...` call is.
|
|
2554
|
+
*/
|
|
2303
2555
|
paramNull(): boolean {
|
|
2304
2556
|
if (this.startParam(toI32(0)) < 0) {
|
|
2305
2557
|
return false
|
|
@@ -2308,7 +2560,14 @@ export class PgConnection {
|
|
|
2308
2560
|
return true
|
|
2309
2561
|
}
|
|
2310
2562
|
|
|
2311
|
-
/**
|
|
2563
|
+
/**
|
|
2564
|
+
* An integer parameter, in decimal text, which the server reads as the
|
|
2565
|
+
* statement's type (`int2`, `int4`, `int8`, `numeric`, ...). Panics while an
|
|
2566
|
+
* array parameter is open.
|
|
2567
|
+
* @param value The integer; one outside the parameter's type is the
|
|
2568
|
+
* server's error (22003) for that execution.
|
|
2569
|
+
* @returns True when it was written; false as every `param...` call is.
|
|
2570
|
+
*/
|
|
2312
2571
|
paramInt(value: i64): boolean {
|
|
2313
2572
|
const at: i32 = this.startParam(toI32(20))
|
|
2314
2573
|
if (at < 0) {
|
|
@@ -2327,8 +2586,14 @@ export class PgConnection {
|
|
|
2327
2586
|
}
|
|
2328
2587
|
|
|
2329
2588
|
/**
|
|
2330
|
-
* An `int8[]` parameter from `values[start, start + count)`, in decimal
|
|
2331
|
-
* panics when the range is not inside
|
|
2589
|
+
* An `int8[]` parameter from `values[start, start + count)`, in decimal
|
|
2590
|
+
* text (`{1,2,3}`, or `{}` for none); panics when the range is not inside
|
|
2591
|
+
* `values`, or while an array parameter is open.
|
|
2592
|
+
* @param values The integers; read now, not kept.
|
|
2593
|
+
* @param start The first element of the window.
|
|
2594
|
+
* @param count The elements to send, 0 for an empty array.
|
|
2595
|
+
* @returns True when it was written; false, and nothing written, as every
|
|
2596
|
+
* `param...` call is.
|
|
2332
2597
|
*/
|
|
2333
2598
|
paramIntArray(values: i64[], start: i32, count: i32): boolean {
|
|
2334
2599
|
if (start < 0 || count < 0 || count > toI32(values.length) - start) {
|
|
@@ -2361,7 +2626,14 @@ export class PgConnection {
|
|
|
2361
2626
|
return true
|
|
2362
2627
|
}
|
|
2363
2628
|
|
|
2364
|
-
/**
|
|
2629
|
+
/**
|
|
2630
|
+
* A `text[]` parameter: every element quoted, with each double quote and
|
|
2631
|
+
* backslash escaped by a backslash, so no element reads as NULL (build one
|
|
2632
|
+
* with `arrayNull` for that). Panics while an array parameter is open.
|
|
2633
|
+
* @param items The elements, in order; read now, not kept. Empty sends `{}`.
|
|
2634
|
+
* @returns True when it was written; false, and nothing written, as every
|
|
2635
|
+
* `param...` call is.
|
|
2636
|
+
*/
|
|
2365
2637
|
paramTextArray(items: string[]): boolean {
|
|
2366
2638
|
// Its exact size first, so that room is asked for once and a refusal writes nothing.
|
|
2367
2639
|
let size: i64 = 2
|
|
@@ -2415,7 +2687,12 @@ export class PgConnection {
|
|
|
2415
2687
|
/**
|
|
2416
2688
|
* An `int4[]` parameter in binary from `values[start, start + count)`;
|
|
2417
2689
|
* false as the `param...` calls are. Panics, writing nothing, when the
|
|
2418
|
-
* window is not inside `values` or an element is outside `int4
|
|
2690
|
+
* window is not inside `values` or an element is outside `int4`, and while
|
|
2691
|
+
* an array parameter is open.
|
|
2692
|
+
* @param values The integers, each within -2^31..2^31-1; read now, not kept.
|
|
2693
|
+
* @param start The first element of the window.
|
|
2694
|
+
* @param count The elements to send, 0 for an empty array.
|
|
2695
|
+
* @returns True when it was written.
|
|
2419
2696
|
*/
|
|
2420
2697
|
paramInt4Array(values: i64[], start: i32, count: i32): boolean {
|
|
2421
2698
|
pgIntWindow(values, start, count)
|
|
@@ -2431,7 +2708,11 @@ export class PgConnection {
|
|
|
2431
2708
|
/**
|
|
2432
2709
|
* An `int8[]` parameter in binary from `values[start, start + count)`;
|
|
2433
2710
|
* false as the `param...` calls are. Panics when the window is not inside
|
|
2434
|
-
* `values
|
|
2711
|
+
* `values`, and while an array parameter is open.
|
|
2712
|
+
* @param values The integers; read now, not kept.
|
|
2713
|
+
* @param start The first element of the window.
|
|
2714
|
+
* @param count The elements to send, 0 for an empty array.
|
|
2715
|
+
* @returns True when it was written.
|
|
2435
2716
|
*/
|
|
2436
2717
|
paramInt8Array(values: i64[], start: i32, count: i32): boolean {
|
|
2437
2718
|
pgIntWindow(values, start, count)
|
|
@@ -2485,7 +2766,13 @@ export class PgConnection {
|
|
|
2485
2766
|
// with none open and a second `arrayStart()`; `sync()`, `prepare`,
|
|
2486
2767
|
// `closeStatement` and `bindStart` answer false, the bind being open.
|
|
2487
2768
|
|
|
2488
|
-
/**
|
|
2769
|
+
/**
|
|
2770
|
+
* Opens a text array parameter, `{}` so far, which `arrayElement`,
|
|
2771
|
+
* `arrayInt` and `arrayNull` fill and `arrayEnd()` closes. Panics while an
|
|
2772
|
+
* array is open.
|
|
2773
|
+
* @returns True when it was opened; false, and nothing written, as the
|
|
2774
|
+
* `param...` calls are.
|
|
2775
|
+
*/
|
|
2489
2776
|
arrayStart(): boolean {
|
|
2490
2777
|
if (this.arrayAt >= 0) {
|
|
2491
2778
|
panic("nish/net/postgres: arrayStart() while an array is open")
|
|
@@ -2519,7 +2806,12 @@ export class PgConnection {
|
|
|
2519
2806
|
/**
|
|
2520
2807
|
* A text element from `bytes[start, start + length)`, UTF-8, quoted with
|
|
2521
2808
|
* `"` and `\` escaped; false, and nothing written, when there is no room.
|
|
2522
|
-
* Panics when no array is open or the window is not inside `bytes`.
|
|
2809
|
+
* Panics when no text array is open or the window is not inside `bytes`.
|
|
2810
|
+
* @param bytes The buffer the element lies in; copied, so it may be reused at once.
|
|
2811
|
+
* @param start The element's first byte.
|
|
2812
|
+
* @param length The element's length in bytes; 0 is the empty string.
|
|
2813
|
+
* @returns True when it was written; false leaves the array open with the
|
|
2814
|
+
* elements it has.
|
|
2523
2815
|
*/
|
|
2524
2816
|
arrayElement(bytes: u8[], start: i32, length: i32): boolean {
|
|
2525
2817
|
this.arrayOpen()
|
|
@@ -2557,7 +2849,11 @@ export class PgConnection {
|
|
|
2557
2849
|
return true
|
|
2558
2850
|
}
|
|
2559
2851
|
|
|
2560
|
-
/**
|
|
2852
|
+
/**
|
|
2853
|
+
* A NULL element of the open text array. Panics when no text array is open.
|
|
2854
|
+
* @returns True when it was written; false, and nothing written, when there
|
|
2855
|
+
* is no room.
|
|
2856
|
+
*/
|
|
2561
2857
|
arrayNull(): boolean {
|
|
2562
2858
|
this.arrayOpen()
|
|
2563
2859
|
if (!this.elementRoom(toI64(4))) {
|
|
@@ -2575,7 +2871,13 @@ export class PgConnection {
|
|
|
2575
2871
|
this.arrayCount += 1
|
|
2576
2872
|
}
|
|
2577
2873
|
|
|
2578
|
-
/**
|
|
2874
|
+
/**
|
|
2875
|
+
* An integer element of the open text array, in decimal. Panics when no
|
|
2876
|
+
* text array is open.
|
|
2877
|
+
* @param value The element.
|
|
2878
|
+
* @returns True when it was written; false, and nothing written, when there
|
|
2879
|
+
* is no room.
|
|
2880
|
+
*/
|
|
2579
2881
|
arrayInt(value: i64): boolean {
|
|
2580
2882
|
this.arrayOpen()
|
|
2581
2883
|
if (!this.elementRoom(toI64(pgDecimalLength(value)))) {
|
|
@@ -2592,7 +2894,14 @@ export class PgConnection {
|
|
|
2592
2894
|
// The text builder's rules hold, and a text element in a binary array, or a
|
|
2593
2895
|
// binary element in a text one, panics.
|
|
2594
2896
|
|
|
2595
|
-
/**
|
|
2897
|
+
/**
|
|
2898
|
+
* Opens a binary array parameter of `elementOid`'s elements, which
|
|
2899
|
+
* `binaryArrayInt` and `binaryArrayNull` fill and `arrayEnd()` closes.
|
|
2900
|
+
* Panics on another OID, or while an array is open.
|
|
2901
|
+
* @param elementOid 23 for an `int4[]`, 20 for an `int8[]`.
|
|
2902
|
+
* @returns True when it was opened; false, and nothing written, as the
|
|
2903
|
+
* `param...` calls are.
|
|
2904
|
+
*/
|
|
2596
2905
|
binaryArrayStart(elementOid: i32): boolean {
|
|
2597
2906
|
if (this.arrayAt >= 0) {
|
|
2598
2907
|
panic("nish/net/postgres: binaryArrayStart() while an array is open")
|
|
@@ -2624,6 +2933,8 @@ export class PgConnection {
|
|
|
2624
2933
|
* An integer element of the open binary array; false, and nothing written,
|
|
2625
2934
|
* when there is no room. Panics when no binary array is open, or when it is
|
|
2626
2935
|
* an `int4[]` and `value` is outside `int4`.
|
|
2936
|
+
* @param value The element: four bytes in an `int4[]`, eight in an `int8[]`.
|
|
2937
|
+
* @returns True when it was written.
|
|
2627
2938
|
*/
|
|
2628
2939
|
binaryArrayInt(value: i64): boolean {
|
|
2629
2940
|
this.binaryArrayOpen()
|
|
@@ -2646,7 +2957,12 @@ export class PgConnection {
|
|
|
2646
2957
|
return true
|
|
2647
2958
|
}
|
|
2648
2959
|
|
|
2649
|
-
/**
|
|
2960
|
+
/**
|
|
2961
|
+
* A NULL element of the open binary array, length -1. Panics when no binary
|
|
2962
|
+
* array is open.
|
|
2963
|
+
* @returns True when it was written; false, and nothing written, when there
|
|
2964
|
+
* is no room.
|
|
2965
|
+
*/
|
|
2650
2966
|
binaryArrayNull(): boolean {
|
|
2651
2967
|
this.binaryArrayOpen()
|
|
2652
2968
|
if (!this.room(toI32(4))) {
|
|
@@ -2658,7 +2974,11 @@ export class PgConnection {
|
|
|
2658
2974
|
return true
|
|
2659
2975
|
}
|
|
2660
2976
|
|
|
2661
|
-
/**
|
|
2977
|
+
/**
|
|
2978
|
+
* Ends the open array parameter, text or binary; never refused for room,
|
|
2979
|
+
* which its elements kept. An array with no elements is sent as the empty
|
|
2980
|
+
* array. Panics when no array is open.
|
|
2981
|
+
*/
|
|
2662
2982
|
arrayEnd(): void {
|
|
2663
2983
|
if (this.arrayAt < 0) {
|
|
2664
2984
|
panic("nish/net/postgres: arrayEnd() with no arrayStart()")
|
|
@@ -2686,7 +3006,9 @@ export class PgConnection {
|
|
|
2686
3006
|
* Ends the Bind (every result column in text, or in binary after
|
|
2687
3007
|
* `bindStartBinary`) and queues its Execute, for every row. False, and
|
|
2688
3008
|
* nothing written, when no bind is open; never for room, which the calls
|
|
2689
|
-
* before it kept.
|
|
3009
|
+
* before it kept. Panics while an array parameter is open. The Bind's bytes
|
|
3010
|
+
* count toward `outputEnd()` from here on.
|
|
3011
|
+
* @returns True when the Bind and Execute were queued.
|
|
2690
3012
|
*/
|
|
2691
3013
|
bindEnd(): boolean {
|
|
2692
3014
|
if (this.bindAt < 0) {
|
|
@@ -2723,6 +3045,7 @@ export class PgConnection {
|
|
|
2723
3045
|
* Drops the open bind, and the array open in it, unsent, so that a program
|
|
2724
3046
|
* whose parameter was refused for room can send the group without it; a
|
|
2725
3047
|
* group the bind opened is closed again. False when no bind is open.
|
|
3048
|
+
* @returns True when an open bind was dropped.
|
|
2726
3049
|
*/
|
|
2727
3050
|
bindCancel(): boolean {
|
|
2728
3051
|
if (this.bindAt < 0) {
|
|
@@ -2766,7 +3089,12 @@ export class PgConnection {
|
|
|
2766
3089
|
this.paramCountAt = from + codes
|
|
2767
3090
|
}
|
|
2768
3091
|
|
|
2769
|
-
/**
|
|
3092
|
+
/**
|
|
3093
|
+
* Sync: ends the open group, which the server answers with
|
|
3094
|
+
* `PG_GROUP_DONE`; the group stays in `inFlight` until then.
|
|
3095
|
+
* @returns True when the Sync was queued; false when no group is open or a
|
|
3096
|
+
* bind is; never for room.
|
|
3097
|
+
*/
|
|
2770
3098
|
sync(): boolean {
|
|
2771
3099
|
if (!this.groupOpen || this.bindAt >= 0) {
|
|
2772
3100
|
return false
|
|
@@ -2778,7 +3106,11 @@ export class PgConnection {
|
|
|
2778
3106
|
return true
|
|
2779
3107
|
}
|
|
2780
3108
|
|
|
2781
|
-
/**
|
|
3109
|
+
/**
|
|
3110
|
+
* Terminate: tells the server the connection is ending; close the socket
|
|
3111
|
+
* once it is sent. A bind still open is dropped unsent. It is queued in any
|
|
3112
|
+
* state, and is never refused for room.
|
|
3113
|
+
*/
|
|
2782
3114
|
terminate(): void {
|
|
2783
3115
|
if (this.bindAt >= 0) {
|
|
2784
3116
|
this.dropBind()
|
|
@@ -2790,22 +3122,39 @@ export class PgConnection {
|
|
|
2790
3122
|
|
|
2791
3123
|
// --- Results -----------------------------------------------------------------
|
|
2792
3124
|
|
|
2793
|
-
/**
|
|
3125
|
+
/**
|
|
3126
|
+
* Column `c`'s first byte in `inputBuffer()`, valid until the next `next()`.
|
|
3127
|
+
* @param c The column, 0 to `columns - 1`.
|
|
3128
|
+
* @returns An index into `inputBuffer()`.
|
|
3129
|
+
*/
|
|
2794
3130
|
colStart(c: i32): i32 {
|
|
2795
3131
|
return this.colStarts[c]
|
|
2796
3132
|
}
|
|
2797
3133
|
|
|
2798
|
-
/**
|
|
3134
|
+
/**
|
|
3135
|
+
* Column `c`'s length.
|
|
3136
|
+
* @param c The column, 0 to `columns - 1`.
|
|
3137
|
+
* @returns The length in bytes, or -1 for NULL.
|
|
3138
|
+
*/
|
|
2799
3139
|
colLength(c: i32): i32 {
|
|
2800
3140
|
return this.colLengths[c]
|
|
2801
3141
|
}
|
|
2802
3142
|
|
|
2803
|
-
/**
|
|
3143
|
+
/**
|
|
3144
|
+
* Whether column `c` of the current row is NULL.
|
|
3145
|
+
* @param c The column, 0 to `columns - 1`.
|
|
3146
|
+
* @returns True when the column is NULL.
|
|
3147
|
+
*/
|
|
2804
3148
|
isNull(c: i32): boolean {
|
|
2805
3149
|
return this.colLengths[c] < 0
|
|
2806
3150
|
}
|
|
2807
3151
|
|
|
2808
|
-
/**
|
|
3152
|
+
/**
|
|
3153
|
+
* Column `c` as a string; the one result read that allocates, and the string
|
|
3154
|
+
* outlives the row.
|
|
3155
|
+
* @param c The column, 0 to `columns - 1`.
|
|
3156
|
+
* @returns The column's bytes as a string; "" for NULL and for an empty value.
|
|
3157
|
+
*/
|
|
2809
3158
|
columnText(c: i32): string {
|
|
2810
3159
|
const length: i32 = this.colLengths[c]
|
|
2811
3160
|
if (length <= 0) {
|
|
@@ -2815,37 +3164,70 @@ export class PgConnection {
|
|
|
2815
3164
|
return String.fromBytes(this.input, start, start + length)
|
|
2816
3165
|
}
|
|
2817
3166
|
|
|
2818
|
-
/**
|
|
3167
|
+
/**
|
|
3168
|
+
* Column `c` of the statement just described, after `PG_DESCRIBED`.
|
|
3169
|
+
* @param c The column, 0 to `columns - 1`.
|
|
3170
|
+
* @returns Its type's OID (23 is `int4`, 25 `text`).
|
|
3171
|
+
*/
|
|
2819
3172
|
columnType(c: i32): i32 {
|
|
2820
3173
|
return this.colTypes[c]
|
|
2821
3174
|
}
|
|
2822
3175
|
|
|
2823
|
-
/**
|
|
3176
|
+
/**
|
|
3177
|
+
* Text column `c` as an integer, through `text.int`; NULL or a bad value
|
|
3178
|
+
* sets `text.failed`.
|
|
3179
|
+
* @param c The column, 0 to `columns - 1`.
|
|
3180
|
+
* @returns The value, or 0 when it sets `text.failed`.
|
|
3181
|
+
*/
|
|
2824
3182
|
int(c: i32): i64 {
|
|
2825
3183
|
return this.text.int(this.input, this.colStarts[c], this.colLengths[c])
|
|
2826
3184
|
}
|
|
2827
3185
|
|
|
2828
|
-
/**
|
|
3186
|
+
/**
|
|
3187
|
+
* Text column `c` as a boolean, through `text.bool`; NULL or a bad value
|
|
3188
|
+
* sets `text.failed`.
|
|
3189
|
+
* @param c The column, 0 to `columns - 1`.
|
|
3190
|
+
* @returns True for `t`; false for `f`, and when it sets `text.failed`.
|
|
3191
|
+
*/
|
|
2829
3192
|
bool(c: i32): boolean {
|
|
2830
3193
|
return this.text.bool(this.input, this.colStarts[c], this.colLengths[c])
|
|
2831
3194
|
}
|
|
2832
3195
|
|
|
2833
|
-
/**
|
|
3196
|
+
/**
|
|
3197
|
+
* Binary column `c`, an `int2`, `int4`, `int8` or a time's microseconds
|
|
3198
|
+
* since 2000, as an integer; NULL or another length sets `binary.failed`.
|
|
3199
|
+
* @param c The column, 0 to `columns - 1`.
|
|
3200
|
+
* @returns The value, or 0 when it sets `binary.failed`.
|
|
3201
|
+
*/
|
|
2834
3202
|
binaryInt(c: i32): i64 {
|
|
2835
3203
|
return this.binary.int(this.input, this.colStarts[c], this.colLengths[c])
|
|
2836
3204
|
}
|
|
2837
3205
|
|
|
2838
|
-
/**
|
|
3206
|
+
/**
|
|
3207
|
+
* Binary column `c` as a boolean; NULL or a bad value sets `binary.failed`.
|
|
3208
|
+
* @param c The column, 0 to `columns - 1`.
|
|
3209
|
+
* @returns True for 1; false for 0, and when it sets `binary.failed`.
|
|
3210
|
+
*/
|
|
2839
3211
|
binaryBool(c: i32): boolean {
|
|
2840
3212
|
return this.binary.bool(this.input, this.colStarts[c], this.colLengths[c])
|
|
2841
3213
|
}
|
|
2842
3214
|
|
|
2843
|
-
/**
|
|
3215
|
+
/**
|
|
3216
|
+
* Binary column `c`, a `float8`; NULL or another length sets `binary.failed`.
|
|
3217
|
+
* @param c The column, 0 to `columns - 1`.
|
|
3218
|
+
* @returns The value, or 0 when it sets `binary.failed`.
|
|
3219
|
+
*/
|
|
2844
3220
|
binaryFloat(c: i32): f64 {
|
|
2845
3221
|
return this.binary.float(this.input, this.colStarts[c], this.colLengths[c])
|
|
2846
3222
|
}
|
|
2847
3223
|
|
|
2848
|
-
/**
|
|
3224
|
+
/**
|
|
3225
|
+
* Whether the tag of the execution just completed starts with the word
|
|
3226
|
+
* `word`, read after `PG_COMPLETE` and before the next `next()`.
|
|
3227
|
+
* @param word The command word, as the server spells it (`INSERT`,
|
|
3228
|
+
* `SELECT`, `UPDATE`, ...); case matters, and `INS` does not match `INSERT`.
|
|
3229
|
+
* @returns True when the tag is `word` or begins with `word` and a space.
|
|
3230
|
+
*/
|
|
2849
3231
|
tagIs(word: string): boolean {
|
|
2850
3232
|
const n: i32 = toI32(word.length)
|
|
2851
3233
|
if (n > this.tagLength || !pgBytesAre(this.input, this.tagStart, n, word)) {
|
|
@@ -2854,7 +3236,13 @@ export class PgConnection {
|
|
|
2854
3236
|
return n === this.tagLength || toI32(this.input[this.tagStart + n]) === 32
|
|
2855
3237
|
}
|
|
2856
3238
|
|
|
2857
|
-
/**
|
|
3239
|
+
/**
|
|
3240
|
+
* The row count the tag of the execution just completed ends with, read
|
|
3241
|
+
* after `PG_COMPLETE` and before the next `next()`; `text.failed` is left
|
|
3242
|
+
* as it was.
|
|
3243
|
+
* @returns The count (`INSERT 0 3` is 3, `SELECT 5` is 5), or -1 when the
|
|
3244
|
+
* tag has none (`BEGIN`) or it does not fit an i64.
|
|
3245
|
+
*/
|
|
2858
3246
|
tagRows(): i64 {
|
|
2859
3247
|
const end: i32 = this.tagStart + this.tagLength
|
|
2860
3248
|
let p: i32 = end
|
|
@@ -2904,15 +3292,27 @@ const PG_SLOT_DRAINING: i32 = 4
|
|
|
2904
3292
|
|
|
2905
3293
|
/** One of a pool's connections, and the groups it has in flight. */
|
|
2906
3294
|
class PgPoolSlot {
|
|
3295
|
+
/** @internal Used by `PgPool.dispatch`, `PgPool.wanted`, `PgPool.connect`, `PgPool.next` and `PgPool.anyReady` in this module. */
|
|
2907
3296
|
state: i32 = 0
|
|
3297
|
+
/** @internal Used by `PgPool.dispatch`, `PgPool.connect`, `PgPool.connection` and `PgPool.dispose` in this module. */
|
|
2908
3298
|
conn: PgConnection | null = null
|
|
2909
|
-
/**
|
|
3299
|
+
/**
|
|
3300
|
+
* How many registered statements this connection has queued, and how many the server has described.
|
|
3301
|
+
* @internal Used by `PgPool.dispatch`, `PgPool.connect` and `PgPool.next` in this module.
|
|
3302
|
+
*/
|
|
2910
3303
|
queued: i32 = 0
|
|
3304
|
+
/** @internal Used by `PgPool.connect` and `PgPool.next` in this module. */
|
|
2911
3305
|
described: i32 = 0
|
|
2912
|
-
/**
|
|
3306
|
+
/**
|
|
3307
|
+
* The groups in flight, oldest first, in a ring: each one's ticket, and how many of the pool's own prepares lead it.
|
|
3308
|
+
* @internal Used by `PgPool.next` in this module.
|
|
3309
|
+
*/
|
|
2913
3310
|
readonly tickets: i32[]
|
|
3311
|
+
/** @internal Used by `PgPool.next` in this module. */
|
|
2914
3312
|
readonly leads: i32[]
|
|
3313
|
+
/** @internal Used by `PgPool.connect` and `PgPool.next` in this module. */
|
|
2915
3314
|
head: i32 = 0
|
|
3315
|
+
/** @internal Used by `PgPool.inFlight`, `PgPool.send`, `PgPool.connect` and `PgPool.next` in this module. */
|
|
2916
3316
|
count: i32 = 0
|
|
2917
3317
|
|
|
2918
3318
|
constructor(ring: i32) {
|
|
@@ -2920,6 +3320,7 @@ class PgPoolSlot {
|
|
|
2920
3320
|
this.leads = new Array<i32>(ring)
|
|
2921
3321
|
}
|
|
2922
3322
|
|
|
3323
|
+
/** @internal Used by `PgPool.dispatch` and `PgPool.next` in this module. */
|
|
2923
3324
|
push(ticket: i32, leads: i32): void {
|
|
2924
3325
|
const at: i32 = (this.head + this.count) % toI32(this.tickets.length)
|
|
2925
3326
|
this.tickets[at] = ticket
|
|
@@ -2927,6 +3328,7 @@ class PgPoolSlot {
|
|
|
2927
3328
|
this.count += 1
|
|
2928
3329
|
}
|
|
2929
3330
|
|
|
3331
|
+
/** @internal Used by `PgPool.next` in this module. */
|
|
2930
3332
|
pop(): void {
|
|
2931
3333
|
this.head = (this.head + 1) % toI32(this.tickets.length)
|
|
2932
3334
|
this.count -= 1
|
|
@@ -2975,6 +3377,12 @@ export class PgPool {
|
|
|
2975
3377
|
* waiting requests (1 to 2^20). `password` is copied and kept until
|
|
2976
3378
|
* `dispose()`, since a connection is made again after a failure. Panics as
|
|
2977
3379
|
* `PgConnection` does on `config`, and on a `maxInFlight` over 1024.
|
|
3380
|
+
*
|
|
3381
|
+
* @param config The settings every connection of the pool is made with; kept, not copied.
|
|
3382
|
+
* @param password The password every connection authenticates with. The pool keeps its
|
|
3383
|
+
* own copy, so the caller may wipe this one as soon as the constructor returns.
|
|
3384
|
+
* @param size The most connections the pool makes, from 1 to 1024.
|
|
3385
|
+
* @param queueSize The most requests that may wait for a connection, from 1 to 2^20.
|
|
2978
3386
|
*/
|
|
2979
3387
|
constructor(config: PgConfig, password: Secret<u8[]>, size: i32, queueSize: i32) {
|
|
2980
3388
|
pgCheckConfig(config)
|
|
@@ -3004,6 +3412,11 @@ export class PgPool {
|
|
|
3004
3412
|
* Registers a statement for every connection to prepare before its first
|
|
3005
3413
|
* request. False when a connection has been made already, `name` or `sql`
|
|
3006
3414
|
* holds a NUL, or 256 are registered.
|
|
3415
|
+
*
|
|
3416
|
+
* @param name The statement's name, which the program's binds use; no NUL.
|
|
3417
|
+
* @param sql The statement's text, with `$1`, `$2`... for its parameters; no NUL.
|
|
3418
|
+
* @param paramTypes The type OID of each parameter, 0 to let the server infer it; copied.
|
|
3419
|
+
* @returns True when the statement was registered.
|
|
3007
3420
|
*/
|
|
3008
3421
|
register(name: string, sql: string, paramTypes: i32[]): boolean {
|
|
3009
3422
|
if (
|
|
@@ -3024,7 +3437,12 @@ export class PgPool {
|
|
|
3024
3437
|
return true
|
|
3025
3438
|
}
|
|
3026
3439
|
|
|
3027
|
-
/**
|
|
3440
|
+
/**
|
|
3441
|
+
* Queues a request and answers its ticket, or `PG_POOL_FULL` when `queueSize` are waiting.
|
|
3442
|
+
*
|
|
3443
|
+
* @returns The request's ticket, from 0 to 2^31-1 and counting up from 0, wrapping to 0
|
|
3444
|
+
* after 2^31-1; or `PG_POOL_FULL`.
|
|
3445
|
+
*/
|
|
3028
3446
|
request(): i32 {
|
|
3029
3447
|
const room: i32 = toI32(this.queue.length)
|
|
3030
3448
|
if (this.queueCount === room) {
|
|
@@ -3037,12 +3455,21 @@ export class PgPool {
|
|
|
3037
3455
|
return ticket
|
|
3038
3456
|
}
|
|
3039
3457
|
|
|
3040
|
-
/**
|
|
3458
|
+
/**
|
|
3459
|
+
* How many requests wait for a connection.
|
|
3460
|
+
*
|
|
3461
|
+
* @returns The requests queued and not yet given a connection.
|
|
3462
|
+
*/
|
|
3041
3463
|
waiting(): i32 {
|
|
3042
3464
|
return this.queueCount
|
|
3043
3465
|
}
|
|
3044
3466
|
|
|
3045
|
-
/**
|
|
3467
|
+
/**
|
|
3468
|
+
* How many groups are in flight across every connection: the `inFlight` a
|
|
3469
|
+
* `PgBatchClock` reads.
|
|
3470
|
+
*
|
|
3471
|
+
* @returns The groups sent and not yet done, summed over every connection.
|
|
3472
|
+
*/
|
|
3046
3473
|
inFlight(): i32 {
|
|
3047
3474
|
let n: i32 = 0
|
|
3048
3475
|
for (const slot of this.slots) {
|
|
@@ -3061,6 +3488,8 @@ export class PgPool {
|
|
|
3061
3488
|
* waiting requests that the connections already starting cannot take. A
|
|
3062
3489
|
* request handed out is the program's to end with `send()`: until then no
|
|
3063
3490
|
* other is handed out.
|
|
3491
|
+
*
|
|
3492
|
+
* @returns The slot the request was handed to, from 0 to `size - 1`, or `PG_POOL_NONE`.
|
|
3064
3493
|
*/
|
|
3065
3494
|
dispatch(): i32 {
|
|
3066
3495
|
if (this.building >= 0 || this.queueCount === 0) {
|
|
@@ -3117,6 +3546,8 @@ export class PgPool {
|
|
|
3117
3546
|
* is none; when a bind is still open, so finish it and call again; and
|
|
3118
3547
|
* when no message of the group was written, so the request is dropped and
|
|
3119
3548
|
* gets no events (`PG_LOST` if its connection has failed).
|
|
3549
|
+
*
|
|
3550
|
+
* @returns True when the group's Sync was written and the request is in flight.
|
|
3120
3551
|
*/
|
|
3121
3552
|
send(): boolean {
|
|
3122
3553
|
const s: i32 = this.building
|
|
@@ -3140,7 +3571,11 @@ export class PgPool {
|
|
|
3140
3571
|
return false
|
|
3141
3572
|
}
|
|
3142
3573
|
|
|
3143
|
-
/**
|
|
3574
|
+
/**
|
|
3575
|
+
* A slot that needs a socket, or `PG_POOL_NONE`: connect it, then call `connect(slot, nonce)`.
|
|
3576
|
+
*
|
|
3577
|
+
* @returns The lowest wanted slot, or `PG_POOL_NONE` when no slot is wanted.
|
|
3578
|
+
*/
|
|
3144
3579
|
wanted(): i32 {
|
|
3145
3580
|
for (let s: i32 = 0; s < this.size; s++) {
|
|
3146
3581
|
if (this.slots[s].state === PG_SLOT_WANTED) {
|
|
@@ -3155,6 +3590,10 @@ export class PgPool {
|
|
|
3155
3590
|
* send its output once the socket is connected, and if the socket fails,
|
|
3156
3591
|
* call `connection(slot).closed()`. Panics when `slot` is not wanted or the
|
|
3157
3592
|
* pool is disposed.
|
|
3593
|
+
*
|
|
3594
|
+
* @param slot The slot `wanted()` answered.
|
|
3595
|
+
* @param nonce At least 18 fresh random bytes for the SCRAM client nonce, as the
|
|
3596
|
+
* `PgConnection` constructor takes them; a new one for every connection.
|
|
3158
3597
|
*/
|
|
3159
3598
|
connect(slot: i32, nonce: u8[]): void {
|
|
3160
3599
|
if (slot < 0 || slot >= this.size || this.slots[slot].state !== PG_SLOT_WANTED) {
|
|
@@ -3173,7 +3612,13 @@ export class PgPool {
|
|
|
3173
3612
|
this.started = true
|
|
3174
3613
|
}
|
|
3175
3614
|
|
|
3176
|
-
/**
|
|
3615
|
+
/**
|
|
3616
|
+
* The connection in `slot`, its buffers the carrier's to fill and drain; the last one made
|
|
3617
|
+
* after it fails. Panics when none was made.
|
|
3618
|
+
*
|
|
3619
|
+
* @param slot The slot, from 0 to `size - 1`.
|
|
3620
|
+
* @returns The slot's connection, owned by the pool: a later `connect` on the slot replaces it.
|
|
3621
|
+
*/
|
|
3177
3622
|
connection(slot: i32): PgConnection {
|
|
3178
3623
|
const conn: PgConnection | null = slot < 0 || slot >= this.size ? null : this.slots[slot].conn
|
|
3179
3624
|
if (conn === null) {
|
|
@@ -3193,6 +3638,9 @@ export class PgPool {
|
|
|
3193
3638
|
* server that cannot be reached empties the queue rather than holds it.
|
|
3194
3639
|
* `PG_NEED_MORE` once `PG_FAILED` was answered, until `connect` builds the
|
|
3195
3640
|
* slot again. Panics as `connection(slot)` does.
|
|
3641
|
+
*
|
|
3642
|
+
* @param slot The slot whose input the carrier has just filled, from 0 to `size - 1`.
|
|
3643
|
+
* @returns A `PG_` event; `ticket` names the request it is about.
|
|
3196
3644
|
*/
|
|
3197
3645
|
next(slot: i32): i32 {
|
|
3198
3646
|
const conn: PgConnection = this.connection(slot)
|
|
@@ -3249,7 +3697,13 @@ export class PgPool {
|
|
|
3249
3697
|
return false
|
|
3250
3698
|
}
|
|
3251
3699
|
|
|
3252
|
-
/**
|
|
3700
|
+
/**
|
|
3701
|
+
* Whether every byte of the pool's copy of the password is zero, as
|
|
3702
|
+
* `PgConnection.passwordWiped()` reads its own: true once it is wiped, and
|
|
3703
|
+
* for an empty password before any wipe.
|
|
3704
|
+
*
|
|
3705
|
+
* @returns True once the pool's copy is wiped; the connections' copies are not read.
|
|
3706
|
+
*/
|
|
3253
3707
|
passwordWiped(): boolean {
|
|
3254
3708
|
return this.password.wiped()
|
|
3255
3709
|
}
|
|
@@ -3365,23 +3819,46 @@ export class PgBatchConfig {
|
|
|
3365
3819
|
|
|
3366
3820
|
/** One execution's requests, grouped by key, and how far its rows have been routed. */
|
|
3367
3821
|
class PgBatchRun {
|
|
3368
|
-
/**
|
|
3822
|
+
/**
|
|
3823
|
+
* Key `k`'s requests' tags are `tags[first[k], first[k + 1])`, in the order they were added; grown by `take` to the batch.
|
|
3824
|
+
* @internal Used by `PgBatcher.take`, `PgBatcher.emit`, `PgBatcher.next` and `PgBatcher.nextUnsorted` in this module.
|
|
3825
|
+
*/
|
|
3369
3826
|
tags: i32[]
|
|
3827
|
+
/** @internal Used by `PgBatcher.take`, `PgBatcher.emit` and `PgBatcher.nextUnsorted` in this module. */
|
|
3370
3828
|
first: i32[]
|
|
3371
|
-
/**
|
|
3829
|
+
/**
|
|
3830
|
+
* Under `sorted` false, whether key `k` has had a row; grown by `take` with `tags`, and empty when sorted.
|
|
3831
|
+
* @internal Used by `PgBatcher.take`, `PgBatcher.row` and `PgBatcher.nextUnsorted` in this module.
|
|
3832
|
+
*/
|
|
3372
3833
|
had: boolean[]
|
|
3834
|
+
/** @internal Used by `PgBatcher.row`, `PgBatcher.next` and `PgBatcher.nextUnsorted` in this module. */
|
|
3373
3835
|
keys: i32 = 0
|
|
3374
|
-
/**
|
|
3836
|
+
/**
|
|
3837
|
+
* The key rows are being read for, whether it has had one, and the next of its requests to answer.
|
|
3838
|
+
* @internal Used by `PgBatcher.row`, `PgBatcher.emit`, `PgBatcher.next` and `PgBatcher.nextUnsorted` in this module.
|
|
3839
|
+
*/
|
|
3375
3840
|
cur: i32 = 0
|
|
3841
|
+
/** @internal Used by `PgBatcher.next` in this module. */
|
|
3376
3842
|
curRows: boolean = false
|
|
3843
|
+
/** @internal Used by `PgBatcher.emit`, `PgBatcher.next` and `PgBatcher.nextUnsorted` in this module. */
|
|
3377
3844
|
at: i32 = 0
|
|
3378
|
-
/**
|
|
3845
|
+
/**
|
|
3846
|
+
* The key whose `PG_BATCH_ROW` events are owed for the connection's current row; -1 for none.
|
|
3847
|
+
* @internal Used by `PgBatcher.quietRun`, `PgBatcher.row`, `PgBatcher.next` and `PgBatcher.nextUnsorted` in this module.
|
|
3848
|
+
*/
|
|
3379
3849
|
target: i32 = -1
|
|
3380
|
-
/**
|
|
3850
|
+
/**
|
|
3851
|
+
* The handle `take` gave for the run's execution, and how many takes it has had, mod `PG_BATCH_USES`.
|
|
3852
|
+
* @internal Used by `PgBatcher.take` and `PgBatcher.run` in this module.
|
|
3853
|
+
*/
|
|
3381
3854
|
handle: i32 = -1
|
|
3855
|
+
/** @internal Used by `PgBatcher.take` in this module. */
|
|
3382
3856
|
uses: i32 = 0
|
|
3857
|
+
/** @internal Used by `PgBatcher.take`, `PgBatcher.run`, `PgBatcher.next` and `PgBatcher.nextUnsorted` in this module. */
|
|
3383
3858
|
open: boolean = false
|
|
3859
|
+
/** @internal Used by `PgBatcher.quietRun`, `PgBatcher.end`, `PgBatcher.fail`, `PgBatcher.next` and `PgBatcher.nextUnsorted` in this module. */
|
|
3384
3860
|
ended: boolean = false
|
|
3861
|
+
/** @internal Used by `PgBatcher.row`, `PgBatcher.fail`, `PgBatcher.next` and `PgBatcher.nextUnsorted` in this module. */
|
|
3385
3862
|
failed: boolean = false
|
|
3386
3863
|
|
|
3387
3864
|
constructor() {
|
|
@@ -3390,7 +3867,10 @@ class PgBatchRun {
|
|
|
3390
3867
|
this.had = []
|
|
3391
3868
|
}
|
|
3392
3869
|
|
|
3393
|
-
/**
|
|
3870
|
+
/**
|
|
3871
|
+
* Opens the run for `keys` keys, none of whose rows have been read.
|
|
3872
|
+
* @internal Used by `PgBatcher.take` in this module.
|
|
3873
|
+
*/
|
|
3394
3874
|
reset(keys: i32): void {
|
|
3395
3875
|
this.open = true
|
|
3396
3876
|
this.keys = keys
|
|
@@ -3407,39 +3887,41 @@ class PgBatchRun {
|
|
|
3407
3887
|
}
|
|
3408
3888
|
|
|
3409
3889
|
/**
|
|
3410
|
-
* Batches keyed reads of one statement shape, sans-IO like `PgConnection`:
|
|
3411
|
-
*
|
|
3412
|
-
*
|
|
3413
|
-
* `take(conn)` binds up to `maxRequests` of them, and up to `maxBytes` of
|
|
3414
|
-
*
|
|
3415
|
-
*
|
|
3416
|
-
*
|
|
3417
|
-
*
|
|
3418
|
-
* `row(run, conn)`, its `PG_COMPLETE`
|
|
3419
|
-
* connection to `fail(run)`; after each,
|
|
3420
|
-
* `PG_BATCH_NONE`, `tag` naming the request
|
|
3421
|
-
* every request for its key, and every request
|
|
3422
|
-
* `PG_BATCH_DONE`, `PG_BATCH_MISSING` or
|
|
3423
|
-
*
|
|
3424
|
-
*
|
|
3425
|
-
*
|
|
3426
|
-
*
|
|
3427
|
-
*
|
|
3428
|
-
*
|
|
3429
|
-
*
|
|
3890
|
+
* Batches keyed reads of one statement shape, sans-IO like `PgConnection`: it
|
|
3891
|
+
* reads no clock and makes no socket. Each request is a key and the caller's
|
|
3892
|
+
* `tag`, queued by `addInt` or `addText`. When a connection is free,
|
|
3893
|
+
* `take(conn)` binds up to `maxRequests` of them, and up to `maxBytes` of keys,
|
|
3894
|
+
* as one execution of `sql`, each distinct key once (a key whose probe of the
|
|
3895
|
+
* batcher's table passes 1024 slots, which takes keys chosen to collide, is
|
|
3896
|
+
* bound again and answered the same), and answers the execution's run handle.
|
|
3897
|
+
*
|
|
3898
|
+
* Each `PG_ROW` of that execution goes to `row(run, conn)`, its `PG_COMPLETE`
|
|
3899
|
+
* to `end(run)`, and an error or a lost connection to `fail(run)`; after each,
|
|
3900
|
+
* `next(run)` answers events until `PG_BATCH_NONE`, `tag` naming the request
|
|
3901
|
+
* each is about. Every row goes to every request for its key, and every request
|
|
3902
|
+
* gets one last event: `PG_BATCH_DONE`, `PG_BATCH_MISSING` or
|
|
3903
|
+
* `PG_BATCH_FAILED`.
|
|
3904
|
+
*
|
|
3905
|
+
* Sorted (the default), rows come in key order and a key's last events come as
|
|
3906
|
+
* soon as a later key's row does; with `sorted` false, rows come in any order,
|
|
3907
|
+
* each answered at once, and every last event waits for `end` or `fail`, then
|
|
3908
|
+
* comes in key order. A batch with `binary` set comes in binary format: its
|
|
3909
|
+
* rows are read with the binary decoders, `binaryInt` for each ordinal, and the
|
|
3910
|
+
* caller's `binary.failed` is left as it was.
|
|
3430
3911
|
*
|
|
3431
|
-
* Nothing outlives its execution: a run is free again once the events
|
|
3432
|
-
* `
|
|
3433
|
-
*
|
|
3434
|
-
*
|
|
3435
|
-
*
|
|
3436
|
-
*
|
|
3437
|
-
*
|
|
3438
|
-
*
|
|
3439
|
-
*
|
|
3440
|
-
* or
|
|
3441
|
-
*
|
|
3442
|
-
*
|
|
3912
|
+
* Nothing outlives its execution: a run is free again once the events `end` or
|
|
3913
|
+
* `fail` owe are answered, and its handle is then spent. What the server or the
|
|
3914
|
+
* network can send after that — a second `PG_COMPLETE`, a row or an error after
|
|
3915
|
+
* one, a lost connection — goes to a spent handle, and `row`, `end` and `fail`
|
|
3916
|
+
* count it in `stray` and do nothing, even once `take` has given the run out
|
|
3917
|
+
* again under a new handle. The ordinal each row carries comes from the server
|
|
3918
|
+
* and is checked before it routes anything.
|
|
3919
|
+
*
|
|
3920
|
+
* What panics is only the program's own misuse: a handle out of the range
|
|
3921
|
+
* `take` can give (-1 or any negative, or `runs` * 2^20 or more), or `row`,
|
|
3922
|
+
* `end` or `fail` before `next(run)` has answered `PG_BATCH_NONE` for the event
|
|
3923
|
+
* before. A handle in that range that `take` never gave is spent like any
|
|
3924
|
+
* other: counted in `stray`, not a panic.
|
|
3443
3925
|
*/
|
|
3444
3926
|
export class PgBatcher {
|
|
3445
3927
|
/** The prepared statement's name. */
|
|
@@ -3471,7 +3953,10 @@ export class PgBatcher {
|
|
|
3471
3953
|
refused: i32 = 0
|
|
3472
3954
|
/** The number of `row`, `end` and `fail` calls on a spent handle, each ignored, stopping at 2^31 - 1. */
|
|
3473
3955
|
stray: i32 = 0
|
|
3474
|
-
/**
|
|
3956
|
+
/**
|
|
3957
|
+
* The most requests one execution takes, from `PgBatchConfig.maxRequests`.
|
|
3958
|
+
* @internal Used by `PgCarrier.routeBatch` in std/net/postgres-carrier.ts.
|
|
3959
|
+
*/
|
|
3475
3960
|
readonly maxRequests: i32
|
|
3476
3961
|
private readonly keyType: i32
|
|
3477
3962
|
private readonly maxBytes: i32
|
|
@@ -3481,7 +3966,14 @@ export class PgBatcher {
|
|
|
3481
3966
|
private head: i32 = 0
|
|
3482
3967
|
private count: i32 = 0
|
|
3483
3968
|
|
|
3484
|
-
/**
|
|
3969
|
+
/**
|
|
3970
|
+
* A batcher for `config`; panics when a name or query is empty or holds a NUL, or a cap is out
|
|
3971
|
+
* of range.
|
|
3972
|
+
*
|
|
3973
|
+
* @param config The statement shape and caps, read once here: later changes to it do nothing.
|
|
3974
|
+
* `maxRequests` is 1 to 65536, `maxBytes` at least 22, `queueSize` 1 to 2^20, `runs` 1 to
|
|
3975
|
+
* 1024, and `queueBytes` at least 0 (a text batcher with 0 can queue only empty keys).
|
|
3976
|
+
*/
|
|
3485
3977
|
constructor(config: PgBatchConfig) {
|
|
3486
3978
|
const keyType: i32 = config.keyType
|
|
3487
3979
|
if (keyType !== PG_BATCH_INT && keyType !== PG_BATCH_TEXT) {
|
|
@@ -3547,15 +4039,21 @@ export class PgBatcher {
|
|
|
3547
4039
|
}
|
|
3548
4040
|
}
|
|
3549
4041
|
|
|
3550
|
-
/**
|
|
4042
|
+
/**
|
|
4043
|
+
* How many requests wait for `take`.
|
|
4044
|
+
*
|
|
4045
|
+
* @returns The requests queued and not yet taken into a batch.
|
|
4046
|
+
*/
|
|
3551
4047
|
waiting(): i32 {
|
|
3552
4048
|
return this.count
|
|
3553
4049
|
}
|
|
3554
4050
|
|
|
3555
4051
|
/**
|
|
3556
|
-
* Drops the oldest waiting request
|
|
3557
|
-
*
|
|
3558
|
-
*
|
|
4052
|
+
* Drops the oldest waiting request, so that a carrier that cannot reach the
|
|
4053
|
+
* server fails its requests rather than holds them.
|
|
4054
|
+
*
|
|
4055
|
+
* @returns The dropped request's tag, or -1 when none waits.
|
|
4056
|
+
* @internal Used by `PgCarrier.next` in std/net/postgres-carrier.ts.
|
|
3559
4057
|
*/
|
|
3560
4058
|
shed(): i32 {
|
|
3561
4059
|
if (this.count === 0) {
|
|
@@ -3570,7 +4068,15 @@ export class PgBatcher {
|
|
|
3570
4068
|
return tag
|
|
3571
4069
|
}
|
|
3572
4070
|
|
|
3573
|
-
/**
|
|
4071
|
+
/**
|
|
4072
|
+
* Queues a request for the int8 `key`; false when `queueSize` are waiting. Panics on a text
|
|
4073
|
+
* batcher.
|
|
4074
|
+
*
|
|
4075
|
+
* @param key The key the statement's `q.key` is bound to.
|
|
4076
|
+
* @param tag The caller's own number for the request, which `tag` holds when `next(run)`
|
|
4077
|
+
* answers an event about it; best not -1, which `tag` holds for none.
|
|
4078
|
+
* @returns True when the request was queued.
|
|
4079
|
+
*/
|
|
3574
4080
|
addInt(key: i64, tag: i32): boolean {
|
|
3575
4081
|
if (this.keyType !== PG_BATCH_INT) {
|
|
3576
4082
|
panic("nish/net/postgres: PgBatcher.addInt on a text batcher")
|
|
@@ -3591,6 +4097,14 @@ export class PgBatcher {
|
|
|
3591
4097
|
* the key would not fit in `queueBytes` beside those waiting, or it is too
|
|
3592
4098
|
* long for one execution's `maxBytes`. Panics on an int8 batcher, or when
|
|
3593
4099
|
* the window is not inside `bytes`.
|
|
4100
|
+
*
|
|
4101
|
+
* @param bytes The buffer holding the key; only the window is read, and the caller may reuse
|
|
4102
|
+
* the buffer as soon as the call returns.
|
|
4103
|
+
* @param start The index of the key's first byte in `bytes`.
|
|
4104
|
+
* @param length The key's length in bytes, 0 for the empty key.
|
|
4105
|
+
* @param tag The caller's own number for the request, which `tag` holds when `next(run)`
|
|
4106
|
+
* answers an event about it; best not -1, which `tag` holds for none.
|
|
4107
|
+
* @returns True when the request was queued.
|
|
3594
4108
|
*/
|
|
3595
4109
|
addText(bytes: u8[], start: i32, length: i32, tag: i32): boolean {
|
|
3596
4110
|
if (this.keyType !== PG_BATCH_TEXT) {
|
|
@@ -3684,6 +4198,12 @@ export class PgBatcher {
|
|
|
3684
4198
|
* answers -1. The program calls `clock.arrived(now)` for each request it
|
|
3685
4199
|
* adds. Panics when the clock's waiting count is not this batcher's, or its
|
|
3686
4200
|
* `maxCount` is below `maxRequests`.
|
|
4201
|
+
*
|
|
4202
|
+
* @param conn The free connection to bind the batch on, as `take` takes it.
|
|
4203
|
+
* @param clock The clock that mirrors this batcher's queue, one `arrived` per request added.
|
|
4204
|
+
* @param nowUs The time now, in the clock's microseconds.
|
|
4205
|
+
* @param inFlight The program's executions or groups still running, for the idle bypass.
|
|
4206
|
+
* @returns The run handle `take` answered, or -1 when no batch was taken.
|
|
3687
4207
|
*/
|
|
3688
4208
|
takeDue(conn: PgConnection, clock: PgBatchClock, nowUs: i64, inFlight: i32): i32 {
|
|
3689
4209
|
if (clock.waiting() !== this.count || clock.maxCount < this.maxRequests) {
|
|
@@ -3709,6 +4229,10 @@ export class PgBatcher {
|
|
|
3709
4229
|
* the connection's `maxOutput`; those not taken stay queued. -1, and
|
|
3710
4230
|
* nothing written, when none waits, every run is in flight, or `conn`
|
|
3711
4231
|
* refused the bind or the first key.
|
|
4232
|
+
*
|
|
4233
|
+
* @param conn A connection with no bind open, on which `sql` has been prepared under `name`.
|
|
4234
|
+
* @returns The run handle, from 0 to `runs` * 2^20 - 1, to pass to `row`, `end`, `fail` and
|
|
4235
|
+
* `next` for this execution's events; or -1.
|
|
3712
4236
|
*/
|
|
3713
4237
|
take(conn: PgConnection): i32 {
|
|
3714
4238
|
if (this.count === 0) {
|
|
@@ -3892,6 +4416,10 @@ export class PgBatcher {
|
|
|
3892
4416
|
* one before the key the last row was for): that counts in `refused` and
|
|
3893
4417
|
* fails the run; and on a spent handle, which counts in `stray`. Panics on a handle
|
|
3894
4418
|
* `take` cannot give, or when the run's events are not all answered.
|
|
4419
|
+
*
|
|
4420
|
+
* @param r The run handle `take` answered for the execution the row belongs to.
|
|
4421
|
+
* @param conn The connection whose `next()` has just answered `PG_ROW` for that execution.
|
|
4422
|
+
* @returns True when the row was routed, and `next(r)` answers its `PG_BATCH_ROW` events.
|
|
3895
4423
|
*/
|
|
3896
4424
|
row(r: i32, conn: PgConnection): boolean {
|
|
3897
4425
|
const run: PgBatchRun | null = this.quietRun(r, "row")
|
|
@@ -3935,7 +4463,12 @@ export class PgBatcher {
|
|
|
3935
4463
|
return true
|
|
3936
4464
|
}
|
|
3937
4465
|
|
|
3938
|
-
/**
|
|
4466
|
+
/**
|
|
4467
|
+
* Ends run `r`'s execution, on its `PG_COMPLETE`: `next(r)` then closes every request left.
|
|
4468
|
+
* Ignores a spent handle, and panics, as `row` does.
|
|
4469
|
+
*
|
|
4470
|
+
* @param r The run handle `take` answered for the execution.
|
|
4471
|
+
*/
|
|
3939
4472
|
end(r: i32): void {
|
|
3940
4473
|
const run: PgBatchRun | null = this.quietRun(r, "end")
|
|
3941
4474
|
if (run !== null) {
|
|
@@ -3943,7 +4476,12 @@ export class PgBatcher {
|
|
|
3943
4476
|
}
|
|
3944
4477
|
}
|
|
3945
4478
|
|
|
3946
|
-
/**
|
|
4479
|
+
/**
|
|
4480
|
+
* Fails run `r`'s execution, on its `PG_ERROR` or `PG_LOST`: `next(r)` then answers
|
|
4481
|
+
* `PG_BATCH_FAILED` for every request left. Ignores a spent handle, and panics, as `row` does.
|
|
4482
|
+
*
|
|
4483
|
+
* @param r The run handle `take` answered for the execution.
|
|
4484
|
+
*/
|
|
3947
4485
|
fail(r: i32): void {
|
|
3948
4486
|
const run: PgBatchRun | null = this.quietRun(r, "fail")
|
|
3949
4487
|
if (run !== null) {
|
|
@@ -3969,6 +4507,9 @@ export class PgBatcher {
|
|
|
3969
4507
|
* Once `end` or `fail` has had all its events the run is over, free for
|
|
3970
4508
|
* `take` again, and its handle spent: `PG_BATCH_NONE` ever after. Panics
|
|
3971
4509
|
* on a handle `take` cannot give.
|
|
4510
|
+
*
|
|
4511
|
+
* @param r The run handle `take` answered for the execution.
|
|
4512
|
+
* @returns A `PG_BATCH_*` event: call again until it is `PG_BATCH_NONE`.
|
|
3972
4513
|
*/
|
|
3973
4514
|
next(r: i32): i32 {
|
|
3974
4515
|
const found: PgBatchRun | null = this.run(r)
|
|
@@ -4120,6 +4661,7 @@ export class PgBatchClock {
|
|
|
4120
4661
|
lastReason: i32 = 0
|
|
4121
4662
|
/** How long the oldest item of the last batch waited, in microseconds. */
|
|
4122
4663
|
lastWaitUs: i64 = 0
|
|
4664
|
+
/** @internal Used by `PgBatcher.takeDue` in this module. */
|
|
4123
4665
|
readonly maxCount: i32
|
|
4124
4666
|
private readonly minCount: i32
|
|
4125
4667
|
private readonly factor: f64
|
|
@@ -4138,7 +4680,12 @@ export class PgBatchClock {
|
|
|
4138
4680
|
private last: i64 = 0
|
|
4139
4681
|
private due: i32 = 0
|
|
4140
4682
|
|
|
4141
|
-
/**
|
|
4683
|
+
/**
|
|
4684
|
+
* A clock for `config`; panics when a setting is out of the range its field names, or
|
|
4685
|
+
* `minCount` is above `maxCount`.
|
|
4686
|
+
*
|
|
4687
|
+
* @param config The settings, read once here: later changes to it do nothing.
|
|
4688
|
+
*/
|
|
4142
4689
|
constructor(config: PgBatchClockConfig) {
|
|
4143
4690
|
const factor: f64 = config.factor
|
|
4144
4691
|
const weight: f64 = config.weight
|
|
@@ -4171,7 +4718,11 @@ export class PgBatchClock {
|
|
|
4171
4718
|
this.starts = new Array<i64>(5)
|
|
4172
4719
|
}
|
|
4173
4720
|
|
|
4174
|
-
/**
|
|
4721
|
+
/**
|
|
4722
|
+
* How many items wait for a batch.
|
|
4723
|
+
*
|
|
4724
|
+
* @returns The items queued and not yet started in a batch.
|
|
4725
|
+
*/
|
|
4175
4726
|
waiting(): i32 {
|
|
4176
4727
|
return this.count
|
|
4177
4728
|
}
|
|
@@ -4180,6 +4731,9 @@ export class PgBatchClock {
|
|
|
4180
4731
|
* Records an item queued at `nowUs`; false when `queueSize` are waiting. A
|
|
4181
4732
|
* time before the last one given counts as the last one, so a clock that
|
|
4182
4733
|
* steps back cannot make an item older than its neighbours.
|
|
4734
|
+
*
|
|
4735
|
+
* @param nowUs The time the item was queued, in microseconds from the program's fixed point.
|
|
4736
|
+
* @returns True when the item was recorded.
|
|
4183
4737
|
*/
|
|
4184
4738
|
arrived(nowUs: i64): boolean {
|
|
4185
4739
|
const ring: i32 = toI32(this.times.length)
|
|
@@ -4201,7 +4755,11 @@ export class PgBatchClock {
|
|
|
4201
4755
|
return true
|
|
4202
4756
|
}
|
|
4203
4757
|
|
|
4204
|
-
/**
|
|
4758
|
+
/**
|
|
4759
|
+
* The count that starts a batch now.
|
|
4760
|
+
*
|
|
4761
|
+
* @returns The larger of `minCount` and the average times `factor`, at most `maxCount`.
|
|
4762
|
+
*/
|
|
4205
4763
|
target(): i32 {
|
|
4206
4764
|
const scaled: f64 = Math.ceil(this.average * this.factor)
|
|
4207
4765
|
let target: i32 = this.minCount
|
|
@@ -4215,6 +4773,12 @@ export class PgBatchClock {
|
|
|
4215
4773
|
* The reason a batch should start at `nowUs`, with `inFlight` batches (or
|
|
4216
4774
|
* groups) still running, or `PG_CLOCK_WAIT`. It only says; the program
|
|
4217
4775
|
* starts the batch when a connection is free, then calls `started`.
|
|
4776
|
+
*
|
|
4777
|
+
* @param nowUs The time now, in the clock's microseconds.
|
|
4778
|
+
* @param inFlight The batches or groups still running; 0 or less lets the idle bypass fire.
|
|
4779
|
+
* @returns `PG_CLOCK_COUNT`, `PG_CLOCK_AVERAGE`, `PG_CLOCK_TIMER`, `PG_CLOCK_IDLE`, or
|
|
4780
|
+
* `PG_CLOCK_WAIT`, always `PG_CLOCK_WAIT` when nothing waits. The next `started` records it
|
|
4781
|
+
* as `lastReason`.
|
|
4218
4782
|
*/
|
|
4219
4783
|
check(nowUs: i64, inFlight: i32): i32 {
|
|
4220
4784
|
let reason: i32 = PG_CLOCK_WAIT
|
|
@@ -4232,7 +4796,11 @@ export class PgBatchClock {
|
|
|
4232
4796
|
return reason
|
|
4233
4797
|
}
|
|
4234
4798
|
|
|
4235
|
-
/**
|
|
4799
|
+
/**
|
|
4800
|
+
* When the oldest waiting item will have waited `maxWaitUs`.
|
|
4801
|
+
*
|
|
4802
|
+
* @returns That time in the caller's microseconds, or -1 when none waits.
|
|
4803
|
+
*/
|
|
4236
4804
|
deadline(): i64 {
|
|
4237
4805
|
if (this.count === 0) {
|
|
4238
4806
|
return -1
|
|
@@ -4244,6 +4812,10 @@ export class PgBatchClock {
|
|
|
4244
4812
|
* Records a batch of the `size` oldest items started at `nowUs`, and moves
|
|
4245
4813
|
* the average toward it; the first batch sets it. Panics when `size` is
|
|
4246
4814
|
* below 1 or more than are waiting or than `maxCount`.
|
|
4815
|
+
*
|
|
4816
|
+
* @param size The number of items the batch took, oldest first.
|
|
4817
|
+
* @param nowUs The time the batch started, in the clock's microseconds; `lastWaitUs` is
|
|
4818
|
+
* measured to it, and is 0 when it is before the oldest item's arrival.
|
|
4247
4819
|
*/
|
|
4248
4820
|
started(size: i32, nowUs: i64): void {
|
|
4249
4821
|
if (size < 1 || size > this.count || size > this.maxCount) {
|
|
@@ -4263,7 +4835,13 @@ export class PgBatchClock {
|
|
|
4263
4835
|
this.due = PG_CLOCK_WAIT
|
|
4264
4836
|
}
|
|
4265
4837
|
|
|
4266
|
-
/**
|
|
4838
|
+
/**
|
|
4839
|
+
* How many batches have started for `reason`, one of the `PG_CLOCK_*` (`PG_CLOCK_WAIT` counts
|
|
4840
|
+
* those started without a due `check`). Panics on any other `reason`.
|
|
4841
|
+
*
|
|
4842
|
+
* @param reason `PG_CLOCK_WAIT` to `PG_CLOCK_IDLE`.
|
|
4843
|
+
* @returns The count since the clock was made.
|
|
4844
|
+
*/
|
|
4267
4845
|
startsFor(reason: i32): i64 {
|
|
4268
4846
|
if (reason < 0 || reason > PG_CLOCK_IDLE) {
|
|
4269
4847
|
panic("nish/net/postgres: PgBatchClock.startsFor with a reason out of range")
|
|
@@ -4312,12 +4890,18 @@ export class PgBatchTurns {
|
|
|
4312
4890
|
/** The clock the turns read and record into. */
|
|
4313
4891
|
readonly clock: PgBatchClock
|
|
4314
4892
|
/** The number of slots. */
|
|
4315
|
-
readonly size: i32
|
|
4893
|
+
private readonly size: i32
|
|
4316
4894
|
private readonly busy: boolean[]
|
|
4317
4895
|
private running: i32 = 0
|
|
4318
4896
|
private woken: i32 = -1
|
|
4319
4897
|
|
|
4320
|
-
/**
|
|
4898
|
+
/**
|
|
4899
|
+
* Turns over `size` slots (1 to 1024), all free; panics on a size out of range.
|
|
4900
|
+
*
|
|
4901
|
+
* @param clock The clock the program's batches are formed by; kept. `push` and `started`
|
|
4902
|
+
* record into it, so the program does not call its `arrived` or `started` itself.
|
|
4903
|
+
* @param size The number of connections, numbered 0 to `size - 1`.
|
|
4904
|
+
*/
|
|
4321
4905
|
constructor(clock: PgBatchClock, size: i32) {
|
|
4322
4906
|
if (size < 1 || size > PG_POOL_MAX_SLOTS) {
|
|
4323
4907
|
panic("nish/net/postgres: a PgBatchTurns size out of range")
|
|
@@ -4327,7 +4911,11 @@ export class PgBatchTurns {
|
|
|
4327
4911
|
this.busy = new Array<boolean>(size)
|
|
4328
4912
|
}
|
|
4329
4913
|
|
|
4330
|
-
/**
|
|
4914
|
+
/**
|
|
4915
|
+
* The slot that collects the next batch.
|
|
4916
|
+
*
|
|
4917
|
+
* @returns The lowest-numbered free slot, or `PG_TURNS_NONE` when every slot holds a batch.
|
|
4918
|
+
*/
|
|
4331
4919
|
collector(): i32 {
|
|
4332
4920
|
for (let i: i32 = 0; i < this.size; i++) {
|
|
4333
4921
|
if (!this.busy[i]) {
|
|
@@ -4337,17 +4925,31 @@ export class PgBatchTurns {
|
|
|
4337
4925
|
return PG_TURNS_NONE
|
|
4338
4926
|
}
|
|
4339
4927
|
|
|
4340
|
-
/**
|
|
4928
|
+
/**
|
|
4929
|
+
* How many slots hold a batch.
|
|
4930
|
+
*
|
|
4931
|
+
* @returns The slots whose batch has `started` and not yet `finished`.
|
|
4932
|
+
*/
|
|
4341
4933
|
inFlight(): i32 {
|
|
4342
4934
|
return this.running
|
|
4343
4935
|
}
|
|
4344
4936
|
|
|
4345
|
-
/**
|
|
4937
|
+
/**
|
|
4938
|
+
* When the collector's timer fires, as `PgBatchClock.deadline()` gives it.
|
|
4939
|
+
*
|
|
4940
|
+
* @returns That time in the caller's microseconds, or -1 when nothing waits.
|
|
4941
|
+
*/
|
|
4346
4942
|
deadline(): i64 {
|
|
4347
4943
|
return this.clock.deadline()
|
|
4348
4944
|
}
|
|
4349
4945
|
|
|
4350
|
-
/**
|
|
4946
|
+
/**
|
|
4947
|
+
* Records an item queued at `nowUs` and answers the slot to wake, or `PG_TURNS_FULL` when the
|
|
4948
|
+
* clock is full.
|
|
4949
|
+
*
|
|
4950
|
+
* @param nowUs The time the item was queued, in the clock's microseconds.
|
|
4951
|
+
* @returns The slot to wake, `PG_TURNS_NONE` when none is to be woken, or `PG_TURNS_FULL`.
|
|
4952
|
+
*/
|
|
4351
4953
|
push(nowUs: i64): i32 {
|
|
4352
4954
|
if (!this.clock.arrived(nowUs)) {
|
|
4353
4955
|
return PG_TURNS_FULL
|
|
@@ -4355,7 +4957,12 @@ export class PgBatchTurns {
|
|
|
4355
4957
|
return this.poll(nowUs)
|
|
4356
4958
|
}
|
|
4357
4959
|
|
|
4358
|
-
/**
|
|
4960
|
+
/**
|
|
4961
|
+
* The slot to wake at `nowUs`, when a batch is due and no slot is named already.
|
|
4962
|
+
*
|
|
4963
|
+
* @param nowUs The time now, in the clock's microseconds; call at `deadline()`.
|
|
4964
|
+
* @returns The collector's slot, or `PG_TURNS_NONE`.
|
|
4965
|
+
*/
|
|
4359
4966
|
poll(nowUs: i64): i32 {
|
|
4360
4967
|
if (this.woken >= 0) {
|
|
4361
4968
|
return PG_TURNS_NONE
|
|
@@ -4368,7 +4975,17 @@ export class PgBatchTurns {
|
|
|
4368
4975
|
return slot
|
|
4369
4976
|
}
|
|
4370
4977
|
|
|
4371
|
-
/**
|
|
4978
|
+
/**
|
|
4979
|
+
* Records `slot` starting a batch of `size` items at `nowUs`, and answers the next slot to
|
|
4980
|
+
* wake. Panics on a slot out of range or holding a batch already, or as
|
|
4981
|
+
* `PgBatchClock.started`.
|
|
4982
|
+
*
|
|
4983
|
+
* @param slot The slot that took the batch, from 0 to `size - 1`; it holds the batch until
|
|
4984
|
+
* `finished`.
|
|
4985
|
+
* @param size The number of items the batch took.
|
|
4986
|
+
* @param nowUs The time the batch started, in the clock's microseconds.
|
|
4987
|
+
* @returns The slot to wake, or `PG_TURNS_NONE`.
|
|
4988
|
+
*/
|
|
4372
4989
|
started(slot: i32, size: i32, nowUs: i64): i32 {
|
|
4373
4990
|
this.free(slot)
|
|
4374
4991
|
this.clock.started(size, nowUs)
|
|
@@ -4380,7 +4997,14 @@ export class PgBatchTurns {
|
|
|
4380
4997
|
return this.poll(nowUs)
|
|
4381
4998
|
}
|
|
4382
4999
|
|
|
4383
|
-
/**
|
|
5000
|
+
/**
|
|
5001
|
+
* Records `slot`'s batch done at `nowUs`, and answers the slot to wake. Panics on a slot out
|
|
5002
|
+
* of range or holding no batch.
|
|
5003
|
+
*
|
|
5004
|
+
* @param slot The slot whose batch is done, from 0 to `size - 1`.
|
|
5005
|
+
* @param nowUs The time now, in the clock's microseconds.
|
|
5006
|
+
* @returns The slot to wake, or `PG_TURNS_NONE`.
|
|
5007
|
+
*/
|
|
4384
5008
|
finished(slot: i32, nowUs: i64): i32 {
|
|
4385
5009
|
if (slot < 0 || slot >= this.size || !this.busy[slot]) {
|
|
4386
5010
|
panic("nish/net/postgres: PgBatchTurns.finished on a slot holding no batch")
|
|
@@ -4390,7 +5014,12 @@ export class PgBatchTurns {
|
|
|
4390
5014
|
return this.poll(nowUs)
|
|
4391
5015
|
}
|
|
4392
5016
|
|
|
4393
|
-
/**
|
|
5017
|
+
/**
|
|
5018
|
+
* Gives back a wake that started nothing, so the next push or poll can wake a slot again.
|
|
5019
|
+
* Panics on a slot out of range or holding a batch.
|
|
5020
|
+
*
|
|
5021
|
+
* @param slot The slot that was woken and took no batch.
|
|
5022
|
+
*/
|
|
4394
5023
|
release(slot: i32): void {
|
|
4395
5024
|
this.free(slot)
|
|
4396
5025
|
if (this.woken === slot) {
|
|
@@ -4462,6 +5091,11 @@ const pgTargetFailed = (failure: i32): PgTarget => {
|
|
|
4462
5091
|
* empty host, a `,` (more than one host) or a NUL byte is refused, and so is
|
|
4463
5092
|
* a socket path over 107 bytes (an `@` name over 107 after its `@`), never
|
|
4464
5093
|
* cut short.
|
|
5094
|
+
*
|
|
5095
|
+
* @param host The host, a socket directory starting with `/`, or an abstract name starting
|
|
5096
|
+
* with `@`; taken as it is, not percent-decoded.
|
|
5097
|
+
* @param port The TCP port, or the number in the socket's name, from 1 to 65535.
|
|
5098
|
+
* @returns The target; read `failure` before anything else.
|
|
4465
5099
|
*/
|
|
4466
5100
|
export const pgTarget = (host: string, port: i32): PgTarget => {
|
|
4467
5101
|
if (port < 1 || port > 65535) {
|
|
@@ -4519,20 +5153,24 @@ const pgPortValue = (text: string): i32 => {
|
|
|
4519
5153
|
}
|
|
4520
5154
|
|
|
4521
5155
|
/**
|
|
4522
|
-
* The target a `postgres://` or `postgresql://` URL names, as libpq reads
|
|
4523
|
-
*
|
|
4524
|
-
*
|
|
4525
|
-
*
|
|
4526
|
-
*
|
|
4527
|
-
*
|
|
4528
|
-
*
|
|
4529
|
-
*
|
|
5156
|
+
* The target a `postgres://` or `postgresql://` URL names, as libpq reads one:
|
|
5157
|
+
* `postgres://[user[:password]@][host][:port][/dbname][?key=value&...]`. The
|
|
5158
|
+
* host, the port and every query key and value are percent-decoded, so a socket
|
|
5159
|
+
* directory is written `%2Ftmp` or passed as `?host=/tmp`; a `host` or `port`
|
|
5160
|
+
* in the query overrides the authority's, and other keys are ignored. The user,
|
|
5161
|
+
* password and database are not read here, but a bad escape in them still
|
|
5162
|
+
* refuses the URL. A `%` without two hex digits after it, `%00`, or a part that
|
|
5163
|
+
* decodes to bytes that are not UTF-8 is `PG_TARGET_BAD_ESCAPE`.
|
|
5164
|
+
*
|
|
4530
5165
|
* The user information ends at the first `@`, as in libpq; a raw `@` after a
|
|
4531
|
-
* `?` or after that first `@` in the authority, or a raw NUL byte anywhere,
|
|
4532
|
-
*
|
|
4533
|
-
*
|
|
4534
|
-
*
|
|
4535
|
-
*
|
|
5166
|
+
* `?` or after that first `@` in the authority, or a raw NUL byte anywhere, is
|
|
5167
|
+
* `PG_TARGET_BAD_HOST`, as is a URL with no host anywhere, where libpq would
|
|
5168
|
+
* use its default socket directory. An empty port or query value is refused,
|
|
5169
|
+
* where libpq would take it as unset. The decoded host is then resolved as
|
|
5170
|
+
* `pgTarget` resolves one.
|
|
5171
|
+
*
|
|
5172
|
+
* @param url The URL; any user or password it holds is not kept in the target.
|
|
5173
|
+
* @returns The target; read `failure` before anything else.
|
|
4536
5174
|
*/
|
|
4537
5175
|
export const pgTargetUrl = (url: string): PgTarget => {
|
|
4538
5176
|
let at: i32 = 0
|