conversant 1.0.16

data/Rakefile

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+require 'rubocop/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]
+
+desc 'Run tests and linting'
+task test: %i[spec rubocop]
+
+desc 'Open a console with the gem loaded'
+task :console do
+  require 'bundler/setup'
+  require 'conversant'
+  require 'pry'
+  Pry.start
+end

data/conversant.gemspec

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require_relative 'lib/conversant/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'conversant'
+  spec.version       = Conversant::VERSION
+  spec.authors       = ['Tho Nguyen']
+  spec.email         = ['tho.nguyen@vnetwork.vn']
+
+  spec.summary       = 'Ruby client for Conversant CDN API (V3)'
+  spec.description   = 'A Ruby gem providing a clean interface to interact with Conversant/SwiftFederation CDN services including Portal, CDN, and LMS APIs with V3 authentication support. Features zero-configuration setup, automatic ENV detection, and seamless integration with existing Conversant implementations.'
+  spec.homepage      = 'https://gitlab.vnetwork.dev/gems/conversant'
+  spec.license       = 'MIT'
+  spec.required_ruby_version = '>= 2.7.0'
+
+  spec.metadata = {
+    'homepage_uri' => spec.homepage,
+    'source_code_uri' => "#{spec.homepage}/-/tree/main",
+    'changelog_uri' => "#{spec.homepage}/-/blob/main/CHANGELOG.md",
+    'bug_tracker_uri' => "#{spec.homepage}/-/issues",
+    'documentation_uri' => 'https://rubydoc.info/gems/conversant'
+  }
+
+  # Specify which files should be added to the gem when it is released.
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      f.match(%r{\A(?:test|spec|features)/})
+    end
+  end
+  spec.bindir        = 'exe'
+  spec.executables   = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ['lib']
+
+  # Runtime dependencies
+  spec.add_runtime_dependency 'rest-client', '~> 2.1'
+  spec.add_runtime_dependency 'redis', '~> 5.0'
+  spec.add_runtime_dependency 'json', '~> 2.6'
+
+  # Development dependencies
+  spec.add_development_dependency 'bundler', '~> 2.0'
+  spec.add_development_dependency 'rake', '~> 13.0'
+  spec.add_development_dependency 'rspec', '~> 3.12'
+  spec.add_development_dependency 'rubocop', '~> 1.50'
+  spec.add_development_dependency 'webmock', '~> 3.18'
+  spec.add_development_dependency 'vcr', '~> 6.1'
+  spec.add_development_dependency 'pry', '~> 0.14'
+  spec.add_development_dependency 'yard', '~> 0.9'
+end

data/examples/inheritance_integration.rb

