conduit-ussd 0.1.0

data/lib/conduit/middleware/logging.rb

@@ -0,0 +1,23 @@
+module Conduit
+  module Middleware
+    class Logging < Base
+      def initialize(app, logger: nil)
+        super(app)
+        @logger = logger || Conduit.configuration.logger
+      end
+
+      def call(env)
+        start_time = Time.current
+
+        @logger.info "USSD Request: session_id=#{env[:session_id]} msisdn=#{env[:msisdn]} input=#{env[:input]}"
+
+        result = @app.call(env)
+
+        duration = ((Time.current - start_time) * 1000).round(2)
+        @logger.info "USSD Response: session_id=#{env[:session_id]} duration=#{duration}ms action=#{result[:action]}"
+
+        result
+      end
+    end
+  end
+end

data/lib/conduit/middleware/session_tracking.rb

@@ -0,0 +1,30 @@
+module Conduit
+  module Middleware
+    class SessionTracking < Base
+      def call(env)
+        session = env[:session]
+
+        if session && session.navigation_stack.empty?
+          track_event("session_started", session)
+        end
+
+        result = @app.call(env)
+
+        if result[:response]&.end?
+          track_event("session_ended", session)
+        end
+
+        result
+      end
+
+      private
+
+      def track_event(event, session)
+        return unless session
+
+        # this could be a call to AppSignal, StatsD ... etc(I'm thinking StatsD)
+        Conduit.configuration.logger.info "Track: #{event} for #{session.msisdn}"
+      end
+    end
+  end
+end

data/lib/conduit/middleware/throttling.rb

@@ -0,0 +1,41 @@
+module Conduit
+  module Middleware
+    class Throttling < Base
+      def initialize(app, max_requests: 10, window: 60)
+        super(app)
+        @max_requests = max_requests
+        @window = window
+      end
+
+      def call(env)
+        msisdn = env[:msisdn]
+        return @app.call(env) unless msisdn
+
+        key = "throttle:#{msisdn}"
+        count = increment_counter(key)
+
+        if count > @max_requests
+          {
+            response: Conduit::Response.new(
+              text: "Too many requests. Please try again later.",
+              action: :end
+            ),
+            provider: env[:provider]
+          }
+        else
+          @app.call(env)
+        end
+      end
+
+      private
+
+      def increment_counter(key)
+        Conduit.configuration.redis_pool.with do |redis|
+          count = redis.incr(key)
+          redis.expire(key, @window) if count == 1
+          count
+        end
+      end
+    end
+  end
+end

data/lib/conduit/middleware.rb

@@ -0,0 +1,36 @@
+module Conduit
+  module Middleware
+    class Base
+      def initialize(app, *args, &block)
+        @app = app
+      end
+
+      delegate :call, to: :@app
+    end
+
+    class Chain
+      def initialize
+        @middlewares = []
+      end
+
+      def use(middleware, *args, &block)
+        @middlewares << [middleware, args, block]
+      end
+
+      def call(env, &final_block)
+        chain = final_block || ->(e) { e }
+
+        @middlewares.reverse_each do |(middleware, args, block)|
+          previous_chain = chain
+          chain = ->(environment) do
+            middleware.new(previous_chain, *args, &block).call(environment)
+          end
+        end
+
+        chain.call(env)
+      end
+
+      delegate :clear, to: :@middlewares
+    end
+  end
+end

data/lib/conduit/providers/africas_talking.rb

@@ -0,0 +1,39 @@
+module Conduit
+  module Providers
+    class AfricasTalking
+      attr_reader :params
+
+      def initialize(params)
+        @params = params
+      end
+
+      def parse_request
+        {
+          session_id: params[:sessionId],
+          msisdn: normalize_phone_number(params[:phoneNumber]),
+          service_code: params[:serviceCode],
+          network_code: params[:networkCode],
+          raw_input: params[:text],
+          input: extract_latest_input(params[:text])
+        }
+      end
+
+      def format_response(response)
+        prefix = response.end? ? "END " : "CON "
+        "#{prefix}#{response.text}"
+      end
+
+      private
+
+      def extract_latest_input(text)
+        return nil if text.blank?
+        text.split("*").last
+      end
+
+      # for this one we can use Phobelib.parse(phone).to_s :thinkng?
+      def normalize_phone_number(phone)
+        phone.to_s.gsub(/\D/, "")
+      end
+    end
+  end
+end

