Minor documentation improvements.

Author: ioquatix

context/deployment.md

@@ -16,7 +16,7 @@ Falcon can be deployed into production either as a standalone application server
 
 `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.
 
-Here is a basic example which hosts a rack application using :
+Here is a basic example which hosts a rack application:
 
 ~~~ ruby
 #!/usr/bin/env falcon-host
@@ -33,29 +33,134 @@ service hostname do
 
 	# Insert an in-memory cache in front of the application (using async-http-cache).
 	cache true
+	
+	# Connect to the supervisor for monitoring.
+	include Async::Container::Supervisor::Supervised
 end
 
 service "supervisor" do
 	include Falcon::Environment::Supervisor
+	
+	monitors do
+		[
+			MemoryMonitor.new(
+				# Check every 10 seconds:
+				interval: 10,
+				# Per-supervisor (cluster) limit:
+				total_size_limit: 1000*1024*1024,
+				# Per-process limit:
+				maximum_size_limit: 200*1024*1024
+			)
+		]
+	end
 end
 ~~~
 
 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.
 
 ### Environments
 
-The service blocks define configuration that is loaded by the serivce 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.
+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.
+
+### Application Configuration
+
+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:
+
+~~~ ruby
+#!/usr/bin/env falcon host
+# frozen_string_literal: true
+
+require "falcon/environment/rack"
+require "falcon/environment/supervisor"
+
+hostname = File.basename(__dir__)
+service hostname do
+	include Falcon::Environment::Rack
+	include Falcon::Environment::LetsEncryptTLS
+
+	endpoint do
+		Async::HTTP::Endpoint
+			.parse('http://localhost:3000')
+			.with(protocol: Async::HTTP::Protocol::HTTP2)
+	end
+end
+
+service "supervisor" do
+	include Falcon::Environment::Supervisor
+end
+~~~
+
+You can verify this is working using `nghttp -v http://localhost:3000`.
+
+#### Application Configuration Example for Heroku
+
+Building on the examples above, the following is a full configuration example for Heroku:
+
+~~~ bash
+# Procfile
+
+web: bundle exec falcon host
+~~~
+
+~~~ ruby
+# falcon.rb
+
+#!/usr/bin/env -S falcon host
+# frozen_string_literal: true
+
+require "falcon/environment/rack"
+
+hostname = File.basename(__dir__)
+
+service hostname do
+	include Falcon::Environment::Rack
+	
+	# By default, Falcon uses Etc.nprocessors to set the count, which is likely incorrect on shared hosts like Heroku.
+	# Review the following for guidance about how to find the right value for your app:
+	# https://help.heroku.com/88G3XLA6/what-is-an-acceptable-amount-of-dyno-load
+	# https://devcenter.heroku.com/articles/deploying-rails-applications-with-the-puma-web-server#workers
+	count ENV.fetch("WEB_CONCURRENCY", 1).to_i
+	
+	# If using count > 1 you may want to preload your app to reduce memory usage and increase performance:
+	preload "preload.rb"
+	
+	# The default port should be 3000, but you can change it to match your Heroku configuration.
+	port {ENV.fetch("PORT", 3000).to_i}
+	
+	# Heroku only supports HTTP/1.1 at the time of this writing. Review the following for possible updates in the future:
+	# https://devcenter.heroku.com/articles/http-routing#http-versions-supported
+	# https://github.com/heroku/roadmap/issues/34
+	endpoint do
+		Async::HTTP::Endpoint
+			.parse("http://0.0.0.0:#{port}")
+			.with(protocol: Async::HTTP::Protocol::HTTP11)
+	end
+~~~
+
+~~~ ruby
+# preload.rb
+
+# frozen_string_literal: true
+
+require_relative "config/environment"
+~~~
 
 ## Falcon Virtual
 
 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.
 
