cent 4.0.0 → 5.0.0

data/lib/cent/handler.rb

@@ -0,0 +1,179 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module Cent
+  # A request to a handler, as the application's block receives it.
+  #
+  # @!attribute [r] method
+  #   @return [String] the HTTP method, upper case
+  # @!attribute [r] headers
+  #   @return [Hash{String => String}] the headers, lowercase names: those
+  #     Centrifugo passes on from the client's connection to a proxy, the client
+  #     SDK's to an endpoint
+  # @!attribute [r] query
+  #   @return [Hash{String => String}] the query parameters, the first value of
+  #     each
+  # @!attribute [r] path
+  #   @return [String] the path, as the server saw it
+  # @!attribute [r] raw
+  #   @return [Object] the server's own form of the request: the Rack env, or
+  #     what was given to {Handler#handle} - for what the core does not carry,
+  #     such as the client's address or the session
+  class HTTPRequest < Data.define(:method, :headers, :query, :path, :raw); end
+
+  # A handler's answer: +[status, headers, body]+ with {#to_a}.
+  #
+  # @!attribute [r] status
+  #   @return [Integer]
+  # @!attribute [r] headers
+  #   @return [Hash{String => String}] lowercase names, as Rack 3 wants them
+  # @!attribute [r] body
+  #   @return [String]
+  class HTTPResponse < Data.define(:status, :headers, :body)
+    # @return [Array] +[status, headers, body]+
+    def to_a = [status, headers, body]
+
+    # @api private
+    def self.text(status, message, extra = {})
+      new(status:, headers: { "content-type" => "text/plain; charset=utf-8", **extra }, body: message)
+    end
+
+    # @api private
+    REASONS = { 400 => "Bad Request", 403 => "Forbidden", 405 => "Method Not Allowed",
+                500 => "Internal Server Error" }.freeze
+
+    # @api private
+    def self.status_text(status) = text(status, REASONS.fetch(status, status.to_s))
+
+    # @api private
+    def self.allow(methods) = text(405, "only #{methods} allowed", { "allow" => methods })
+
+    # @api private
+    def self.json(body, cache = "no-store")
+      new(status: 200, headers: { "content-type" => "application/json", "cache-control" => cache }, body:)
+    end
+  end
+
+  # The base of every handler - an endpoint for client SDKs, the JWKS endpoint,
+  # a proxy handler. Its framework-free core, {#handle}, turns a request into a
+  # response; {#call} serves it as a Rack app, which Rails, Sinatra, Hanami and
+  # every Rack server mount:
+  #
+  #   mount handler, at: "/centrifugo/connect"   # config/routes.rb
+  #
+  # Any other server calls {#handle}.
+  class Handler
+    # @return [Integer] the largest request body read, in bytes
+    attr_reader :max_body
+
+    # @api private
+    def initialize(max_body, on_error, &func)
+      raise ArgumentError, "#{self.class} takes a block" if func.nil? && !answers_itself?
+      raise ArgumentError, "on_error must respond to call" unless on_error.nil? || on_error.respond_to?(:call)
+      unless max_body.is_a?(Integer) && max_body.positive?
+        raise ArgumentError,
+              "max_body must be a positive number of bytes"
+      end
+
+      @max_body = max_body
+      @on_error = on_error
+      @func = func
+    end
+
+    # Answers a request.
+    #
+    # @param method [String]
+    # @param headers [Hash{String => String}, Array<Array(String, String)>]
+    # @param body [String]
+    # @param query [Hash{String => String}]
+    # @param path [String]
+    # @param raw [Object] passed on as {HTTPRequest#raw}: the server's own
+    #   request object
+    # @return [HTTPResponse]
+    def handle(method, headers = {}, body = "", query: {}, path: "", raw: nil)
+      h = {}
+      headers.each do |k, v|
+        k = k.to_s.downcase
+        h[k] = h.key?(k) ? "#{h[k]}, #{v}" : v.to_s
+      end
+      req = HTTPRequest.new(method: method.to_s.upcase, headers: h.freeze, query: query.to_h.freeze, path:, raw:)
+      return failure(req, 400, ArgumentError.new("request body over #{max_body} bytes")) if body.bytesize > max_body
+
+      begun = start(req, body)
+      return begun if begun.is_a?(HTTPResponse)
+
+      begin
+        out = @func.call(*begun, req)
+      rescue StandardError => e
+        return finish(req, begun, nil, e)
+      end
+      finish(req, begun, out, nil)
+    end
+
+    # The handler as a Rack app.
+    #
+    # @param env [Hash] the Rack env
+    # @return [Array] +[status, headers, [body]]+
+    def call(env)
+      body = read_body(env)
+      headers = env.filter_map { |k, v| [k.delete_prefix("HTTP_").tr("_", "-"), v] if k.start_with?("HTTP_") }
+      headers << ["content-type", env["CONTENT_TYPE"]] if env["CONTENT_TYPE"]
+      headers << ["content-length", env["CONTENT_LENGTH"]] if env["CONTENT_LENGTH"]
+      query = {}
+      URI.decode_www_form(env["QUERY_STRING"].to_s).each { |k, v| query[k] ||= v }
+      resp = handle(env["REQUEST_METHOD"], headers, body, query:, path: env["PATH_INFO"].to_s, raw: env)
+      [resp.status, resp.headers.dup, [resp.body]]
+    rescue ArgumentError => e
+      # A malformed query string.
+      resp = failure(HTTPRequest.new(method: env["REQUEST_METHOD"].to_s, headers: {}, query: {}, path: "", raw: env),
+                     400, e)
+      [resp.status, resp.headers.dup, [resp.body]]
+    end
+
+    private
+
+    def answers_itself? = false
+
+    # The block's arguments before the request, or the response when the
+    # request is answered without calling it.
+    def start(req, body) = raise NotImplementedError
+
+    # The response to what the block returned or raised.
+    def finish(req, args, out, error) = raise NotImplementedError
+
+    # +status+, after telling on_error of +err+.
+    def failure(req, status, err)
+      @on_error&.call(req, err)
+      HTTPResponse.status_text(status)
+    end
+
+    def read_body(env)
+      input = env["rack.input"]
+      return "" if input.nil?
+
+      # A framework may have read it already: Rails does.
+      input.rewind if input.respond_to?(:rewind)
+      (input.read(max_body + 1) || "").b
+    end
+
+    # err, or its cause, when it is a klass.
+    def find(err, klass)
+      while err
+        return err if err.is_a?(klass)
+
+        err = err.cause
+      end
+      nil
+    end
+
+    def parse_json(req, body)
+      d = JSON.parse(body, allow_nan: false)
+      return failure(req, 400, ArgumentError.new("malformed request: not a JSON object")) unless d.is_a?(Hash)
+
+      d
+    rescue JSON::ParserError, EncodingError => e
+      failure(req, 400, ArgumentError.new("malformed request: #{e.message}"))
+    end
+  end
+end

data/lib/cent/http.rb

@@ -0,0 +1,251 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "openssl"
+require "uri"
+
+module Cent
+  # The default HTTP transport: Net::HTTP connections kept alive in a pool, each
+  # request bounded by one deadline through Net::HTTP's public API: the time
+  # left as its open, read and write timeouts, and again as the read timeout
+  # before each chunk of the body. Those bound each read, so a reply's headers
+  # trickling in would outlast them: the Watchdog finishes a connection whose
+  # deadline passed.
+  #
+  # @api private
+  module HTTP
+    # Up to 256 idle connections to a host are kept, so that a burst does not
+    # open connections only to close them; idle ones are closed after 50
+    # seconds, before load balancers commonly close theirs.
+    MAX_IDLE = 256
+    IDLE_TIMEOUT = 50.0
+
+    # The body of an unexpected status is read up to MAX_API_ERROR_BYTES for a
+    # Centrifugo error in it, MAX_ERROR_BODY_BYTES of it kept for the HTTPError,
+    # and the rest drained up to MAX_DRAIN_BYTES, so that the connection is
+    # reused.
+    MAX_ERROR_BODY_BYTES = 512
+    MAX_API_ERROR_BYTES = 4 << 10
+    MAX_DRAIN_BYTES = 64 << 10
+
+    def self.now = ::Process.clock_gettime(::Process::CLOCK_MONOTONIC)
+
+    # Finishes the connections whose request's deadline passed, which wakes a
+    # read blocked on them with an IOError. One thread for every pool, started
+    # when first needed, and again in a forked process.
+    class Watchdog
+      Entry = Struct.new(:conn, :deadline, :fired)
+
+      def initialize
+        @fork_lock = Mutex.new
+        reset
+      end
+
+      # Returns the block's value, with +conn+ finished if +deadline+ passes
+      # first. An error raised once it was finished - an IOError from the read
+      # it woke, or whatever Net::HTTP raises on a connection finished under
+      # it - is the deadline's.
+      def watch(conn, deadline)
+        reset_after_fork
+        entry = Entry.new(conn, deadline, false)
+        @lock.synchronize do
+          @thread = Thread.new { run } unless @thread&.alive?
+          @entries << entry
+          @wake.signal
+        end
+        begin
+          yield
+        rescue StandardError
+          raise Net::ReadTimeout, "the call's deadline passed" if fired?(entry)
+
+          raise
+        ensure
+          # Under the lock: once removed, the connection is never finished
+          # again, so that it goes back to the pool safely.
+          @lock.synchronize { @entries.delete(entry) }
+        end
+      end
+
+      private
+
+      # A forked process starts with fresh state: the parent's thread did not
+      # survive the fork, its entries are the parent's connections, and its
+      # lock may have been held by a thread which no longer exists - taking it
+      # would block forever.
+      def reset_after_fork
+        return if @pid == ::Process.pid
+
+        @fork_lock.synchronize do
+          reset unless @pid == ::Process.pid
+        end
+      end
+
+      def reset
+        @lock = Mutex.new
+        @wake = ConditionVariable.new
+        @entries = []
+        @thread = nil
+        @pid = ::Process.pid
+      end
+
+      def fired?(entry) = @lock.synchronize { entry.fired }
+
+      def run
+        Thread.current.name = "rubycent-watchdog"
+        @lock.synchronize do
+          loop do
+            now = HTTP.now
+            next_deadline = nil
+            @entries.each do |e|
+              next if e.fired
+
+              if e.deadline <= now
+                e.fired = true
+                finish(e.conn)
+              elsif next_deadline.nil? || e.deadline < next_deadline
+                next_deadline = e.deadline
+              end
+            end
+            @wake.wait(@lock, next_deadline && (next_deadline - now))
+          end
+        end
+      end
+
+      def finish(conn)
+        conn.finish
+      rescue IOError, SystemCallError, OpenSSL::SSL::SSLError
+        nil
+      end
+    end
+
+    WATCHDOG = Watchdog.new
+
+    # Connections kept alive per scheme, host and port. Safe for concurrent use.
+    class Pool
+      # @param options [Hash] Net::HTTP settings for every connection: ca_file,
+      #   cert, key, verify_mode, local_host and the like
+      def initialize(options = {})
+        @options = options
+        @idle = Hash.new { |h, k| h[k] = [] }
+        @lock = Mutex.new
+        @closed = false
+      end
+
+      # @return [Hash] the Net::HTTP settings of its connections
+      attr_reader :options
+
+      # Sends a POST, and returns [status, headers, body]: the body of a
+      # status other than 200 read up to MAX_API_ERROR_BYTES.
+      def post(url, headers, body, deadline)
+        uri = URI.parse(url)
+        key = [uri.scheme, uri.host, uri.port]
+        conn = checkout(key, uri)
+        reusable = false
+        begin
+          out, reusable = WATCHDOG.watch(conn, deadline) { exchange(conn, uri, headers, body, deadline) }
+          reusable &&= conn.started?
+          out
+        ensure
+          reusable ? checkin(key, conn) : discard(conn)
+        end
+      end
+
+      def close
+        conns = @lock.synchronize do
+          @closed = true
+          all = @idle.values.flatten(1).map(&:first)
+          @idle.clear
+          all
+        end
+        conns.each { discard(it) }
+      end
+
+      private
+
+      # Sends the request on +conn+, and returns [[status, headers, body],
+      # whether the connection may be reused].
+      def exchange(conn, uri, headers, body, deadline)
+        left = time_left(deadline)
+        conn.open_timeout = left
+        conn.read_timeout = left
+        conn.write_timeout = left
+        conn.start unless conn.started?
+        req = Net::HTTP::Post.new(uri.request_uri, headers)
+        req.body = body
+        out = nil
+        reusable = false
+        catch(:drop) do
+          conn.request(req) do |res|
+            out = [res.code.to_i, res.to_hash.transform_values { it.join(", ") }, +""]
+            read(conn, res, out[2], deadline)
+          end
+          reusable = true
+        end
+        [out, reusable]
+      end
+
+      # Reads the body into +body+: whole for a 200, up to MAX_API_ERROR_BYTES
+      # otherwise, the rest drained so that the connection is reused - or
+      # dropped, by a throw, when there is too much. Each next chunk is read by
+      # the time left: a body arriving in pieces stops at the deadline.
+      def read(conn, res, body, deadline)
+        total = 0
+        res.read_body do |chunk|
+          if res.code == "200"
+            body << chunk
+          else
+            body << chunk.byteslice(0, MAX_API_ERROR_BYTES - body.bytesize) if body.bytesize < MAX_API_ERROR_BYTES
+            total += chunk.bytesize
+            throw :drop if total > MAX_DRAIN_BYTES
+          end
+          conn.read_timeout = time_left(deadline)
+        end
+      end
+
+      def time_left(deadline)
+        t = deadline - HTTP.now
+        raise Net::ReadTimeout, "the call's deadline passed" if t <= 0
+
+        t
+      end
+
+      def checkout(key, uri)
+        stale = []
+        conn = @lock.synchronize do
+          list = @idle[key]
+          while (entry = list.pop)
+            c, since = entry
+            break c if HTTP.now - since < IDLE_TIMEOUT
+
+            stale << c
+          end
+        end
+        stale.each { discard(it) }
+        return conn if conn
+
+        conn = Net::HTTP.new(uri.host, uri.port)
+        conn.use_ssl = uri.scheme == "https"
+        conn.keep_alive_timeout = IDLE_TIMEOUT
+        conn.max_retries = 0
+        @options.each { |k, v| conn.public_send(:"#{k}=", v) }
+        conn
+      end
+
+      def checkin(key, conn)
+        keep = @lock.synchronize do
+          next false if @closed || @idle[key].size >= MAX_IDLE
+
+          @idle[key] << [conn, HTTP.now]
+          true
+        end
+        discard(conn) unless keep
+      end
+
+      def discard(conn)
+        conn.finish if conn.started?
+      rescue IOError, SystemCallError, OpenSSL::SSL::SSLError
+        nil
+      end
+    end
+  end
+end

