skaidb 1.0.3 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d5792e9877643c116649c834851fc097027b72fd01ab0f40920dd4e99d977a0d
-  data.tar.gz: 6d035367f1b2f97b6f49306ef5ff6b77974a2825e73356740d66237e2577a1d1
+  metadata.gz: 7a9f39f07d8b6d8abb6edf43d48b4c70da568b4a66f62044fb6f36d7b7b0e1ae
+  data.tar.gz: bb205511e213fe77efcfbaff5c17b82c453fcc2135cee1c362e154b9ad169e6f
 SHA512:
-  metadata.gz: e2aec63bcdd3ef8d199d223c7de91343370dceaea32fd626b1cb085606d533c613909d3653e60a662e1874f0293ebc9c6c3633f931d39f1ea569970668867e63
-  data.tar.gz: 3b4e1accd06da21f72da0148e3340bee4eeb1dbe3fbc98c51ce9b0d9891b6075a653c6386258582cadf8b3d49de8f596713e562213bd29c471c78c18865946e5
+  metadata.gz: 9ce5348688c5bd6cd480006b2fa567ed7af74cc0ffe557f387d55705effd49dcbd754b8c52b32a30ae3361234226e4a82828bff7dc0d3d43f9a03e086849c53b
+  data.tar.gz: e7d6fd76c93392bbea0e2583b5741b418188c4d045d0226d7e8d0dcf2828fbe4cd03e34a32da58598d0173d81875cf8b1fe5b405c64e0ac658c108be67adf1da

data/CHANGELOG.md

