scriva 1.2.1

data/lib/scriva/client.rb

@@ -0,0 +1,648 @@
+require "time"
+require "grpc"
+require "google/protobuf/well_known_types"
+require "scriva/proto/scriva_pb"
+require "scriva/proto/scriva_services_pb"
+
+module Scriva
+  # Base class for ScrivaDB client errors mapped from engine gRPC status codes.
+  class Error < StandardError; end
+
+  # Raised when a keyed lookup/update/delete referenced a key that no live
+  # record holds (gRPC NOT_FOUND).
+  class NotFoundError < Error; end
+
+  # Raised when a keyed insert used a key already held by a live record
+  # (gRPC ALREADY_EXISTS).
+  class AlreadyExistsError < Error; end
+
+  # Synchronous gRPC client for ScrivaDB.
+  #
+  # Example:
+  #   db = Scriva::Client.new(host: "localhost", port: 5433, api_key: "dev-key")
+  #   db.create_collection("users")
+  #   id = db.insert("users", { name: "Alice", age: 30 })
+  #   record = db.find_by_id("users", id)
+  #   db.update("users", id, { name: "Alice", age: 31 })
+  #   db.delete("users", id)
+  #   db.drop_collection("users")
+  #   db.close
+  class Client
+    OP_MAP = {
+      "eq"       => :EQ,
+      "neq"      => :NEQ,
+      "gt"       => :GT,
+      "gte"      => :GTE,
+      "lt"       => :LT,
+      "lte"      => :LTE,
+      "contains" => :CONTAINS,
+      "regex"    => :REGEX,
+    }.freeze
+
+    # Documented short aggregation names → proto AggregateOp enum symbols.
+    AGG_MAP = {
+      "count" => :AGG_COUNT,
+      "sum"   => :AGG_SUM,
+      "avg"   => :AGG_AVG,
+      "min"   => :AGG_MIN,
+      "max"   => :AGG_MAX,
+    }.freeze
+
+    WATCH_OP_NAMES = {
+      0 => "UNSPECIFIED",
+      1 => "INSERTED",
+      2 => "UPDATED",
+      3 => "DELETED",
+      4 => "OVERFLOW",
+    }.freeze
+
+    # @param host        [String]  server hostname
+    # @param port        [Integer] gRPC port (default 5433)
+    # @param api_key     [String]  sent as x-api-key metadata on every call
+    # @param tls_ca_cert [String, nil] PEM CA certificate string or path to PEM file;
+    #                    when nil the channel uses plaintext (insecure) transport
+    def initialize(host: "localhost", port: 5433, api_key:, tls_ca_cert: nil)
+      @api_key = api_key
+      target   = "#{host}:#{port}"
+
+      if tls_ca_cert
+        pem = load_pem(tls_ca_cert)
+        creds = GRPC::Core::ChannelCredentials.new(pem)
+      else
+        creds = :this_channel_is_insecure
+      end
+
+      @stub = Scriva::V1::Scriva::Stub.new(target, creds)
+    end
+
+    # -- lifecycle -----------------------------------------------------------
+
+    def close
+      # GRPC::ClientStub does not expose an explicit close method in all
+      # versions; the channel is GC-collected. This method exists for API
+      # symmetry with other SDKs and for use as a context manager via #tap.
+    end
+
+    # Yields self then closes — use like:
+    #   Scriva::Client.open(host: ...) { |db| db.insert(...) }
+    def self.open(**kwargs, &block)
+      client = new(**kwargs)
+      if block
+        begin
+          block.call(client)
+        ensure
+          client.close
+        end
+      else
+        client
+      end
+    end
+
+    # -- collection management -----------------------------------------------
+
+    # Create a collection. When +default_ttl_seconds+ > 0, records inserted
+    # without an explicit ttl expire that many seconds after being written;
+    # 0 inherits the server-wide default.
+    def create_collection(name, default_ttl_seconds: 0)
+      req  = Scriva::V1::CreateCollectionRequest.new(
+        name:                name,
+        default_ttl_seconds: default_ttl_seconds,
+      )
+      resp = @stub.create_collection(req, metadata: metadata)
+      resp.name
+    end
+
+    def drop_collection(name)
+      req  = Scriva::V1::DropCollectionRequest.new(name: name)
+      resp = @stub.drop_collection(req, metadata: metadata)
+      resp.ok
+    end
+
+    def list_collections
+      req  = Scriva::V1::ListCollectionsRequest.new
+      resp = @stub.list_collections(req, metadata: metadata)
+      resp.names.to_a
+    end
+
+    # -- CRUD ----------------------------------------------------------------
+
+    # Insert one record. Returns the assigned integer ID.
+    #
+    # +ttl_seconds+ > 0 expires the record that long after insertion, overriding
+    # any collection default; 0 applies the collection default (if any).
+    #
+    # +key+ sets an optional caller-supplied string primary key (keyed create).
+    # When set, the record is inserted under this key and a key already held by
+    # a live record raises AlreadyExistsError. A keyed insert does not
+    # participate in transactions or per-record TTL.
+    def insert(collection, data, ttl_seconds: 0, key: "")
+      translate_errors do
+        req  = Scriva::V1::InsertRequest.new(
+          collection:  collection,
+          data:        hash_to_struct(data),
+          ttl_seconds: ttl_seconds,
+          key:         key,
+        )
+        resp = @stub.insert(req, metadata: metadata)
+        resp.id
+      end
+    end
+
+    # Insert multiple records. Returns an array of assigned IDs.
+    # +ttl_seconds+ is applied uniformly to every record in the batch.
+    def insert_many(collection, records, ttl_seconds: 0)
+      req  = Scriva::V1::InsertManyRequest.new(
+        collection:  collection,
+        records:     records.map { |r| hash_to_struct(r) },
+        ttl_seconds: ttl_seconds,
+      )
+      resp = @stub.insert_many(req, metadata: metadata)
+      resp.ids.to_a
+    end
+
+    # Fetch a single record by ID. Returns a Hash.
+    #
+    # +fields+ is an optional projection: when non-empty, only those top-level
+    # fields are returned in +data+ (id, key and rev are always included).
+    # nil/empty returns the full record.
+    def find_by_id(collection, id, fields: nil)
+      req  = Scriva::V1::FindByIdRequest.new(
+        collection: collection,
+        id:         id,
+        fields:     fields ? fields.map(&:to_s) : [],
+      )
+      resp = @stub.find_by_id(req, metadata: metadata)
+      record_to_hash(resp.record)
+    end
+
+    # Query records. Returns an Array of Hashes.
+    # The Find RPC is server-streaming; this collects the stream for convenience.
+    # Pass a block to stream results one by one without buffering.
+    #
+    # @param filter     [Hash, nil] filter hash (see filter_to_proto)
+    # @param limit      [Integer]   0 = no limit
+    # @param offset     [Integer]
+    # @param order_by   [String, Array] a single field name (deprecated scalar
+    #                    sort, paired with +descending+) or an Array for a
+    #                    multi-field sort — each item a field-name String, a
+    #                    [field, desc] pair, or a {field:, desc:} Hash.
+    # @param descending [Boolean]   only honoured for the scalar +order_by+ form
+    # @param fields     [Array, nil] optional projection (see #find_by_id)
+    # @param page_token [String]    keyset cursor from a previous #find_page
+    def find(collection, filter: nil, limit: 0, offset: 0, order_by: "",
+             descending: false, fields: nil, page_token: "")
+      req = build_find_request(
+        collection, filter, limit, offset, order_by, descending, fields, page_token
+      )
+      stream = @stub.find(req, metadata: metadata)
+      if block_given?
+        stream.each { |resp| yield record_to_hash(resp.record) }
+        nil
+      else
+        stream.map { |resp| record_to_hash(resp.record) }
+      end
+    end
+
+    # Query one keyset page, returning [records, next_page_token].
+    #
+    # Pass an ordering (+order_by+) and a +limit+, then feed the returned
+    # next-page token back as +page_token+ on the next call to walk the
+    # collection page by page in O(page) time. An empty next-page token means
+    # the last page was reached. Keep the same filter, ordering and limit on
+    # every page.
+    def find_page(collection, filter: nil, limit: 0, offset: 0, order_by: "",
+                  descending: false, fields: nil, page_token: "")
+      req = build_find_request(
+        collection, filter, limit, offset, order_by, descending, fields, page_token
+      )
+      records    = []
+      next_token = ""
+      @stub.find(req, metadata: metadata).each do |resp|
+        records << record_to_hash(resp.record)
+        next_token = resp.page_token unless resp.page_token.empty?
+      end
+      [records, next_token]
+    end
+
+    # Update a record. +ttl_seconds+ > 0 resets the record's expiry deadline to
+    # that long from now; 0 (the default) is sticky and leaves any existing
+    # deadline untouched.
+    def update(collection, id, data, ttl_seconds: 0)
+      req  = Scriva::V1::UpdateRequest.new(
+        collection:  collection,
+        id:          id,
+        data:        hash_to_struct(data),
+        ttl_seconds: ttl_seconds,
+      )
+      resp = @stub.update(req, metadata: metadata)
+      resp.id
+    end
+
+    def delete(collection, id)
+      req  = Scriva::V1::DeleteRequest.new(collection: collection, id: id)
+      resp = @stub.delete(req, metadata: metadata)
+      resp.ok
+    end
+
+    # -- keyed CRUD, upsert & compare-and-swap (N1) --------------------------
+
+    # Insert +data+ under +key+, or replace the existing keyed record —
+    # atomically. If no live record carries +key+ it is inserted; otherwise the
+    # existing record's data is replaced and its +rev+ incremented. Returns the
+    # resulting record Hash (including "key" and "rev").
+    def upsert(collection, key, data)
+      req  = Scriva::V1::UpsertRequest.new(
+        collection: collection,
+        key:        key,
+        data:       hash_to_struct(data),
+      )
+      resp = @stub.upsert(req, metadata: metadata)
+      record_to_hash(resp.record)
+    end
+
+    # Fetch the record carrying +key+. Raises NotFoundError if none.
+    # +fields+ projects +data+ to those top-level fields (id/key/rev always
+    # returned).
+    def find_by_key(collection, key, fields: nil)
+      translate_errors do
+        req  = Scriva::V1::FindByKeyRequest.new(
+          collection: collection,
+          key:        key,
+          fields:     fields ? fields.map(&:to_s) : [],
+        )
+        resp = @stub.find_by_key(req, metadata: metadata)
+        record_to_hash(resp.record)
+      end
+    end
+
+    # Overwrite the record carrying +key+, preserving the key itself. Raises
+    # NotFoundError if no live record carries +key+. Returns a Hash with "id",
+    # "key", "rev" (after the write) and "date_modified".
+    def update_by_key(collection, key, data)
+      translate_errors do
+        req  = Scriva::V1::UpdateByKeyRequest.new(
+          collection: collection,
+          key:        key,
+          data:       hash_to_struct(data),
+        )
+        resp = @stub.update_by_key(req, metadata: metadata)
+        out = { "id" => resp.id }
+        out["key"]           = resp.key           unless resp.key.empty?
+        out["rev"]           = resp.rev           unless resp.rev.zero?
+        out["date_modified"] = resp.date_modified unless resp.date_modified.empty?
+        out
+      end
+    end
+
+    # Delete the record carrying +key+. Returns true on success. Raises
+    # NotFoundError if no live record carries +key+.
+    def delete_by_key(collection, key)
+      translate_errors do
+        req  = Scriva::V1::DeleteByKeyRequest.new(collection: collection, key: key)
+        resp = @stub.delete_by_key(req, metadata: metadata)
+        resp.ok
+      end
+    end
+
+    # Compare-and-swap update on +key+, conditional on +expected_rev+. The write
+    # is applied only if the record's current +rev+ equals +expected_rev+. A
+    # stale revision (or a missing key) is a clean no-op — never an error.
+    # Returns { "swapped" => Boolean, "record" => Hash | nil }; "record" is the
+    # resulting record only when "swapped" is true.
+    def update_if_rev(collection, key, expected_rev, data)
+      req  = Scriva::V1::UpdateIfRevRequest.new(
+        collection:   collection,
+        key:          key,
+        expected_rev: expected_rev,
+        data:         hash_to_struct(data),
+      )
+      resp = @stub.update_if_rev(req, metadata: metadata)
+      out = { "swapped" => resp.swapped, "record" => nil }
+      out["record"] = record_to_hash(resp.record) if resp.swapped && resp.has_record?
+      out
+    end
+
+    # -- secondary indexes ---------------------------------------------------
+
+    def ensure_index(collection, field)
+      req = Scriva::V1::EnsureIndexRequest.new(collection: collection, field: field)
+      @stub.ensure_index(req, metadata: metadata)
+      nil
+    end
+
+    def drop_index(collection, field)
+      req  = Scriva::V1::DropIndexRequest.new(collection: collection, field: field)
+      resp = @stub.drop_index(req, metadata: metadata)
+      resp.ok
+    end
+
+    def list_indexes(collection)
+      req  = Scriva::V1::ListIndexesRequest.new(collection: collection)
+      resp = @stub.list_indexes(req, metadata: metadata)
+      resp.fields.to_a
+    end
+
+    # -- transactions --------------------------------------------------------
+
+    def begin_tx(collection)
+      req  = Scriva::V1::BeginTxRequest.new(collection: collection)
+      resp = @stub.begin_tx(req, metadata: metadata)
+      resp.tx_id
+    end
+
+    def commit_tx(tx_id)
+      req  = Scriva::V1::CommitTxRequest.new(tx_id: tx_id)
+      resp = @stub.commit_tx(req, metadata: metadata)
+      resp.ok
+    end
+
+    def rollback_tx(tx_id)
+      req  = Scriva::V1::RollbackTxRequest.new(tx_id: tx_id)
+      resp = @stub.rollback_tx(req, metadata: metadata)
+      resp.ok
+    end
+
+    # -- watch ---------------------------------------------------------------
+
+    # Subscribe to change events on a collection.
+    #
+    # Without a block, returns an Enumerator that yields event Hashes:
+    #   { op: "INSERTED", collection: "users", record: {...}, ts: "2026-..." }
+    #
+    # With a block, iterates until the server closes the stream or the block
+    # raises StopIteration / the caller breaks.
+    #
+    # @param filter [Hash, nil] optional filter
+    def watch(collection, filter: nil)
+      req    = Scriva::V1::WatchRequest.new(
+        collection: collection,
+        filter:     filter_to_proto(filter),
+      )
+      stream = @stub.watch(req, metadata: metadata)
+      enum   = Enumerator.new do |yielder|
+        stream.each do |event|
+          out = {
+            op:         WATCH_OP_NAMES[event.op] || "UNSPECIFIED",
+            collection: event.collection,
+            record:     record_to_hash(event.record),
+          }
+          out[:ts] = event.ts.to_time.utc.iso8601(9) if event.has_ts?
+          yielder << out
+        end
+      end
+      if block_given?
+        enum.each { |ev| yield ev }
+        nil
+      else
+        enum
+      end
+    end
+
+    # -- aggregations (N4) ---------------------------------------------------
+
+    # Compute count + numeric aggregations over the filtered live records.
+    #
+    # The Aggregate RPC is server-streaming — one message per group; this
+    # collects them into an Array. Each result Hash carries "group" (the
+    # group-by value, nil for the whole-set group), "count", "numeric", and —
+    # when the group had at least one numeric +field+ value — "sum"/"avg"/
+    # "min"/"max".
+    #
+    # @param aggregations [Array, nil] which numeric aggregations to compute —
+    #        any of "count", "sum", "avg", "min", "max". count is always
+    #        returned; sum/avg/min/max require +field+.
+    # @param field    [String] numeric field for sum/avg/min/max.
+    # @param group_by [String] optional group-by field — one result per value.
+    # @param filter   [Hash, nil] the same plain-hash filter as #find.
+    def aggregate(collection, aggregations: nil, field: "", group_by: "", filter: nil)
+      agg_ops = (aggregations || []).map do |name|
+        key = name.to_s.downcase
+        AGG_MAP[key] or raise ArgumentError,
+          "unknown aggregation #{name.inspect}; expected one of #{AGG_MAP.keys.sort.join(", ")}"
+      end
+
+      req = Scriva::V1::AggregateRequest.new(
+        collection:   collection,
+        filter:       filter_to_proto(filter),
+        group_by:     group_by,
+        field:        field,
+        aggregations: agg_ops,
+      )
+      @stub.aggregate(req, metadata: metadata).map do |resp|
+        g = {
+          "group"   => resp.has_group_value? ? resp.group_value.to_ruby : nil,
+          "count"   => resp.count,
+          "numeric" => resp.numeric,
+        }
+        if resp.numeric
+          g["sum"] = resp.sum
+          g["avg"] = resp.avg
+          g["min"] = resp.min
+          g["max"] = resp.max
+        end
+        g
+      end
+    end
+
+    # Count the live records matching +filter+ (or all records).
+    def count(collection, filter: nil)
+      groups = aggregate(collection, filter: filter)
+      groups.empty? ? 0 : groups.first["count"]
+    end
+
+    # Group live records by +field+ and aggregate each group. Convenience
+    # wrapper over #aggregate. +field+ is the group-by field; +metric+ is the
+    # numeric field for sum/avg/min/max (pass those in +aggregations+). Returns
+    # one Hash per distinct group value; see #aggregate for the Hash shape.
+    def group_by(collection, field, aggregations: nil, metric: "", filter: nil)
+      aggregate(
+        collection,
+        aggregations: aggregations,
+        field:        metric,
+        group_by:     field,
+        filter:       filter,
+      )
+    end
+
+    # -- stats ---------------------------------------------------------------
+
+    def stats(collection)
+      req  = Scriva::V1::CollectionStatsRequest.new(collection: collection)
+      resp = @stub.collection_stats(req, metadata: metadata)
+      {
+        collection:    resp.collection,
+        record_count:  resp.record_count,
+        segment_count: resp.segment_count,
+        dirty_entries: resp.dirty_entries,
+        size_bytes:    resp.size_bytes,
+      }
+    end
+
+    # -- maintenance ---------------------------------------------------------
+
+    # Force a synchronous compaction of a collection — merges dirty segments and
+    # reclaims space from deleted/overwritten records. Returns only once it is
+    # done. Returns true on success.
+    def compact(collection)
+      req  = Scriva::V1::CompactRequest.new(collection: collection)
+      resp = @stub.compact(req, metadata: metadata)
+      resp.ok
+    end
+
+    # Stream a consistent, gzip-compressed tar snapshot of the whole database.
+    #
+    # Without a block, returns an Enumerator yielding binary String chunks.
+    # With a block, yields each chunk in turn. Concatenate the chunks in order
+    # to reconstruct the archive; restore with `tar xzf backup.tar.gz`.
+    def snapshot(&block)
+      req    = Scriva::V1::SnapshotRequest.new
+      stream = @stub.snapshot(req, metadata: metadata)
+      enum   = Enumerator.new { |y| stream.each { |chunk| y << chunk.data } }
+      if block
+        enum.each(&block)
+        nil
+      else
+        enum
+      end
+    end
+
+    # Stream a whole-database snapshot straight to a file (binary). Returns the
+    # number of bytes written.
+    def snapshot_to_file(path)
+      total = 0
+      File.open(path, "wb") do |f|
+        snapshot { |chunk| total += f.write(chunk) }
+      end
+      total
+    end
+
+    private
+
+    def metadata
+      { "x-api-key" => @api_key }
+    end
+
+    # Map gRPC NOT_FOUND / ALREADY_EXISTS onto typed exceptions; other status
+    # codes propagate as the original GRPC::BadStatus.
+    def translate_errors
+      yield
+    rescue GRPC::NotFound => e
+      raise NotFoundError, e.details
+    rescue GRPC::AlreadyExists => e
+      raise AlreadyExistsError, e.details
+    end
+
+    def load_pem(tls_ca_cert)
+      return tls_ca_cert if tls_ca_cert.include?("BEGIN CERTIFICATE")
+      File.read(tls_ca_cert)
+    end
+
+    # Convert a plain Ruby Hash into a google.protobuf.Struct message.
+    def hash_to_struct(hash)
+      Google::Protobuf::Struct.from_hash(stringify_keys(hash))
+    end
+
+    def stringify_keys(hash)
+      hash.transform_keys(&:to_s)
+    end
+
+    # Convert a proto Record into a plain Ruby Hash. The caller-supplied "key"
+    # (when set) and the per-record "rev" (present on every live record,
+    # starting at 1) are surfaced alongside "id", "data" and the timestamps.
+    def record_to_hash(record)
+      return {} if record.nil?
+      out = {
+        "id"   => record.id,
+        "data" => record.has_data? ? record.data.to_h : {},
+      }
+      out["key"]           = record.key                                 unless record.key.empty?
+      out["rev"]           = record.rev                                 unless record.rev.zero?
+      out["date_added"]    = record.date_added.to_time.utc.iso8601(9)    if record.has_date_added?
+      out["date_modified"] = record.date_modified.to_time.utc.iso8601(9) if record.has_date_modified?
+      out
+    end
+
+    # Build a FindRequest shared by #find and #find_page, wiring projection,
+    # keyset pagination and either the multi-field or the deprecated scalar sort.
+    def build_find_request(collection, filter, limit, offset, order_by, descending, fields, page_token)
+      req = Scriva::V1::FindRequest.new(
+        collection: collection,
+        filter:     filter_to_proto(filter),
+        limit:      limit,
+        offset:     offset,
+        fields:     fields ? fields.map(&:to_s) : [],
+        page_token: page_token,
+      )
+      specs = order_by_to_proto(order_by)
+      if specs
+        specs.each { |o| req.order_by_fields.push(o) }
+      elsif order_by.is_a?(String) && !order_by.empty?
+        # Deprecated single-field path — honoured only when order_by_fields is
+        # empty (server-side).
+        req.order_by   = order_by
+        req.descending = descending
+      end
+      req
+    end
+
+    # Convert a multi-field +order_by+ argument to an Array of OrderBy specs.
+    # Returns nil when +order_by+ is empty or a plain String (the deprecated
+    # single-field path, handled by the caller). Otherwise accepts an Array
+    # whose items are field-name Strings, [field, desc] pairs, or
+    # {field:, desc:} Hashes.
+    def order_by_to_proto(order_by)
+      return nil if order_by.nil? || order_by.is_a?(String)
+      order_by.map do |item|
+        case item
+        when String
+          Scriva::V1::OrderBy.new(field: item, desc: false)
+        when Hash
+          h    = item.transform_keys(&:to_s)
+          desc = h.fetch("desc", h.fetch("descending", false))
+          Scriva::V1::OrderBy.new(field: h["field"].to_s, desc: !!desc)
+        when Array
+          desc = item.length > 1 ? !!item[1] : false
+          Scriva::V1::OrderBy.new(field: item[0].to_s, desc: desc)
+        else
+          raise ArgumentError,
+            "order_by items must be a field-name String, a [field, desc] pair, " \
+            "or a {field:, desc:} Hash"
+        end
+      end
+    end
+
+    # Convert a plain Hash filter into a proto Filter message.
+    #
+    # Accepted shapes:
+    #   { field: "age", op: "gt", value: "30" }
+    #   { and: [ <filter>, ... ] }
+    #   { or:  [ <filter>, ... ] }
+    def filter_to_proto(hash)
+      return nil if hash.nil?
+
+      h = hash.transform_keys(&:to_s)
+
+      if h.key?("and")
+        children = h["and"].map { |c| filter_to_proto(c) }
+        return Scriva::V1::Filter.new(and: Scriva::V1::AndFilter.new(filters: children))
+      end
+
+      if h.key?("or")
+        children = h["or"].map { |c| filter_to_proto(c) }
+        return Scriva::V1::Filter.new(or: Scriva::V1::OrFilter.new(filters: children))
+      end
+
+      op_name = h["op"].to_s.downcase
+      op_val  = OP_MAP[op_name] or raise ArgumentError,
+        "unknown filter op #{h["op"].inspect}; expected one of #{OP_MAP.keys.sort.join(", ")}"
+
+      Scriva::V1::Filter.new(
+        field: Scriva::V1::FieldFilter.new(
+          field: h["field"].to_s,
+          op:    Scriva::V1::FilterOp.const_get(op_val),
+          value: h["value"].to_s,
+        )
+      )
+    end
+  end
+end