cent 4.0.0 → 5.0.0

data/lib/cent/auto_batch.rb

@@ -0,0 +1,305 @@
+# frozen_string_literal: true
+
+module Cent
+  # Lets a client send concurrent calls together, as one batch request, once
+  # enough of them are in flight:
+  #
+  #   client = Cent::Client.new(api_endpoint:, api_key:, auto_batch: Cent::AutoBatch.new(max_in_flight: 8))
+  #
+  # Nothing waits for a batch to fill. While fewer than max_in_flight requests
+  # are in flight, every call is sent at once, alone, exactly as without
+  # AutoBatch. Only a call made when max_in_flight requests are already in
+  # flight waits - for one of them to finish, not for a timer. Then all the
+  # calls waiting at that moment go out together, at most max_batch_size of
+  # them. The busier the client - Puma threads, Sidekiq workers, fibers sharing
+  # it - the larger the batches, and the fewer requests Centrifugo handles for
+  # the same work.
+  #
+  # Every call gets its own command's reply. Calls made one after another keep
+  # their order: a call waits for its reply, so the next one joins a later
+  # batch. Calls sharing a batch were made concurrently, with no order between
+  # them, and Centrifugo runs them in parallel.
+  #
+  # Calls sharing a batch share its request, though: when it fails as a whole -
+  # the network, the credentials, a body too large for a proxy in front of
+  # Centrifugo (nginx refuses bodies over 1 MB by default) - every call in it
+  # fails with that error. Each call keeps its own timeout: the batch lasts
+  # until the latest of its calls'.
+  #
+  # It is for processes which publish a lot at once - a Sidekiq process at
+  # concurrency 10 or more, an app on Falcon - and does nothing for a Puma web
+  # process of a few threads. Set max_in_flight to about half the threads or
+  # fibers which call the client at once: above that, it never batches; just
+  # below, it batches calls one at a time, and only limits them.
+  #
+  # @!attribute [r] max_in_flight
+  #   @return [Integer] how many requests may be in flight before calls start
+  #     to wait and be batched
+  # @!attribute [r] max_batch_size
+  #   @return [Integer] the most calls one batch carries, 1000 by default
+  class AutoBatch < Data.define(:max_in_flight, :max_batch_size)
+    # @raise [InvalidConfigError]
+    def initialize(max_in_flight:, max_batch_size: 1000)
+      unless max_in_flight.is_a?(Integer) && max_in_flight >= 1
+        raise InvalidConfigError, "AutoBatch max_in_flight must be 1 or more; leave auto_batch unset to disable it"
+      end
+      unless max_batch_size.is_a?(Integer) && max_batch_size >= 2
+        raise InvalidConfigError, "AutoBatch max_batch_size must be 2 or more: a batch of 1 never batches"
+      end
+
+      super
+    end
+
+    # A call waiting to be sent in a batch. Until done, its fields belong to
+    # the batcher; afterwards, to the caller.
+    #
+    # @api private
+    class Queued
+      attr_accessor :reply, :error, :taken, :gone, :index
+      attr_reader :command, :deadline, :done, :storage
+
+      def initialize(command, deadline)
+        # Encoded before it queued: the batch never reads the caller's request.
+        @command = command
+        @deadline = deadline
+        @done = Thread::Queue.new
+        @reply = {}
+        @error = nil
+        # taken once in a batch; gone once its caller gave up before that.
+        @taken = false
+        @gone = false
+        # Its place in the batch which carried it, for error messages.
+        @index = 0
+        # The caller's fiber storage, for batch_context.
+        @storage = Fiber.current.storage
+      end
+    end
+
+    # AutoBatch for a Client.
+    #
+    # @api private
+    class Batcher
+      # Seconds a thread sending batches waits for the next before it ends.
+      WORKER_IDLE = 10.0
+
+      class << self
+        # WORKER_IDLE, unless the tests set another.
+        #
+        # @api private
+        attr_writer :worker_idle
+
+        # @api private
+        def worker_idle = @worker_idle || WORKER_IDLE
+      end
+
+      def initialize(client, opts, batch_context)
+        @client = client
+        @batch_context = batch_context
+        @max_in_flight = opts.max_in_flight
+        @max_batch = opts.max_batch_size
+        @lock = Mutex.new
+        @in_flight = 0
+        @queue = []
+        # The threads sending batches, started as needed and kept while busy:
+        # at most one per slot, since a batch holds one, each ending after
+        # WORKER_IDLE seconds without a batch. Starting a thread per batch cost
+        # more than a small batch saved.
+        @jobs = Thread::Queue.new
+        @workers = 0
+        @idle = 0
+      end
+
+      # Stops the threads sending batches, once those in progress are sent.
+      def close
+        n = @lock.synchronize { @workers }
+        n.times { @jobs << :stop }
+      end
+
+      # [true, what alone returned] when a slot was free and the call went
+      # alone; [false, [its place in the batch, its command's reply]] when it
+      # went in a batch.
+      def call(method, wire, deadline, alone)
+        command = nil
+        q = nil
+        @lock.lock
+        begin
+          loop do
+            drop_gone
+            if @in_flight < @max_in_flight && @queue.empty?
+              @in_flight += 1
+              break
+            end
+            if command
+              q = Queued.new(command, deadline)
+              @queue << q
+              break
+            end
+            # The call will queue: encode its command first, outside the lock,
+            # then look again - a slot may have freed meanwhile, and a call must
+            # never queue while one is free.
+            @lock.unlock
+            begin
+              command = "{\"#{method}\":#{Client.encode(wire)}}"
+            ensure
+              @lock.lock
+            end
+          end
+        ensure
+          @lock.unlock
+        end
+        if q.nil?
+          begin
+            return [true, alone.call]
+          ensure
+            release
+          end
+        end
+        [false, wait(q, method, deadline)]
+      end
+
+      private
+
+      def wait(q, method, deadline)
+        if q.done.pop(timeout: [deadline - HTTP.now, 0].max).nil?
+          taken = @lock.synchronize do
+            q.gone = true unless q.taken
+            q.taken
+          end
+          # The reply may have come as the deadline ended: it is the call's
+          # outcome.
+          if q.done.empty?
+            raise TimeoutError, "#{method}: timed out" if taken
+
+            raise TimeoutError, "#{method}: timed out before it was sent"
+          end
+        end
+        # A copy for each caller: raised in each caller's thread, one shared
+        # error would gather all their backtraces.
+        raise q.error.dup if q.error
+
+        [q.index, q.reply]
+      end
+
+      def drop_gone
+        @queue.shift while @queue.first&.gone
+      end
+
+      # Hands the slot of a finished request to the calls waiting, if any, and
+      # frees it otherwise.
+      def release
+        items = @lock.synchronize do
+          drop_gone
+          if @queue.empty?
+            @in_flight -= 1
+            next nil
+          end
+          take
+        end
+        return if items.nil?
+
+        # Sent from a thread of the batcher's, so that no caller's thread does
+        # work for others. Counted as a call: close waits for it.
+        @client.calls.add
+        dispatch(items)
+      end
+
+      def dispatch(items)
+        start = @lock.synchronize do
+          # Pushed under the lock which a sender ending idle takes: it sees
+          # the batch, and stays for it.
+          @jobs << items
+          next false unless @idle.zero? && @workers < @max_in_flight
+
+          @workers += 1
+          @idle += 1
+        end
+        Thread.new { work } if start
+      end
+
+      def work
+        loop do
+          items = @jobs.pop(timeout: self.class.worker_idle)
+          if items.nil?
+            done = @lock.synchronize do
+              next false unless @jobs.empty?
+
+              @workers -= 1
+              @idle -= 1
+              true
+            end
+            break if done
+
+            next
+          end
+          if items == :stop
+            @lock.synchronize do
+              @workers -= 1
+              @idle -= 1
+            end
+            break
+          end
+          @lock.synchronize { @idle -= 1 }
+          # With an empty fiber storage: a batch is no one caller's.
+          Fiber.new(storage: {}) { flush(items) }.resume
+          @lock.synchronize { @idle += 1 }
+        end
+      end
+
+      # Takes up to max_batch calls off the head of the queue, skipping those
+      # gone.
+      def take
+        items = []
+        until items.size >= @max_batch || @queue.empty?
+          q = @queue.shift
+          next if q.gone
+
+          q.taken = true
+          q.index = items.size
+          items << q
+        end
+        items
+      end
+
+      def flush(items)
+        send_items(items) unless items.empty?
+      ensure
+        release
+        @client.calls.leave
+      end
+
+      def send_items(items)
+        # Parallel: the calls of an automatic batch were made concurrently, so
+        # nothing orders them, and Centrifugo pipelines their broker commands.
+        body = "{\"commands\":[#{items.map(&:command).join(",")}],\"parallel\":true}"
+        # The latest deadline of the calls, never less than request_timeout
+        # from now.
+        timeout = [@client.request_timeout, *items.map { it.deadline - HTTP.now }].max
+        replies =
+          if @batch_context
+            out = nil
+            called = false
+            @batch_context.call(items.map(&:storage)) do
+              called = true
+              out = @client.send_auto_batch(body, items.size, timeout)
+            end
+            # Without the batch sent, its calls fail - not the batcher.
+            raise InvalidConfigError, "batch_context must call its block once: the batch was not sent" unless called
+
+            out
+          else
+            @client.send_auto_batch(body, items.size, timeout)
+          end
+      rescue StandardError => e
+        items.each do |q|
+          q.error = e
+          q.done << true
+        end
+      else
+        items.zip(replies) do |q, r|
+          q.reply = r
+          q.done << true
+        end
+      end
+    end
+  end
+end

data/lib/cent/batch.rb

@@ -0,0 +1,209 @@
+# frozen_string_literal: true
+
+module Cent
+  # The outcome of a sent batch as a whole. Each command's own outcome is in the
+  # Pending its method returned.
+  #
+  # @!attribute [r] replied
+  #   @return [Boolean] true when Centrifugo replied to every command, the failed
+  #     ones included; false when the batch failed as a whole. True for an empty
+  #     batch.
+  # @!attribute [r] failed
+  #   @return [Array<FailedCommand>] the commands which failed, with their
+  #     errors, in the order they were added
+  class BatchResult < Data.define(:replied, :failed)
+    include Message
+
+    # @return [Boolean] alias of replied
+    def replied? = replied
+  end
+
+  # The outcome of one command of a batch, available once the batch is sent.
+  class Pending
+    # @api private
+    def initialize(batch, index)
+      @batch = batch
+      @index = index
+    end
+
+    # The command's result, or its error raised: an ApiError for this command,
+    # the error which failed the whole batch, or BatchNotSentError. A broadcast
+    # raises BroadcastFailedChannelsError, carrying every channel's outcome,
+    # when any channel failed.
+    #
+    # @return [Object] the result of the command's method
+    # @raise [Error]
+    def value = @batch.outcome(@index)
+
+    # A Pending of no batch, whose {#value} returns +value+ or raises +error+:
+    # for test doubles of code which reads a batch's outcomes.
+    #
+    #   Cent::Pending.resolved(Cent::PublishResult.new(offset: 1))
+    #   Cent::Pending.resolved(error: Cent::ApiError.for_code(102, "unknown channel"))
+    #
+    # @param value [Object]
+    # @param error [Exception, nil]
+    # @return [Pending]
+    def self.resolved(value = nil, error: nil) = new(Resolved.new(value, error), 0)
+
+    # The outcome of a resolved Pending.
+    Resolved = Struct.new(:value, :error) do
+      # @api private
+      def outcome(_) = error ? raise(error) : value
+    end
+    private_constant :Resolved
+  end
+
+  # Commands sent to Centrifugo in one request. Create one with
+  # {Client#new_batch}, add commands with its methods - one per API method, each
+  # taking the method's fields and returning a {Pending} - then send it:
+  #
+  #   batch = client.new_batch
+  #   pub = batch.publish(channel: "news", data: { text: "hi" })
+  #   stats = batch.presence_stats(channel: "news")
+  #   batch.send            # raises unless every command succeeded
+  #   pub.value.offset
+  #
+  # A batch is sent once, and is not safe for concurrent use.
+  class Batch
+    include BatchMethods
+
+    # @api private
+    def initialize(client, parallel)
+      @client = client
+      @parallel = parallel
+      @commands = []
+      @methods = []
+      # Per command: an error which fails the whole batch before sending - a
+      # request the client can tell is invalid.
+      @invalid = []
+      # Per command, filled when sent: its outcome, a result or an error.
+      @outcomes = []
+      @replies = nil
+      @error = nil
+      @sent = false
+    end
+
+    # @return [Integer] how many commands the batch has
+    def size = @commands.size
+    alias length size
+
+    # @return [Boolean]
+    def empty? = @commands.empty?
+
+    # Sends the batch and waits for Centrifugo's reply to every command.
+    #
+    # It returns when every command succeeded. BatchFailedCommandsError means
+    # one or more commands failed, up to all: every command got its own reply,
+    # each Pending holds its outcome. Any other error means the batch failed as
+    # a whole: no command got a reply, and every Pending raises that error. A
+    # command the client can tell is invalid fails the whole batch before
+    # anything is sent. An empty batch sends nothing.
+    #
+    # Called with a method name, it is Object#send.
+    #
+    # @param timeout [Numeric, nil] seconds bounding the call: request_timeout
+    #   when nil
+    # @return [BatchResult]
+    # @raise [Error]
+    def send(*args, timeout: nil, **, &)
+      return __send__(*args, **, &) unless args.empty?
+
+      raise BatchSentError, "batch already sent" if @sent
+
+      @sent = true
+      begin
+        if @commands.empty?
+          @client.send_batch(nil, 0, timeout)
+          @replies = []
+          return BatchResult.new(replied: true, failed: [])
+        end
+        @invalid.each_with_index do |err, i|
+          raise InvalidRequestError, "batch command ##{i}: #{err.message}" if err
+        end
+        parallel = @parallel ? ',"parallel":true' : ""
+        body = "{\"commands\":[#{@commands.join(",")}]#{parallel}}"
+        @replies = @client.send_batch(body, @commands.size, timeout)
+      rescue StandardError => e
+        @error = e
+        raise
+      end
+      failed = []
+      @methods.each_with_index do |method, i|
+        out = resolve(i)
+        failed << FailedCommand.new(index: i, method:, error: out) if out.is_a?(Exception)
+      end
+      res = BatchResult.new(replied: true, failed:)
+      raise BatchFailedCommandsError.new(failed, @commands.size, res) unless failed.empty?
+
+      res
+    end
+
+    # @api private
+    def outcome(index)
+      raise BatchNotSentError, "batch not sent yet" unless @sent
+      raise @error if @error
+
+      out = resolve(index)
+      raise out if out.is_a?(Exception)
+
+      out
+    end
+
+    private
+
+    def add(method, result_class, &)
+      append(method, ->(r, i) { result_class.from_wire(r[method] || {}, "replies[#{i}].#{method}") }, &)
+    end
+
+    def add_broadcast
+      channels = []
+      key = ""
+      decode = lambda do |r, i|
+        BroadcastResult.from_wire(r["broadcast"] || {}, channels, key).check!
+      rescue DecodeError => e
+        raise DecodeError, "replies[#{i}]: #{e.message}"
+      end
+      append("broadcast", decode) do
+        w = yield
+        channels = w["channels"] || []
+        key = w["idempotency_key"] || ""
+        w
+      end
+    end
+
+    def append(method, decode)
+      raise FrozenError.new("cent: command added to a batch that was already sent", receiver: self) if @sent
+
+      text = ""
+      invalid = nil
+      begin
+        w = Reply.validate(method, yield)
+        text = "{\"#{method}\":#{Client.encode(w)}}"
+      rescue InvalidRequestError => e
+        invalid = InvalidRequestError.new("invalid #{method} request: #{e.message}")
+      end
+      @commands << text
+      @methods << method
+      @invalid << invalid
+      @outcomes << decode
+      Pending.new(self, @commands.size - 1)
+    end
+
+    # Decodes command i's outcome once, so that send's BatchFailedCommandsError
+    # holds the very error its Pending raises.
+    def resolve(i)
+      out = @outcomes[i]
+      return out unless out.is_a?(Proc)
+
+      reply = @replies[i]
+      err = Reply.command_error(reply, i, @methods[i])
+      @outcomes[i] =
+        (err || begin
+          out.call(reply, i)
+        rescue Error => e
+          e
+        end)
+    end
+  end
+end