@@ -0,0 +1,348 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'bundler/setup'
+require 'conversant'
+require 'redis'
+require 'logger'
+
+# ==============================================================================
+# STEP 1: Configure the Conversant gem
+# ==============================================================================
+
+# Option 1: Auto-configure from environment variables (recommended)
+begin
+  # This will automatically load all settings from ENV variables:
+  # PORTAL_ROOT_HOSTNAME, PORTAL_SSO_HOSTNAME, PRIVATE_CDN_ENDPOINT,
+  # PRIVATE_LMS_ENDPOINT, SWIFTSERVE_IDENTIFIER_ID, SWIFTSERVE_IDENTIFIER_HASH,
+  # DEFAULT_UA, DEFAULT_CONTENT_TYPE, CONVERSANT_DEBUG, CONVERSANT_CACHE_TTL
+  Conversant.auto_configure!
+  puts "✓ Auto-configured from environment variables"
+rescue Conversant::Error => e
+  puts "Auto-configuration failed: #{e.message}"
+
+  # Option 2: Manual configuration fallback
+  Conversant.configure do |config|
+    config.private_cdn_endpoint = ENV['PRIVATE_CDN_ENDPOINT'] || 'https://cdn.example.com'
+    config.private_lms_endpoint = ENV['PRIVATE_LMS_ENDPOINT'] || 'https://lms.example.com'
+    config.swiftserve_identifier_id = ENV['SWIFTSERVE_IDENTIFIER_ID'] || 'test_id'
+    config.swiftserve_identifier_hash = ENV['SWIFTSERVE_IDENTIFIER_HASH'] || 'test_hash'
+    config.redis = Redis.new(url: ENV['REDIS_URL'] || 'redis://localhost:6379')
+  end
+end
+
+# ==============================================================================
+# STEP 2: Define your application's namespace structure
+# ==============================================================================
+
+module Utils
+  module Conversant
+    module V3
+      # Empty - will be populated with our classes
+    end
+  end
+end
+
+# ==============================================================================
+# APPROACH 1: Direct Inheritance
+# Your classes inherit from gem classes and extend functionality
+# ==============================================================================
+
+module Utils
+  module Conversant
+    module V3
+      # Portal Service - Inherits from gem and adds custom methods
+      class Portal < ::Conversant::V3::Services::Portal
+        # Add your custom business logic methods
+        def appliances_summary(gte = nil, lte = nil)
+          appliances_data = appliances(gte, lte)
+
+          {
+            total: appliances_data.length,
+            active: appliances_data.reject { |a| a['deleted'] }.length,
+            deleted: appliances_data.select { |a| a['deleted'] }.length,
+            by_pop: appliances_data.group_by { |a| a['pop'] }.transform_values(&:length),
+            total_volume: appliances_data.sum { |a| a['volume'] || 0 },
+            total_federation: appliances_data.sum { |a| a['federation'] || 0 }
+          }
+        end
+
+        # Override parent method if needed
+        def appliances(gte = nil, lte = nil)
+          logger.info "#{self.class.name} - Fetching appliances for customer: #{customer_id}"
+          super # Call parent implementation
+        end
+      end
+
+      # CDN Service - Inherits from gem and adds custom analytics
+      class CDN < ::Conversant::V3::Services::CDN
+        # Add custom analytics aggregation
+        def daily_summary(date = Date.today)
+          start_time = date.strftime("%Y-%m-%dT00:00:00Z")
+          end_time = date.strftime("%Y-%m-%dT23:59:59Z")
+
+          {
+            date: date,
+            bandwidth: analytics.bandwidths({
+              startTime: start_time,
+              endTime: end_time,
+              interval: "1h"
+            }),
+            volumes: analytics.volumes({
+              startTime: start_time,
+              endTime: end_time
+            }),
+            monitoring_spots: monitoring.spots({
+              startTime: start_time,
+              endTime: end_time
+            })
+          }
+        end
+
+        # Custom method for weekly reports
+        def weekly_report(start_date = Date.today - 7)
+          (0..6).map { |i| daily_summary(start_date + i) }
+        end
+      end
+
+      # LMS Service - Inherits from gem and adds stream management
+      class LMS < ::Conversant::V3::Services::LMS
+        # Add stream filtering and grouping
+        def active_streams_by_status
+          streams = job.where(limit: 1000)
+
+          return {} unless streams
+
+          streams.group_by { |s| s[:status] }.transform_values do |stream_list|
+            {
+              count: stream_list.length,
+              streams: stream_list.map { |s|
+                {
+                  id: s[:id],
+                  name: s[:name],
+                  encoder: s[:encoder],
+                  started_at: s[:started_at]
+                }
+              }
+            }
+          end
+        end
+
+        # Add business-specific method
+        def find_stream_by_name(stream_name)
+          streams = job.where(limit: 1000)
+          streams&.find { |s| s[:name] == stream_name }
+        end
+
+        # Monitor GPU usage
+        def gpu_utilization
+          streams = job.where(status: 'streaming')
+
+          return nil unless streams
+
+          total_streams = streams.length
+          gpu_streams = streams.select { |s| s[:gpu] }.length
+
+          {
+            total_streams: total_streams,
+            gpu_enabled: gpu_streams,
+            cpu_only: total_streams - gpu_streams,
+            gpu_percentage: total_streams > 0 ? (gpu_streams.to_f / total_streams * 100).round(2) : 0
+          }
+        end
+      end
+    end
+  end
+end
+
+# ==============================================================================
+# APPROACH 2: Mixin-Based (When you can't change inheritance)
+# Use when you have existing classes that can't inherit from gem
+# ==============================================================================
+
+module Utils
+  module Conversant
+    module V3
+      # Existing class that includes mixin instead of inheriting
+      class LegacyPortal
+        include ::Conversant::V3::Mixins::Authentication
+        use_conversant_auth!
+
+        def initialize(customer_id, type = 2)
+          @customer_id = customer_id
+          @type = type
+          initialize_conversant_auth(customer_id, type)
+        end
+
+        # Use gem's authentication for your custom methods
+        def get_appliance_metrics
+          headers = portal_authorized_headers
+
+          # Your custom API call using gem's auth
+          response = RestClient.post(
+            "#{configuration.portal_endpoint}/custom/metrics",
+            { customerId: @customer_id }.to_json,
+            headers
+          )
+
+          JSON.parse(response.body)
+        rescue => e
+          logger.error "Failed to get metrics: #{e.message}"
+          nil
+        end
+
+        private
+
+        def configuration
+          ::Conversant.configuration
+        end
+
+        def logger
+          configuration.logger
+        end
+      end
+    end
+  end
+end
+
+# ==============================================================================
+# APPROACH 3: Composition (Wrapper Pattern)
+# Wrap gem classes when you need more control
+# ==============================================================================
+
+module Utils
+  module Conversant
+    module V3
+      class PortalWrapper
+        attr_reader :portal_client, :customer_id
+
+        def initialize(customer_id, type = 2)
+          @customer_id = customer_id
+          @portal_client = ::Conversant::V3.portal(customer_id, type)
+        end
+
+        # Delegate to gem client
+        def appliances(*args)
+          portal_client.appliances(*args)
+        end
+
+        # Add your business logic
+        def appliances_with_cache(gte = nil, lte = nil)
+          cache_key = "portal_appliances_#{customer_id}_#{gte}_#{lte}"
+
+          cached = read_cache(cache_key)
+          return cached if cached
+
+          data = portal_client.appliances(gte, lte)
+          write_cache(cache_key, data, ttl: 3600)
+
+          data
+        end
+
+        private
+
+        def read_cache(key)
+          # Your caching logic
+          nil
+        end
+
+        def write_cache(key, data, ttl:)
+          # Your caching logic
+        end
+      end
+    end
+  end
+end
+
+# ==============================================================================
+# USAGE EXAMPLES
+# ==============================================================================
+
+def demo_inheritance_approach
+  puts "\n" + "="*60
+  puts "INHERITANCE APPROACH - Using Utils::Conversant::V3 classes"
+  puts "="*60
+
+  customer_id = ENV['CUSTOMER_ID'] || '12345'
+
+  # Use your inherited Portal class
+  portal = Utils::Conversant::V3::Portal.new(customer_id)
+
+  puts "\n--- Portal Operations ---"
+  summary = portal.appliances_summary
+  puts "Appliances Summary:"
+  puts "  Total: #{summary[:total]}"
+  puts "  Active: #{summary[:active]}"
+  puts "  By POP: #{summary[:by_pop]}"
+  puts "  Total Volume: #{summary[:total_volume]}"
+
+  # Use your inherited CDN class
+  cdn = Utils::Conversant::V3::CDN.new(customer_id)
+
+  puts "\n--- CDN Operations ---"
+  daily = cdn.daily_summary
+  puts "Today's CDN Summary:"
+  puts "  Date: #{daily[:date]}"
+  puts "  Monitoring Spots: #{daily[:monitoring_spots]&.length || 0}"
+
+  # Use your inherited LMS class
+  lms = Utils::Conversant::V3::LMS.new(customer_id)
+
+  puts "\n--- LMS Operations ---"
+  gpu_stats = lms.gpu_utilization
+  if gpu_stats
+    puts "GPU Utilization:"
+    puts "  Total Streams: #{gpu_stats[:total_streams]}"
+    puts "  GPU Enabled: #{gpu_stats[:gpu_enabled]} (#{gpu_stats[:gpu_percentage]}%)"
+  end
+
+  streams_by_status = lms.active_streams_by_status
+  puts "Streams by Status:"
+  streams_by_status.each do |status, info|
+    puts "  #{status}: #{info[:count]} streams"
+  end
+end
+
+def demo_mixin_approach
+  puts "\n" + "="*60
+  puts "MIXIN APPROACH - Using Authentication Mixin"
+  puts "="*60
+
+  customer_id = ENV['CUSTOMER_ID'] || '12345'
+
+  legacy = Utils::Conversant::V3::LegacyPortal.new(customer_id)
+  metrics = legacy.get_appliance_metrics
+  puts "Custom metrics retrieved: #{metrics ? 'Success' : 'Failed'}"
+end
+
+def demo_composition_approach
+  puts "\n" + "="*60
+  puts "COMPOSITION APPROACH - Using Wrapper Pattern"
+  puts "="*60
+
+  customer_id = ENV['CUSTOMER_ID'] || '12345'
+
+  wrapper = Utils::Conversant::V3::PortalWrapper.new(customer_id)
+  appliances = wrapper.appliances_with_cache
+  puts "Appliances via wrapper: #{appliances&.length || 0} items"
+end
+
+# ==============================================================================
+# RUN THE EXAMPLES
+# ==============================================================================
+
+if __FILE__ == $0
+  begin
+    # Run all three approaches
+    demo_inheritance_approach
+    demo_mixin_approach
+    demo_composition_approach
+
+    puts "\n" + "="*60
+    puts "All examples completed successfully!"
+    puts "="*60
+  rescue => e
+    puts "\nError: #{e.message}"
+    puts e.backtrace.first(5)
+  end
+end

