falcon-rails 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 34ee82aedb10194c91447a3ea58db73ba79da8ebbe6621cc4a9148f5517bdeb6
+  data.tar.gz: 14d659677ee4e20bddfc2b1107277b01c883aecf6a843eaca4ff2799bf58976b
+SHA512:
+  metadata.gz: 6e8ad267e81745e93527f25511a56775ff6cf3c8b38ef99553fdd2679de87c8b2d090788f34b48ebca0ed0a20f8a881fa97026466ac62ffdc99399618ed5fc2a
+  data.tar.gz: 150e56abe7e16e42d56421a5b4c860d1da3d5e653615ee2dcb7b20e94fc213e3c1010596959593c4a57b7830fb5c95a6e1d503adb8699a1052dd605356a8465e

data/context/getting-started.md

@@ -0,0 +1,43 @@
+# Getting Started
+
+This guide explains how to get started using Falcon to host your Rails application.
+
+## Installation
+
+In your existing Rails application:
+
+```bash
+bundle add falcon-rails
+```
+
+You might also like to remove your existing web server, such as Puma, and replace it with Falcon:
+
+```bash
+bundle remove puma
+```
+
+## Usage
+
+Falcon is an Async-compatible web server that can be used with Rails. It provides high concurrency and low latency for web applications.
+
+To use Falcon in development, first install the development TLS certificates:
+
+```
+> bundle exec bake localhost:install
+```
+
+Then, you can start your Rails application with Falcon:
+
+```bash
+> bundle exec falcon serve
+```
+
+You can access your application at `https://localhost:9292`.
+
+## Integrations
+
+Consult the other integration guides for more information on using Falcon with popular libraries and frameworks.
+	
+### Example
+
+Many of the integrations are demonstrated in the example application available at: https://github.com/socketry/falcon-rails-examples

data/context/http-streaming.md