data/lib/cent/broadcast.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module Cent
+  # The outcome of a broadcast in one channel.
+  #
+  # @!attribute [r] channel
+  #   @return [String] the channel, as the request named it
+  # @!attribute [r] result
+  #   @return [PublishResult, nil] the publication's position in the channel's
+  #     history, when it succeeded
+  # @!attribute [r] error
+  #   @return [Error, nil] nil when the publication succeeded; the channel's
+  #     ApiError, or the error of the whole broadcast when it failed as a whole
+  # @!attribute [r] attempts
+  #   @return [Integer] how many times the channel was sent: more than 1 when
+  #     broadcast_with_retry retried it
+  class ChannelResult < Data.define(:channel, :result, :error, :attempts)
+    include Message
+
+    def initialize(channel:, result: nil, error: nil, attempts: 0) = super
+  end
+
+  # The outcome of a broadcast: one entry per channel, in the order the request
+  # listed them.
+  #
+  # @!attribute [r] channels
+  #   @return [Array<ChannelResult>]
+  # @!attribute [r] idempotency_key
+  #   @return [String] the key the broadcast was sent with: the request's, or the
+  #     one broadcast_with_retry made when the request had none. A later retry
+  #     with it does not publish again into the channels which got the
+  #     publication.
+  # @!attribute [r] attempts
+  #   @return [Integer] how many times the broadcast was tried: 1 from broadcast,
+  #     up to max_attempts from broadcast_with_retry, 0 when it was refused
+  #     before sending
+  # @!attribute [r] replied
+  #   @return [Boolean] true when Centrifugo carried the broadcast out and
+  #     replied for every channel, the failed ones included; false when it
+  #     failed as a whole
+  class BroadcastResult < Data.define(:channels, :idempotency_key, :attempts, :replied)
+    include Message
+
+    def initialize(channels: [], idempotency_key: "", attempts: 0, replied: false) = super
+
+    # The channels which did not get the publication, with their errors, in the
+    # order of the request.
+    #
+    # @return [Array<ChannelResult>]
+    def failed = channels.select(&:error)
+
+    # @return [Boolean] alias of replied
+    def replied? = replied
+
+    # @api private
+    def self.failed_as_whole(channels, err, attempts = 0)
+      new(channels: channels.map { ChannelResult.new(channel: it, error: err, attempts:) }, attempts:)
+    end
+
+    # The result of a broadcast Centrifugo replied to. The reply holds one
+    # response per channel, in the request's order.
+    #
+    # @api private
+    def self.from_wire(v, channels, key)
+      d = Wire.obj(v, "broadcast result")
+      responses = d["responses"] || []
+      raise DecodeError, "broadcast result.responses: expected an array" unless responses.is_a?(Array)
+      if responses.size != channels.size
+        raise DecodeError, "broadcast: got #{responses.size} replies for #{channels.size} channels"
+      end
+
+      results = responses.each_with_index.map do |item, i|
+        where = "broadcast result.responses[#{i}]"
+        r = Wire.obj(item, where)
+        if r["error"].nil?
+          ChannelResult.new(channel: channels[i], result: PublishResult.from_wire(r["result"] || {}, "#{where}.result"),
+                            attempts: 1)
+        else
+          ChannelResult.new(channel: channels[i], error: Reply.api_error(r["error"], "#{where}.error"), attempts: 1)
+        end
+      end
+      new(channels: results, idempotency_key: key, attempts: 1, replied: true)
+    end
+
+    # The result, or BroadcastFailedChannelsError carrying it when any channel
+    # failed.
+    #
+    # @api private
+    def check!
+      f = failed
+      raise BroadcastFailedChannelsError.new(f, channels.size, self) unless f.empty?
+
+      self
+    end
+  end
+
+  # A failed attempt of broadcast_with_retry, given to its block.
+  #
+  # @!attribute [r] attempt
+  #   @return [Integer] the attempt which failed, from 1
+  # @!attribute [r] error
+  #   @return [Error] its error: BroadcastFailedChannelsError when Centrifugo
+  #     replied and some channels failed, otherwise the error of the request as a
+  #     whole
+  # @!attribute [r] retry
+  #   @return [Array<ChannelResult>] the channels the next attempt sends, with
+  #     the errors this attempt failed them with. A broadcast to many channels
+  #     which all failed lists every one: log a count or a few.
+  # @!attribute [r] result
+  #   @return [BroadcastResult] every channel's outcome so far, as the call
+  #     would return it if it stopped now
+  # @!attribute [r] idempotency_key
+  #   @return [String] the key every attempt is sent with
+  class BroadcastAttempt < Data.define(:attempt, :error, :retry, :result, :idempotency_key)
+    include Message
+  end
+end