tricoredb 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 735d173a09ff6f3b5251bbade94d449f563aad10257266b7aaa6e15030ad2fe8
-  data.tar.gz: 93d4dc22f7e1c09b0617d1826b5f7037a4c4313b58afd6c2493216dde1714161
+  metadata.gz: 35bb477aa16cb254d9745e4290a8ec5e052ba11e53dba60c8aa3b7a80aaff1a8
+  data.tar.gz: 3b6a18885b33a6625cb896a47856cf8def9c6c57b8c14cca85c282026ace41cb
 SHA512:
-  metadata.gz: f55362c4d3caaec273f45bd09861a2ae5f3e6b47707914009828a20fc6be04d3a75e22fa5f6febe8857b4b106420dfe0ad7498b2fee00fbd92455ef8f6d4fda3
-  data.tar.gz: 88df99ed1634d7c5eacd010861dbc72bf690d96500e282d2daa89d35a46249151e9d66eaa8003f2a75460e84f558dadff235b369cb9bd20a07bbafc043fc499f
+  metadata.gz: 5bb412d2aab2c127906911819e76d9d7703b1593a2d2cd01949be19f6c3534f1a5e440f907331ab60cec875aac4e955771018096d3d6a08b1faa3da71bcb856f
+  data.tar.gz: afc95e82a32c49fb6a5ca4dbeab10b8e42f93684842d1a42a8f3ee35b526746c3fba3654cb6152ea4715da9e9bcb20a221984ce6752601f2138c6f4f13c2f651

data/CHANGELOG.md

@@ -6,6 +6,61 @@ All notable changes to the `tricoredb` gem are recorded here. The format follows
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-10-13
+
+Every method added here needs a server at **0.1.0-rc.3 or later**. An older server
+does not know the operation and answers it with an error.
+
+### Added
+
+- 116 methods, one for each operation the server gained since 0.1.0-rc.2. The README
+  lists every one beside the server operation it sends.
+  - Cache (53): sorted sets, locks with fencing tokens, bitmaps, HyperLogLog,
+    multi-key reads and writes, conditional and atomic read-and-change writes,
+    stale-while-revalidate reads, list moves and blocking pops, set algebra,
+    pipelines, transactions and scripts, publish and poll, namespace limits and
+    statistics.
+  - Documents (13): `doc_replace`, `doc_insert_many`, `doc_delete_many`,
+    `doc_bulk_write`, `doc_explain`, collection options, renaming, index rebuilds
+    and transactions spanning requests.
+  - Vectors (21): batch upserts and deletes, batch, multi-query and by-example
+    searches, named vectors, aliases, filters, counts, partitions, text embedding,
+    index statistics and collection configuration.
+  - Graphs (29): bulk writes, in-place updates, traversals and algorithms
+    (components, cycles, k shortest paths, centrality, communities, PageRank and
+    more), indexes and constraints, CSV import, Cypher writes and transactions.
+- `TriCoreDB::BulkOp`, the four kinds of item a `doc_bulk_write` takes, and
+  `TriCoreDB::CacheOp`, the operations a cache pipeline, transaction or script runs.
+- `TriCoreDB::ScoreBound` and `TriCoreDB::CacheExpiry`.
+- `txn:` on `request` and on the document reads and writes, naming the document
+  transaction a call runs inside.
+
+### Fixed
+
+- `in_transaction?` stays true while an outer transaction is open. Since 2026-09-29
+  the server opens a nested block when `BEGIN` is sent inside a transaction, and the
+  `COMMIT` or `ROLLBACK` that ends the block (answered with `nested_depth`) leaves
+  the outer transaction open. The driver used to report the transaction as over, so
+  a pool could lend the connection on with it still open.
+
+
+## [0.2.0] - 2026-09-17
+
+### Added
+
+- Following the leader: a request refused with `not_leader` is sent again, to the
+  leader the refusal names (over a new connection that replaces the current one) or,
+  while no leader is known, to the same node after a pause. On by default;
+  `follow_leader: false` restores the previous behaviour, and `leader_retries` (5) and
+  `leader_retry_delay` (0.25 s) bound it. Never inside a session transaction.
+- `TriCoreDB::OUTCOME_UNKNOWN`: a request that may or may not have been applied. It is
+  never sent again.
+- `Client#address`.
+
+### Changed
+
+- A `not_leader` error message says whether the client already retried.
+
 ## [0.1.0] - 2026-09-16
 
 First release.
