cent 3.0.0 → 4.0.0

data/lib/cent/notary.rb

@@ -6,84 +6,93 @@ require 'cent/error'
 module Cent
   # Cent::Notary
   #
-  #   Handle token generation
+  # 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 algorithm of your choice.
-    # @param algorithm [String] Specify algorithm(one from HMAC, RSA or ECDSA family). Default is HS256.
-    #
-    # @example Construct new client instance
-    #   notary = Cent::Notary.new(secret: 'secret')
-    #
+    # @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
+      @secret    = secret
       @algorithm = algorithm
     end
 
-    # Generate connection JWT for the given user
-    #
-    # @param sub [String]
-    #   Standard JWT claim which must contain an ID of current application user.
-    #
-    # @option channel [String]
-    #   Channel that client tries to subscribe to (string).
-    #
-    # @param exp [Integer]
-    #   (default: nil) UNIX timestamp seconds when token will expire.
-    #
-    # @param info [Hash]
-    #   (default: {}) This claim is optional - this is additional information about
-    #   client connection that can be provided for Centrifugo.
-    #
-    # @example Get user JWT with expiration and extra info
-    #   notary.issue_connection_token(sub: '1', exp: 3600, info: { 'role' => 'admin' })
-    #     #=> "eyJhbGciOiJIUzI1NiJ9.eyJzdWIi..."
-    #
-    # @see (https://centrifugal.github.io/centrifugo/server/authentication/)
-    #
-    # @return [String]
-    #
-    def issue_connection_token(sub:, info: nil, exp: nil)
+    # 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,
-        'exp' => exp
+        'b64info' => b64info,
+        'channels' => channels,
+        'subs' => subs,
+        'meta' => meta,
+        'expire_at' => expire_at
       }.compact
 
       JWT.encode(payload, secret, algorithm)
     end
 
-    # Generate JWT for private channels
-    #
-    # @param client [String]
-    #   Client ID which wants to subscribe on channel
-    #
-    # @option channel [String]
-    #   Channel that client tries to subscribe to (string).
-    #
-    # @param exp [Integer]
-    #   (default: nil) UNIX timestamp seconds when token will expire.
-    #
-    # @param info [Hash]
-    #   (default: {}) This claim is optional - this is additional information about
-    #   client connection that can be provided for Centrifugo.
-    #
-    # @example Get private channel JWT with expiration and extra info
-    #   notary.issue_channel_token(client: 'client', channel: 'channel', exp: 3600, info: { 'message' => 'wat' })
-    #     #=> eyJhbGciOiJIUzI1NiJ9.eyJjbGllbnQiOiJjbG..."
-    #
-    # @see (https://centrifugal.github.io/centrifugo/server/private_channels/)
-    #
-    # @return [String]
-    #
-    def issue_channel_token(client:, channel:, info: nil, exp: nil)
+    # 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 = {
-        'client' => client,
+        'sub' => sub,
         'channel' => channel,
+        'exp' => exp,
+        'iat' => iat,
+        'jti' => jti,
+        'aud' => aud,
+        'iss' => iss,
         'info' => info,
-        'exp' => exp
+        'b64info' => b64info,
+        'override' => override,
+        'expire_at' => expire_at
       }.compact
 
       JWT.encode(payload, secret, algorithm)

data/lib/cent/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Cent
-  VERSION = '3.0.0'
+  VERSION = '4.0.0'
 end

data/lib/cent.rb

@@ -1,10 +1,10 @@
 # frozen_string_literal: true
 
 require 'cent/version'
+require 'cent/error'
 require 'cent/notary'
 require 'cent/client'
 
 # Centrifugo Ruby Client
 module Cent
-  # Here will be code...
 end

metadata

@@ -1,71 +1,65 @@
 --- !ruby/object:Gem::Specification
 name: cent
 version: !ruby/object:Gem::Version
-  version: 3.0.0
+  version: 4.0.0
 platform: ruby
 authors:
 - Sergey Prikhodko
-autorequire: 
+- Centrifugal Labs
 bindir: bin
 cert_chain: []
-date: 2024-03-25 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "<"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: 3.0.0
-    - - ">"
+        version: '2.0'
+    - - "<"
       - !ruby/object:Gem::Version
-        version: 2.0.0
+        version: '4'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "<"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: 3.0.0
-    - - ">"
+        version: '2.0'
+    - - "<"
       - !ruby/object:Gem::Version
-        version: 2.0.0
+        version: '4'
 - !ruby/object:Gem::Dependency
   name: jwt
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "<"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: 3.0.0
-    - - ">"
+        version: '2.2'
+    - - "<"
       - !ruby/object:Gem::Version
-        version: 2.2.0
+        version: '4'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "<"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: 3.0.0
-    - - ">"
+        version: '2.2'
+    - - "<"
       - !ruby/object:Gem::Version
-        version: 2.2.0
+        version: '4'
 description: |
-  Provides helper classes Cent::Client and Cent::Notary.
-
-  `Cent::Client` is made to communicate to the server API
-  `Client::Notary` is a simple JWT wrapper to generate authorization tokens for the frontend
+  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.
 email:
 - prikha@gmail.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- ".github/workflows/main.yml"