data/examples/rails_initializer.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+# config/initializers/conversant.rb
+#
+# Rails initializer for Conversant gem
+# This file auto-configures the gem using your existing environment variables
+
+require 'conversant'
+
+# Auto-configure from ENV variables
+begin
+  Conversant.auto_configure!
+
+  Rails.logger.info "✓ Conversant gem configured successfully"
+  Rails.logger.info "  Portal: #{Conversant.configuration.portal_endpoint}"
+  Rails.logger.info "  CDN: #{Conversant.configuration.private_cdn_endpoint}"
+  Rails.logger.info "  LMS: #{Conversant.configuration.private_lms_endpoint}"
+  Rails.logger.info "  Debug: #{Conversant.configuration.debug_mode}"
+  Rails.logger.info "  Cache TTL: #{Conversant.configuration.cache_ttl}s"
+
+rescue Conversant::Error => e
+  Rails.logger.error "Conversant configuration failed: #{e.message}"
+
+  # Optional: Raise error in production to prevent startup with bad config
+  raise if Rails.env.production?
+
+  # Optional: Use fallback configuration in development
+  if Rails.env.development?
+    Conversant.configure do |config|
+      config.private_cdn_endpoint = 'https://cdn.dev.example.com'
+      config.private_lms_endpoint = 'https://lms.dev.example.com'
+      config.swiftserve_identifier_id = 'dev_id'
+      config.swiftserve_identifier_hash = 'dev_hash'
+      config.redis = $redis || Redis.new
+    end
+    Rails.logger.warn "Using development fallback configuration"
+  end
+end
+
+# Optional: Add convenience methods to ApplicationController or as a concern
+module ConversantHelper
+  extend ActiveSupport::Concern
+
+  included do
+    helper_method :conversant_portal, :conversant_cdn, :conversant_lms if respond_to?(:helper_method)
+  end
+
+  private
+
+  def conversant_portal(customer_id)
+    @conversant_portal ||= {}
+    @conversant_portal[customer_id] ||= Conversant::V3.portal(customer_id)
+  end
+
+  def conversant_cdn(customer_id)
+    @conversant_cdn ||= {}
+    @conversant_cdn[customer_id] ||= Conversant::V3.cdn(customer_id)
+  end
+
+  def conversant_lms(customer_id)
+    @conversant_lms ||= {}
+    @conversant_lms[customer_id] ||= Conversant::V3.lms(customer_id)
+  end
+end
+
+# Optional: Include in ApplicationController
+# class ApplicationController < ActionController::Base
+#   include ConversantHelper
+# end

