pgbus 0.17.1 → 0.17.3

data/lib/pgbus/web/queue_summary.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module Pgbus
+  module Web
+    # Turns one queue's facts into the sentences an operator reads at the top
+    # of its page: why it is paused, who drains it, what is waiting, and which
+    # priority level it is (issue #491).
+    #
+    # Pure like JobState: it takes queue_detail, queue_pause_state and
+    # queue_drainers as given and does no I/O. Each Line carries a translation
+    # key under pgbus.queues.show.summary, raw args (Times under :ago/:time,
+    # seconds under :age) and a tone the view maps to colours.
+    module QueueSummary
+      Line = Data.define(:key, :args, :tone)
+
+      PRIORITY_LEVEL = /_p(\d+)\z/
+      FAILURES = /(\d+) consecutive failures/
+      BACKLOG_KEYS = %w[backlog backlog_parked_only empty].freeze
+
+      module_function
+
+      def present(detail, pause_state, drainers, max_retries:)
+        name = detail[:name].to_s
+        dlq = name.end_with?(Pgbus::DEAD_LETTER_SUFFIX)
+        [
+          pause_line(pause_state),
+          drain_line(dlq, detail, drainers, max_retries),
+          (backlog_line(detail) unless dlq || drainers[:stream]),
+          priority_line(drainers)
+        ].compact
+      end
+
+      def pause_line(state)
+        return unless state[:paused]
+
+        if state[:resumes_at]
+          failures = state[:reason].to_s[FAILURES, 1].to_i
+          return line("paused_circuit_breaker", :yellow, ago: state[:paused_at], failures: failures,
+                                                         time: state[:resumes_at], trip: state[:trip_count].to_i)
+        end
+        return line("paused_operator_no_reason", :yellow, ago: state[:paused_at]) if state[:reason].to_s.strip.empty?
+
+        line("paused_operator", :yellow, ago: state[:paused_at], reason: state[:reason])
+      end
+
+      # First match wins, as in JobState#ready_overlay: what the queue is
+      # explains everything below it, then whether anything is configured to
+      # drain it, and only then whether a worker is alive.
+      def drain_line(dlq, detail, drainers, max_retries)
+        return line("dlq", :gray, logical: drainers[:logical], max: max_retries) if dlq
+        return line("stream", :gray) if drainers[:stream]
+
+        if drainers[:handler]
+          consumers = drainers[:live_consumers].to_i
+          return line("handler", :gray, count: consumers) if consumers.positive?
+
+          return line("no_consumers", :red, count: detail[:queue_visible_length].to_i)
+        end
+
+        capsules = Array(drainers[:capsules])
+        live = drainers[:live_workers].to_i
+        if capsules.empty? && !drainers[:wildcard]
+          # Capsules from `pgbus --queues` never reach the web process's
+          # configuration: a healthy heartbeat for this queue outranks it.
+          return live.zero? ? line("not_drained", :red) : line("drained_live", :gray, count: live)
+        end
+        return line("no_workers", :red, count: detail[:queue_visible_length].to_i) if live.zero?
+        return line("drained_wildcard", :gray, count: live) if capsules.empty?
+
+        line("drained_by", :gray, capsules: capsules.join(", "), count: live)
+      end
+
+      def backlog_line(detail)
+        visible = detail[:queue_visible_length].to_i
+        parked = detail[:parked_length].to_i
+        if visible.positive?
+          line("backlog", :gray, visible: visible, age: detail[:oldest_claimable_age_sec], parked: parked)
+        elsif parked.positive?
+          line("backlog_parked_only", :gray, parked: parked)
+        else
+          line("empty", :gray)
+        end
+      end
+
+      def priority_line(drainers)
+        level = drainers[:priority_level]
+        return unless level
+
+        line("priority_level", :gray, level: level, logical: drainers[:logical])
+      end
+
+      # The one line a queue row has room for (the home page's queues table,
+      # issue #492): whatever needs attention (a pause, nothing draining it),
+      # else what is waiting, else what the queue is.
+      def headline(lines)
+        lines.find { |l| l.tone != :gray } || lines.find { |l| BACKLOG_KEYS.include?(l.key) } || lines.first
+      end
+
+      def line(key, tone, **args)
+        Line.new(key: key, args: args, tone: tone)
+      end
+    end
+  end
+end

data/lib/pgbus/web/stream_app.rb

@@ -31,6 +31,9 @@ module Pgbus
     # full request lifecycle.
     class StreamApp
       PATH_PREFIX = "/pgbus/streams"
+      # The client's per-tab presence seat (?seat=, issue #515): an opaque id
+      # minted by <pgbus-stream-source presence>. Anything else is dropped.
+      SEAT_FORMAT = /\A[A-Za-z0-9_-]{1,64}\z/
       # EventSource reconnect delay handed to the streams_test_mode stub (24h).
       TEST_MODE_RETRY_MS = 86_400_000
       private_constant :PATH_PREFIX
@@ -64,14 +67,16 @@ module Pgbus
         cursor = parse_cursor(env, request)
         return bad_request("invalid cursor: #{cursor}") if cursor.is_a?(String)
 
+        seat = parse_seat(request)
+
         return test_mode_stub if config.streams_test_mode
 
         return over_capacity if streamer.registry.size >= config.streams_max_connections
 
         if config.streams_falcon_streaming_body
-          streaming_body_response(stream_name: stream_name, since_id: cursor, context: context)
+          streaming_body_response(stream_name: stream_name, since_id: cursor, context: context, seat: seat)
         elsif env["rack.hijack?"]
-          hijack_and_register(env, stream_name: stream_name, since_id: cursor, context: context)
+          hijack_and_register(env, stream_name: stream_name, since_id: cursor, context: context, seat: seat)
         else
           unsupported_server
         end
@@ -114,7 +119,12 @@ module Pgbus
         e.message
       end
 
-      def hijack_and_register(env, stream_name:, since_id:, context: nil)
+      def parse_seat(request)
+        seat = request.params["seat"]
+        seat if seat.is_a?(String) && seat.ascii_only? && SEAT_FORMAT.match?(seat)
+      end
+
+      def hijack_and_register(env, stream_name:, since_id:, context: nil, seat: nil)
         # Rack hijack is a one-time transition per the Rack spec. Call
         # once, use the return value, and fall back to the side-effect
         # `rack.hijack_io` variable only if the return was nil (some
@@ -133,14 +143,15 @@ module Pgbus
           since_id: since_id,
           writer: Pgbus::Web::Streamer::IoWriter,
           write_deadline_ms: config.streams_write_deadline_ms,
-          context: context
+          context: context,
+          seat: seat
         )
         streamer.register(connection)
 
         [-1, {}, []]
       end
 
-      def streaming_body_response(stream_name:, since_id:, context: nil)
+      def streaming_body_response(stream_name:, since_id:, context: nil, seat: nil)
         require "protocol/http/body/writable" unless defined?(::Protocol::HTTP::Body::Writable)
         require_relative "streamer/falcon_connection" unless defined?(Pgbus::Web::Streamer::FalconConnection)
 
@@ -159,7 +170,8 @@ module Pgbus
           body: body,
           since_id: since_id,
           write_deadline_ms: config.streams_write_deadline_ms,
-          context: context
+          context: context,
+          seat: seat
         )
         streamer.register(connection)
 

data/lib/pgbus/web/streamer/connection.rb

@@ -14,10 +14,15 @@ module Pgbus
       # the client-side leg of the replay-race fix (§6.5 of the design doc).
       class Connection
         attr_reader :id, :stream_name, :io, :mutex, :context
+        # The client's per-tab presence seat (?seat=), or nil (issue #515).
+        attr_reader :seat
         # The presence member id this connection auto-joined as, or nil for
         # non-presence streams / anonymous connections. Set by the
         # Dispatcher on connect; read on disconnect and heartbeat touch.
         attr_accessor :presence_member
+        # True when presence_member joined as a seat row, false when as a
+        # member-keyed row (table not yet migrated). Leave follows the join.
+        attr_accessor :presence_seat
 
         # last_msg_id_sent is the ONE field whose writer can cross threads: with
         # streams_writer_threads > 0 (issue #321) the OutboundPump worker thread
@@ -31,7 +36,7 @@ module Pgbus
           @last_msg_id_sent.get
         end
 
-        def initialize(id:, stream_name:, io:, since_id:, writer:, write_deadline_ms:, context: nil)
+        def initialize(id:, stream_name:, io:, since_id:, writer:, write_deadline_ms:, context: nil, seat: nil)
           @id = id
           @stream_name = stream_name
           @io = io
