cent 4.0.0 → 5.0.0

data/lib/cent/payload.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module Cent
+  # Payloads - data, info, meta and the like - are JSON values: a Hash, Array,
+  # String, Integer, Float, true, false or nil, Symbols allowed as strings and
+  # Hash keys. Raw JSON - text you already have, or encoded with rules of your
+  # own - goes in a +JSON::Fragment+, sent as it is:
+  #
+  #   client.publish(channel: "news", data: { text: "hi" })
+  #   client.publish(channel: "news", data: JSON::Fragment.new(row["payload_json"]))
+  #
+  # A String is a JSON string, never raw JSON. Replies give payloads as
+  # +JSON.parse+ gives them - Hashes with String keys - which go back unchanged
+  # as the same JSON value.
+  #
+  # @api private
+  module Payload
+    # Deeper than this, a payload is refused: Centrifugo's decoder stops at
+    # 10000 levels, and a value which contains itself never ends.
+    MAX_DEPTH = 1000
+
+    module_function
+
+    # Checks that a payload is a JSON value, raising InvalidRequestError naming
+    # where it is not. The checked value is sent as it is.
+    #
+    # @return [Object] value
+    def check!(value, where)
+      # Iterative, not recursive: a deep value must not overflow the stack,
+      # which is small on some platforms - a thread's on Windows.
+      stack = [[value, where, 0]]
+      until stack.empty?
+        v, path, depth = stack.pop
+        raise InvalidRequestError, "#{path} is nested too deeply, or contains itself" if depth > MAX_DEPTH
+
+        case v
+        when Hash
+          v.each do |k, item|
+            key!(k, path)
+            stack << [item, "#{path}.#{k}", depth + 1]
+          end
+        when Array then v.each_with_index { |item, i| stack << [item, "#{path}[#{i}]", depth + 1] }
+        else scalar!(v, path)
+        end
+      end
+      value
+    end
+
+    def key!(k, path)
+      case k
+      when String then string!(k, "#{path} key #{k.inspect}")
+      when Symbol then nil
+      else raise InvalidRequestError, "#{path} has a #{k.class} key, #{k.inspect}: JSON object keys are strings"
+      end
+    end
+
+    def scalar!(v, path)
+      case v
+      when String then string!(v, path)
+      when Float
+        raise InvalidRequestError, "#{path} is #{v}, which is not a JSON number" unless v.finite?
+      when Integer, true, false, nil, Symbol then nil
+      when JSON::Fragment then fragment!(v, path)
+      else
+        raise InvalidRequestError,
+              "#{path} is a #{v.class}, which is not a JSON value: convert it - " \
+              "or encode the payload yourself and pass the JSON as JSON::Fragment.new(json)"
+      end
+    end
+
+    def string!(s, where)
+      if s.encoding == Encoding::BINARY
+        raise InvalidRequestError,
+              "#{where} is a binary (ASCII-8BIT) string: force_encoding(\"UTF-8\") text read as bytes, " \
+              "or send binary data base64-encoded in a b64 field, such as b64data"
+      end
+      raise InvalidRequestError, "#{where} is not valid #{s.encoding}" unless s.valid_encoding?
+    end
+
+    # Raw JSON is checked to be valid JSON, NaN and infinities refused.
+    def fragment!(f, where)
+      json = f.json
+      unless json.is_a?(String)
+        raise InvalidRequestError, "#{where} is a JSON::Fragment of a #{json.class}: it holds JSON text"
+      end
+
+      string!(json, where)
+      JSON.parse(json, allow_nan: false, max_nesting: false)
+    rescue JSON::ParserError => e
+      raise InvalidRequestError, "#{where} is a JSON::Fragment which is not valid JSON: #{e.message}"
+    end
+  end
+end

data/lib/cent/proxy.rb

