mqkv 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c4110775ffdb60a5ede4fadbdb553beec726b337d7a06c7feb97b4c367cf0b56
-  data.tar.gz: e4fd4b75b0d80fe6c70af944ed94507c40e92c610bd55f68259761680de7b61b
+  metadata.gz: d737d046ae643ce3d316df07cc167f11f9c141b2d6f58f504557edcb3c4384c8
+  data.tar.gz: 574cf60004e1150b02959944c6fb38797ae14ecdca48351d7813a87441c465d4
 SHA512:
-  metadata.gz: eed925c0d43599e3d8dc283ca70befc5bb79e10b72f9a5727eaa33dba93e3509e50304d6aa6cb428fe7cb6e40dff13dc97b75c01ab682b6e0c4ce4e6ab60f998
-  data.tar.gz: 5a15102dbaad4203e0b8db1fa8bf22cd9f240ee88c20edf963e6a85f2ef89e6422b7a5d7d1cf25ae529edeb2dd3e6c05e092ba8bbf306ffdcc34c09f0df8b102
+  metadata.gz: 6880875f67dc0e324073475cba672c60c8e747ff6da11289b39ff41d5a2c20b4c772a39fa114ffef00ad9d0c5aadcbad438d385ae3d6f1fce37c408086122e9c
+  data.tar.gz: 168e701a4272b63237cc2a59755fb89fe4e28f94828a171632655a355dd9cc7581d931b7431bfefd79221bd403c08de54374534b3c4abc457a0d29e0c3f6a434

data/lib/mqkv/store.rb

@@ -20,11 +20,20 @@ module MQKV
     TOMBSTONE_HEADER = "__mqkv_deleted__"
     EXPIRES_HEADER = "__mqkv_expires_at__"
 
-    def initialize(url, prefix: "mqkv", read_timeout: 0.5, confirm: true, logger: nil)
+    # Stream consumers must ack to advance the broker's flow-control
+    # window: with manual acks and a prefetch of N, delivery stalls
+    # after N outstanding messages. Acking every half-window keeps
+    # deliveries flowing while still batching (multiple: true).
+    CONSUME_PREFETCH = 256
+    CONSUME_ACK_BATCH = CONSUME_PREFETCH / 2
+
+    def initialize(url, prefix: "mqkv", read_timeout: 0.5, connect_timeout: nil, confirm: true, cache_watchers: true, logger: nil)
       @url = url
       @prefix = prefix
       @read_timeout = read_timeout
+      @connect_timeout = connect_timeout
       @confirm = confirm
+      @cache_watchers_enabled = cache_watchers
       @logger = logger
       @mutex = Mutex.new
       @connection = nil
@@ -63,6 +72,31 @@ module MQKV
       resolve_current(consume_stream(queue_name(key), offset: "last"))
     end
 
+    # Cache-only read. Returns the cached value, or nil if the key has
+    # been tombstoned or isn't in the cache at all. Never falls through
+    # to the stream — intended for callers that want to decouple read
+    # latency from the broker (e.g. an HTTP handler that should show a
+    # placeholder when the cache isn't ready yet rather than block on
+    # AMQP). Use `cached?(key)` to distinguish "tombstoned" from
+    # "not cached".
+    def cached_get(key)
+      return nil unless @cache
+
+      @cache_mutex.synchronize do
+        return @cache[key].current_value if @cache.key?(key)
+      end
+      nil
+    end
+
+    # Whether the key is present in the in-memory cache. A tombstoned
+    # key still counts as cached (cached_get returns nil for it).
+    # Returns false if no preload has happened yet (no cache exists).
+    def cached?(key)
+      return false unless @cache
+
+      @cache_mutex.synchronize { @cache.key?(key) }
+    end
+
     def delete(key)
       name = queue_name(key)
       ensure_stream(name)
@@ -81,25 +115,50 @@ module MQKV
     end
 
     def history(key, limit: 10)
-      messages = consume_stream(queue_name(key), offset: "first")
       values = []
-      messages.each do |msg|
+      consume_stream(queue_name(key), offset: "first") do |msg|
         if tombstone?(msg)
           values.clear
         else
           values << msg.body
+          # Only the last `limit` values can ever be returned, so drop
+          # older ones as we scan — memory stays O(limit) instead of
+          # holding every body in the stream at once.
+          values.shift if values.size > limit
         end
       end
-      values.last(limit)
+      values
     end
 
     def preload(*keys, max_messages: 10_000)
       @cache_mutex.synchronize { @cache ||= {} }
       keys.each do |key|