@@ -4,6 +4,64 @@ All notable changes to the skaidb Ruby driver. The format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); versions follow
 [Semantic Versioning](https://semver.org/).
 
+## [1.2.0] - 2026-10-25
+
+### Added
+- **Pool load balancing across members** (the rules every skaidb driver
+  shares, PROTOCOL.md §6.1): `load_balancing: :round_robin` /
+  `:least_latency` (power of two choices on the round-trip average ×
+  checked-out connections, re-measuring a member not used in the last 2 s;
+  `:random` stays the default), `idle_order: :fifo`, health ejection
+  (consecutive transport failures, or a latency average far above the other
+  members') with a background probe that re-admits the member,
+  `discover: true` (members from `SHOW ENDPOINTS`, server ≥ 0.327: joiners
+  added, leavers dropped, resyncing/unreachable members skipped and
+  re-checked every 5 s), and `read_your_writes: <seconds>` with
+  `checkout(affinity: key)` / `with(affinity: key)` — reads follow the member
+  that took the key's last write. `pool.members` reports each member's
+  state, latency and connections; `logger:` is told of ejections and
+  re-admissions. Options take Symbols or Strings.
+- `Connection#endpoint`: the `"host:port"` of the member a connection reached.
+
+### Changed
+- A pooled connection that re-dials does so in the pool's order (usable
+  members first, the one it lost last) instead of shuffling the seeds.
+- `Skaidb::Pool.new` checks its `Skaidb.connect` keywords when it is created
+  instead of at the first checkout, and a connection checked in to a pool
+  that did not create it is closed instead of kept.
+
+## [1.1.0] - 2026-09-26
+
+### Added
+- Certificate login (wire mechanism EXTERNAL): `auth_mechanism: :certificate`
+  with `tls_client_cert:` / `tls_client_key:` (PEM files). AuthStart carries
+  the optional user, an empty client nonce and mechanism byte 2; the
+  outcome's signature is not verified, since TLS authenticated the server.
+  `user:` is optional under it and, when given, must equal the certificate's
+  Common Name. `Skaidb::AuthMechanism` resolves the option.
+- `tls_client_cert:` / `tls_client_key:` also present a client certificate
+  under SCRAM, for servers that verify client certificates; either turns TLS
+  on, and they must be given together.
+- The shared wire-protocol conformance suite: `conformance/vectors.json` and
+  its contract, vendored byte-identical, run by `test/conformance_test.rb`
+  (values, SCRAM, auth outcomes, every case through the public API; nothing
+  skipped). CI fails when the vendored vectors differ from
+  https://skaidb.org/conformance/vectors.json.
+- `Result#kind` (`:rows`, `:mutation`, `:ddl`, `:stream`): a DDL
+  acknowledgement was indistinguishable from "0 rows affected".
+- `Skaidb.salted_password` and `Skaidb.auth_message`, the SCRAM pieces the
+  handshake uses, so they can be checked against the reference vectors.
+
+### Changed
+- `Connection#stream` with a block returns a `Result` instead of `nil`. Found
+  by the conformance suite: a stream with no rows had no way to report its
+  column names, and a non-row statement sent over the streaming opcode
+  dropped its affected-row count. A row stream now returns `kind: :stream`
+  with the column names in `fields`; a non-row statement returns its
+  `:mutation` (with `cmd_tuples`) or `:ddl` Result.
+- `Skaidb.connect`'s `user:` defaults to `nil`, which still means
+  `"anonymous"` under SCRAM and an empty user under certificate login.
+
 ## [1.0.3] - 2026-09-20
 
 Release automation: published from GitHub Actions. No code change.
@@ -116,6 +174,8 @@ batches, a 2 500-row stream, error handling, and the `drivers` table showing
   because it is a bundled gem since Ruby 3.4.
 - The example moved to `examples/basic.rb`.
 
+[1.2.0]: https://github.com/porcupin26/skaidb-ruby/compare/v1.1.0...v1.2.0
+[1.1.0]: https://github.com/porcupin26/skaidb-ruby/compare/v1.0.3...v1.1.0
 [1.0.3]: https://github.com/porcupin26/skaidb-ruby/compare/v1.0.2...v1.0.3
 [1.0.2]: https://github.com/porcupin26/skaidb-ruby/compare/v1.0.1...v1.0.2
 [1.0.1]: https://github.com/porcupin26/skaidb-ruby/compare/v1.0.0...v1.0.1

data/README.md

@@ -13,7 +13,8 @@ and the result behaves like `PG::Result`. **Pure standard library** (`socket`,
 Ruby 2.7 through 3.4. It speaks skaidb's binary protocol directly:
 SCRAM-SHA-256 authentication, server-side prepared statements with typed
 parameters, one-round-trip batches, streamed result sets, multi-seed failover,
-transparent reconnect, TLS and connection pooling.
+transparent reconnect, TLS and a connection pool that balances across the
+cluster's members.
 
 - Repository: <https://github.com/porcupin26/skaidb-ruby>
 - RubyGems: <https://rubygems.org/gems/skaidb>
@@ -54,13 +55,13 @@ Xcode command-line tools on macOS). `gem install skaidb` and vendoring reuse
 the `bigdecimal` already installed.
 
 Or vendor the single file: copy
-[`lib/skaidb.rb`](https://github.com/porcupin26/skaidb-ruby/blob/v1.0.3/lib/skaidb.rb)
+[`lib/skaidb.rb`](https://github.com/porcupin26/skaidb-ruby/blob/v1.2.0/lib/skaidb.rb)
 into your project and `require_relative` it. It has no dependencies beyond
 Ruby's standard library.
 
 Every release is also attached as a `.gem` to its
 [GitHub release](https://github.com/porcupin26/skaidb-ruby/releases) for
-installs without registry access: `gem install ./skaidb-1.0.3.gem`.
+installs without registry access: `gem install ./skaidb-1.2.0.gem`.
 
 ## Quick start
 
@@ -98,7 +99,8 @@ end
   prepared statements, `exec_batch`
 - [Results](#results)
 - [Streaming large results](#streaming-large-results)
-- [Connection pool](#connection-pool)
+- [Connection pool](#connection-pool) — balancing across members,
+  health ejection, discovery, read-your-writes
 - [Streams (`CREATE STREAM`)](#streams-create-stream) — `subscribe`
 - [Type mapping](#type-mapping)
 - [Errors](#errors)
@@ -117,7 +119,9 @@ Skaidb.connect(
   timeout: 10.0,               # TCP connect timeout in seconds; nil = none
   database: nil,               # run USE <database> as part of connecting
   seeds: nil,                  # ["db1", "db2:7000", …] tried in random order
-  tls: false, tls_ca: nil, tls_insecure: false, tls_server_name: "skaidb"
+  tls: false, tls_ca: nil, tls_insecure: false, tls_server_name: "skaidb",
+  tls_client_cert: nil, tls_client_key: nil,   # PEM files: present a client certificate
+  auth_mechanism: :scram       # or :certificate: the client certificate is the login
 ) # => Skaidb::Connection (or the block's value when a block is given)
 ```
 
@@ -163,8 +167,19 @@ conn = Skaidb.connect(host: "db1", tls_insecure: true)            # dev only: no
 
 Any of the three enables TLS. The server name sent as SNI and checked against
 the certificate is `tls_server_name` (default `"skaidb"`, the SAN skaidb's own
-certificates carry). SCRAM runs inside the TLS session. The driver does not
-present a client certificate. Details: [docs/tls.md](https://github.com/porcupin26/skaidb-ruby/blob/main/docs/tls.md).
+certificates carry). SCRAM runs inside the TLS session.
+
+`tls_client_cert:` / `tls_client_key:` present a client certificate; with
+`auth_mechanism: :certificate` that certificate is the login (its Common Name
+is the user, no password is sent):
+
+```ruby
+conn = Skaidb.connect(host: "db1", tls_ca: "/etc/skaidb/ca.crt",
+                      tls_client_cert: "app.crt", tls_client_key: "app.key",
+                      auth_mechanism: :certificate)
+```
+
+Details: [docs/tls.md](https://github.com/porcupin26/skaidb-ruby/blob/main/docs/tls.md).
 
 ### Consistency
 
@@ -255,6 +270,8 @@ shaped like `PG::Result`:
   cell by index or column name.
 - `cmd_tuples`: rows affected by `INSERT`/`UPDATE`/`DELETE`; `0` for a
   `SELECT` and for DDL.
+- `kind`: `:rows`, `:mutation` (a count in `cmd_tuples`) or `:ddl` (a bare
+  acknowledgement), which tells "DDL succeeded" from "0 rows affected".
 - `result_sets`: for a `CALL` whose procedure `EMIT`s several result sets,
   every set in order (each a `Result`); the last set is the result's own
   `rows`/`fields`. Empty for an ordinary reply.
@@ -274,8 +291,10 @@ end
 first = conn.stream("SELECT id FROM big ORDER BY id").first(10)   # Enumerator form
 ```
 
-`stream` takes SQL text only (no parameters). A non-row statement returns
-`nil` without yielding.
+`stream` takes SQL text only (no parameters). With a block it returns a
+`Result` whose `kind` is `:stream` and whose `fields` are the column names
+(the rows went to the block); a non-row statement returns its `:mutation` /
+`:ddl` Result without yielding.
 
 **The abandon/drain rule.** The connection is busy for the whole stream:
 a statement from another thread waits for it. Leaving the block early —
@@ -304,7 +323,29 @@ pool.close                                    # closes idle connections
 blocks — when no idle connection is available a new one is dialed, and a
 returned connection beyond `maxsize` is closed. Connections are validated with
 `usable?` on checkout and check-in, so one broken by a transport error or an
-undrained stream is closed and replaced. Details: [docs/pooling.md](https://github.com/porcupin26/skaidb-ruby/blob/main/docs/pooling.md).
+undrained stream is closed and replaced.
+
+The pool spreads its connections across the members by the rules every skaidb
+driver shares
+([PROTOCOL.md §6.1](https://skaidb.org/docs/PROTOCOL.html#61-balancing-a-pool-across-members)):
+
+```ruby
+pool = Skaidb::Pool.new(seeds: ["db1", "db2", "db3"], database: "app",
+                        load_balancing: :least_latency, # or :round_robin; :random is the default
+                        discover: true,                 # members from SHOW ENDPOINTS, resyncing ones skipped
+                        read_your_writes: 2.0)          # seconds; see affinity below
+
+pool.with(affinity: user_id) { |conn| conn.exec_params("INSERT INTO notes (id, owner) VALUES ($1, $2)", [nid, user_id]) }
+pool.with(affinity: user_id) { |conn| conn.exec_params("SELECT * FROM notes WHERE id = $1", [nid]) } # same member
+
+pool.members # => [{ endpoint: "db1:7000", canonical: "10.0.0.1:7000", state: :ready,
+             #      latency_ms: 0.8, in_use: 2, idle: 3, seed: true }, …]
+```
+
+A member with consecutive transport failures, or a round-trip average far
+above the others', is ejected and re-admitted by a background probe (the last
+usable member never is); `idle_order: :fifo` keeps every idle connection in
+use. Details: [docs/pooling.md](https://github.com/porcupin26/skaidb-ruby/blob/main/docs/pooling.md).
 
 ## Streams (`CREATE STREAM`)
 
@@ -376,8 +417,9 @@ StandardError
   connection stays usable.
 - A transport failure (`ConnectionError`) marks the connection broken; the
   next statement re-dials, or a pool replaces it.
-- `ArgumentError` for `Pool.new(maxsize: 0)` and for `Skaidb::Uuid.new` of a
-  string that is not a UUID.
+- `ArgumentError` for `Pool.new(maxsize: 0)` or an unknown
+  `load_balancing`/`idle_order`, and for `Skaidb::Uuid.new` of a string that
+  is not a UUID.
 
 ## Transactions
 
@@ -404,7 +446,7 @@ frame after every handshake. It shows up as `client_name = 'ruby'` /
 
 ```sql
 SELECT client_name, client_version FROM drivers;
--- ruby | 1.0.3
+-- ruby | 1.2.0
 ```
 
 The server records the row asynchronously, so a `SELECT` immediately after
@@ -417,13 +459,38 @@ know the opcode answers with an error the driver ignores.
   `bigdecimal` is declared because it is a bundled gem since Ruby 3.4.
 - Works with any skaidb server. Where a server predates an opcode the driver
   falls back: prepared statements → client-side text binding, `Hello` →
-  ignored. `stream` and `exec_batch` need a server with those opcodes and
-  raise `QueryError` otherwise.
+  ignored, pool discovery (`SHOW ENDPOINTS`, server ≥ 0.327) → the
+  configured seeds. `stream` and `exec_batch` need a server with those
+  opcodes and raise `QueryError` otherwise.
 - The wire protocol (framing, SCRAM handshake, value encoding, opcodes) is
   specified at <https://skaidb.org/docs/PROTOCOL.html>. The driver speaks the
   binary protocol on port 7000; the server's REST/JSON gateway (port 7080)
   is a dependency-free alternative for other clients.
 
+## Conformance
+
+`test/conformance_test.rb` runs skaidb's shared wire-protocol conformance
+suite, vendored byte-identical from the server repository in
+[`conformance/`](https://github.com/porcupin26/skaidb-ruby/tree/main/conformance)
+(`vectors.json` plus the contract in its `README.md`), as part of `rake test`:
+
+- every value vector decodes to the expected Ruby value and encodes back to
+  the reference bytes (a Uuid cell is compared as its canonical String, the
+  form the driver returns);
+- every SCRAM vector (auth message, salted password, client proof, server
+  signature) through the driver's own SCRAM code;
+- the auth outcomes against a fake server that verifies the client proof
+  independently: `ok` connects, a server signature that does not verify
+  fails the connect, `denied` fails with the server's reason;
+- every case through the public API (`exec`, `stream`, `exec_params`,
+  `exec_batch`, and sequences of them on one connection), checking the exact
+  request bytes and the decoded result. The vectors' `?` placeholders are
+  passed as this driver's `$1`, `$2`, ….
+
+Nothing is skipped: the test prints `skipped call methods: none`. CI also
+fails when the vendored `vectors.json` differs from the published
+<https://skaidb.org/conformance/vectors.json>.
+
 ## Examples
 
 [`examples/`](https://github.com/porcupin26/skaidb-ruby/tree/main/examples)

data/docs/api.md

@@ -8,7 +8,7 @@ Everything lives under the `Skaidb` module in `lib/skaidb.rb`.
 |---|---|---|
 | `host` | `"localhost"` | Node to dial (ignored when `seeds` is given). |
 | `port` | `7000` | Binary-protocol port; also the port for a seed without one. |
-| `user` | `"anonymous"` | SCRAM user name. |
+| `user` | `"anonymous"` (SCRAM), `""` (certificate) | User name. Under `auth_mechanism: :certificate` it is optional and, when given, must equal the certificate's Common Name. |
 | `password` | `""` | SCRAM password. Empty skips server-signature verification (anonymous connect). |
 | `consistency` | `:quorum` | Default level for every statement: `:one`, `:quorum`, `:all`, `"ONE"`…, or `0`/`1`/`2`. |
 | `timeout` | `10.0` | TCP connect timeout in seconds; `nil` for none. Reads are not bounded. |
@@ -18,12 +18,18 @@ Everything lives under the `Skaidb` module in `lib/skaidb.rb`.
 | `tls_ca` | `nil` | PEM file to trust instead of the system store; implies `tls`. |
 | `tls_insecure` | `false` | TLS without any certificate verification; implies `tls`. Development only. |
 | `tls_server_name` | `"skaidb"` | SNI name, also checked against the certificate's SANs. |
+| `tls_client_cert` | `nil` | PEM file of a client certificate to present in the TLS handshake; implies `tls`. Needs `tls_client_key`. |
+| `tls_client_key` | `nil` | PEM file of that certificate's private key. |
+| `auth_mechanism` | `:scram` | `:scram` (user + password) or `:certificate` (the client certificate is the login, wire mechanism EXTERNAL; needs `tls_client_cert`/`tls_client_key`). Strings and the aliases `"password"`, `"external"`, `"x509"` are accepted. |
 
 With a block, yields the connection and closes it when the block returns
 (the block's value is returned). Raises `Skaidb::ConnectionError` when no
 endpoint accepts the handshake (`no reachable endpoint in …: <last error>`),
 `authentication denied: …` on a wrong password, and
 `server signature mismatch` when the server fails mutual authentication.
+Raises `Skaidb::Error` before dialing for an unknown `auth_mechanism`, a
+`tls_client_cert` without its `tls_client_key` (or the reverse), and
+`:certificate` without a client certificate.
 
 ## `Skaidb::Connection`
 
@@ -49,8 +55,11 @@ endpoint accepts the handshake (`no reachable endpoint in …: <last error>`),
 - `prepare_server(sql) → [id, nparams] | nil` — prepare a statement with `?`
   placeholders on the server; `nil` when the server refuses. Cached per
   connection (240 entries); the cache is cleared on re-dial.
-- `stream(sql, consistency: nil) { |row| … } → nil` — see
-  [streaming.md](streaming.md). Without a block returns an Enumerator.
+- `stream(sql, consistency: nil) { |row| … } → Result` — see
+  [streaming.md](streaming.md). For a row stream the returned Result has
+  `kind == :stream`, the column names in `fields` and no `rows` (they went to
+  the block); a statement without rows returns its `:mutation` / `:ddl`
+  Result without yielding. Without a block returns an Enumerator.
 - `subscribe(stream_name, after: nil, poll: 0.5) { |event| … }` — yields a
   `CREATE STREAM` log's events forever, each a Hash with `"id"`, `"op"`,
   `"k"`, `"ts"`, `"doc"`. Polls `_stream_<name>` 500 rows at a time with a
@@ -64,6 +73,8 @@ endpoint accepts the handshake (`no reachable endpoint in …: <last error>`),
 - `usable?` — `false` once closed, once a transport error broke the socket,
   or while a stream is in flight (including one abandoned through external
   iteration). No round-trip.
+- `endpoint` — the member the connection reached, as the `"host:port"` it
+  dialed (it changes when a re-dial lands on another member).
 - `closed`, `finished?` — `true` after `close`.
 - `close` — closes the socket; idempotent. Does not take the connection's
   lock, so another thread can use it to break a blocked read.
@@ -72,10 +83,11 @@ endpoint accepts the handshake (`no reachable endpoint in …: <last error>`),
 
 A transport failure raises `Skaidb::ConnectionError` and marks the
 connection broken. The next `exec`/`exec_params`/`exec_batch`/`stream`
-re-dials across the original seeds, re-authenticates, re-sends `Hello`,
-re-runs `USE`, and starts with an empty prepared-statement cache. If the
-re-dial fails, that statement raises `ConnectionError` and the one after it
-tries again.
+re-dials across the original seeds (a pooled connection: in the pool's
+order, usable members first and the one it lost last), re-authenticates,
+re-sends `Hello`, re-runs `USE`, and starts with an empty prepared-statement
+cache. If the re-dial fails, that statement raises `ConnectionError` and the
+one after it tries again.
 
 ## `Skaidb::Result`
 
@@ -91,14 +103,38 @@ Shaped like `PG::Result`; `Enumerable` over row Hashes.
 | `[i]` | Row `i` as a Hash, or `nil`. |
 | `getvalue(row, col)` | One cell; `col` is an index or a column name. |
 | `cmd_tuples` | Rows affected by `INSERT`/`UPDATE`/`DELETE`; `0` for `SELECT` and DDL. |
+| `kind` | What the server answered: `:rows` (a result set, or several in `result_sets`), `:mutation` (a count in `cmd_tuples`), `:ddl` (a bare acknowledgement — no rows and no count), `:stream` (the summary `stream` returns). |
 | `result_sets` | For a `CALL` whose body `EMIT`s, every result set in order (each a `Result`); the last one is this result's own `rows`/`fields`. `[]` otherwise. |
 
 ## `Skaidb::Pool`
 
-`Skaidb::Pool.new(maxsize: 10, **connect_options)` — see
-[pooling.md](pooling.md). `with { |conn| }`, `checkout`, `checkin(conn)`,
-`close`. Raises `ArgumentError` for `maxsize < 1` and `Skaidb::Error` on
-checkout from a closed pool.
+```ruby
+Skaidb::Pool.new(maxsize: 10, load_balancing: :random, idle_order: :lifo, discover: false,
+                 refresh_interval: 60.0, read_your_writes: 0.0, eject_errors: 3,
+                 eject_latency_factor: 3.0, eject_latency_floor: 0.05, eject_backoff: 5.0,
+                 eject_backoff_max: 60.0, logger: nil, **connect_options)
+```
+
+A thread-safe pool balanced across the cluster's members — see
+[pooling.md](pooling.md) for every option.
+
+- `with(affinity: nil) { |conn| … }` — check out, yield, check in; returns
+  the block's value.
+- `checkout(affinity: nil) → Connection` — an idle connection to the member
+  the policy picks, or a new one. Never blocks. `affinity` (any Hash key;
+  `nil` = pool-wide) scopes `read_your_writes`.
+- `checkin(conn)` — return it; closed instead when broken, when its member
+  is ejected or gone, or when `maxsize` are already idle.
+- `members → Array<Hash>` — per member: `:endpoint`, `:canonical`, `:state`
+  (`:ready`, `:ejected`, `:resyncing`, `:unreachable`, `:unlisted`),
+  `:latency_ms` (`nil` until measured), `:in_use`, `:idle`, `:seed`.
+- `close` — closes the idle connections and stops the background thread.
+
+`load_balancing` (`:random`, `:round_robin`, `:least_latency`) and
+`idle_order` (`:lifo`, `:fifo`) take a Symbol or a String. Raises
+`ArgumentError` for `maxsize < 1`, `eject_errors < 1` or an unknown
+`load_balancing`/`idle_order`, and `Skaidb::Error` on checkout from a closed
+pool.
 
 ## `Skaidb::Uuid`
 

data/docs/pooling.md

@@ -2,7 +2,9 @@
 
 `Skaidb::Pool` keeps a bounded set of idle connections and hands one to each
 caller, so a threaded server or job runner can use one connection per
-thread without dialing and authenticating on every request.
+thread without dialing and authenticating on every request. It spreads its
+connections across the cluster's members by the rules every skaidb driver
+shares.
 
 ```ruby
 pool = Skaidb::Pool.new(seeds: ["db1", "db2", "db3"], user: "app", password: "secret",
@@ -22,11 +24,120 @@ end
 pool.close                                   # closes every idle connection
 ```
 
+## API
+
+```ruby
+Skaidb::Pool.new(
+  maxsize: 10,
+  load_balancing: :random,      # :random | :round_robin | :least_latency
+  idle_order: :lifo,            # :lifo | :fifo
+  discover: false,              # read the members from SHOW ENDPOINTS
+  refresh_interval: 60.0,       # seconds between discovery refreshes
+  read_your_writes: 0.0,        # seconds; 0 = off
+  eject_errors: 3,              # consecutive transport failures
+  eject_latency_factor: 3.0,    # x the other members' median; 0 = off
+  eject_latency_floor: 0.05,    # seconds above the median, at least
+  eject_backoff: 5.0,           # first ejection, doubling per repeat
+  eject_backoff_max: 60.0,
+  logger: nil,                  # anything with #warn: ejections, re-admissions
+  **connect_options             # every Skaidb.connect keyword
+)
+
+pool.with(affinity: nil) { |conn| … }   # the block's value
+pool.checkout(affinity: nil)  -> Skaidb::Connection
+pool.checkin(conn)
+pool.members                  -> Array of Hashes (see "Watching it")
+pool.close
+```
+
+`load_balancing` and `idle_order` take a Symbol or a String. `host`/`port`/
+`seeds` name the starting members; the other `Skaidb.connect` keywords
+(`database`, TLS, `consistency`, `timeout`) apply to every connection, so
+pooled connections run `USE` and authenticate exactly like single ones. A
+pooled connection that re-dials after a transport error does so in the
+pool's order: usable members first, the one it lost last.
+`Connection#endpoint` names the member a connection reached.
+
+## Balancing across members
+
+With the default `load_balancing: :random` each new connection dials the
+members in random order and stays on the member it reached — fine for many
+clients, but one process can end up with most of its connections on one
+member. Pick a policy to spread a single process's load:
+
+```ruby
+pool = Skaidb::Pool.new(
+  seeds: ["db1", "db2", "db3"], database: "app", user: "app", password: pw,
+  load_balancing: :least_latency, # or :round_robin
+  discover: true,                 # learn the members from the cluster
+  read_your_writes: 2.0,          # seconds; see below
+  idle_order: :fifo
+)
+```
+
+| Option | Default | What it does |
+|---|---|---|
+| `load_balancing` | `:random` | `:round_robin`: checkouts rotate over the usable members in endpoint order. `:least_latency`: of two members picked at random, the one with the lower round-trip average × (checked-out connections + 1), so near and idle members win; a member not measured yet, or not in the last 2 s, scores 0 and is tried, so a lightly loaded pool keeps re-measuring every member. |
+| `idle_order` | `:lifo` | `:lifo` hands out the most recently returned connection first, so a quiet pool keeps few sockets warm. `:fifo` hands out the longest-idle one first, so every idle connection keeps being used and a server-side idle timeout never finds one. |
+| `discover` | `false` | Reads the members with `SHOW ENDPOINTS` (server ≥ 0.327; no privilege needed) when a member is first reached and every `refresh_interval` (60 s) after — every 5 s while a member is `resyncing` or `unreachable`. New members are added, members that left are dropped (seeds are kept, marked `unlisted`), and members the server reports `resyncing` or `unreachable` get no new connections until they are `ready` again, when they start with a fresh latency average. An older or standalone server leaves the seeds as they are, and the pool stops asking. |
+| `eject_errors` | `3` | Consecutive transport failures (a failed dial, an I/O error mid-request, a capacity refusal) that eject a member. Statement errors and refused logins do not count. |
+| `eject_latency_factor`, `eject_latency_floor` | `3.0`, `0.05` | A member whose round-trip average is above factor × the other usable members' median **and** more than floor seconds above it is ejected (once it and another member have 10 samples each). A factor of `0` disables it. |
+| `eject_backoff`, `eject_backoff_max` | `5.0`, `60.0` | How long an ejection lasts, doubling for each repeat up to the max; a member that stays healthy for `eject_backoff_max` after a re-admission starts over at the base. When the time is up a background thread dials the member and runs one statement: success re-admits it (with a fresh latency average), failure ejects it again. The last usable member is never ejected — a slow or flaky member beats none. |
+| `read_your_writes` | `0.0` | Seconds after a write during which checkouts with the same `affinity` go to the member that took the write. |
+| `logger` | `nil` | A `Logger` (or anything with `warn`) told of each ejection and re-admission. |
+
+An ejected member gets no new connections and its idle ones are closed; a
+connection to it that is returned to the pool is closed instead of kept.
+With a target member (round-robin, least-latency, an affinity) the pool
+hands out an idle connection to that member or dials it; a failed dial falls
+through to the other usable members, then to the unusable ones, so a
+checkout never has nowhere to go while any member is configured.
+
+**Latency.** Per member the pool keeps an exponentially weighted average of
+round trips (request sent to the first response frame): each sample moves it
+5 % of the way, and no sample counts for more than 10 × the larger of the
+current average and `eject_latency_floor`. One slow statement barely moves
+it; a member that stays slow is noticed within a few dozen statements.
+
+**Read-your-writes.** The member that coordinated a write reads it back at
+any consistency, `ONE` included; another member may not have applied it yet.
+With `read_your_writes` set, pass an affinity key — a user or session id —
+when you check out:
+
+```ruby
+pool.with(affinity: user_id) do |conn|
+  conn.exec_params("INSERT INTO notes (id, owner, body) VALUES ($1, $2, $3)", [nid, user_id, body])
+end
+# … the next request for the same user, within the window:
+pool.with(affinity: user_id) do |conn|        # same member
+  conn.exec_params("SELECT body FROM notes WHERE id = $1", [nid])
+end
+```
+
+The window starts when a write succeeds on a connection checked out under
+the key, and checkouts under it go to that member until the window ends
+(unless the member is ejected or not `ready`). Checkouts without a key
+share one pool-wide key, so with constant writes everything follows the
+latest writer — pass a key when you balance. A statement is a write unless
+its first keyword (after whitespace, comments and opening parentheses) is
+`SELECT`, `SHOW`, `EXPLAIN`, `DESCRIBE`, `DESC`, `VALUES`, `WITH` or `USE`.
+
+**Watching it.** `pool.members` returns one Hash per member, sorted by
+endpoint:
+
+```ruby
+[{ endpoint: "db1:7000", canonical: "10.0.0.1:7000", state: :ready,
+   latency_ms: 0.8, in_use: 2, idle: 3, seed: true }, …]
+```
+
+`endpoint` is what the pool dials, `canonical` the name the member reports
+for itself (once discovered), `state` one of `:ready`, `:ejected`,
+`:resyncing`, `:unreachable`, `:unlisted`, and `latency_ms` is `nil` until
+the member has been measured. The rules are the same in every skaidb driver
+([PROTOCOL.md §6.1](https://skaidb.org/docs/PROTOCOL.html#61-balancing-a-pool-across-members)).
+
 ## Behaviour
 
-- Every `Skaidb.connect` keyword passes through (`seeds`, `database`, TLS,
-  `consistency`, `timeout`), so pooled connections fail over across seeds
-  and run `USE` exactly like single ones.
 - `maxsize` (default 10) bounds the connections kept **idle**, not the number
   checked out. `checkout` never blocks: with no idle connection available it
   dials a new one, and a connection returned while `maxsize` are already idle
@@ -38,10 +149,15 @@ pool.close                                   # closes every idle connection
   and will fail its first statement with `Skaidb::ConnectionError`; that
   failure marks it broken, so `checkin` discards it and the next checkout
   gets a fresh one. Retry the statement in that case if it is safe to.
-- `close` marks the pool closed and closes the idle connections; connections
-  checked out at the time are closed when they are returned. `checkout` on a
-  closed pool raises `Skaidb::Error`. `maxsize < 1` raises `ArgumentError`.
-- The pool is thread-safe. A single connection should still be used by one
-  thread at a time; the pool is what gives each thread its own.
+- `close` marks the pool closed, closes the idle connections and stops the
+  background thread; connections checked out at the time are closed when
+  they are returned. `checkout` on a closed pool raises `Skaidb::Error`.
+  `maxsize < 1`, `eject_errors < 1` and an unknown `load_balancing` or
+  `idle_order` raise `ArgumentError`.
+- The pool is thread-safe: the idle list and the member table are guarded
+  by one mutex. The background thread (probes and discovery refreshes) is
+  started on first need; Ruby never waits for it at exit. A single
+  connection should still be used by one thread at a time; the pool is what
+  gives each thread its own.
 
 See also `examples/pool.rb`.

data/docs/streaming.md

@@ -13,11 +13,14 @@ end
 ```
 
 - `stream(sql, consistency: nil)` takes SQL text only — no parameters.
-- With a block it returns `nil` after the last row.
+- With a block it returns a `Skaidb::Result` after the last row: `kind` is
+  `:stream`, `fields` holds the column names (known even when no row
+  arrived), and `rows` is empty because the rows went to the block.
 - Without a block it returns an Enumerator: `conn.stream(sql).first(10)`,
   `.each_slice(1000)`, `.lazy.map { … }`, and the rest of Enumerable work.
 - A non-row statement (an `INSERT`, DDL, `USE`) answers with its ordinary
-  result over the same opcode; `stream` returns `nil` without yielding.
+  result over the same opcode; `stream` returns that Result (`kind`
+  `:mutation` with `cmd_tuples`, or `:ddl`) without yielding.
 - A server without the streaming opcode raises `Skaidb::QueryError`
   (`server does not support streaming: …`).
 

data/docs/tls.md

@@ -42,16 +42,44 @@ OpenSSL's message.
 
 ## What runs inside the session
 
-The TCP connection is upgraded to TLS *before* the SCRAM handshake, so the
+The TCP connection is upgraded to TLS *before* the login handshake, so the
 user name, nonces and proof all travel encrypted; with `seeds:`, each
-endpoint is upgraded and authenticated in turn until one succeeds. The
-driver does not present a client certificate; authentication is SCRAM.
+endpoint is upgraded and authenticated in turn until one succeeds.
+
+## Client certificates
+
+`tls_client_cert:` / `tls_client_key:` (PEM files) make the driver present a
+client certificate in the TLS handshake, which a server with
+`client_tls = "required"` and client verification needs. Either one turns TLS
+on, and they go together. On its own the certificate only opens the TLS
+session; the login is still the SCRAM user.
+
+With `auth_mechanism: :certificate` the certificate IS the login (wire
+mechanism EXTERNAL): the server maps its Common Name to a role and no
+password is sent. The server needs `auth.x509_enabled`, and its client CA
+must have signed the certificate.
+
+```ruby
+conn = Skaidb.connect(host: "db1", tls_ca: "/etc/skaidb/ca.crt",
+                      tls_client_cert: "/etc/app/app.crt",
+                      tls_client_key: "/etc/app/app.key",
+                      auth_mechanism: :certificate, database: "app")
+```
+
+Pass `user:` only to assert the expected identity: a certificate mapped to a
+different role fails the connect. The server's answer carries no signature
+to check — TLS already authenticated the server, so keep `tls_ca:` (or the
+system store) and do not combine a certificate login with `tls_insecure`.
+`Skaidb::Pool` passes these keywords through like the others.
 
 ## Failures
 
 - Wrong CA, expired certificate, name mismatch: `Skaidb::ConnectionError`
   with the OpenSSL message, from `connect` (or from the statement that
   triggered a re-dial).
+- A certificate login the server refuses (no role for the CN, `user:` not
+  matching it, x509 login disabled): `Skaidb::ConnectionError` with
+  `authentication denied: <reason>`.
 - Plain TCP against a `client_tls = required` server: the handshake cannot
   complete, so `connect` raises `Skaidb::ConnectionError`
   (`no reachable endpoint in …`) naming the underlying failure.