data/lib/cent/message.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Cent
+  # What every result and message type has besides its fields: Hash and JSON
+  # forms, nested ones included, for rendering or logging a result -
+  # +render json: client.history(channel:)+ in Rails, say.
+  #
+  #   res = client.history(channel: "news", limit: 1)
+  #   res.to_h      # => {publications: [{data: {"text" => "hi"}, info: nil, offset: 1, tags: {}}], offset: 1, ...}
+  #   res.to_json   # => '{"publications":[{"data":{"text":"hi"},...}],...}'
+  #
+  # Payloads stay as they are. An error in a result - a channel's, in a
+  # broadcast - is its message in JSON.
+  module Message
+    # The fields as a Hash with Symbol keys, nested messages as Hashes too.
+    #
+    # @return [Hash{Symbol => Object}]
+    def to_h(&)
+      return super if block_given?
+
+      super.transform_values { Message.deep(it) }
+    end
+
+    # The Hash a JSON encoder writes: {#to_h}, errors as their messages.
+    #
+    # @return [Hash{String => Object}]
+    def as_json(*) = Message.json(to_h)
+
+    # @return [String] the JSON of {#as_json}
+    def to_json(*) = as_json.to_json(*)
+
+    # @api private
+    def self.deep(v)
+      case v
+      when Message then v.to_h
+      when Array then v.map { deep(it) }
+      when Hash then v.transform_values { deep(it) }
+      else v
+      end
+    end
+
+    # @api private
+    def self.json(v)
+      case v
+      when Hash then v.to_h { |k, x| [k.to_s, json(x)] }
+      when Array then v.map { json(it) }
+      when Exception then v.message
+      else v
+      end
+    end
+  end
+end