@@ -50,6 +55,7 @@ module Pgbus
           # registry when evaluating visible_to predicates. Defaults to
           # nil for tests that don't need audience filtering.
           @context = context
+          @seat = seat
         end
 
         # deadline_ms defaults to the connection's own write deadline so every

data/lib/pgbus/web/streamer/falcon_connection.rb

@@ -13,7 +13,12 @@ module Pgbus
       # is fiber-safe under Falcon's scheduler.
       class FalconConnection
         attr_reader :id, :stream_name, :io, :mutex, :context
+        # The client's per-tab presence seat (?seat=), or nil (issue #515).
+        attr_reader :seat
         attr_accessor :presence_member
+        # True when presence_member joined as a seat row, false when as a
+        # member-keyed row (table not yet migrated). Leave follows the join.
+        attr_accessor :presence_seat
 
         # last_msg_id_sent mirrors Connection's cross-thread cursor (issue #321):
         # a Concurrent::AtomicReference so the OutboundPump worker's advance and
@@ -23,7 +28,7 @@ module Pgbus
           @last_msg_id_sent.get
         end
 
-        def initialize(id:, stream_name:, body:, since_id:, write_deadline_ms:, context: nil)
+        def initialize(id:, stream_name:, body:, since_id:, write_deadline_ms:, context: nil, seat: nil)
           @id = id
           @stream_name = stream_name
           @body = body
@@ -37,6 +42,7 @@ module Pgbus
           @created_at = monotonic
           @last_write_at = @created_at
           @context = context
+          @seat = seat
         end
 
         # deadline_ms is accepted for duck-type parity with Connection#enqueue

data/lib/pgbus/web/streamer/heartbeat.rb

@@ -26,13 +26,18 @@ module Pgbus
       # the Connection's own mutex, so concurrent dispatcher + heartbeat
       # writes are safe.
       class Heartbeat
-        def initialize(registry:, dispatch_queue:, interval:, idle_timeout:, logger: Pgbus.logger, clock: nil)
+        # presence_expiry: true (streams_presence_patterns is set) posts the
+        # presence touch every tick, even with no presence connection here,
+        # so the dispatcher can expire seats left by other processes.
+        def initialize(registry:, dispatch_queue:, interval:, idle_timeout:, logger: Pgbus.logger, clock: nil,
+                       presence_expiry: false)
           @registry = registry
           @queue = dispatch_queue
           @interval = interval
           @idle_timeout = idle_timeout
           @logger = logger
           @clock = clock || -> { ::Process.clock_gettime(::Process::CLOCK_MONOTONIC) }
+          @presence_expiry = presence_expiry
           @running = false
           @thread = nil
           @wake = ConditionVariable.new
@@ -122,9 +127,10 @@ module Pgbus
         # Posts one batched touch per tick so the dispatcher (which owns AR
         # connection release) refreshes last_seen_at for live presence
         # members, keeping them out of the sweeper. No message when no
-        # connection has presence — avoids waking the dispatcher for nothing.
+        # connection has presence and seat expiry is off — avoids waking the
+        # dispatcher for nothing.
         def enqueue_presence_touch(connections)
-          return if connections.empty?
+          return if connections.empty? && !@presence_expiry
 
           @queue << StreamEventDispatcher::PresenceTouchMessage.new(connections: connections)
         end

data/lib/pgbus/web/streamer/instance.rb

@@ -74,7 +74,8 @@ module Pgbus
             dispatch_queue: @dispatch_queue,
             interval: @config.streams_heartbeat_interval,
             idle_timeout: @config.streams_idle_timeout,
-            logger: @logger
+            logger: @logger,
+            presence_expiry: Array(@config.streams_presence_patterns).any?
           )
           @started = false
           @shutdown_mutex = Mutex.new

