flow_chat 0.9.0 → 0.10.0

data/docs/async-background-processing.md

@@ -1,298 +1,64 @@
-# Async Background Processing
+# Async and background processing
 
-FlowChat supports asynchronous background processing to decouple flow execution from webhook request-response cycles. Webhook endpoints respond immediately (< 100ms) while flows process in background jobs.
+A webhook has a response deadline. If a flow does slow work (calling the platform API, hitting your own services) the webhook can time out and the platform will retry, sometimes delivering the same message twice. Async processing acknowledges the webhook immediately and runs the flow in a background job.
 
-## Quick Start
+This works on gateways with an outbound API (WhatsApp, Telegram, HTTP, Intercom), because the job can send the reply through that API afterward. USSD cannot use it: its protocol requires the answer in the webhook response itself.
 
-### Option 1: Using Factory Pattern (Recommended)
+## Enabling it
 
-The cleanest approach uses the Factory pattern for centralized configuration:
+Call `use_async` in the processor. It has two forms.
 
-```ruby
-# config/initializers/flow_chat.rb
-FlowChat::Factory.register :whatsapp do |controller|
-  processor = FlowChat::Processor.new(controller) do |config|
-    config.use_gateway FlowChat::Whatsapp::Gateway::CloudApi
-    config.use_session_store FlowChat::Session::CacheSessionStore
-    config.use_session_config(boundaries: [:flow])
-    config.use_async(factory: :whatsapp)  # Self-referencing for async
-  end
-  processor.run(WhatsAppFlow, :start)
-end
-
-# app/controllers/webhooks_controller.rb
-class WebhooksController < ApplicationController
-  def whatsapp
-    FlowChat::Factory.execute(:whatsapp, controller: self)
-  end
-end
-```
-
-**Benefits:**
-- No custom job class needed
-- Configuration defined once in initializer
-- Works seamlessly in both webhook and background contexts
-
-See [Factory Pattern Documentation](factory-pattern.md) for more details.
-
-### Option 2: Custom Job Class
-
-For advanced use cases, create a custom job class:
+Use a factory, and let FlowChat provide the job class:
 
 ```ruby
-# app/jobs/my_flow_job.rb
-class MyFlowJob < FlowChat::AsyncJob
-  def execute(controller, **job_params)
-    # Access job params passed from use_async
-    deployment_id = job_params[:deployment_id]
-
-    # Build and run your processor
-    processor = FlowChat::Processor.new(controller) do |config|
-      config.use_gateway FlowChat::Whatsapp::Gateway::CloudApi
-      config.use_session_store FlowChat::Session::CacheSessionStore
-      config.use_session_config(boundaries: [:flow])
-    end
-
-    processor.run MyFlow, :start
-  end
-end
-
-# app/controllers/webhooks_controller.rb
-class WebhooksController < ApplicationController
-  def whatsapp
-    processor = FlowChat::Processor.new(self) do |config|
-      config.use_gateway FlowChat::Whatsapp::Gateway::CloudApi
-      config.use_session_store FlowChat::Session::CacheSessionStore
-      config.use_async MyFlowJob, deployment_id: params[:deployment_id]
-    end
-    processor.run(MyFlow, :start)
-  end
-end
+config.use_async(factory: :whatsapp)
 ```
 
-## Configuration
-
-### Session Store
-
-Use a centralized cache store e.g. `CacheSessionStore` for async processing:
+Or use your own ActiveJob subclass, with optional job params:
 
 ```ruby
-config.use_session_store FlowChat::Session::CacheSessionStore
+config.use_async(MyFlowJob, deployment_id: 123)
 ```
 
-### ActiveJob Backend
+The `factory:` form is the common one and needs no custom job class. See [factory-pattern.md](factory-pattern.md).
 
-```ruby
-# config/application.rb
-config.active_job.queue_adapter = :sidekiq  # or :resque, :delayed_job
-```
+## How it works
 
-### Queue Configuration
+The `GatewayAsyncSupport` concern, mixed into every async-capable gateway, does the detection and enqueueing.
 
-Set queue in job class:
+1. On a real webhook, the gateway calls `should_enqueue_async?`. It returns true when async is enabled, the gateway supports it (`async_supported?`), and the request is not already running in the background.
+2. If so, the gateway serializes the request (params, method, headers, host, path, body, remote ip) and enqueues the job with `perform_later(request_context: ..., **job_params)`, then returns an immediate acknowledgement to the platform.
+3. The job reconstructs a `FlowChat::BackgroundController` from the serialized request. It quacks like a Rails controller (its `render` and `head` are no-ops, its `request` is a `BackgroundRequest` rebuilt from the serialized data), so the same gateway code runs against it.
+4. Running in the background, `should_enqueue_async?` now returns false (the controller is a `BackgroundController`), so the gateway processes the flow inline and sends the reply through the platform API.
 
-```ruby
-class MyFlowJob < FlowChat::AsyncJob
-  queue_as :support_flows
+The same gateway and the same flow run in both passes. The only difference is who calls them: the webhook the first time, the job the second.
 
-  def execute(controller)
-    # ...
-  end
-end
-```
+## Custom jobs
 
-Configure priorities:
+`FlowChat::AsyncJob` is the base class. It handles reconstructing the controller in `perform`; you implement `execute(controller, **job_params)`:
 
 ```ruby
-# config/sidekiq.yml
-:queues:
-  - [critical, 2]
-  - [support_flows, 1]
-  - [default, 1]
-```
-
-## Passing Parameters to Jobs
-
-### Job Params
-
-When using custom job classes, you can pass additional parameters via `use_async`:
-
-```ruby
-# In controller
-config.use_async(MyFlowJob, deployment_id: 123, flow_name: "SupportFlow")
-
-# In job execute method
 class MyFlowJob < FlowChat::AsyncJob
   def execute(controller, **job_params)
-    deployment_id = job_params[:deployment_id]  # => 123
-    flow_name = job_params[:flow_name]          # => "SupportFlow"
-
-    # Use params for business logic
+    deployment_id = job_params[:deployment_id]
     processor = FlowChat::Processor.new(controller) do |config|
-      # ... configuration
-    end
-    processor.run(MyFlow, :start)
-  end
-end
-```
-
-**Note:** Request params (from `controller.params`) are automatically available in the background job via the reconstructed `controller.params`. Job params are for additional data specific to job execution logic.
-
-### Factory with GenericAsyncJob
-
-When using `factory:` param, additional params are ignored by `GenericAsyncJob` but can be used by the factory:
-
-```ruby
-config.use_async(factory: :whatsapp, extra_data: "value")
-# extra_data is passed to perform but not used by GenericAsyncJob
-```
-
-## Gateway Support
-
-| Gateway | Async Support | Nil Response Handling |
-|---------|--------------|----------------------|
-| WhatsApp Cloud API | ✅ | ✅ Returns silently |
-| Intercom API | ✅ | ✅ Returns silently |
-| HTTP Simple | ✅ | ✅ Returns `{type: :skip}` JSON |
-| USSD Nalo | ❌ (synchronous protocol) | ❌ Requires immediate response |
-
-### Middleware Nil Response Handling
-
-Async-capable gateways support middleware that returns `nil` instead of a response tuple. This is useful for middleware that handles responses directly (e.g., `AgentHandoffMiddleware`):
-
-```ruby
-class AgentHandoffMiddleware
-  def call(context)
-    if should_handoff_to_agent?
-      # Middleware handles response directly
-      send_to_agent(context)
-      return nil  # Signal that response was handled
+      config.use_gateway FlowChat::Whatsapp::Gateway::CloudApi
+      config.use_session_store FlowChat::Session::CacheSessionStore
+      config.use_async(MyFlowJob, deployment_id: deployment_id)
     end
-
-    @app.call(context)  # Continue to next middleware
+    processor.run(WhatsAppFlow, :start)
   end
 end
 ```
 