@@ -0,0 +1,254 @@
+# frozen_string_literal: true
+
+module Cent
+  # The application side of Centrifugo's HTTP proxy: the requests Centrifugo
+  # sends to the backend when a client connects, subscribes, publishes or calls
+  # an RPC, the results the backend answers with, and a handler for each proxy
+  # type which decodes the request, calls a block and encodes its answer. Each
+  # handler is a {Handler}: a Rack app, with a framework-free core.
+  #
+  #   connect = Cent::Proxy::ConnectHandler.new(on_error: ->(_http, err) { logger.error(err) }) do |req, http|
+  #     user = session_user(http.headers["cookie"])    # passed on with http_headers
+  #     raise Cent::Proxy::Disconnect.new(4501, "unauthorized") unless user
+  #
+  #     Cent::Proxy::ConnectResult.new(user:)          # or a Hash: { user: }
+  #   end
+  #   mount connect, at: "/centrifugo/connect"       # config/routes.rb
+  #
+  # and in Centrifugo's configuration:
+  #
+  #   "client": {"proxy": {"connect": {"enabled": true,
+  #     "endpoint": "http://backend:3000/centrifugo/connect", "http_headers": ["Cookie"]}}}
+  #
+  # See https://centrifugal.dev/docs/server/proxy.
+  #
+  # The block gets the decoded request and the {HTTPRequest}, and returns a
+  # result - the result type, or a Hash of its fields - to accept the request,
+  # or raises:
+  #
+  # - {ProxyError} rejects the request with that error, which the client
+  #   receives: use codes in [400, 1999]. The connect, subscribe, publish, RPC,
+  #   map publish and map remove proxies pass it to the client; the shared poll
+  #   refresh and channel state proxies take it as a failure.
+  # - {Disconnect} closes the client's connection with that code: use codes in
+  #   [4000, 4999] - [4500, 4999] to tell the client not to reconnect. Only the
+  #   proxies which pass a ProxyError to the client honour it.
+  # - Any other error, or one a proxy cannot carry, fails the request with HTTP
+  #   status 500, and is passed to +on_error+ for logging - without +on_error+,
+  #   it is logged nowhere. Centrifugo then
+  #   answers the client with its temporary internal error; for refresh and sub
+  #   refresh it keeps the connection or subscription for another minute and
+  #   asks again.
+  #
+  # A ProxyError or Disconnect which is the cause of another error counts too.
+  # The refresh and sub refresh proxies end a connection or subscription
+  # through their result's expired, not an error. A handler answers with
+  # exactly one of result, error and disconnect - a block returning nil fails
+  # with 500 too. Centrifugo would take a response with none of them as
+  # accepting a subscribe, publish, RPC, map publish or map remove as the
+  # client sent it; as refusing a connect, unless anonymous connections are
+  # allowed; and as a refresh or sub refresh which expired.
+  #
+  # Payloads - data, info, meta - arrive as JSON.parse gives them, and a result
+  # takes them back as they are, or as JSON::Fragment. A proxy with
+  # binary_encoding enabled sends them base64-encoded in the b64 fields, with
+  # encoding "binary"; a result may answer with either field.
+  #
+  # Security: Centrifugo trusts what a proxy endpoint answers, and the endpoint
+  # trusts what Centrifugo sends - a SubscribeRequest's user is the user
+  # Centrifugo authenticated. Anyone else able to reach the endpoint could claim
+  # any user. Keep proxy endpoints reachable by Centrifugo only: on a network
+  # only Centrifugo reaches; behind a secret header Centrifugo adds to every
+  # proxy request - the proxy's static_headers option - which the application
+  # checks before the handler; with TLS where the traffic leaves a trusted
+  # network.
+  #
+  # Centrifugo's GRPC proxy is not covered: generate GRPC code from proxy.proto
+  # for it.
+  module Proxy
+    # The default bound of a request's body, 16 MiB: far above what
+    # Centrifugo's own limits on client messages let through, it only stops a
+    # request which is not Centrifugo's from taking the memory it likes.
+    DEFAULT_MAX_BODY = 16 << 20
+
+    # Raised by a proxy block to reject the client's request with this error:
+    # code in [400, 1999], which Centrifugo leaves to applications. temporary
+    # tells the client that retrying may succeed.
+    class ProxyError < StandardError
+      # @return [Integer]
+      attr_reader :code
+      # @return [String]
+      attr_reader :reason
+
+      # @param code [Integer]
+      # @param reason [String] the error's message, sent to the client
+      # @param temporary [Boolean]
+      def initialize(code, reason = "", temporary: false)
+        @code = code
+        @reason = reason
+        @temporary = temporary
+        super("#{reason} (code #{code})")
+      end
+
+      # @return [Boolean]
+      def temporary? = @temporary
+    end
+
+    # Raised by a proxy block to close the client's connection: code in [4000,
+    # 4999] - [4000, 4499] tells the client to reconnect, [4500, 4999] not to.
+    # reason is a short description, at most 32 bytes.
+    class Disconnect < StandardError
+      # @return [Integer]
+      attr_reader :code
+      # @return [String]
+      attr_reader :reason
+
+      # @param code [Integer]
+      # @param reason [String]
+      def initialize(code, reason = "")
+        @code = code
+        @reason = reason
+        super("disconnect: #{reason} (code #{code})")
+      end
+    end
+
+    # @api private
+    class ProxyHandler < Handler
+      # @param on_error [#call, nil] told of every 500 and 400, with the
+      #   {HTTPRequest} and the error; it must not raise. Pass one: without it,
+      #   an error in the block is answered with 500 and logged nowhere.
+      # @param max_body [Integer] the largest request body read, in bytes
+      def initialize(on_error: nil, max_body: DEFAULT_MAX_BODY, &) = super(max_body, on_error, &)
+
+      private
+
+      def start(req, body)
+        return HTTPResponse.allow("POST") unless req.method == "POST"
+
+        name, request_class, = self.class::SPEC
+        [request_class.from_wire(JSON.parse(body, allow_nan: false, max_nesting: false), "#{name} request")]
+      rescue JSON::ParserError, EncodingError, DecodeError => e
+        failure(req, 400, ArgumentError.new("proxy: malformed #{name} request: #{e.message}"))
+      end
+
+      def finish(req, _args, out, error)
+        name, _, result_class, answers = self.class::SPEC
+        if error.nil?
+          begin
+            wire = { "result" => Wire.message(result_class, out, "result").to_wire("result.") }
+          rescue InvalidRequestError => e
+            return failure(req, 500, TypeError.new("proxy: the #{name} block returned an invalid result: #{e.message}"))
+          end
+        else
+          d = find(error, Disconnect)
+          e = find(error, ProxyError)
+          if d && answers == :disconnect
+            wire = { "disconnect" => { "code" => d.code, "reason" => d.reason } }
+          elsif e && answers != :result
+            wire = { "error" => { "code" => e.code, "message" => e.reason } }
+            wire["error"]["temporary"] = true if e.temporary?
+          elsif d || e
+            # Centrifugo would ignore it in this proxy's response.
+            return failure(req, 500, ArgumentError.new("proxy: the #{name} proxy cannot answer with #{error.inspect}"))
+          else
+            return failure(req, 500, error)
+          end
+        end
+        HTTPResponse.new(status: 200, headers: { "content-type" => "application/json" }, body: Client.encode(wire))
+      rescue InvalidRequestError => e
+        # A payload which is not JSON, say: Centrifugo could not use the
+        # response.
+        failure(req, 500, e)
+      end
+    end
+
+    # The connect proxy: the block authenticates a connecting client and
+    # returns its user and initial state. ProxyError rejects the connection;
+    # Disconnect closes it with that code.
+    class ConnectHandler < ProxyHandler
+      # @api private
+      SPEC = ["connect", ConnectRequest, ConnectResult, :disconnect].freeze
+    end
+
+    # The refresh proxy: the block decides whether a connection about to expire
+    # lives on, and until when. To end it, return a result with expired set.
+    # Any error fails the request, and Centrifugo keeps the connection for
+    # another minute before asking again.
+    class RefreshHandler < ProxyHandler
+      # @api private
+      SPEC = ["refresh", RefreshRequest, RefreshResult, :result].freeze
+    end
+
+    # The subscribe proxy: the block decides whether a client may subscribe to
+    # a channel. ProxyError rejects the subscription; Disconnect closes the
+    # connection.
+    class SubscribeHandler < ProxyHandler
+      # @api private
+      SPEC = ["subscribe", SubscribeRequest, SubscribeResult, :disconnect].freeze
+    end
+
+    # The publish proxy: the block decides whether a client may publish into a
+    # channel, and may change the publication. ProxyError rejects it;
+    # Disconnect closes the connection.
+    class PublishHandler < ProxyHandler
+      # @api private
+      SPEC = ["publish", PublishRequest, PublishResult, :disconnect].freeze
+    end
+
+    # The RPC proxy: the block answers a client's RPC call. ProxyError fails the
+    # call; Disconnect closes the connection.
+    class RPCHandler < ProxyHandler
+      # @api private
+      SPEC = ["rpc", RPCRequest, RPCResult, :disconnect].freeze
+    end
+
+    # The sub refresh proxy: the block decides whether a subscription about to
+    # expire lives on, and until when. To end it, return a result with expired
+    # set. Any error fails the request, and Centrifugo keeps the subscription
+    # for another minute before asking again.
+    class SubRefreshHandler < ProxyHandler
+      # @api private
+      SPEC = ["sub refresh", SubRefreshRequest, SubRefreshResult, :result].freeze
+    end
+
+    # The map publish proxy: the block decides whether a client may publish a
+    # key into a map channel, and may change the publication.
+    class MapPublishHandler < ProxyHandler
+      # @api private
+      SPEC = ["map publish", MapPublishRequest, MapPublishResult, :disconnect].freeze
+    end
+
+    # The map remove proxy: the block decides whether a client may remove a key
+    # from a map channel.
+    class MapRemoveHandler < ProxyHandler
+      # @api private
+      SPEC = ["map remove", MapRemoveRequest, MapRemoveResult, :disconnect].freeze
+    end
+
+    # The shared poll refresh proxy: the block returns the current data of the
+    # items tracked in a shared poll channel. ProxyError, or any other error,
+    # fails the refresh: Centrifugo tries again at the next interval.
+    class SharedPollRefreshHandler < ProxyHandler
+      # @api private
+      SPEC = ["shared poll refresh", SharedPollRefreshRequest, SharedPollRefreshResult, :error].freeze
+    end
+
+    # The cache empty proxy of Centrifugo PRO: the block learns that a client
+    # subscribed to a channel in cache recovery mode with nothing to recover,
+    # and may publish the current state - then it returns a result with
+    # populated set, for Centrifugo to recover once more. Any error fails the
+    # request, and the client which subscribed is disconnected to reconnect.
+    class NotifyCacheEmptyHandler < ProxyHandler
+      # @api private
+      SPEC = ["cache empty", NotifyCacheEmptyRequest, NotifyCacheEmptyResult, :result].freeze
+    end
+
+    # The channel state proxy of Centrifugo PRO, in preview: the block receives
+    # channels becoming occupied or vacated. ProxyError, or any other error,
+    # fails the request.
+    class NotifyChannelStateHandler < ProxyHandler
+      # @api private
+      SPEC = ["channel state", NotifyChannelStateRequest, NotifyChannelStateResult, :error].freeze
+    end
+  end
+end