@@ -42,5 +97,7 @@ First release.
 - A value with no SQL form is refused by name instead of being pushed through
   `to_s`, and text that is not valid UTF-8 is refused rather than sent as mojibake.
 
-[Unreleased]: https://github.com/trinesh14/tricoredb-sdk-ruby/compare/v0.1.0...HEAD
+[Unreleased]: https://github.com/trinesh14/tricoredb-sdk-ruby/compare/v0.3.0...HEAD
+[0.3.0]: https://github.com/trinesh14/tricoredb-sdk-ruby/compare/v0.2.0...v0.3.0
+[0.2.0]: https://github.com/trinesh14/tricoredb-sdk-ruby/compare/v0.1.0...v0.2.0
 [0.1.0]: https://github.com/trinesh14/tricoredb-sdk-ruby/releases/tag/v0.1.0

data/README.md

@@ -110,6 +110,9 @@ db.close
 | `tls` | `nil` | See [TLS](#tls) |
 | `client_name` | `"tricoredb-ruby/<version>"` | Name reported in the handshake |
 | `features` | every capability | Bitmap announced in the handshake |
+| `follow_leader` | `true` | Send a `not_leader` refusal again, to the leader |
+| `leader_retries` | `5` | How many times a refused request is sent again |
+| `leader_retry_delay` | `0.25` | First pause, in seconds, before asking again; doubles up to 2 |
 
 A connection is a single request/response stream, so one connection serves one
 thread. For concurrent work use a [pool](#connection-pool).
@@ -290,6 +293,183 @@ path["node_path"]  # => ["u1", "u2"]
 `graph_degree`, `graph_list_nodes`, `graph_list_edges` and `graph_query` for the
 read-only Cypher subset.
 
+## Operations added for server 0.1.0-rc.3
+
+These need a server at **0.1.0-rc.3 or later**. An older server does not know the
+operation and answers it with an error, which this client raises like any other
+refusal.
+
+### Cache
+
+| Method | Server operation | What it does |
+| --- | --- | --- |
+| `cache_set_fresh` | `Cache.SetFresh` | Store a value that answers as fresh for the given time and as stale after it, until its TTL (if any) ends |
+| `cache_get_fresh` | `Cache.GetFresh` | Read with stale-while-revalidate and stampede protection |
+| `cache_set_missing` | `Cache.SetMissing` | Negative caching |
+| `cache_warm` | `Cache.Warm` | Cache warming |
+| `cache_mget` | `Cache.MGet` | Read many values in one request |
+| `cache_mset` | `Cache.MSet` | Write many values as one batch, all with the same optional TTL |
+| `cache_set_if` | `Cache.SetIf` | Write a value under a condition, with explicit control over the TTL |
+| `cache_zadd` | `Cache.ZAdd` | Add scored members to a sorted set, or re-score ones already there |
+| `cache_zrem` | `Cache.ZRem` | Remove members from a sorted set, returning how many were present |
+| `cache_zscore` | `Cache.ZScore` | The score of one member, or null when it is not in the set |
+| `cache_zcard` | `Cache.ZCard` | How many members a sorted set holds |
+| `cache_zrank` | `Cache.ZRank` | A member's position in the ordering, or null when it is absent |
+| `cache_zrange` | `Cache.ZRange` | Members by rank, `start..=stop` inclusive |
+| `cache_zrangebyscore` | `Cache.ZRangeByScore` | Members by score, between two bounds |
+| `cache_zincrby` | `Cache.ZIncrBy` | Add to a member's score, creating it at that score when absent |
+| `cache_lock_acquire` | `Cache.LockAcquire` | Take a lease on a lock, or refresh one already held by `owner` |
+| `cache_lock_renew` | `Cache.LockRenew` | Extend a lease the caller still holds |
+| `cache_lock_release` | `Cache.LockRelease` | Give up a lock |
+| `cache_setbit` | `Cache.SetBit` | Set one bit of a string value, growing it with zero bytes if needed |
+| `cache_getbit` | `Cache.GetBit` | Read one bit |
+| `cache_bitcount` | `Cache.BitCount` | Count the set bits, optionally within a byte range `(start, end)` with signed indices |
+| `cache_bitpos` | `Cache.BitPos` | The position of the first bit equal to `bit`, optionally within a byte range, or -1 when there is none |
+| `cache_bitop` | `Cache.BitOp` | Combine several values bitwise and store the result at `dest` |
+| `cache_pfadd` | `Cache.PfAdd` | Add elements to a HyperLogLog, creating it when absent |
+| `cache_pfcount` | `Cache.PfCount` | Estimated number of distinct elements |
+| `cache_pfmerge` | `Cache.PfMerge` | Merge several HyperLogLogs into `dest`, which is included as a source when it already exists |
+| `cache_lmove` | `Cache.LMove` | Atomically pop an element from one end of `source` and push it onto one end of `destination` |
+| `cache_expire_at` | `Cache.ExpireAt` | Set the absolute instant an existing live key dies |
+| `cache_stats` | `Cache.Stats` | What this node's cache is doing |
+| `cache_flush_database` | `Cache.FlushDatabase` | Delete every cache key in this database, across every namespace |
+| `cache_append` | `Cache.Append` | Concatenate bytes onto what a key already holds, and return the new length |
+| `cache_compare_and_swap` | `Cache.CompareAndSwap` | Write only if the key still holds `expected` (null |
+| `cache_getdel` | `Cache.GetDel` | Read a key and delete it in one atomic step |
+| `cache_getset` | `Cache.GetSet` | Write a value and return the one it replaced, atomically |
+| `cache_getex` | `Cache.GetEx` | Read a key and change its expiry in the same atomic step |
+| `cache_ltrim` | `Cache.LTrim` | Keep only the inclusive index range of a list, dropping everything outside it |
+| `cache_sunion` | `Cache.SUnion` | Every member of every named set, without duplicates |
+| `cache_sinter` | `Cache.SInter` | The members present in every named set |
+| `cache_sdiff` | `Cache.SDiff` | The members of the first set that are in none of the rest |
+| `cache_srandmember` | `Cache.SRandMember` | Random members of a set, without removing them |
+| `cache_hincrby` | `Cache.HIncrBy` | Add to one hash field, atomically, returning its new value |
+| `cache_pipeline` | `Cache.Pipeline` | Run cache operations in order in one round trip, each exactly as if it had been sent alone |
+| `cache_transaction` | `Cache.Transaction` | Run cache operations in order holding the cache write lock, so no other writer interleaves with them |
+| `cache_script_load` | `Cache.ScriptLoad` | Store a script |
+| `cache_script_run` | `Cache.ScriptRun` | Run a stored script with these arguments as one transaction |
+| `cache_hot_keys` | `Cache.HotKeys` | The most frequently addressed keys on this node since it started, with estimated counts |
+| `cache_purge_expired` | `Cache.PurgeExpired` | Delete every expired cache key in this database now, rather than leaving it to compaction |
+| `cache_blpop` | `Cache.BLPop` | Pop the head of the first non-empty list among `keys`, waiting up to the timeout for one to receive an element |
+| `cache_brpop` | `Cache.BRPop` | Pop the tail of the first non-empty list among `keys`, waiting up to the timeout for one to receive an element |
+| `cache_set_namespace_limit` | `Cache.SetNamespaceLimit` | Cap a namespace at `max_keys` live keys and `max_bytes` of values |
+| `cache_get_namespace_limit` | `Cache.GetNamespaceLimit` | A namespace's limit and what it holds now |
+| `cache_publish` | `Cache.Publish` | Append a message to a channel, returning the id it was given |
+| `cache_poll` | `Cache.Poll` | The messages after id `after` on these channels (a trailing `*` is a pattern) |
+
+### Documents
+
+| Method | Server operation | What it does |
+| --- | --- | --- |
+| `doc_replace` | `Document.Replace` | Swap a document's whole body for a new one |
+| `doc_insert_many` | `Document.InsertMany` | Insert several documents as one atomic batch |
+| `doc_delete_many` | `Document.DeleteMany` | Delete every document a filter matches, returning how many went |
+| `doc_rename_collection` | `Document.RenameCollection` | Move a collection, with its documents and indexes, to a new name |
+| `doc_purge_expired` | `Document.PurgeExpired` | Delete the documents a TTL index says have expired, now |
+| `doc_explain` | `Document.Explain` | Run a find and describe how it ran instead of returning its documents |
+| `doc_begin_transaction` | `Document.BeginTransaction` | Open a document transaction spanning requests, returning its id |
+| `doc_commit_transaction` | `Document.CommitTransaction` | Commit a document transaction |
+| `doc_rollback_transaction` | `Document.RollbackTransaction` | Discard a document transaction |
+| `doc_rebuild_index` | `Document.RebuildIndex` | Rebuild one index from the stored documents |
+| `doc_set_collection_options` | `Document.SetCollectionOptions` | Set a collection's options (`schema`, `defaults`, `versioned`), replacing any it had |
+| `doc_get_collection_options` | `Document.GetCollectionOptions` | A collection's options |
+| `doc_bulk_write` | `Document.BulkWrite` | Many inserts, updates, replaces and deletes on one collection, applied in order as one atomic batch |
+
+### Vectors
+
+| Method | Server operation | What it does |
+| --- | --- | --- |
+| `vector_embed` | `Vector.Embed` | Embed texts with the server's built-in embedder (deterministic feature hashing |
+| `vector_upsert_text` | `Vector.UpsertText` | Embed each text at the collection's dimension and upsert the vectors as one atomic batch |
+| `vector_set_alias` | `Vector.SetAlias` | Point an alias at a collection; a null collection removes it |
+| `vector_list_aliases` | `Vector.ListAliases` | Every alias and the collection it names, as `{alias, collection}` |
+| `vector_add_named_vector` | `Vector.AddNamedVector` | Declare a named vector on a collection |
+| `vector_upsert_named` | `Vector.UpsertNamed` | Write an item's vectors by name (`default` is the collection's own), each with the same metadata |
+| `vector_upsert_many` | `Vector.UpsertMany` | Write many vectors as one atomic batch |
+| `vector_delete_many` | `Vector.DeleteMany` | Delete many vectors by id as one atomic batch, returning how many of the ids were present |
+| `vector_search_batch` | `Vector.SearchBatch` | Run several query vectors against one collection in one request |
+| `vector_delete_by_filter` | `Vector.DeleteByFilter` | Delete every vector whose metadata matches a filter, as one atomic batch |
+| `vector_update_by_filter` | `Vector.UpdateByFilter` | Merge `set` into the metadata of every vector matching a filter, as one atomic batch |
+| `vector_count` | `Vector.Count` | How many vectors a collection holds, or, with a filter, how many match it |
+| `vector_list_partitions` | `Vector.ListPartitions` | The partitions of a collection |
+| `vector_rename_collection` | `Vector.RenameCollection` | Rename a collection, moving its catalog record and every vector with it |
+| `vector_rebuild_index` | `Vector.RebuildIndex` | Rebuild the collection's ANN index from its stored vectors and persist it, clearing every tombstone |
+| `vector_index_stats` | `Vector.IndexStats` | The shape of the collection's ANN index |
+| `vector_measure_recall` | `Vector.MeasureRecall` | Measure the ANN index's recall |
+| `vector_search_multi` | `Vector.SearchMulti` | Search with several query vectors and return one fused ranking |
+| `vector_set_collection_config` | `Vector.SetCollectionConfig` | Change a collection's configuration, returning it |
+| `vector_copy_collection` | `Vector.CopyCollection` | Copy a collection (configuration and every vector) to a new name |
+| `vector_search_by_examples` | `Vector.SearchByExamples` | Search with a query built from examples |
+
+### Graphs
+
+| Method | Server operation | What it does |
+| --- | --- | --- |
+| `graph_add_many` | `Graph.AddMany` | Write many nodes and edges as one unit |
+| `graph_remove_many` | `Graph.RemoveMany` | Delete many nodes and edges as one unit |
+| `graph_update_node` | `Graph.UpdateNode` | Change an existing node in place, returning it |
+| `graph_update_edge` | `Graph.UpdateEdge` | Change an existing edge in place, returning it |
+| `graph_copy` | `Graph.CopyGraph` | Copy a graph (nodes, edges and schema) to a new name |
+| `graph_dfs` | `Graph.Dfs` | A bounded depth-first walk from a node |
+| `graph_connected_components` | `Graph.ConnectedComponents` | Partition the graph's nodes into connected components, largest first |
+| `graph_detect_cycle` | `Graph.DetectCycle` | Whether the graph contains a cycle (`hasCycle`), and one `cycle` as evidence |
+| `graph_stats` | `Graph.GraphStats` | Counts describing a graph |
+| `graph_subgraph` | `Graph.Subgraph` | The part of the graph within `max_depth` hops of the seeds |
+| `graph_schema` | `Graph.GraphSchema` | What the graph's data looks like |
+| `graph_k_shortest_paths` | `Graph.KShortestPaths` | The `k` cheapest loopless paths between two nodes, cheapest first (default 3, at most 20) |
+| `graph_all_paths` | `Graph.AllPaths` | Every simple path between two nodes of at most `max_depth` edges (default 5, at most 10) |
+| `graph_centrality` | `Graph.Centrality` | Betweenness, closeness or eigenvector centrality |
+| `graph_communities` | `Graph.Communities` | Communities by Louvain modularity optimisation, direction ignored, largest first, with the partition's `modularity` |
+| `graph_triangle_count` | `Graph.TriangleCount` | Triangles and clustering coefficients, direction ignored |
+| `graph_node_similarity` | `Graph.NodeSimilarity` | The nodes whose neighbour sets most resemble a node's, under `results` |
+| `graph_check_consistency` | `Graph.CheckConsistency` | Check a graph's stored records against each other and against the resident mirror |
+| `graph_create_node_index` | `Graph.CreateNodeIndex` | Index node properties for finding nodes |
+| `graph_create_constraint` | `Graph.CreateConstraint` | Enforce a rule on a property of every node (or, with target `edge`, every relationship) carrying a label |
+| `graph_drop_schema_object` | `Graph.DropSchemaObject` | Drop an index or a constraint by name |
+| `graph_list_schema_objects` | `Graph.ListSchemaObjects` | A graph's `indexes` and `constraints` |
+| `graph_find_nodes` | `Graph.FindNodes` | Nodes with a label (when given) whose properties equal the given values, in id order |
+| `graph_import_csv` | `Graph.ImportCsv` | Import nodes and edges from CSV text as one atomic batch, so constraints apply |
+| `graph_page_rank` | `Graph.PageRank` | PageRank over edge direction |
+| `graph_execute` | `Graph.Execute` | Run a Cypher write |
+| `graph_begin_transaction` | `Graph.BeginTransaction` | Open a transaction on a graph, returning its id |
+| `graph_commit_transaction` | `Graph.CommitTransaction` | Apply every statement queued in a graph transaction as one |
+| `graph_rollback_transaction` | `Graph.RollbackTransaction` | Discard a graph transaction and its queued statements |
+`doc_bulk_write` takes its operations from `TriCoreDB::BulkOp` (`insert`,
+`update_one`, `replace`, `delete`), and a cache pipeline, transaction or script takes
+its from `TriCoreDB::CacheOp`:
+
+```ruby
+db.doc_bulk_write("people", [
+  TriCoreDB::BulkOp.insert({ "name" => "ada" }, id: "a"),
+  TriCoreDB::BulkOp.update_one("a", set: { "city" => "Pune" }),
+  TriCoreDB::BulkOp.delete("b")
+]) # every operation lands, or none does
+
+results = db.cache_pipeline([
+  TriCoreDB::CacheOp.set("sessions", "abc", "ada"),
+  TriCoreDB::CacheOp.get("sessions", "abc")
+]) # => [{"ok" => {"Json" => {"set" => true}}}, {"ok" => {"CacheValue" => [97, 100, 97]}}]
+```
+
+A document transaction is named in each call that runs inside it, and a graph
+transaction queues Cypher writes until it commits:
+
+```ruby
+txn = db.doc_begin_transaction
+db.doc_insert("people", { "name" => "ada" }, id: "a", txn: txn)
+db.doc_commit_transaction(txn)
+
+graph_txn = db.graph_begin_transaction("social")
+db.graph_execute("social", "CREATE (n:Person {name: 'ada'})", txn: graph_txn)
+db.graph_commit_transaction("social", graph_txn)
+```
+
+A result with one meaningful field comes back as that value; a larger one comes back
+as the server's own Hash, with the server's field names. Sorted-set bounds come from
+`TriCoreDB::ScoreBound` (a bare number is an inclusive bound) and expiries from
+`TriCoreDB::CacheExpiry`; search `options:` are the server's own names (`offset`,
+`exact`, `using`, `namespace`, ...).
+
 ## LLM context
 
 ```ruby
@@ -329,11 +509,24 @@ Every failure is a `TriCoreDB::Error`. Rescue the class you mean, and branch on
 | `ParameterError` | A value with no SQL form; nothing was sent. |
 | `PoolTimeout` | No pooled connection became free in time. |
 
-**Leader redirects.** In a cluster, a write that reaches a follower fails with
-`code == "not_leader"`, which `error.redirect?` and `response.redirect?` test. When
-the cluster knows the leader, `leader_hint` holds its `host:port`; a `nil` hint means
-the destination is unknown yet, so wait and retry — it does not mean the failure was
-something else. This driver does not follow the redirect for you.
+**Leader redirects.** In a cluster only the leader accepts writes, and a follower
+refuses with `code == "not_leader"` (`error.redirect?`). The client handles that
+itself (`follow_leader: true`, the default):
+
+- when the refusal names the leader (`leader_hint`), it opens a connection there with
+  the same user, secret and TLS settings (the leader's host is the certificate name),
+  sends the request again, and keeps that connection (`db.address` reports it);
+- while an election is in progress (no hint), it waits and asks the same node again,
+  pausing 0.25 s, then 0.5 s, up to 2 s;
+- after `leader_retries` (5) it raises the last refusal.
+
+This is safe because a `not_leader` refusal was applied nowhere. Nothing is sent again
+inside a session transaction, and never a refusal with `TriCoreDB::OUTCOME_UNKNOWN`: a
+follower handed that request to the leader and lost the answer, or the leader could
+not confirm it, so it may have been applied. The leader's address must be reachable
+from your application; when it is not, the client keeps its connection and waits. A
+pool passes these options to every connection. To handle redirects yourself, connect
+with `follow_leader: false`:
 
 ```ruby
 begin
@@ -370,7 +563,9 @@ rake test:integration  # the live tests, against a private tricore-server
 The scripted-peer tests play the answers a real cluster would send — a `not_leader`
 refusal, a refused handshake, a frame that declares more bytes than it sends — so
 they need no server. The live tests start their own `tricore-server` on an ephemeral
-port: point `TRICORE_SERVER_BIN` at the binary, and without one they skip.
+port: point `TRICORE_SERVER_BIN` at the binary. To use a server that is already
+running instead, set `TRICORE_HOST`, `TRICORE_PORT`, `TRICORE_USER` and
+`TRICORE_SECRET`. Without either they skip.
 
 ## License
 

data/lib/tricoredb/builders.rb

@@ -110,6 +110,148 @@ module TriCoreDB
     end
   end
 
+  # What a cache call does to a key's expiry.
+  module CacheExpiry
+    module_function
+
+    # Leave the expiry as it is.
+    def keep
+      "Keep"
+    end
+
+    # Remove the expiry, which is what a plain set does.
+    def clear
+      "Clear"
+    end
+
+    # Expire `ttl_ms` milliseconds from now.
+    # @return [Hash]
+    def set(ttl_ms)
+      { "Set" => { "ttl_ms" => Integer(ttl_ms) } }
+    end
+  end
+
+  # One end of a sorted-set score range.
+  #
+  # JSON has no infinity, so an unbounded end is sent as the largest finite Float,
+  # which no finite score lies beyond.
+  module ScoreBound
+    module_function
+
+    # A bound that includes members scoring exactly `value`.
+    # @return [Hash]
+    def inclusive(value)
+      bound(value, false)
+    end
+
+    # A bound that leaves out members scoring exactly `value`.
+    # @return [Hash]
+    def exclusive(value)
+      bound(value, true)
+    end
+
+    # No lower limit.
+    def lowest
+      bound(-Float::INFINITY, false)
+    end
+
+    # No upper limit.
+    def highest
+      bound(Float::INFINITY, false)
+    end
+
+    # @api private
+    def bound(value, exclusive)
+      number = Float(value)
+      raise ArgumentError, "a score bound must not be NaN" if number.nan?
+
+      number = number.positive? ? Float::MAX : -Float::MAX if number.infinite?
+      { "value" => number, "exclusive" => exclusive }
+    end
+  end
+
+  # Builders for the cache operations a pipeline, a transaction or a script runs.
+  # Each is the operation exactly as it would be sent alone.
+  #
+  # @example
+  #   db.cache_pipeline([TriCoreDB::CacheOp.set("sessions", "abc", "ada"), TriCoreDB::CacheOp.get("sessions", "abc")])
+  module CacheOp
+    module_function
+
+    # A liveness check.
+    def ping
+      "Ping"
+    end
+
+    # Any cache operation by its server name, with its fields as the server names
+    # them. Byte fields are Arrays of byte values.
+    # @return [Hash]
+    def raw(variant, body)
+      { variant.to_s => body }
+    end
+
+    # @param value [String, Array<Integer>]
+    def set(namespace, key, value, ttl_ms: nil)
+      raw("Set", "namespace" => namespace.to_s, "key" => key.to_s,
+                 "value" => value.is_a?(String) ? value.bytes : value, "ttl_ms" => ttl_ms)
+    end
+
+    def get(namespace, key)
+      raw("Get", "namespace" => namespace.to_s, "key" => key.to_s)
+    end
+
+    def delete(namespace, key)
+      raw("Delete", "namespace" => namespace.to_s, "key" => key.to_s)
+    end
+
+    def exists(namespace, key)
+      raw("Exists", "namespace" => namespace.to_s, "key" => key.to_s)
+    end
+
+    def incr(namespace, key, by = 1)
+      raw("Incr", "namespace" => namespace.to_s, "key" => key.to_s, "by" => Integer(by))
+    end
+
+    def expire(namespace, key, ttl_ms)
+      raw("Expire", "namespace" => namespace.to_s, "key" => key.to_s, "ttl_ms" => Integer(ttl_ms))
+    end
+  end
+
+  # Builders for the operations of {Client#doc_bulk_write}.
+  module BulkOp
+    module_function
+
+    # Insert a document, under `id` when one is given.
+    # @return [Hash]
+    def insert(document, id: nil)
+      { "Insert" => { "id" => id, "document" => document } }
+    end
+
+    # Set or increment fields on one document. `expected_version` applies it only
+    # if the document's `_version` is still that.
+    # @return [Hash]
+    def update_one(id, set: nil, inc: nil, upsert: false, expected_version: nil)
+      update = {}
+      update["set"] = set if set && !set.empty?
+      update["inc"] = inc if inc && !inc.empty?
+      { "UpdateOne" => { "id" => id, "update" => update, "upsert" => upsert ? true : false,
+                         "expected_version" => expected_version } }
+    end
+
+    # Swap a document's whole body for `document`.
+    # @return [Hash]
+    def replace(id, document, upsert: false, expected_version: nil)
+      { "Replace" => { "id" => id, "document" => document, "upsert" => upsert ? true : false,
+                       "expected_version" => expected_version } }
+    end
+
+    # Delete one document by id.
+    # @return [Hash]
+    def delete(id, expected_version: nil)
+      { "Delete" => { "id" => id, "expected_version" => expected_version } }
+    end
+  end
+
   # Builders for `LlmSource`.
   module LlmSource
     module_function