cent 3.0.0 → 4.0.0

data/lib/cent/client.rb

@@ -1,272 +1,260 @@
 # frozen_string_literal: true
 
 require 'faraday'
-require 'cent/http'
+require 'cent/error'
 
 module Cent
   # Cent::Client
   #
-  #   Main object that handles configuration and requests to centrifugo API
+  # Ruby client for Centrifugo server HTTP API (Centrifugo v4+).
   #
+  # Every API method returns the raw parsed response body from Centrifugo —
+  # typically `{ "result" => { ... } }` on success. If Centrifugo rejects the
+  # request with a top-level `error`, {Cent::ResponseError} is raised with
+  # Centrifugo's numeric `code` and `message`. Transport-level problems
+  # (network failure, timeout, non-2xx HTTP status, unparseable body) raise
+  # other {Cent::Error} subclasses.
+  #
+  # {#batch} and {#broadcast} are special: their responses contain an array
+  # of independent sub-replies, each of which may carry its own `error`
+  # field. Those sub-reply errors are NOT raised — callers inspect them
+  # manually. See {#batch} for details.
+  #
+  # @example Basic usage
+  #   client = Cent::Client.new(api_key: 'secret')
+  #   client.publish(channel: 'chat', data: { text: 'hi' })
+  #   # => {"result" => {}}
+  #
+  # @example Custom Faraday configuration
+  #   Cent::Client.new(api_key: 'k', endpoint: 'https://c.example.com/api') do |conn|
+  #     conn.options.open_timeout = 3
+  #     conn.options.timeout      = 7
+  #     conn.adapter :typhoeus
+  #   end
   class Client
-    # @param endpoint [String]
-    #   (default: 'http://localhost:8000/api') Centrifugo HTTP API URL
-    #
-    # @param api_key [String]
-    #   Centrifugo API key(used to perform requests)
-    #
-    # @yield [Faraday::Connection] yields connection object so that it can be configured
-    #
-    # @example Construct new client instance
-    #   Cent::Client.new(
-    #     endpoint: 'http://localhost:8000/api',
-    #     api_key: 'api key'
-    #   )
-    #
-    def initialize(api_key:, endpoint: 'http://localhost:8000/api')
+    DEFAULT_ENDPOINT = 'http://localhost:8000/api'
+    DEFAULT_TIMEOUT  = 10
+
+    attr_reader :connection
+
+    # @param api_key  [String]  Centrifugo HTTP API key (sent as `X-API-Key`).
+    # @param endpoint [String]  Centrifugo HTTP API base URL.
+    # @param timeout  [Numeric] Request timeout in seconds.
+    # @yield [Faraday::Connection] optional block to further configure the connection.
+    def initialize(api_key:, endpoint: DEFAULT_ENDPOINT, timeout: DEFAULT_TIMEOUT, &block)
       headers = {
         'Content-Type' => 'application/json',
-        'Authorization' => "apikey #{api_key}"
+        'X-API-Key' => api_key
       }
 
-      @connection = Faraday.new(endpoint, headers: headers) do |conn|
-        conn.request :json # encode req bodies as JSON
+      base = endpoint.end_with?('/') ? endpoint : "#{endpoint}/"
 
-        conn.response :json # decode response bodies as JSON
+      @connection = Faraday.new(base, headers: headers) do |conn|
+        conn.options.timeout      = timeout
+        conn.options.open_timeout = timeout
+        conn.request :json
+        conn.response :json
         conn.response :raise_error
-
-        yield conn if block_given?
+        block&.call(conn)
       end
     end
 
-    # Publish data into channel
-    #
-    # @param channel [String]
-    #   Name of the channel to publish
-    #
-    # @param data [Hash]
-    #   Data for publication in the channel
-    #
-    # @example Publish `content: 'hello'` into `chat` channel
-    #   client.publish(channel: 'chat', data: 'hello') #=> {}
-    #
-    # @see (https://centrifugal.github.io/centrifugo/server/http_api/#publish)
-    #
-    # @raise [Cent::Error, Cent::ResponseError]
-    #
-    # @return [Hash] Return empty hash in case of successful publish
-    #
-    def publish(channel:, data:)
-      execute('publish', channel: channel, data: data)
+    # Publish data into a channel.
+    # @see https://centrifugal.dev/docs/server/server_api#publish
+    def publish(channel:, data:, skip_history: nil, tags: nil, b64data: nil,
+                idempotency_key: nil, delta: nil, version: nil, version_epoch: nil)
+      send_command('publish', {
+                     'channel' => channel,
+                     'data' => data,
+                     'skip_history' => skip_history,
+                     'tags' => tags,
+                     'b64data' => b64data,
+                     'idempotency_key' => idempotency_key,
+                     'delta' => delta,
+                     'version' => version,
+                     'version_epoch' => version_epoch
+                   })
     end
 
-    # Publish data into multiple channels
-    #   (Similar to `#publish` but allows to send the same data into many channels)
-    #
-    # @param channels [Array<String>] Collection of channels names to publish
-    # @param data [Hash] Data for publication in the channels
-    #
-    # @example Broadcast `content: 'hello'` into `channel_1`, 'channel_2' channels
-    #   client.broadcast(channels: ['channel_1', 'channel_2'], data: 'hello') #=> {}
-    #
-    # @see (https://centrifugal.github.io/centrifugo/server/http_api/#broadcast)
-    #
-    # @raise [Cent::Error, Cent::ResponseError]
-    #
-    # @return [Hash] Return empty hash in case of successful broadcast
-    #
-    def broadcast(channels:, data:)
-      execute('broadcast', channels: channels, data: data)
+    # Publish the same data into many channels.
+    # @see https://centrifugal.dev/docs/server/server_api#broadcast
+    def broadcast(channels:, data:, skip_history: nil, tags: nil, b64data: nil,
+                  idempotency_key: nil, delta: nil, version: nil, version_epoch: nil)
+      send_command('broadcast', {
+                     'channels' => channels,
+                     'data' => data,
+                     'skip_history' => skip_history,
+                     'tags' => tags,
+                     'b64data' => b64data,
+                     'idempotency_key' => idempotency_key,
+                     'delta' => delta,
+                     'version' => version,
+                     'version_epoch' => version_epoch
+                   })
     end
 
-    # Unsubscribe user from channel
-    #
-    # @param channel [String]
-    #   Channel name to unsubscribe from
-    #
-    # @param user [String, Integer]
-    #   User ID you want to unsubscribe
-    #
-    # @example Unsubscribe user with `id = 1` from `chat` channel
-    #   client.unsubscribe(channel: 'chat', user: '1') #=> {}
-    #
-    # @see (https://centrifugal.github.io/centrifugo/server/http_api/#unsubscribe)
-    #
-    # @raise [Cent::Error, Cent::ResponseError]
-    #
-    # @return [Hash] Return empty hash in case of successful unsubscribe
-    #
-    def unsubscribe(channel:, user:)
-      execute('unsubscribe', channel: channel, user: user)
+    # Subscribe a user's active session to a channel (server-side subscription).
+    # @see https://centrifugal.dev/docs/server/server_api#subscribe
+    def subscribe(user:, channel:, info: nil, b64info: nil, client: nil, session: nil,
+                  data: nil, b64data: nil, recover_since: nil, override: nil)
+      send_command('subscribe', {
+                     'user' => user,
+                     'channel' => channel,
+                     'info' => info,
+                     'b64info' => b64info,
+                     'client' => client,
+                     'session' => session,
+                     'data' => data,
+                     'b64data' => b64data,
+                     'recover_since' => recover_since,
+                     'override' => override
+                   })
     end
 
-    # Disconnect user by it's ID
-    #
-    # @param user [String, Integer]
-    #   User ID you want to disconnect
-    #
-    # @example Disconnect user with `id = 1`
-    #   client.disconnect(user: '1') #=> {}
-    #
-    # @see (https://centrifugal.github.io/centrifugo/server/http_api/#disconnect)
-    #
-    # @raise [Cent::Error, Cent::ResponseError]
-    #
-    # @return [Hash] Return empty hash in case of successful disconnect
-    #
-    def disconnect(user:)
-      execute('disconnect', user: user)
+    # Unsubscribe a user from a channel.
+    # @see https://centrifugal.dev/docs/server/server_api#unsubscribe
+    def unsubscribe(user:, channel:, client: nil, session: nil)
+      send_command('unsubscribe', {
+                     'user' => user,
+                     'channel' => channel,
+                     'client' => client,
+                     'session' => session
+                   })
     end
 
-    # Get channel presence information
-    #   (all clients currently subscribed on this channel)
-    #
-    # @param channel [String] Name of the channel
-    #
-    # @example Get presence information for channel `chat`
-    #   client.presence(channel: 'chat') #=> {
-    #     "result" => {
-    #       "presence" => {
-    #         "c54313b2-0442-499a-a70c-051f8588020f" => {
-    #           "client" => "c54313b2-0442-499a-a70c-051f8588020f",
-    #           "user" => "42"
-    #         },
-    #         "adad13b1-0442-499a-a70c-051f858802da" => {
-    #           "client" => "adad13b1-0442-499a-a70c-051f858802da",
-    #           "user" => "42"
-    #         }
-    #       }
-    #     }
-    #   }
-    #
-    # @see (https://centrifugal.github.io/centrifugo/server/http_api/#presence)
-    #
-    # @raise [Cent::Error, Cent::ResponseError]
-    #
-    # @return [Hash]
-    #   Return hash with information about all clients currently subscribed on this channel
-    #
+    # Disconnect a user by ID.
+    # @see https://centrifugal.dev/docs/server/server_api#disconnect
+    def disconnect(user:, client: nil, session: nil, whitelist: nil, disconnect: nil)
+      send_command('disconnect', {
+                     'user' => user,
+                     'client' => client,
+                     'session' => session,
+                     'whitelist' => whitelist,
+                     'disconnect' => disconnect
+                   })
+    end
+
+    # Refresh a user connection (for unidirectional transports).
+    # @see https://centrifugal.dev/docs/server/server_api#refresh
+    def refresh(user:, client: nil, session: nil, expired: nil, expire_at: nil)
+      send_command('refresh', {
+                     'user' => user,
+                     'client' => client,
+                     'session' => session,
+                     'expired' => expired,
+                     'expire_at' => expire_at
+                   })
+    end
+
+    # Get channel presence (all currently subscribed clients).
+    # @see https://centrifugal.dev/docs/server/server_api#presence
     def presence(channel:)
-      execute('presence', channel: channel)
+      send_command('presence', { 'channel' => channel })
     end
 
-    # Get short channel presence information
-    #
-    # @param channel [String] Name of the channel
-    #
-    # @example Get short presence information for channel `chat`
-    #   client.presence_stats(channel: 'chat') #=> {
-    #     "result" => {
-    #       "num_clients" => 0,
-    #       "num_users" => 0
-    #     }
-    #   }
-    #
-    # @see (https://centrifugal.github.io/centrifugo/server/http_api/#presence_stats)
-    #
-    # @raise [Cent::Error, Cent::ResponseError]
-    #
-    # @return [Hash]
-    #   Return hash with short presence information about channel
-    #
+    # Get short presence stats for a channel.
+    # @see https://centrifugal.dev/docs/server/server_api#presence_stats
     def presence_stats(channel:)
-      execute('presence_stats', channel: channel)
+      send_command('presence_stats', { 'channel' => channel })
     end
 