data/lib/pgbus/web/streamer/presence_tracker.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+module Pgbus
+  module Web
+    module Streamer
+      # Connection-driven presence (issues #169, #515), run on the
+      # StreamEventDispatcher thread, which owns AR connection release.
+      #
+      # On a seat table (Pgbus::Streams::Presence.seats_supported?) every SSE
+      # connection is its own row, keyed by connection id and carrying the
+      # client's seat; two tabs of one member are two rows. On an older
+      # table it falls back to one member-keyed row, as before.
+      #
+      # The heartbeat posts a PresenceTouchMessage each tick; #touch refreshes
+      # the live seats, re-joins any whose row was expired while the
+      # connection stayed open, and expires silent seats across all streams
+      # (rows of crashed processes included) at most every min_ttl / 2 after
+      # a successful sweep.
+      #
+      # Each connection remembers whether it joined as a seat or as a
+      # member-keyed row, so a table migrated while it is open still has
+      # its row removed on leave (and converted to a seat on the next touch).
+      #
+      # Every failure is logged and swallowed: a presence DB hiccup must not
+      # knock a live SSE connection out of the registry.
+      class PresenceTracker
+        def initialize(config:, presence_provider:, logger:, sweeper: nil, clock: nil)
+          @config = config
+          @presence_provider = presence_provider
+          @logger = logger
+          @sweeper = sweeper || method(:expire_seats)
+          @clock = clock || -> { ::Process.clock_gettime(::Process::CLOCK_MONOTONIC) }
+          @last_sweep_at = nil
+        end
+
+        def join(connection, stream = connection.stream_name)
+          return unless @config&.stream_presence?(stream)
+
+          member = @config.presence_member_for(connection.context)
+          return unless member
+
+          presence = @presence_provider.call(stream)
+          seat = seats?(presence)
+          join_member(presence, connection, member, seat)
+          connection.presence_member = member[:id] if connection.respond_to?(:presence_member=)
+          connection.presence_seat = seat if connection.respond_to?(:presence_seat=)
+        rescue StandardError => e
+          log_failure("join", e)
+        end
+
+        def leave(connection, stream = connection.stream_name)
+          member_id = presence_member_of(connection)
+          return unless member_id
+
+          # Cleared first: a heartbeat touch already queued behind this
+          # disconnect must not re-join the seat it removes.
+          connection.presence_member = nil if connection.respond_to?(:presence_member=)
+          presence = @presence_provider.call(stream)
+          if joined_as_seat?(connection, presence)
+            presence.leave(connection_id: connection.id)
+          else
+            presence.leave(member_id: member_id)
+          end
+        rescue StandardError => e
+          log_failure("leave", e)
+        end
+
+        def touch(connections)
+          connections.select { |conn| presence_member_of(conn) }.group_by(&:stream_name).each do |stream, conns|
+            touch_stream(stream, conns)
+          rescue StandardError => e
+            log_failure("touch", e)
+          end
+          sweep_if_due
+        end
+
+        private
+
+        def join_member(presence, connection, member, seat)
+          metadata = member[:metadata] || {}
+          if seat
+            presence.join(member_id: member[:id], metadata: metadata,
+                          connection_id: connection.id, seat: seat_of(connection))
+          else
+            presence.join(member_id: member[:id], metadata: metadata)
+          end
+        end
+
+        def touch_stream(stream, conns)
+          presence = @presence_provider.call(stream)
+          unless seats?(presence)
+            conns.each { |conn| presence.touch(member_id: presence_member_of(conn)) }
+            return
+          end
+
+          live = presence.touch(connection_id: conns.map(&:id))
+          conns.reject { |conn| live.include?(conn.id) }.each { |conn| rejoin_as_seat(presence, conn, stream) }
+        end
+
+        # A connection that joined as a member-keyed row before the table
+        # was migrated drops that row before it takes a seat.
+        def rejoin_as_seat(presence, connection, stream)
+          presence.leave(member_id: presence_member_of(connection)) unless joined_as_seat?(connection, presence)
+          join(connection, stream)
+        end
+
+        def sweep_if_due
+          return if Array(@config.streams_presence_patterns).empty?
+
+          at = now
+          return if @last_sweep_at && at - @last_sweep_at < @config.presence_min_ttl / 2.0
+
+          @sweeper.call
+          @last_sweep_at = at
+        rescue StandardError => e
+          log_failure("expiry", e)
+        end
+
+        def expire_seats
+          Pgbus::Streams::Presence.expire_seats!(
+            ttl_for: ->(stream) { @config.presence_ttl_for(stream) }, min_ttl: @config.presence_min_ttl
+          )
+        end
+
+        def seats?(presence)
+          presence.respond_to?(:seats?) && presence.seats?
+        end
+
+        # The mode recorded at join; a connection without the accessor
+        # follows the table's current schema.
+        def joined_as_seat?(connection, presence)
+          return connection.presence_seat if connection.respond_to?(:presence_seat)
+
+          seats?(presence)
+        end
+
+        def seat_of(connection)
+          connection.respond_to?(:seat) ? connection.seat : nil
+        end
+
+        def presence_member_of(connection)
+          connection.respond_to?(:presence_member) ? connection.presence_member : nil
+        end
+
+        def now
+          @clock.call
+        end
+
+        def log_failure(action, error)
+          @logger.error { "[Pgbus::Streamer::PresenceTracker] presence #{action} failed: #{error.class}: #{error.message}" }
+        end
+      end
+    end
+  end
+end

