cent 4.0.0 → 5.0.0

data/lib/cent/wire.rb

@@ -0,0 +1,222 @@
+# frozen_string_literal: true
+
+module Cent
+  # Encoding requests and decoding replies, for the generated code: each field
+  # is put or got by its kind - :str, :bool, :int, :float, :json (a payload),
+  # :bool_value and :int32_value (protobuf wrappers), or a message's class - and
+  # its shape - :one, :list, :map, or :presence for a message which is a
+  # presence wrapper, sent whenever it is set, even empty.
+  #
+  # @api private
+  module Wire
+    ZERO = { str: "", bool: false, int: 0, float: 0.0 }.freeze
+
+    module_function
+
+    # Sets +w[key]+ to the encoded field +v+, unless it is unset or at its zero
+    # value: nil, "", false, 0, an empty list or map, a message with nothing set
+    # - but a presence wrapper, sent as {} when set empty. +where+ prefixes the
+    # field's name in error messages.
+    def put(w, key, v, where, kind, shape = :one)
+      return if v.nil?
+
+      out =
+        case shape
+        when :list
+          raise InvalidRequestError, "#{where}#{key} must be an Array, not #{kind_of(v)}" unless v.is_a?(Array)
+          return if v.empty?
+
+          v.each_with_index.map { |item, i| value(kind, item, "#{where}#{key}[#{i}]", true) }
+        when :map
+          raise InvalidRequestError, "#{where}#{key} must be a Hash, not #{kind_of(v)}" unless v.is_a?(Hash)
+          return if v.empty?
+
+          v.each_with_object({}) do |(k, item), h|
+            name = map_key(k, "#{where}#{key}")
+            h[name] = value(kind, item, "#{where}#{key}[#{name.inspect}]", true)
+          end
+        else value(kind, v, "#{where}#{key}", shape == :presence)
+        end
+      w[key] = out unless out.nil?
+    end
+
+    # One value of a field, encoded; nil for a zero value, unless +keep+ (an
+    # item of a list or map, a presence wrapper).
+    def value(kind, v, path, keep)
+      case kind
+      when :str, :bool, :int, :float then scalar(kind, v, path, keep)
+      when :json then Payload.check!(v, path)
+      when :bool_value
+        raise InvalidRequestError, "#{path} must be true or false, not #{kind_of(v)}" unless [true, false].include?(v)
+
+        { "value" => v }
+      when :int32_value
+        raise InvalidRequestError, "#{path} must be an Integer, not #{kind_of(v)}" unless v.is_a?(Integer)
+
+        { "value" => v }
+      else
+        w = message(kind, v, path).to_wire("#{path}.")
+        w.empty? && !keep ? nil : w
+      end
+    end
+
+    def scalar(kind, v, path, keep)
+      case kind
+      when :str
+        s = case v
+            when String then v
+            when Symbol then v.name
+            else raise InvalidRequestError, "#{path} must be a String, not #{kind_of(v)}"
+            end
+        Payload.string!(s, path)
+        s.empty? && !keep ? nil : s
+      when :bool
+        raise InvalidRequestError, "#{path} must be true or false, not #{kind_of(v)}" unless [true, false].include?(v)
+
+        v || keep ? v : nil
+      when :int
+        raise InvalidRequestError, "#{path} must be an Integer, not #{kind_of(v)}" unless v.is_a?(Integer)
+
+        v.zero? && !keep ? nil : v
+      when :float
+        unless (v.is_a?(Float) && v.finite?) || v.is_a?(Integer)
+          raise InvalidRequestError, "#{path} must be a finite number, not #{kind_of(v)}"
+        end
+
+        v.zero? && !keep ? nil : v
+      end
+    end
+
+    # A message given as its class's instance, or as a Hash of its fields.
+    def message(klass, v, path)
+      return v if v.is_a?(klass)
+      unless v.is_a?(Hash)
+        raise InvalidRequestError, "#{path} must be a #{short(klass)} or a Hash of its fields, not #{kind_of(v)}"
+      end
+
+      v.each_key do |k|
+        next if k.is_a?(Symbol) && klass.members.include?(k)
+
+        name = k.to_s
+        if k.is_a?(String) && klass.members.include?(name.to_sym)
+          raise InvalidRequestError, "#{path}: field names are Symbols - #{name}:, not #{name.inspect}"
+        end
+
+        like = DidYouMean::SpellChecker.new(dictionary: klass.members.map(&:name)).correct(name).first
+        raise InvalidRequestError,
+              "#{path}.#{name} is not a field of #{short(klass)}#{": did you mean #{like}?" if like}"
+      end
+      missing = required_members(klass).find { !v.key?(it) }
+      raise InvalidRequestError, "#{path}.#{missing} is required" if missing
+
+      klass.new(**v)
+    end
+
+    # The fields a message type's initialize requires: every one when it is
+    # Data's own, which the generator leaves when no field has a default.
+    def required_members(klass)
+      params = klass.instance_method(:initialize).parameters
+      return klass.members if params == [[:rest]]
+
+      params.filter_map { |t, name| name if t == :keyreq }
+    end
+
+    # Raises InvalidRequestError naming the first field the proto marks
+    # required which the JSON +w+ of the request or message +key+ - its method
+    # or name in REQUIRED - leaves out: unset, or at its zero value. A nested
+    # message is checked when it is set, a list's each.
+    def check_required(w, key, path = "")
+      REQUIRED.fetch(key).each do |name, required, nested, list|
+        v = w[name]
+        if v.nil?
+          raise InvalidRequestError, "#{path}#{name} is required" if required
+
+          next
+        end
+        next unless nested
+
+        if list
+          v.each_with_index { |item, i| check_required(item, nested, "#{path}#{name}[#{i}].") }
+        else
+          check_required(v, nested, "#{path}#{name}.")
+        end
+      end
+    end
+
+    def map_key(k, path)
+      case k
+      when String
+        Payload.string!(k, "#{path} key #{k.inspect}")
+        k
+      when Symbol then k.name
+      else raise InvalidRequestError, "#{path} has a #{k.class} key, #{k.inspect}: keys are strings"
+      end
+    end
+
+    # The field +key+ of the decoded object +d+, at its zero value when the reply
+    # left it out; fields the client does not know are ignored.
+    def get(d, key, where, kind, shape = :one)
+      v = d[key]
+      case shape
+      when :list
+        return [] if v.nil?
+        raise DecodeError, "#{where}.#{key}: expected an array, got #{kind_of(v)}" unless v.is_a?(Array)
+
+        v.each_with_index.map { |item, i| decode(kind, item, "#{where}.#{key}[#{i}]") }
+      when :map
+        return {} if v.nil?
+
+        obj(v, "#{where}.#{key}").to_h { |k, item| [k, decode(kind, item, "#{where}.#{key}[#{k.inspect}]")] }
+      else
+        return ZERO.fetch(kind, nil) if v.nil? && kind != :json
+
+        decode(kind, v, "#{where}.#{key}")
+      end
+    end
+
+    def decode(kind, v, path)
+      case kind
+      when :str
+        raise DecodeError, "#{path}: expected a string, got #{kind_of(v)}" unless v.is_a?(String)
+      when :bool
+        raise DecodeError, "#{path}: expected a boolean, got #{kind_of(v)}" unless [true, false].include?(v)
+      when :int
+        raise DecodeError, "#{path}: expected an integer, got #{kind_of(v)}" unless v.is_a?(Integer)
+      when :float
+        raise DecodeError, "#{path}: expected a number, got #{kind_of(v)}" unless v.is_a?(Numeric)
+
+        return v.to_f
+      when :json then nil
+      when :bool_value, :int32_value
+        inner = obj(v, path)["value"]
+        # The value's zero, which a protobuf encoder leaves out.
+        return kind == :bool_value ? false : 0 if inner.nil?
+
+        return decode(kind == :bool_value ? :bool : :int, inner, "#{path}.value")
+      else return kind.from_wire(v, path)
+      end
+      v
+    end
+
+    def obj(v, where)
+      raise DecodeError, "#{where}: expected an object, got #{kind_of(v)}" unless v.is_a?(Hash)
+
+      v
+    end
+
+    def kind_of(v)
+      case v
+      when nil then "nil"
+      when true, false then v.to_s
+      when String then "a String"
+      when Integer then "an Integer, #{v}"
+      when Float then "a Float, #{v}"
+      when Array then "an Array"
+      when Hash then "a Hash"
+      else "a #{v.class}"
+      end
+    end
+
+    def short(klass) = klass.name.delete_prefix("Cent::")
+  end
+end