-        messages = consume_stream(queue_name(key), offset: "first", max_messages: max_messages)
+        # Only the last message decides the cache entry; stream the
+        # scan so a long history never sits in memory all at once.
+        last = nil
+        count = consume_stream(queue_name(key), offset: "first", max_messages: max_messages) do |msg|
+          last = msg
+        end
+        entry = last ? msg_to_cache_entry(last) : CacheEntry.new(value: nil, expires_at: nil)
+        @cache_mutex.synchronize { @cache[key] = entry }
+        log(:debug) { "at=preload key=#{key} messages=#{count} value=#{entry.current_value.nil? ? "nil" : "present"}" }
+        start_cache_watcher(key)
+      end
+    end
+
+    # Like `preload`, but reads from `x-stream-offset: last` so only the
+    # current value is consumed (plus anything appended during the brief
+    # `read_timeout` window). Use this when keys live in streams with long
+    # histories and callers only care about the latest value — `preload`'s
+    # `offset: "first"` would otherwise drain up to `max_messages` of
+    # accumulated history per key on every boot.
+    def preload_latest(*keys)
+      @cache_mutex.synchronize { @cache ||= {} }
+      keys.each do |key|
+        messages = consume_stream(queue_name(key), offset: "last")
         entry = resolve_entry(messages)
         @cache_mutex.synchronize { @cache[key] = entry }
-        log(:debug) { "at=preload key=#{key} messages=#{messages.size} value=#{entry.current_value.nil? ? "nil" : "present"}" }
+        log(:debug) { "at=preload_latest key=#{key} value=#{entry.current_value.nil? ? "nil" : "present"}" }
         start_cache_watcher(key)
       end
     end
@@ -152,12 +211,16 @@ module MQKV
         return @connection if @connection && !@connection.closed?
 
         log(:info) { "at=connect url=#{sanitized_url}" }
-        @connection = AMQP::Client.new(@url).connect
+        @connection = AMQP::Client.new(@url, **client_options).connect
         @declared_streams.clear
         @connection
       end
     end
 
+    def client_options
+      @connect_timeout ? { connect_timeout: @connect_timeout } : {}
+    end
+
     def queue_name(key)
       "#{@prefix}.#{key}"
     end
@@ -191,12 +254,23 @@ module MQKV
       publish(name, "", headers: { TOMBSTONE_HEADER => true })
     end
 
+    # Drains the stream from `offset` until it goes quiet for
+    # `read_timeout`. With a block, each message is yielded as it
+    # arrives and the message count is returned — nothing is retained,
+    # so callers control their own memory. Without a block, all
+    # messages are collected and returned (only suitable for short
+    # reads like offset=last). Acks are issued in batches as the scan
+    # progresses; a single ack at the end would stall delivery once
+    # the prefetch window fills and silently truncate longer streams.
     def consume_stream(name, offset:, max_messages: 0)
       ensure_stream(name)
       ch = connection.channel
       begin
-        ch.basic_qos(256)
-        collected = []
+        ch.basic_qos(CONSUME_PREFETCH)
+        collected = block_given? ? nil : []
+        count = 0
+        unacked = 0
+        last = nil
         q = ::Queue.new
 
         consume_ok = ch.basic_consume(name, no_ack: false,
@@ -209,13 +283,25 @@ module MQKV
           msg = q.pop(timeout: @read_timeout)
           break if msg.nil?
 
-          collected << msg
-          break if max_messages > 0 && collected.size >= max_messages
+          count += 1
+          last = msg
+          if collected
+            collected << msg
+          else
+            yield msg
+          end
+
+          unacked += 1
+          if unacked >= CONSUME_ACK_BATCH
+            ch.basic_ack(msg.delivery_tag, multiple: true)
+            unacked = 0
+          end
+          break if max_messages > 0 && count >= max_messages
         end
 
-        ch.basic_ack(collected.last.delivery_tag, multiple: true) if collected.any?
+        ch.basic_ack(last.delivery_tag, multiple: true) if last && unacked > 0
         ch.basic_cancel(consume_ok.consumer_tag)
-        collected
+        collected || count
       ensure
         ch.close
       end
@@ -251,6 +337,8 @@ module MQKV
     end
 
     def start_cache_watcher(key)
+      return unless @cache_watchers_enabled
+
       @cache_mutex.synchronize { return if @cache_watchers.key?(key) }
 
       name = queue_name(key)

data/lib/mqkv/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module MQKV
-  VERSION = "0.2.0"
+  VERSION = "0.3.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mqkv
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - mqkv contributors
@@ -64,7 +64,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.6
+rubygems_version: 4.0.10
 specification_version: 4
 summary: Key-value store backed by AMQP stream queues
 test_files: []