-- ".github/workflows/release.yml"
-- ".gitignore"
-- ".rspec"
-- ".rubocop.yml"
 - CHANGELOG.md
 - Gemfile
 - LICENSE.txt
@@ -77,16 +71,15 @@ files:
 - lib/cent.rb
 - lib/cent/client.rb
 - lib/cent/error.rb
-- lib/cent/http.rb
 - lib/cent/notary.rb
 - lib/cent/version.rb
 homepage: https://github.com/centrifugal/rubycent
 licenses:
 - MIT
 metadata:
-  homepage_uri: https://github.com/centrifugal/rubycent
   source_code_uri: https://github.com/centrifugal/rubycent
-post_install_message: 
+  changelog_uri: https://github.com/centrifugal/rubycent/releases
+  bug_tracker_uri: https://github.com/centrifugal/rubycent/issues
 rdoc_options: []
 require_paths:
 - lib
@@ -94,15 +87,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.5.0
+      version: '3.0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.3
-signing_key: 
+rubygems_version: 3.6.9
 specification_version: 4
-summary: Centrifugo API V2 Ruby Client
+summary: Centrifugo server API client for Ruby
 test_files: []

data/.github/workflows/main.yml

@@ -1,20 +0,0 @@
-name: Ruby
-
-on: [push,pull_request]
-
-jobs:
-  build:
-    runs-on: ubuntu-latest
-    strategy:
-      matrix:
-        ruby-version: ['2.7', '3.3']
-    steps:
-    - uses: actions/checkout@v4
-    - name: Set up Ruby
-      uses: ruby/setup-ruby@v1
-      with:
-        ruby-version: ${{ matrix.ruby-version }}
-    - name: Run the default task
-      run: |
-        bundle install
-        bundle exec rake

data/.github/workflows/release.yml

@@ -1,37 +0,0 @@
-name: Release Ruby Gem
-
-on:
-  push:
-    tags:
-      - 'v[0-9].[0-9]+.[0-9]+'
-jobs:
-  build-and-release:
-    name: Release
-    runs-on: ubuntu-latest
-    permissions:
-      packages: write
-      contents: read
-
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-
-      - name: Set up Ruby
-        uses: ruby/setup-ruby@v1
-        with:
-          ruby-version: 3.3.0
-
-      - name: Bundle install
-        run: |
-          bundle install
-
-      - name: Publish to RubyGems
-        run: |
-          mkdir -p $HOME/.gem
-          touch $HOME/.gem/credentials
-          chmod 0600 $HOME/.gem/credentials
-          printf -- "---\n:rubygems_api_key: ${GEM_HOST_API_KEY}\n" > $HOME/.gem/credentials
-          gem build *.gemspec
-          gem push *.gem
-        env:
-          GEM_HOST_API_KEY: "${{secrets.RUBYGEMS_API_KEY}}"

data/.gitignore

@@ -1,20 +0,0 @@
-/.bundle/
-/.yardoc
-/Gemfile.lock
-/_yardoc/
-/coverage/
-/doc/
-/pkg/
-/spec/reports/
-/tmp/
-*.bundle
-*.so
-*.o
-*.a
-mkmf.log
-.ruby-gemset
-.ruby-versions
-*.iml
-.idea/
-.rspec_status
-

data/.rspec

@@ -1,3 +0,0 @@
---format documentation
---color
---require spec_helper

data/.rubocop.yml

@@ -1,13 +0,0 @@
-require:
-  - rubocop-rspec
-  - rubocop-rake
-AllCops:
-  TargetRubyVersion: 2.5
-  NewCops: enable
-RSpec/ExampleLength:
-  Max: 15
-Metrics/BlockLength:
-  Exclude:
-    - 'spec/**/*'
-Gemspec/RequireMFA:
-  Enabled: false

data/lib/cent/http.rb

@@ -1,47 +0,0 @@
-# frozen_string_literal: true
-
-require 'cent/error'
-
-module Cent
-  # Cent::ResponseError
-  #
-  #   Raised when response from Centrifugo contains any error as result of API command execution.
-  #
-  class ResponseError < Error
-    attr_reader :code
-
-    def initialize(code:, message:)
-      @code = code
-      super(message)
-    end
-  end
-
-  # Cent::HTTP
-  #
-  #   Holds request call and response handling logic
-  #
-  class HTTP
-    attr_reader :connection
-
-    # @param connection [Faraday::Connection] HTTP Connection object
-    #
-    def initialize(connection:)
-      @connection = connection
-    end
-
-    # Perform POST request to centrifugo API
-    # @param body [Hash] Request body(non serialized)
-    #
-    # @raise [Cent::ResponseError]
-    #
-    # @return [Hash] Parsed response body
-    #
-    def post(body: nil)
-      response = connection.post(nil, body)
-
-      raise ResponseError.new(**response.body['error'].transform_keys(&:to_sym)) if response.body.key?('error')
-
-      response.body
-    end
-  end
-end