data/lib/cent.rb

@@ -1,10 +1,38 @@
 # frozen_string_literal: true
 
-require 'cent/version'
-require 'cent/error'
-require 'cent/notary'
-require 'cent/client'
+require "json"
+require "net/http"
+require "openssl"
+require "zlib"
 
-# Centrifugo Ruby Client
+# Ruby SDK for Centrifugo's HTTP server API:
+#
+#   client = Cent::Client.new(api_endpoint: "http://localhost:8000/api", api_key: ENV.fetch("CENTRIFUGO_API_KEY"))
+#   client.publish(channel: "news", data: { text: "hello" })
+#
+# See https://github.com/centrifugal/rubycent for the documentation.
 module Cent
 end
+
+require_relative "cent/version"
+require_relative "cent/message"
+require_relative "cent/errors"
+require_relative "cent/payload"
+require_relative "cent/wire"
+require_relative "cent/http"
+require_relative "cent/generated/types"
+require_relative "cent/generated/methods"
+require_relative "cent/reply"
+require_relative "cent/pages"
+require_relative "cent/broadcast"
+require_relative "cent/retry"
+require_relative "cent/batch"
+require_relative "cent/command"
+require_relative "cent/auto_batch"
+require_relative "cent/client"
+require_relative "cent/handler"
+require_relative "cent/token"
+require_relative "cent/shared_poll"
+require_relative "cent/endpoints"
+require_relative "cent/generated/proxy_types"
+require_relative "cent/proxy"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cent
 version: !ruby/object:Gem::Version