data/lib/conduit/request_handler.rb

@@ -0,0 +1,126 @@
+module Conduit
+  class RequestHandler
+    def initialize
+      @store = SessionStore.new
+      @provider = Providers::AfricasTalking
+    end
+
+    def process(raw_params)
+      # Parse request using AfricasTalking
+      provider = @provider.new(raw_params)
+      params = provider.parse_request
+
+      env = {
+        params:,
+        session_id: params[:session_id],
+        msisdn: params[:msisdn],
+        service_code: params[:service_code],
+        input: params[:input],
+        raw_params:,
+        provider:
+      }
+
+      # Run through middleware chain
+      result = Conduit.configuration.middleware.call(env) do |environment|
+        process_request(environment)
+      end
+
+      # Format response
+      result[:provider].format_response(result[:response])
+    rescue => e
+      Conduit.configuration.logger.error "Error processing request: #{e.message}\n#{e.backtrace.join("\n")}"
+      error_response = Response.new(text: "Service temporarily unavailable", action: :end)
+      provider.format_response(error_response)
+    end
+
+    private
+
+    def process_request(env)
+      params = env[:params]
+
+      # Get or create session
+      session = @store.get(params[:session_id]) || create_session(params)
+      env[:session] = session
+
+      # Check if expired
+      if session.expired?
+        @store.delete(session.session_id)
+        response = Response.new(
+          text: "Your session has expired. Please dial again.",
+          action: :end
+        )
+      else
+        # Check if there's a pending flow transition from previous request
+        if session.data[:pending_flow_transition]
+          flow_class_name = session.data[:pending_flow_transition]
+          session.data.delete(:pending_flow_transition)
+
+          # Reset session state for new flow
+          session.current_state = nil
+
+          # Store the current flow for subsequent requests
+          session.data[:current_flow] = flow_class_name
+
+          # Instantiate the new flow and process with empty input (display initial state)
+          flow = Object.const_get(flow_class_name).new
+          response = flow.process(session, "")
+        elsif session.data[:current_flow]
+          # Continue with the current flow
+          flow = Object.const_get(session.data[:current_flow]).new
+          response = flow.process(session, params[:input])
+        else
+          # Get flow for service code (normal flow - first request)
+          flow = Router.find_flow(params[:service_code])
+
+          # Store the flow class name for subsequent requests
+          session.data[:current_flow] = flow.class.name
+
+          response = flow.process(session, params[:input])
+        end
+
+        # Handle flow transition if next_flow is specified
+        if response.transition?
+          # Store the next flow class name for the NEXT request
+          session.data[:pending_flow_transition] = response.next_flow.name
+          # Keep the response text but change action to continue
+          response = Response.new(text: response.text, action: :continue)
+        end
+
+        # Save or cleanup session
+        if response.end?
+          save_completed_session(session) if Conduit.configuration.save_sessions
+          @store.delete(session.session_id)
+        else
+          @store.set(session)
+        end
+      end
+
+      {response:, provider: env[:provider], session:}
+    end
+
+    def create_session(params)
+      Session.new(
+        session_id: params[:session_id],
+        msisdn: params[:msisdn],
+        service_code: params[:service_code]
+      )
+    end
+
+    def save_completed_session(session)
+      return unless Conduit.configuration.save_sessions
+
+      # Save to database if available
+      if defined?(Conduit::SessionRecord)
+        begin
+          record = Conduit::SessionRecord.from_session(session, completed: true)
+          record.save!
+          Rails.logger.info "Session saved: #{session.session_id}"
+        rescue => e
+          Rails.logger.error "Failed to save session: #{e.message}"
+        end
+      else
+        Rails.logger.info "Session completed: #{session.to_h}"
+      end
+    end
+  end
+end

data/lib/conduit/response.rb

@@ -0,0 +1,23 @@
+module Conduit
+  class Response
+    attr_reader :text, :action, :next_flow
+
+    def initialize(text:, action: :continue, next_flow: nil)
+      @text = text
+      @action = action.to_sym
+      @next_flow = next_flow
+    end
+
+    def continue?
+      @action == :continue
+    end
+
+    def end?
+      @action == :end
+    end
+
+    def transition?
+      !@next_flow.nil?
+    end
+  end
+end

data/lib/conduit/router.rb

