flow_chat 0.7.0 → 0.8.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1d5c2d35096c65d8953ed19fe427a61b13c7b2fabab871cc99562bde861576be
-  data.tar.gz: ee342523ae86be4397bbb0586a2a38966d473094a1d33aacb047fe26edf93c78
+  metadata.gz: abe12ed32427797b8d7c5dc79766bae76113ec62df415e495f900e4216af5c3f
+  data.tar.gz: d344431fbde29789a0013a78dd099b253b65dc9e8af90ef2d403a5592b5bb7aa
 SHA512:
-  metadata.gz: bae27cb42464181afbc3751082344d9aaa6c8d4ae6915794aa5671fec8622eb24f2d694d14a3414c11f3125c954a022a781ed91eaf4705c0314b240920434eac
-  data.tar.gz: 50fd0405af1d6e1e79ef62be8bb2e6bca81ed0d46297bf7b1ed5bbd04f0d892b30261fde9c547a523bd9003ad8612efee3aadb11f683af4af0fded396c6a2538
+  metadata.gz: b05a61d0e7a41db5ecd2137aaa193c7431f1e16277e093af4eacbcf657696aa42a22d177407718618959b021298a3583101004534d3666a51b2607b4f621db88
+  data.tar.gz: a9aab01a2754996205c2b9c1fa8143cdf503f4033c243ed537120c975249eebc0b0cc42f310864a8923b8fd819cc625205cd32463f15e5db93ccd88c2c4ecfe1

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_app.rb

@@ -0,0 +1,74 @@
+module FlowChat
+  class BaseApp
+    attr_reader :session, :input, :context, :navigation_stack
+
+    def initialize(context)
+      @context = context
+      @session = context.session
+      @input = context.input
+      @navigation_stack = []
+    end
+
+    def screen(key)
+      raise ArgumentError, "a block is expected" unless block_given?
+      raise ArgumentError, "screen has already been presented" if navigation_stack.include?(key)
+
+      navigation_stack << key
+      return session.get(key) if session.get(key).present?
+
+      user_input = prepare_user_input
+      prompt = FlowChat::Prompt.new user_input
+      @input = nil # input is being submitted to prompt so we clear it
+
+      value = yield prompt
+      session.set(key, value)
+      value
+    end
+
+    def go_back
+      return false if navigation_stack.empty?
+      
+      @context.input = nil
+      current_screen = navigation_stack.last
+      session.delete(current_screen)
+      
+      # Restart the flow from the beginning
+      raise FlowChat::Interrupt::RestartFlow.new
+    end
+
+    def say(msg, media: nil)
+      raise FlowChat::Interrupt::Terminate.new(msg, media: media)
+    end
+
+    def phone_number
+      context["request.msisdn"]
+    end
+
+    def message_id
+      context["request.message_id"]
+    end
+
+    def timestamp
+      context["request.timestamp"]
+    end
+
+    def contact_name
+      nil
+    end
+
+    def location
+      nil
+    end
+
+    def media
+      nil
+    end
+
+    protected
+
+    # Platform-specific methods to be overridden
+    def prepare_user_input
+      input
+    end
+  end
+end