pgbus 0.9.0 → 0.9.3

data/lib/pgbus/process/notify_listener.rb

@@ -0,0 +1,268 @@
+# frozen_string_literal: true
+
+module Pgbus
+  module Process
+    # Owns a single dedicated PG::Connection that LISTENs on the INSERT NOTIFY
+    # channel of every queue a Worker/Consumer reads, and fires a WakeSignal the
+    # moment any of them receives a row. This converts the worker/consumer loop
+    # from "blind-read every polling_interval" into "sleep until a real insert,
+    # poll only as a fallback" — eliminating the empty-read storm that dominates
+    # DB load on idle queues.
+    #
+    # pgmq-ruby's `wait_for_notify(queue, timeout:)` is single-queue and wraps
+    # the wait in `with_connection`, which only watches one channel and holds the
+    # pooled connection for the whole wait. Neither fits a worker that reads N
+    # queues on a small shared pool. So we own ONE raw PG::Connection and
+    # hand-roll per-channel LISTEN on it.
+    #
+    # A persistent LISTEN connection silently dies under a transaction-pool
+    # PgBouncer (LISTEN does not survive COMMIT boundaries). Point this
+    # connection at a DIRECT port via `config.worker_notify_*` overrides.
+    # The health-check-on-timeout catches a connection killed out from under us
+    # and re-LISTENs everything.
+    #
+    # NOTIFY channel naming (pgmq trigger): PG_NOTIFY('pgmq.' || table || '.' ||
+    # TG_OP). For queue `pgbus_default` the table is `q_pgbus_default`, so the
+    # channel is `pgmq.q_pgbus_default.INSERT`.
+    #
+    # Thread safety: @running, @conn, and @listening_to are guarded by
+    # @state_mutex. The listener thread owns @conn during wait_for_notify (a
+    # blocking IO call where the mutex MUST NOT be held), so wait_once reads
+    # the connection out of the mutex first and operates on a local. Reconnect
+    # publishes the new connection + channel set under the mutex.
+    class NotifyListener
+      CHANNEL_PREFIX = "pgmq.q_"
+      CHANNEL_SUFFIX = ".INSERT"
+
+      RECONNECT_BACKOFF_SECONDS = 0.5
+
+      def initialize(physical_queues:, on_wake:, connection_options:,
+                     health_check_ms: 1000, logger: Pgbus.logger)
+        @physical_queues = Array(physical_queues)
+        @on_wake = on_wake
+        @connection_options = connection_options
+        @health_check_ms = health_check_ms
+        @logger = logger
+        @state_mutex = Mutex.new
+        @listening_to = Set.new
+        @commands = Queue.new
+        @running = false
+        @thread = nil
+        @conn = nil
+      end
+
+      def listening_to
+        @state_mutex.synchronize { @listening_to.dup }
+      end
+
+      def start
+        @state_mutex.synchronize do
+          return self if @running
+
+          @running = true
+        end
+        @physical_queues.each { |q| @commands << [:listen, q] }
+        @thread = Thread.new { run_loop }
+        self
+      end
+
+      def stop
+        conn_to_close = nil
+        @state_mutex.synchronize do
+          return self unless @running
+
+          @running = false
+          conn_to_close = @conn
+        end
+        @commands << [:stop]
+        # Interrupt the blocking wait by closing the socket; the rescue in
+        # wait_once sees @running == false and exits cleanly.
+        begin
+          conn_to_close&.close if conn_to_close.respond_to?(:close)
+        rescue StandardError
+          nil
+        end
+        @thread&.join(5)
+        @thread = nil
+        self
+      end
+
+      def add_queue(physical_queue)
+        @commands << [:listen, physical_queue]
+      end
+
+      def remove_queue(physical_queue)
+        @commands << [:unlisten, physical_queue]
+      end
+
+      private
+
+      def running?
+        @state_mutex.synchronize { @running }
+      end
+
+      def run_loop
+        conn = build_connection
+        @state_mutex.synchronize { @conn = conn }
+        drain_commands
+
+        loop do
+          break unless running?
+
+          drain_commands
+          break unless running?
+
+          wait_once
+        end
+      rescue StandardError => e
+        @logger.error { "[Pgbus::NotifyListener] fatal: #{e.class}: #{e.message}" } if running?
+      ensure
+        # Clear @running so #start can spawn a fresh thread after a fatal exit
+        # (e.g. build_connection raising at boot). Without this, the dead
+        # thread's @running stays true and #start returns early forever.
+        @state_mutex.synchronize { @running = false }
+        safe_unlisten_all
+        safe_close
+      end
+
+      def wait_once
+        conn = @state_mutex.synchronize { @conn }
+        return reconnect! unless conn
+
+        timeout_s = @health_check_ms / 1000.0
+        got_notify = conn.wait_for_notify(timeout_s) do |_channel, _pid, _payload|
+          @on_wake.call
+        end
+        run_health_check(conn) unless got_notify
+      rescue IOError, PG::Error => e
+        return unless running?
+
+        @logger.warn { "[Pgbus::NotifyListener] connection error (#{e.class}: #{e.message}) — reconnecting" }
+        reconnect!
+      end
+
+      def drain_commands
+        loop do
+          cmd = @commands.pop(true)
+          case cmd[0]
+          when :listen   then do_listen(cmd[1])
+          when :unlisten then do_unlisten(cmd[1])
+          when :stop
+            @state_mutex.synchronize { @running = false }
+            return
+          end
+        rescue ThreadError
+          return
+        end
+      end
+
+      def do_listen(physical_queue)
+        channel = channel_for(physical_queue)
+        conn = @state_mutex.synchronize do
+          return if @listening_to.include?(channel)
+
+          @conn
+        end
+        return unless conn
+
+        conn.exec(%(LISTEN "#{channel}"))
+        @state_mutex.synchronize { @listening_to.add(channel) }
+      end
+
+      def do_unlisten(physical_queue)
+        channel = channel_for(physical_queue)
+        conn = @state_mutex.synchronize do
+          return unless @listening_to.include?(channel)
+
+          @conn
+        end
+        return unless conn
+
+        conn.exec(%(UNLISTEN "#{channel}"))
+        @state_mutex.synchronize { @listening_to.delete(channel) }
+      end
+
+      def run_health_check(conn)
+        conn.exec("SELECT 1")
+      end
+
+      # Retry reconnect until either we succeed (new conn + every channel
+      # re-LISTENed) or @running flips to false. Without the loop, a single
+      # PG::Error during build/LISTEN left @conn nil and the listener degraded
+      # silently — wait_once would re-enter and fail forever or run with an
+      # incomplete subscription set.
+      def reconnect!
+        channels = @state_mutex.synchronize { @listening_to.to_a }
+        loop do
+          return unless running?
+
+          safe_close
+          new_conn = nil
+          begin
+            new_conn = build_connection
+            channels.each { |channel| new_conn.exec(%(LISTEN "#{channel}")) }
+          rescue PG::Error => e
+            # build_connection may have succeeded before a later LISTEN raised.
+            # Without this close, the partially-built conn is orphaned and the
+            # next retry just allocates another one — leaking PG connections on
+            # repeated failures.
+            close_quietly(new_conn)
+            @logger.error { "[Pgbus::NotifyListener] reconnect failed: #{e.class}: #{e.message}" }
+            sleep RECONNECT_BACKOFF_SECONDS
+            next
+          end
+
+          @state_mutex.synchronize do
+            @conn = new_conn
+            @listening_to = Set.new(channels)
+          end
+          return
+        end
+      end
+
+      def build_connection
+        require "pg" unless defined?(::PG::Connection)
+        case @connection_options
+        when String then ::PG.connect(@connection_options)
+        when Hash   then ::PG.connect(**@connection_options)
+        else
+          raise Pgbus::ConfigurationError,
+                "NotifyListener cannot build a PG connection from #{@connection_options.class}. " \
+                "Set worker_notify_database_url / worker_notify_host / worker_notify_port, " \
+                "or a base database_url, so the listener owns a dedicated connection."
+        end
+      end
+
+      def safe_unlisten_all
+        channels, conn = @state_mutex.synchronize { [@listening_to.to_a, @conn] }
+        channels.each do |channel|
+          conn&.exec(%(UNLISTEN "#{channel}"))
+        rescue PG::Error
+          nil
+        end
+        @state_mutex.synchronize { @listening_to.clear }
+      end
+
+      def safe_close
+        conn = @state_mutex.synchronize do
+          c = @conn
+          @conn = nil
+          c
+        end
+        close_quietly(conn)
+      end
+
+      # Close an unpublished PG::Connection (one that never made it into @conn,
+      # e.g. a half-built reconnect attempt where LISTEN raised). Best-effort.
+      def close_quietly(conn)
+        conn&.close if conn.respond_to?(:close)
+      rescue StandardError
+        nil
+      end
+
+      def channel_for(physical_queue)
+        "#{CHANNEL_PREFIX}#{physical_queue}#{CHANNEL_SUFFIX}"
+      end
+    end
+  end
+end

