flow_chat 0.7.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1d5c2d35096c65d8953ed19fe427a61b13c7b2fabab871cc99562bde861576be
-  data.tar.gz: ee342523ae86be4397bbb0586a2a38966d473094a1d33aacb047fe26edf93c78
+  metadata.gz: 5ebeb5cdcbacce73ec580e381554dbd2377f7896d7d06c488970051f6a8bf599
+  data.tar.gz: bc33f9f54c78264f416e00163e2ba0cf78da2e8e0961c942bb3aab1e86e783e5
 SHA512:
-  metadata.gz: bae27cb42464181afbc3751082344d9aaa6c8d4ae6915794aa5671fec8622eb24f2d694d14a3414c11f3125c954a022a781ed91eaf4705c0314b240920434eac
-  data.tar.gz: 50fd0405af1d6e1e79ef62be8bb2e6bca81ed0d46297bf7b1ed5bbd04f0d892b30261fde9c547a523bd9003ad8612efee3aadb11f683af4af0fded396c6a2538
+  metadata.gz: 34006bb23ddaf1aefd8ec4876cb70d8f06d2bbb23da48663ff7a40dd630d9b01af58d9980c343c9d933fa637512375b5c7ba3b0b336ba91a314fdd9ae5fb2ba1
+  data.tar.gz: 78a242f2b175f57ce29326f342c9d4bf4c7c4402c0e2fcd634c21322280dcd0ac273d86eb19750702472218e9d08fd97267ad711b3673f108f89617e5319b9f7

data/README.md

@@ -186,6 +186,7 @@ See the [Testing Guide](docs/testing.md) for complete setup instructions and tes
 - **[WhatsApp Setup](docs/whatsapp-setup.md)** - Comprehensive WhatsApp configuration
 - **[USSD Setup](docs/ussd-setup.md)** - USSD gateway configuration and examples
 - **[Flow Development](docs/flows.md)** - Advanced flow patterns and techniques
+- **[Session Management](docs/sessions.md)** - Session architecture and configuration
 - **[Media Support](docs/media.md)** - Rich media handling for WhatsApp
 - **[Testing Guide](docs/testing.md)** - Complete testing strategies
 - **[Configuration Reference](docs/configuration.md)** - All configuration options

data/docs/configuration.md

@@ -19,6 +19,26 @@ FlowChat::Config.combine_validation_error_with_message = true  # default
 FlowChat.setup_instrumentation!
 ```
 
+## Session Configuration
+
+```ruby
+# Session boundaries control how session IDs are constructed
+FlowChat::Config.session.boundaries = [:flow, :platform]  # default
+FlowChat::Config.session.hash_phone_numbers = true        # hash phone numbers for privacy
+FlowChat::Config.session.identifier = nil                 # let platforms choose (default)
+
+# Available boundary options:
+# :flow - separate sessions per flow class
+# :platform - separate sessions per platform (ussd, whatsapp)  
+# :gateway - separate sessions per gateway
+# [] - global sessions (no boundaries)
+
+# Available identifier options:
+# nil - platform chooses default (:request_id for USSD, :msisdn for WhatsApp)
+# :msisdn - use phone number (durable sessions)
+# :request_id - use request ID (ephemeral sessions)
+```
+
 ## USSD Configuration
 
 ```ruby
@@ -28,10 +48,6 @@ FlowChat::Config.ussd.pagination_next_option = "#"        # option to go to next
 FlowChat::Config.ussd.pagination_next_text = "More"       # text for next option
 FlowChat::Config.ussd.pagination_back_option = "0"        # option to go back
 FlowChat::Config.ussd.pagination_back_text = "Back"       # text for back option
-
-# Resumable sessions
-FlowChat::Config.ussd.resumable_sessions_enabled = true   # default
-FlowChat::Config.ussd.resumable_sessions_timeout_seconds = 300  # 5 minutes
 ```
 
 ## WhatsApp Configuration
@@ -174,8 +190,15 @@ processor = FlowChat::Ussd::Processor.new(self) do |config|
   # Optional middleware
   config.use_middleware MyCustomMiddleware
   
-  # Optional resumable sessions
-  config.use_resumable_sessions
+  # Configure session boundaries
+  config.use_session_config(
+    boundaries: [:flow, :platform],     # which boundaries to enforce
+    hash_phone_numbers: true,           # hash phone numbers for privacy
+    identifier: :msisdn                 # use MSISDN for durable sessions (optional)
+  )
+  
+  # Shorthand for durable sessions (identifier: :msisdn)
+  config.use_durable_sessions
 end
 ```
 

data/docs/sessions.md

