falcon 0.52.0 → 0.52.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +4 -4
- checksums.yaml.gz.sig +0 -0
- data/context/deployment.md +166 -0
- data/context/extended-features.md +13 -0
- data/context/getting-started.md +73 -0
- data/context/how-it-works.md +23 -0
- data/context/index.yaml +34 -0
- data/context/interim-response.md +19 -0
- data/context/interim-responses.md +19 -0
- data/context/performance-tuning.md +62 -0
- data/context/rails-integration.md +90 -0
- data/context/websockets.md +23 -0
- data/lib/falcon/version.rb +1 -1
- data/readme.md +13 -3
- data/releases.md +8 -0
- data.tar.gz.sig +0 -0
- metadata +12 -2
- metadata.gz.sig +0 -0
checksums.yaml
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
---
|
2
2
|
SHA256:
|
3
|
-
metadata.gz:
|
4
|
-
data.tar.gz:
|
3
|
+
metadata.gz: 95ff41d54e933c37257afda238572f60d9d73cbc7a8d4e9455b114fcee69a35d
|
4
|
+
data.tar.gz: 0db20e527e3dbe621863bcb222082a1a6798357e7a5b667a7e333cfc4f10b35f
|
5
5
|
SHA512:
|
6
|
-
metadata.gz:
|
7
|
-
data.tar.gz:
|
6
|
+
metadata.gz: 26ca76ce7cf101b8ec3f0767b7c4fafa8edd6aa826622b22b861ebfc57c64baa7dec02693188ed57ef6756fd9f3919d274908ba5c975f79801197c7f9f26652c
|
7
|
+
data.tar.gz: 9ab2fa4115477cfb45359c8765ae3ee9540372fe4198f2534792bec94784b3471e28a9047767b2f4ec6e8848606675779147acfe7360d6cf89997a3cd5eb6842
|
checksums.yaml.gz.sig
CHANGED
Binary file
|
@@ -0,0 +1,166 @@
|
|
1
|
+
# Deployment
|
2
|
+
|
3
|
+
This guide explains how to use Falcon in production environments.
|
4
|
+
|
5
|
+
Falcon can be deployed into production either as a standalone application server, or as a virtual host routing to multiple applications. Both configurations can run behind a load balancer, but `falcon virtual` is designed to be zero-configuration deployment option.
|
6
|
+
|
7
|
+
## Falcon Serve
|
8
|
+
|
9
|
+
`falcon serve` is not designed for deployment because the command line interface is not guaranteed to be stable nor does it expose every possible configuration option.
|
10
|
+
|
11
|
+
## Falcon Hosts
|
12
|
+
|
13
|
+
`falcon host` is designed for deployment, and is the recommended way to deploy Falcon in production. It exposes a well defined interface for configuring services (web applications, job servers, etc).
|
14
|
+
|
15
|
+
### Configuration
|
16
|
+
|
17
|
+
`falcon host` loads configuration from the `falcon.rb` file in your application directory. This file contains configuration blocks which define how to host the application and any related services. This file should be executable and it invokes `falcon-host` which starts all defined services.
|
18
|
+
|
19
|
+
Here is a basic example which hosts a rack application:
|
20
|
+
|
21
|
+
~~~ ruby
|
22
|
+
#!/usr/bin/env falcon-host
|
23
|
+
# frozen_string_literal: true
|
24
|
+
|
25
|
+
require "falcon/environment/rack"
|
26
|
+
require "falcon/environment/lets_encrypt_tls"
|
27
|
+
require "falcon/environment/supervisor"
|
28
|
+
|
29
|
+
hostname = File.basename(__dir__)
|
30
|
+
service hostname do
|
31
|
+
include Falcon::Environment::Rack
|
32
|
+
include Falcon::Environment::LetsEncryptTLS
|
33
|
+
|
34
|
+
# Insert an in-memory cache in front of the application (using async-http-cache).
|
35
|
+
cache true
|
36
|
+
|
37
|
+
# Connect to the supervisor for monitoring.
|
38
|
+
include Async::Container::Supervisor::Supervised
|
39
|
+
end
|
40
|
+
|
41
|
+
service "supervisor" do
|
42
|
+
include Falcon::Environment::Supervisor
|
43
|
+
|
44
|
+
monitors do
|
45
|
+
[
|
46
|
+
MemoryMonitor.new(
|
47
|
+
# Check every 10 seconds:
|
48
|
+
interval: 10,
|
49
|
+
# Per-supervisor (cluster) limit:
|
50
|
+
total_size_limit: 1000*1024*1024,
|
51
|
+
# Per-process limit:
|
52
|
+
maximum_size_limit: 200*1024*1024
|
53
|
+
)
|
54
|
+
]
|
55
|
+
end
|
56
|
+
end
|
57
|
+
~~~
|
58
|
+
|
59
|
+
These configuration blocks are evaluated using the [async-service](https://github.com/socketry/async-service) gem. The supervisor is an independent service which monitors the health of the application and can restart it if necessary. Other services like background job processors can be added to the configuration.
|
60
|
+
|
61
|
+
### Environments
|
62
|
+
|
63
|
+
The service blocks define configuration that is loaded by the service layer to control how the service is run. The `service ... do` block defines the service name and the environment in which it runs. Different modules can be included to provide different functionality, such as `Falcon::Environment::Rack` for Rack applications, or `Falcon::Environment::LetsEncryptTLS` for automatic TLS certificate management.
|
64
|
+
|
65
|
+
### Application Configuration
|
66
|
+
|
67
|
+
The environment configuration is defined in the `Falcon::Environment` module. The {ruby Falcon::Environment::Application} environment supports the generic virtual host functionality, but you can customise any parts of the configuration, e.g. to bind a production host to `localhost:3000` using plaintext HTTP/2:
|
68
|
+
|
69
|
+
~~~ ruby
|
70
|
+
#!/usr/bin/env falcon host
|
71
|
+
# frozen_string_literal: true
|
72
|
+
|
73
|
+
require "falcon/environment/rack"
|
74
|
+
require "falcon/environment/supervisor"
|
75
|
+
|
76
|
+
hostname = File.basename(__dir__)
|
77
|
+
service hostname do
|
78
|
+
include Falcon::Environment::Rack
|
79
|
+
include Falcon::Environment::LetsEncryptTLS
|
80
|
+
|
81
|
+
endpoint do
|
82
|
+
Async::HTTP::Endpoint
|
83
|
+
.parse('http://localhost:3000')
|
84
|
+
.with(protocol: Async::HTTP::Protocol::HTTP2)
|
85
|
+
end
|
86
|
+
end
|
87
|
+
|
88
|
+
service "supervisor" do
|
89
|
+
include Falcon::Environment::Supervisor
|
90
|
+
end
|
91
|
+
~~~
|
92
|
+
|
93
|
+
You can verify this is working using `nghttp -v http://localhost:3000`.
|
94
|
+
|
95
|
+
#### Application Configuration Example for Heroku
|
96
|
+
|
97
|
+
Building on the examples above, the following is a full configuration example for Heroku:
|
98
|
+
|
99
|
+
~~~ bash
|
100
|
+
# Procfile
|
101
|
+
|
102
|
+
web: bundle exec falcon host
|
103
|
+
~~~
|
104
|
+
|
105
|
+
~~~ ruby
|
106
|
+
# falcon.rb
|
107
|
+
|
108
|
+
#!/usr/bin/env -S falcon host
|
109
|
+
# frozen_string_literal: true
|
110
|
+
|
111
|
+
require "falcon/environment/rack"
|
112
|
+
|
113
|
+
hostname = File.basename(__dir__)
|
114
|
+
|
115
|
+
service hostname do
|
116
|
+
include Falcon::Environment::Rack
|
117
|
+
|
118
|
+
# By default, Falcon uses Etc.nprocessors to set the count, which is likely incorrect on shared hosts like Heroku.
|
119
|
+
# Review the following for guidance about how to find the right value for your app:
|
120
|
+
# https://help.heroku.com/88G3XLA6/what-is-an-acceptable-amount-of-dyno-load
|
121
|
+
# https://devcenter.heroku.com/articles/deploying-rails-applications-with-the-puma-web-server#workers
|
122
|
+
count ENV.fetch("WEB_CONCURRENCY", 1).to_i
|
123
|
+
|
124
|
+
# If using count > 1 you may want to preload your app to reduce memory usage and increase performance:
|
125
|
+
preload "preload.rb"
|
126
|
+
|
127
|
+
# The default port should be 3000, but you can change it to match your Heroku configuration.
|
128
|
+
port {ENV.fetch("PORT", 3000).to_i}
|
129
|
+
|
130
|
+
# Heroku only supports HTTP/1.1 at the time of this writing. Review the following for possible updates in the future:
|
131
|
+
# https://devcenter.heroku.com/articles/http-routing#http-versions-supported
|
132
|
+
# https://github.com/heroku/roadmap/issues/34
|
133
|
+
endpoint do
|
134
|
+
Async::HTTP::Endpoint
|
135
|
+
.parse("http://0.0.0.0:#{port}")
|
136
|
+
.with(protocol: Async::HTTP::Protocol::HTTP11)
|
137
|
+
end
|
138
|
+
~~~
|
139
|
+
|
140
|
+
~~~ ruby
|
141
|
+
# preload.rb
|
142
|
+
|
143
|
+
# frozen_string_literal: true
|
144
|
+
|
145
|
+
require_relative "config/environment"
|
146
|
+
~~~
|
147
|
+
|
148
|
+
## Falcon Virtual
|
149
|
+
|
150
|
+
Falcon virtual provides a virtual host proxy and HTTP-to-HTTPS redirection for multiple applications. It is designed to be a zero-configuration deployment option, allowing you to run multiple applications on the same server.
|
151
|
+
|
152
|
+
~~~ mermaid
|
153
|
+
graph TD;
|
154
|
+
client[Client Browser] -->|TLS + HTTP/2 TCP| proxy["Falcon Proxy (SNI)"];
|
155
|
+
proxy -->|HTTP/2 UNIX PIPE| server["Application Server (Rack Compatible)"];
|
156
|
+
~~~
|
157
|
+
|
158
|
+
You need to create a `falcon.rb` configuration in the root of your applications, and start the virtual host:
|
159
|
+
|
160
|
+
~~~ bash
|
161
|
+
falcon virtual /srv/http/*/falcon.rb
|
162
|
+
~~~
|
163
|
+
|
164
|
+
By default, it binds to both HTTP and HTTPS ports, and automatically redirects HTTP requests to HTTPS. It also supports TLS SNI for resolving the certificates.
|
165
|
+
|
166
|
+
See the [docker example](https://github.com/socketry/falcon-virtual-docker-example) for a complete working example.
|
@@ -0,0 +1,13 @@
|
|
1
|
+
# Extended Features
|
2
|
+
|
3
|
+
This guide explains some of the extended features and functionality of Falcon.
|
4
|
+
|
5
|
+
## WebSockets
|
6
|
+
|
7
|
+
Falcon supports (partial and full) `rack.hijack` for both for HTTP/1 and HTTP/2 connections. You can use [async-websocket] in any controller layer to serve WebSocket connections.
|
8
|
+
|
9
|
+
[async-websocket]: https://github.com/socketry/async-websocket
|
10
|
+
|
11
|
+
## Early Hints
|
12
|
+
|
13
|
+
Falcon supports the `rack.early_hints` API when running over HTTP/2. You can [read more about the implementation and proposed interface](https://www.codeotaku.com/journal/2019-02/falcon-early-hints/index).
|
@@ -0,0 +1,73 @@
|
|
1
|
+
# Getting Started
|
2
|
+
|
3
|
+
This guide gives an overview of how to use Falcon for running Ruby web applications.
|
4
|
+
|
5
|
+
## Installation
|
6
|
+
|
7
|
+
Add the gem to your project:
|
8
|
+
|
9
|
+
~~~ bash
|
10
|
+
$ bundle add falcon
|
11
|
+
~~~
|
12
|
+
|
13
|
+
Or, if you prefer, install it globally:
|
14
|
+
|
15
|
+
~~~ bash
|
16
|
+
$ gem install falcon
|
17
|
+
~~~
|
18
|
+
|
19
|
+
## Core Concepts
|
20
|
+
|
21
|
+
Falcon is a high-performance web server for Ruby. It is designed to be fast, lightweight, and easy to use.
|
22
|
+
|
23
|
+
- **Asynchronous**: Falcon is built on top of the fiber scheduler and the [async gem](https://github.com/socketry/async) which allow it to handle thousands of connections concurrently.
|
24
|
+
- **Rack Compatible**: Falcon is a Rack server. It can run any Rack application, including Rails, Sinatra, and Roda with no modifications.
|
25
|
+
- **Secure**: Falcon supports TLS out of the box. It can generate self-signed certificates for localhost.
|
26
|
+
- **HTTP/2**: Falcon is build on top of the [async-http gem](https://github.com/socketry/async-http) which supports HTTP/2. It can serve multiple requests over a single connection.
|
27
|
+
- **WebSockets**: Falcon supports WebSockets using the [async-websocket gem](https://github.com/socketry/async-websocket) which takes advantage of Rack 3 streaming responses. You can build complex real-time applications with ease.
|
28
|
+
|
29
|
+
### Rack
|
30
|
+
|
31
|
+
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:
|
32
|
+
|
33
|
+
~~~ ruby
|
34
|
+
# config.ru
|
35
|
+
|
36
|
+
run do |env|
|
37
|
+
[200, {'Content-Type' => 'text/plain'}, ['Hello, World!']]
|
38
|
+
end
|
39
|
+
~~~
|
40
|
+
|
41
|
+
Then run the application with:
|
42
|
+
|
43
|
+
~~~ bash
|
44
|
+
$ falcon serve
|
45
|
+
~~~
|
46
|
+
|
47
|
+
## Running a Local Server
|
48
|
+
|
49
|
+
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.
|
50
|
+
|
51
|
+
To run on a different port:
|
52
|
+
|
53
|
+
~~~ bash
|
54
|
+
$ falcon serve --port 3000
|
55
|
+
~~~
|
56
|
+
|
57
|
+
### Unencrypted HTTP
|
58
|
+
|
59
|
+
If you want to run Falcon without TLS, you can use the `--bind` option to bind to an unencrypted HTTP endpoint:
|
60
|
+
|
61
|
+
~~~ bash
|
62
|
+
$ falcon serve --bind http://localhost:3000
|
63
|
+
~~~
|
64
|
+
|
65
|
+
### Using with Rackup
|
66
|
+
|
67
|
+
You can invoke Falcon via `rackup`:
|
68
|
+
|
69
|
+
~~~ bash
|
70
|
+
$ rackup --server falcon
|
71
|
+
~~~
|
72
|
+
|
73
|
+
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.
|
@@ -0,0 +1,23 @@
|
|
1
|
+
# How It Works
|
2
|
+
|
3
|
+
This guide gives an overview of how Falcon handles an incoming web request.
|
4
|
+
|
5
|
+
## Overview
|
6
|
+
|
7
|
+
When you run `falcon serve`, Falcon creates a {ruby Falcon::Controller::Serve} which is used to create several worker threads or processes. Before starting the workers, the controller binds to an endpoint (e.g. a local unix socket, a TCP network socket, etc). The workers are spawned and receive this bound endpoint, and start accepting connections.
|
8
|
+
|
9
|
+
The workers individually load a copy of your rack application. These applications are wrapped using {ruby Falcon::Adapters::Rack} which modifies the incoming {ruby Protocol::HTTP::Request} object into an `env` object suitable for your application. It also handles converting the output of your rack application `[status, headers, body]` into an instance of {ruby Falcon::Adapters::Response} which is derived from {ruby Protocol::HTTP::Response}.
|
10
|
+
|
11
|
+
See the [protocol-http documentation](https://socketry.github.io/protocol-http/) for more details on how it works.
|
12
|
+
|
13
|
+
## Server
|
14
|
+
|
15
|
+
The server itself is mostly implemented by {ruby Async::HTTP::Server} which in turn depends on the `protocol-http` gems for the actual protocol implementations. Therefore, Falcon is primarily a bridge between the underlying protocol objects and the Rack interface.
|
16
|
+
|
17
|
+
See the [async-http documentation](https://socketry.github.io/async-http/) for more details on how it works.
|
18
|
+
|
19
|
+
## Protocol::Rack
|
20
|
+
|
21
|
+
Falcon uses the `protocol-rack` gem to provide a Rack interface for the HTTP protocol. This allows you to run any Rack-compatible application with Falcon. However, Falcon itself is not a Rack server, but rather an HTTP server that can run Rack applications.
|
22
|
+
|
23
|
+
See the [protocol-rack documentation](https://socketry.github.io/protocol-rack/) for more details on how it works.
|
data/context/index.yaml
ADDED
@@ -0,0 +1,34 @@
|
|
1
|
+
# Automatically generated context index for Utopia::Project guides.
|
2
|
+
# Do not edit then files in this directory directly, instead edit the guides and then run `bake utopia:project:agent:context:update`.
|
3
|
+
---
|
4
|
+
getting-started:
|
5
|
+
title: Getting Started
|
6
|
+
order: 1
|
7
|
+
description: This guide gives an overview of how to use Falcon for running Ruby
|
8
|
+
web applications.
|
9
|
+
rails-integration:
|
10
|
+
title: Rails Integration
|
11
|
+
order: 2
|
12
|
+
description: This guide explains how to host Rails applications with Falcon.
|
13
|
+
deployment:
|
14
|
+
title: Deployment
|
15
|
+
order: 3
|
16
|
+
description: This guide explains how to use Falcon in production environments.
|
17
|
+
performance-tuning:
|
18
|
+
title: Performance Tuning
|
19
|
+
order: 4
|
20
|
+
description: This guide explains the performance characteristics of Falcon.
|
21
|
+
websockets:
|
22
|
+
title: WebSockets
|
23
|
+
order: 5
|
24
|
+
description: This guide explains how to use WebSockets with Falcon.
|
25
|
+
interim-responses:
|
26
|
+
title: Interim Responses
|
27
|
+
order: 6
|
28
|
+
description: This guide explains how to use interim responses in Falcon to send
|
29
|
+
early hints to the client.
|
30
|
+
how-it-works:
|
31
|
+
title: How It Works
|
32
|
+
order: 10
|
33
|
+
description: This guide gives an overview of how Falcon handles an incoming web
|
34
|
+
request.
|
@@ -0,0 +1,19 @@
|
|
1
|
+
# Interim Responses
|
2
|
+
|
3
|
+
This guide explains how to use interim responses in Falcon to send early hints to the client.
|
4
|
+
|
5
|
+
## Overview
|
6
|
+
|
7
|
+
Interim responses allow the server to send early hints to the client before the final response is ready. This can be useful for preloading resources or providing immediate feedback. They can also be used as a response to the `expect` header, allowing the server to indicate that it is ready to process the request without waiting for the full request body.
|
8
|
+
|
9
|
+
Since Rack does not currently have a specificatio for interim responses, you need to access the underlying HTTP response object directly.
|
10
|
+
|
11
|
+
~~~ruby
|
12
|
+
# config.ru
|
13
|
+
|
14
|
+
run do |env|
|
15
|
+
if request = env["protocol.http.request"]
|
16
|
+
request.send_interim_response(103, [["link", "</style.css>; rel=preload; as=style"]])
|
17
|
+
end
|
18
|
+
end
|
19
|
+
~~~
|
@@ -0,0 +1,19 @@
|
|
1
|
+
# Interim Responses
|
2
|
+
|
3
|
+
This guide explains how to use interim responses in Falcon to send early hints to the client.
|
4
|
+
|
5
|
+
## Overview
|
6
|
+
|
7
|
+
Interim responses allow the server to send early hints to the client before the final response is ready. This can be useful for preloading resources or providing immediate feedback. They can also be used as a response to the `expect` header, allowing the server to indicate that it is ready to process the request without waiting for the full request body.
|
8
|
+
|
9
|
+
Since Rack does not currently have a specificatio for interim responses, you need to access the underlying HTTP response object directly.
|
10
|
+
|
11
|
+
~~~ruby
|
12
|
+
# config.ru
|
13
|
+
|
14
|
+
run do |env|
|
15
|
+
if request = env["protocol.http.request"]
|
16
|
+
request.send_interim_response(103, [["link", "</style.css>; rel=preload; as=style"]])
|
17
|
+
end
|
18
|
+
end
|
19
|
+
~~~
|
@@ -0,0 +1,62 @@
|
|
1
|
+
# Performance Tuning
|
2
|
+
|
3
|
+
This guide explains the performance characteristics of Falcon.
|
4
|
+
|
5
|
+
## Scalability
|
6
|
+
|
7
|
+
Falcon uses an asynchronous event-driven reactor to provide non-blocking IO. It uses one Fiber per request, which have minimal overhead. Falcon can handle a large number of in-flight requests including long-running connections like websockets, HTTP/2 streaming, etc.
|
8
|
+
|
9
|
+
- [Improving Ruby Concurrency](https://www.codeotaku.com/journal/2018-06/improving-ruby-concurrency/index#performance) – Comparison of Falcon and Puma.
|
10
|
+
|
11
|
+
### Falcon Benchmark
|
12
|
+
|
13
|
+
The [falcon-benchmark] suite looks at how various servers respond to different levels of concurrency across several sample applications.
|
14
|
+
|
15
|
+
[falcon-benchmark]: https://github.com/socketry/falcon-benchmark
|
16
|
+
|
17
|
+
## Memory Usage
|
18
|
+
|
19
|
+
Falcon uses [async-container] to start multiple copies of your application. Each instance of your application is isolated by default for maximum fault-tolerance. However, this can lead to increased memory usage. Preloading parts of your application reduce this overhead and in addition can improve instance start-up time. To understand your application memory usage, you should use [process-metrics] which take into account memory shared between processes.
|
20
|
+
|
21
|
+
[async-container]: https://github.com/socketry/async-container
|
22
|
+
[process-metrics]: https://github.com/socketry/process-metrics
|
23
|
+
|
24
|
+
### Preloading
|
25
|
+
|
26
|
+
Falcon offers two mechanisms for preloading code.
|
27
|
+
|
28
|
+
#### Preloading Gems
|
29
|
+
|
30
|
+
By default, falcon will load all gems in the `preload` group:
|
31
|
+
|
32
|
+
~~~ ruby
|
33
|
+
# In gems.rb:
|
34
|
+
|
35
|
+
source "https://rubygems.org"
|
36
|
+
|
37
|
+
group :preload do
|
38
|
+
# List any gems you want to be pre-loaded into the falcon process before forking.
|
39
|
+
end
|
40
|
+
~~~
|
41
|
+
|
42
|
+
#### Preloading Files
|
43
|
+
|
44
|
+
Create a file in your application called `preload.rb`. You can put this file anywhere in your application.
|
45
|
+
|
46
|
+
##### Falcon Serve
|
47
|
+
|
48
|
+
`falcon serve` has a `--preload` option which accepts the path to this file.
|
49
|
+
|
50
|
+
##### Falcon Host
|
51
|
+
|
52
|
+
`falcon.rb` applications may have a `preload` configuration option.
|
53
|
+
|
54
|
+
## System Limitations
|
55
|
+
|
56
|
+
If you are expecting to handle many simultaneous connections, please ensure you configure your file limits correctly.
|
57
|
+
|
58
|
+
~~~
|
59
|
+
Errno::EMFILE: Too many open files - accept(2)
|
60
|
+
~~~
|
61
|
+
|
62
|
+
This means that your system is limiting the number of files that can be opened by falcon. Please check the `ulimit` of your system and set it appropriately.
|
@@ -0,0 +1,90 @@
|
|
1
|
+
# Rails Integration
|
2
|
+
|
3
|
+
This guide explains how to host Rails applications with Falcon.
|
4
|
+
|
5
|
+
**We strongly recommend using the latest stable release of Rails with Falcon.**
|
6
|
+
|
7
|
+
We now recommend using the `Falcon::Rails` gem for Rails integration. This gem provides a simple way to configure Falcon as the web server for your Rails application, and includes many conveniences for running Rails with Falcon.
|
8
|
+
|
9
|
+
~~~
|
10
|
+
> bundle add falcon-rails
|
11
|
+
~~~
|
12
|
+
|
13
|
+
It also includes detailed documentation for [common tasks and configurations](https://socketry.github.io/falcon-rails/).
|
14
|
+
|
15
|
+
## Usage
|
16
|
+
|
17
|
+
Because Rails apps are built on top of Rack, they are compatible with Falcon.
|
18
|
+
|
19
|
+
1. Add `gem "falcon"` to your `Gemfile` and perhaps remove `gem "puma"` once you are satisfied with the change.
|
20
|
+
2. Run `falcon serve` to start a local development server.
|
21
|
+
|
22
|
+
Falcon assumes HTTPS by default (so that browsers can use HTTP2). To run under HTTP in development you can bind it to an explicit scheme, host and port:
|
23
|
+
|
24
|
+
~~~ bash
|
25
|
+
falcon serve -b http://localhost:3000
|
26
|
+
~~~
|
27
|
+
|
28
|
+
### Self-signed Development Certificates
|
29
|
+
|
30
|
+
The [localhost gem](https://github.com/socketry/localhost) is used to generate self-signed certificates for local development. This allows you to run Falcon with HTTPS in development without needing to set up a real certificate authority. However, you must still install the development certificate to avoid security warnings in your browser:
|
31
|
+
|
32
|
+
~~~bash
|
33
|
+
> bundle exec bake localhost:install
|
34
|
+
~~~
|
35
|
+
|
36
|
+
### Production
|
37
|
+
|
38
|
+
The `falcon serve` command is only intended to be used for local development. We recommend you use `falcon host` for production deployments.
|
39
|
+
|
40
|
+
#### Falcon Host Configuration File
|
41
|
+
|
42
|
+
Create a `falcon.rb` file in the root of your Rails application. This file will be used to configure the Falcon server for production. The following example binds HTTP/1 to port 3000 as is common for Rails applications:
|
43
|
+
|
44
|
+
~~~ ruby
|
45
|
+
#!/usr/bin/env -S falcon-host
|
46
|
+
# frozen_string_literal: true
|
47
|
+
|
48
|
+
require "falcon/environment/rack"
|
49
|
+
|
50
|
+
hostname = File.basename(__dir__)
|
51
|
+
|
52
|
+
service hostname do
|
53
|
+
include Falcon::Environment::Rack
|
54
|
+
|
55
|
+
# This file will be loaded in the main process before forking.
|
56
|
+
preload "preload.rb"
|
57
|
+
|
58
|
+
# Default to port 3000 unless otherwise specified.
|
59
|
+
port {ENV.fetch("PORT", 3000).to_i}
|
60
|
+
|
61
|
+
# Default to HTTP/1.1.
|
62
|
+
endpoint do
|
63
|
+
Async::HTTP::Endpoint
|
64
|
+
.parse("http://0.0.0.0:#{port}")
|
65
|
+
.with(protocol: Async::HTTP::Protocol::HTTP11)
|
66
|
+
end
|
67
|
+
end
|
68
|
+
~~~
|
69
|
+
|
70
|
+
#### Preloading Rails
|
71
|
+
|
72
|
+
Preloading is a technique used to load your Rails application into memory before forking worker processes. This can significantly improve performance by reducing the time it takes to start each worker.
|
73
|
+
|
74
|
+
~~~ ruby
|
75
|
+
# frozen_string_literal: true
|
76
|
+
|
77
|
+
require_relative "config/environment"
|
78
|
+
~~~
|
79
|
+
|
80
|
+
#### Running the Production Server
|
81
|
+
|
82
|
+
To run the production server, make sure your `falcon.rb` is executable and then run it:
|
83
|
+
|
84
|
+
~~~ bash
|
85
|
+
> bundle exec falcon.rb
|
86
|
+
~~~
|
87
|
+
|
88
|
+
## Isolation Level
|
89
|
+
|
90
|
+
Rails provides the ability to change its internal isolation level from threads (default) to fibers. When you use `falcon` with Rails, it will automatically set the isolation level to fibers as Falcon provides the appropriate Railtie.
|
@@ -0,0 +1,23 @@
|
|
1
|
+
# WebSockets
|
2
|
+
|
3
|
+
This guide explains how to use WebSockets with Falcon.
|
4
|
+
|
5
|
+
## Overview
|
6
|
+
|
7
|
+
Falcon supports WebSockets using the [async-websocket gem](https://github.com/socketry/async-websocket). This allows you to build real-time applications that can handle bidirectional communication between the server and clients.
|
8
|
+
|
9
|
+
~~~ruby
|
10
|
+
# config.ru
|
11
|
+
|
12
|
+
require "async/websocket/adapter/rack"
|
13
|
+
|
14
|
+
run do |env|
|
15
|
+
Async::WebSocket::Adapters::Rack.open(env, protocols: ['ws']) do |connection|
|
16
|
+
# Simple echo server:
|
17
|
+
while message = connection.read
|
18
|
+
connection.write(message)
|
19
|
+
connection.flush
|
20
|
+
end
|
21
|
+
end or [200, {}, ["Hello World"]]
|
22
|
+
end
|
23
|
+
~~~
|
data/lib/falcon/version.rb
CHANGED
data/readme.md
CHANGED
@@ -29,22 +29,32 @@ Please visit [Socketry.io](https://socketry.io) to register and subscribe.
|
|
29
29
|
|
30
30
|
Please see the [project documentation](https://socketry.github.io/falcon/) for more details.
|
31
31
|
|
32
|
-
- [Getting Started](https://socketry.github.io/falcon/guides/getting-started/index) - This guide
|
32
|
+
- [Getting Started](https://socketry.github.io/falcon/guides/getting-started/index) - This guide gives an overview of how to use Falcon for running Ruby web applications.
|
33
33
|
|
34
34
|
- [Rails Integration](https://socketry.github.io/falcon/guides/rails-integration/index) - This guide explains how to host Rails applications with Falcon.
|
35
35
|
|
36
36
|
- [Deployment](https://socketry.github.io/falcon/guides/deployment/index) - This guide explains how to use Falcon in production environments.
|
37
37
|
|
38
|
-
- [Extended Features](https://socketry.github.io/falcon/guides/extended-features/index) - This guide explains some of the extended features and functionality of Falcon.
|
39
|
-
|
40
38
|
- [Performance Tuning](https://socketry.github.io/falcon/guides/performance-tuning/index) - This guide explains the performance characteristics of Falcon.
|
41
39
|
|
40
|
+
- [WebSockets](https://socketry.github.io/falcon/guides/websockets/index) - This guide explains how to use WebSockets with Falcon.
|
41
|
+
|
42
|
+
- [Interim Responses](https://socketry.github.io/falcon/guides/interim-responses/index) - This guide explains how to use interim responses in Falcon to send early hints to the client.
|
43
|
+
|
42
44
|
- [How It Works](https://socketry.github.io/falcon/guides/how-it-works/index) - This guide gives an overview of how Falcon handles an incoming web request.
|
43
45
|
|
44
46
|
## Releases
|
45
47
|
|
46
48
|
Please see the [project releases](https://socketry.github.io/falcon/releases/index) for all releases.
|
47
49
|
|
50
|
+
### v0.52.0
|
51
|
+
|
52
|
+
- Modernized codebase and dropped support for Ruby v3.1.
|
53
|
+
- Improved Rails integration documentation.
|
54
|
+
- Added extra logging of `RUBY_DESCRIPTION`.
|
55
|
+
- Minor documentation improvements.
|
56
|
+
- Agent context is now available, via the [`agent-context` gem](https://github.com/ioquatix/agent-context).
|
57
|
+
|
48
58
|
### v0.51.0
|
49
59
|
|
50
60
|
- Introduce <code class="language-ruby">Falcon::Environment::Server\#make\_server</code> which gives you full control over the server creation process.
|
data/releases.md
CHANGED
@@ -1,5 +1,13 @@
|
|
1
1
|
# Releases
|
2
2
|
|
3
|
+
## v0.52.0
|
4
|
+
|
5
|
+
- Modernized codebase and dropped support for Ruby v3.1.
|
6
|
+
- Improved Rails integration documentation.
|
7
|
+
- Added extra logging of `RUBY_DESCRIPTION`.
|
8
|
+
- Minor documentation improvements.
|
9
|
+
- Agent context is now available, via the [`agent-context` gem](https://github.com/ioquatix/agent-context).
|
10
|
+
|
3
11
|
## v0.51.0
|
4
12
|
|
5
13
|
- Introduce {ruby Falcon::Environment::Server\#make\_server} which gives you full control over the server creation process.
|
data.tar.gz.sig
CHANGED
Binary file
|
metadata
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
--- !ruby/object:Gem::Specification
|
2
2
|
name: falcon
|
3
3
|
version: !ruby/object:Gem::Version
|
4
|
-
version: 0.52.
|
4
|
+
version: 0.52.1
|
5
5
|
platform: ruby
|
6
6
|
authors:
|
7
7
|
- Samuel Williams
|
@@ -241,6 +241,16 @@ files:
|
|
241
241
|
- bake/falcon/supervisor.rb
|
242
242
|
- bin/falcon
|
243
243
|
- bin/falcon-host
|
244
|
+
- context/deployment.md
|
245
|
+
- context/extended-features.md
|
246
|
+
- context/getting-started.md
|
247
|
+
- context/how-it-works.md
|
248
|
+
- context/index.yaml
|
249
|
+
- context/interim-response.md
|
250
|
+
- context/interim-responses.md
|
251
|
+
- context/performance-tuning.md
|
252
|
+
- context/rails-integration.md
|
253
|
+
- context/websockets.md
|
244
254
|
- lib/falcon.rb
|
245
255
|
- lib/falcon/command.rb
|
246
256
|
- lib/falcon/command/host.rb
|
@@ -301,7 +311,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
|
|
301
311
|
- !ruby/object:Gem::Version
|
302
312
|
version: '0'
|
303
313
|
requirements: []
|
304
|
-
rubygems_version: 3.6.
|
314
|
+
rubygems_version: 3.6.9
|
305
315
|
specification_version: 4
|
306
316
|
summary: A fast, asynchronous, rack-compatible web server.
|
307
317
|
test_files: []
|
metadata.gz.sig
CHANGED
Binary file
|