Add initial agent context.

Author: ioquatix

context/deployment.md

@@ -0,0 +1,59 @@
+# Deployment
+
+This guide explains how to use Falcon in production environments.
+
+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.
+
+## Falcon Serve
+
+`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.
+
+## Falcon Hosts
+
+`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).
+
+### Configuration
+
+`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 :
+
+~~~ ruby
+#!/usr/bin/env falcon-host
+# frozen_string_literal: true
+
+require "falcon/environment/rack"
+require "falcon/environment/lets_encrypt_tls"
+require "falcon/environment/supervisor"
+
+hostname = File.basename(__dir__)
+service hostname do
+	include Falcon::Environment::Rack
+	include Falcon::Environment::LetsEncryptTLS
+
+	# Insert an in-memory cache in front of the application (using async-http-cache).
+	cache true
+end
+
+service "supervisor" do
+	include Falcon::Environment::Supervisor
+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.
+
+## 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.
+
+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
+~~~
+
+See the [docker example](https://github.com/socketry/falcon-virtual-docker-example) for a complete working example.

context/rails.md

@@ -0,0 +1,30 @@
+# Rails Integration
+
+Falcon can serve Rails applications, however **it is highly recommended to use the latest stable release of Rails** for the best compatibility and performance. This guide explains how to host Rails applications with Falcon.
+
+## Integration with Rails
+
+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
+~~~
+
+## Isolation Level
+
+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.
+
+## ActionCable
+
+Falcon fully supports ActionCable with the [`Async::Cable` adapter](https://github.com/socketry/async-cable).
+
+## ActiveJob
+
+Falcon fully supports ActiveJob with the [`Async::Job` adapter](https://github.com/socketry/async-job-adapter-active_job).

context/streaming.md

@@ -0,0 +1,53 @@
+# Streaming
+
+Falcon supports streaming input and output, allowing you to send and receive data in real-time. This is particularly useful for applications that require live updates, such as chat applications or real-time dashboards.
+
+## WebSockets
+
+Falcon supports `Async::WebSocket` for client and server WebSocket connections. This allows for full-duplex communication channels over a single TCP connection, enabling real-time data exchange (including via HTTP/2).
+
+```ruby
+require 'async/websocket/adapters/rack'
+require 'set'
+
+run lambda {|env|
+	Async::WebSocket::Adapters::Rack.open(env, protocols: ['ws']) do |connection|
+		# Echo server:
+		while message = connection.read
+			connection.write(message)
+			connection.flush
+		end
+	end or [404, {}, []]
+}
+```
+
+
+
+## Server Sent Events
+
+Falcon supports Server-Sent Events (SSE) for sending real-time updates to clients. This is useful for applications that need to push updates to the browser without requiring a full page reload.
+
+```ruby
+def server_sent_events?(env)
+	env['HTTP_ACCEPT'].include?('text/event-stream')
+end
+
+run do |env|
+	if server_sent_events?(env)
+		body = proc do |stream|
+			while true
+				stream << "data: The time is #{Time.now}\n\n"
+				sleep 1
+			end
+		rescue => error
+		ensure
+			stream.close(error)
+		end
+		
+		[200, {'content-type' => 'text/event-stream'}, body]
+	else
+		# Else the request is for the index page, return the contents of index.html:
+		[200, {'content-type' => 'text/html'}, [File.read('index.html')]]
+	end
+end
+```

context/usage.md

@@ -0,0 +1,35 @@
+# Usage
+
+Falcon is a high-performance web server designed for Ruby applications, particularly those that require efficient handling of both asynchronous I/O and CPU-bound tasks. This guide provides an overview of how to use Falcon effectively, especially in scenarios involving concurrent processing.
+
+## Overview
+
+Falcon operates by creating a server that can handle multiple requests concurrently, leveraging Ruby's async capabilities. It is built on top of the `async` gem and integrates with Rack applications, allowing for seamless handling of web requests.
+
+## Rack Support
+
+Falcon supports traditional Rack applications, enabling developers to run existing Ruby web frameworks (like Sinatra or Rails) with minimal changes. It wraps the incoming HTTP requests and responses, allowing for a consistent interface across different types of applications.
+
+```
+# config.ru
+
+run do |env|
+	[200, { 'Content-Type' => 'text/plain' }, ['Hello from Falcon!']]
+end
+```
+
+You can run this application using Falcon by executing:
+
+```bash
+falcon serve
+```
+
+Falcon itself supports HTTP/2 by default, which requires the use of TLS. To do this, it uses the `localhost` gem which creates self-signed certificates for local development.
+
+### Un-encrypted HTTP
+
+Falcon can also run unencrypted HTTP for development purposes. To do this, you can specify the `--bind` option when starting the server:
+
+```bash
+falcon serve --bind http://localhost:9292
+```