cosmonats 0.2.0 → 0.3.0

data/lib/cosmo/processor.rb

@@ -1,16 +1,24 @@
 # frozen_string_literal: true
 
 module Cosmo
-  class Processor
+  class Processor # rubocop:disable Metrics/ClassLength
+    STREAM_PAUSED_RECHECK_TTL = 5.0 # Seconds a stream's paused state is cached before re-checking (override via COSMO_STREAM_PAUSED_RECHECK_TTL)
+    STREAMS_PAUSED_IDLE_SLEEP = 1.0 # Seconds to sleep when every stream is paused, preventing a tight CPU spin (override via COSMO_STREAMS_PAUSED_IDLE_SLEEP)
+    STREAM_EMPTY_BACKOFF_MAX = 5.0  # Max seconds to sleep between empty fetches (override via COSMO_STREAM_EMPTY_BACKOFF_MAX)
+
     def self.run(...)
       new(...).tap(&:run)
     end
 
+    attr_reader :consumers
+
     def initialize(pool, running, options)
       @pool = pool
       @running = running
       @options = options
+      @threads = []
       @consumers = []
+      @cache = Utils::TTLCache.new
     end
 
     def run
@@ -21,9 +29,95 @@ module Cosmo
       run_loop
     end
 
+    def stop(timeout = Config[:timeout])
+      @running.make_false
+      @pool.shutdown
+      @consumers.each { |(s, _)| s.unsubscribe rescue nil }
+      @pool.wait_for_termination(timeout)
+      @threads.compact.each { _1.join(timeout) || _1.kill }
+      @consumers.clear
+      @threads.clear
+    end
+
     private
 
     def run_loop
+      @threads << Thread.new { work_loop }
+      @threads << Thread.new { schedule_loop } if scheduler?
+    end
+
+    def work_loop # rubocop:disable Metrics/AbcSize, Metrics/MethodLength, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+      shutdown = false
+
+      while running?
+        break if shutdown
+
+        all_empty = true  # every stream is empty
+        all_paused = true # every stream is paused
+        consumers.each do |(subscription, config, processor)| # rubocop:disable Metrics/BlockLength
+          break unless running?
+
+          stream_name = config[:stream].to_s
+          ttl = ENV.fetch("COSMO_STREAM_PAUSED_RECHECK_TTL", STREAM_PAUSED_RECHECK_TTL).to_f
+          if @cache.fetch(stream_name, ttl:) { API::Stream.new(stream_name).paused? }
+            Logger.debug "stream #{stream_name} is paused, skipping fetch"
+            next
+          end
+          all_paused = false
+
+          _, skip_t = consumer_state[stream_name]
+          if skip_t && Time.now < skip_t
+            Logger.debug "stream #{stream_name} is empty, backing off"
+            next
+          end
+          all_empty = false
+
+          begin
+            @pool.post do
+              # Re-check, after possibly being blocked on post to thread pool
+              _, skip_t = consumer_state[stream_name]
+              next if skip_t && Time.now < skip_t
+
+              timeout = fetch_timeout(config)
+              Logger.debug "fetching #{fetch_subjects(config).inspect}, timeout=#{timeout}"
+              messages = lock(stream_name) { fetch(subscription, batch_size: config[:batch_size], timeout:) }
+              Logger.debug "fetched (#{messages&.size.to_i}) messages"
+              if messages&.any?
+                consumer_state.delete(stream_name)
+                process(messages, processor)
+              else
+                max_backoff = ENV.fetch("COSMO_STREAM_EMPTY_BACKOFF_MAX", STREAM_EMPTY_BACKOFF_MAX).to_f
+                consumer_state.compute(stream_name) do |current|
+                  count = (current&.first || 0) + 1
+                  backoff = [timeout * (2**(count - 1)), max_backoff].min
+                  [count, Time.now + backoff]
+                end
+              end
+            end
+          rescue Concurrent::RejectedExecutionError
+            shutdown = true
+            break # pool doesn't accept new jobs, we are shutting down
+          end
+        end
+
+        break unless running?
+
+        if all_paused
+          period = ENV.fetch("COSMO_STREAMS_PAUSED_IDLE_SLEEP", STREAMS_PAUSED_IDLE_SLEEP).to_f
+          Logger.debug "all streams paused, sleep=#{period}"
+          sleep(period)
+        elsif all_empty
+          next_wake = consumer_state.values.filter_map { |_, t| t }.min
+          next unless next_wake # entry was deleted concurrently (messages arrived), re-loop immediately
+
+          remaining = [next_wake - Time.now, 0.01].max
+          Logger.debug "all streams empty, sleep=#{remaining}"
+          sleep(remaining)
+        end
+      end
+    end
+
+    def schedule_loop
       raise NotImplementedError
     end
 