-    # Get channel history information
-    #   (list of last messages published into channel)
-    #
-    # @param channel [String] Name of the channel
-    #
-    # @example Get history for channel `chat`
-    #   client.history(channel: 'chat') #=> {
-    #     "result" => {
-    #       "publications" => [
-    #         {
-    #           "data" => {
-    #             "text" => "hello"
-    #           },
-    #           "uid" => "BWcn14OTBrqUhTXyjNg0fg"
-    #         },
-    #         {
-    #           "data" => {
-    #             "text" => "hi!"
-    #           },
-    #           "uid" => "Ascn14OTBrq14OXyjNg0hg"
-    #         }
-    #       ]
-    #     }
-    #   }
-    #
-    # @see (https://centrifugal.github.io/centrifugo/server/http_api/#history)
-    #
-    # @raise [Cent::Error, Cent::ResponseError]
-    #
-    # @return [Hash]
-    #   Return hash with a list of last messages published into channel
-    #
-    def history(channel:)
-      execute('history', channel: channel)
+    # Get channel history (recent publications).
+    # @see https://centrifugal.dev/docs/server/server_api#history
+    def history(channel:, limit: nil, since: nil, reverse: nil)
+      send_command('history', {
+                     'channel' => channel,
+                     'limit' => limit,
+                     'since' => since,
+                     'reverse' => reverse
+                   })
     end
 
-    # Get list of active(with one or more subscribers) channels.
-    #
-    # @example Get active channels list
-    #   client.channels #=> {
-    #     "result" => {
-    #       "channels" => [
-    #         "chat"
-    #       ]
-    #     }
-    #   }
-    #
-    # @see (https://centrifugal.github.io/centrifugo/server/http_api/#channels)
-    #
-    # @raise [Cent::Error, Cent::ResponseError]
-    #
-    # @return [Hash]
-    #   Return hash with a list of active channels
-    #
-    def channels
-      execute('channels', {})
+    # Remove all publications from a channel's history.
+    # @see https://centrifugal.dev/docs/server/server_api#history_remove
+    def history_remove(channel:)
+      send_command('history_remove', { 'channel' => channel })
     end
 
-    # Get information about running Centrifugo nodes
-    #
-    # @example Get running centrifugo nodes list
-    #   client.info #=> {
-    #     "result" => {
-    #       "nodes" => [
-    #         {
-    #           "name" => "Alexanders-MacBook-Pro.local_8000",
-    #           "num_channels" => 0,
-    #           "num_clients" => 0,
-    #           "num_users" => 0,
-    #           "uid" => "f844a2ed-5edf-4815-b83c-271974003db9",
-    #           "uptime" => 0,
-    #           "version" => ""
-    #         }
-    #       ]
-    #     }
-    #   }
-    #
-    # @see (https://centrifugal.github.io/centrifugo/server/http_api/#info)
-    #
-    # @raise [Cent::Error, Cent::ResponseError]
-    #
-    # @return [Hash]
-    #   Return hash with a list of last messages published into channel
-    #
+    # List active channels (channels with at least one subscriber).
+    # @see https://centrifugal.dev/docs/server/server_api#channels
+    def channels(pattern: nil)
+      send_command('channels', { 'pattern' => pattern })
+    end
+
+    # Get information about running Centrifugo nodes.
+    # @see https://centrifugal.dev/docs/server/server_api#info
     def info