@@ -0,0 +1,433 @@
+# Session Management
+
+FlowChat provides a powerful and flexible session management system that enables persistent conversational state across multiple requests. This document covers the architecture, configuration, and best practices for session management.
+
+## Overview
+
+Sessions in FlowChat store user conversation state between requests, enabling:
+
+- **Multi-step workflows** - Collect information across multiple prompts
+- **Context preservation** - Remember user inputs and conversation history
+- **Cross-platform consistency** - Same session behavior across USSD and WhatsApp
+- **Privacy protection** - Automatic phone number hashing for security
+- **Flexible isolation** - Control session boundaries per deployment needs
+
+## Architecture
+
+The session system is built around three core components:
+
+### 1. Session Configuration (`FlowChat::Config::SessionConfig`)
+
+Controls how session IDs are generated and sessions are isolated:
+
+```ruby
+# Global session configuration
+FlowChat::Config.session.boundaries = [:flow, :gateway, :platform]  # isolation boundaries
+FlowChat::Config.session.hash_phone_numbers = true                   # privacy protection
+FlowChat::Config.session.identifier = nil                            # platform chooses default
+```
+
+### 2. Session Middleware (`FlowChat::Session::Middleware`)
+
+Automatically manages session creation and ID generation based on configuration:
+
+- Generates consistent session IDs based on boundaries and identifiers
+- Creates session store instances for each request
+- Handles platform-specific defaults (USSD = ephemeral, WhatsApp = durable)
+- Provides instrumentation events for monitoring
+
+### 3. Session Stores
+
+Store actual session data with different persistence strategies:
+
+- **`FlowChat::Session::CacheSessionStore`** - Uses Rails cache (recommended)
+- **`FlowChat::Session::RailsSessionStore`** - Uses Rails session (limited)
+
+## Session Boundaries
+
+Boundaries control how session IDs are constructed, determining when sessions are shared vs. isolated:
+
+### Available Boundaries
+
+- **`:flow`** - Separate sessions per flow class
+- **`:platform`** - Separate sessions per platform (ussd, whatsapp)
+- **`:gateway`** - Separate sessions per gateway
+- **`:url`** - Separate sessions per request URL (host + path)
+- **`[]`** - Global sessions (no boundaries)
+
+### Examples
+
+```ruby
+# Default: Full isolation
+FlowChat::Config.session.boundaries = [:flow, :gateway, :platform]
+# Session ID: "registration_flow:nalo:ussd:abc123"
+
+# Flow isolation only
+FlowChat::Config.session.boundaries = [:flow]
+# Session ID: "registration_flow:abc123"
+
+# Platform isolation only
+FlowChat::Config.session.boundaries = [:platform]
+# Session ID: "ussd:abc123"
+
+# Global sessions
+FlowChat::Config.session.boundaries = []
+# Session ID: "abc123"
+```
+
+## Session Identifiers
+
+Identifiers determine what makes a session unique:
+
+### Available Identifiers
+
+- **`nil`** - Platform chooses default (recommended)
+  - USSD: `:request_id` (ephemeral sessions)
+  - WhatsApp: `:msisdn` (durable sessions)
+- **`:msisdn`** - Use phone number (durable sessions)
+- **`:request_id`** - Use request ID (ephemeral sessions)
+
+### Platform Defaults
+
+```ruby
+# USSD: ephemeral sessions by default
+identifier: :request_id
+# New session each time USSD times out
+
+# WhatsApp: durable sessions by default  
+identifier: :msisdn
+# Same session resumes across conversations
+```
+
+### Phone Number Hashing
+
+When using `:msisdn` identifier, phone numbers are automatically hashed for privacy:
+
+```ruby
+FlowChat::Config.session.hash_phone_numbers = true  # default
+# "+256700123456" becomes "a1b2c3d4" (8-character hash)
+
+FlowChat::Config.session.hash_phone_numbers = false
+# "+256700123456" used directly (not recommended for production)
+```
+
+## Configuration Examples
+
+### Basic USSD Configuration
+
+```ruby
+processor = FlowChat::Ussd::Processor.new(self) do |config|
+  config.use_gateway FlowChat::Ussd::Gateway::Nalo
+  config.use_session_store FlowChat::Session::CacheSessionStore
+  
+  # Use shorthand for standard durable sessions
+  config.use_durable_sessions
+end
+```
+
+### Custom Session Configuration
+
+```ruby
+processor = FlowChat::Ussd::Processor.new(self) do |config|
+  config.use_gateway FlowChat::Ussd::Gateway::Nalo
+  config.use_session_store FlowChat::Session::CacheSessionStore
+  
+  # Explicit session configuration
+  config.use_session_config(
+    boundaries: [:flow, :platform],     # isolate by flow and platform
+    hash_phone_numbers: true,           # hash phone numbers for privacy
+    identifier: :msisdn                 # use phone number for durable sessions
+  )
+end
+```
+
+### Cross-gateway Sessions
+
+```ruby
+processor = FlowChat::Ussd::Processor.new(self) do |config|
+  config.use_gateway FlowChat::Ussd::Gateway::Nalo
+  config.use_session_store FlowChat::Session::CacheSessionStore
+  
+  # Allow sessions to work across different gateways
+  config.use_session_config(boundaries: [:flow, :platform])
+end
+```
+
+### Cross-Platform Sessions
+
+```ruby
+processor = FlowChat::Ussd::Processor.new(self) do |config|
+  config.use_gateway FlowChat::Ussd::Gateway::Nalo
+  config.use_session_store FlowChat::Session::CacheSessionStore
+  
+  # Allow same user to continue on USSD or WhatsApp
+  config.use_cross_platform_sessions
+  # Equivalent to: boundaries: [:flow]
+end
+```
+
+### URL-Based Session Isolation
+
+Perfect for multi-tenant applications:
+
+```ruby
+processor = FlowChat::Ussd::Processor.new(self) do |config|
+  config.use_gateway FlowChat::Ussd::Gateway::Nalo
+  config.use_session_store FlowChat::Session::CacheSessionStore
+  
+  # Isolate sessions by URL (great for multi-tenant SaaS)
+  config.use_url_isolation
+  # Adds :url to existing boundaries
+end
+```
+
+**URL Boundary Examples:**
+- `tenant1.example.com/ussd` vs `tenant2.example.com/ussd` - Different sessions
+- `api.example.com/v1/ussd` vs `api.example.com/v2/ussd` - Different sessions  
+- `dev.example.com/ussd` vs `prod.example.com/ussd` - Different sessions
+
+**URL Processing:**
+- Combines host + path: `example.com/api/v1/ussd`
+- Sanitizes special characters: `tenant-1.com/ussd` → `tenant_1.com/ussd`
+- Hashes long URLs (>50 chars): `verylongdomain.../path` → `url_a1b2c3d4`
+
+### Global Sessions
+
+```ruby
+processor = FlowChat::Ussd::Processor.new(self) do |config|
+  config.use_gateway FlowChat::Ussd::Gateway::Nalo
+  config.use_session_store FlowChat::Session::CacheSessionStore
+  
+  # Single session shared across everything
+  config.use_session_config(boundaries: [])
+end
+```
+
+## Session Stores
+
+### Cache Session Store (Recommended)
+
+Uses Rails cache backend with automatic TTL management:
+
+```ruby
+config.use_session_store FlowChat::Session::CacheSessionStore
+
+# Requires Rails cache to be configured
+# config/environments/production.rb
+config.cache_store = :redis_cache_store, { url: ENV['REDIS_URL'] }
+```
+
+**Features:**
+- Automatic session expiration via cache TTL
+- Redis/Memcached support for distributed deployments
+- High performance
+- Memory efficient
+
+### Rails Session Store
+
+Uses Rails session for storage (limited scope):
+
+```ruby
+config.use_session_store FlowChat::Session::RailsSessionStore
+```
+
+**Limitations:**
+- Tied to HTTP session lifecycle
+- Limited storage capacity
+- Not suitable for long-running conversations
+
+## Session Data Usage
+
+### In Flows
+
+Sessions are automatically available in flows:
+
+```ruby
+class RegistrationFlow < FlowChat::Flow
+  def main_page
+    # Store data
+    app.session.set("step", "registration")
+    app.session.set("user_data", {name: "John", age: 25})
+    
+    # Retrieve data
+    step = app.session.get("step")
+    user_data = app.session.get("user_data")
+    
+    # Check existence
+    if app.session.get("completed")
+      app.say "Registration already completed!"
+      return
+    end
+    
+    # Continue flow...
+    name = app.screen(:name) { |prompt| prompt.ask "Name?" }
+    app.session.set("name", name)
+  end
+end
+```
+
+### Session Store API
+
+All session stores implement a consistent interface:
+
+```ruby
+# Basic operations
+session.set(key, value)          # Store data
+value = session.get(key)         # Retrieve data
+session.delete(key)              # Delete specific key
+session.clear                    # Clear all session data
+session.destroy                  # Destroy entire session
+
+# Utility methods
+session.exists?                  # Check if session has any data
+```
+
+## Best Practices
+
+### 1. Choose Appropriate Boundaries
+
+```ruby
+# High-traffic public services
+boundaries: [:flow, :gateway, :platform]  # Full isolation
+
+# Single-tenant applications
+boundaries: [:flow]  # Simpler, allows cross-platform
+
+# Global state services (rare)
+boundaries: []  # Shared state across everything
+```
+
+### 2. Consider Session Lifecycle
+
+```ruby
+# USSD: Short sessions, frequent timeouts
+identifier: :request_id  # New session each timeout (default)
+
+# WhatsApp: Long conversations, persistent
+identifier: :msisdn     # Resume across days/weeks (default)
+
+# Custom requirements
+identifier: :msisdn     # Make USSD durable
+identifier: :request_id # Make WhatsApp ephemeral
+```
+
+### 3. Handle Session Expiration
+
+```ruby
+class RegistrationFlow < FlowChat::Flow
+  def main_page
+    # Check if session expired
+    if app.session.get("user_id").nil?
+      restart_registration
+      return
+    end
+    
+    # Continue existing session
+    continue_registration
+  end
+  
+  private
+  
+  def restart_registration
+    app.say "Session expired. Let's start over."
+    # Reset flow to beginning
+  end
+end
+```
+
+### 4. Optimize Session Data
+
+```ruby
+# Store only necessary data
+app.session.set("user_id", 123)           # Good: minimal data
+app.session.set("user", user_object)      # Avoid: large objects
+
+# Clean up when done
+def complete_registration
+  app.session.set("completed", true)
+  app.session.delete("temp_data")  # Clean up temporary data
+end
+```
+
+### 5. Security Considerations
+
+```ruby
+# Always hash phone numbers in production
+FlowChat::Config.session.hash_phone_numbers = true
+
+# Use secure cache backends
+config.cache_store = :redis_cache_store, {
+  url: ENV['REDIS_URL'],
+  ssl_params: { verify_mode: OpenSSL::SSL::VERIFY_NONE }
+}
+
+# Set appropriate TTLs
+cache_options = { expires_in: 30.minutes }  # Reasonable session timeout
+```
+
+## Troubleshooting
+
+### Session Not Persisting
+
+1. **Check session store configuration:**
+   ```ruby
+   # Ensure session store is configured
+   config.use_session_store FlowChat::Session::CacheSessionStore
+   ```
+
+2. **Verify cache backend:**
+   ```ruby
+   # Test cache is working
+   Rails.cache.write("test", "value")
+   puts Rails.cache.read("test")  # Should output "value"
+   ```
+
+3. **Check session boundaries:**
+   ```ruby
+   # Debug session ID generation
+   FlowChat.logger.level = Logger::DEBUG
+   # Look for "Session::Middleware: Generated session ID: ..." messages
+   ```
+
+### Different Session IDs
+
+1. **Inconsistent request data:**
+   - Verify `request.gateway` is consistent
+   - Check `request.platform` is set correctly
+   - Ensure `request.msisdn` format is consistent
+
+2. **Boundary configuration mismatch:**
+   ```ruby
+   # Ensure same boundaries across requests
+   config.use_session_config(boundaries: [:flow, :platform])
+   ```
+
+### Session Data Lost
+
+1. **Cache expiration:**
+   ```ruby
+   # Increase TTL if needed
+   FlowChat::Config.cache = Rails.cache
+   # Configure longer expiration in cache store
+   ```
+
+2. **Session ID changes:**
+   - Check logs for "Generated session ID" messages
+   - Verify identifier consistency (`:msisdn` vs `:request_id`)
+
+## Monitoring and Instrumentation
+
+FlowChat emits events for session operations:
+
+```ruby
+# Subscribe to session events
+ActiveSupport::Notifications.subscribe("session.created.flow_chat") do |event|
+  Rails.logger.info "Session created: #{event.payload[:session_id]}"
+end
+
+# Monitor session usage
+ActiveSupport::Notifications.subscribe(/session\..*\.flow_chat/) do |name, start, finish, id, payload|
+  # Track session operations for analytics
+  Analytics.track("flowchat.session.#{name.split('.')[1]}", payload)
+end
+```