@@ -39,6 +133,10 @@ module Cosmo
       @running.true?
     end
 
+    def scheduler?
+      false
+    end
+
     def fetch(subscription, batch_size:, timeout:)
       subscription.fetch(batch_size, timeout:)
     rescue NATS::Timeout
@@ -49,6 +147,7 @@ module Cosmo
 
       backoff = ENV.fetch("COSMO_STREAMS_FETCH_BACKOFF", 5).to_f
       sleep([timeout, backoff].max) # backoff before retry
+      nil
     end
 
     def client
@@ -58,5 +157,14 @@ module Cosmo
     def stopwatch
       Utils::Stopwatch.new
     end
+
+    def lock(stream_name, &)
+      @locks ||= Hash.new { |h, k| h[k] = Mutex.new }
+      @locks[stream_name].synchronize(&)
+    end
+
+    def consumer_state
+      @consumer_state ||= Concurrent::Map.new
+    end
   end
 end

data/lib/cosmo/stream/processor.rb

@@ -3,48 +3,18 @@
 module Cosmo
   module Stream
     class Processor < ::Cosmo::Processor
-      def initialize(pool, running, options)
-        super
-        @configs = []
-      end
-
       private
 
-      def run_loop
-        Thread.new { work_loop }
-      end
-
       def setup
-        setup_configs
-        setup_consumers
-      end
-
-      def work_loop # rubocop:disable Metrics/AbcSize, Metrics/MethodLength, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
-        shutdown = false
-
-        while running?
-          break if shutdown
-
-          @consumers.each do |(subscription, config, processor)|
-            break unless running?
-
-            begin
-              @pool.post do
-                timeout = convert_timeout(config[:fetch_timeout])
-                Logger.debug "fetching #{config.dig(:consumer, :subjects).inspect}, timeout=#{timeout}"
-                messages = fetch(subscription, batch_size: config[:batch_size], timeout:)
-                Logger.debug "fetched (#{messages&.size.to_i}) messages"
-                process(messages, processor) if messages&.any?
-                Logger.debug "processed (#{messages&.size.to_i}) messages"
-              end
-            rescue Concurrent::RejectedExecutionError
-              shutdown = true
-              break # pool doesn't accept new jobs, we are shutting down
-            end
+        @configs ||= []
+        @configs = static_config + dynamic_config
 
-            break unless running?
-          end
+        if @options[:processors]
+          pattern = Regexp.new(@options[:processors].map { "\\b#{_1}\\b" }.join("|"))
+          @configs.select! { _1[:class].name.match?(pattern) }
         end
+
+        @configs.each { @consumers << subscribe(nil, _1) }
       end
 
       def process(messages, processor) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
@@ -70,25 +40,6 @@ module Cosmo
         raise
       end
 
-      def setup_configs
-        @configs = static_config + dynamic_config
-        return unless @options[:processors]
-
-        pattern = Regexp.new(@options[:processors].map { "\\b#{_1}\\b" }.join("|"))
-        @configs.select! { _1[:class].name.match?(pattern) }
-      end
-
-      def setup_consumers
-        @configs.each do |config|
-          processor = config[:class].new
-          subjects = config.dig(:consumer, :subjects)
-          deliver_policy = Config.deliver_policy(config[:start_position])
-          consumer_config, consumer_name = config.values_at(:consumer, :consumer_name)
-          subscription = client.subscribe(subjects, consumer_name, consumer_config.merge(deliver_policy))
-          @consumers << [subscription, config, processor]
-        end
-      end
-
       def static_config
         Config.dig(:consumers, :streams)&.filter_map do |config|
           next unless (klass = Utils::String.safe_constantize(config[:class]))
