Rails Learn Rails 5 by Reading Source Code
Posted at: https://github.com/gazeldx/Learn-Rails-by-Reading-Source-Code
Learn-Rails-by-Reading-Source-Code
Table of Contents
- Part 0: Before reading Rails 5 source code
- Part 1: Your app: an instance of YourProject::Application
- Part 2: config
- Part 3: Every request and response
-
Part 4: What does
$ rails serverdo?
Part 0: Before reading Rails 5 source code
1) I suggest you learn Rack http://rack.github.io/ first.
In rack, an object with call method is a rack app.
So what is the object with call method in Rails? I will answer this question in Part 1.
2) You need a good IDE which can help for debugging. I use RubyMine.
What will you learn from this tutorial?
How does Rails start your application?
How does Rails process every request?
How does Rails combine ActionController, ActionView and Routes together?
How does puma, rack, Rails work together?
What's Puma's multiple threads?
I should start with the command $ rails server, but I put this to Part 4. Because it's a little bit complex.
Part 1: Your app: an instance of YourProject::Application
Assume your Rails app's class name is YourProject::Application (defined in ./config/application.rb).
First, I will give you a piece of important code.
# ./gems/railties-5.2.2/lib/rails/commands/server/server_command.rb
module Rails
module Command
class ServerCommand < Base
def perform
# ...
Rails::Server.new(server_options).tap do |server|
# APP_PATH is '/Users/your_name/your_project/config/application'.
# require APP_PATH will create the 'Rails.application' object.
# Actually, 'Rails.application' is an instance of `YourProject::Application`.
# Rack server will start 'Rails.application'.
require APP_PATH
Dir.chdir(Rails.application.root)
server.start
end
end
end
end
class Server < ::Rack::Server
def start
#...
# 'wrapped_app' will get an well prepared app from `./config.ru` file.
# 'wrapped_app' will return an instance of `YourProject::Application`.
# But the instance of `YourProject::Application` returned is not created in 'wrapped_app'.
# It has been created when `require APP_PATH` in previous code:
# in Rails::Command::ServerCommand#perform
wrapped_app
super # Will invoke ::Rack::Server#start.
end
end
end
A rack server need to start with an App object. The App object should have a call method.
config.ru is the conventional entry file for rack app. So let's look at it.
# ./config.ru
require_relative 'config/environment'
run Rails.application # It seems that this is the app.
Let's test it by Rails.application.respond_to?(:call), it returns true.
Let's step into Rails.application.
# ./gems/railties-5.2.2/lib/rails.rb
module Rails
class << self
@application = @app_class = nil
attr_accessor :app_class
# Oh, 'application' is a class method for module 'Rails'. It is not an object.
# But it returns an object which is an instance of 'app_class'.
# So it is important for us to know what class 'app_class' is.
def application
@application ||= (app_class.instance if app_class)
end
end
end
Because Rails.application.respond_to?(:call) returns true, app_class.instance has a call method.
When was app_class set?
module Rails
class Application < Engine
class << self
def inherited(base) # This is a hooked method.
Rails.app_class = base # This line set the 'app_class'.
end
end
end
end
Rails::Application is inherited by YourProject,
# ./config/application.rb
module YourProject
# The hooked method `inherited` will be invoked here.
class Application < Rails::Application
end
end
So YourProject::Application is the Rails.app_class here.
You may have a question: When does Rails execute the code in ./config/application.rb?
To answer this question, we need to look back to config.ru.
# ./config.ru
require_relative 'config/environment' # Let's step into this line.
run Rails.application # It seems that this is the app.
# ./config/environment.rb
# Load the Rails application.
require_relative 'application' # Let's step into this line.
# Initialize the Rails application.
Rails.application.initialize!
# ./config/application.rb
require_relative 'boot'
require 'rails/all'
# Require the gems listed in Gemfile, including any gems
# you've limited to :test, :development, or :production.
Bundler.require(*Rails.groups)
module YourProject
# The hooked method `inherited` will be invoked here.
class Application < Rails::Application
config.load_defaults 5.2
config.i18n.default_locale = :zh
end
end
Because YourProject::Application is Rails.app_class, app_class.instance is YourProject::Application.instance.
But where is the call method?
call method should be a method of YourProject::Application.instance.
The call method processes every request. Here it is.
# ./gems/railties/lib/rails/engine.rb
module Rails
class Engine < Railtie
def call(env) # This method will process every request. It is invoked by Rack. So it is very important.
req = build_request env
app.call req.env # We will discuss the 'app' object later.
end
end
end
# ./gems/railties/lib/rails/application.rb
module Rails
class Application < Engine
end
end
# ./config/application.rb
module YourProject
class Application < Rails::Application
end
end
Ancestor's chain is YourProject::Application < Rails::Application < Rails::Engine < Rails::Railtie.
So YourProject::Application.new.respond_to?(:call) returns true.
But what does app_class.instance really do?
instance is just a method name. What we really expects is something like app_class.new.
Let's look at the definition of instance.
# ./gems/railties/lib/rails/application.rb
module Rails
class Application < Engine
def instance
super.run_load_hooks! # This line confused me at the beginning.
end
end
end
After a deep research, I realized that this code is equal to:
def instance
return_value = super # Keyword 'super' means call the ancestor's same name method: 'instance'.
return_value.run_load_hooks!
end
# ./gems/railties/lib/rails/railtie.rb
module Rails
class Railtie
def instance
# 'Rails::Railtie' is the top ancestor class.
# Now 'app_class.instance' is 'YourProject::Application.new'.
@instance ||= new
end
end
end
module Rails
def application
@application ||= (app_class.instance if app_class)
end
end
So YourProject::Application.new is Rails.application.
Rack server will start Rails.application in the end.
Rails.application is an important object in Rails.
And you'll only have one Rails.application in one puma process.
Multiple threads in a puma process shares the Rails.application.
Part 2: config
The first time we see the config is in ./config/application.rb.
# ./config/application.rb
#...
module YourProject
class Application < Rails::Application
# Actually, `config` is a method of `YourProject::Application`.
# It is defined in it's grandfather's father: `Rails::Railtie`
config.load_defaults 5.2 # Let's step into this line to see what is config.
config.i18n.default_locale = :zh
end
end
module Rails
class Railtie
class << self
# Method `:config` is defined here.
# Actually, method `:config` is delegated to another object `:instance`.
delegate :config, to: :instance
# Call `YourProject::Application.config` will actually call `YourProject::Application.instance.config`
def instance
# return an instance of `YourProject::Application`.
# Call `YourProject::Application.config` will actually call `YourProject::Application.new.config`
@instance ||= new
end
end
end
class Engine < Railtie
end
class Application < Engine
class << self
def instance
# 'super' will call `:instance` method in `Railtie`,
# which will return an instance of `YourProject::Application`.
return_value = super
return_value.run_load_hooks!
end
end
def run_load_hooks!
return self if @ran_load_hooks
@ran_load_hooks = true
# ...
self # `self` is an instance of `YourProject::Application`, and `self` is `Rails.application`.
end
# This is the method `config`.
def config
# It is an instance of class `Rails::Application::Configuration`.
# Please notice that `Rails::Application` is superclass of `YourProject::Application` (self's class).
@config ||= Application::Configuration.new(self.class.find_root(self.class.called_from))
end
end
end
In the end, YourProject::Application.config === Rails.application.config returns true.
Invoke Class's config method become invoke the class's instance's config method.
module Rails
class << self
def configuration
application.config
end
end
end
So Rails.configuration === Rails.application.config returns true.
FYI:
module Rails
class Application
class Configuration < ::Rails::Engine::Configuration
end
end
class Engine
class Configuration < ::Rails::Railtie::Configuration
attr_accessor :middleware
def initialize(root = nil)
super()
#...
@middleware = Rails::Configuration::MiddlewareStackProxy.new
end
end
end
class Railtie
class Configuration
end
end
end
Part 3: Every request and response
Imagine we have this route for the home page.
# ./config/routes.rb
Rails.application.routes.draw do
root 'home#index' # HomeController#index
end
Puma
When a request is made from client, puma will process the request in Puma::Server#process_client.
If you want to know how puma enter the method Puma::Server#process_client, please read part 4 or just search 'process_client' in this document.
# ./gems/puma-3.12.0/lib/puma/server.rb
require 'socket'
module Puma
# The HTTP Server itself. Serves out a single Rack app.
#
# This class is used by the `Puma::Single` and `Puma::Cluster` classes
# to generate one or more `Puma::Server` instances capable of handling requests.
# Each Puma process will contain one `Puma::Server` instacne.
#
# The `Puma::Server` instance pulls requests from the socket, adds them to a
# `Puma::Reactor` where they get eventually passed to a `Puma::ThreadPool`.
#
# Each `Puma::Server` will have one reactor and one thread pool.
class Server
def initialize(app, events=Events.stdio, options={})
# app: #<Puma::Configuration::ConfigMiddleware:0x00007fcf1612c338
# @app = #<YourProject::Application:0x00007fcf160fb120>
# @config = #<Puma::Configuration:0x00007fcf169a6c98>
# >
@app = app
#...
end
# Given a connection on +client+, handle the incoming requests.
#
# This method support HTTP Keep-Alive so it may, depending on if the client
# indicates that it supports keep alive, wait for another request before
# returning.
#
def process_client(client, buffer)
begin
# ...
while true
# Let's step into this line.
case handle_request(client, buffer) # Will return true in this example.
when true
return unless @queue_requests
buffer.reset
ThreadPool.clean_thread_locals if clean_thread_locals
unless client.reset(@status == :run)
close_socket = false
client.set_timeout @persistent_timeout
@reactor.add client
return
end
end
end
# ...
ensure
buffer.reset
client.close if close_socket
#...
end
end
# Given the request +env+ from +client+ and a partial request body
# in +body+, finish reading the body if there is one and invoke
# the rack app. Then construct the response and write it back to
# +client+
#
def handle_request(req, lines)
env = req.env
# ...
# app: #<Puma::Configuration::ConfigMiddleware:0x00007fcf1612c338
# @app = #<YourProject::Application:0x00007fcf160fb120>
# @config = #<Puma::Configuration:0x00007fcf169a6c98>
# >
status, headers, res_body = @app.call(env) # Let's step into this line.
# ...
return keep_alive
end
end
end
# ./gems/puma-3.12.0/lib/puma/configuration.rb
module Puma
class Configuration
class ConfigMiddleware
def initialize(config, app)
@config = config
@app = app
end
def call(env)
env[Const::PUMA_CONFIG] = @config
# @app: #<YourProject::Application:0x00007fb4b1b4bcf8>
@app.call(env)
end
end
end
end
Rack apps
As we see when Ruby enter Puma::Configuration::ConfigMiddleware#call, the @app is YourProject::Application instance.
It is just the Rails.application.
Rack need a call method to process request.
Rails defined this call method in Rails::Engine#call, so that YourProject::Application instance will have a call method.
# ./gems/railties/lib/rails/engine.rb
module Rails
class Engine < Railtie
def call(env) # This method will process every request. It is invoked by Rack.
req = build_request env
app.call req.env # The 'app' method is blow.
end
def app
# FYI,
# caller: [
# "../gems/railties-5.2.2/lib/rails/application/finisher.rb:47:in `block in <module:Finisher>'",
# "../gems/railties-5.2.2/lib/rails/initializable.rb:32:in `instance_exec'",
# "../gems/railties-5.2.2/lib/rails/initializable.rb:32:in `run'",
# "../gems/railties-5.2.2/lib/rails/initializable.rb:63:in `block in run_initializers'",
# "../ruby-2.6.0/lib/ruby/2.6.0/tsort.rb:228:in `block in tsort_each'",
# "../ruby-2.6.0/lib/ruby/2.6.0/tsort.rb:350:in `block (2 levels) in each_strongly_connected_component'",
# "../ruby-2.6.0/lib/ruby/2.6.0/tsort.rb:431:in `each_strongly_connected_component_from'",
# "../ruby-2.6.0/lib/ruby/2.6.0/tsort.rb:349:in `block in each_strongly_connected_component'",
# "../ruby-2.6.0/lib/ruby/2.6.0/tsort.rb:347:in `each'",
# "../ruby-2.6.0/lib/ruby/2.6.0/tsort.rb:347:in `call'",
# "../ruby-2.6.0/lib/ruby/2.6.0/tsort.rb:347:in `each_strongly_connected_component'",
# "../ruby-2.6.0/lib/ruby/2.6.0/tsort.rb:226:in `tsort_each'",
# "../ruby-2.6.0/lib/ruby/2.6.0/tsort.rb:205:in `tsort_each'",
# "../gems/railties-5.2.2/lib/rails/initializable.rb:61:in `run_initializers'",
# "../gems/railties-5.2.2/lib/rails/application.rb:361:in `initialize!'",
# "/Users/lanezhang/projects/mine/free-erp/config/environment.rb:5:in `<top (required)>'",
# "config.ru:2:in `require_relative'", "config.ru:2:in `block in <main>'",
# "../gems/rack-2.0.6/lib/rack/builder.rb:55:in `instance_eval'",
# "../gems/rack-2.0.6/lib/rack/builder.rb:55:in `initialize'",
# "config.ru:in `new'", "config.ru:in `<main>'",
# "../gems/rack-2.0.6/lib/rack/builder.rb:49:in `eval'",
# "../gems/rack-2.0.6/lib/rack/builder.rb:49:in `new_from_string'",
# "../gems/rack-2.0.6/lib/rack/builder.rb:40:in `parse_file'",
# "../gems/rack-2.0.6/lib/rack/server.rb:320:in `build_app_and_options_from_config'",
# "../gems/rack-2.0.6/lib/rack/server.rb:219:in `app'",
# "../gems/railties-5.2.2/lib/rails/commands/server/server_command.rb:27:in `app'",
# "../gems/rack-2.0.6/lib/rack/server.rb:357:in `wrapped_app'",
# "../gems/railties-5.2.2/lib/rails/commands/server/server_command.rb:92:in `log_to_stdout'",
# "../gems/railties-5.2.2/lib/rails/commands/server/server_command.rb:54:in `start'",
# "../gems/railties-5.2.2/lib/rails/commands/server/server_command.rb:149:in `block in perform'",
# "../gems/railties-5.2.2/lib/rails/commands/server/server_command.rb:144:in `tap'",
# "../gems/railties-5.2.2/lib/rails/commands/server/server_command.rb:144:in `perform'",
# "../gems/thor-0.20.3/lib/thor/command.rb:27:in `run'",
# "../gems/thor-0.20.3/lib/thor/invocation.rb:126:in `invoke_command'",
# "../gems/thor-0.20.3/lib/thor.rb:391:in `dispatch'",
# "../gems/railties-5.2.2/lib/rails/command/base.rb:65:in `perform'",
# "../gems/railties-5.2.2/lib/rails/command.rb:46:in `invoke'",
# "../gems/railties-5.2.2/lib/rails/commands.rb:18:in `<top (required)>'",
# "../path/to/your_project/bin/rails:5:in `require'",
# "../path/to/your_project/bin/rails:5:in `<main>'"
# ]
puts "caller: #{caller.inspect}"
# You may want to know when is the @app first time initialized.
# It is initialized when 'config.ru' is load by rack server.
# Please search `Rack::Server#build_app_and_options_from_config` in this document for more information.
# When `Rails.application.initialize!` (in ./config/environment.rb) executed, @app is initialized.
@app || @app_build_lock.synchronize { # '@app_build_lock = Mutex.new', so multiple threads share one '@app'.
@app ||= begin
# In the end, config.middleware will be an instance of ActionDispatch::MiddlewareStack with preset instance variable @middlewares (which is an Array).
stack = default_middleware_stack # Let's step into this line
# 'middleware' is a 'middleware_stack'!
config.middleware = build_middleware.merge_into(stack)
# FYI, this line is the last line and the result of this line is the return value for @app.
config.middleware.build(endpoint) # look at this endpoint below. We will enter method `build` later.
end
}
# @app: #<Rack::Sendfile:0x00007ff14d905f60
# @app=#<ActionDispatch::Static:0x00007ff14d906168
# @app=#<ActionDispatch::Executor:0x00007ff14d9061b8
# ...
# @app=#<Rack::ETag:0x00007fa1e540c4f8
# @app=#<Rack::TempfileReaper:0x00007fa1e540c520
# @app=#<ActionDispatch::Routing::RouteSet:0x00007fa1e594cbe8>
# >
# ...
# >
#
# >
# >
@app
end
# Defaults to an ActionDispatch::Routing::RouteSet instance.
def endpoint
ActionDispatch::Routing::RouteSet.new_with_config(config)
end
end
end
# ./gems/railties/lib/rails/application...
module Rails
class Application < Engine
def default_middleware_stack
default_stack = DefaultMiddlewareStack.new(self, config, paths)
default_stack.build_stack # Let's step into this line.
end
class DefaultMiddlewareStack
attr_reader :config, :paths, :app
def initialize(app, config, paths)
@app = app
@config = config
@paths = paths
end
def build_stack
ActionDispatch::MiddlewareStack.new do |middleware|
if config.force_ssl
middleware.use ::ActionDispatch::SSL, config.ssl_options
end
middleware.use ::Rack::Sendfile, config.action_dispatch.x_sendfile_header
if config.public_file_server.enabled
headers = config.public_file_server.headers || {}
middleware.use ::ActionDispatch::Static, paths["public"].first, index: config.public_file_server.index_name, headers: headers
end
if rack_cache = load_rack_cache
require "action_dispatch/http/rack_cache"
middleware.use ::Rack::Cache, rack_cache
end
if config.allow_concurrency == false
# User has explicitly opted out of concurrent request
# handling: presumably their code is not threadsafe
middleware.use ::Rack::Lock
end
middleware.use ::ActionDispatch::Executor, app.executor
middleware.use ::Rack::Runtime
middleware.use ::Rack::MethodOverride unless config.api_only
middleware.use ::ActionDispatch::RequestId
middleware.use ::ActionDispatch::RemoteIp, config.action_dispatch.ip_spoofing_check, config.action_dispatch.trusted_proxies
middleware.use ::Rails::Rack::Logger, config.log_tags
middleware.use ::ActionDispatch::ShowExceptions, show_exceptions_app
middleware.use ::ActionDispatch::DebugExceptions, app, config.debug_exception_response_format
unless config.cache_classes
middleware.use ::ActionDispatch::Reloader, app.reloader
end
middleware.use ::ActionDispatch::Callbacks
middleware.use ::ActionDispatch::Cookies unless config.api_only
if !config.api_only && config.session_store
if config.force_ssl && config.ssl_options.fetch(:secure_cookies, true) && !config.session_options.key?(:secure)
config.session_options[:secure] = true
end
middleware.use config.session_store, config.session_options
middleware.use ::ActionDispatch::Flash
end
unless config.api_only
middleware.use ::ActionDispatch::ContentSecurityPolicy::Middleware
end
middleware.use ::Rack::Head
middleware.use ::Rack::ConditionalGet
middleware.use ::Rack::ETag, "no-cache"
middleware.use ::Rack::TempfileReaper unless config.api_only
end
end
end
end
end
# ./gems/actionpack-5.2.2/lib/action_dispatch/middleware/stack.rb
module ActionDispatch
class MiddlewareStack
def use(klass, *args, &block)
middlewares.push(build_middleware(klass, args, block))
end
def build_middleware(klass, args, block)
Middleware.new(klass, args, block)
end
def build(app = Proc.new)
# See Enumerable#inject for more information.
return_val = middlewares.freeze.reverse.inject(app) do |a, middleware|
# a: app, and will be changed when iterating
# middleware: #<ActionDispatch::MiddlewareStack::Middleware:0x00007f8a4fada6e8>, 'middleware' will be switched to another instance of ActionDispatch::MiddlewareStack::Middleware when iterating
middleware.build(a) # Let's step into this line.
end
return_val
end
class Middleware
def initialize(klass, args, block)
@klass = klass
@args = args
@block = block
end
def build(app)
# klass is rack middleware like : Rack::TempfileReaper, Rack::ETag, Rack::ConditionalGet or Rack::Head, etc.
# It's typical rack app to use these middlewares.
# See https://github.com/rack/rack-contrib/blob/master/lib/rack/contrib for more information.
klass.new(app, *args, &block)
end
end
end
end
The core app: ActionDispatch::Routing::RouteSet instance
# Paste again FYI.
# @app: #<Rack::Sendfile:0x00007ff14d905f60
# @app=#<ActionDispatch::Static:0x00007ff14d906168
# @app=#<ActionDispatch::Executor:0x00007ff14d9061b8
# ...
# @app=#<Rack::ETag:0x00007fa1e540c4f8
# @app=#<Rack::TempfileReaper:0x00007fa1e540c520
# @app=#<ActionDispatch::Routing::RouteSet:0x00007fa1e594cbe8>
# >
# ...
# >
#
# >
# >
As we see in the Rack middleware stack, the last one is
@app=#<ActionDispatch::Routing::RouteSet:0x00007fa1e594cbe8>
# ./gems/actionpack-5.2.2/lib/action_dispatch/routing/route_set.rb
module ActionDispatch
module Routing
class RouteSet
def initialize(config = DEFAULT_CONFIG)
@set = Journey::Routes.new
@router = Journey::Router.new(@set)
end
def call(env)
req = make_request(env) # return ActionDispatch::Request.new(env)
req.path_info = Journey::Router::Utils.normalize_path(req.path_info)
@router.serve(req) # Let's step into this line.
end
end
end
# ./gems/actionpack5.2.2/lib/action_dispatch/journey/router.rb
module Journey
class Router
class RoutingError < ::StandardError
end
attr_accessor :routes
def initialize(routes)
@routes = routes
end
def serve(req)
find_routes(req).each do |match, parameters, route| # Let's step into 'find_routes'
set_params = req.path_parameters
path_info = req.path_info
script_name = req.script_name
unless route.path.anchored
req.script_name = (script_name.to_s + match.to_s).chomp("/")
req.path_info = match.post_match
req.path_info = "/" + req.path_info unless req.path_info.start_with? "/"
end
parameters = route.defaults.merge parameters.transform_values { |val|
val.dup.force_encoding(::Encoding::UTF_8)
}
req.path_parameters = set_params.merge parameters
# 'route' is an instance of ActionDispatch::Journey::Route.
# 'route.app' is an instance of ActionDispatch::Routing::RouteSet::Dispatcher.
status, headers, body = route.app.serve(req) # Let's step into method 'serve'
if "pass" == headers["X-Cascade"]
req.script_name = script_name
req.path_info = path_info
req.path_parameters = set_params
next
end
return [status, headers, body]
end
[404, { "X-Cascade" => "pass" }, ["Not Found"]]
end
def find_routes(req)
routes = filter_routes(req.path_info).concat custom_routes.find_all { |r|
r.path.match(req.path_info)
}
routes =
if req.head?
match_head_routes(routes, req)
else
match_routes(routes, req)
end
routes.sort_by!(&:precedence)
routes.map! { |r|
match_data = r.path.match(req.path_info)
path_parameters = {}
match_data.names.zip(match_data.captures) { |name, val|
path_parameters[name.to_sym] = Utils.unescape_uri(val) if val
}
[match_data, path_parameters, r]
}
end
end
end
end
# ./gems/actionpack-5.2.2/lib/action_dispatch/routing/route_set.rb
module ActionDispatch
module Routing
class RouteSet
class Dispatcher < Routing::Endpoint
def serve(req)
params = req.path_parameters # params: { action: 'index', controller: 'home' }
controller = controller(req) # controller: HomeController
# The definition of 'make_response!' is
# ActionDispatch::Response.create.tap { |res| res.request = request; }
res = controller.make_response!(req)
dispatch(controller, params[:action], req, res) # Let's step into this line.
rescue ActionController::RoutingError
if @raise_on_name_error
raise
else
return [404, { "X-Cascade" => "pass" }, []]
end
end
private
def controller(req)
req.controller_class
rescue NameError => e
raise ActionController::RoutingError, e.message, e.backtrace
end
def dispatch(controller, action, req, res)
controller.dispatch(action, req, res) # Let's step into this line.
end
end
end
end
end
# ./gems/actionpack-5.2.2/lib/action_controller/metal.rb
module ActionController
class Metal < AbstractController::Base
abstract!
def self.controller_name
@controller_name ||= name.demodulize.sub(/Controller$/, "").underscore
end
def self.make_response!(request)
ActionDispatch::Response.new.tap do |res|
res.request = request
end
end
class_attribute :middleware_stack, default: ActionController::MiddlewareStack.new
def self.inherited(base)
base.middleware_stack = middleware_stack.dup
super
end
# Direct dispatch to the controller. Instantiates the controller, then
# executes the action named +name+.
def self.dispatch(name, req, res)
if middleware_stack.any?
middleware_stack.build(name) { |env| new.dispatch(name, req, res) }.call req.env
else
# 'self' is HomeController, so for this line Rails will new a HomeController instance.
# Invoke `HomeController.ancestors`, you can find many superclasses of HomeController.
# These are some typical superclasses of HomeController.
# HomeController
# < ApplicationController
# < ActionController::Base
# < ActiveRecord::Railties::ControllerRuntime (module included)
# < ActionController::Instrumentation (module included)
# < ActionController::Rescue (module included)
# < AbstractController::Callbacks (module included)
# < ActionController::ImplicitRender (module included)
# < ActionController::BasicImplicitRender (module included)
# < ActionController::Renderers (module included)
# < ActionController::Rendering (module included)
# < ActionView::Layouts (module included)
# < ActionView::Rendering (module included)
# < ActionDispatch::Routing::UrlFor (module included)
# < AbstractController::Rendering (module included)
# < ActionController::Metal
# < AbstractController::Base
new.dispatch(name, req, res) # Let's step into this line.
end
end
def dispatch(name, request, response)
set_request!(request)
set_response!(response)
process(name) # Let's step into this line.
request.commit_flash
to_a
end
def to_a
response.to_a
end
end
end
# .gems/actionpack-5.2.2/lib/abstract_controller/base.rb
module AbstractController
class Base
def process(action, *args)
@_action_name = action.to_s
unless action_name = _find_action_name(@_action_name)
raise ActionNotFound, "The action '#{action}' could not be found for #{self.class.name}"
end
@_response_body = nil
# action_name: 'index'
process_action(action_name, *args) # Let's step into this line.
end
end
end
# .gems/actionpack-5.2.2/lib/action_controller/metal/instrumentation.rb
module ActionController
module Instrumentation
def process_action(*args)
raw_payload = {
controller: self.class.name,
action: action_name,
params: request.filtered_parameters,
headers: request.headers,
format: request.format.ref,
method: request.request_method,
path: request.fullpath
}
ActiveSupport::Notifications.instrument("start_processing.action_controller", raw_payload.dup)
ActiveSupport::Notifications.instrument("process_action.action_controller", raw_payload) do |payload|
begin
# self: #<HomeController:0x00007fcd3c5dfd48>
result = super # Let's step into this line.
payload[:status] = response.status
result
ensure
append_info_to_payload(payload)
end
end
end
end
end
# .gems/actionpack-5.2.2/lib/action_controller/metal/rescue.rb
module ActionController
module Rescue
def process_action(*args)
super # Let's step into this line.
rescue Exception => exception
request.env["action_dispatch.show_detailed_exceptions"] ||= show_detailed_exceptions?
rescue_with_handler(exception) || raise
end
end
end
# .gems/actionpack-5.2.2/lib/abstract_controller/callbacks.rb
module AbstractController
# = Abstract Controller Callbacks
#
# Abstract Controller provides hooks during the life cycle of a controller action.
# Callbacks allow you to trigger logic during this cycle. Available callbacks are:
#
# * <tt>after_action</tt>
# * <tt>before_action</tt>
# * <tt>skip_before_action</tt>
# * ...
module Callbacks
def process_action(*args)
run_callbacks(:process_action) do
# self: #<HomeController:0x00007fcd3c5dfd48>
super # Let's step into this line.
end
end
end
end
# .gems/actionpack-5.2.2/lib/action_controller/metal/rendering.rb
module ActionController
module Rendering
def process_action(*)
self.formats = request.formats.map(&:ref).compact
super # Let's step into this line.
end
end
end
# .gems/actionpack-5.2.2/lib/abstract_controller/base.rb
module AbstractController
class Base
def process_action(method_name, *args)
# self: #<HomeController:0x00007fcd3c5dfd48>, method_name: 'index'
# In the end, method 'send_action' is method 'send' by `alias send_action send`
send_action(method_name, *args)
end
alias send_action send
end
end
# .gems/actionpack-5.2.2/lib/action_controller/metal/basic_implicit_render.rb
module ActionController
module BasicImplicitRender
def send_action(method, *args)
# self: #<HomeController:0x00007fcd3c5dfd48>, method_name: 'index'
# Because 'send_action' is an alias of 'send',
# self.send('index', *args) will goto HomeController#index.
x = super
# performed?: false (for this example)
x.tap { default_render unless performed? } # Let's step into 'default_render' later.
end
end
end
# ./your_project/app/controllers/home_controller.rb
class HomeController < ApplicationController
# Will go back to BasicImplicitRender#send_action when method 'index' is done.
def index
# Question: How does the instance variable '@users' defined in HomeController can be accessed in './app/views/home/index.html.erb' ?
# I will answer this question later.
@users = User.all.pluck(:id, :name)
end
end
# ./app/views/home/index.html.erb
<div class="container">
<h1 class="display-4 font-italic">
<%= t('home.banner_title') %>
<%= @users %>
</h1>
</div>
Render view
As we see in ActionController::BasicImplicitRender::send_action, the last line is default_render.
So after HomeController#index is done, Ruby will execute method default_render.
# .gems/actionpack-5.2.2/lib/action_controller/metal/implicit_render.rb
module ActionController
# Handles implicit rendering for a controller action that does not
# explicitly respond with +render+, +respond_to+, +redirect+, or +head+.
module ImplicitRender
def default_render(*args)
# Let's step into template_exists?
if template_exists?(action_name.to_s, _prefixes, variants: request.variant)
# Rails has found the default template './app/views/home/index.html.erb', so render it.
render(*args) # Let's step into this line later
#...
else
logger.info "No template found for #{self.class.name}\##{action_name}, rendering head :no_content" if logger
super
end
end
end
end
# .gems/actionview-5.2.2/lib/action_view/lookup_context.rb
module ActionView
class LookupContext
module ViewPaths
# Rails checks whether the default template exists.
def exists?(name, prefixes = [], partial = false, keys = [], **options)
@view_paths.exists?(*args_for_lookup(name, prefixes, partial, keys, options))
end
alias :template_exists? :exists?
end
end
end
# .gems/actionpack-5.2.2/lib/action_controller/metal/instrumentation.rb
module ActionController
module Instrumentation
def render(*args)
render_output = nil
self.view_runtime = cleanup_view_runtime do
Benchmark.ms {
# self: #<HomeController:0x00007fa7e9c54278>
render_output = super # Let's step into super
}
end
render_output
end
end
end
# .gems/actionpack-5.2.2/lib/action_controller/metal/rendering.rb
module ActionController
module Rendering
# Check for double render errors and set the content_type after rendering.
def render(*args)
raise ::AbstractController::DoubleRenderError if response_body
super # Let's step into super
end
end
end
# .gems/actionpack-5.2.2/lib/abstract_controller/rendering.rb
module AbstractController
module Rendering
# Normalizes arguments, options and then delegates render_to_body and
# sticks the result in <tt>self.response_body</tt>.
def render(*args, &block)
options = _normalize_render(*args, &block)
rendered_body = render_to_body(options) # Let's step into this line.
if options[:html]
_set_html_content_type
else
_set_rendered_content_type rendered_format
end
self.response_body = rendered_body
end
end
end
# .gems/actionpack-5.2.2/lib/action_controller/metal/renderers.rb
module ActionController
module Renderers
def render_to_body(options)
_render_to_body_with_renderer(options) || super # Let's step into this line and 'super' later.
end
# For this example, this method return nil in the end.
def _render_to_body_with_renderer(options)
# The '_renderers' is defined at line 31: `class_attribute :_renderers, default: Set.new.freeze.`
# '_renderers' is an instance predicate method. For more information,
# see ./gems/activesupport/lib/active_support/core_ext/class/attribute.rb
_renderers.each do |name|
if options.key?(name)
_process_options(options)
method_name = Renderers._render_with_renderer_method_name(name)
return send(method_name, options.delete(name), options)
end
end
nil
end
end
end
# .gems/actionpack-5.2.2/lib/action_controller/metal/renderers.rb
module ActionController
module Rendering
def render_to_body(options = {})
super || _render_in_priorities(options) || " " # Let's step into 'super'
end
end
end
# .gems/actionview-5.2.2/lib/action_view/rendering.rb
module ActionView
module Rendering
def render_to_body(options = {})
_process_options(options)
_render_template(options) # Let's step into this line.
end
def _render_template(options)
variant = options.delete(:variant)
assigns = options.delete(:assigns)
context = view_context # We will step into this line later.
context.assign assigns if assigns
lookup_context.rendered_format = nil if options[:formats]
lookup_context.variants = variant if variant
view_renderer.render(context, options) # Let's step into this line.
end
end
end
# .gems/actionview-5.2.2/lib/action_view/renderer/renderer.rb
module ActionView
class Renderer
def render(context, options)
if options.key?(:partial)
render_partial(context, options)
else
render_template(context, options) # Let's step into this line.
end
end
# Direct access to template rendering.
def render_template(context, options)
TemplateRenderer.new(@lookup_context).render(context, options) # Let's step into this line.
end
end
end
# .gems/actionview-5.2.2/lib/action_view/renderer/template_renderer.rb
module ActionView
class TemplateRenderer < AbstractRenderer
def render(context, options)
@view = context
@details = extract_details(options)
template = determine_template(options)
prepend_formats(template.formats)
@lookup_context.rendered_format ||= (template.formats.first || formats.first)
render_template(template, options[:layout], options[:locals]) # Let's step into this line.
end
def render_template(template, layout_name = nil, locals = nil)
view, locals = @view, locals || {}
render_with_layout(layout_name, locals) do |layout| # Let's step into this line
instrument(:template, identifier: template.identifier, layout: layout.try(:virtual_path)) do
# template: #<ActionView::Template:0x00007f822759cbc0>
template.render(view, locals) { |*name| view._layout_for(*name) } # Let's step into this line
end
end
end
def render_with_layout(path, locals)
layout = path && find_layout(path, locals.keys, [formats.first])
content = yield(layout)
if layout
view = @view
view.view_flow.set(:layout, content)
layout.render(view, locals) { |*name| view._layout_for(*name) }
else
content
end
end
end
end
# .gems/actionview-5.2.2/lib/action_view/template.rb
module ActionView
class Template
def render(view, locals, buffer = nil, &block)
instrument_render_template do
# self: #<ActionView::Template:0x00007f89bab1efb8
# @identifier="/path/to/your/project/app/views/home/index.html.erb"
# @source="<div class='container'\n ..."
# >
compile!(view)
# method_name: "_app_views_home_index_html_erb___3699380246341444633_70336654511160" (This method is defined in 'def compile(mod)' below)
# view: #<#<Class:0x00007ff10d6c9d18>:0x00007ff10ea050a8>, view is an instance of <a subclass of ActionView::Base> which has same instance variables defined in the instance of HomeController.
# You will get the result html after invoking 'view.send'.
view.send(method_name, locals, buffer, &block)
end
rescue => e
handle_render_error(view, e)
end
# Compile a template. This method ensures a template is compiled
# just once and removes the source after it is compiled.
def compile!(view)
return if @compiled
# Templates can be used concurrently in threaded environments
# so compilation and any instance variable modification must
# be synchronized
@compile_mutex.synchronize do
# Any thread holding this lock will be compiling the template needed
# by the threads waiting. So re-check the @compiled flag to avoid
# re-compilation
return if @compiled
if view.is_a?(ActionView::CompiledTemplates)
mod = ActionView::CompiledTemplates
else
mod = view.singleton_class
end
instrument("!compile_template") do
compile(mod) # Let's step into this line.
end
# Just discard the source if we have a virtual path. This
# means we can get the template back.
@source = nil if @virtual_path
@compiled = true
end
end
def compile(mod)
encode!
# @handler: #<ActionView::Template::Handlers::ERB:0x00007ff10e1be188>
code = @handler.call(self) # Let's step into this line.
# Make sure that the resulting String to be eval'd is in the
# encoding of the code
source = <<-end_src.dup
def #{method_name}(local_assigns, output_buffer)
_old_virtual_path, @virtual_path = @virtual_path, #{@virtual_path.inspect};_old_output_buffer = @output_buffer;#{locals_code};#{code}
ensure
@virtual_path, @output_buffer = _old_virtual_path, _old_output_buffer
end
end_src
# ...
# source: def _app_views_home_index_html_erb___1187260686135140546_70244801399180(local_assigns, output_buffer)
# _old_virtual_path, @virtual_path = @virtual_path, "home/index";_old_output_buffer = @output_buffer;;
# @output_buffer = output_buffer || ActionView::OutputBuffer.new;
# @output_buffer.safe_append='<div class="container">
# <h1 class="display-4 font-italic">
# '.freeze;
# @output_buffer.append=( t('home.banner_title') );
# @output_buffer.append=( @users );
# @output_buffer.safe_append='
# </h1>
# </div>
# '.freeze;
# @output_buffer.to_s
# ensure
# @virtual_path, @output_buffer = _old_virtual_path, _old_output_buffer
# end
mod.module_eval(source, identifier, 0) # This line will actually define the method '_app_views_home_index_html_erb___1187260686135140546_70244801399180'
# mod: ActionView::CompiledTemplates
ObjectSpace.define_finalizer(self, Finalizer[method_name, mod])
end
# .gems/actionview-5.2.2/lib/action_view/template/handler/erb.rb
module Handlers
class ERB
def call(template)
template_source = template.source.dup.force_encoding(Encoding::ASCII_8BIT)
erb = template_source.gsub(ENCODING_TAG, "")
encoding = $2
erb.force_encoding valid_encoding(template.source.dup, encoding)
# Always make sure we return a String in the default_internal
erb.encode!
self.class.erb_implementation.new(
erb,
escape: (self.class.escape_whitelist.include? template.type),
trim: (self.class.erb_trim_mode == "-")
).src
end
end
end
end
end
How can instance variables defined in Controller be accessed in view file?
It's time to answer the question before:
How can instance variables like @users defined in HomeController be accessed in ./app/views/home/index.html.erb?
I will answer this question by showing the source code below.
# ./gems/actionview-5.2.2/lib/action_view/rendering.rb
module ActionView
module Rendering
def view_context
# view_context_class is a subclass of ActionView::Base.
view_context_class.new( # Let's step into this line later.
view_renderer,
view_assigns, # This line will set the instance variables like '@users' in this example. Let's step into this line.
self
)
end
def view_assigns
# self: #<HomeController:0x00007f83ecfed310>
protected_vars = _protected_ivars
# instance_variables is an instance method of class `Object` and it will return an array. And the array contains @users.
variables = instance_variables
variables.reject! { |s| protected_vars.include? s }
ret = variables.each_with_object({}) { |name, hash|
hash[name.slice(1, name.length)] = instance_variable_get(name)
}
# ret: {"marked_for_same_origin_verification"=>true, "users"=>[[1, "Lane"], [2, "John"], [4, "Frank"]]}
ret
end
def view_context_class
# Will return a subclass of ActionView::Base.
@_view_context_class ||= self.class.view_context_class
end
# How this ClassMethods works? Please look at ActiveSupport::Concern in ./gems/activesupport-5.2.2/lib/active_support/concern.rb
# FYI, the method 'append_features' will be executed automatically before method 'included' executed.
# https://apidock.com/ruby/v1_9_3_392/Module/append_features
module ClassMethods
def view_context_class
# self: HomeController
@view_context_class ||= begin
supports_path = supports_path?
routes = respond_to?(:_routes) && _routes
helpers = respond_to?(:_helpers) && _helpers
Class.new(ActionView::Base) do
if routes
include routes.url_helpers(supports_path)
include routes.mounted_helpers
end
if helpers
include helpers
end
end
end
end
end
end
end
# ./gems/actionview-5.2.2/lib/action_view/base.rb
module ActionView
class Base
def initialize(context = nil, assigns = {}, controller = nil, formats = nil)
@_config = ActiveSupport::InheritableOptions.new
if context.is_a?(ActionView::Renderer)
@view_renderer = context
else
lookup_context = context.is_a?(ActionView::LookupContext) ?
context : ActionView::LookupContext.new(context)
lookup_context.formats = formats if formats
lookup_context.prefixes = controller._prefixes if controller
@view_renderer = ActionView::Renderer.new(lookup_context)
end
@cache_hit = {}
assign(assigns) # Let's step into this line.
assign_controller(controller)
_prepare_context
end
def assign(new_assigns)
@_assigns =
new_assigns.each do |key, value|
# This line will set the instance variables (like '@users') in HomeController to itself.
instance_variable_set("@#{key}", value)
end
end
end
end
After all rack apps called, user will get the response.
Part 4: What does $ rails server do?
If you start Rails by $ rails server. You may want to know what does this command do?
The command rails locates at ./bin/.
#!/usr/bin/env ruby
APP_PATH = File.expand_path('../config/application', __dir__)
require_relative '../config/boot'
require 'rails/commands' # Let's look at this file.
# ./railties-5.2.2/lib/rails/commands.rb
require "rails/command"
aliases = {
"g" => "generate",
"d" => "destroy",
"c" => "console",
"s" => "server",
"db" => "dbconsole",
"r" => "runner",
"t" => "test"
}
command = ARGV.shift
command = aliases[command] || command # command is 'server'
Rails::Command.invoke command, ARGV # Let's step into this line.
# ./railties-5.2.2/lib/rails/command.rb
module Rails
module Command
class << self
def invoke(full_namespace, args = [], **config)
# ...
# command_name: 'server'
# After calling `find_by_namespace`, we will get this result:
# command: Rails::Command::ServerCommand
command = find_by_namespace(namespace, command_name)
# Equals to: Rails::Command::ServerCommand.perform('server', args, config)
command.perform(command_name, args, config)
end
end
end
end
# ./gems/railties-5.2.2/lib/rails/commands/server/server_command.rb
module Rails
module Command
# There is a class method 'perform' in the Base class.
class ServerCommand < Base
end
end
end
Thor
Thor is a toolkit for building powerful command-line interfaces.
https://github.com/erikhuda/thor
Inheritance relationship: Rails::Command::ServerCommand < Rails::Command::Base < Thor
# ./gems/railties-5.2.2/lib/rails/command/base.rb
module Rails
module Command
class Base < Thor
class << self
# command: 'server'
def perform(command, args, config)
#...
dispatch(command, args.dup, nil, config) # Thor.dispatch
end
end
end
end
end
# ./gems/thor-0.20.3/lib/thor.rb
class Thor
class << self
# meth is 'server'
def dispatch(meth, given_args, given_opts, config)
# ...
# Will new a Rails::Command::ServerCommand instance here
# because 'self' is Rails::Command::ServerCommand.
instance = new(args, opts, config)
# ...
# Method 'invoke_command' is defined in Thor::Invocation.
# command: {Thor::Command}#<struct Thor::Command name="server" ...>
instance.invoke_command(command, trailing || [])
end
end
end
# ./gems/thor-0.20.3/lib/thor/invocation.rb
class Thor
# FYI, this module is included in Thor.
# And Thor is grandfather of Rails::Command::ServerCommand
module Invocation
def invoke_command(command, *args) # 'invoke_command' is defined at here.
# ...
# self: #<Rails::Command::ServerCommand:0x00007fdcc49791b0>
# command: {Thor::Command}#<struct Thor::Command name="server" ...>
command.run(self, *args)
end
end
end
# ./gems/thor-0.20.3/lib/thor/command.rb
class Thor
class Command < Struct.new(:name, :description, :long_description, :usage, :options, :ancestor_name)
def run(instance, args = [])
# ...
# instance: #<Rails::Command::ServerCommand:0x00007fdcc49791b0>
# name: "server"
# This line will invoke Rails::Command::ServerCommand#server,
# the instance method 'server' is defined in Rails::Command::ServerCommand implicitly.
# I will show you how the instance method 'server' is implicitly defined.
instance.__send__(name, *args)
end
end
end
# ./gems/thor-0.20.3/lib/thor.rb
class Thor
# ...
include Thor::Base # Will invoke hooked method 'Thor::Base.included(self)'
end
# ./gems/thor-0.20.3/lib/thor/base.rb
module Thor
module Base
class << self
# 'included' is a hooked method.
# When module 'Thor::Base' is included, method 'included' is executed.
def included(base)
# base: Thor
# this line will define `Thor.method_added`.
base.extend ClassMethods
# Module 'Invocation' is included for class 'Thor' here.
# Because Thor is grandfather of Rails::Command::ServerCommand,
# 'invoke_command' will be instance method of Rails::Command::ServerCommand
base.send :include, Invocation # 'invoke_command' is defined in module Invocation
base.send :include, Shell
end
end
module ClassMethods
# 'method_added' is a hooked method.
# When an instance method is created in Rails::Command::ServerCommand,
# `method_added` will be executed.
# So, when method `perform` is defined in Rails::Command::ServerCommand,
# `method_added` will be executed and create_command('perform') will be invoked.
# So in the end, method 'server' will be created by alias_method('server', 'perform').
# And the method 'server' is for the 'server' in command `$ rails server`.
def method_added(meth)
# ...
# self: {Class} Rails::Command::ServerCommand
create_command(meth) # meth is 'perform'. Let's step into this line.
end
end
end
end
# ./gems/railties-5.2.2/lib/rails/command/base.rb
module Rails
module Command
# Rails::Command::Base is superclass of Rails::Command::ServerCommand
module Base
class << self
def create_command(meth)
if meth == "perform"
# Calling instance method 'server' of Rails::Command::ServerCommand
# will be transferred to call instance method 'perform'.
alias_method('server', meth)
end
end
end
end
end
end
# ./gems/thor-0.20.3/lib/thor/command.rb
class Thor
class Command < Struct.new(:name, :description, :long_description, :usage, :options, :ancestor_name)
def run(instance, args = [])
#...
# instance: {Rails::Command::ServerCommand}#<Rails::Command::ServerCommand:0x00007fa5f319bf40>
# name: 'server'.
# Will actually invoke 'instance.perform(*args)'.
# Equals to invoke Rails::Command::ServerCommand#perform(*args).
# Let's step into Rails::Command::ServerCommand#perform.
instance.__send__(name, *args)
end
end
end
# ./gems/railties-5.2.2/lib/rails/commands/server/server_command.rb
module Rails
module Command
class ServerCommand < Base
# This is the method will be executed when `$ rails server`.
def perform
# ...
Rails::Server.new(server_options).tap do |server|
# APP_PATH is '/Users/your_name/your_project/config/application'.
# require APP_PATH will create the 'Rails.application' object.
# 'Rails.application' is 'YourProject::Application.new'.
# Rack server will start 'Rails.application'.
require APP_PATH
Dir.chdir(Rails.application.root)
server.start # Let's step into this line.
end
end
end
end
end
Rails::Server#start
# ./gems/railties-5.2.2/lib/rails/commands/server/server_command.rb
module Rails
class Server < ::Rack::Server
def start
print_boot_information
trap(:INT) do
exit
end
create_tmp_directories
setup_dev_caching
# This line is important. Although the method name seems not.
log_to_stdout# Let step into this line.
super # Will invoke ::Rack::Server#start. I will show you later.
ensure
puts "Exiting" unless @options && options[:daemonize]
end
def log_to_stdout
# 'wrapped_app' will get an well prepared Rack app from './config.ru' file.
# It's the first time invoke 'wrapped_app'.
# The app is an instance of YourProject::Application.
# But the app is not created in 'wrapped_app'.
# It has been created when `require APP_PATH` in previous code,
# just at the 'perform' method in Rails::Command::ServerCommand.
wrapped_app # Let's step into this line
# ...
end
end
end
# ./gems/rack-2.0.6/lib/rack/server.rb
module Rack
class Server
def wrapped_app
@wrapped_app ||=
build_app(
app # Let's step into this line.
)
end
def app
@app ||= build_app_and_options_from_config # Let's step into this line.
@app
end
def build_app_and_options_from_config
# ...
# self.options[:config]: 'config.ru'. Let's step into this line.
app, options = Rack::Builder.parse_file(self.options[:config], opt_parser)
# ...
app
end
# This method is called in Rails::Server#start
def start(&blk)
#...
wrapped_app
#...
# server: {Module} Rack::Handler::Puma
# wrapped_app: {YourProject::Application} #<YourProject::Application:0x00007f7fe5523f98>
server.run(wrapped_app, options, &blk) # We will step into this line (Rack::Handler::Puma.run) later.
end
end
end
# ./gems/rack/lib/rack/builder.rb
module Rack
module Builder
def self.parse_file(config, opts = Server::Options.new)
# config: 'config.ru'
cfgfile = ::File.read(config)
app = new_from_string(cfgfile, config)
return app, options
end
# Let's guess what does 'run Rails.application' do in config.ru?
# You may guess that:
# Run YourProject::Application instance.
# But 'run' maybe not what you are thinking about.
# Because the 'self' object in 'config.ru' is #<Rack::Builder:0x00007f8c861ec278 @warmup=nil, @run=nil, @map=nil, @use=[]>,
# 'run' is an instance method of Rack::Builder.
# Let's look at the definition of the 'run' method:
# def run(app)
# @run = app # Just set an instance variable for Rack::Builder instance.
# end
def self.new_from_string(builder_script, file="(rackup)")
# Rack::Builder implements a small DSL to iteratively construct Rack applications.
eval "Rack::Builder.new {\n" + builder_script + "\n}.to_app",
TOPLEVEL_BINDING, file, 0
end
end
end
Starting Puma
As we see in Rack::Server#start, there is Rack::Handler::Puma.run(wrapped_app, options, &blk).
# ./gems/puma-3.12.0/lib/rack/handler/puma.rb
module Rack
module Handler
module Puma
# This method is invoked in `Rack::Server#start`:
# Rack::Handler::Puma.run(wrapped_app, options, &blk)
def self.run(app, options = {})
conf = self.config(app, options)
# ...
launcher = ::Puma::Launcher.new(conf, :events => events)
begin
# Puma will run your app (instance of YourProject::Application)
launcher.run # Let's step into this line.
rescue Interrupt
puts "* Gracefully stopping, waiting for requests to finish"
launcher.stop
puts "* Goodbye!"
end
end
end
end
end
# .gems/puma-3.12.0/lib/puma/launcher.rb
module Puma
# Puma::Launcher is the single entry point for starting a Puma server based on user
# configuration. It is responsible for taking user supplied arguments and resolving them
# with configuration in `config/puma.rb` or `config/puma/<env>.rb`.
#
# It is responsible for either launching a cluster of Puma workers or a single
# puma server.
class Launcher
def initialize(conf, launcher_args={})
@runner = nil
@config = conf
# ...
if clustered?
# ...
@runner = Cluster.new(self, @events)
else
# For this example, it is Single.new.
@runner = Single.new(self, @events)
end
# ...
end
def run
#...
# Set the behaviors for signals like `$ kill -s SIGTERM puma_process_id` received.
setup_signals # We will discuss this line later.
set_process_title
@runner.run # We will enter `Single.new(self, @events).run` here.
case @status
when :halt
log "* Stopping immediately!"
when :run, :stop
graceful_stop
when :restart
log "* Restarting..."
ENV.replace(previous_env)
@runner.before_restart
restart!
when :exit
# nothing
end
end
end
end
# .gems/puma-3.12.0/lib/puma/single.rb
module Puma
# This class is instantiated by the `Puma::Launcher` and used
# to boot and serve a Ruby application when no puma "workers" are needed
# i.e. only using "threaded" mode. For example `$ puma -t 1:5`
#
# At the core of this class is running an instance of `Puma::Server` which
# gets created via the `start_server` method from the `Puma::Runner` class
# that this inherits from.
class Single < Runner
def run
# ...
# @server: Puma::Server.new(app, @launcher.events, @options)
@server = server = start_server # Let's step into this line.
# ...
thread = server.run # Let's step into this line later.
# This line will suspend the main thread execution.
# And the `thread`'s block (which is method `handle_servers`) will be executed.
# See `Thread#join` for more information.
# I will show you a simple example for using `thread.join`.
# Please search `test_thread_join.rb` in this document.
thread.join
# The below line will never be executed because `thread` is always running and `thread` has joined.
# When `$ kill -s SIGTERM puma_process_id`, the below line will still not be executed
# because the block of `Signal.trap "SIGTERM"` in `Puma::Launcher#setup_signals` will be executed.
# If you remove the line `thread.join`, the below line will be executed,
# but the main thread will exit after all code executed and all the threads not joined will be killed.
puts "anything which will never be executed..."
end
end
end
# .gems/puma-3.12.0/lib/puma/runner.rb
module Puma
# Generic class that is used by `Puma::Cluster` and `Puma::Single` to
# serve requests. This class spawns a new instance of `Puma::Server` via
# a call to `start_server`.
class Runner
def app
@app ||= @launcher.config.app
end
def start_server
min_t = @options[:min_threads]
max_t = @options[:max_threads]
server = Puma::Server.new(app, @launcher.events, @options)
server.min_threads = min_t
server.max_threads = max_t
# ...
server
end
end
end
# .gems/puma-3.12.0/lib/puma/server.rb
module Puma
class Server
def run(background=true)
#...
@status = :run
queue_requests = @queue_requests
# This part is important.
# Remember the block of ThreadPool.new will be called when a request added to the ThreadPool instance.
# And the block will process the request by calling method `process_client`.
# Let's step into this line later to see how puma call the block.
@thread_pool = ThreadPool.new(@min_threads,
@max_threads,
IOBuffer) do |client, buffer|
# Advertise this server into the thread
Thread.current[ThreadLocalKey] = self
process_now = false
if queue_requests
process_now = client.eagerly_finish
end
# ...
if process_now
# Process the request. You can treat `client` as request.
# If you want to know more about 'process_client', please read part 3
# or search 'process_client' in this document.
process_client(client, buffer)
else
client.set_timeout @first_data_timeout
@reactor.add client
end
end
# ...
if background # background: true (for this example)
# This part is important.
# Remember puma created a thread here!
# We will know that the newly created thread's job is waiting for requests.
# When a request comes, the thread will transfer the request processing work to a thread in ThreadPool.
# The method `handle_servers` in thread's block will be executed immediately
# (executed in the newly created thread, not in the main thread).
@thread = Thread.new { handle_servers } # Let's step into this line to see what I said.
return @thread
else
handle_servers
end
end
def handle_servers
sockets = [check] + @binder.ios
pool = @thread_pool
queue_requests = @queue_requests
# ...
# The thread is always running, because @status has been set to :run in Puma::Server#run.
# Yes, it should always be running to transfer the incoming requests.
while @status == :run
begin
# This line will cause current thread waiting until a request arrives.
# So it will be the entry of every request!
# sockets: [#<IO:fd 23>, #<TCPServer:fd 22, AF_INET, 0.0.0.0, 3000>]
ios = IO.select sockets
ios.first.each do |sock|
if sock == check
break if handle_check
else
if io = sock.accept_nonblock
# You can simply think a Puma::Client instance as a request.
client = Client.new(io, @binder.env(sock))
# ...
# FYI, the method '<<' is redefined.
# Add the request (client) to thread pool means
# a thread in the pool will process this request (client).
pool << client # Let's step into this line.
pool.wait_until_not_full # Let's step into this line later.
end
end
end
rescue Object => e
@events.unknown_error self, e, "Listen loop"
end
end
end
end
end
# .gems/puma-3.12.0/lib/puma/thread_pool.rb
module Puma
class ThreadPool
# Maintain a minimum of +min+ and maximum of +max+ threads
# in the pool.
#
# The block passed is the work that will be performed in each
# thread.
#
def initialize(min, max, *extra, &block)
#..
@mutex = Mutex.new
@todo = [] # @todo is requests (in puma, they are Puma::Client instances) which need to be processed.
@spawned = 0 # the count of @spawned threads
@min = Integer(min) # @min threads count
@max = Integer(max) # @max threads count
@block = block # block will be called in method `spawn_thread` to processed a request.
@workers = []
@reaper = nil
@mutex.synchronize do
@min.times { spawn_thread } # Puma spawns @min count threads.
end
end
def spawn_thread
@spawned += 1
# Create a new Thread now.
# The block of the thread will be executed immediately and separately from the calling thread (main thread).
th = Thread.new(@spawned) do |spawned|
# Thread name is new in Ruby 2.3
Thread.current.name = 'puma %03i' % spawned if Thread.current.respond_to?(:name=)
block = @block
mutex = @mutex
#...
extra = @extra.map { |i| i.new }
# Pay attention to here:
# 'while true' means this part will always be running.
# And there will be @min count threads always running!
# Puma uses these threads to process requests.
# The line: 'not_empty.wait(mutex)' will make current thread waiting.
while true
work = nil
continue = true
mutex.synchronize do
while todo.empty?
if @trim_requested > 0
@trim_requested -= 1
continue = false
not_full.signal
break
end
if @shutdown
continue = false
break
end
@waiting += 1 # `@waiting` is the waiting threads count.
not_full.signal
# This line will cause current thread waiting
# until `not_empty.signal` executed in some other place to wake it up .
# Actually, `not_empty.signal` is located at `def <<(work)` in the same file.
# You can search `def <<(work)` in this document.
# Method `<<` is used in method `handle_servers`: `pool << client` in Puma::Server#run.
# `pool << client` means add a request to the thread pool,
# and then the waked up thread will process the request.
not_empty.wait mutex
@waiting -= 1
end
# `work` is the request (in puma, it's Puma::Client instance) which need to be processed.
work = todo.shift if continue
end
break unless continue
if @clean_thread_locals
ThreadPool.clean_thread_locals
end
begin
# `block.call` will switch program to the block definition part.
# The block definition part is in `Puma::Server#run`:
# @thread_pool = ThreadPool.new(@min_threads,
# @max_threads,
# IOBuffer) do |client, buffer| #...; end
# So please search `ThreadPool.new` in this document to look back.
block.call(work, *extra)
rescue Exception => e
STDERR.puts "Error reached top of thread-pool: #{e.message} (#{e.class})"
end
end
mutex.synchronize do
@spawned -= 1
@workers.delete th
end
end # end of the Thread.new.
@workers << th
th
end
def wait_until_not_full
@mutex.synchronize do
while true
return if @shutdown
# If we can still spin up new threads and there
# is work queued that cannot be handled by waiting
# threads, then accept more work until we would
# spin up the max number of threads.
return if @todo.size - @waiting < @max - @spawned
@not_full.wait @mutex
end
end
end
# Add +work+ to the todo list for a Thread to pickup and process.
def <<(work)
@mutex.synchronize do
if @shutdown
raise "Unable to add work while shutting down"
end
# work: #<Puma::Client:0x00007ff114ece6b0>
# You can treat Puma::Client instance as a request.
@todo << work
if @waiting < @todo.size and @spawned < @max
spawn_thread # Create one more thread to process request.
end
# Wake up the waiting thread to process the request.
# The waiting thread is defined in the same file: Puma::ThreadPool#spawn_thread.
# This code is in `spawn_thread`:
# while true
# # ...
# not_empty.wait mutex
# # ...
# block.call(work, *extra) # This line will process the request.
# end
@not_empty.signal
end
end
end
end
Conclusion
In conclusion, $ rails server will execute Rails::Command::ServerCommand#perform.
In #perform, call Rails::Server#start. Then call Rack::Server#start.
Then call Rack::Handler::Puma.run(YourProject::Application.new).
In .run, Puma will new a always running Thread for ios = IO.select(#<TCPServer:fd 22, AF_INET, 0.0.0.0, 3000>).
Request is created from ios object.
A thread in puma threadPool will process the request.
The thread will invoke rack apps' call to get the response for the request.
Exiting Puma
Process and Thread
Because Puma is using multiple threads, we need to have some basic concepts about Process and Thread.
This link is good for you to obtain the concepts: Process and Thread
In the next part, you will often see thread.join.
I will use two simple example to tell what does thread.join do.
Example one
Try to run test_thread_join.rb.
# ./test_thread_join.rb
thread = Thread.new() do
3.times do |n|
puts "~~~~ " + n.to_s
end
end
# sleep 1
puts "==== I am the main thread."
# thread.join # Try to uncomment these two lines to see the differences.
# puts "==== after thread.join"
You will find that if there is no thread.join, you can only see ==== I am the main thread. in console.
After you added thread.join, you can see:
~~~~ 1
~~~~ 2
~~~~ 3
in console.
Example two
Try to run test_thread_join2.rb.
# ./test_thread_join2.rb
arr = [
Thread.new { sleep 1 },
Thread.new do
sleep 5
puts 'I am arr[1]'
end,
Thread.new { sleep 8}
]
puts Thread.list.size # returns 4 (including the main thread)
sleep 2
arr.each { |thread| puts "~~~~~ #{thread}" }
puts Thread.list.size # returns 3 (because arr[0] is dead)
# arr[1].join # uncomment to see differences
arr.each { |thread| puts "~~~~~ #{thread}" }
puts "Exit main thread"
Send SIGTERM to Puma
When you stop puma by running $ kill -s SIGTERM puma_process_id, you will enter setup_signals in Puma::Launcher#run.
# .gems/puma-3.12.0/lib/puma/launcher.rb
module Puma
# Puma::Launcher is the single entry point for starting a Puma server based on user
# configuration.
class Launcher
def run
#...
# Set the behaviors for signals like `$ kill -s SIGTERM puma_process_id`.
setup_signals # Let's step into this line.
set_process_title
@runner.run
# ...
end
# Set the behaviors for signals like `$ kill -s SIGTERM puma_process_id`.
# Signal.list #=> {"EXIT"=>0, "HUP"=>1, "INT"=>2, "QUIT"=>3, "ILL"=>4, "TRAP"=>5, "IOT"=>6, "ABRT"=>6, "FPE"=>8, "KILL"=>9, "BUS"=>7, "SEGV"=>11, "SYS"=>31, "PIPE"=>13, "ALRM"=>14, "TERM"=>15, "URG"=>23, "STOP"=>19, "TSTP"=>20, "CONT"=>18, "CHLD"=>17, "CLD"=>17, "TTIN"=>21, "TTOU"=>22, "IO"=>29, "XCPU"=>24, "XFSZ"=>25, "VTALRM"=>26, "PROF"=>27, "WINCH"=>28, "USR1"=>10, "USR2"=>12, "PWR"=>30, "POLL"=>29}
# Press `Control + C` to quit means 'SIGINT'.
def setup_signals
begin
# After running `$ kill -s SIGTERM puma_process_id`, Ruby will execute the block of `Signal.trap "SIGTERM"`.
Signal.trap "SIGTERM" do
graceful_stop # Let's step into this line.
raise SignalException, "SIGTERM"
end
rescue Exception
log "*** SIGTERM not implemented, signal based gracefully stopping unavailable!"
end
begin
Signal.trap "SIGUSR2" do
restart
end
rescue Exception
log "*** SIGUSR2 not implemented, signal based restart unavailable!"
end
begin
Signal.trap "SIGUSR1" do
phased_restart
end
rescue Exception
log "*** SIGUSR1 not implemented, signal based restart unavailable!"
end
begin
Signal.trap "SIGINT" do
if Puma.jruby?
@status = :exit
graceful_stop
exit
end
stop
end
rescue Exception
log "*** SIGINT not implemented, signal based gracefully stopping unavailable!"
end
begin
Signal.trap "SIGHUP" do
if @runner.redirected_io?
@runner.redirect_io
else
stop
end
end
rescue Exception
log "*** SIGHUP not implemented, signal based logs reopening unavailable!"
end
end
def graceful_stop
# @runner: instance of Puma::Single (for this example)
@runner.stop_blocked # Let's step into this line.
log "=== puma shutdown: #{Time.now} ==="
log "- Goodbye!"
end
end
end
# .gems/puma-3.12.0/lib/puma/launcher.rb
module Puma
class Single < Runner
def run
# ...
# @server: Puma::Server.new(app, @launcher.events, @options)
@server = server = start_server # Let's step into this line.
# ...
thread = server.run
# This line will suspend the main thread execution.
# And the `thread`'s block (which is the method `handle_servers`) will be executed.
thread.join
end
def stop_blocked
log "- Gracefully stopping, waiting for requests to finish"
@control.stop(true) if @control
# @server: instance of Puma::Server
@server.stop(true) # Let's step into this line
end
end
end
# .gems/puma-3.12.0/lib/puma/server.rb
module Puma
class Server
def initialize(app, events=Events.stdio, options={})
# 'Puma::Util.pipe' returns `IO.pipe`.
@check, @notify = Puma::Util.pipe # @check, @notify is a pair.
@status = :stop
end
def run(background=true)
# ...
@thread_pool = ThreadPool.new(@min_threads,
@max_threads,
IOBuffer) do |client, buffer|
#...
# Process the request.
process_client(client, buffer)
#...
end
# 'Thread.current.object_id' returns '70144214949920',
# which is the same as the 'Thread.current.object_id' in Puma::Server#stop.
# Current thread is the main thread here.
puts "#{Thread.current.object_id}"
# The created @thread is the @thread in `stop` method below.
@thread = Thread.new {
# FYI, this is in the puma starting process.
# 'Thread.current.object_id' returns '70144220123860',
# which is the same as the 'Thread.current.object_id' in 'handle_servers' in Puma::Server#run
# def handle_servers
# begin
# # ...
# ensure
# # FYI, the 'ensure' part is in the puma stopping process.
# puts "#{Thread.current.object_id}" # returns '70144220123860' too.
# end
# end
puts "#{Thread.current.object_id}" # returns '70144220123860'
handle_servers
}
return @thread
end
# Stops the acceptor thread and then causes the worker threads to finish
# off the request queue before finally exiting.
def stop(sync=false)
# This line will set '@status = :stop',
# and cause `ios = IO.select sockets` (in method `handle_servers`) to return result.
# So that the code after `ios = IO.select sockets` will be executed.
notify_safely(STOP_COMMAND) # Let's step into this line.
# 'Thread.current.object_id' returns '70144214949920',
# which is the same as the 'Thread.current.object_id' in Puma::Server#run.
# Current thread is exactly the main thread here.
puts "#{Thread.current.object_id}"
# The @thread is just the always running Thread created in `Puma::Server#run`.
# Please look at method `Puma::Server#run`.
# `@thread.join` will suspend the main thread execution.
# And the code in @thread will continue be executed.
@thread.join if @thread && sync
end
def notify_safely(message)
@notify << message
end
def handle_servers
begin
check = @check
# sockets: [#<IO:fd 23>, #<TCPServer:fd 22, AF_INET, 0.0.0.0, 3000>]
sockets = [check] + @binder.ios
pool = @thread_pool
#...
while @status == :run
# After `notify_safely(STOP_COMMAND)` in main thread, `ios = IO.select sockets` will return result.
# FYI, `@check, @notify = IO.pipe`.
# def notify_safely(message)
# @notify << message
# end
# sockets: [#<IO:fd 23>, #<TCPServer:fd 22, AF_INET, 0.0.0.0, 3000>]
ios = IO.select sockets
ios.first.each do |sock|
if sock == check
# The @status is updated to :stop for this example in `handle_check`.
break if handle_check # Let's step into this line.
else
if io = sock.accept_nonblock
client = Client.new(io, @binder.env(sock))
# ...
pool << client
pool.wait_until_not_full
end
end
end
end
# Let's step into `graceful_shutdown`.
graceful_shutdown if @status == :stop || @status == :restart
# ...
ensure
# FYI, the 'ensure' part is in the puma stopping process.
# 'Thread.current.object_id' returns '70144220123860',
# which is the same as the 'Thread.current.object_id' in 'Thread.new block' in Puma::Server#run
# @thread = Thread.new do
# # FYI, this is in the puma starting process.
# puts "#{Thread.current.object_id}" # returns '70144220123860'
# handle_servers
# end
puts "#{Thread.current.object_id}"
@check.close
@notify.close
# ...
end
end
def handle_check
cmd = @check.read(1)
case cmd
when STOP_COMMAND
@status = :stop # The @status is updated to :stop for this example.
return true
when HALT_COMMAND
@status = :halt
return true
when RESTART_COMMAND
@status = :restart
return true
end
return false
end
def graceful_shutdown
if @thread_pool
@thread_pool.shutdown # Let's step into this line.
end
end
end
end
module Puma
class ThreadPool
# Tell all threads in the pool to exit and wait for them to finish.
def shutdown(timeout=-1)
threads = @mutex.synchronize do
@shutdown = true
# `broadcast` will wakes up all threads waiting for this lock.
@not_empty.broadcast
@not_full.broadcast
# ...
# dup workers so that we join them all safely
# @workers is an array.
# @workers.dup will not create new thread.
# @workers is an instance variable and will be changed when shutdown (by `@workers.delete th`).
# So ues @workers.dup here.
@workers.dup
end
# Wait for threads to finish without force shutdown.
threads.each do |thread|
thread.join
end
@spawned = 0
@workers = []
end
def initialize(min, max, *extra, &block)
#..
@mutex = Mutex.new
@spawned = 0 # The count of @spawned threads.
@todo = [] # @todo is requests (in puma, it's Puma::Client instance) which need to be processed.
@min = Integer(min) # @min threads count
@block = block # block will be called in method `spawn_thread` to process a request.
@workers = []
@mutex.synchronize do
@min.times { spawn_thread } # Puma spawns @min count threads.
end
end
def spawn_thread
@spawned += 1
# Run a new Thread now.
# The block of the thread will be executed separately from the calling thread.
th = Thread.new(@spawned) do |spawned|
block = @block
mutex = @mutex
#...
while true
work = nil
continue = true
mutex.synchronize do
while todo.empty?
# ...
if @shutdown
continue = false
break
end
# ...
# After `@not_empty.broadcast` is executed in '#shutdown', `not_empty` is waked up.
# Ruby will continue to execute the next line here.
not_empty.wait mutex
@waiting -= 1
end
# ...
end
break unless continue
# ...
end
mutex.synchronize do
@spawned -= 1
@workers.delete th
end
end # end of the Thread.new.
@workers << th
th
end
end
end
So all the threads in the ThreadPool joined and finished.
Let's inspect the caller in block of Signal.trap "SIGTERM" below.
# .gems/puma-3.12.0/lib/puma/launcher.rb
module Puma
# Puma::Launcher is the single entry point for starting a Puma server based on user
# configuration.
class Launcher
def run
#...
# Set the behaviors for signals like `$ kill -s SIGTERM puma_process_id`.
setup_signals # Let's step into this line.
set_process_title
# Process.pid: 42264
puts "Process.pid: #{Process.pid}"
@runner.run
# ...
end
def setup_signals
# ...
begin
# After running `$ kill -s SIGTERM puma_process_id`, Ruby will execute the block of `Signal.trap "SIGTERM"`.
Signal.trap "SIGTERM" do
# I inspect `caller` to see the caller stack.
# caller: [
# "../gems/puma-3.12.0/lib/puma/single.rb:118:in `join'",
# "../gems/puma-3.12.0/lib/puma/single.rb:118:in `run'",
# "../gems/puma-3.12.0/lib/puma/launcher.rb:186:in `run'",
# "../gems/puma-3.12.0/lib/rack/handler/puma.rb:70:in `run'",
# "../gems/rack-2.0.6/lib/rack/server.rb:298:in `start'",
# "../gems/railties-5.2.2/lib/rails/commands/server/server_command.rb:55:in `start'",
# "../gems/railties-5.2.2/lib/rails/commands/server/server_command.rb:149:in `block in perform'",
# "../gems/railties-5.2.2/lib/rails/commands/server/server_command.rb:144:in `tap'",
# "../gems/railties-5.2.2/lib/rails/commands/server/server_command.rb:144:in `perform'",
# "../gems/thor-0.20.3/lib/thor/command.rb:27:in `run'",
# "../gems/thor-0.20.3/lib/thor/invocation.rb:126:in `invoke_command'",
# "../gems/thor-0.20.3/lib/thor.rb:391:in `dispatch'",
# "../gems/railties-5.2.2/lib/rails/command/base.rb:65:in `perform'",
# "../gems/railties-5.2.2/lib/rails/command.rb:46:in `invoke'",
# "../gems/railties-5.2.2/lib/rails/commands.rb:18:in `<top (required)>'",
# "../path/to/your_project/bin/rails:5:in `require'",
# "../path/to/your_project/bin/rails:5:in `<main>'"
# ]
puts "caller: #{caller.inspect}"
# Process.pid: 42264 which is the same as the `Process.pid` in the Puma::Launcher#run.
puts "Process.pid: #{Process.pid}"
graceful_stop
# This SignalException is not rescued in the caller stack.
# So in the the caller stack, Ruby will goto the `ensure` part in
# "../gems/railties-5.2.2/lib/rails/commands/server/server_command.rb:55:in `start'".
# So the last code executed is `puts "Exiting" unless @options && options[:daemonize]`
# when running `$ kill -s SIGTERM puma_process_id`.
# You can search `puts "Exiting"` in this document to see it.
raise SignalException, "SIGTERM"
end
rescue Exception
# This `rescue` is only for `Signal.trap "SIGTERM"`, not for `raise SignalException, "SIGTERM"`.
log "*** SIGTERM not implemented, signal based gracefully stopping unavailable!"
end
end
end
end
Welcome to point out the mistakes in this article :)
No reference
Reply to
rails_taotao
rails_taotao
可以用 Chrome 中带的 Google Translate（可能是 Google Extension，要安装下）。
用它翻译 https://github.com/gazeldx/Learn-Rails-by-Reading-Source-Code 效果不错。
翻译本页也可以，但大量注释不会被翻译到，好处是代码没有被翻译。