data/docs/testing.md

@@ -43,7 +43,7 @@ class SimulatorController < ApplicationController
         name: "USSD Integration",
         icon: "📱", 
         processor_type: "ussd",
-        provider: "nalo",
+        gateway: "nalo",
         endpoint: "/ussd",
         color: "#007bff"
       },
@@ -51,7 +51,7 @@ class SimulatorController < ApplicationController
         name: "WhatsApp Integration",
         icon: "💬",
         processor_type: "whatsapp", 
-        provider: "cloud_api",
+        gateway: "cloud_api",
         endpoint: "/whatsapp/webhook",
         color: "#25D366"
       }

data/docs/ussd-setup.md

@@ -119,19 +119,35 @@ Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor i
 0 Back
 ```
 
-## Resumable Sessions
+## Session Management
 
-Enable resumable sessions for better user experience:
+Configure session behavior for better user experience:
 
 ```ruby
 processor = FlowChat::Ussd::Processor.new(self) do |config|
   config.use_gateway FlowChat::Ussd::Gateway::Nalo
   config.use_session_store FlowChat::Session::CacheSessionStore
-  config.use_resumable_sessions  # Enable resumable sessions
+  
+  # Enable durable sessions (shorthand)
+  config.use_durable_sessions
 end
 ```
 
-Users can continue interrupted conversations within the timeout period.
+### Session Boundaries
+
+Session boundaries control how session IDs are constructed:
+
+- **`:flow`** - Separate sessions per flow class
+- **`:platform`** - Separate USSD from WhatsApp sessions  
+- **`:gateway`** - Separate sessions per gateway
+- **`[]`** - Global sessions (no boundaries)
+
+Session identifier options:
+
+- **`nil`** - Platform chooses default (`:request_id` for USSD, `:msisdn` for WhatsApp)
+- **`:msisdn`** - Use phone number (durable sessions)
+- **`:request_id`** - Use request ID (ephemeral sessions)
+- **`hash_phone_numbers`** - Hash phone numbers for privacy (recommended)
 
 ## Middleware
 

data/examples/simulator_controller.rb

@@ -17,7 +17,7 @@ class SimulatorController < ApplicationController
         name: "Main USSD Endpoint",
         description: "Primary USSD integration",
         processor_type: "ussd",
-        provider: "nalo",
+        gateway: "nalo",
         endpoint: "/ussd",
         icon: "📱",
         color: "#28a745"
@@ -26,7 +26,7 @@ class SimulatorController < ApplicationController
         name: "Main WhatsApp Endpoint",
         description: "Primary WhatsApp webhook",
         processor_type: "whatsapp",
-        provider: "cloud_api",
+        gateway: "cloud_api",
         endpoint: "/whatsapp/webhook",
         icon: "💬",
         color: "#25D366"
@@ -35,7 +35,7 @@ class SimulatorController < ApplicationController
         name: "Tenant A WhatsApp",
         description: "Multi-tenant endpoint for Tenant A",
         processor_type: "whatsapp",
-        provider: "cloud_api",
+        gateway: "cloud_api",
         endpoint: "/tenants/a/whatsapp/webhook",
         icon: "🏢",
         color: "#fd7e14"
@@ -44,7 +44,7 @@ class SimulatorController < ApplicationController
         name: "Legacy WhatsApp",
         description: "Legacy endpoint for compatibility",
         processor_type: "whatsapp",
-        provider: "cloud_api",
+        gateway: "cloud_api",
         endpoint: "/legacy/whatsapp",
         icon: "📦",
         color: "#6c757d"

data/examples/ussd_controller.rb

@@ -10,8 +10,8 @@ class UssdController < ApplicationController
       # Use Rails session for USSD (shorter sessions)
       config.use_session_store FlowChat::Session::RailsSessionStore
 
-      # Enable resumable sessions (optional)
-      config.use_resumable_sessions
+      # Enable durable sessions (optional)
+      config.use_durable_sessions  # Configures flow+platform isolation with durable sessions
     end
 
     processor.run WelcomeFlow, :main_page
@@ -232,7 +232,13 @@ class UssdController < ApplicationController
       config.use_gateway FlowChat::Ussd::Gateway::Nalo
       config.use_session_store FlowChat::Session::RailsSessionStore
       config.use_middleware LoggingMiddleware  # Add custom logging
-      config.use_resumable_sessions           # Enable resumable sessions
+      config.use_durable_sessions           # Enable durable sessions
+      
+      # Or configure session boundaries explicitly:
+      # config.use_session_config(
+      #   boundaries: [:flow, :platform],     # which boundaries to enforce
+      #   hash_phone_numbers: true            # hash phone numbers for privacy
+      # )
     end
 
     processor.run WelcomeFlow, :main_page

data/lib/flow_chat/base_processor.rb

@@ -13,6 +13,7 @@ module FlowChat
       @context["controller"] = controller
       @context["enable_simulator"] = enable_simulator.nil? ? (defined?(Rails) && Rails.env.local?) : enable_simulator
       @middleware = ::Middleware::Builder.new(name: middleware_name)
+      @session_options = FlowChat::Config.session
 
       FlowChat.logger.debug { "BaseProcessor: Simulator mode #{@context["enable_simulator"] ? "enabled" : "disabled"}" }
 
@@ -29,17 +30,46 @@ module FlowChat
     end
 
     def use_session_store(session_store)
-      FlowChat.logger.debug { "BaseProcessor: Configuring session store #{session_store.class.name}" }
+      raise "Session store must be a class" unless session_store.is_a?(Class)
+      FlowChat.logger.debug { "BaseProcessor: Configuring session store #{session_store.name}" }
       @context["session.store"] = session_store
       self
     end
 
+    def use_session_config(boundaries: nil, hash_phone_numbers: nil, identifier: nil)
+      FlowChat.logger.debug { "BaseProcessor: Configuring session config: boundaries=#{boundaries.inspect}, hash_phone_numbers=#{hash_phone_numbers}, identifier=#{identifier}" }
+      
+      # Update the session options directly
+      @session_options = @session_options.dup
+      @session_options.boundaries = Array(boundaries) if boundaries
+      @session_options.hash_phone_numbers = hash_phone_numbers if hash_phone_numbers
+      @session_options.identifier = identifier if identifier
+      
+      self
+    end
+
     def use_middleware(middleware)
-      FlowChat.logger.debug { "BaseProcessor: Adding middleware #{middleware.class.name}" }
+      raise "Middleware must be a class" unless middleware.is_a?(Class)
+      FlowChat.logger.debug { "BaseProcessor: Adding middleware #{middleware.name}" }
       @middleware.use middleware
       self
     end
 
+    def use_cross_platform_sessions
+      FlowChat.logger.debug { "BaseProcessor: Enabling cross-platform sessions via session configuration" }
+      use_session_config(
+        boundaries: [:flow]
+      )
+      self
+    end
+
+    def use_url_isolation
+      FlowChat.logger.debug { "BaseProcessor: Enabling URL-based session isolation" }
+      current_boundaries = @session_options.boundaries.dup
+      current_boundaries << :url unless current_boundaries.include?(:url)
+      use_session_config(boundaries: current_boundaries)
+    end
+
     def run(flow_class, action)
       # Instrument flow execution (this will log via LogSubscriber)
       instrument(Events::FLOW_EXECUTION_START, {
@@ -101,6 +131,7 @@ module FlowChat
 
       ::Middleware::Builder.new(name: name) do |b|
         b.use @gateway_class, *@gateway_args
+        b.use FlowChat::Session::Middleware, @session_options
         configure_middleware_stack(b)
       end.inject_logger(FlowChat.logger)
     end

data/lib/flow_chat/config.rb

@@ -8,6 +8,11 @@ module FlowChat
     # When false, only the validation error message is shown to the user.
     mattr_accessor :combine_validation_error_with_message, default: true
 
+    # Session configuration object
+    def self.session
+      @session ||= SessionConfig.new
+    end
+
     # USSD-specific configuration object
     def self.ussd
       @ussd ||= UssdConfig.new
@@ -18,10 +23,29 @@ module FlowChat
       @whatsapp ||= WhatsappConfig.new
     end
 
+    class SessionConfig
+      attr_accessor :boundaries, :hash_phone_numbers, :identifier
+
+      def initialize
+        # Session boundaries control how session IDs are constructed
+        # :flow = separate sessions per flow
+        # :gateway = separate sessions per gateway
+        # :platform = separate sessions per platform (ussd, whatsapp)
+        @boundaries = [:flow, :gateway, :platform]
+        
+        # Always hash phone numbers for privacy
+        @hash_phone_numbers = true
+        
+        # Session identifier type (nil = let platforms choose their default)
+        # :msisdn = durable sessions (durable across timeouts)
+        # :request_id = ephemeral sessions (new session each time)
+        @identifier = nil
+      end
+    end
+
     class UssdConfig
       attr_accessor :pagination_page_size, :pagination_back_option, :pagination_back_text,
-        :pagination_next_option, :pagination_next_text,
-        :resumable_sessions_enabled, :resumable_sessions_global, :resumable_sessions_timeout_seconds
+        :pagination_next_option, :pagination_next_text
 
       def initialize
         @pagination_page_size = 140
@@ -29,9 +53,6 @@ module FlowChat
         @pagination_back_text = "Back"
         @pagination_next_option = "#"
         @pagination_next_text = "More"
-        @resumable_sessions_enabled = false
-        @resumable_sessions_global = true
-        @resumable_sessions_timeout_seconds = 300
       end
     end
 

data/lib/flow_chat/session/middleware.rb

@@ -5,8 +5,9 @@ module FlowChat
 
       attr_reader :context
 
-      def initialize(app)
+      def initialize(app, session_options)
         @app = app
+        @session_options = session_options
         FlowChat.logger.debug { "Session::Middleware: Initialized session middleware" }
       end
 
@@ -19,9 +20,10 @@ module FlowChat
         context.session = context["session.store"].new(context)
 
         # Use instrumentation instead of direct logging for session creation
+        store_type = context["session.store"].name || "$Anonymous"
         instrument(Events::SESSION_CREATED, {
           session_id: session_id,
-          store_type: context["session.store"].name,
+          store_type: store_type,
           gateway: context["request.gateway"]
         })
 
@@ -40,28 +42,111 @@ module FlowChat
 
       def session_id(context)
         gateway = context["request.gateway"]
+        platform = context["request.platform"]
         flow_name = context["flow.name"]
 
-        FlowChat.logger.debug { "Session::Middleware: Building session ID for gateway=#{gateway}, flow=#{flow_name}" }
+        # Check for explicit session ID first (for manual session management)
+        if context["session.id"].present?
+          session_id = context["session.id"]
+          FlowChat.logger.debug { "Session::Middleware: Using explicit session ID: #{session_id}" }
+          return session_id
+        end
+
+        FlowChat.logger.debug { "Session::Middleware: Building session ID for platform=#{platform}, gateway=#{gateway}, flow=#{flow_name}" }
 
-        case gateway
-        when :whatsapp_cloud_api
-          # For WhatsApp, use phone number + flow name for consistent sessions
+        # Get identifier based on configuration
+        identifier = get_session_identifier(context)
+
+        # Build session ID based on configuration
+        session_id = build_session_id(flow_name, platform, gateway, identifier)
+        FlowChat.logger.debug { "Session::Middleware: Generated session ID: #{session_id}" }
+        session_id
+      end
+
+      def get_session_identifier(context)
+        identifier_type = @session_options.identifier
+        
+        # If no identifier specified, use platform defaults
+        if identifier_type.nil?
+          platform = context["request.platform"]
+          identifier_type = case platform
+          when :ussd
+            :request_id    # USSD defaults to ephemeral sessions
+          when :whatsapp
+            :msisdn       # WhatsApp defaults to durable sessions
+          else
+            :msisdn       # Default fallback to durable
+          end
+        end
+        
+        case identifier_type
+        when :request_id
+          context["request.id"]
+        when :msisdn
           phone = context["request.msisdn"]
-          session_id = "#{gateway}:#{flow_name}:#{phone}"
-          FlowChat.logger.debug { "Session::Middleware: WhatsApp session ID created for phone #{phone}" }
-          session_id
-        # when :nalo, :nsano
-        #   # For USSD, use the request ID from the gateway
-        #   "#{gateway}:#{flow_name}:#{context["request.id"]}"
+          @session_options.hash_phone_numbers ? hash_phone_number(phone) : phone
         else
-          # Fallback to request ID
-          request_id = context["request.id"]
-          session_id = "#{gateway}:#{flow_name}:#{request_id}"
-          FlowChat.logger.debug { "Session::Middleware: Generic session ID created for request #{request_id}" }
-          session_id
+          raise "Invalid session identifier type: #{identifier_type}"
         end
       end
+
+      def build_session_id(flow_name, platform, gateway, identifier)
+        parts = []
+
+        # Add flow name if flow isolation is enabled
+        parts << flow_name if @session_options.boundaries.include?(:flow)
+
+        # Add platform if platform isolation is enabled
+        parts << platform.to_s if @session_options.boundaries.include?(:platform)
+
+        # Add gateway if gateway isolation is enabled
+        parts << gateway.to_s if @session_options.boundaries.include?(:gateway)
+
+        # Add URL if URL isolation is enabled
+        if @session_options.boundaries.include?(:url)
+          url_identifier = get_url_identifier(context)
+          parts << url_identifier if url_identifier.present?
+        end
+
+        # Add the session identifier
+        parts << identifier if identifier.present?
+
+        # Join parts with colons
+        parts.join(":")
+      end
+
+      def get_url_identifier(context)
+        request = context.controller&.request
+        return nil unless request
+
+        # Extract host and path for URL boundary
+        host = request.host rescue nil
+        path = request.path rescue nil
+
+        # Create a normalized URL identifier: host + path 
+        # e.g., "example.com/api/v1/ussd" or "tenant1.example.com/ussd"
+        url_parts = []
+        url_parts << host if host.present?
+        url_parts << path.sub(/^\//, '') if path.present? && path != '/'
+
+        # For long URLs, use first part + hash suffix instead of full hash
+        url_identifier = url_parts.join('/').gsub(/[^a-zA-Z0-9._-]/, '_')
+        if url_identifier.length > 50
+          require 'digest'
+          # Take first 41 chars + hash suffix to keep it manageable but recognizable
+          first_part = url_identifier[0, 41]
+          hash_suffix = Digest::SHA256.hexdigest(url_identifier)[0, 8]
+          url_identifier = "#{first_part}_#{hash_suffix}"
+        end
+
+        url_identifier
+      end
+
+      def hash_phone_number(phone)
+        # Use SHA256 but only take first 8 characters for reasonable session IDs
+        require 'digest'
+        Digest::SHA256.hexdigest(phone.to_s)[0, 8]
+      end
     end
   end
 end

data/lib/flow_chat/simulator/controller.rb

@@ -32,7 +32,7 @@ module FlowChat
             name: "USSD (Nalo)",
             description: "USSD integration using Nalo",
             processor_type: "ussd",
-            provider: "nalo",
+            gateway: "nalo",
             endpoint: "/ussd",
             icon: "📱",
             color: "#28a745",
@@ -45,7 +45,7 @@ module FlowChat
             name: "WhatsApp (Cloud API)",
             description: "WhatsApp integration using Cloud API",
             processor_type: "whatsapp",
-            provider: "cloud_api",
+            gateway: "cloud_api",
             endpoint: "/whatsapp/webhook",
             icon: "💬",
             color: "#25D366",

data/lib/flow_chat/simulator/views/simulator.html.erb

@@ -1057,8 +1057,8 @@
             <span class="config-detail-value">${config.endpoint}</span>
           </div>
           <div class="config-detail-item">
-            <span class="config-detail-label">Provider:</span>
-            <span class="config-detail-value">${config.provider}</span>
+            <span class="config-detail-label">gateway:</span>
+            <span class="config-detail-value">${config.gateway}</span>
           </div>
           <div class="config-detail-item">
             <span class="config-detail-label">Type:</span>
@@ -1304,7 +1304,7 @@
         
         let requestData = {}
         
-        switch (config.provider) {
+        switch (config.gateway) {
           case 'nalo':
             requestData = {
               USERID: state.sessionId,
@@ -1322,7 +1322,7 @@
             }
             break
           default:
-            throw new Error(`Unsupported USSD provider: ${config.provider}`)
+            throw new Error(`Unsupported USSD gateway: ${config.gateway}`)
         }
         
         try {
@@ -1342,7 +1342,7 @@
             throw new Error(`HTTP ${response.status}: ${response.statusText}`)
           }
           
-          switch (config.provider) {
+          switch (config.gateway) {
             case 'nalo':
               displayUSSDResponse(data.MSG)
               state.isRunning = data.MSGTYPE

data/lib/flow_chat/ussd/gateway/nalo.rb

@@ -20,6 +20,7 @@ module FlowChat
           context["request.message_id"] = SecureRandom.uuid
           context["request.timestamp"] = Time.current.iso8601
           context["request.gateway"] = :nalo
+          context["request.platform"] = :ussd
           context["request.network"] = nil
           context["request.msisdn"] = Phonelib.parse(params["MSISDN"]).e164
           # context["request.type"] = params["MSGTYPE"] ? :initial : :response

data/lib/flow_chat/ussd/gateway/nsano.rb

@@ -22,6 +22,7 @@ module FlowChat
 
           # Set a basic message_id (can be enhanced based on actual Nsano implementation)
           context["request.message_id"] = SecureRandom.uuid
+          context["request.platform"] = :ussd
 
           # TODO: Implement Nsano-specific parameter parsing
           # For now, add basic instrumentation structure for when this is implemented
@@ -58,7 +59,7 @@ module FlowChat
           #   if params["network"].present? && params["UserSessionID"].present?
           #     request_id = "nsano::request_id::#{params["UserSessionID"]}"
           #     context["ussd.request"] = {
-          #       provider: :nsano,
+          #       gateway: :nsano,
           #       network: params["network"].to_sym,
           #       msisdn: Phonelib.parse(params["msisdn"]).e164,
           #       type: Config.cache&.read(request_id).present? ? :response : :initial,
@@ -70,7 +71,7 @@ module FlowChat
 
           # status, headers, response = @app.call(context)
 
-          # if context["ussd.response"].present? && context["ussd.request"][:provider] == :nsano
+          # if context["ussd.response"].present? && context["ussd.request"][:gateway] == :nsano
           #   if context["ussd.response"][:type] == :terminal
           #     Config.cache&.write(request_id, nil)
           #   else

data/lib/flow_chat/ussd/processor.rb

@@ -1,10 +1,11 @@
 module FlowChat
   module Ussd
     class Processor < FlowChat::BaseProcessor
-      def use_resumable_sessions
-        FlowChat.logger.debug { "Ussd::Processor: Enabling resumable sessions middleware" }
-        middleware.insert_before 0, FlowChat::Ussd::Middleware::ResumableSession
-        self
+      def use_durable_sessions(cross_gateway: false)
+        FlowChat.logger.debug { "Ussd::Processor: Enabling durable sessions via session configuration" }
+        use_session_config(
+          identifier: :msisdn  # Use MSISDN for durable sessions
+        )
       end
 
       protected
@@ -21,9 +22,6 @@ module FlowChat
       def configure_middleware_stack(builder)
         FlowChat.logger.debug { "Ussd::Processor: Configuring USSD middleware stack" }
 
-        builder.use FlowChat::Session::Middleware
-        FlowChat.logger.debug { "Ussd::Processor: Added Session::Middleware" }
-
         builder.use FlowChat::Ussd::Middleware::Pagination
         FlowChat.logger.debug { "Ussd::Processor: Added Ussd::Middleware::Pagination" }
 

data/lib/flow_chat/version.rb

@@ -1,3 +1,3 @@
 module FlowChat
-  VERSION = "0.7.0"
+  VERSION = "0.8.0"
 end

data/lib/flow_chat/whatsapp/gateway/cloud_api.rb

@@ -160,6 +160,7 @@ module FlowChat
 
             context["request.id"] = phone_number
             context["request.gateway"] = :whatsapp_cloud_api
+            context["request.platform"] = :whatsapp
             context["request.message_id"] = message_id
             context["request.msisdn"] = Phonelib.parse(phone_number).e164
             context["request.contact_name"] = contact_name

data/lib/flow_chat/whatsapp/processor.rb

@@ -20,8 +20,6 @@ module FlowChat
 
       def configure_middleware_stack(builder)
         FlowChat.logger.debug { "Whatsapp::Processor: Configuring WhatsApp middleware stack" }
-        builder.use FlowChat::Session::Middleware
-        FlowChat.logger.debug { "Whatsapp::Processor: Added Session::Middleware" }
 
         builder.use middleware
         FlowChat.logger.debug { "Whatsapp::Processor: Added custom middleware" }

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: flow_chat
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.8.0
 platform: ruby
 authors:
 - Stefan Froelich
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-06-07 00:00:00.000000000 Z
+date: 2025-06-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: zeitwerk
@@ -107,6 +107,7 @@ files:
 - docs/images/simulator.png
 - docs/instrumentation.md
 - docs/media.md
+- docs/sessions.md
 - docs/testing.md
 - docs/ussd-setup.md
 - docs/whatsapp-setup.md
@@ -139,7 +140,6 @@ files:
 - lib/flow_chat/ussd/middleware/choice_mapper.rb
 - lib/flow_chat/ussd/middleware/executor.rb
 - lib/flow_chat/ussd/middleware/pagination.rb
-- lib/flow_chat/ussd/middleware/resumable_session.rb
 - lib/flow_chat/ussd/processor.rb
 - lib/flow_chat/ussd/renderer.rb
 - lib/flow_chat/version.rb

data/lib/flow_chat/ussd/middleware/resumable_session.rb

@@ -1,39 +0,0 @@
-module FlowChat
-  module Ussd
-    module Middleware
-      class ResumableSession
-        def initialize(app)
-          @app = app
-        end
-
-        def call(context)
-          if FlowChat::Config.ussd.resumable_sessions_enabled && context["ussd.request"].present?
-            # First, try to find any interruption session.
-            # The session key can be:
-            #  - a global session (key: "global")
-            #  - a provider-specific session (key: <provider>)
-            session_key = self.class.session_key(context)
-            resumable_session = context["session.store"].get(session_key)
-
-            if resumable_session.present? && valid?(resumable_session)
-              context.merge! resumable_session
-            end
-          end
-
-          @app.call(context)
-        end
-
-        private
-
-        def valid?(session)
-          return true unless FlowChat::Config.ussd.resumable_sessions_timeout_seconds
-
-          last_active_at = Time.parse session.dig("context", "last_active_at")
-          (Time.current - FlowChat::Config.ussd.resumable_sessions_timeout_seconds) < last_active_at
-        rescue
-          false
-        end
-      end
-    end
-  end
-end