data/lib/cent/reply.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module Cent
+  # Reading Centrifugo's replies, and the rules checked before sending.
+  #
+  # @api private
+  module Reply
+    # Statuses Centrifugo's transport error mode maps errors to.
+    TRANSPORT_MODE_STATUSES = [400, 404, 409, 416, 429, 500].freeze
+    MIN_ERROR_CODE = 100
+    # nil is "no data", as for every keyword: how to publish JSON null.
+    NULL_HINT = " (to publish JSON null, pass data: JSON::Fragment.new(\"null\"))"
+
+    module_function
+
+    def parse(body, method)
+      JSON.parse(body, allow_nan: false, max_nesting: false)
+    rescue JSON::ParserError, EncodingError => e
+      raise DecodeError, "#{method}: the reply is not JSON: #{e.message}"
+    end
+
+    # The decoded reply of a method: [its result, its error].
+    def envelope(body, method)
+      d = parse(body, method)
+      raise DecodeError, "#{method}: the reply is not a JSON object" unless d.is_a?(Hash)
+      return [{}, api_error(d["error"], "error")] unless d["error"].nil?
+
+      result = d["result"]
+      return [{}, nil] if result.nil?
+      raise DecodeError, "#{method}: result: expected an object" unless result.is_a?(Hash)
+
+      [result, nil]
+    end
+
+    # The replies of a batch of n commands.
+    def batch(body, n)
+      d = parse(body, "batch")
+      raise DecodeError, "batch: the reply is not a JSON object" unless d.is_a?(Hash)
+      raise api_error(d["error"], "error") unless d["error"].nil?
+
+      replies = d["replies"] || []
+      unless replies.is_a?(Array) && replies.all?(Hash)
+        raise DecodeError, "batch: replies: expected an array of objects"
+      end
+      raise DecodeError, "batch: got #{replies.size} replies for #{n} commands" if replies.size != n
+
+      replies
+    end
+
+    # The ApiError of an error object in a reply.
+    def api_error(v, where)
+      d = Wire.obj(v, where)
+      ApiError.for_code(Wire.get(d, "code", where, :int), Wire.get(d, "message", where, :str),
+                        temporary: Wire.get(d, "temporary", where, :bool))
+    end
+
+    # The error of a batch command's reply, if it has one. A PRO method's code
+    # 104 hints that the server may be Centrifugo OSS.
+    def command_error(reply, i, method)
+      return nil if reply["error"].nil?
+
+      err = api_error(reply["error"], "replies[#{i}].error")
+      err.pro_method!(method) if err.code == NotFoundError::CODE && API_METHODS[method]
+      err
+    end
+
+    # The error of a reply with a status other than 200: a Centrifugo error in
+    # the transport error mode, an HTTPError otherwise.
+    def http_error(method, status, body, headers)
+      if TRANSPORT_MODE_STATUSES.include?(status)
+        d = begin
+          JSON.parse(body)
+        rescue JSON::ParserError, EncodingError
+          nil
+        end
+        # A body whose code is an HTTP error status - {"code": 429} from a rate
+        # limiting gateway - is a gateway's, not Centrifugo's.
+        code = d["code"] if d.is_a?(Hash)
+        if code.is_a?(Integer) && code >= MIN_ERROR_CODE && !(400..599).cover?(code)
+          begin
+            return api_error(d, "error")
+          rescue DecodeError
+            nil
+          end
+        end
+      end
+      start = body.byteslice(0, HTTP::MAX_ERROR_BODY_BYTES).strip
+      err = (status == 401 ? UnauthorizedError : HTTPError).new(status, start, headers)
+      err.pro_method!(method) if API_METHODS[method]
+      err
+    end
+
+    # The rules every Centrifugo holds a request to, checked before sending:
+    # the fields the proto marks required, and publish's and broadcast's data.
+    # Everything else Centrifugo checks itself.
+    def validate(method, w)
+      Wire.check_required(w, method)
+      case method
+      when "publish"
+        raise InvalidRequestError, "data or b64data is required#{NULL_HINT}" unless w.key?("data") || w["b64data"]
+      when "broadcast"
+        raise InvalidRequestError, "data or b64data is required#{NULL_HINT}" unless w.key?("data") || w["b64data"]
+
+        w["channels"].each_with_index { |ch, i| raise InvalidRequestError, "channels[#{i}] is empty" if ch.empty? }
+      end
+      w
+    end
+  end
+end

data/lib/cent/retry.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Cent
+  # The wait, in seconds, before retrying after a failed attempt, attempt 1
+  # being the first failure: +base+ after it, twice as long after each next one,
+  # up to +limit+. Each wait is a random time between half of it and all of it,
+  # so that clients which failed together do not all retry at the same moment. A
+  # negative base counts as zero, a limit below base as base, and an attempt
+  # below 1 as 1.
+  #
+  # In a retry loop of your own - a publication retried with the same
+  # idempotency_key:
+  #
+  #   backoff = Cent.exponential_backoff(0.1, 2.0)
+  #   attempt = 0
+  #   begin
+  #     attempt += 1
+  #     client.publish(channel: "orders:42", data:, idempotency_key: "order-42-paid")
+  #   rescue Cent::Error => e
+  #     raise unless Cent.retryable?(e) && attempt < 3
+  #
+  #     sleep(backoff.(attempt))
+  #     retry
+  #   end
+  #
+  # Retry a broadcast with broadcast_with_retry instead: repeating it resends to
+  # the channels which already got it.
+  #
+  # @param base [Numeric] seconds
+  # @param limit [Numeric] seconds
+  # @return [Proc] taking the attempt, returning seconds
+  def self.exponential_backoff(base, limit)
+    base = [base.to_f, 0.0].max
+    limit = [limit.to_f, base].max
+    lambda do |attempt|
+      d = base
+      (1...[attempt, 1].max).each do
+        # A zero base never grows: no need to count the attempts out.
+        break if d >= limit || d.zero?
+
+        d *= 2
+      end
+      d = [d, limit].min
+      (d / 2) + (rand * (d / 2))
+    end
+  end
+
+  DEFAULT_BACKOFF = exponential_backoff(0.1, 5.0)
+  private_constant :DEFAULT_BACKOFF
+
+  # @api private
+  def self.default_delay(attempt) = DEFAULT_BACKOFF.call(attempt)
+end

