cent 4.0.0 → 5.0.0

data/lib/cent/command.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Cent
+  # An API call left for Centrifugo's async consumers to make: written to a
+  # PostgreSQL outbox table, a Kafka topic, a Redis stream. See
+  # https://centrifugal.dev/docs/server/consumers.
+  #
+  # There is a class method per API method, taking the fields of its request as
+  # keyword arguments, as Client's methods do. The call is checked as a Client
+  # checks it before sending - an invalid one raises InvalidRequestError here,
+  # rather than in Centrifugo, whose consumers drop a command they cannot run -
+  # and encoded:
+  #
+  #   cmd = Cent::Command.publish(channel: "news", data: { text: "hi" })
+  #   db.exec_params("INSERT INTO centrifugo_outbox (method, payload, partition) VALUES ($1, $2, 0)",
+  #                  [cmd.method, cmd.payload])
+  #
+  # Consumers take it as its method and payload apart - the outbox table's
+  # method and payload columns, a message attribute - or as the JSON message
+  # +{"method": ..., "payload": ...}+ of {#to_json} (Kafka, NATS JetStream).
+  # {#as_json} gives that message with payload as a Hash, so a command inside
+  # another value - rendered by Rails, say - carries an object, not a string.
+  #
+  # The outbox table's payload column is jsonb: raw SQL passes {#payload}, JSON
+  # text, as it is; ActiveRecord's json types take the object,
+  # +JSON.parse(cmd.payload)+ - given the text, they would store a JSON string.
+  #
+  # Where the method goes apart from the payload - the outbox table's method
+  # column, a message header or attribute - Centrifugo reads the payload as the
+  # request itself: a JSON string holding it is a bad request there, dropped
+  # with only Centrifugo's log saying so. Only a message which is a whole
+  # command may hold its payload as a string of JSON, for CDC pipelines.
+  #
+  # Within a partition a consumer keeps commands in order: a channel's commands
+  # keep their order only when every writer derives their partition from the
+  # channel the same way - the channel as a Kafka message key, say.
+  #
+  # @!attribute [r] method
+  #   @return [String] the API method, such as "publish"
+  # @!attribute [r] payload
+  #   @return [String] the request, as JSON text
+  class Command < Data.define(:method, :payload)
+    extend CommandMethods
+
+    # The command as one JSON message: +{"method": ..., "payload": ...}+, the
+    # payload's text kept exactly.
+    #
+    # @return [String]
+    def to_json(*) = "{\"method\":#{JSON.generate(method)},\"payload\":#{payload}}"
+
+    # The message of {#to_json} as Ruby values, payload a Hash.
+    #
+    # @return [Hash{String => Object}]
+    def as_json(*) = { "method" => method, "payload" => JSON.parse(payload) }
+
+    def self.build(method)
+      w = Reply.validate(method, yield)
+      new(method:, payload: Client.encode(w))
+    rescue InvalidRequestError => e
+      raise InvalidRequestError, "invalid #{method} request: #{e.message}"
+    end
+    private_class_method :build
+  end
+end

data/lib/cent/endpoints.rb