-      execute('info', {})
+      send_command('info', {})
+    end
+
+    # Send many commands in a single request.
+    #
+    # The response is shaped `{ "replies" => [<reply>, ...] }` — note there
+    # is no top-level `result` wrapper, unlike every other method. Each reply
+    # in the array corresponds to one command (in the order they were sent
+    # when `parallel` is not set) and has the shape `{ "<method>" => <result> }`
+    # on success or `{ "error" => { "code" => ..., "message" => ... } }` on a
+    # per-command failure.
+    #
+    # These per-command errors are **not** raised as {Cent::ResponseError} —
+    # that would make partial-failure responses impossible to inspect. The
+    # caller is expected to walk `response["replies"]` and check each entry.
+    # If Centrifugo rejects the batch request as a whole (e.g. malformed
+    # top-level body), the top-level `error` field is present and
+    # {Cent::ResponseError} is raised normally.
+    #
+    # @example
+    #   response = client.batch(commands: [
+    #     { 'publish' => { 'channel' => 'a', 'data' => {} } },
+    #     { 'publish' => { 'channel' => 'unknown:b', 'data' => {} } }
+    #   ])
+    #   response['replies'].each do |reply|
+    #     if reply['error']
+    #       warn "command failed: #{reply['error']['code']} #{reply['error']['message']}"
+    #     end
+    #   end
+    #
+    # @param commands [Array<Hash>] Each element is a command object of the
+    #   form `{ "publish" => { ... } }`, `{ "broadcast" => { ... } }`, etc.
+    # @param parallel [Boolean, nil] When true, Centrifugo processes commands
+    #   in parallel (lower latency, order not guaranteed).
+    # @see https://centrifugal.dev/docs/server/server_api#batch
+    def batch(commands:, parallel: nil)
+      send_command('batch', {
+                     'commands' => commands,
+                     'parallel' => parallel
+                   })
     end
 
     private
 
-    def execute(method, data)
-      body = { method: method, params: data }
+    def send_command(method, params)
+      body = connection.post(method, params.compact).body
+      check_response_error!(body)
+      body
+    rescue Faraday::TimeoutError => e
+      raise Cent::TimeoutError, e.message
+    rescue Faraday::ConnectionFailed => e
+      raise Cent::NetworkError, e.message
+    rescue Faraday::UnauthorizedError => e
+      raise Cent::UnauthorizedError.new(status: 401, message: e.message)
+    rescue Faraday::ClientError, Faraday::ServerError => e
+      status = e.response_status || e.response&.dig(:status)
+      raise Cent::TransportError.new(status: status, message: e.message)
+    rescue Faraday::ParsingError => e
+      raise Cent::DecodeError, e.message
+    end
+
+    # Top-level `error` means Centrifugo rejected the whole request. Batch
+    # and broadcast sub-reply errors live inside arrays and are NOT raised —
+    # callers inspect them manually (see #batch docs).
+    def check_response_error!(body)
+      return unless body.is_a?(Hash) && body['error'].is_a?(Hash)
 
-      Cent::HTTP.new(connection: @connection).post(body: body)
+      raise Cent::ResponseError.new(
+        code: body['error']['code'],
+        message: body['error']['message']
+      )
     end
   end
 end

data/lib/cent/error.rb

@@ -1,9 +1,46 @@
 # frozen_string_literal: true
 
 module Cent
-  # Cent::Error
-  #
-  #   Wrapper for all errors(failures).
-  #
+  # Base class for all errors raised by this library.
   class Error < StandardError; end
+
+  # Raised when Centrifugo is unreachable (DNS failure, connection refused, ...).
+  class NetworkError < Error; end
+
+  # Raised when the HTTP request times out.
+  class TimeoutError < Error; end
+
+  # Raised when Centrifugo returns a non-2xx HTTP status.
+  class TransportError < Error
+    attr_reader :status
+
+    def initialize(status:, message: nil)
+      @status = status
+      super(message || "HTTP #{status}")
+    end
+  end
+
+  # Raised when Centrifugo returns HTTP 401 (invalid API key).
+  class UnauthorizedError < TransportError; end
+
+  # Raised when response from Centrifugo cannot be decoded (not valid JSON).
+  class DecodeError < Error; end
+
+  # Raised when Centrifugo returns a top-level `error` in the response body
+  # (API-level failure, e.g., unknown channel, namespace not found). Exposes
+  # Centrifugo's numeric `code` and human-readable `message`. See
+  # https://centrifugal.dev/docs/server/server_api#error for the full list
+  # of codes.
+  #
+  # Note: for `batch` and `broadcast`, individual sub-reply errors are NOT
+  # raised — those responses contain an array of independent replies, and
+  # each entry should be inspected by the caller for its own `error` key.
+  class ResponseError < Error
+    attr_reader :code
+
+    def initialize(code:, message:)
+      @code = code
+      super(message)
+    end
+  end
 end