Async Falcon Rails

Workflow

Follow these steps in order to transform a Rails application to use the async/Falcon stack:

Step 1: Update Gemfile Dependencies

Replace Puma with Falcon and add async dependencies:

bundle remove puma
bundle add falcon
bundle add async-job-processor-redis
bundle add async-job-adapter-active_job
bundle add async-cable
bundle add redis

After running these commands, verify the Gemfile includes:

• gem "falcon"
• gem "async-job-processor-redis"
• gem "async-job-adapter-active_job"
• gem "async-cable"
• gem "redis" (provides Async::Redis::Endpoint for endpoint parsing)

Step 2: Update Dockerfile for SSL Dependencies

CRITICAL: The async/Falcon stack requires OpenSSL development libraries to build properly. Without this, Docker builds will fail.

Edit the Dockerfile and add libssl-dev to the system dependencies.

Find the line that installs build packages (usually around line 40):

RUN apt-get update -qq && \
    apt-get install --no-install-recommends -y build-essential git libyaml-dev pkg-config && \
    rm -rf /var/lib/apt/lists /var/cache/apt/archives

Update it to include libssl-dev:

RUN apt-get update -qq && \
    apt-get install --no-install-recommends -y build-essential git libyaml-dev libssl-dev pkg-config && \
    rm -rf /var/lib/apt/lists /var/cache/apt/archives

Why this is needed: The Falcon web server and async gems depend on native extensions that require OpenSSL headers to compile. Without libssl-dev, the Docker build will fail with compilation errors.

Step 3: Create Async Job Configuration

Create config/initializers/async_job.rb with the following content:

require "async/job"
require "async/job/processor/aggregate"
require "async/job/processor/redis"
require "async/job/processor/inline"
require "async/redis/endpoint"

Rails.application.configure do
  # Resolve Redis endpoint from REDIS_URL; fallback to localhost for dev/test.
  redis_endpoint = Async::Redis::Endpoint.parse(
    ENV.fetch("REDIS_URL") { "redis://localhost:6379/1" }
  )

  config.async_job.define_queue "default" do
    enqueue Async::Job::Processor::Aggregate
    # Ensure the job runner connects to the accessory container (or localhost in dev).
    dequeue Async::Job::Processor::Redis, endpoint: redis_endpoint
  end

  config.async_job.define_queue "local" do
    dequeue Async::Job::Processor::Inline
  end
end

This configuration:

• Sets up a "default" queue using Redis for job processing
• Parses the REDIS_URL environment variable to create a proper Redis endpoint
• Passes the endpoint to the Redis processor for both development and production
• Sets up a "local" queue for inline processing
• Uses Aggregate processor for enqueuing and Redis for dequeuing

Step 4: Update Procfile for Development

Update Procfile.dev to include the async job processor:

Add this line to the existing Procfile.dev: