legba-ruby 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 7e16984aefaf11067ac2cda77557466008f4ca10b3c2e254b07e162eda13df26
+  data.tar.gz: 6eda037a9461abc89012d851287d177b5cc427ed5c8ac5b5cc4b527944890f8f
+SHA512:
+  metadata.gz: d85ebdff690bc72a80cf5bf45acc5a358b99a0df6c3099b14b883c42811467aa37e285272972548ba4684630ddecc95c81910e031c2a6f051a188a29940b5cc5
+  data.tar.gz: 231e3e5342fd0d79a9fa1b6e48c8a6c99dcbda22e39216488fbd90b2cccb4b3bc997643354bc6055f4e06c955d7e2b552908c4714e857dfa702233b11959f265

data/lib/legba/client.rb

@@ -0,0 +1,289 @@
+# frozen_string_literal: true
+
+require 'net/http'
+require 'uri'
+require 'json'
+require 'openssl'
+require 'base64'
+require_relative 'encryption'
+
+module Legba
+  class Client
+    def initialize(app_id:, key:, secret:, cluster: nil, host: nil, use_tls: true, timeout: 30,
+                   encryption_master_key_base64: nil)
+      raise ArgumentError, 'app_id is required' if app_id.nil? || app_id.empty?
+      raise ArgumentError, 'key is required'    if key.nil?    || key.empty?
+      raise ArgumentError, 'secret is required' if secret.nil? || secret.empty?
+      raise ArgumentError, 'cluster or host is required' if cluster.nil? && host.nil?
+
+      @app_id  = app_id
+      @key     = key
+      @secret  = secret
+      @timeout = timeout
+
+      if encryption_master_key_base64
+        begin
+          key_bytes = Base64.strict_decode64(encryption_master_key_base64)
+        rescue ArgumentError
+          raise ArgumentError, 'encryption_master_key_base64 must be valid base64'
+        end
+        raise ArgumentError, 'encryption_master_key_base64 must encode exactly 32 bytes' unless key_bytes.bytesize == 32
+
+        @encryption_master_key = key_bytes
+      end
+
+      scheme = use_tls == false ? 'http' : 'https'
+      if host
+        bare      = host.sub(%r{^https?://}, '')
+        @base_url = "#{scheme}://#{bare}"
+      else
+        @base_url = "#{scheme}://api-#{cluster}.legba.dev"
+      end
+    end
+
+    def trigger(channels, event, data, socket_id: nil)
+      channel_array = Array(channels)
+
+      raise ArgumentError, 'channels must not be empty' if channel_array.empty?
+
+      channel_array.each do |ch|
+        raise ArgumentError, 'each channel must be a non-empty string' unless ch.is_a?(String) && !ch.empty?
+      end
+      raise ArgumentError, 'event must be a non-empty string' unless event.is_a?(String) && !event.empty?
+
+      has_encrypted = channel_array.any? { |ch| Legba::Encryption.encrypted_channel?(ch) }
+      if has_encrypted && channel_array.length > 1
+        raise ArgumentError,
+              'encrypted channels do not support multi-channel triggers'
+      end
+
+      data_string = JSON.generate(data)
+      raise ArgumentError, 'data must not exceed 10KB' if data_string.bytesize > 10_240
+
+      if has_encrypted
+        unless @encryption_master_key
+          raise ArgumentError,
+                'encryption_master_key_base64 is required for encrypted channels'
+        end
+
+        shared_secret = Legba::Encryption.derive_shared_secret(@encryption_master_key, channel_array[0])
+        data_string = Legba::Encryption.encrypt_data(data_string, shared_secret)
+      end
+
+      body = { 'name' => event, 'data' => data_string }
+      if channel_array.length == 1
+        body['channel'] = channel_array[0]
+      else
+        body['channels'] = channel_array
+      end
+      body['socket_id'] = socket_id if socket_id
+
+      post('/events', JSON.generate(body))
+    end
+
+    def trigger_batch(events)
+      raise ArgumentError, 'batch must be a non-empty array' if events.nil? || events.empty?
+      raise ArgumentError, 'batch must not exceed 10 events' if events.length > 10
+
+      batch = events.map do |e|
+        channel = e[:channel] || e['channel']
+        event_name = e[:event]    || e['event']
+        data      = e[:data]      || e['data']
+        socket_id = e[:socket_id] || e['socket_id']
+
+        unless channel.is_a?(String) && !channel.empty?
+          raise ArgumentError,
+                'each batch event channel must be a non-empty string'
+        end
+        unless event_name.is_a?(String) && !event_name.empty?
+          raise ArgumentError,
+                'each batch event name must be a non-empty string'
+        end
+
+        data_string = JSON.generate(data)
+        raise ArgumentError, 'batch event data must not exceed 10KB' if data_string.bytesize > 10_240
+
+        if Legba::Encryption.encrypted_channel?(channel)
+          unless @encryption_master_key
+            raise ArgumentError,
+                  'encryption_master_key_base64 is required for encrypted channels'
+          end
+
+          shared_secret = Legba::Encryption.derive_shared_secret(@encryption_master_key, channel)
+          data_string = Legba::Encryption.encrypt_data(data_string, shared_secret)
+        end
+
+        item = { 'name' => event_name, 'channel' => channel, 'data' => data_string }
+        item['socket_id'] = socket_id if socket_id
+        item
+      end
+
+      post('/batch_events', JSON.generate({ 'batch' => batch }))
+    end
+
+    def channels(filter_by_prefix: nil)
+      extra = filter_by_prefix ? { 'filter_by_prefix' => filter_by_prefix } : {}
+      raw   = get('/channels', extra)
+
+      mapped = raw['channels'].each_with_object({}) do |(name, info), acc|
+        ch = { subscription_count: info['subscription_count'] }
+        ch[:user_count] = info['user_count'] if info.key?('user_count')
+        acc[name] = ch
+      end
+
+      { channels: mapped }
+    end
+
+    def channel(channel_name)
+      raise ArgumentError, 'channel_name must be a non-empty string' if channel_name.nil? || channel_name.empty?
+
+      raw    = get("/channels/#{channel_name}")
+      result = { occupied: raw['occupied'], subscription_count: raw['subscription_count'] }
+      result[:user_count] = raw['user_count'] if raw.key?('user_count')
+      result
+    end
+
+    def channel_users(channel_name)
+      raise ArgumentError, 'channel_name must be a non-empty string' if channel_name.nil? || channel_name.empty?
+
+      unless channel_name.start_with?('presence-')
+        raise ArgumentError,
+              "channel_users is only available for presence channels (must start with 'presence-')"
+      end
+
+      raw = get("/channels/#{channel_name}/users")
+      { users: raw['users'].map { |u| { id: u['id'] } } }
+    end
+
+    def authenticate_channel(socket_id, channel_name, channel_data: nil)
+      raise ArgumentError, 'socket_id is required'    if socket_id.nil?    || socket_id.empty?
+      raise ArgumentError, 'channel_name is required' if channel_name.nil? || channel_name.empty?
+
+      if Legba::Encryption.encrypted_channel?(channel_name)
+        unless @encryption_master_key
+          raise ArgumentError,
+                'encryption_master_key_base64 is required for encrypted channels'
+        end
+
+        shared_secret  = Legba::Encryption.derive_shared_secret(@encryption_master_key, channel_name)
+        string_to_sign = "#{socket_id}:#{channel_name}"
+        hmac           = OpenSSL::HMAC.hexdigest('SHA256', @secret, string_to_sign)
+        { auth: "#{@key}:#{hmac}", shared_secret: Base64.strict_encode64(shared_secret) }
+      elsif channel_name.start_with?('presence-')
+        raise ArgumentError, 'channel_data is required for presence channels' if channel_data.nil?
+
+        channel_data_json = JSON.generate(channel_data)
+        string_to_sign    = "#{socket_id}:#{channel_name}:#{channel_data_json}"
+        hmac              = OpenSSL::HMAC.hexdigest('SHA256', @secret, string_to_sign)
+        { auth: "#{@key}:#{hmac}", channel_data: channel_data_json }
+      else
+        string_to_sign = "#{socket_id}:#{channel_name}"
+        hmac           = OpenSSL::HMAC.hexdigest('SHA256', @secret, string_to_sign)
+        { auth: "#{@key}:#{hmac}" }
+      end
+    end
+
+    def authenticate_user(socket_id, user_data)
+      raise ArgumentError, 'socket_id is required' if socket_id.nil? || socket_id.empty?
+
+      user_id = user_data[:id] || user_data['id']
+      raise ArgumentError, 'user_data must include :id' if user_id.nil? || user_id.to_s.empty?
+
+      user_info = user_data[:user_info] || user_data['user_info']
+
+      user_hash = { 'id' => user_id.to_s }
+      user_hash['user_info'] = user_info if user_info
+
+      body = JSON.generate({ 'socket_id' => socket_id, 'user' => user_hash })
+      post_json('/users/auth', body)
+    end
+
+    private
+
+    def sign(method, path, body, extra_params = {})
+      body_md5       = OpenSSL::Digest::MD5.hexdigest(body)
+      auth_timestamp = Time.now.to_i.to_s
+
+      params = {
+        'auth_key' => @key,
+        'auth_timestamp' => auth_timestamp,
+        'auth_version' => '1.0',
+        'body_md5' => body_md5
+      }.merge(extra_params)
+
+      sorted_params  = params.keys.sort.map { |k| "#{k}=#{params[k]}" }.join('&')
+      string_to_sign = "#{method}\n#{path}\n#{sorted_params}"
+      auth_signature = OpenSSL::HMAC.hexdigest('SHA256', @secret, string_to_sign)
+
+      params.merge('auth_signature' => auth_signature)
+    end
+
+    def post(path, body)
+      full_path = "/apps/#{@app_id}#{path}"
+      signed    = sign('POST', full_path, body)
+
+      uri       = URI("#{@base_url}#{full_path}")
+      uri.query = URI.encode_www_form(signed)
+
+      Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == 'https') do |http|
+        http.read_timeout = @timeout
+        http.open_timeout = @timeout
+
+        req = Net::HTTP::Post.new(uri)
+        req['Content-Type'] = 'application/json'
+        req.body = body
+
+        resp = http.request(req)
+        return true if resp.is_a?(Net::HTTPSuccess)
+
+        json = JSON.parse(resp.body)
+        raise Legba::Error.new(json['error'], status: resp.code.to_i, code: json['code'])
+      end
+    end
+
+    def get(path, extra_params = {})
+      full_path = "/apps/#{@app_id}#{path}"
+      signed    = sign('GET', full_path, '', extra_params)
+
+      uri       = URI("#{@base_url}#{full_path}")
+      uri.query = URI.encode_www_form(signed)
+
+      Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == 'https') do |http|
+        http.read_timeout = @timeout
+        http.open_timeout = @timeout
+
+        req  = Net::HTTP::Get.new(uri)
+        resp = http.request(req)
+        return JSON.parse(resp.body) if resp.is_a?(Net::HTTPSuccess)
+
+        json = JSON.parse(resp.body)
+        raise Legba::Error.new(json['error'], status: resp.code.to_i, code: json['code'])
+      end
+    end
+
+    def post_json(path, body)
+      full_path = "/apps/#{@app_id}#{path}"
+      signed    = sign('POST', full_path, body)
+
+      uri       = URI("#{@base_url}#{full_path}")
+      uri.query = URI.encode_www_form(signed)
+
+      Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == 'https') do |http|
+        http.read_timeout = @timeout
+        http.open_timeout = @timeout
+
+        req = Net::HTTP::Post.new(uri)
+        req['Content-Type'] = 'application/json'
+        req.body = body
+
+        resp = http.request(req)
+        if resp.is_a?(Net::HTTPSuccess)
+          return JSON.parse(resp.body).each_with_object({}) { |(k, v), h| h[k.to_sym] = v }
+        end
+
+        json = JSON.parse(resp.body)
+        raise Legba::Error.new(json['error'], status: resp.code.to_i, code: json['code'])
+      end
+    end
+  end
+end

