Action Pack

Active contributors: rafaelfranca, kamipo, byroot, dhh

Purpose

Action Pack is the HTTP layer of Rails. It contains two distinct sub-modules in one gem:

• Action Controller — the controller framework (filters, params, redirects, rendering).
• Action Dispatch — the routing engine, request/response wrappers, middleware stack, sessions, cookies, and integration testing.

Source: actionpack/lib/action_controller/ and actionpack/lib/action_dispatch/. Total ~28K lines of lib/ Ruby.

Directory layout

actionpack/
├── lib/
│   ├── action_controller/
│   │   ├── base.rb                 # ActionController::Base
│   │   ├── api.rb                  # ActionController::API
│   │   ├── metal.rb                # ActionController::Metal — minimal base
│   │   ├── metal/                  # Mixins (params, rendering, callbacks, etc.)
│   │   ├── form_builder.rb
│   │   ├── log_subscriber.rb
│   │   ├── railtie.rb
│   │   ├── renderer.rb
│   │   └── test_case.rb
│   └── action_dispatch/
│       ├── http/                   # Request, Response, Headers, Mime
│       ├── routing/                # The router
│       ├── routing.rb
│       ├── journey/                # The pattern matcher
│       ├── middleware/             # Cookies, sessions, exceptions, SSL, etc.
│       ├── request/                # Session, Utils
│       ├── system_test_case.rb     # Capybara integration
│       ├── system_testing/
│       └── testing/                # IntegrationTest, Assertions
├── test/
└── actionpack.gemspec

ActionController layers

graph TD
    Metal[ActionController::Metal<br/>minimal base, no defaults]
    Base[ActionController::Base<br/>HTML defaults: layouts, flash, cookies, ...]
    API[ActionController::API<br/>JSON defaults: lighter than Base]
    Metal --> Base
    Metal --> API

ActionController::Metal (actionpack/lib/action_controller/metal.rb) is a Rack-compatible class with nothing included by default. Base and API (actionpack/lib/action_controller/base.rb, api.rb) layer in features by include-ing modules from actionpack/lib/action_controller/metal/:

• actions.rb / rendering.rb — action dispatch, rendering.
• helpers.rb — view helper integration.
• flash.rb, cookies.rb (via Action Dispatch).
• request_forgery_protection.rb (CSRF).
• params_wrapper.rb (wraps params[:user] around top-level params).
• parameter_filter.rb — filtered logging.
• strong_parameters.rb — params.require(:user).permit(...).
• live.rb — server-sent events.
• streaming.rb — chunked rendering.
• instrumentation.rb — process_action.action_controller notifications.
• etag_with_template_digest.rb — automatic ETags.
• default_headers.rb, head.rb, mime_responds.rb, redirecting.rb.

Key abstractions

Constant	File	Purpose
ActionController::Base	actionpack/lib/action_controller/base.rb	Default base for HTML controllers
ActionController::API	actionpack/lib/action_controller/api.rb	Lighter base for JSON APIs
ActionController::Metal	actionpack/lib/action_controller/metal.rb	Minimal Rack-compatible controller
ActionController::Parameters	actionpack/lib/action_controller/metal/strong_parameters.rb	Strong parameters wrapper around params
ActionDispatch::Routing::RouteSet	actionpack/lib/action_dispatch/routing/route_set.rb	The router
ActionDispatch::Routing::Mapper	actionpack/lib/action_dispatch/routing/mapper.rb	The routes.rb DSL (get, resources, namespace)
ActionDispatch::Request / Response	actionpack/lib/action_dispatch/http/request.rb, response.rb	Request/response wrappers around Rack
ActionDispatch::MiddlewareStack	actionpack/lib/action_dispatch/middleware/stack.rb	Ordered Rack middleware
ActionDispatch::IntegrationTest	actionpack/lib/action_dispatch/testing/integration.rb	Full-stack request testing
ActionDispatch::SystemTestCase	actionpack/lib/action_dispatch/system_test_case.rb	Capybara-based browser testing
Journey::Routes, Journey::Path::Pattern	actionpack/lib/action_dispatch/journey/	The route-pattern matcher

Routing

config/routes.rb is evaluated against ActionDispatch::Routing::Mapper, which builds a Journey::Routes collection inside the application's RouteSet. The mapper DSL (get, resources, namespace, scope, mount) is in actionpack/lib/action_dispatch/routing/mapper.rb.

At request time, RouteSet#call matches the env against Journey::Routes and dispatches to the matching endpoint:

sequenceDiagram
    participant Rack
    participant RouteSet as ActionDispatch::Routing::RouteSet
    participant Journey
    participant Controller
    Rack->>RouteSet: env
    RouteSet->>Journey: find match for path
    Journey-->>RouteSet: route + params
    RouteSet->>Controller: ControllerClass.action(name).call(env)
    Controller-->>RouteSet: [status, headers, body]
    RouteSet-->>Rack: response

URL helpers (posts_path, user_url, etc.) are defined on RouteSet#url_helpers. They're proxied into views and controllers via the _routes accessor.

Middleware stack

actionpack/lib/action_dispatch/middleware/:

• static.rb — serves files from public/.
• executor.rb, reloader.rb — wrap requests with the Active Support executor / reloader.
• cookies.rb — request.cookie_jar, signed and encrypted cookies.
• session/ — cookie / mem_cache / cache store sessions.
• flash.rb — the flash hash.
• request_id.rb — unique request IDs (X-Request-Id).
• remote_ip.rb — IP forensics through trusted proxies.
• host_authorization.rb — protect against DNS rebinding.
• ssl.rb / assume_ssl.rb — HSTS and SSL redirects.
• show_exceptions.rb, debug_exceptions.rb, actionable_exceptions.rb, public_exceptions.rb — error pages.
• server_timing.rb — Server-Timing header.

The default stack is built in railties/lib/rails/application/default_middleware_stack.rb, which reads config.middleware to allow apps to insert / delete middleware.

Request and response

ActionDispatch::Request and ActionDispatch::Response (actionpack/lib/action_dispatch/http/request.rb and response.rb) wrap Rack's env with helpers:

• Request: params, headers, cookies, session, format, xhr?, protocol, remote_ip, query_parameters.
• Response: status, headers, body, cookies, content_type, media_type.

Mime negotiation is in actionpack/lib/action_dispatch/http/mime_type.rb and mime_negotiation.rb.

Strong parameters

ActionController::Parameters (actionpack/lib/action_controller/metal/strong_parameters.rb) wraps params with permit / require semantics. The integration with Active Model is ActiveModel::ForbiddenAttributesProtection — assigning unpermitted parameters to a model raises.

CSRF

actionpack/lib/action_controller/metal/request_forgery_protection.rb. Token generation is per-form, signed via ActiveSupport::MessageVerifier. The protect_from_forgery call is included by default in ActionController::Base.

Integration testing

ActionDispatch::IntegrationTest (actionpack/lib/action_dispatch/testing/integration.rb) drives full-stack Rack tests via get, post, follow_redirect!, etc. It composes:

• ActionDispatch::IntegrationTest::Behavior
• ActionDispatch::Assertions::ResponseAssertions
• ActionDispatch::Assertions::RoutingAssertions

System tests (ActionDispatch::SystemTestCase) drive a real browser via Capybara + Selenium. Configuration lives in actionpack/lib/action_dispatch/system_testing/.

Integration points

• Railtie: actionpack/lib/action_controller/railtie.rb and actionpack/lib/action_dispatch/railtie.rb wire the middleware stack, parameters, and helpers into Rails::Application.
• Action View: controllers include ActionView::Layouts and Rendering to integrate template rendering. The view context is created per-request from the controller.
• Active Job: ActiveJob::Railtie registers job-specific middleware on the Rack stack via Action Dispatch (e.g., for Mission Control).
• Active Record: the connection pool is reset between requests by ActiveRecord::QueryCache and ActiveRecord::ConnectionAdapters::ConnectionManagement, which sit in the middleware stack.
• Active Storage / Action Text: both register routes via engines that mount inside the host application's RouteSet.

Entry points for modification

• Adding a controller mixin: add a module under actionpack/lib/action_controller/metal/, then include it from Base and/or API. Tests under actionpack/test/controller/.
• Adding routing DSL: edit actionpack/lib/action_dispatch/routing/mapper.rb. Tests under actionpack/test/dispatch/routing_test.rb (the largest test file in the repo at 5.3K lines).
• Adding middleware: new file in actionpack/lib/action_dispatch/middleware/ plus an entry in railties/lib/rails/application/default_middleware_stack.rb.
• Adding session storage: subclass an existing class in actionpack/lib/action_dispatch/middleware/session/ and register via config.session_store.

Related pages

• packages/action-view — templates, helpers, the view context.
• packages/railties — boot, default middleware, generators.
• features/request-lifecycle — full request walk-through.