data/lib/cent/shared_poll.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require "openssl"
+
+module Cent
+  # Signatures for shared poll subscriptions. See
+  # https://centrifugal.dev/docs/server/shared_poll. Shared poll subscriptions
+  # are experimental in Centrifugo, and this module follows their changes.
+  module SharedPoll
+    module_function
+
+    # The signature authorizing +user+ to track +keys+ in +channel+ until
+    # +expires_at+, as Centrifugo verifies it: "iat:exp:hmac", iat now and exp
+    # expires_at in Unix seconds. +expires_at+ is required, as a token's expiry
+    # is: a Time, or +:never+ for a signature which never expires - an Integer
+    # or a Duration, such as +1.hour+, is refused. +secret+ is Centrifugo's
+    # shared_poll.hmac_secret_key; +user+ is the ID of the connection's user,
+    # empty for an anonymous one.
+    #
+    # The signature covers exactly +keys+, in their order: a client tracking
+    # other keys, or the same in another order, is refused.
+    #
+    #   Cent::SharedPoll.sign(secret, user: "42", channel: "poll:prices", keys: ["AAPL"], expires_at: Time.now + 3600)
+    #
+    # @param secret [String]
+    # @param user [String]
+    # @param channel [String]
+    # @param keys [Array<String>]
+    # @param expires_at [Time, :never]
+    # @return [String]
+    def sign(secret, user:, channel:, keys:, expires_at:)
+      sign_at(Time.now, secret, user:, channel:, keys:, expires_at:)
+    end
+
+    # sign, at the time +now+: for the spec's test vectors.
+    def sign_at(now, secret, user:, channel:, keys:, expires_at:)
+      raise Error, "shared poll: the secret must be a non-empty String" unless secret.is_a?(String) && !secret.empty?
+
+      iat = now.to_i.to_s
+      exp = expires_at == :never ? "0" : unix(expires_at).to_s
+      keys_hash = OpenSSL::Digest::SHA256.hexdigest(keys.join("\0"))
+      # NUL-separated, so that a colon in a user or channel cannot move between
+      # fields: ("alice", "news:tech") and ("alice:news", "tech") sign
+      # differently.
+      msg = [iat, exp, user, channel, keys_hash].join("\0")
+      "#{iat}:#{exp}:#{OpenSSL::HMAC.hexdigest("SHA256", secret, msg)}"
+    end
+
+    def unix(t)
+      t = t.to_time if !t.is_a?(Time) && t.respond_to?(:to_time)
+      unless t.is_a?(Time)
+        raise Error, "shared poll: expires_at must be a Time, or :never for a signature which never expires - " \
+                     "not #{t.class}"
+      end
+
+      t.to_i
+    end
+
+    private_class_method :sign_at, :unix
+  end
+end