@@ -98,11 +49,24 @@ module Cosmo
       end
 
       def dynamic_config
-        Config.system[:streams].map { _1.default_options.merge(class: _1) }
+        Config.internal[:streams].map { _1.default_options.merge(class: _1) }
+      end
+
+      def subscribe(_stream_name, config)
+        processor = config[:class].new
+        subjects = config.dig(:consumer, :subjects)
+        deliver_policy = Config.deliver_policy(config[:start_position])
+        consumer_config, consumer_name = config.values_at(:consumer, :consumer_name)
+        subscription = client.subscribe(subjects, consumer_name, consumer_config.merge(deliver_policy))
+        [subscription, config, processor]
+      end
+
+      def fetch_subjects(config)
+        config.dig(:consumer, :subjects)
       end
 
-      def convert_timeout(value)
-        timeout = value.to_f
+      def fetch_timeout(config)
+        timeout = config[:fetch_timeout].to_f
         if timeout <= 0
           Logger.warn "Ignoring `fetch_timeout: #{timeout}` (causes high CPU usage) with #{Data::DEFAULTS[:fetch_timeout]}s instead"
           timeout = Data::DEFAULTS[:fetch_timeout].to_f

data/lib/cosmo/stream.rb

@@ -28,8 +28,8 @@ module Cosmo
       end
 
       def register # rubocop:disable Metrics/AbcSize
-        Config.system[:streams] ||= []
-        Config.system[:streams] << self
+        Config.internal[:streams] ||= []
+        Config.internal[:streams] << self
 
         # settings are inherited, don't try to modify them
         return if default_options != Data::DEFAULTS

data/lib/cosmo/utils/hash.rb

@@ -23,22 +23,6 @@ module Cosmo
         end
       end
 
-      # deep dup
-      def dup(hash)
-        Marshal.load(Marshal.dump(hash))
-      end
-
-      # dig keys
-      def keys?(hash, *keys)
-        keys.reduce(hash) do |base, key|
-          return false if !base.is_a?(::Hash) || !base.key?(key)
-
-          base[key]
-        end
-
-        true
-      end
-
       # deep set
       def set(hash, *keys, value)
         last_key = keys.pop
@@ -49,17 +33,9 @@ module Cosmo
         target[last_key] = value
       end
 
-      # deep merge
-      def merge(hash1, hash2)
-        return hash1 unless hash2
-
-        hash1.merge(hash2) do |_key, old_val, new_val|
-          if old_val.is_a?(::Hash) && new_val.is_a?(::Hash)
-            merge(old_val, new_val)
-          else
-            new_val
-          end
-        end
+      # deep dup
+      def dup(hash)
+        Marshal.load(Marshal.dump(hash))
       end
     end
   end

data/lib/cosmo/utils/ttl_cache.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Cosmo
+  module Utils
+    class TTLCache
+      def initialize
+        @store = {}
+      end
+
+      def set(key, value, ttl: nil)
+        @store[key] = [value, ttl ? Time.now + ttl : nil]
+        value
+      end
+
+      def get(key)
+        return unless key?(key)
+
+        @store[key].first
+      end
+
+      def fetch(key, ttl: nil)
+        return get(key) if key?(key)
+
+        result = yield
+        set(key, result, ttl: ttl)
+        result
+      end
+
+      private
+
+      def key?(key)
+        exists = @store.key?(key)
+        return false unless exists
+
+        _, ttl = @store[key]
+        return true unless ttl
+        return true if Time.now < ttl
+
+        @store.delete(key)
+        false
+      end
+    end
+  end
+end

data/lib/cosmo/utils.rb