-  version: 4.0.0
+  version: 5.0.0
 platform: ruby
 authors:
 - Sergey Prikhodko
@@ -11,49 +11,24 @@ cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
-  name: faraday
+  name: json
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '2.0'
-    - - "<"
-      - !ruby/object:Gem::Version
-        version: '4'
+        version: '2.10'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '2.0'
-    - - "<"
-      - !ruby/object:Gem::Version
-        version: '4'
-- !ruby/object:Gem::Dependency
-  name: jwt
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '2.2'
-    - - "<"
-      - !ruby/object:Gem::Version
-        version: '4'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '2.2'
-    - - "<"
-      - !ruby/object:Gem::Version
-        version: '4'
+        version: '2.10'
 description: |
-  Ruby client for Centrifugo server HTTP API. Provides Cent::Client to call
-  Centrifugo server methods (publish, broadcast, subscribe, presence, history, ...)
-  and Cent::Notary to issue JWT connection and subscription tokens.
+  Every method of Centrifugo's HTTP server API, with typed results, batches,
+  automatic batching and retries; connection, subscription and API tokens,
+  JWKS; endpoints for client SDKs and Rack handlers for Centrifugo's proxy.
+  No dependencies but json.
 email:
 - prikha@gmail.com
 executables: []
@@ -61,25 +36,40 @@ extensions: []
 extra_rdoc_files: []
 files:
 - CHANGELOG.md
-- Gemfile
 - LICENSE.txt
+- MIGRATING.md
 - README.md
-- Rakefile
-- bin/console
-- bin/setup
-- cent.gemspec
 - lib/cent.rb
+- lib/cent/auto_batch.rb
+- lib/cent/batch.rb
+- lib/cent/broadcast.rb
 - lib/cent/client.rb
-- lib/cent/error.rb
-- lib/cent/notary.rb
+- lib/cent/command.rb
+- lib/cent/endpoints.rb
+- lib/cent/errors.rb
+- lib/cent/generated/methods.rb
+- lib/cent/generated/proxy_types.rb
+- lib/cent/generated/types.rb
+- lib/cent/handler.rb
+- lib/cent/http.rb
+- lib/cent/message.rb
+- lib/cent/pages.rb
+- lib/cent/payload.rb
+- lib/cent/proxy.rb
+- lib/cent/reply.rb
+- lib/cent/retry.rb
+- lib/cent/shared_poll.rb
+- lib/cent/token.rb
 - lib/cent/version.rb
+- lib/cent/wire.rb
 homepage: https://github.com/centrifugal/rubycent
 licenses:
 - MIT
 metadata:
   source_code_uri: https://github.com/centrifugal/rubycent
-  changelog_uri: https://github.com/centrifugal/rubycent/releases
+  changelog_uri: https://github.com/centrifugal/rubycent/blob/master/CHANGELOG.md
   bug_tracker_uri: https://github.com/centrifugal/rubycent/issues
