Updated documentation.

Author: ioquatix

context/how-it-works.md

@@ -8,6 +8,16 @@ When you run `falcon serve`, Falcon creates a {ruby Falcon::Controller::Serve} w
 
 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}.
 
+See the [protocol-http documentation](https://socketry.github.io/protocol-http/) for more details on how it works.
+
 ## Server
 
 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.
+
+See the [async-http documentation](https://socketry.github.io/async-http/) for more details on how it works.
+
+## Protocol::Rack
+
+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.
+
+See the [protocol-rack documentation](https://socketry.github.io/protocol-rack/) for more details on how it works.

context/index.yaml

@@ -14,17 +14,21 @@ deployment:
   title: Deployment
   order: 3
   description: This guide explains how to use Falcon in production environments.
-extended-features:
-  title: Extended Features
-  order: 4
-  description: This guide explains some of the extended features and functionality
-    of Falcon.
 performance-tuning:
   title: Performance Tuning
-  order: 5
+  order: 4
   description: This guide explains the performance characteristics of Falcon.
+websockets:
+  title: WebSockets
+  order: 5
+  description: This guide explains how to use WebSockets with Falcon.
+interim-responses:
+  title: Interim Responses
+  order: 6
+  description: This guide explains how to use interim responses in Falcon to send
+    early hints to the client.
 how-it-works:
   title: How It Works
-  order: 6
+  order: 10
   description: This guide gives an overview of how Falcon handles an incoming web
     request.

context/interim-response.md

@@ -0,0 +1,19 @@
+# Interim Responses
+
+This guide explains how to use interim responses in Falcon to send early hints to the client.
+
+## Overview
+
+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.
+
+Since Rack does not currently have a specificatio for interim responses, you need to access the underlying HTTP response object directly.
+
+~~~ruby
+# config.ru
+
+run do |env|
+	if request = env["protocol.http.request"]
+		request.send_interim_response(103, [["link", "</style.css>; rel=preload; as=style"]])
+	end
+end
+~~~

context/interim-responses.md

@@ -0,0 +1,19 @@
+# Interim Responses
+
+This guide explains how to use interim responses in Falcon to send early hints to the client.
+
+## Overview
+
+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.
+
+Since Rack does not currently have a specificatio for interim responses, you need to access the underlying HTTP response object directly.
+
+~~~ruby
+# config.ru
+
+run do |env|
+	if request = env["protocol.http.request"]
+		request.send_interim_response(103, [["link", "</style.css>; rel=preload; as=style"]])
+	end
+end
+~~~

context/rails-integration.md

@@ -2,31 +2,47 @@
 
 This guide explains how to host Rails applications with Falcon.
 
-**We strongly recommend using the latest stable release of Rails with Falcon.** The integration is much smoother and you will benefit from the latest features and bug fixes. This guide is primarily intended for users of Rails 8.0 and later.
+**We strongly recommend using the latest stable release of Rails with Falcon.**
 
-## Integration with Rails
+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.
+
+~~~
+> bundle add falcon-rails
+~~~
+
+It also includes detailed documentation for [common tasks and configurations](https://socketry.github.io/falcon-rails/).
+
+## Usage
 
 Because Rails apps are built on top of Rack, they are compatible with Falcon.
 
 1. Add `gem "falcon"` to your `Gemfile` and perhaps remove `gem "puma"` once you are satisfied with the change.
 2. Run `falcon serve` to start a local development server.
 
-We do not recommend using Rails older than v7.1 with Falcon. If you are using an older version of Rails, you should upgrade to the latest version before using Falcon.
-
 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:
 
 ~~~ bash
 falcon serve -b http://localhost:3000
 ~~~
 
+### Self-signed Development Certificates
+
+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:
+
+~~~bash
+> bundle exec bake localhost:install
+~~~
+
 ### Production
 
-The `falcon serve` command is only intended to be used for local development. Follow these steps to run a production Rails app with Falcon:
+The `falcon serve` command is only intended to be used for local development. We recommend you use `falcon host` for production deployments.
 
-1. Create a `falcon.rb` file
+#### Falcon Host Configuration File
+
+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:
 
 ~~~ ruby
-#!/usr/bin/env -S falcon host
+#!/usr/bin/env -S falcon-host
 # frozen_string_literal: true
 
 require "falcon/environment/rack"
@@ -51,25 +67,24 @@ service hostname do
 end
 ~~~
 
-2. Create a `preload.rb` file
+#### Preloading Rails
+
+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.
 
 ~~~ ruby
 # frozen_string_literal: true
 
 require_relative "config/environment"
 ~~~
 
-3. Run the production server with `bundle exec falcon host`
-
-
-## Isolation Level
+#### Running the Production Server
 
-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.
+To run the production server, make sure your `falcon.rb` is executable and then run it:
 
-## ActionCable
-
-Falcon fully supports ActionCable with the [`Async::Cable` adapter](https://github.com/socketry/async-cable).
+~~~ bash
+> bundle exec falcon.rb
+~~~
 
-## ActiveJob
+## Isolation Level
 
-Falcon fully supports ActiveJob with the [`Async::Job` adapter](https://github.com/socketry/async-job-adapter-active_job).
+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.

context/websockets.md

@@ -0,0 +1,23 @@
+# WebSockets
+
+This guide explains how to use WebSockets with Falcon.
+
+## Overview
+
+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.
+
+~~~ruby
+# config.ru
+
+require "async/websocket/adapter/rack"
+
+run do |env|
+	Async::WebSocket::Adapters::Rack.open(env, protocols: ['ws']) do |connection|
+		# Simple echo server:
+		while message = connection.read
+			connection.write(message)
+			connection.flush
+		end
+	end or [200, {}, ["Hello World"]]
+end
+~~~

guides/extended-features/readme.md

@@ -8,6 +8,16 @@ When you run `falcon serve`, Falcon creates a {ruby Falcon::Controller::Serve} w
 
 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}.
 
+See the [protocol-http documentation](https://socketry.github.io/protocol-http/) for more details on how it works.
+
 ## Server
 
 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.
+
+See the [async-http documentation](https://socketry.github.io/async-http/) for more details on how it works.
+
+## Protocol::Rack
+
+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.
+
+See the [protocol-rack documentation](https://socketry.github.io/protocol-rack/) for more details on how it works.

guides/how-it-works/readme.md

@@ -0,0 +1,19 @@
+# Interim Responses
+
+This guide explains how to use interim responses in Falcon to send early hints to the client.
+
+## Overview
+
+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.
+
+Since Rack does not currently have a specificatio for interim responses, you need to access the underlying HTTP response object directly.
+
+~~~ruby
+# config.ru
+
+run do |env|
+	if request = env["protocol.http.request"]
+		request.send_interim_response(103, [["link", "</style.css>; rel=preload; as=style"]])
+	end
+end
+~~~

guides/interim-responses/readme.md

@@ -4,9 +4,11 @@ rails-integration:
   order: 2
 deployment:
   order: 3
-extended-features:
-  order: 4
 performance-tuning:
+  order: 4
+websockets:
   order: 5
-how-it-works:
+interim-responses:
   order: 6
+how-it-works:
+  order: 10