@@ -0,0 +1,191 @@
+# frozen_string_literal: true
+
+module Cent
+  # The HTTP endpoints client SDKs call: for connection and subscription tokens
+  # - what their getToken callbacks fetch - and for shared poll signatures, plus
+  # the JSON Web Key Set Centrifugo fetches. Each is a {Handler}: a Rack app,
+  # with a framework-free core.
+  #
+  #   conn = Cent::Endpoints::ConnectionToken.new(on_error: ->(_http, err) { logger.error(err) }) do |req|
+  #     user = session_user(req.raw)                     # the Rack env
+  #     raise Cent::Endpoints::ForbiddenError unless user
+  #
+  #     Cent::Token.connection(key, user:, expires_at: Time.now + 15 * 60)
+  #   end
+  #   mount conn, at: "/centrifugo/connection_token"   # config/routes.rb
+  #
+  # An endpoint answers a JSON object, never cached; ForbiddenError - also as the
+  # cause of another error - with 403, on which client SDKs stop asking, and
+  # disconnect or unsubscribe; any other error with 500, which they retry. A
+  # malformed request gets 400, a wrong method 405. +on_error+, when set, is
+  # told of every 500 and 400, with the request and the error - without it, an
+  # error in the block is logged nowhere.
+  module Endpoints
+    # Bodies are read up to 1 MiB.
+    MAX_BODY = 1 << 20
+
+    # Raised by the block of an endpoint when the user may not have a token or
+    # signature: answered with 403, on which client SDKs stop asking, and
+    # disconnect or unsubscribe. Client SDKs report it as their
+    # UnauthorizedError. It is not the API client's {Cent::UnauthorizedError},
+    # which means Centrifugo refused this server's credentials: the two are
+    # named apart so that rescuing one where the other is meant cannot pass
+    # silently.
+    class ForbiddenError < StandardError
+      def initialize(msg = "forbidden") = super
+    end
+
+    # @api private
+    class Endpoint < Handler
+      # @param on_error [#call, nil] told of every 500 and 400, with the
+      #   request and the error; it must not raise. Pass one: without it, an
+      #   error in the block is answered with 500 and logged nowhere.
+      def initialize(on_error: nil, &) = super(MAX_BODY, on_error, &)
+
+      private
+
+      def answer(req, body, error)
+        if error
+          return HTTPResponse.text(403, "Forbidden") if find(error, ForbiddenError)
+
+          return failure(req, 500, error)
+        end
+        HTTPResponse.json(JSON.generate(body))
+      end
+
+      def token(req, out, error)
+        if error.nil? && !(out.is_a?(String) && !out.empty?)
+          error = TypeError.new("the block returned #{out.class}, not a token")
+        end
+        answer(req, error ? nil : { "token" => out }, error)
+      end
+    end
+
+    # The endpoint a client's getToken callback calls. Its block, given the
+    # {HTTPRequest}, returns the connection token of the request's user - from
+    # {Token.connection}, say - or raises ForbiddenError. It takes GET and POST,
+    # the body ignored.
+    class ConnectionToken < Endpoint
+      private
+
+      def start(req, _body)
+        return HTTPResponse.allow("GET, POST") unless %w[GET POST].include?(req.method)
+
+        []
+      end
+
+      def finish(req, _args, out, error) = token(req, out, error)
+    end
+
+    # The endpoint a subscription's getToken callback calls. Its block, given
+    # the channel and the {HTTPRequest}, returns the token of the request's
+    # user for the channel - from {Token.subscription}, say - or raises
+    # ForbiddenError when the user may not subscribe. The channel comes from a
+    # POST's JSON body, +{"channel": ...}+, or from a GET's channel query
+    # parameter; it is required.
+    #
+    #   Cent::Endpoints::SubscriptionToken.new do |channel, req|
+    #     user = session_user(req.raw)
+    #     raise Cent::Endpoints::ForbiddenError unless user && may_read?(user, channel)
+    #
+    #     Cent::Token.subscription(key, user:, channel:, expires_at: Time.now + 15 * 60)
+    #   end
+    class SubscriptionToken < Endpoint
+      private
+
+      def start(req, body)
+        case req.method
+        when "GET" then channel = req.query.fetch("channel", "")
+        when "POST"
+          d = parse_json(req, body)
+          return d if d.is_a?(HTTPResponse)
+
+          channel = d.fetch("channel", "")
+          unless channel.is_a?(String)
+            return failure(req, 400,
+                           ArgumentError.new("malformed request: channel is not a string"))
+          end
+        else return HTTPResponse.allow("GET, POST")
+        end
+        return failure(req, 400, ArgumentError.new("subscription token request without a channel")) if channel.empty?
+
+        [channel]
+      end
+
+      def finish(req, _args, out, error) = token(req, out, error)
+    end
+
+    # The endpoint a shared poll subscription's getSignature callback calls: a
+    # POST of +{"channel": ..., "keys": [...]}+, answered +{"signature": ...,
+    # "keys": [...]}+.
+    #
+    # Its block, given the channel, the keys and the {HTTPRequest}, decides
+    # which of the keys the user may track in the channel, signs them - with
+    # {SharedPoll.sign}, say - and returns them, in the order signed, with the
+    # signature: +[allowed, signature]+. The keys it leaves out are revoked:
+    # the client stops tracking them. To end the subscription instead, it
+    # raises ForbiddenError. It may return only keys it was asked for: a
+    # signature covering another would be refused, and such a key fails the
+    # request with 500.
+    class SharedPollSignature < Endpoint
+      private
+
+      def start(req, body)
+        return HTTPResponse.allow("POST") unless req.method == "POST"
+
+        d = parse_json(req, body)
+        return d if d.is_a?(HTTPResponse)
+
+        channel = d.fetch("channel", "")
+        keys = d["keys"] || []
+        unless channel.is_a?(String) && keys.is_a?(Array) && keys.all?(String)
+          return failure(req, 400, ArgumentError.new("malformed request: channel and keys must be strings"))
+        end
+        return failure(req, 400, ArgumentError.new("signature request without a channel")) if channel.empty?
+
+        [channel, keys]
+      end
+
+      def finish(req, args, out, error)
+        return answer(req, nil, error) if error
+
+        allowed, signature = out if out.is_a?(Array) && out.size == 2
+        unless signature.is_a?(String) && allowed.is_a?(Array) && allowed.all?(String)
+          return answer(req, nil, TypeError.new("the block must return [keys, signature]"))
+        end
+
+        extra = allowed - args[1]
+        unless extra.empty?
+          return answer(req, nil,
+                        ArgumentError.new("signed key #{extra.first.inspect} the client did not ask for"))
+        end
+
+        # The SDK reads the keys as an array, empty included.
+        answer(req, { "signature" => signature, "keys" => allowed }, nil)
+      end
+    end
+
+    # Serves the JSON Web Key Set of +keys+ - see {Token.jwks} - at the URL
+    # configured as Centrifugo's client.token.jwks_public_endpoint, or PRO's
+    # http_api.jwks.endpoint. It answers GET and HEAD, cacheable for five
+    # minutes. A set Token.jwks refuses fails here, when the endpoint is built.
+    class JWKS < Handler
+      # @param keys [Array<Token::Key>]
+      # @raise [Token::Error]
+      def initialize(*keys)
+        super(MAX_BODY, nil)
+        @body = Token.jwks(*keys)
+      end
+
+      private
+
+      def answers_itself? = true
+
+      def start(req, _body)
+        return HTTPResponse.allow("GET, HEAD") unless %w[GET HEAD].include?(req.method)
+
+        HTTPResponse.json(req.method == "GET" ? @body : "", "public, max-age=300")
+      end
+    end
+  end
+end