data/lib/pgbus/process/worker.rb

@@ -13,6 +13,7 @@ module Pgbus
                      single_active_consumer: false, consumer_priority: 0,
                      execution_mode: :threads, group_mode: nil)
         @queues = Array(queues)
+        @initial_queues = @queues.dup.freeze
         @wildcard = @queues.include?("*")
         @threads = threads
         @config = config
@@ -49,6 +50,7 @@ module Pgbus
         )
         @circuit_breaker = Pgbus::CircuitBreaker.new(config: config)
         @queue_lock = QueueLock.new if @single_active_consumer
+        @notify_listener = nil
       end
 
       def stats
@@ -66,14 +68,17 @@ module Pgbus
         }.merge(@pool.metadata)
       end
 
+      NOTIFY_FALLBACK_POLL_SECONDS = 15
+
       def run
         setup_signals
         start_heartbeat
         resolve_wildcard_queues
+        start_notify_listener
         @lifecycle.transition_to!(:running)
         Pgbus.logger.info do
           "[Pgbus] Worker started: queues=#{queues.join(",")} threads=#{threads} " \
-            "mode=#{@execution_mode} pid=#{::Process.pid}"
+            "mode=#{@execution_mode} notify_wakeup=#{notify_wakeup?} pid=#{::Process.pid}"
         end
 
         loop do