@@ -7,6 +7,7 @@ require "cosmo/utils/signal"
 require "cosmo/utils/warnings"
 require "cosmo/utils/stopwatch"
 require "cosmo/utils/thread_pool"
+require "cosmo/utils/ttl_cache"
 
 module Cosmo
   module Utils

data/lib/cosmo/version.rb

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

data/lib/cosmo/web/assets/app.css

@@ -135,6 +135,52 @@ button:hover, .btn:hover {
   );
 }
 
+.btn-warning {
+  background: linear-gradient(
+    oklch(from var(--color-warning) calc(l + 0.06) c h),
+    var(--color-warning)
+  );
+  color: oklch(27% 0.005 256);
+}
+.btn-warning:hover {
+  background: linear-gradient(
+    oklch(from var(--color-warning) calc(l + 0.16) c h),
+    oklch(from var(--color-warning) calc(l + 0.1) c h)
+  );
+  color: oklch(27% 0.005 256);
+}
+
+.btn-success {
+  background: linear-gradient(
+    oklch(from var(--color-success) calc(l + 0.06) c h),
+    var(--color-success)
+  );
+}
+.btn-success:hover {
+  background: linear-gradient(
+    oklch(from var(--color-success) calc(l + 0.16) c h),
+    oklch(from var(--color-success) calc(l + 0.1) c h)
+  );
+}
+
+/* ── Badges ────────────────────────────────────────────────────────────── */
+.badge {
+  border-radius: var(--space-1-2);
+  display: inline-block;
+  font-size: var(--font-size-small);
+  font-weight: 700;
+  padding: 2px var(--space);
+  white-space: nowrap;
+}
+.badge-success {
+  background: oklch(from var(--color-success) l c h / 15%);
+  color: var(--color-success);
+}
+.badge-warning {
+  background: oklch(from var(--color-warning) l c h / 20%);
+  color: oklch(from var(--color-warning) calc(l - 0.15) c h);
+}
+
 /* ── Alerts ────────────────────────────────────────────────────────────── */
 .alert {
   padding: var(--space-2x);

data/lib/cosmo/web/controllers/streams.rb

@@ -21,22 +21,48 @@ module Cosmo
           ok render("streams/info", { name: name }, layout: true)
         end
 
-        def _table
-          streams = API::Stream.all.map do |stream|
-            state, config = stream.info.values
-            { name: stream.name, messages: state.messages, bytes: state.bytes,
-              first_seq: state.first_seq, last_seq: state.last_seq,
-              consumer_count: state.consumer_count,
-              subjects: config.subjects }
-          end
+        def pause
+          name = Rack::Utils.unescape(@request.params["name"])
+          stream = API::Stream.new(name)
+          stream.pause!
+          return ok render("streams/_pause_banner", banner_locals(stream)) if @request.params["banner"]
+
+          ok render("streams/_stream_row", { stream: row_locals(stream) })
+        end
+
+        def unpause
+          name = Rack::Utils.unescape(@request.params["name"])
+          stream = API::Stream.new(name)
+          stream.unpause!
+          return ok render("streams/_pause_banner", banner_locals(stream)) if @request.params["banner"]
+
+          ok render("streams/_stream_row", { stream: row_locals(stream) })
+        end
 
+        def _table
+          streams = API::Stream.all.map { row_locals(_1) }
           ok render("streams/_table", { streams: streams })
         end
 
         def _info
           name = Rack::Utils.unescape(@request.params["name"])
-          state = API::Stream.new(name).info.merge(name:)
-          ok render("streams/_info", state)
+          stream = API::Stream.new(name)
+          ok render("streams/_info", stream.info.merge(name:, paused: stream.paused?))
+        end
+
+        private
+
+        def row_locals(stream)
+          state, config = stream.info.values
+          { name: stream.name, messages: state.messages, bytes: state.bytes,
+            first_seq: state.first_seq, last_seq: state.last_seq,
+            consumer_count: state.consumer_count,
+            subjects: config.subjects,
+            paused: stream.paused? }
+        end
+
+        def banner_locals(stream)
+          { name: stream.name, paused: stream.paused? }
         end
       end
     end

data/lib/cosmo/web/helpers/application.rb

@@ -8,6 +8,12 @@ module Cosmo
       module Application
         include Renderer
 
+        def render(template, locals = nil)
+          defaults = { request: @request }
+          locals = Hash(locals).merge(defaults)
+          erb(template, locals)
+        end
+
         def format_bytes(bytes)
           b = bytes.to_i
           return "0 B" if b.zero?
@@ -64,11 +70,16 @@ module Cosmo
         def current_page?(path)
           request_path = @request.path_info
           request_path = "/" if request_path.empty?
-          request_path == url_for(path)
+          request_path == path
         end
 
         def referrer?(path)
-          URI(@request.referrer).path == path
+          referrer_uri  = URI(@request.referrer)
+          referrer_path = referrer_uri.path
+          script_name   = @request.script_name
+          referrer_path = referrer_path.delete_prefix(script_name) if script_name && !script_name.empty?
+          referrer_path = "/" if referrer_path.empty?
+          referrer_path == path
         end
       end
     end

data/lib/cosmo/web/views/streams/_info.erb

@@ -17,6 +17,8 @@
   </article>
 </div>
 
+<%= render("streams/_pause_banner", { name: @name, paused: @paused }) %>
+
 <div class="nav">
   <a href="<%= url_for('/streams') %>"
      hx-get="<%= url_for('/streams') %>"
@@ -87,3 +89,4 @@
     <div class="subject-tag" style="padding: var(--space) var(--space-2x); font-size: 1rem;"><%= h(sub) %></div>
   <% end -%>
 </div>
+

data/lib/cosmo/web/views/streams/_pause_banner.erb

@@ -0,0 +1,17 @@
+<% if @paused -%>
+  <div id="pause-banner-<%= h(@name) %>" class="alert alert-warning" style="display:flex; align-items:center; justify-content:space-between; flex-wrap:wrap; gap:var(--space-2x);">
+    <span>&#9208; <strong>Stream is paused</strong> — consumers are not fetching new messages.</span>
+    <a hx-patch="<%= url_for('/streams/unpause', { name: u(@name), banner: 1 }) %>"
+       hx-target="#pause-banner-<%= h(@name) %>"
+       hx-swap="outerHTML"
+       class="btn btn-success">&#9654; Resume Stream</a>
+  </div>
+<% else -%>
+  <div id="pause-banner-<%= h(@name) %>" class="alert alert-success" style="display:flex; align-items:center; justify-content:space-between; flex-wrap:wrap; gap:var(--space-2x);">
+    <span>&#9654; <strong>Stream is active</strong> — consumers are fetching new messages.</span>
+    <a hx-patch="<%= url_for('/streams/pause', { name: u(@name), banner: 1 }) %>"
+       hx-target="#pause-banner-<%= h(@name) %>"
+       hx-swap="outerHTML"
+       class="btn btn-warning">&#9208; Pause Stream</a>
+  </div>
+<% end -%>

data/lib/cosmo/web/views/streams/_stream_row.erb

@@ -0,0 +1,42 @@
+<tr id="stream-row-<%= h(@stream[:name]) %>">
+  <td>
+    <a href="<%= url_for('/streams/info', { name: u(@stream[:name]) }) %>"
+       hx-get="<%= url_for('/streams/info', { name: u(@stream[:name]) }) %>"
+       hx-target="#content"
+       hx-push-url="true"
+       class="stream-link"><%= h(@stream[:name]) %></a>
+  </td>
+  <td><%= format_numbers(@stream[:messages]) %></td>
+  <td><%= format_bytes(@stream[:bytes]) %></td>
+  <td><%= @stream[:consumer_count] %></td>
+  <td>
+    <div class="subjects">
+      <% Array(@stream[:subjects]).each do |subject| -%>
+        <span class="subject-tag"><%= h(subject) %></span>
+      <% end -%>
+    </div>
+  </td>
+  <td><code><%= format_numbers(@stream[:first_seq]) %> &rarr; <%= format_numbers(@stream[:last_seq]) %></code></td>
+  <td>
+    <% if @stream[:paused] -%>
+      <span class="badge badge-warning">&#9208; Paused</span>
+    <% elsif @stream[:consumer_count].to_i > 0 -%>
+      <span class="badge badge-success">&#9654; Active</span>
+    <% else -%>
+      <span class="badge">No consumers</span>
+    <% end -%>
+  </td>
+  <td>
+    <% if @stream[:paused] -%>
+      <a hx-patch="<%= url_for('/streams/unpause', { name: u(@stream[:name]) }) %>"
+         hx-target="#stream-row-<%= h(@stream[:name]) %>"
+         hx-swap="outerHTML"
+         class="btn btn-success">&#9654; Resume</a>
+    <% else -%>
+      <a hx-patch="<%= url_for('/streams/pause', { name: u(@stream[:name]) }) %>"
+         hx-target="#stream-row-<%= h(@stream[:name]) %>"
+         hx-swap="outerHTML"
+         class="btn btn-warning">&#9208; Pause</a>
+    <% end -%>
+  </td>
+</tr>

data/lib/cosmo/web/views/streams/_table.erb

@@ -11,30 +11,13 @@
           <th>Consumers</th>
           <th>Subjects</th>
           <th>Sequence</th>
+          <th>Status</th>
+          <th>Actions</th>
         </tr>
       </thead>
       <tbody>
-        <% @streams.each do |s| -%>
-        <tr>
-          <td>
-            <a href="<%= url_for('/streams/info', { name: u(s[:name]) }) %>"
-               hx-get="<%= url_for('/streams/info', { name: u(s[:name]) }) %>"
-               hx-target="#content"
-               hx-push-url="true"
-               class="stream-link"><%= h(s[:name]) %></a>
-          </td>
-          <td><%= format_numbers(s[:messages]) %></td>
-          <td><%= format_bytes(s[:bytes]) %></td>
-          <td><%= s[:consumer_count] %></td>
-          <td>
-            <div class="subjects">
-              <% (s[:subjects] || []).each do |sub| -%>
-                <span class="subject-tag"><%= h(sub) %></span>
-              <% end -%>
-            </div>
-          </td>
-          <td><code><%= format_numbers(s[:first_seq]) %> &rarr; <%= format_numbers(s[:last_seq]) %></code></td>
-        </tr>
+        <% @streams.each do |stream| -%>
+          <%= render("streams/_stream_row", { stream: stream }) %>
         <% end -%>
       </tbody>
     </table>

data/lib/cosmo/web.rb

@@ -41,6 +41,8 @@ module Cosmo
                  in [:get,    "/streams/info"]          then [Controllers::Streams, :info]
                  in [:get,    "/streams/_table"]        then [Controllers::Streams, :_table]
                  in [:get,    "/streams/_info"]         then [Controllers::Streams, :_info]
+                 in [:patch,  "/streams/pause"]         then [Controllers::Streams, :pause]
+                 in [:patch,  "/streams/unpause"]       then [Controllers::Streams, :unpause]
                  in [:get,    "/actions"]               then [Controllers::Actions, :index]
                  in [:get,    "/assets/htmx.min.js.gz"] then serve("htmx.2.0.8.min.js.gz",
                                                                    "application/javascript",

data/sig/cosmo/api/stream.rbs

@@ -26,7 +26,7 @@ module Cosmo
 
       def retries: () -> ::Integer
 
-      def each: (?from: ::Integer?) { (Job) -> void } -> void
+      def each: () { (Job) -> void } -> void
 
       def messages: (?page: ::Integer?, ?limit: ::Integer?) -> Array[Job]
 
@@ -36,6 +36,12 @@ module Cosmo
 
       def delete: (::Integer seq) -> untyped
 
+      def pause!: () -> untyped
+
+      def unpause!: () -> untyped
+
+      def paused?: () -> bool
+
       private
 
       def client: () -> Client