Getting Started

Installation

Add the gem to your project:

$ bundle add falcon

Or, if you prefer, install it globally:

$ gem install falcon

Core Concepts

Falcon is a high-performance web server for Ruby. It is designed to be fast, lightweight, and easy to use.

• Asynchronous: Falcon is built on top of the fiber scheduler and the async gem which allow it to handle thousands of connections concurrently.
• Rack Compatible: Falcon is a Rack server. It can run any Rack application, including Rails, Sinatra, and Roda with no modifications.
• Secure: Falcon supports TLS out of the box. It can generate self-signed certificates for localhost.
• HTTP/2: Falcon is build on top of the async-http gem which supports HTTP/2. It can serve multiple requests over a single connection.
• WebSockets: Falcon supports WebSockets using the async-websocket gem which takes advantage of Rack 3 streaming responses. You can build complex real-time applications with ease.

Rack

Falcon is a Rack server. This means it can run any Rack application, including Rails, Sinatra, and Roda. It is compatible with the Rack 2 and Rack 3 specifications. Typically these applications have a config.ru file that defines the application. Falcon can run these applications directly:

# config.ru

run do |env|
	[200, {'Content-Type' => 'text/plain'}, ['Hello, World!']]
end

Then run the application with:

$ falcon serve

Rack Applications Defined in Ruby Files

Rack can load a Ruby file directly and infer the application constant from its filename. For example, Rack::Builder.parse_file("app.rb") requires the file and uses ::App as the Rack application.

Falcon reserves .rb serve configurations for protocol HTTP middleware. Existing Rack applications can be exposed through config/serve.rb using Protocol::Rack::Adapter:

# config/serve.rb

require "protocol/rack"
require_relative "../app"

run Protocol::Rack::Adapter.new(App)

Running falcon serve loads config/serve.rb as protocol HTTP middleware, while the adapter translates requests and responses for the existing Rack application. This replaces the older falcon serve --config app.rb convention without requiring changes to App itself.

Running a Local Server

For local application development, you can use the falcon serve command. This will start a local server on https://localhost:9292. Falcon generates self-signed certificates for localhost. This allows you to test your application with HTTPS locally.

To run on a different port:

$ falcon serve --port 3000

Unencrypted HTTP

If you want to run Falcon without TLS, you can use the --bind option to bind to an unencrypted HTTP endpoint:

$ falcon serve --bind http://localhost:3000

Using with Rackup

You can invoke Falcon via rackup:

$ rackup --server falcon

This will run a single-threaded instance of Falcon using http/1. While it works fine, it's not recommended to use rackup with falcon, because performance will be limited.