data/lib/legba/encryption.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require 'rbnacl'
+require 'base64'
+require 'openssl'
+require 'json'
+
+module Legba
+  module Encryption
+    ENCRYPTED_PREFIX = 'private-encrypted-'
+
+    def self.encrypted_channel?(channel_name)
+      channel_name.start_with?(ENCRYPTED_PREFIX)
+    end
+
+    def self.derive_shared_secret(master_key_bytes, channel_name)
+      digest = OpenSSL::Digest.new('SHA256')
+      digest.update(master_key_bytes)
+      digest.update(channel_name)
+      digest.digest
+    end
+
+    def self.encrypt_data(data_string, shared_secret)
+      box = RbNaCl::SecretBox.new(shared_secret)
+      nonce = RbNaCl::Random.random_bytes(box.nonce_bytes)
+      ciphertext = box.encrypt(nonce, data_string)
+
+      JSON.generate({
+                      'nonce' => Base64.strict_encode64(nonce),
+                      'ciphertext' => Base64.strict_encode64(ciphertext)
+                    })
+    end
+  end
+end

data/lib/legba/error.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Legba
+  class Error < StandardError
+    attr_reader :status, :code
+
+    def initialize(message, status:, code:)
+      super(message)
+      @status = status
+      @code   = code
+    end
+  end
+end

data/lib/legba/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Legba
+  VERSION = '0.1.0'
+end

data/lib/legba/webhook.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require 'openssl'
+require 'json'
+
+module Legba
+  class Webhook
+    # Verifies that the x-legba-signature header matches HMAC-SHA256(secret, body).
+    # Uses timing-safe comparison to prevent timing attacks.
+    # Returns true if valid, false otherwise.
+    def self.verify(headers, body, secret)
+      normalized = headers.each_with_object({}) { |(k, v), h| h[k.downcase] = v }
+      signature  = normalized['x-legba-signature']
+      return false if signature.nil? || signature.empty?
+
+      expected = OpenSSL::HMAC.hexdigest('SHA256', secret, body)
+      OpenSSL.secure_compare(expected, signature)
+    end
+
+    # Parses a webhook JSON body into a symbol-keyed hash.
+    # Returns { time_ms: N, events: [{ name:, channel:, ... }] }
+    def self.parse(body)
+      raw    = JSON.parse(body)
+      events = raw['events'].map do |event|
+        event.each_with_object({}) { |(k, v), h| h[k.to_sym] = v }
+      end
+      { time_ms: raw['time_ms'], events: events }
+    end
+  end
+end

data/lib/legba.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require_relative 'legba/version'
+require_relative 'legba/error'
+require_relative 'legba/encryption'
+require_relative 'legba/client'
+require_relative 'legba/webhook'
+
+module Legba
+  # Public API: Legba::Client, Legba::Error, Legba::Webhook, Legba::VERSION
+end

metadata

@@ -0,0 +1,120 @@
+--- !ruby/object:Gem::Specification
+name: legba-ruby
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Legba
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-03-16 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rbnacl
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '7.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '7.1'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.75'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.75'
+- !ruby/object:Gem::Dependency
+  name: websocket-client-simple
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+description: Zero-dependency Ruby server SDK for triggering real-time events on Legba
+  channels.
+email:
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/legba.rb
+- lib/legba/client.rb
+- lib/legba/encryption.rb
+- lib/legba/error.rb
+- lib/legba/version.rb
+- lib/legba/webhook.rb
+homepage:
+licenses:
+- MIT
+metadata:
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.3.7
+signing_key:
+specification_version: 4
+summary: Ruby server SDK for Legba real-time messaging
+test_files: []