@@ -117,7 +122,7 @@ module Pgbus
       private
 
       def claim_and_execute
-        poll_interval = effective_polling_interval
+        poll_interval = wake_timeout
 
         idle = @pool.available_capacity
         return @wake_signal.wait(timeout: poll_interval) if idle <= 0
@@ -147,9 +152,19 @@ module Pgbus
       # Returns an array of [queue_name, message] pairs so we always know
       # which queue each message came from.
       def fetch_messages(qty)
+        restore_evicted_queues if queues.empty? && !@wildcard
+
         active_queues = queues.reject { |q| @circuit_breaker.paused?(q) }
         active_queues = active_queues.select { |q| @queue_lock.try_lock(q) } if @single_active_consumer
-        return [] if active_queues.empty?
+
+        if active_queues.empty?
+          Pgbus.logger.debug do
+            paused = queues.select { |q| @circuit_breaker.paused?(q) }
+            "[Pgbus] Worker fetch: all queues filtered — queues=#{queues.join(",")} " \
+              "paused=#{paused.join(",")}"
+          end
+          return []
+        end
 
         if priority_enabled?
           fetch_prioritized(active_queues, qty)
@@ -295,6 +310,7 @@ module Pgbus
           Pgbus.logger.info { "[Pgbus] Wildcard queue '*' resolved to: #{@queues.join(", ")}" } unless @last_wildcard_resolve
         end
         @last_wildcard_resolve = monotonic_now
+        sync_notify_listener_queues
       rescue StandardError => e
         Pgbus.logger.error { "[Pgbus] Failed to resolve wildcard queues: #{e.message} — falling back to default" }
         @queues = [config.default_queue] unless @last_wildcard_resolve
@@ -321,6 +337,15 @@ module Pgbus
           end
         end
         Pgbus.logger.error { "[Pgbus] Queue table missing: #{error.message}" }
+        restore_evicted_queues if @queues.empty? && !@wildcard
+      end
+
+      def restore_evicted_queues
+        @queues = @initial_queues.dup
+        Pgbus.logger.warn do
+          "[Pgbus] Worker queue list was empty after eviction — " \
+            "restoring initial queues: #{@queues.join(", ")}"
+        end
       end
 
       def detect_zombie(queue_name, message)
@@ -401,6 +426,16 @@ module Pgbus
         end
       end
 