data/lib/pgbus/web/streamer/stream_event_dispatcher.rb

@@ -105,6 +105,7 @@ module Pgbus
           # process-wide setting. Falls back to the global config
           # for production call sites that don't specify one.
           @config = config || Pgbus.configuration
+          @presence = PresenceTracker.new(config: @config, presence_provider: @presence_provider, logger: @logger)
           # Two write deadlines (issue #315 item 3). Fanout writes run serially
           # on this single thread, so a slow client stalls the connections
           # queued behind it — the short fanout deadline bounds that stall.
@@ -436,19 +437,11 @@ module Pgbus
           )
         end
 
-        # Touches (refreshes last_seen_at for) the presence members on the
-        # given connections. Posted by the Heartbeat each tick so idle but
-        # still-connected members don't get swept. Connections without a
-        # presence member (non-presence streams, anonymous) are skipped.
+        # Touches the presence rows of the given connections and expires
+        # silent seats. Posted by the Heartbeat each tick so idle but
+        # still-connected members don't get swept (see PresenceTracker).
         def handle_presence_touch(msg)
-          msg.connections.each do |connection|
-            member_id = presence_member_of(connection)
-            next unless member_id
-
-            @presence_provider.call(connection.stream_name).touch(member_id: member_id)
-          rescue StandardError => e
-            @logger.error { "[Pgbus::Streamer::StreamEventDispatcher] presence touch failed: #{e.class}: #{e.message}" }
-          end
+          @presence.touch(msg.connections)
         end
 
         # If this stream has no remaining subscribers (registered or
@@ -640,35 +633,13 @@ module Pgbus
           connection.respond_to?(:id) && connection.id.to_s == exclude.to_s
         end
 
-        # Connection-driven presence (issue #169). Auto-joins a member when
-        # the stream is configured for presence and the connection's
-        # authorize-context yields a member id. Stores the member id on the
-        # connection so handle_disconnect/handle_presence_touch can act on
-        # it. Failures are logged and swallowed: a presence DB hiccup must
-        # not knock a live SSE connection out of the registry.
+        # Connection-driven presence (issues #169, #515): see PresenceTracker.
         def presence_join(connection, stream)
-          return unless @config&.stream_presence?(stream)
-
-          member = @config.presence_member_for(connection.context)
-          return unless member
-
-          @presence_provider.call(stream).join(member_id: member[:id], metadata: member[:metadata] || {})
-          connection.presence_member = member[:id] if connection.respond_to?(:presence_member=)
-        rescue StandardError => e
-          @logger.error { "[Pgbus::Streamer::StreamEventDispatcher] presence join failed: #{e.class}: #{e.message}" }
+          @presence.join(connection, stream)
         end
 
         def presence_leave(connection, stream)
-          member_id = presence_member_of(connection)
-          return unless member_id
-
-          @presence_provider.call(stream).leave(member_id: member_id)
-        rescue StandardError => e
-          @logger.error { "[Pgbus::Streamer::StreamEventDispatcher] presence leave failed: #{e.class}: #{e.message}" }
-        end
-
-        def presence_member_of(connection)
-          connection.respond_to?(:presence_member) ? connection.presence_member : nil
+          @presence.leave(connection, stream)
         end
 
         def monotonic_ms