data/lib/cent/pages.rb

@@ -0,0 +1,165 @@
+# frozen_string_literal: true
+
+module Cent
+  # Where the publication went in the channel's stream.
+  class PublishResult
+    # @return [StreamPosition] the publication's offset and the stream's epoch:
+    #   the since of a history call reading what came after it
+    def position = StreamPosition.new(offset:, epoch:)
+  end
+
+  # The channel's stream position when the history was read.
+  class HistoryResult
+    # @return [StreamPosition] the stream's top offset and epoch
+    def position = StreamPosition.new(offset:, epoch:)
+  end
+
+  # The map channel's stream position when its state was read.
+  class MapReadStateResult
+    # @return [StreamPosition] the stream's offset and epoch: as map_read_stream's
+    #   since_offset and since_epoch, it reads the changes since
+    def position = StreamPosition.new(offset:, epoch:)
+  end
+
+  # The map channel's stream position when its stream was read.
+  class MapReadStreamResult
+    # @return [StreamPosition] the stream's offset and epoch
+    def position = StreamPosition.new(offset:, epoch:)
+  end
+
+  # The map channel's stream position after the publication.
+  class MapPublishResult
+    # @return [StreamPosition] the publication's offset in the map's stream and
+    #   the stream's epoch
+    def position = StreamPosition.new(offset:, epoch:)
+  end
+
+  # The map channel's stream position after the removal.
+  class MapRemoveResult
+    # @return [StreamPosition] the removal's offset in the map's stream and the
+    #   stream's epoch
+    def position = StreamPosition.new(offset:, epoch:)
+  end
+
+  # A publication read by history_all, with the epoch of the stream it was read
+  # from. The publication's fields read directly - +item.data+, +item.offset+ -
+  # and {#position} is where it is in the channel's stream: the since of a
+  # history call resuming after it, or a subscription's recover_since.
+  #
+  # @!attribute [r] publication
+  #   @return [Publication]
+  # @!attribute [r] epoch
+  #   @return [String] the epoch of the channel's stream
+  class HistoryItem < Data.define(:publication, :epoch)
+    include Message
+
+    Publication.members.each { |m| define_method(m) { publication.public_send(m) } }
+
+    # @return [StreamPosition] the publication's offset and the stream's epoch
+    def position = StreamPosition.new(offset: publication.offset, epoch:)
+  end
+
+  # An entry read by map_read_state_all, with the position of the state it was
+  # read at: the first page's, every later page being read at it, or the
+  # revision the request gave. The entry's fields read directly - +item.key+,
+  # +item.data+ - and map_read_stream from {#position} follows the state with
+  # every change made since.
+  #
+  # @!attribute [r] entry
+  #   @return [MapEntry]
+  # @!attribute [r] state
+  #   @return [StreamPosition] the position of the map's state the entry was
+  #     read at
+  class MapStateItem < Data.define(:entry, :state)
+    include Message
+
+    MapEntry.members.each { |m| define_method(m) { entry.public_send(m) } }
+
+    # @return [StreamPosition] the state's position, {#state}
+    def position = state
+  end
+
+  # The <method>_all iterators of Client (spec 3.8): paging written once over
+  # the cursor, and once for history.
+  #
+  # @api private
+  module Pages
+    # Each paged method's result type, the field of its items, and the field
+    # holding the next page's cursor - empty when there is none.
+    PAGED = {
+      "history" => [HistoryResult, :publications, nil],
+      "device_list" => [DeviceListResult, :items, :next_cursor],
+      "device_topic_list" => [DeviceTopicListResult, :items, :next_cursor],
+      "user_topic_list" => [UserTopicListResult, :items, :next_cursor],
+      "map_read_state" => [MapReadStateResult, :entries, :cursor]
+    }.freeze
+
+    private
+
+    # The items of every page of +method+, the first page's request the JSON
+    # the block builds: an Enumerator, or each yielded to +block+. The request
+    # is checked here, before anything is sent.
+    def pages(method, page_timeout, block, &)
+      deadline(page_timeout, "page_timeout") # checked at the call, as the request is
+      first = encode_request(method, &)
+      check_history(first) if method == "history"
+      return Enumerator.new { |y| each_page(method, first, page_timeout) { y << it } } unless block
+
+      each_page(method, first, page_timeout, &block)
+      nil
+    end
+
+    def check_history(w)
+      limit = w["limit"] || 0
+      if limit < 1
+        raise InvalidRequestError, "invalid history request: history_all needs a limit of 1 or more, the page size " \
+                                   "(0 asks for the position alone, -1 for everything in one call)"
+      end
+      return unless w["reverse"]
+
+      raise InvalidRequestError, "invalid history request: history_all reads forward only: reverse is not supported"
+    end
+
+    def each_page(method, w, page_timeout)
+      result_class, items, cursor = PAGED.fetch(method)
+      # map_read_state's later pages are read at the first page's revision,
+      # unless the request pins one itself.
+      pin = method == "map_read_state" && !w.key?("revision_offset") && !w.key?("revision_epoch")
+      state = StreamPosition.new(offset: w["revision_offset"] || 0, epoch: w["revision_epoch"] || "") unless pin
+      loop do
+        res = invoke(method, result_class, page_timeout) { w }
+        page = res.public_send(items)
+        state ||= res.position if method == "map_read_state"
+        page.each do |item|
+          yield case method
+                when "history" then HistoryItem.new(publication: item, epoch: res.epoch)
+                when "map_read_state" then MapStateItem.new(entry: item, state:)
+                else item
+                end
+        end
+        if cursor.nil?
+          break if page.size < w["limit"]
+
+          w = w.merge("since" => position(page.last.offset, res.epoch))
+        else
+          following = res.public_send(cursor)
+          break if following.empty?
+
+          w = w.merge("cursor" => following)
+          if pin
+            w = w.merge(position(res.offset, res.epoch).transform_keys { "revision_#{it}" })
+            pin = false
+          end
+        end
+      end
+    end
+
+    # A stream position as the JSON of a request, zero values left out.
+    def position(offset, epoch)
+      w = {}
+      w["offset"] = offset unless offset.zero?
+      w["epoch"] = epoch unless epoch.empty?
+      w
+    end
+  end
+end