@@ -0,0 +1,200 @@
+# HTTP Streaming
+
+This guide explains how to implement HTTP response streaming with Falcon and Rails.
+
+## What is HTTP Streaming?
+
+HTTP streaming allows you to send data to the client progressively over a single HTTP connection using chunked transfer encoding. Unlike Server-Sent Events, HTTP streaming gives you complete control over the data format and doesn't require specific protocols.
+
+**When to use HTTP streaming:**
+- Progress indicators for long-running tasks.
+- Live log streaming.
+- Large file generation (CSV, JSON exports).
+- Real-time data feeds with custom formats.
+- Streaming API responses.
+
+**When NOT to use HTTP streaming:**
+- When you need persistent connections (use SSE or WebSockets instead).
+- For simple real-time updates (SSE is easier).
+
+## Basic Implementation
+
+### Server-Side: Rails Controller
+
+Create a controller action that streams data using `Rack::Response`:
+
+```ruby
+class StreamingController < ApplicationController
+	def index
+		# Render the page with streaming JavaScript
+	end
+	
+	def stream
+		body = proc do |stream|
+			10.downto(1) do |i|
+				stream.write "#{i} bottles of beer on the wall\n"
+				sleep 1
+				stream.write "#{i} bottles of beer\n"
+				sleep 1
+				stream.write "Take one down, pass it around\n"
+				sleep 1
+				stream.write "#{i - 1} bottles of beer on the wall\n"
+				sleep 1
+			end
+		end
+
+		self.response = Rack::Response[200, {"content-type" => "text/plain"}, body]
+	end
+end
+```
+
+**Key Points:**
+- Use `Rack::Response` with a callable body for streaming.
+- `content-type` can be `text/plain`, `application/json`, or any format you need.
+- Each `stream.write` sends data immediately to the client.
+- No special formatting required (unlike SSE's `data: ` prefix).
+
+### Client-Side: Fetch API with ReadableStream
+
+Create an HTML page that consumes the HTTP stream:
+
+```html
+<button id="startStream" class="button">🚀 Start Streaming Demo</button>
+<button id="stopStream" class="button" disabled>⏹️ Stop Stream</button>
+<div id="streamOutput" class="terminal"></div>
+
+<script>
+let streamController = null;
+let streamReader = null;
+
+document.getElementById('startStream').addEventListener('click', function() {
+	const output = document.getElementById('streamOutput');
+	const startBtn = document.getElementById('startStream');
+	const stopBtn = document.getElementById('stopStream');
+	
+	// Clear previous output
+	output.innerHTML = '<div class="terminal-status">🔄 Starting stream...</div>';
+	
+	// Create abort controller for stopping the stream
+	streamController = new AbortController();
+	
+	// Start streaming
+	fetch('/streaming/stream', { signal: streamController.signal })
+		.then(response => {
+			if (!response.ok) throw new Error('Network response was not ok');
+			
+			streamReader = response.body.getReader();
+			const decoder = new TextDecoder();
+			
+			function readStream() {
+				streamReader.read().then(({ done, value }) => {
+					if (done) {
+						output.innerHTML += '<div class="terminal-complete">✅ Stream completed!</div>';
+						startBtn.disabled = false;
+						stopBtn.disabled = true;
+						return;
+					}
+					
+					const text = decoder.decode(value, { stream: true });
+					const lines = text.split('\n');
+					
+					lines.forEach(line => {
+						if (line.trim()) {
+							const lineDiv = document.createElement('div');
+							lineDiv.className = 'terminal-line';
+							lineDiv.textContent = line;
+							output.appendChild(lineDiv);
+							output.scrollTop = output.scrollHeight;
+						}
+					});
+					
+					readStream();
+				});
+			}
+			
+			readStream();
+		});
+});
+
+document.getElementById('stopStream').addEventListener('click', function() {
+	if (streamController) {
+		streamController.abort();
+	}
+});
+</script>
+```
+
+**Key Points:**
+- Use `fetch()` with `AbortController` for cancellation support.
+- Get a `ReadableStream` reader with `response.body.getReader()`.
+- Use `TextDecoder` to convert binary data to text.
+- Handle the stream chunks manually in the `readStream()` function.
+
+### Routing Configuration
+
+Add routes to your `config/routes.rb`:
+
+```ruby
+Rails.application.routes.draw do
+	# Streaming Example:
+	get 'streaming/index'  # Page with streaming JavaScript
+	get 'streaming/stream' # HTTP streaming endpoint
+end
+```
+
+## Advanced Patterns
+
+### Streaming NDJSON Data
+
+Server-side:
+```ruby
+def stream
+	body = proc do |stream|
+		User.find_each(batch_size: 100) do |user|
+			# Each line is a complete JSON object
+			stream.write "#{user.to_json}\n"
+		end
+	end
+	
+	self.response = Rack::Response[200, {"content-type" => "application/x-ndjson"}, body]
+end
+```
+
+Client-side:
+```javascript
+fetch('/streaming/users')
+	.then(response => {
+		const reader = response.body.getReader();
+		const decoder = new TextDecoder();
+		let buffer = '';
+		
+		function readStream() {
+			reader.read().then(({ done, value }) => {
+				if (done) {
+					console.log('All users loaded');
+					return;
+				}
+				
+				buffer += decoder.decode(value, { stream: true });
+				const lines = buffer.split('\n');
+				buffer = lines.pop(); // Keep incomplete line in buffer
+				
+				lines.forEach(line => {
+					if (line.trim()) {
+						try {
+							const user = JSON.parse(line);
+							console.log('User loaded:', user);
+							displayUser(user);
+						} catch (e) {
+							console.error('Invalid JSON:', line);
+						}
+					}
+				});
+				
+				readStream();
+			});
+		}
+		
+		readStream();
+	});
+```

data/context/job-processing.md

@@ -0,0 +1,78 @@
+# Job Processing
+
+This guide explains how to implement background job processing with Falcon and Rails using the `async-job` gem.
+
+## What is Async::Job?
+
+`Async::Job` is a framework for creating background jobs that run asynchronously without blocking web requests. It integrates seamlessly with Rails' ActiveJob, allowing you to offload long-running tasks to background workers. The Rails integration uses a specific gem to provide this functionality, called `async-job-adapter-active_job`.
+
+**When to use async jobs:**
+- Long-running tasks (data processing, file uploads).
+- Email sending and external API calls.
+- Scheduled tasks and periodic jobs.
+- Heavy computations that would slow down web responses.
+
+**When NOT to use async jobs:**
+- Simple operations that complete quickly.
+- Tasks that need immediate user feedback.
+
+## Basic Implementation
+
+### Server-Side: Job Class
+
+Create a job class that inherits from `ApplicationJob`:
+
+```ruby
+class MyJob < ApplicationJob
+	# Specify the queue adapter per-job rather than globally:
+	# queue_adapter :async_job
+	
+	queue_as "default"
+	
+	def perform
+		# ... work ...
+	end
+end
+```
+
+**Key Points:**
+- Use `queue_as` to specify which queue this job should use.
+- The `perform` method contains your background work.
+
+### Configuration
+
+Configure async-job queues in `config/initializers/async_job.rb`:
+
+```ruby
+require 'async/job'
+require 'async/job/processor/aggregate'
+require 'async/job/processor/redis'
+require 'async/job/processor/inline'
+
+Rails.application.configure do
+	config.async_job.define_queue "default" do
+		# Double-buffers incoming jobs to avoid submission latency:
+		enqueue Async::Job::Processor::Aggregate
+		dequeue Async::Job::Processor::Redis
+	end
+	
+	config.async_job.define_queue "local" do
+		dequeue Async::Job::Processor::Inline
+	end
+end
+```
+
+**Key Points:**
+- `default` queue uses Redis for persistent job storage.
+- `local` queue processes jobs inline, but in a background Async task - higher throughput but lower robustness.
+- Different processors can be used for different queue behaviors.
+
+Configure the default adapter in `config/application.rb`:
+
+```ruby
+# ... in the application configuration:
+config.active_job.queue_adapter = :async_job
+```
+
+**Key Points:**
+- This sets `Async::Job` as the default queue adapter. You can instead specify this per-job for incremental migration.

data/context/real-time-views.md

@@ -0,0 +1,259 @@
+# Real-Time Views
+
+This guide explains how to implement real-time interfaces with `Live::View`.
+
+## What is `Live::View`?
+
+`Live::View` enables real-time, interactive web interfaces using WebSocket connections. It allows you to update the DOM in real-time without JavaScript, making it perfect for dynamic content that changes frequently.
+
+**When to use `Live::View`:**
+- Real-time dashboards and status displays.
+- Interactive forms with live validation.
+- Live updating content (clocks, counters, progress bars).
+- Simple games and interactive applications.
+
+**When NOT to use `Live::View`:**
+- Static content that doesn't change.
+- Complex client-side interactions requiring heavy JavaScript.
+
+## Setup
+
+### Import Maps Configuration
+
+Use `bin/importmap` to install the required JavaScript packages:
+
+```bash
+> bin/importmap pin @socketry/live
+Pinning "@socketry/live" to vendor/javascript/@socketry/live.js via download from https://ga.jspm.io/npm:@socketry/live@0.14.0/Live.js
+Pinning "morphdom" to vendor/javascript/morphdom.js via download from https://ga.jspm.io/npm:morphdom@2.7.7/dist/morphdom-esm.js
+```
+
+### JavaScript Setup
+
+Create `app/javascript/live.js` to initialize `Live::View`:
+
+```javascript
+import {Live} from "@socketry/live"
+window.live = Live.start()
+```
+
+Pin your local `live.js` file in `config/importmap.rb`:
+
+```ruby
+pin "live"
+```
+
+**Key Points:**
+- Import maps handle the `@socketry/live` package automatically.
+- The `live.js` file starts the `Live::View` client connection.
+- `pin "live"` makes your local `live.js` file importable in view templates.
+- `window.live` makes the Live connection globally available.
+
+## Basic Implementation: Live Clock
+
+### Live::View Class
+
+Create a `Live::View` class that handles the real-time logic:
+
+```ruby
+require 'live'
+
+class ClockTag < Live::View
+	def initialize(...)
+		super
+	end
+	
+	def bind(page)
+		@task ||= start_clock
+	end
+	
+	def close
+		if task = @task
+			@task = nil
+			task.stop
+		end
+	end
+	
+	def start_clock
+		Async do
+			while true
+				sleep 1
+				self.update!
+			end
+		end
+	end
+	
+	def forward_event(name)
+		"event.preventDefault(); live.forwardEvent(#{JSON.dump(@id)}, event, {name: #{name.inspect}})"
+	end
+
+	def render(builder)
+		builder.tag(:div, class: "clock-container") do
+			builder.tag(:h2) {builder.text("Live Clock")}
+			builder.tag(:div, id: "clock", class: "clock-display") do
+				builder.text(Time.now.strftime("%H:%M:%S"))
+			end
+		end
+	end
+end
+```
+
+**Key Points:**
+- Inherit from `Live::View` to get real-time capabilities.
+- Use `Async` blocks for background tasks.
+- Use `self.update!` to queue a full re-render.
+- Define `forward_event` method to handle user interactions.
+- The `render` method defines the initial HTML structure.
+
+### Controller
+
+Create a controller to handle the Live::View connection:
+
+```ruby
+require 'async/websocket/adapters/rails'
+
+class ClockController < ApplicationController
+	RESOLVER = Live::Resolver.allow(ClockTag)
+
+	def index
+		@tag = ClockTag.new('clock')
+	end
+	
+	skip_before_action :verify_authenticity_token, only: :live
+	
+	def live
+		self.response = Async::WebSocket::Adapters::Rails.open(request) do |connection|
+			Live::Page.new(RESOLVER).run(connection)
+		end
+	end
+end
+```
+
+**Key Points:**
+- Use `Live::Resolver.allow` to whitelist your `Live::View` sub-classes.
+- Skip CSRF verification for the WebSocket endpoint.
+- Use `Async::WebSocket::Adapters::Rails.open` for WebSocket handling.
+- `Live::Page.new(RESOLVER).run(connection)` handles the `Live::View` protocol.
+
+### View Template
+
+Create a view template that renders the Live::View:
+
+```html
+<h1>⏰ Live Clock Example</h1>
+<p>This clock updates every second using Live::View.</p>
+
+<%= javascript_import_module_tag "live" %>
+
+<div class="clock-wrapper">
+	<%= raw @tag.to_html %>
+</div>
+
+<style>
+.clock-container {
+	text-align: center;
+	padding: 2rem;
+	border: 2px solid #ddd;
+	border-radius: 8px;
+	margin: 2rem 0;
+}
+
+.clock-display {
+	font-size: 3rem;
+	font-family: 'Monaco', 'Consolas', monospace;
+	color: #333;
+	background: #f0f0f0;
+	padding: 1rem;
+	border-radius: 4px;
+	margin-top: 1rem;
+}
+</style>
+```
+
+**Key Points:**
+- Use `<%= javascript_import_module_tag "live" %>` to load Live::View on specific pages.
+- Use `raw @tag.to_html` to render the Live::View component.
+- The Live::View will automatically connect via WebSocket.
+- This loads Live::View only on pages that need it, not globally.
+
+### Routing Configuration
+
+Add routes to your `config/routes.rb`:
+
+```ruby
+Rails.application.routes.draw do
+	# Live Clock Example:
+	get "clock/index"
+	connect "clock/live"
+end
+```
+
+**Key Points:**
+- Use the Rails 8 `connect` helper for WebSocket routes.
+- The `live` action handles the WebSocket connection.
+
+## Interactive Example: Counter with Buttons
+
+### Live::View Class with User Interaction
+
+```ruby
+class CounterTag < Live::View
+	def initialize(count: 0)
+		super
+
+		# @data is persisted on the tag in `data-` attributes.
+		@data["count"] = @data.fetch("count", count).to_i
+	end
+	
+	def handle(event)
+		case event[:type]
+		when "click"
+			case event.dig(:detail, :name)
+			when "increment"
+				@data["count"] += 1
+			when "decrement"
+				@data["count"] -= 1
+			end
+			
+			update_counter
+		end
+	end
+	
+	def update_counter
+		self.replace("#counter") do |builder|
+			builder.tag(:div, id: "counter", class: "counter-display") do
+				builder.text(@data["count"].to_s)
+			end
+		end
+	end
+	
+	def forward_event(name)
+		"event.preventDefault(); live.forwardEvent(#{JSON.dump(@id)}, event, {name: #{name.inspect}})"
+	end
+
+	def render(builder)
+		builder.tag(:div, class: "counter-container") do
+			builder.tag(:h2) { builder.text("Live Counter") }
+			
+			builder.tag(:div, id: "counter", class: "counter-display") do
+				builder.text(@count.to_s)
+			end
+			
+			builder.tag(:div, class: "counter-buttons") do
+				builder.tag(:button, onclick: forward_event("decrement")) do
+					builder.text("-")
+				end
+				builder.tag(:button, onclick: forward_event("increment")) do
+					builder.text("+")
+				end
+			end
+		end
+	end
+end
+```
+
+**Key Points:**
+- Define `forward_event` (or `forward_click`, etc) methods to generate JavaScript for event handling.
+- `live.forwardEvent(...)` on the client side invokes `handle(event)` on the server side.
+- Update the DOM in response to user actions.
+- Maintain persistent state in `@data`.

data/context/server-sent-events.md

@@ -0,0 +1,149 @@
+# Server-Sent Events
+
+This guide explains how to implement Server-Sent Events with Falcon and Rails.
+
+## What are Server-Sent Events?
+
+Server-Sent Events (SSE) provide a way to push real-time updates from the server to the client over a single HTTP connection. Unlike WebSockets, SSE is unidirectional (server-to-client only) and uses the standard HTTP protocol.
+
+**When to use SSE:**
+- Live dashboards and monitoring systems.
+- Real-time notifications.
+- Progress indicators for long-running tasks.
+- Live feeds (news, social media updates).
+- Database change notifications.
+
+**When NOT to use SSE:**
+- When you need bidirectional communication (use WebSockets instead).
+- When you need binary data transmission.
+
+## Basic Implementation
+
+### Server-Side: Rails Controller
+
+Create a controller action that streams events using `Rack::Response`:
+
+```ruby
+class SseController < ApplicationController
+	def index
+		# Render the page with EventSource JavaScript
+	end
+	
+	EVENT_STREAM_HEADERS = {
+		'content-type' => 'text/event-stream',
+		'cache-control' => 'no-cache',
+		'connection' => 'keep-alive'
+	}
+
+	def events
+		body = proc do |stream|
+			while true
+				# Send timestamped data:
+				stream.write("data: #{Time.now}\n\n")
+				sleep 1
+			end
+		end
+		
+		self.response = Rack::Response[200, EVENT_STREAM_HEADERS.dup, body]
+	end
+end
+```
+
+**Key Points:**
+- `content-type: text/event-stream` is required for SSE.
+- Each message must end with `\n\n` (two newlines).
+- The `data: ` prefix is required for the message content.
+- Use a callable body for streaming responses.
+
+### Client-Side: JavaScript EventSource
+
+Create an HTML page that consumes the SSE stream:
+
+```html
+<div id="status" class="status warning">🔄 Connecting to event stream...</div>
+<div id="history" class="terminal"></div>
+
+<script>
+var eventSource = new EventSource("events");
+var messageCount = 0;
+
+eventSource.addEventListener("open", function(event) {
+	document.getElementById("status").innerHTML = "✅ Connected to event stream";
+	document.getElementById("status").className = "status success";
+});
+
+eventSource.addEventListener("message", function(event) {
+	messageCount++;
+	var container = document.createElement("div");
+	container.className = "terminal-line";
+	container.innerHTML = `<span class="event-count">#${messageCount}</span> <span class="event-data">${event.data}</span>`;
+	
+	var history = document.querySelector("#history");
+	history.appendChild(container);
+	history.scrollTop = history.scrollHeight;
+	
+	// Keep only last 20 messages to prevent memory issues
+	if (history.children.length > 20) {
+		history.removeChild(history.firstChild);
+	}
+});
+
+eventSource.addEventListener("error", function(event) {
+	document.getElementById("status").innerHTML = "❌ Connection error - attempting to reconnect...";
+	document.getElementById("status").className = "status error";
+});
+</script>
+```
+
+**Key Points:**
+- `EventSource` automatically handles connection and reconnection.
+- Listen for `open`, `message`, and `error` events.
+- `event.data` contains the message content.
+- Implement UI feedback for connection status.
+
+### Routing Configuration
+
+Add routes to your `config/routes.rb`:
+
+```ruby
+Rails.application.routes.draw do
+	# SSE Example:
+	get 'sse/index'    # Page with EventSource JavaScript
+	get 'sse/events'   # SSE endpoint
+end
+```
+
+## Advanced Patterns
+
+### Sending Custom Event Types
+
+By default, `event: message` is assumed for each record sent on the stream. However, it's possible to specify different kinds of events:
+
+```ruby
+def events
+	body = proc do |stream|
+		# Send different event types
+		stream.write("event: user_joined\n")
+		stream.write("data: #{user.to_json}\n\n")
+		
+		stream.write("event: message\n")
+		stream.write("data: #{message.to_json}\n\n")
+	end
+	
+	self.response = Rack::Response[200, EVENT_STREAM_HEADERS.dup, body]
+end
+```
+
+On the client, you need to register multiple event listeners:
+
+```javascript
+eventSource.addEventListener("user_joined", function(event) {
+	var user = JSON.parse(event.data);
+	// Handle user joined event
+});
+
+eventSource.addEventListener("message", function(event) {
+	var message = JSON.parse(event.data);
+	// Handle message event
+});
+```

data/context/websockets.md

@@ -0,0 +1,133 @@
+# WebSockets
+
+This guide explains how to implement WebSocket connections with Falcon and Rails.
+
+## What are WebSockets?
+
+WebSockets provide full-duplex communication between client and server over a single persistent connection. Unlike HTTP streaming or SSE, WebSockets allow both client and server to send messages at any time.
+
+**When to use WebSockets:**
+- Real-time chat applications.
+- Interactive games and collaborative tools.
+- Live dashboards with user interaction.
+- Real-time notifications with user actions.
+
+**When NOT to use WebSockets:**
+- Simple server-to-client updates (use SSE instead).
+- Request/response patterns (use regular HTTP).
+
+## Basic Implementation
+
+### Server-Side: Rails Controller
+
+Create a controller that handles WebSocket connections:
+
+```ruby
+require 'async/websocket/adapters/rails'
+
+class ChatController < ApplicationController
+	def index
+		# Render the page with WebSocket JavaScript
+	end
+
+	skip_before_action :verify_authenticity_token, only: :connect
+
+	def connect
+		self.response = Async::WebSocket::Adapters::Rails.open(request) do |connection|
+			Sync do
+				# Perpetually read incoming messages from client:
+				while message = connection.read
+					# Echo message back to client:
+					response_data = { text: "Echo: #{JSON.parse(message.buffer)['text']}" }
+					connection.send_text(response_data.to_json)
+					connection.flush
+				end
+			rescue Protocol::WebSocket::ClosedError
+				# Connection closed by client.
+			end
+		end
+	end
+end
+```
+
+**Key Points:**
+- Use `Async::WebSocket::Adapters::Rails.open` for WebSocket handling.
+- Skip CSRF token verification for WebSocket endpoints.
+- Use `connection.read` to receive messages from clients.
+- Use `connection.send_text` and `connection.flush` to send messages.
+
+### Client-Side: WebSocket JavaScript
+
+Create JavaScript that connects to the WebSocket endpoint:
+
+```html
+<section id="response"></section>
+<section class="input">
+	<input id="chat" disabled="true" placeholder="Type your message and press Enter..." />
+</section>
+
+<script>
+function connectToChatServer(url) {
+	console.log("WebSocket Connecting...", url);
+	var server = new WebSocket(url.href);
+	
+	server.onopen = function(event) {
+		console.log("WebSocket Connected:", server);
+		chat.disabled = false;
+		
+		chat.onkeypress = function(event) {
+			if (event.keyCode == 13) {
+				server.send(JSON.stringify({text: chat.value}));
+				chat.value = "";
+			}
+		}
+	};
+	
+	server.onmessage = function(event) {
+		console.log("WebSocket Message:", event);
+		
+		var message = JSON.parse(event.data);
+		
+		var pre = document.createElement('pre');
+		pre.innerText = message.text;
+		
+		response.appendChild(pre);
+	};
+	
+	server.onerror = function(event) {
+		console.log("WebSocket Error:", event);
+		chat.disabled = true;
+		server.close();
+	};
+	
+	server.onclose = function(event) {
+		console.log("WebSocket Close:", event);
+		
+		setTimeout(function() {
+			connectToChatServer(url);
+		}, 1000);
+	};
+}
+
+var url = new URL('/chat/connect', window.location.href);
+url.protocol = url.protocol.replace('http', 'ws');
+connectToChatServer(url);
+</script>
+```
+
+**Key Points:**
+- Convert HTTP URL to WebSocket URL by replacing protocol.
+- Handle `onopen`, `onmessage`, `onerror`, and `onclose` events.
+- Use `JSON.stringify` and `JSON.parse` for structured messages.
+- Implement automatic reconnection on close.
+
+### Routing Configuration
+
+Add routes to your `config/routes.rb`:
+
+```ruby
+Rails.application.routes.draw do
+	get "chat/index"
+	connect "chat/connect"
+end
+```

data/lib/falcon/rails/version.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+# @namespace
+module Falcon
+	# @namespace
+	module Rails
+		VERSION = "0.2.0"
+	end
+end

data/lib/falcon/rails.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Samuel Williams.
+
+require_relative "rails/version"
+
+require "falcon"
+
+# Load all the dependencies:
+require "async/cable"
+require "async/job/adapter/active_job"
+require "async/websocket"
+require "console/adapter/rails"
+require "live"

data/license.md

@@ -0,0 +1,21 @@
+# MIT License
+
+Copyright, 2025, by Samuel Williams.  
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/readme.md

@@ -0,0 +1,54 @@
+# Async::Rails
+
+Provides integration support for Async and Rails, allowing you to use Async's concurrency model within a Rails application.
+
+[![Development Status](https://github.com/socketry/falcon-rails/workflows/Test/badge.svg)](https://github.com/socketry/falcon-rails/actions?workflow=Test)
+
+## Usage
+
+Please see the [project documentation](https://socketry.github.io/falcon-rails/) for more details.
+
+  - [Getting Started](https://socketry.github.io/falcon-rails/guides/getting-started/index) - This guide explains how to get started using Falcon to host your Rails application.
+
+  - [Job Processing](https://socketry.github.io/falcon-rails/guides/job-processing/index) - This guide explains how to implement background job processing with Falcon and Rails using the `async-job` gem.
+
+  - [HTTP Streaming](https://socketry.github.io/falcon-rails/guides/http-streaming/index) - This guide explains how to implement HTTP response streaming with Falcon and Rails.
+
+  - [Server-Sent Events](https://socketry.github.io/falcon-rails/guides/server-sent-events/index) - This guide explains how to implement Server-Sent Events with Falcon and Rails.
+
+  - [WebSockets](https://socketry.github.io/falcon-rails/guides/websockets/index) - This guide explains how to implement WebSocket connections with Falcon and Rails.
+
+  - [Real-Time Views](https://socketry.github.io/falcon-rails/guides/real-time-views/index) - This guide explains how to implement real-time interfaces with `Live::View`.
+
+## Releases
+
+Please see the [project releases](https://socketry.github.io/falcon-rails/releases/index) for all releases.
+
+### v0.1.0
+
+## See Also
+
+  - [Async](https://github.com/socketry/async) - The core library for asynchronous programming in Ruby.
+  - [Async::Cable](https://github.com/socketry/async-cable) - Async-compatible ActionCable implementation.
+  - [Async::Job](https://github.com/socketry/async-job) - Background job processing with ActiveJob adapter.
+  - [Console::Adapter::Rails](https://github.com/socketry/console-adapter-rails) - Rails logging adapter for the console gem.
+  - [Falcon](https://github.com/socketry/falcon) - High-performance web server for Ruby.
+  - [Live](https://github.com/socketry/live) - Real-time server components for interactive web applications.
+
+## Contributing
+
+We welcome contributions to this project.
+
+1.  Fork it.
+2.  Create your feature branch (`git checkout -b my-new-feature`).
+3.  Commit your changes (`git commit -am 'Add some feature'`).
+4.  Push to the branch (`git push origin my-new-feature`).
+5.  Create new Pull Request.
+
+### Developer Certificate of Origin
+
+In order to protect users of this project, we require all contributors to comply with the [Developer Certificate of Origin](https://developercertificate.org/). This ensures that all contributions are properly licensed and attributed.
+
+### Community Guidelines
+
+This project is best served by a collaborative and respectful environment. Treat each other professionally, respect differing viewpoints, and engage constructively. Harassment, discrimination, or harmful behavior is not tolerated. Communicate clearly, listen actively, and support one another. If any issues arise, please inform the project maintainers.

data/releases.md

@@ -0,0 +1,3 @@
+# Releases
+
+## v0.1.0

metadata

@@ -0,0 +1,177 @@
+--- !ruby/object:Gem::Specification
+name: falcon-rails
+version: !ruby/object:Gem::Version
+  version: 0.2.0
+platform: ruby
+authors:
+- Samuel Williams
+bindir: bin
+cert_chain:
+- |
+  -----BEGIN CERTIFICATE-----
+  MIIE2DCCA0CgAwIBAgIBATANBgkqhkiG9w0BAQsFADBhMRgwFgYDVQQDDA9zYW11
+  ZWwud2lsbGlhbXMxHTAbBgoJkiaJk/IsZAEZFg1vcmlvbnRyYW5zZmVyMRIwEAYK
+  CZImiZPyLGQBGRYCY28xEjAQBgoJkiaJk/IsZAEZFgJuejAeFw0yMjA4MDYwNDUz
+  MjRaFw0zMjA4MDMwNDUzMjRaMGExGDAWBgNVBAMMD3NhbXVlbC53aWxsaWFtczEd
+  MBsGCgmSJomT8ixkARkWDW9yaW9udHJhbnNmZXIxEjAQBgoJkiaJk/IsZAEZFgJj
+  bzESMBAGCgmSJomT8ixkARkWAm56MIIBojANBgkqhkiG9w0BAQEFAAOCAY8AMIIB
+  igKCAYEAomvSopQXQ24+9DBB6I6jxRI2auu3VVb4nOjmmHq7XWM4u3HL+pni63X2
+  9qZdoq9xt7H+RPbwL28LDpDNflYQXoOhoVhQ37Pjn9YDjl8/4/9xa9+NUpl9XDIW
+  sGkaOY0eqsQm1pEWkHJr3zn/fxoKPZPfaJOglovdxf7dgsHz67Xgd/ka+Wo1YqoE
+  e5AUKRwUuvaUaumAKgPH+4E4oiLXI4T1Ff5Q7xxv6yXvHuYtlMHhYfgNn8iiW8WN
+  XibYXPNP7NtieSQqwR/xM6IRSoyXKuS+ZNGDPUUGk8RoiV/xvVN4LrVm9upSc0ss
+  RZ6qwOQmXCo/lLcDUxJAgG95cPw//sI00tZan75VgsGzSWAOdjQpFM0l4dxvKwHn
+  tUeT3ZsAgt0JnGqNm2Bkz81kG4A2hSyFZTFA8vZGhp+hz+8Q573tAR89y9YJBdYM
+  zp0FM4zwMNEUwgfRzv1tEVVUEXmoFCyhzonUUw4nE4CFu/sE3ffhjKcXcY//qiSW
+  xm4erY3XAgMBAAGjgZowgZcwCQYDVR0TBAIwADALBgNVHQ8EBAMCBLAwHQYDVR0O
+  BBYEFO9t7XWuFf2SKLmuijgqR4sGDlRsMC4GA1UdEQQnMCWBI3NhbXVlbC53aWxs
+  aWFtc0BvcmlvbnRyYW5zZmVyLmNvLm56MC4GA1UdEgQnMCWBI3NhbXVlbC53aWxs
+  aWFtc0BvcmlvbnRyYW5zZmVyLmNvLm56MA0GCSqGSIb3DQEBCwUAA4IBgQB5sxkE
+  cBsSYwK6fYpM+hA5B5yZY2+L0Z+27jF1pWGgbhPH8/FjjBLVn+VFok3CDpRqwXCl
+  xCO40JEkKdznNy2avOMra6PFiQyOE74kCtv7P+Fdc+FhgqI5lMon6tt9rNeXmnW/
+  c1NaMRdxy999hmRGzUSFjozcCwxpy/LwabxtdXwXgSay4mQ32EDjqR1TixS1+smp
+  8C/NCWgpIfzpHGJsjvmH2wAfKtTTqB9CVKLCWEnCHyCaRVuKkrKjqhYCdmMBqCws
+  JkxfQWC+jBVeG9ZtPhQgZpfhvh+6hMhraUYRQ6XGyvBqEUe+yo6DKIT3MtGE2+CP
+  eX9i9ZWBydWb8/rvmwmX2kkcBbX0hZS1rcR593hGc61JR6lvkGYQ2MYskBveyaxt
+  Q2K9NVun/S785AP05vKkXZEFYxqG6EW012U4oLcFl5MySFajYXRYbuUpH6AY+HP8
+  voD0MPg1DssDLKwXyt1eKD/+Fq0bFWhwVM/1XiAXL7lyYUyOq24KHgQ2Csg=
+  -----END CERTIFICATE-----
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: async-cable
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: async-job-adapter-active_job
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: async-websocket
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: console-adapter-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: falcon
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: live
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.0'
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- context/getting-started.md
+- context/http-streaming.md
+- context/job-processing.md
+- context/real-time-views.md
+- context/server-sent-events.md
+- context/websockets.md
+- lib/falcon/rails.rb
+- lib/falcon/rails/version.rb
+- license.md
+- readme.md
+- releases.md
+homepage: https://github.com/socketry/falcon-rails
+licenses:
+- MIT
+metadata:
+  documentation_uri: https://socketry.github.io/falcon-rails/
+  source_code_uri: https://github.com/socketry/falcon-rails.git
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.7
+specification_version: 4
+summary: Easy Falcon and Rails integration.
+test_files: []