data/lib/pgbus/web/time_format.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+require "time"
+require "active_support/core_ext/time"
+require "active_support/core_ext/date_time"
+
+module Pgbus
+  module Web
+    # Every timestamp, age and duration the dashboard prints (issue #497).
+    #
+    # Accepts the shapes the data sources hand the views: Time (pg decoders),
+    # ActiveSupport::TimeWithZone (AR attributes), DateTime, ISO 8601 or
+    # Time#to_s Strings (PGMQ JSON, payload["scheduled_at"]), Numeric epoch
+    # seconds (ActiveJob before 7.1), and nil. Every time is shown in
+    # Time.zone. Every word comes from pgbus.helpers.time in the locale.
+    # Pure: no I/O, no view context; the view helpers wrap it in <time>.
+    module TimeFormat
+      SCOPE = "pgbus.helpers.time"
+      NONE = "—"
+      MINUTE = 60
+      HOUR = 3600
+      DAY = 86_400
+
+      module_function
+
+      def coerce(value)
+        case value
+        when nil then nil
+        when Time, DateTime, ActiveSupport::TimeWithZone then value.in_time_zone
+        when Numeric then epoch(value)
+        when String then parse(value)
+        end
+      end
+
+      # NaN and Infinity are not moments.
+      def epoch(seconds)
+        Time.at(seconds).in_time_zone
+      rescue RangeError
+        nil
+      end
+
+      def parse(string)
+        string = string.strip
+        return nil if string.empty?
+
+        Time.zone ? Time.zone.parse(string) : Time.parse(string)
+      rescue ArgumentError
+        nil
+      end
+
+      # "5m ago", "in 2h" or "now", measured from now:.
+      def relative(value, now: Time.current)
+        time = coerce(value)
+        return nil unless time
+
+        delta = time - now
+        return I18n.t("#{SCOPE}.now") if delta.abs < 1
+
+        distance = largest_unit(delta.abs.to_i)
+        I18n.t("#{SCOPE}.#{delta.negative? ? "past" : "future"}", distance: distance)
+      end
+
+      def absolute(value)
+        coerce(value)&.strftime(I18n.t("#{SCOPE}.absolute_format"))
+      end
+
+      def clock(value)
+        coerce(value)&.strftime(I18n.t("#{SCOPE}.clock_format"))
+      end
+
+      def iso(value)
+        coerce(value)&.utc&.iso8601
+      end
+
+      # Two units at most: "45s", "2m 5s", "1h 2m", "1d 1h".
+      def duration(seconds)
+        return NONE unless seconds
+
+        # An age is never negative; one is clock skew between hosts.
+        seconds = [seconds.to_i, 0].max
+        if seconds < MINUTE then unit(:seconds, seconds)
+        elsif seconds < HOUR then pair(:minutes, seconds / MINUTE, :seconds, seconds % MINUTE)
+        elsif seconds < DAY then pair(:hours, seconds / HOUR, :minutes, (seconds % HOUR) / MINUTE)
+        else pair(:days, seconds / DAY, :hours, (seconds % DAY) / HOUR)
+        end
+      end
+
+      def ms_duration(millis)
+        return NONE unless millis
+
+        millis = millis.to_i
+        if millis < 1000 then unit(:milliseconds, millis)
+        elsif millis < 60_000 then unit(:seconds, (millis / 1000.0).round(1))
+        else unit(:minutes, (millis / 60_000.0).round(1))
+        end
+      end
+
+      # "15 minutes", "6 hours", "7 days" for an Insights range in minutes.
+      def range_label(minutes)
+        minutes = [minutes.to_i, 1].max
+
+        if minutes > 1440 && (minutes % 1440).zero?
+          I18n.t("#{SCOPE}.range.days", count: minutes / 1440)
+        elsif minutes >= 60 && (minutes % 60).zero?
+          I18n.t("#{SCOPE}.range.hours", count: minutes / 60)
+        else
+          I18n.t("#{SCOPE}.range.minutes", count: minutes)
+        end
+      end
+
+      def largest_unit(seconds)
+        if seconds < MINUTE then unit(:seconds, seconds)
+        elsif seconds < HOUR then unit(:minutes, seconds / MINUTE)
+        elsif seconds < DAY then unit(:hours, seconds / HOUR)
+        else unit(:days, seconds / DAY)
+        end
+      end
+
+      def pair(big, big_count, small, small_count)
+        "#{unit(big, big_count)} #{unit(small, small_count)}"
+      end
+
+      def unit(name, count)
+        I18n.t("#{SCOPE}.units.#{name}", count: count)
+      end
+    end
+  end
+end