+  documentation_uri: https://rubydoc.info/gems/cent
 rdoc_options: []
 require_paths:
 - lib
@@ -87,14 +77,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.0'
+      version: '3.4'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 4.0.20
 specification_version: 4
-summary: Centrifugo server API client for Ruby
+summary: Ruby SDK for Centrifugo's HTTP server API
 test_files: []

data/Gemfile

@@ -1,15 +0,0 @@
-# frozen_string_literal: true
-
-source 'https://rubygems.org'
-
-# Specify your gem's dependencies in cent.gemspec
-gemspec
-
-gem 'appraisal', '~> 2.5'
-gem 'pry'
-gem 'rake', '~> 13.0'
-gem 'rspec', '~> 3.12'
-gem 'rubocop', '~> 1.60'
-gem 'rubocop-rake', '~> 0.6'
-gem 'rubocop-rspec', '~> 3.0'
-gem 'webmock', '~> 3.19'

data/Rakefile

@@ -1,12 +0,0 @@
-# frozen_string_literal: true
-
-require 'bundler/gem_tasks'
-require 'rspec/core/rake_task'
-
-RSpec::Core::RakeTask.new(:spec)
-
-require 'rubocop/rake_task'
-
-RuboCop::RakeTask.new
-
-task default: %i[spec rubocop]

data/bin/console

@@ -1,15 +0,0 @@
-#!/usr/bin/env ruby
-# frozen_string_literal: true
-
-require 'bundler/setup'
-require 'cent'
-
-# You can add fixtures and/or initialization code here to make experimenting
-# with your gem easier. You can also use a different console, if you like.
-
-# (If you use this, don't forget to add pry to your Gemfile!)
-# require "pry"
-# Pry.start
-
-require 'pry'
-Pry.start(__FILE__)

data/bin/setup

@@ -1,8 +0,0 @@
-#!/usr/bin/env bash
-set -euo pipefail
-IFS=$'\n\t'
-set -vx
-
-bundle install
-
-# Do any other automated setup that you need to do here

data/cent.gemspec

@@ -1,36 +0,0 @@
-# frozen_string_literal: true
-
-require_relative 'lib/cent/version'
-
-Gem::Specification.new do |spec|
-  spec.name          = 'cent'
-  spec.version       = Cent::VERSION
-  spec.authors       = ['Sergey Prikhodko', 'Centrifugal Labs']
-  spec.email         = ['prikha@gmail.com']
-
-  spec.summary       = 'Centrifugo server API client for Ruby'
-  spec.description   = <<~DESC
-    Ruby client for Centrifugo server HTTP API. Provides Cent::Client to call
-    Centrifugo server methods (publish, broadcast, subscribe, presence, history, ...)
-    and Cent::Notary to issue JWT connection and subscription tokens.
-  DESC
-  spec.homepage      = 'https://github.com/centrifugal/rubycent'
-  spec.license       = 'MIT'
-  spec.required_ruby_version = Gem::Requirement.new('>= 3.0')
-
-  spec.metadata['source_code_uri'] = 'https://github.com/centrifugal/rubycent'
-  spec.metadata['changelog_uri']   = 'https://github.com/centrifugal/rubycent/releases'
-  spec.metadata['bug_tracker_uri'] = 'https://github.com/centrifugal/rubycent/issues'
-
-  spec.files = Dir.chdir(File.expand_path(__dir__)) do
-    `git ls-files -z`.split("\x0").reject do |f|
-      f.match(%r{\A(?:spec|benchmarks|gemfiles|\.github)/}) ||
-        f.match(/\A(?:docker-compose\.yml|Appraisals|\.rubocop\.yml|\.rspec|\.gitignore)\z/)
-    end
-  end
-
-  spec.require_paths = ['lib']
-
-  spec.add_dependency 'faraday', '>= 2.0', '< 4'
-  spec.add_dependency 'jwt',     '>= 2.2', '< 4'
-end

data/lib/cent/error.rb

@@ -1,46 +0,0 @@
-# frozen_string_literal: true
-
-module Cent
-  # 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

data/lib/cent/notary.rb

