graphmind 0.6.0

data/lib/graphmind/ring_buffer.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Graphmind
+  # Bounded FIFO with drop-oldest semantics, holding the most recent frames
+  # while no viewer is attached so they can be replayed on attach.
+  #
+  # Two independent bounds, both drop-oldest:
+  #   * capacity  — a hard item count;
+  #   * max_bytes — an approximate memory ceiling, in UTF-8 bytes of the
+  #     frames. Without it, N slots cost N x the largest payload the host ever
+  #     emits.
+  #
+  # An item bigger than the whole byte budget is REFUSED (push returns false,
+  # `rejected` counts it) and nothing is evicted for it: one oversized frame
+  # must never cost the replay buffer every older frame — while the debugger
+  # was unreachable that turned one 17 MB event into the loss of every event
+  # before it. The caller decides the refused item's fate (the session sends
+  # it live when attached, else counts it lost). `reject_oversize: false`
+  # restores the old behaviour: the item is kept alone and every other item is
+  # evicted. Port of packages/client/src/ring-buffer.ts (`rejectOversize`,
+  # which the TypeScript session always turns on).
+  #
+  # Not thread-safe on its own — the session owns it under its mutex.
+  class RingBuffer
+    attr_reader :capacity, :dropped, :byte_size, :rejected, :max_bytes
+
+    def initialize(capacity, max_bytes = nil, reject_oversize: true)
+      raise ArgumentError, "capacity must be a positive integer" unless capacity.is_a?(Integer) && capacity >= 1
+      raise ArgumentError, "max_bytes must be > 0" if max_bytes && !(max_bytes.is_a?(Numeric) && max_bytes.positive?)
+
+      @capacity = capacity
+      @max_bytes = max_bytes
+      @reject_oversize = reject_oversize ? true : false
+      @items = []
+      @dropped = 0
+      @rejected = 0
+      @byte_size = 0
+    end
+
+    # Append one serialized frame; drops the oldest when either bound trips.
+    # Returns false only when the frame alone is larger than max_bytes and was
+    # refused (the buffer is then exactly as it was); true otherwise.
+    def push(frame)
+      size = frame.bytesize
+      if @max_bytes && @reject_oversize && size > @max_bytes
+        @rejected += 1
+        return false
+      end
+
+      @items << frame
+      @byte_size += size
+      while @items.size > @capacity
+        @byte_size -= @items.shift.bytesize
+        @dropped += 1
+      end
+      if @max_bytes
+        # Never down to empty: the frame just pushed is the newest and stays.
+        while @byte_size > @max_bytes && @items.size > 1
+          @byte_size -= @items.shift.bytesize
+          @dropped += 1
+        end
+      end
+      true
+    end
+
+    def to_a = @items.dup
+    def size = @items.size
+
+    def clear
+      @items.clear
+      @byte_size = 0
+      nil
+    end
+  end
+end

data/lib/graphmind/runtime.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Graphmind
+  # Process-wide shutdown plumbing.
+  #
+  # A gate held on the main thread would otherwise block interpreter exit
+  # forever, so every live session registers a fail-open hook here and a single
+  # at_exit handler releases them all. One handler, not one per session, so a
+  # test suite that builds hundreds of sessions does not build hundreds of
+  # at_exit callbacks.
+  module Runtime
+    @mutex = Mutex.new
+    @hooks = []
+    @installed = false
+
+    class << self
+      def register(hook)
+        @mutex.synchronize do
+          @hooks << hook
+          install!
+        end
+        nil
+      end
+
+      def unregister(hook)
+        @mutex.synchronize { @hooks.delete(hook) }
+        nil
+      end
+
+      def fail_open_all
+        hooks = @mutex.synchronize { @hooks.dup }
+        hooks.each do |hook|
+          hook.call
+        rescue StandardError
+          nil
+        end
+        nil
+      end
+
+      private
+
+      def install!
+        return if @installed
+
+        @installed = true
+        at_exit { Graphmind::Runtime.fail_open_all }
+      end
+    end
+  end
+end

data/lib/graphmind/safe.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Graphmind
+  # "Never raise into the host app" plumbing.
+  #
+  # All internal failures degrade to a no-op plus a rate-limited warning: at
+  # most one warning per key per interval, so a permanently broken transport
+  # cannot spam a Rails log.
+  class Warner
+    # `Kernel.warn`, explicitly: a bare `warn(message)` inside this class binds
+    # to Warner#warn (arity 2+) and raises ArgumentError, which the rescue at
+    # the bottom of #warn would then swallow — leaving the default sink
+    # silently printing nothing.
+    def initialize(interval = 60.0, sink = nil)
+      @interval = interval
+      @sink = sink || ->(message) { Kernel.warn(message) }
+      @last = {}
+      @mutex = Mutex.new
+    end
+
+    def warn(key, message, cause = nil)
+      now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      emit = @mutex.synchronize do
+        previous = @last[key]
+        if previous && (now - previous) < @interval
+          false
+        else
+          @last[key] = now
+          true
+        end
+      end
+      return unless emit
+
+      suffix =
+        if cause.is_a?(Exception)
+          " (#{cause.class}: #{cause.message})"
+        elsif cause.nil?
+          ""
+        else
+          " (#{cause})"
+        end
+      @sink.call("[graphmind] #{message}#{suffix}")
+    rescue StandardError
+      # Even a raising sink must not propagate into the host.
+      nil
+    end
+  end
+end