-When middleware returns `nil`:
-- **HTTP Simple**: Returns JSON response `{type: :skip, session_id, user_id, timestamp}`
-- **WhatsApp/Intercom**: Returns silently (message already sent by middleware)
-- **USSD**: Not supported - synchronous protocol requires immediate response
-
-**Note**: USSD cannot support middleware that returns nil because the USSD protocol requires an immediate synchronous response to every request.
-
-## How It Works
-
-### Execution Paths
-
-FlowChat's async system automatically routes requests through one of three paths:
-
-#### 1. Webhook → Async Job (async enabled, webhook context)
-
-```
-1. Webhook request arrives at controller
-2. Processor.run() called with use_async configured
-3. Gateway checks: should_enqueue_async?
-   - Not in background? ✅
-   - Async enabled? ✅
-   - Gateway supports async? ✅
-4. Gateway serializes request context:
-   - params (session_id, user_id, input, etc.)
-   - method (POST/GET)
-   - headers (Content-Type, User-Agent)
-5. Gateway enqueues job: JobClass.perform_later(request_context: {...})
-6. Gateway returns immediately (< 100ms)
-7. Background worker picks up job
-8. AsyncJob.perform creates BackgroundController from request_context
-9. User's execute() called with controller
-10. Flow processes normally with reconstructed request
-```
-
-#### 2. Background Job → Inline (async enabled, background context)
-
-```
-1. Background job executes
-2. AsyncJob.perform creates BackgroundController
-3. User's execute() creates new processor
-4. Processor.run() called
-5. Gateway checks: should_enqueue_async?
-   - Not in background? ❌ (BackgroundController detected)
-   - Async enabled? ✅
-   - Gateway supports async? ✅
-6. Gateway processes inline (prevents double-enqueueing)
-7. Flow executes, calls controller.render (no-op in background)
-8. Job completes
-```
-
-#### 3. Webhook → Inline (async not configured)
-
-```
-1. Webhook request arrives
-2. Processor.run() called without use_async
-3. Gateway checks: should_enqueue_async?
-   - Not in background? ✅
-   - Async enabled? ❌
-   - Gateway supports async? ✅
-4. Gateway processes inline
-5. Flow executes
-6. Response returned to webhook provider
-```
-
-### Key Components
+The job params you pass to `use_async` are forwarded to `execute`, so the background pass can rebuild the same processor. `FlowChat::GenericAsyncJob` is exactly this pattern wrapped around a factory, which is why the `factory:` form needs no job class of your own.
 
-**AsyncJob**
-- Base class users inherit from
-- `perform(request_context:, **job_params)` entry point
-- Creates `BackgroundController` from serialized request
-- Calls user's `execute(controller, **job_params)` method
-
-**GenericAsyncJob**
-- Built-in job that uses Factory pattern
-- Automatically used when `use_async(factory: :name)` is called
-- Executes registered factory in background context
-- Validates factory is registered before execution
-
-**BackgroundController**
-- Duck-types as Rails controller
-- Provides `request`, `params`, `render`, `head` interface
-- `params` delegates to `request.params` (mimics Rails controller)
-- `render` and `head` are no-ops in background context
-- `is_a?(FlowChat::BackgroundController)` returns true for detection
-
-**BackgroundRequest**
-- Reconstructs full Rails request interface from serialized data
-- Provides `params`, `method`, `headers`, `host`, `path`, `remote_ip` accessors
-- HTTP method predicates: `post?`, `get?`, `head?`
-- Rails compatibility methods: `request_method`, `user_agent`, `ssl?`
-- Request body support: `body` returns object with `read()` and `rewind()` methods
-- Body content is serialized from webhook and reconstructed in background
-- Returns empty hash for `cookies` (not available in background context)
-
-**GatewayAsyncSupport**
-- Concern mixed into all gateways
-- `should_enqueue_async?` decision logic
-- `in_background?` detection via `BackgroundController`
-- `enqueue_async_job` serializes and enqueues
-- `async_supported?` override for gateways like USSD
-
-### Decision Logic
-
-The gateway's `should_enqueue_async?` method checks three conditions:
-
-```ruby
-def should_enqueue_async?
-  processor = @context["processor"]
-
-  !in_background? &&                # Prevent double-enqueueing
-    processor&.async_enabled? &&    # User opted in
-    async_supported?                # Gateway allows it
-end
-```
+## ActiveJob is optional
 
-**All three must be true** to enqueue. If any condition is false, the flow processes inline.
+`FlowChat::AsyncJob` subclasses `ActiveJob::Base` when ActiveJob is available. Without ActiveJob, FlowChat falls back to a plain class, so requiring the gem does not fail; you supply the queueing yourself in that case.
 
-This ensures:
-- Background jobs never enqueue another job
-- Users explicitly opt in per processor
-- Synchronous protocols (USSD) always process inline
+## Related
 
+- [Factory pattern](factory-pattern.md)
+- [Configuration](configuration.md#async-processing)
+- [Architecture](architecture.md)