@@ -1,105 +0,0 @@
-# frozen_string_literal: true
-
-require 'jwt'
-require 'cent/error'
-
-module Cent
-  # Cent::Notary
-  #
-  # Issues JWT tokens for Centrifugo client connections and channel subscriptions.
-  # Supports HMAC, RSA and ECDSA families of algorithms (HS256/384/512,
-  # RS256/384/512, ES256/384/512).
-  #
-  # @see https://centrifugal.dev/docs/server/authentication
-  # @see https://centrifugal.dev/docs/server/channel_token_auth
-  class Notary
-    # @param secret    [String, OpenSSL::PKey::RSA, OpenSSL::PKey::EC] Secret key
-    #   for the chosen algorithm. For HMAC pass the raw secret as a String. For
-    #   RSA/ECDSA pass a PEM-loaded {OpenSSL::PKey::RSA} / {OpenSSL::PKey::EC}.
-    # @param algorithm [String] JWT algorithm, defaults to `HS256`.
-    def initialize(secret:, algorithm: 'HS256')
-      raise Error, 'Secret can not be nil' if secret.nil?
-
-      @secret    = secret
-      @algorithm = algorithm
-    end
-
-    # Issue a connection JWT used by clients when establishing a real-time
-    # connection to Centrifugo.
-    #
-    # @param sub       [String] Standard JWT claim with the application user ID.
-    #   Use an empty string for anonymous connections.
-    # @param exp       [Integer] UNIX timestamp (seconds) when the token expires.
-    # @param iat       [Integer] UNIX timestamp (seconds) when the token was issued.
-    # @param jti       [String]  Unique token identifier.
-    # @param aud       [String]  Token audience (matches `client.token.audience`).
-    # @param iss       [String]  Token issuer  (matches `client.token.issuer`).
-    # @param info      [Hash]    Arbitrary public info attached to the connection.
-    # @param b64info   [String]  Base64-encoded `info` (for binary payloads).
-    # @param channels  [Array<String>] Server-side subscription channel list.
-    # @param subs      [Hash]    Server-side subscriptions with per-channel options.
-    # @param meta      [Hash]    Server-only metadata attached to the connection.
-    # @param expire_at [Integer] Override connection expiration timestamp.
-    #
-    # @return [String] Encoded JWT.
-    def issue_connection_token(sub:, exp: nil, iat: nil, jti: nil, aud: nil, iss: nil,
-                               info: nil, b64info: nil, channels: nil, subs: nil,
-                               meta: nil, expire_at: nil)
-      payload = {
-        'sub' => sub,
-        'exp' => exp,
-        'iat' => iat,
-        'jti' => jti,
-        'aud' => aud,
-        'iss' => iss,
-        'info' => info,
-        'b64info' => b64info,
-        'channels' => channels,
-        'subs' => subs,
-        'meta' => meta,
-        'expire_at' => expire_at
-      }.compact
-
-      JWT.encode(payload, secret, algorithm)
-    end
-
-    # Issue a subscription JWT used by clients to authorize subscription to a
-    # channel that requires token authorization.
-    #
-    # @param sub       [String]  Application user ID (same meaning as in connection token).
-    # @param channel   [String]  Channel this subscription token is valid for.
-    # @param exp       [Integer] UNIX timestamp (seconds) when the token expires.
-    # @param iat       [Integer] UNIX timestamp (seconds) when the token was issued.
-    # @param jti       [String]  Unique token identifier.
-    # @param aud       [String]  Token audience.
-    # @param iss       [String]  Token issuer.
-    # @param info      [Hash]    Arbitrary channel info.
-    # @param b64info   [String]  Base64-encoded `info`.
-    # @param override  [Hash]    Per-subscription channel option overrides.
-    # @param expire_at [Integer] Override subscription expiration timestamp.
-    #
-    # @return [String] Encoded JWT.
-    def issue_channel_token(sub:, channel:, exp: nil, iat: nil, jti: nil, aud: nil, iss: nil,
-                            info: nil, b64info: nil, override: nil, expire_at: nil)
-      payload = {
-        'sub' => sub,
-        'channel' => channel,
-        'exp' => exp,
-        'iat' => iat,
-        'jti' => jti,
-        'aud' => aud,
-        'iss' => iss,
-        'info' => info,
-        'b64info' => b64info,
-        'override' => override,
-        'expire_at' => expire_at
-      }.compact
-
-      JWT.encode(payload, secret, algorithm)
-    end
-
-    private
-
-    attr_reader :secret, :algorithm
-  end
-end