+      def notify_wakeup?
+        config.respond_to?(:worker_notify_wakeup?) && config.worker_notify_wakeup?
+      end
+
+      def wake_timeout
+        return effective_polling_interval unless notify_wakeup? && @notify_listener
+
+        [effective_polling_interval, config.polling_interval, NOTIFY_FALLBACK_POLL_SECONDS].max
+      end
+
       def effective_polling_interval
         return config.polling_interval if @consumer_priority.zero?
 
@@ -413,6 +448,43 @@ module Pgbus
         config.polling_interval
       end
 
+      def start_notify_listener
+        return unless notify_wakeup?
+
+        @notify_listener = NotifyListener.new(
+          physical_queues: physical_queue_names,
+          on_wake: -> { @wake_signal.notify! },
+          connection_options: config.worker_notify_connection_options,
+          health_check_ms: (config.polling_interval * 1000).to_i.clamp(250, 5_000),
+          logger: Pgbus.logger
+        ).start
+      rescue StandardError => e
+        @notify_listener = nil
+        Pgbus.logger.error do
+          "[Pgbus] NotifyListener failed to start, falling back to polling: #{e.class}: #{e.message}"
+        end
+      end
+
+      def sync_notify_listener_queues
+        return unless @notify_listener
+
+        desired = physical_queue_names.to_set
+        current = @notify_listener.listening_to.to_set { |c| channel_to_physical(c) }
+        (desired - current).each { |q| @notify_listener.add_queue(q) }
+        (current - desired).each { |q| @notify_listener.remove_queue(q) }
+      rescue StandardError => e
+        Pgbus.logger.warn { "[Pgbus] NotifyListener queue sync failed: #{e.class}: #{e.message}" }
+      end
+
+      def physical_queue_names
+        prefix = "#{config.queue_prefix}_"
+        queues.map { |q| "#{prefix}#{q}" }
+      end
+
+      def channel_to_physical(channel)
+        channel.delete_prefix(NotifyListener::CHANNEL_PREFIX).delete_suffix(NotifyListener::CHANNEL_SUFFIX)
+      end
+
       def start_heartbeat
         @heartbeat = Heartbeat.new(
           kind: "worker",
@@ -427,6 +499,7 @@ module Pgbus
 
       def shutdown
         Pgbus.logger.info { "[Pgbus] Worker draining thread pool..." }
+        @notify_listener&.stop
         @pool.shutdown
         @pool.wait_for_termination(30)
         @stat_buffer&.stop

data/lib/pgbus/streams/coalescer.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require "concurrent"
+
+module Pgbus
+  module Streams
+    # Publish-side coalescing for high-frequency broadcasts (issue #171).
+    #
+    # A chatty reactive component — a live cursor, a typing indicator, a
+    # progress bar — can fan out many small broadcasts per second. For
+    # per-keystroke / per-frame updates that's wasteful: every frame
+    # becomes a PGMQ insert (or a NOTIFY) and a fan-out to every connection.
+    #
+    # The Coalescer batches per (stream, target) within a short window and
+    # flushes only the *latest* payload, so superseded frames never hit the
+    # bus at all. This is last-write-wins and is only safe for idempotent
+    # actions (replace / update of a stable target) — which is exactly the
+    # high-frequency case. It is strictly opt-in (`coalesce:` on broadcast).
+    #
+    # Debounce semantics: the FIRST submit for a (stream, target) schedules
+    # a flush `window_ms` later; subsequent submits within that window only
+    # overwrite the buffered payload. So latency is bounded to one window
+    # and a continuous stream of updates can't starve the flush (it is a
+    # trailing-edge-with-max-wait debounce, not a resettable one).
+    #
+    # Thread-safe: many request threads may submit concurrently. The buffer
+    # and the per-key pending-flush set are guarded by a single mutex; the
+    # flush itself runs off the mutex on the scheduler's thread.
+    class Coalescer
+      # Default coalescing window when `coalesce: true` is passed without an
+      # explicit millisecond value.
+      DEFAULT_WINDOW_MS = 50
+
+      Entry = Struct.new(:payload, :opts)
+
+      # scheduler: responds to `schedule(delay_seconds) { ... }`. Defaults
+      #   to a Concurrent::ScheduledTask-backed scheduler.
+      # flush: ->(stream_name:, target:, payload:, opts:) called once per
+      #   window per key with the latest buffered frame.
+      def initialize(flush:, scheduler: nil)
+        @flush = flush
+        @scheduler = scheduler || ScheduledTaskScheduler.new
+        @mutex = Mutex.new
+        @buffer = {}  # key => Entry (latest)
+        @pending = {} # key => true while a flush is scheduled
+      end
+
+      # Buffers a frame for (stream_name, target). Overwrites any frame
+      # already buffered for the same key within the current window. The
+      # first submit per window schedules the flush.
+      def submit(stream_name:, target:, payload:, opts:, window_ms: DEFAULT_WINDOW_MS)
+        key = [stream_name, target]
+        schedule = false
+
+        @mutex.synchronize do
+          @buffer[key] = Entry.new(payload, opts)
+          unless @pending[key]
+            @pending[key] = true
+            schedule = true
+          end
+        end
+
+        @scheduler.schedule(window_ms / 1000.0) { flush_key(key, stream_name, target) } if schedule
+      end
+
+      private
+
+      def flush_key(key, stream_name, target)
+        entry = @mutex.synchronize do
+          @pending.delete(key)
+          @buffer.delete(key)
+        end
+        return unless entry
+
+        @flush.call(stream_name: stream_name, target: target, payload: entry.payload, opts: entry.opts)
+      end
+
+      # Default scheduler backed by Concurrent::ScheduledTask. Kept as a
+      # tiny adapter so the Coalescer can be unit-tested with a synchronous
+      # fake scheduler (no real timers, no sleeps).
+      class ScheduledTaskScheduler
+        def schedule(delay_seconds, &)
+          Concurrent::ScheduledTask.execute(delay_seconds, &)
+        end
+      end
+    end
+  end
+end

data/lib/pgbus/streams/envelope.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "json"
+
 module Pgbus
   module Streams
     # Encodes Server-Sent Events frames per https://html.spec.whatwg.org/multipage/server-sent-events.html.
@@ -29,13 +31,30 @@ module Pgbus
         raise ArgumentError, "id is required" if id.nil?
         raise ArgumentError, "event is required" if event.nil? || event.to_s.empty?
 
-        "id: #{id}\nevent: #{event}\ndata: #{strip_newlines(data.to_s)}\n\n"
+        # Strip newlines from BOTH event and data, not just data: each is
+        # interpolated into its own SSE field line, so an unescaped \r/\n in
+        # either would terminate the field early and let a crafted value
+        # inject extra SSE fields (a forged id:/data:) into the frame.
+        "id: #{id}\nevent: #{strip_newlines(event.to_s)}\ndata: #{strip_newlines(data.to_s)}\n\n"
       end
 
       def self.comment(text)
         ": #{strip_newlines(text.to_s)}\n\n"
       end
 
+      # Emits a `pgbus:connected` frame carrying the server-minted
+      # connection id as JSON. Sent once, right after the open handshake,
+      # so the page can read its own connection id and send it back as
+      # `X-Pgbus-Connection` on action requests (actor-echo suppression,
+      # issue #165). Deliberately omits an `id:` line: this is connection
+      # metadata, not a broadcast, and giving it a cursor id would corrupt
+      # the client's Last-Event-ID replay position on reconnect.
+      def self.connected(id:)
+        raise ArgumentError, "id is required" if id.nil? || id.to_s.empty?
+
+        "event: pgbus:connected\ndata: #{JSON.generate({ connectionId: id.to_s })}\n\n"
+      end
+
       def self.retry_directive(milliseconds)
         unless milliseconds.is_a?(Integer) && !milliseconds.negative?
           raise ArgumentError, "retry must be a non-negative integer (got #{milliseconds.inspect})"

data/lib/pgbus/streams/key.rb

@@ -63,9 +63,42 @@ module Pgbus
       # `to_stream_key`/`to_gid_param` implementation that forgot to
       # sanitize) raise an ArgumentError at the call site.
       def stream_key(*parts, digest_bits: DEFAULT_DIGEST_BITS)
-        fragments = Array(parts).flatten.map { |part| normalize(part, digest_bits: digest_bits) }
+        flattened = Array(parts).flatten
+
+        # Idempotency for an already-built key: a single String argument
+        # is treated as a pre-built pgbus stream key and returned
+        # unchanged (after the budget check). This lets a consumer hold
+        # one `stream_key` value and pass it to both `turbo_stream_from`
+        # and the broadcaster without the colon separator guard raising
+        # on the second call. The guard only protects against ambiguous
+        # *joins* (`stream_key('a:b', :c)` vs `stream_key('a', 'b:c')`),
+        # and there is no second fragment here to collapse against, so the
+        # hazard cannot arise. Symbols and records are NOT keys — a colon
+        # in those never came from `stream_key` and stays a mistake.
+        return stream_key!(flattened.first) if flattened.length == 1 && flattened.first.is_a?(String)
+
+        fragments = flattened.map { |part| normalize(part, digest_bits: digest_bits) }
         fragments.each { |fragment| reject_colons!(fragment) }
-        key = fragments.join(":")
+        validate_budget!(fragments.join(":"))
+      end
+
+      # Accepts an already-built stream key verbatim, skipping the
+      # per-fragment colon guard (a pre-built key legitimately contains
+      # ':' separators). Still enforces the queue-name budget so an
+      # oversized key fails at the call site rather than deep inside
+      # Client#ensure_stream_queue. Use this when you hold a key string
+      # and want to be explicit that no re-keying should happen — e.g.
+      # passing the same value to `turbo_stream_from` and a broadcaster.
+      def stream_key!(key)
+        raise ArgumentError, "stream_key! key must be a String, got #{key.class}" unless key.is_a?(String)
+
+        validate_budget!(key)
+      end
+
+      # Returns the key when it fits the pgbus queue-name budget; raises
+      # ArgumentError with an actionable message otherwise. Shared by
+      # `stream_key` and `stream_key!` so both paths fail identically.
+      def validate_budget!(key)
         budget = queue_name_budget
         return key if key.length <= budget
 

data/lib/pgbus/streams/renderer.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require "cgi"
+
+module Pgbus
+  module Streams
+    # Turns a renderable into a complete `<turbo-stream>` action tag,
+    # ready to hand to Stream#broadcast. This centralises the off-request
+    # render + tag-building that every consumer would otherwise stitch
+    # together by hand (the #1 footgun in server-driven UI: rendering a
+    # component outside a request without a usable view context).
+    #
+    # pgbus deliberately has no hard dependency on turbo-rails, ActionView,
+    # or Phlex, so this builder is self-contained and matches Turbo's wire
+    # format directly. The browser's Turbo runtime consumes the tag; the
+    # exact string is the contract, not any particular Ruby library.
+    #
+    # Renderable resolution (first match wins):
+    #   - String              → used verbatim (already-rendered markup)
+    #   - responds to :call   → Phlex::HTML#call (the issue's example shape)
+    #   - responds to :render_in → ViewComponent / phlex-rails
+    #     (`render_in(view_context)`; a nil context is passed because
+    #     off-request there is no controller — components that need URL
+    #     helpers should be rendered by the app and the string passed in)
+    #   - else                → to_s
+    #
+    # Tag format mirrors Turbo::Streams::TagBuilder:
+    #   - content actions wrap the markup in a <template>
+    #   - content-less actions (remove) emit no <template>
+    module Renderer
+      # Turbo stream actions that carry no content (no <template> wrapper).
+      CONTENTLESS_ACTIONS = %w[remove].freeze
+
+      module_function
+
+      # Builds a `<turbo-stream action target><template>...</template></turbo-stream>`
+      # string. `renderable` may be nil for content-less actions.
+      def turbo_stream_tag(action:, target:, renderable: nil)
+        raise ArgumentError, "target is required" if target.nil? || target.to_s.empty?
+
+        action = action.to_s
+        attrs = %(action="#{escape(action)}" target="#{escape(target)}")
+
+        return "<turbo-stream #{attrs}></turbo-stream>" if CONTENTLESS_ACTIONS.include?(action)
+
+        content = render(renderable)
+        "<turbo-stream #{attrs}><template>#{content}</template></turbo-stream>"
+      end
+
+      # Resolves a renderable to an HTML string. See module docs for the
+      # resolution order. Returns "" for nil (a content action with no
+      # renderable still emits an empty <template>).
+      def render(renderable)
+        return "" if renderable.nil?
+        return renderable if renderable.is_a?(String)
+        return renderable.call.to_s if renderable.respond_to?(:call)
+        return renderable.render_in(nil).to_s if renderable.respond_to?(:render_in)
+
+        renderable.to_s
+      end
+
+      def escape(value)
+        CGI.escape_html(value.to_s)
+      end
+    end
+  end
+end