@@ -0,0 +1,30 @@
+module Conduit
+  class Router
+    class << self
+      def routes
+        @routes ||= {}
+      end
+
+      def draw(&)
+        instance_eval(&)
+      end
+
+      def route(service_code, to:)
+        routes[normalize_service_code(service_code)] = to
+      end
+
+      def find_flow(service_code)
+        flow_class = routes[normalize_service_code(service_code)]
+        raise "No flow found for service code: #{service_code}" unless flow_class
+
+        flow_class.new
+      end
+
+      private
+
+      def normalize_service_code(code)
+        code.to_s.gsub(/\D/, "")
+      end
+    end
+  end
+end

data/lib/conduit/session.rb

@@ -0,0 +1,73 @@
+module Conduit
+  class Session
+    attr_accessor :session_id, :msisdn, :service_code,
+      :current_state, :navigation_stack, :data,
+      :started_at, :last_activity_at
+
+    def initialize(attrs = {})
+      @session_id = attrs[:session_id]
+      @msisdn = attrs[:msisdn]
+      @service_code = attrs[:service_code]
+      @current_state = attrs[:current_state] || "initial"
+      @navigation_stack = attrs[:navigation_stack] || []
+      @data = attrs[:data] || {}
+      @started_at = attrs[:started_at] || Time.current
+      @last_activity_at = attrs[:last_activity_at] || Time.current
+    end
+
+    def navigate_to(state)
+      @navigation_stack.push(@current_state) unless @current_state == "initial"
+      @navigation_stack = @navigation_stack.last(Conduit.configuration.max_navigation_depth)
+      @current_state = state.to_s
+      @last_activity_at = Time.current
+    end
+
+    def go_back
+      previous_state = @navigation_stack.pop
+      @current_state = previous_state if previous_state
+      @last_activity_at = Time.current
+    end
+
+    def can_go_back?
+      @navigation_stack.any?
+    end
+
+    def duration
+      Time.current - @started_at
+    end
+
+    def expired?
+      Time.current - @last_activity_at > Conduit.configuration.session_ttl
+    end
+
+    def to_h
+      {
+        session_id:,
+        msisdn:,
+        service_code:,
+        current_state:,
+        navigation_stack:,
+        data:,
+        started_at: started_at.to_i,
+        last_activity_at: last_activity_at.to_i
+      }
+    end
+
+    delegate :to_json, to: :to_h
+
+    def self.from_hash(hash)
+      hash = hash.with_indifferent_access
+
+      new(
+        session_id: hash[:session_id],
+        msisdn: hash[:msisdn],
+        service_code: hash[:service_code],
+        current_state: hash[:current_state],
+        navigation_stack: hash[:navigation_stack] || [],
+        data: hash[:data] || {},
+        started_at: Time.at((hash[:started_at] || Time.current).to_i),
+        last_activity_at: Time.at((hash[:last_activity_at] || Time.current).to_i)
+      )
+    end
+  end
+end

data/lib/conduit/session_store.rb

@@ -0,0 +1,41 @@
+module Conduit
+  class SessionStore
+    def initialize
+      @pool = Conduit.configuration.redis_pool
+    end
+
+    def get(session_id)
+      @pool.with do |redis|
+        data = redis.get(key_for(session_id))
+        return nil unless data
+
+        Session.from_hash(JSON.parse(data))
+      end
+    rescue => e
+      Conduit.configuration.logger.error "Failed to get session #{session_id}: #{e.message}"
+      nil
+    end
+
+    def set(session)
+      @pool.with do |redis|
+        redis.setex(
+          key_for(session.session_id),
+          Conduit.configuration.session_ttl.to_i,
+          session.to_json
+        )
+      end
+    end
+
+    def delete(session_id)
+      @pool.with do |redis|
+        redis.del(key_for(session_id))
+      end
+    end
+
+    private
+
+    def key_for(session_id)
+      "conduit:session:#{session_id}"
+    end
+  end
+end

data/lib/conduit/state.rb