data/lib/conversant/configuration.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+module Conversant
+  class Configuration
+    attr_accessor :portal_root_hostname,
+                  :portal_sso_hostname,
+                  :private_cdn_endpoint,
+                  :private_lms_endpoint,
+                  :private_vms_endpoint,
+                  :private_oss_endpoint,
+                  :private_portal_endpoint,
+                  :private_sso_endpoint,
+                  :conversant_cdn_api_url,
+                  :swiftserve_identifier_id,
+                  :swiftserve_identifier_hash,
+                  :default_ua,
+                  :default_content_type,
+                  :redis,
+                  :logger,
+                  :debug_mode,
+                  :verify_ssl,
+                  :cache_ttl
+
+    def initialize
+      # All configuration automatically uses ENV variables as defaults
+      # Users only need to override if they want different values
+
+      # Portal configuration - defaults from ENV
+      @portal_root_hostname = ENV['PORTAL_ROOT_HOSTNAME'] || 'console.swiftfederation.com'
+      @portal_sso_hostname = ENV['PORTAL_SSO_HOSTNAME'] || 'sso.swiftfederation.com'
+
+      # API Endpoints - defaults from ENV (matching existing CONVERSANT setup)
+      @private_cdn_endpoint = ENV['PRIVATE_CDN_ENDPOINT']
+      @private_lms_endpoint = ENV['PRIVATE_LMS_ENDPOINT']
+      @private_vms_endpoint = ENV['PRIVATE_VMS_ENDPOINT']
+      @private_oss_endpoint = ENV['PRIVATE_OSS_ENDPOINT']
+      @private_portal_endpoint = ENV['PRIVATE_PORTAL_ENDPOINT'] || "https://#{@portal_root_hostname}"
+      @private_sso_endpoint = ENV['PRIVATE_SSO_ENDPOINT'] || "https://#{@portal_sso_hostname}"
+
+      # Authentication - defaults from ENV
+      @swiftserve_identifier_id = ENV['SWIFTSERVE_IDENTIFIER_ID']
+      @swiftserve_identifier_hash = ENV['SWIFTSERVE_IDENTIFIER_HASH']
+
+      # HTTP settings - defaults from ENV
+      @default_ua = ENV['DEFAULT_UA'] || 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36'
+      @default_content_type = ENV['DEFAULT_CONTENT_TYPE'] || 'application/json'
+
+      # Additional CDN API URL if needed
+      @conversant_cdn_api_url = ENV['CONVERSANT_CDN_API_URL']
+
+      # Runtime settings
+      @logger = Logger.new($stdout)
+      @debug_mode = ENV['CONVERSANT_DEBUG'] == 'true' || ENV['DEBUG'] == 'true'
+      @verify_ssl = ENV['RAILS_ENV'] == 'production'
+      @cache_ttl = (ENV['CONVERSANT_CACHE_TTL'] || 1200).to_i
+
+      # Redis - auto-detect from global $redis or ENV
+      @redis = if defined?($redis) && $redis
+        $redis
+      elsif defined?(::Redis) && ENV['REDIS_URL']
+        ::Redis.new(url: ENV['REDIS_URL'])
+      elsif defined?(::Redis)
+        ::Redis.new
+      else
+        nil
+      end
+    end
+
+    def portal_endpoint
+      @private_portal_endpoint || "https://#{portal_root_hostname}"
+    end
+
+    def sso_endpoint
+      @private_sso_endpoint || "https://#{portal_sso_hostname}"
+    end
+
+    def validate!
+      required_fields = []
+
+      # Only require credentials if not auto-configured
+      unless auto_configured?
+        required_fields += [
+          :swiftserve_identifier_id,
+          :swiftserve_identifier_hash
+        ]
+      end
+
+      # Always require endpoints
+      required_fields += [
+        :private_cdn_endpoint,
+        :private_lms_endpoint,
+        :private_vms_endpoint,
+        :redis
+      ]
+
+      missing_fields = required_fields.select { |field| send(field).nil? || send(field).to_s.empty? }
+
+      if missing_fields.any?
+        raise Error, "Missing required configuration: #{missing_fields.join(', ')}\n" \
+                     "Please set the following environment variables: #{missing_fields.map { |f| env_var_name(f) }.join(', ')}"
+      end
+
+      true
+    end
+
+    # Check if configuration is loaded from environment
+    def auto_configured?
+      !@swiftserve_identifier_id.nil? && !@swiftserve_identifier_hash.nil?
+    end
+
+    # Helper to map config field to ENV variable name
+    def env_var_name(field)
+      case field
+      when :swiftserve_identifier_id then 'SWIFTSERVE_IDENTIFIER_ID'
+      when :swiftserve_identifier_hash then 'SWIFTSERVE_IDENTIFIER_HASH'
+      when :private_cdn_endpoint then 'PRIVATE_CDN_ENDPOINT'
+      when :private_lms_endpoint then 'PRIVATE_LMS_ENDPOINT'
+      when :private_vms_endpoint then 'PRIVATE_VMS_ENDPOINT'
+      when :portal_root_hostname then 'PORTAL_ROOT_HOSTNAME'
+      when :portal_sso_hostname then 'PORTAL_SSO_HOSTNAME'
+      else field.to_s.upcase
+      end
+    end
+
+    # Load configuration from environment and validate
+    def self.from_env
+      config = new
+      config.validate!
+      config
+    end
+  end
+end

data/lib/conversant/v3/base.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Conversant
+  module V3
+    class Base
+      include HttpClient
+
+      attr_reader :customer_id, :type
+
+      def initialize(customer_id, type = 2)
+        @customer_id = customer_id
+        @type = type
+        validate_configuration!
+      end
+
+      protected
+
+      def validate_configuration!
+        Conversant.configuration.validate!
+      end
+
+      def configuration
+        Conversant.configuration
+      end
+
+      def redis
+        configuration.redis
+      end
+
+      def portal_endpoint
+        configuration.portal_endpoint
+      end
+
+      def sso_endpoint
+        configuration.sso_endpoint
+      end
+
+      def identifier
+        @identifier ||= self.class.name.split('::').map(&:upcase).join('-')
+      end
+
+      def logger
+        configuration.logger
+      end
+    end
+  end
+end