data/lib/cent/errors.rb

@@ -0,0 +1,392 @@
+# frozen_string_literal: true
+
+module Cent
+  # How many failures an aggregate error names in its message; all of them stay
+  # available in the error itself.
+  MAX_ERROR_ITEMS = 3
+  private_constant :MAX_ERROR_ITEMS
+
+  # The base of every error cent raises.
+  class Error < StandardError
+    # @return [String, nil] set on the error broadcast_with_retry raises when no
+    #   attempt got a reply - a timeout, say - to the key its attempts carried,
+    #   made for the call when the request had none: Centrifugo may have
+    #   published, and a retry with this key does not publish twice. Nil on
+    #   other errors.
+    attr_accessor :idempotency_key
+  end
+
+  # An error of Centrifugo itself: it understood the request and refused it, or
+  # failed to carry it out.
+  #
+  # Centrifugo identifies an error by its {#code}; {#server_message} is for
+  # people and may change. Errors with a known code are raised as the subclass
+  # for it - +rescue Cent::UnknownChannelError+ - and any other code as ApiError
+  # itself: Centrifugo adds codes from time to time, so rescue the ones you
+  # handle and treat the rest by their class.
+  class ApiError < Error
+    # @return [Integer] the error code: stable, compare it
+    attr_reader :code
+    # @return [String] Centrifugo's message, for people: never compare it
+    attr_reader :server_message
+
+    # Whether Centrifugo marked the error temporary: the same request may
+    # succeed if retried later - a broker being unavailable, a rate limit - not
+    # because of the request. It does not mean nothing was done: a publication
+    # may have happened, so retry it with the same idempotency_key. Centrifugo
+    # versions before the field existed never set it; {Cent.retryable?} takes
+    # that into account.
+    #
+    # @return [Boolean]
+    def temporary? = @temporary
+
+    # @param code [Integer]
+    # @param server_message [String]
+    # @param temporary [Boolean]
+    def initialize(code, server_message = "", temporary: false)
+      @code = code
+      @server_message = server_message
+      @temporary = temporary
+      @pro_method = nil
+      super(nil)
+    end
+
+    # @return [String]
+    def to_s
+      s = "#{server_message.empty? ? "server error" : server_message} (code #{code})"
+      s += " (#{@pro_method} is a Centrifugo PRO method: is the server Centrifugo OSS?)" if @pro_method
+      s
+    end
+
+    # The error for a code: the subclass of a known code, ApiError otherwise.
+    #
+    # @return [ApiError]
+    def self.for_code(code, server_message = "", temporary: false)
+      (BY_CODE[code] || ApiError).new(code, server_message, temporary:)
+    end
+
+    # @api private
+    def pro_method!(method) = (@pro_method = method)
+  end
+
+  # Code 100: an internal error of Centrifugo, temporary.
+  class InternalError < ApiError
+    # The error code.
+    CODE = 100
+  end
+
+  # Code 102: the channel is not in a namespace Centrifugo is configured with.
+  class UnknownChannelError < ApiError
+    # The error code.
+    CODE = 102
+  end
+
+  # Code 104: what the request refers to was not found.
+  #
+  # A method only Centrifugo PRO has, sent in a batch to Centrifugo OSS, fails
+  # with it too, instead of the 404 it gets when sent alone.
+  class NotFoundError < ApiError
+    # The error code.
+    CODE = 104
+  end
+
+  # Code 107: Centrifugo refused the request as invalid.
+  class BadRequestError < ApiError
+    # The error code.
+    CODE = 107
+  end
+
+  # Code 108: the feature is not available - history or presence off in the
+  # channel's namespace, say.
+  class NotAvailableError < ApiError
+    # The error code.
+    CODE = 108
+  end
+
+  # Code 111: a rate limit was reached, temporary.
+  class TooManyRequestsError < ApiError
+    # The error code.
+    CODE = 111
+  end
+
+  # Code 112: the stream position asked for is not in the history any more.
+  class UnrecoverablePositionError < ApiError
+    # The error code.
+    CODE = 112
+  end
+
+  # Code 113: the request conflicts with the current state - a map publish
+  # whose version check failed, say.
+  class ConflictError < ApiError
+    # The error code.
+    CODE = 113
+  end
+
+  class ApiError
+    # @api private
+    BY_CODE = [
+      InternalError, UnknownChannelError, NotFoundError, BadRequestError,
+      NotAvailableError, TooManyRequestsError, UnrecoverablePositionError, ConflictError
+    ].to_h { [it::CODE, it] }.freeze
+  end
+
+  # A reply with an HTTP status other than 200: the request did not reach the
+  # API method. A 401 is an {UnauthorizedError}.
+  class HTTPError < Error
+    # @return [Integer]
+    attr_reader :status_code
+    # @return [String] the start of the reply's body, for diagnostics
+    attr_reader :body
+    # @return [Hash{String => String}] the reply's headers, lowercase names: a
+    #   request ID a proxy set, a +retry-after+
+    attr_reader :headers
+
+    # @param status_code [Integer]
+    # @param body [String]
+    # @param headers [Hash{String => String}]
+    def initialize(status_code, body = "", headers = {})
+      @status_code = status_code
+      @body = body
+      @headers = headers
+      @pro_method = nil
+      super(nil)
+    end
+
+    # @return [String]
+    def to_s
+      s = "unexpected HTTP status #{status_code}"
+      if (300..399).cover?(status_code)
+        # Centrifugo's API never redirects a call: its router redirects only
+        # a path not in canonical form, a doubled slash say, and a proxy in
+        # front of it may redirect http to https.
+        s += " (a redirect, which cent does not follow: check api_endpoint's scheme and path - http or https, " \
+             "a doubled slash)"
+      elsif status_code == 404 && @pro_method
+        s += " (#{@pro_method} is a Centrifugo PRO method: if other methods work, the server is Centrifugo OSS)"
+      elsif status_code == 404
+        # The usual cause: api_endpoint lacks the API prefix.
+        s += " (is api_endpoint the API base URL, such as http://localhost:8000/api?)"
+      elsif status_code == 401
+        s += " (check the credentials: api_key or bearer_token_func)"
+      end
+      s += ": #{body.dup.force_encoding(Encoding::UTF_8).scrub}" unless body.empty?
+      s
+    end
+
+    # @api private
+    def pro_method!(method) = (@pro_method = method)
+  end
+
+  # A 401: Centrifugo did not accept the credentials - the API key or the bearer
+  # token.
+  class UnauthorizedError < HTTPError; end
+
+  # The reply is not a Centrifugo API reply. The usual cause is an api_endpoint
+  # which does not point at Centrifugo's API, so that something else - a proxy,
+  # a web page - answers instead.
+  class DecodeError < Error; end
+
+  # A request the client can tell is wrong without sending it: one which cannot
+  # be encoded - a payload which is not JSON, in any request - or a publication
+  # without a channel or data. It is never sent.
+  #
+  # Only rules which hold for every Centrifugo are checked; everything else
+  # Centrifugo checks itself, and reports as a {BadRequestError}.
+  class InvalidRequestError < Error; end
+
+  # A client refused as configured: not created, or - on a call, before
+  # sending - given an endpoint by api_endpoint_func which fails api_endpoint's
+  # rules, or a token by bearer_token_func which is empty or not printable
+  # ASCII. The message names the option and the fix.
+  class InvalidConfigError < Error; end
+
+  # api_endpoint_func or bearer_token_func raised: the message names the
+  # function, and the cause is its exception. {Cent.retryable?} judges it by
+  # the cause: a Cent error as itself, a network failure or timeout as
+  # retryable, anything else as not.
+  class FunctionError < Error
+    # @return [String] the option holding the function: "api_endpoint_func" or
+    #   "bearer_token_func"
+    attr_reader :function
+
+    # @param function [String] the option holding the function
+    # @param message [String]
+    def initialize(function, message = "#{function} failed")
+      @function = function
+      super(message)
+    end
+  end
+
+  # A call made after the client was closed.
+  class ClosedError < Error; end
+
+  # The request failed on its way: a refused or reset connection, a failed TLS
+  # handshake. The cause is the error of the network.
+  class NetworkError < Error; end
+
+  # The request timed out: its timeout, or request_timeout. A request which
+  # timed out may still have been carried out.
+  class TimeoutError < Error; end
+
+  # A pending command's result read before its batch was sent.
+  class BatchNotSentError < Error; end
+
+  # A batch sent again: a batch is sent once.
+  class BatchSentError < Error; end
+
+  # A broadcast Centrifugo carried out which failed in one or more of its
+  # channels, up to all of them. {#result} holds every channel's outcome.
+  #
+  # It is not an ApiError of its parts: +rescue Cent::UnknownChannelError+ does
+  # not catch a broadcast in which one channel of many was unknown, nor one into
+  # a single channel - the broadcast as a whole is not unknown. Look at each
+  # channel's error in {#failed}.
+  class BroadcastFailedChannelsError < Error
+    # @return [Array<ChannelResult>] the channels which failed, with their
+    #   errors, in the order of the request
+    attr_reader :failed
+    # @return [Integer] how many channels the broadcast had
+    attr_reader :total
+    # @return [BroadcastResult] every channel's outcome
+    attr_reader :result
+
+    # For test doubles, say:
+    #
+    #   raise Cent::BroadcastFailedChannelsError.new(result.failed, result.channels.size, result)
+    #
+    # @param failed [Array<ChannelResult>]
+    # @param total [Integer]
+    # @param result [BroadcastResult]
+    def initialize(failed, total, result)
+      @failed = failed
+      @total = total
+      @result = result
+      super(nil)
+    end
+
+    # The channels whose failure is retryable, in the order of the request: the
+    # channels a retry should go to, with the same idempotency_key. Channels
+    # which failed for good, such as an unknown channel, are left out.
+    #
+    # @return [Array<String>]
+    def retryable_channels = failed.filter_map { it.channel if Cent.retryable?(it.error) }
+
+    # @return [String]
+    def to_s
+      items = failed.map { |ch| [ch.channel, ch.error] }
+      msg = Cent.failures_message("broadcast", "channels", "got the publication", total, items)
+      msg += " (retry only retryable_channels, with the same idempotency_key)" unless retryable_channels.empty?
+      msg
+    end
+  end
+
+  # The failure of one command of a batch.
+  #
+  # @!attribute [r] index
+  #   @return [Integer] the command's position in the batch, from zero
+  # @!attribute [r] method
+  #   @return [String] its API method, such as "publish"
+  # @!attribute [r] error
+  #   @return [Error] the error its pending raises: an ApiError, or a
+  #     BroadcastFailedChannelsError for a broadcast which failed in one or more
+  #     channels
+  class FailedCommand < Data.define(:index, :method, :error)
+    include Message
+  end
+
+  # A batch in which one or more commands failed, up to all of them. Every
+  # command got its own reply: each pending holds its outcome. {#result} is the
+  # batch's.
+  #
+  # It is not an ApiError of its parts: look at each command's error in
+  # {#failed}, or at its pending.
+  class BatchFailedCommandsError < Error
+    # @return [Array<FailedCommand>]
+    attr_reader :failed
+    # @return [Integer] how many commands the batch had
+    attr_reader :total
+    # @return [BatchResult]
+    attr_reader :result
+
+    # For test doubles, say.
+    #
+    # @param failed [Array<FailedCommand>]
+    # @param total [Integer]
+    # @param result [BatchResult]
+    def initialize(failed, total, result)
+      @failed = failed
+      @total = total
+      @result = result
+      super(nil)
+    end
+
+    # @return [String]
+    def to_s
+      items = failed.map { |f| ["##{f.index} #{f.method}", f.error] }
+      Cent.failures_message("batch", "commands", "succeeded", total, items)
+    end
+  end
+
+  # "broadcast: 2 of 4 channels failed, 2 got the publication: a: ...; b: ..."
+  #
+  # @api private
+  def self.failures_message(op, parts, rest, total, items)
+    s = "#{op}: #{items.size} of #{total} #{parts} failed"
+    s += ", #{total - items.size} #{rest}" if items.size < total
+    named = items.first(MAX_ERROR_ITEMS).map { |label, err| "#{label}: #{err.message}" }
+    named << "and #{items.size - MAX_ERROR_ITEMS} more" if items.size > MAX_ERROR_ITEMS
+    s += ": #{named.join("; ")}" unless named.empty?
+    s
+  end
+
+  # Whether a new attempt, with time left, may succeed after +err+: the error
+  # came from a temporary condition, not from the request.
+  #
+  # Retryable are an ApiError Centrifugo marked temporary, and code 100 from
+  # Centrifugo versions which did not mark errors yet; a network failure; a
+  # timeout, also a caller's own; an HTTPError 429 or 5xx; a broadcast or batch
+  # partial error with at least one retryable part.
+  #
+  # A FunctionError is judged by its cause, the configured function's own
+  # exception.
+  #
+  # Not retryable are the request's own errors - an unknown channel, a bad
+  # request, InvalidRequestError - and InvalidConfigError, ClosedError, a
+  # DecodeError, rejected credentials and an invalid TLS certificate.
+  #
+  # A retryable error does not mean nothing was done: retry a publication only
+  # with the same idempotency_key. Retry a broadcast with broadcast_with_retry,
+  # or only its retryable_channels: repeating the call resends to the channels
+  # which already got it.
+  #
+  # @param err [Exception, nil]
+  # @return [Boolean]
+  def self.retryable?(err)
+    case err
+    when BroadcastFailedChannelsError, BatchFailedCommandsError then err.failed.any? { retryable?(it.error) }
+    when ApiError then err.temporary? || err.code == InternalError::CODE
+    when HTTPError then err.status_code == 429 || err.status_code >= 500
+    when TimeoutError then true
+    when NetworkError then !certificate_error?(err)
+    when FunctionError
+      cause = err.cause
+      cause.is_a?(Error) ? retryable?(cause) : NETWORK_CAUSES.any? { cause.is_a?(it) }
+    else false
+    end
+  end
+
+  # The exceptions of a configured function which a retry may get past.
+  NETWORK_CAUSES = [SocketError, SystemCallError, IOError, ::Timeout::Error, IO::TimeoutError].freeze
+  private_constant :NETWORK_CAUSES
+
+  def self.certificate_error?(err)
+    cause = err.cause
+    while cause
+      return true if cause.is_a?(OpenSSL::SSL::SSLError) && cause.message.include?("certificate verify failed")
+
+      cause = cause.cause
+    end
+    false
+  end
+  private_class_method :certificate_error?
+end