@@ -0,0 +1,189 @@
+module Conduit
+  # This behaves like single screen/menu in a USSD flow. Think of it as a "page" in your application.
+  #
+  class State
+    attr_reader :name, :options
+
+    def initialize(name, options = {}, &)
+      @name = name.to_sym
+      @options = options
+      @transitions = {}
+      @display_block = nil
+      @before_callbacks = []
+      @validations = []
+      @on_valid_block = nil
+      @on_invalid_block = nil
+
+      instance_eval(&) if block_given?
+    end
+
+    def display(text = nil, &block)
+      @display_block = if block
+        lambda do |session|
+          # Try to execute block in DisplayBuilder context
+          builder = DisplayBuilder.new
+          result = builder.instance_exec(session, &block)
+
+          # If block returns a string, use that (old style)
+          # Otherwise, use the builder's accumulated content (new DSL style)
+          if result.is_a?(String)
+            result
+          else
+            builder.to_s
+          end
+        end
+      else
+        ->(_) { text }
+      end
+    end
+
+    def validates(validator_name = nil, *args, **options, &custom_validator)
+      if custom_validator
+        # Custom validator block
+        @validations << custom_validator
+      elsif validator_name.is_a?(Symbol)
+        # Built-in validator
+        validator = Validator.public_send(validator_name, *args, **options)
+        @validations << validator
+      elsif validator_name.nil?
+        raise ArgumentError, "Must provide either a validator name or a block"
+      else
+        raise ArgumentError, "Invalid validator: #{validator_name}"
+      end
+    end
+
+    def on_valid(&block)
+      @on_valid_block = block
+    end
+
+    def on_invalid(&block)
+      @on_invalid_block = block
+    end
+
+    def on(input, options = {}, &block)
+      @transitions[input.to_s] = Transition.new(input, options, block)
+    end
+
+    def on_any(options = {}, &block)
+      @transitions[:any] = Transition.new(:any, options, block)
+    end
+
+    def before_render(&block)
+      @before_callbacks << block
+    end
+
+    # Runtime Methods
+    def render(session)
+      run_callbacks(@before_callbacks, session)
+
+      content = if @display_block
+        @display_block.call(session)
+      else
+        "No content defined for state: #{@name}"
+      end
+
+      Response.new(text: content, action: :continue)
+    end
+
+    def handle_input(input, session, flow = nil)
+      # Check for exact transition match first (before validations)
+      # This allows specific handlers like `on "0"` to override validations
+      exact_transition = @transitions[input]
+
+      if exact_transition
+        return exact_transition.execute(input, session)
+      end
+
+      # Check for global back navigation (only if no exact match)
+      if input == "0" && session.can_go_back?
+        session.go_back
+        return nil
+      elsif input == "00" && flow
+        session.navigate_to(flow.class.initial_state_name)
+        return nil
+      end
+
+      # Run validations if any are defined
+      if @validations.any?
+        validation_error = run_validations(input, session, flow)
+
+        if validation_error
+          # Validation failed
+          if @on_invalid_block
+            return @on_invalid_block.call(validation_error, session)
+          else
+            return Response.new(text: validation_error, action: :continue)
+          end
+        elsif @on_valid_block
+          # Validation passed
+          result = @on_valid_block.call(input, session)
+          return result if result.is_a?(Response)
+
+          # Continue with normal transition handling
+        end
+      end
+
+      # Check for catch-all transition
+      transition = @transitions[:any]
+
+      return nil unless transition
+
+      transition.execute(input, session)
+    end
+
+    private
+
+    def run_callbacks(callbacks, *)
+      callbacks.each { |cb| cb.call(*) }
+    end
+
+    def run_validations(input, session, flow)
+      @validations.each do |validation|
+        result = if validation.respond_to?(:call)
+          # Lambda or proc
+          validation.call(input, session)
+        else
+          # Method name (symbol)
+          flow.send(validation, input, session)
+        end
+
+        # If validation returns a string, it's an error message
+        return result if result.is_a?(String)
+
+        # If validation returns false, use a generic message
+        return "Invalid input" if result == false
+      end
+
+      nil # No errors
+    end
+  end
+
+  #  This defines how users move between states based on their input.
+  #
+  class Transition
+    def initialize(matcher, options = {}, block = nil)
+      @matcher = matcher
+      @to = options[:to]
+      @block = block
+    end
+
+    def execute(input, session)
+      # Execute block if provided
+      if @block
+        result = @block.call(input, session)
+        return result if result.is_a?(Response)
+      end
+
+      # Handle navigation
+      if @to
+        if @to == :back
+          session.go_back
+        else
+          session.navigate_to(@to)
+        end
+      end
+
+      nil
+    end
+  end
+end