+~~~ mermaid
+graph TD;
+	client[Client Browser] -->|TLS + HTTP/2 TCP| proxy["Falcon Proxy (SNI)"];
+	proxy -->|HTTP/2 UNIX PIPE| server["Application Server (Rack Compatible)"];
+~~~
+
 You need to create a `falcon.rb` configuration in the root of your applications, and start the virtual host:
 
 ~~~ bash
 falcon virtual /srv/http/*/falcon.rb
 ~~~
 
-By default, it binds to both HTTP and HTTPS ports, and automatically redirects HTTP requests to HTTPS. It also supports automatic TLS certificate management using Let's Encrypt.
+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.
 
 See the [docker example](https://github.com/socketry/falcon-virtual-docker-example) for a complete working example.

context/extended-features.md

@@ -0,0 +1,13 @@
+# Extended Features
+
+This guide explains some of the extended features and functionality of Falcon.
+
+## WebSockets
+
+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.
+
+[async-websocket]: https://github.com/socketry/async-websocket
+
+## Early Hints
+
+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).

context/getting-started.md

@@ -0,0 +1,73 @@
+# Getting Started
+
+This guide gives an overview of how to use Falcon for running Ruby web applications.
+
+## Installation
+
+Add the gem to your project:
+
+~~~ bash
+$ bundle add falcon
+~~~
+
+Or, if you prefer, install it globally:
+
+~~~ bash
+$ 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](https://github.com/socketry/async) 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](https://github.com/socketry/async-http) which supports HTTP/2. It can serve multiple requests over a single connection.
+- **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.
+
+### 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:
+
+~~~ ruby
+# config.ru
+
+run do |env|
+	[200, {'Content-Type' => 'text/plain'}, ['Hello, World!']]
+end
+~~~
+
+Then run the application with:
+
+~~~ bash
+$ falcon serve
+~~~
+
+## 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:
+
+~~~ bash
+$ 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:
+
+~~~ bash
+$ falcon serve --bind http://localhost:3000
+~~~
+
+### Using with Rackup
+
+You can invoke Falcon via `rackup`:
+
+~~~ bash
+$ 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.

context/how-it-works.md

@@ -0,0 +1,13 @@
+# How It Works
+
+This guide gives an overview of how Falcon handles an incoming web request.
+
+## Overview
+
+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.
+
+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}.
+
+## 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.

context/index.yaml

@@ -0,0 +1,30 @@
+# Automatically generated context index for Utopia::Project guides.
+# Do not edit then files in this directory directly, instead edit the guides and then run `bake utopia:project:agent:context:update`.
+---
+getting-started:
+  title: Getting Started
+  order: 1
+  description: This guide gives an overview of how to use Falcon for running Ruby
+    web applications.
+rails-integration:
+  title: Rails Integration
+  order: 2
+  description: This guide explains how to host Rails applications with Falcon.
+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
+  description: This guide explains the performance characteristics of Falcon.
+how-it-works:
+  title: How It Works
+  order: 6
+  description: This guide gives an overview of how Falcon handles an incoming web
+    request.

context/performance-tuning.md

@@ -0,0 +1,62 @@
+# Performance Tuning
+
+This guide explains the performance characteristics of Falcon.
+
+## Scalability
+
+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.
+
+- [Improving Ruby Concurrency](https://www.codeotaku.com/journal/2018-06/improving-ruby-concurrency/index#performance) – Comparison of Falcon and Puma.
+
+### Falcon Benchmark
+
+The [falcon-benchmark] suite looks at how various servers respond to different levels of concurrency across several sample applications.
+
+[falcon-benchmark]: https://github.com/socketry/falcon-benchmark
+
+## Memory Usage
+
+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.
+
+[async-container]: https://github.com/socketry/async-container
+[process-metrics]: https://github.com/socketry/process-metrics
+
+### Preloading
+
+Falcon offers two mechanisms for preloading code.
+
+#### Preloading Gems
+
+By default, falcon will load all gems in the `preload` group:
+
+~~~ ruby
+# In gems.rb:
+
+source "https://rubygems.org"
+
+group :preload do
+	# List any gems you want to be pre-loaded into the falcon process before forking.
+end
+~~~
+
+#### Preloading Files
+
+Create a file in your application called `preload.rb`. You can put this file anywhere in your application.
+
+##### Falcon Serve
+
+`falcon serve` has a `--preload` option which accepts the path to this file.
+
+##### Falcon Host
+
+`falcon.rb` applications may have a `preload` configuration option.
+
+## System Limitations
+
+If you are expecting to handle many simultaneous connections, please ensure you configure your file limits correctly.
+
+~~~
+Errno::EMFILE: Too many open files - accept(2)
+~~~
+
+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.