socketry/falcon

Falcon is a high-performance, asynchronous HTTP web server and deployment framework for Ruby, built on the Async ecosystem. It provides a comprehensive suite of tools for managing server lifecycles, including support for clustering, virtual hosting, reverse proxying, and graceful shutdowns. The system features a modernized middleware stack with capabilities for HTTP/2 push, streaming responses, and detailed utilization metrics, while offering extensive examples for integrating with databases, gRPC, and WebSocket protocols.

16 changes.

This period focused on a comprehensive infrastructure overhaul, migrating the project to GitHub Actions, modernizing the test suite, and enforcing Ruby 3.3+ requirements. Concurrently, the codebase expanded its capabilities with a new composite server architecture, dedicated deployment commands, and a rich set of examples demonstrating async HTTP, streaming, and Redis integration.

16 changes.

This period focused on expanding the Falcon framework with new HTTP middleware components for proxying, redirection, and verbose logging. It also introduced a comprehensive suite of example applications demonstrating WebSocket, streaming, and database integration patterns. Concurrently, the project significantly increased test coverage for core server infrastructure, CLI commands, and middleware while updating compatibility configurations for Rack 3 and Async.

16 changes.

The project introduced a new managed service layer using Async::Service to handle server, cluster, and virtual host lifecycle management, alongside a restructured environment configuration system. This architectural shift was accompanied by extensive documentation through diverse examples covering streaming uploads, reverse proxies, TLS verification, and performance comparisons.

8 changes.

This period focused on enhancing observability by adding tracing for proxy and redirect middleware, fixing metric leaks in request lifecycle handling, and expanding test coverage for environment and body components. It also introduced new examples demonstrating multi-protocol server setups, async utilization monitoring, and load-aware clustering with Envoy.

Users can now run Rack applications using the standard \rackup\ command with Falcon as the underlying server. A new \Falcon::Rackup::Handler\ class has been added to \lib/falcon/rackup/handler.rb\, providing an adaptor that wraps the application in \Protocol::Rack::Adapter\ and runs it via \Falcon::Server\ over HTTP/1. This enables compatibility with tools and workflows that expect a \rackup\ handler, including better integration with frameworks like Sinatra.

lib/falcon/rackup · high confidence

Added a new Elixir example in the examples/hello-elixir directory that demonstrates a simple Plug-based REST application. The example includes a Plug implementation that returns a 'Hello World' string, an application supervisor configured to run the server on port 3000 using Plug.Cowboy, and a README with usage instructions for running and testing the service.

examples/hello-elixir · high confidence

A new example application has been added to the examples/echo directory, providing a minimal Rack-based server that reads from the input stream and echoes it back to the client. The implementation includes a custom response body class and is configured with a config.ru file, adhering to Ruby best practices such as the frozen\_string\_literal pragma.

examples/echo · high confidence

A new example application has been added to the examples/redis directory, demonstrating how to use the updated async-container with Redis. The example implements a Sinatra-based web server that performs a BLPOP operation on a Redis list, measuring the duration of the blocking call using Async::Clock. This serves as a practical demonstration of asynchronous Redis interactions within the async-container framework.

examples/redis · high confidence

A new example application has been added to the examples/sequel directory, demonstrating a minimal Ruby web server using the Sequel ORM with a SQLite database. The application configures a single-threaded mode, connects to a local data.sqlite3 file, and serves a simple HTTP response by retrieving a user name from the database.

examples/sequel · high confidence

A new example in the \examples/tls-client-verify\ directory demonstrates how to configure the Falcon server to verify inbound client requests using TLS client certificates. The example includes a \falcon.rb\ configuration that sets up a self-signed TLS context with \OpenSSL::SSL::VERIFY\_PEER\ mode and a custom verification callback, along with the necessary client certificate and key files for testing.

examples/tls-client-verify · high confidence

Added a new example directory demonstrating a performance comparison between Unicorn and Falcon running in single-request-per-process mode. The example includes a Rack application (\config.ru\) with fast and slow endpoints, a Falcon host configuration (\falcon.rb\) using a limited wrapper, a client script (\client.rb\) for load testing, and a \gems.rb\ specifying dependencies on Unicorn (\~\> 6.1) and the local Falcon gem.

examples/unicorn · high confidence

A new example has been added to the \examples/websockets\ directory that demonstrates how to implement a WebSocket echo server using the \async-websocket\ library with Rack and Falcon. The example includes a \config.ru\ file defining an application that handles both standard HTTP requests and WebSocket connections, a \falcon.rb\ service configuration for running the server with self-signed TLS, and a \readme.md\ with usage instructions for testing the connection.

examples/websockets · high confidence

The utilization example now includes an async-enabled Falcon server implementation (falcon.rb) and a corresponding gemfile (gems.rb) that introduces the async-utilization library. This addition allows users to observe how utilization monitoring integrates with asynchronous service supervisors, specifically demonstrating the tracking of active requests and connections in an async context.

examples/utilization · high confidence

Added a new example in the \examples/limited\ directory that demonstrates how to limit the number of concurrent connections to a Falcon server. The example uses a custom \IO::Endpoint\ wrapper (\Limited::Wrapper\) with a per-worker semaphore to control connection acceptance, preventing server overload from slow requests, and includes a Rack application (\config.ru\) showing how to release connection tokens early for fast, non-blocking endpoints.

examples/limited · high confidence

Added a new gRPC example in the examples/grpc directory, including a proto definition for a Greeter service, generated Ruby protobuf files, and runnable client and server scripts. The example also provides integration examples using Rack and Falcon web servers, along with a script to regenerate the protobuf code and a gems.rb file specifying the required dependencies (grpc, grpc-tools, falcon, bake).

examples/grpc · high confidence

A new example in the examples/cluster directory demonstrates running a two-worker Falcon cluster behind Envoy. The setup uses Docker Compose to orchestrate the services, where the Falcon supervisor publishes worker endpoints via an xDS control plane and reports per-worker CPU utilization and request throughput using ORCA. This allows Envoy to dynamically shift traffic toward workers with more available capacity, and a provided client script verifies that requests are distributed across both workers.

examples/cluster · high confidence

The memory example now includes a new middleware that tracks object allocations using ObjectSpace. When the /allocations endpoint is accessed, it returns a breakdown of allocation counts by class, allowing users to inspect memory usage patterns within the application.

examples/memory · high confidence

A new example in the examples/multi-protocol directory demonstrates how to run a single Rack application on both HTTP/1.1 (port 8080) and HTTP/2 (port 8090) simultaneously using Falcon's composite server and IO::Endpoint::NamedEndpoints.

examples/multi-protocol · high confidence

New example applications have been added to demonstrate usage of the Falcon web server and Trenni templating engine. The 'call' example shows how to implement a streaming response using Trenni templates with deferred body execution, while the 'headers' example demonstrates parsing query parameters and setting custom response headers using the CGI library.

examples/call · high confidence

Added a new example in the \examples/proxy\ directory that demonstrates how to set up a reverse proxy server using Falcon. The example provides two implementation approaches: a Falcon-native proxy using \Falcon::Environment::Application\ and a Rack-based proxy using \Protocol::Rack::Adapter\ to handle format conversion. Both implementations forward incoming requests from \localhost:9292\ to a backend service on \localhost:3000\ using \Async::HTTP::Client\.

examples/proxy · high confidence

New middleware components are introduced to the Falcon server: a Proxy middleware that forwards requests to configured upstream hosts while managing hop headers and forwarding metadata; a Redirect middleware that issues 301 responses to map specific hosts to different endpoints (useful for HTTP-to-HTTPS transitions); and a Verbose middleware that logs detailed request and response information using the Console library.

lib/falcon/middleware · high confidence

A new standalone example script (examples/server/standalone.rb) has been added to demonstrate how to run a WebSocket server using Falcon. This example shows how to configure a Rack-based application to handle WebSocket connections on a specific endpoint, allowing users to see a concrete implementation of WebSocket handling within the Falcon framework.

examples/server · high confidence

Added a new example in the \examples/streaming\_upload\ directory that demonstrates how to handle streaming uploads using the Falcon server. The example includes a \config.ru\ file implementing a \BodyHandler\ to process incoming request bodies in chunks, calculate MD5 hashes, and track upload size and duration, along with a \readme.md\ containing benchmark results and usage instructions.

_examples/cookies, examples/streaming\upload · high confidence

The examples/supervisor directory now includes a complete demonstration of using the Async::Service::Supervisor to monitor and handle memory leaks. This example features a custom MemoryMonitor that detects when process memory exceeds defined limits, dumps the memory state for analysis, and restarts the affected server instance. The setup includes a Rack application (config.ru) capable of simulating memory leaks and a Falcon configuration (falcon.rb) that orchestrates the supervised service with specific memory thresholds.

examples/supervisor · high confidence

The examples/trailer directory now includes a config.ru file that demonstrates an HTTP server setup using the Falcon framework. This example implements a middleware logger and returns a response that includes a 'server-timing' trailer header, allowing users to see how to send trailing headers in HTTP responses.

examples/trailer · high confidence

The examples/internet directory now includes a Rack application (config.ru) that demonstrates how to perform upstream HTTP requests using the Async library. This example provides two distinct endpoints: /sync, which uses the experimental kernel/sync method to handle requests efficiently in both traditional and async-aware servers, and /async, which uses the Async method to perform non-blocking background requests without holding up the main request processing.

examples/internet · high confidence

A new example demonstrating request pushback has been added to the examples/pushback directory. It implements a concurrency limiter using the async gem and Falcon, where incoming requests exceeding a defined worker pool size receive a 429 Too Many Requests response, while others are processed concurrently.

examples/pushback · high confidence

The library now includes specific trace providers for the Falcon web server's proxy and redirect middleware. When these middleware components handle requests, the system automatically records traces with relevant attributes such as HTTP method, path, and authority, allowing users to monitor and debug these specific network operations.

lib/traces · high confidence

The assets directory now includes the original v1 logo design as an SVG file (assets/logo-v1.svg) and a new license file (assets/license.md) that specifies the copyright holder (Malene Laugesen) and the Creative Commons Attribution-NonCommercial-NoDerivatives 4.0 International license terms for the logo.

assets · high confidence

The examples/push directory now provides a complete demonstration of HTTP/2 server push via the Early Hints (103) response. The server-side config.ru includes an EarlyHints middleware that pushes /style.css and /script.js before the main response, while the client.rb example uses Async::HTTP::Protocol::HTTP2::WithPush to receive and process these push promises.

examples/push · high confidence

The \falcon\ CLI now includes new subcommands for production deployment scenarios: \falcon host\ manages application instances via a controller, \falcon virtual\ runs a front-end proxy with automatic HTTP-to-HTTPS redirection for multiple virtual hosts, and \falcon proxy\/\falcon redirect\ allow standalone proxy or redirect services. These commands share a common configuration loading mechanism that resolves wildcard paths and integrate with the \Async::Service\ controller infrastructure, providing a structured way to deploy applications beyond the existing development-focused \falcon serve\ command.

lib/falcon/command · high confidence

The hello example has been updated to demonstrate the new service-based configuration syntax. It now includes a \falcon.rb\ file that defines a service for \hello.localhost\ using \Falcon::Environment::SelfSignedTLS\ and \Falcon::Environment::Rack\, and a \config.ru\ Rack application that returns a simple "Hello World" response. A \preload.rb\ file is also provided to illustrate preloading capabilities.

examples/hello · high confidence

A new example has been added to demonstrate how to use the Async::Service layer to manage a simple HTTP service. The example includes a \hello.rb\ script that configures a \Falcon::Environment::Server\ with a \HelloWorld\ middleware, and a \readme.md\ explaining how to run it via \bundle exec async-service ./hello.rb\ to start a web server on port 9292.

examples/async-service · high confidence

Added new example directories for benchmarking and service configuration. The benchmark example provides a k6-based load testing script (small.js) and a Rack configuration (config.ru) with endpoints for small, big, and hello responses, alongside a Ruby script (bake.rb) to compare server performance using tools like wrk and curl. The service example demonstrates integrating a custom service with Redis using async-redis, including a subscription listener, and defines the necessary gem dependencies.

examples/benchmark · high confidence

Falcon introduces three new service classes in the \lib/falcon/service\ directory to manage application lifecycle and deployment. \Falcon::Service::Server\ acts as a managed service that binds endpoints and runs workers within an \Async::Container\, including support for health check timeouts and improved process title formatting. \Falcon::Service::Cluster\ extends this to allow workers to bind endpoints independently in their own processes. Additionally, \Falcon::Service::Virtual\ provides a controller to manage multiple virtual hosts by spawning proxy and redirect instances, handling privilege dropping and configuration path resolution for each hosted application.

lib/falcon/service · high confidence

The examples/sleep directory now includes a new config.ru file that serves as a demonstration of graceful shutdown behavior. This example uses Async::HTTP to write a stream of 'Hello World' messages and explicitly employs task.defer\_stop to ensure the background writing task completes its current iterations before the server shuts down, providing a concrete pattern for handling graceful termination in HTTP applications.

examples/sleep · high confidence

A new example application has been added to the examples/csv directory that demonstrates streaming CSV data. The application reads words from a dictionary file and sends them as CSV-formatted lines to the client with a one-second delay between each line, utilizing the Falcon web server and Async library for non-blocking I/O.

examples/csv · high confidence

A new handler file is introduced to ensure compatibility with frameworks like Sinatra that expect a handler class in the \Rack::Handler\ namespace. This shim defines a \Rackup::Handler::Falcon\ class that inherits from the internal \Falcon::Rackup::Handler\ and registers itself under the \:falcon\ name, allowing Rack v3 and Sinatra to correctly locate and use the Falcon handler.

lib/rackup · high confidence

New gemfiles have been added to support testing against specific versions of the \async\ and \rack\ libraries. \async-head.rb\ and \async-v1.rb\ allow testing against the latest development version and version 1.x respectively. Similarly, \rack-head.rb\, \rack-v1.rb\, \rack-v2.rb\, and \rack-v3.rb\ enable testing against the latest development version of Rack and its major versions 1, 2, and 3. These files evaluate the base \gems.rb\ and then specify the target gem version, facilitating a broader test matrix for compatibility.

gems · high confidence

Falcon has been updated to version 0.57.0, introducing a \CompositeServer\ that allows running multiple server instances concurrently under a single unit. The framework now uses a dedicated \Endpoint\ class for HTTP-specific configuration, including automatic localhost TLS via \Localhost::Authority\ and ALPN negotiation. The server's middleware stack has been modernized to use \Protocol::HTTP::Middleware\, adding support for content encoding and response caching, while replacing the legacy \Samovar\ CLI with \Console\. Additionally, the server now tracks detailed connection and request statistics via \Async::Utilization\, and Rails integration is configured to use fiber-based isolation.

lib/falcon · high confidence

The beer example has been updated to demonstrate streaming HTTP responses, where the '99 Bottles of Beer' page is generated and sent to the client incrementally rather than all at once. The application now uses a new \config.ru\ entry point and a \falcon.rb\ service definition that leverages \Async::Service::Supervisor\ for process management. This change also includes improvements to logging via \Console.info\, better shebang compatibility, and the addition of self-signed TLS support for the virtual host.

examples/beer · high confidence

The streaming example has been updated to use Rack 3 and the xrb gem, replacing the previous setup. A new config.ru file demonstrates the streaming behavior using the XRB template engine, and the gems.rb file explicitly declares dependencies on xrb, rack (version \~\> 3), and the local falcon gem.

examples/streaming · high confidence

The project has been modernized by migrating from Travis CI to GitHub Actions, replacing the RSpec test runner with Sus, and standardizing code style via RuboCop. Release management now uses the Bake toolchain instead of Rake, and the dependency on \async-container-supervisor\ has been removed in favor of \async-service-supervisor\. Additionally, legacy configuration environments and the \Falcon::Configuration\ class have been dropped, with the server now using \Async::Service::Configuration\ directly.

(repo-wide) · high confidence

The Falcon Rack handler implementation has been refactored to inherit from \Falcon::Rackup::Handler\ instead of defining its own \run\ and \valid\_options\ methods. This change centralizes the server logic within the \Falcon::Rackup\ module, simplifying the handler class and improving compatibility with Rack v2 expectations by explicitly registering the handler using its full name.

lib/rack · high confidence

The main entry point bin/falcon now delegates to the centralized Falcon::Command.call interface instead of manually parsing and invoking commands, simplifying the startup flow. Additionally, the previous test file spec/falcon/server\_spec.rb has been removed and replaced by a new executable bin/falcon-host, which is now a proper script with an executable shebang and requires the Falcon::Command::Host implementation, effectively moving the host functionality from a test context to a standalone binary.

bin · high confidence

The main library entry point has been restructured to explicitly require specific components (version, listener, server, and composite server) instead of the previous command-centric load path. The file now enforces strict string literal freezing and updates the license header to the MIT License with an extended copyright range.

lib · high confidence

The environment configuration system has been restructured to use \Async::Service::Managed::Environment\ as the base for server environments, introducing a new \make\_server\ configuration method that allows custom server instance creation. The \Serve\ environment now supports automatic discovery of application configuration via \config/serve.rb\ or \config.ru\, selecting the appropriate middleware stack based on file extension. Virtual host environments now explicitly bind to HTTP port 80 for redirects and HTTPS port 443 for proxying, with dedicated \Redirect\ and \Proxy\ environments handling insecure-to-secure traffic redirection and SNI-based TLS proxying respectively. The \Cluster\ environment has been added to support hosting multiple Falcon server workers, each binding its own endpoint.

lib/falcon/environment · high confidence

A new RequestFinished wrapper in lib/falcon/body ensures the requests\_active metric is decremented even if the underlying response body's close method raises an exception. This prevents the active request count from leaking when errors occur during the finalization of a response, ensuring accurate monitoring of concurrent requests.

lib/falcon/body · high confidence

Added test coverage for Falcon core components; Added test coverage for Proxy and Redirect middleware; Added tests for Falcon command-line interface commands; Added tests for Falcon environment configuration components; Added tests for Falcon service components; Added tests for Falcon trace middleware; Added tests for request lifecycle metrics in Falcon body handling; Added tests for the Falcon rackup handler; New test configuration for external dependencies and coverage; New test fixtures for server context and temporary directories; Removed spec\_helper.rb test configuration.

This release modernizes the Falcon web server by requiring Ruby 3.3 or later and significantly updating its dependency graph. The gem now depends on \async-http \~\> 0.97\, \async-container \~\> 0.20\, \async-service \~\> 0.19\, and \protocol-rack \~\> 0.7\, replacing older versions of \async-http\ and \samovar\. It also introduces new dependencies for caching (\async-http-cache\), utilization metrics (\async-utilization\), and local host resolution (\localhost\), while dropping support for Ruby versions below 3.3 and removing the \async-io\ dependency. Additionally, example applications for Elixir (using Plug/Cowboy) and Ruby (Sinatra/Sequel) are included to demonstrate integration.

(dependencies) · high confidence

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

• First survey — no prior run to compare against. CAI 68.

• Code Health 100
• Architecture 100
• Maturity 82
• Readiness 51
• Security 74

• 300 commits — 279 feature/other, 21 fixes

• lib/falcon — 108 commits
• (root) — 74 commits
• .github/workflows — 10 commits
• guides/rails-integration — 10 commits
• guides/deployment — 9 commits
• test/falcon — 9 commits
• examples/websockets — 6 commits
• examples/sinatra — 5 commits
• examples/streaming_upload — 5 commits
• examples/hello — 4 commits
• context/deployment.md — 3 commits
• examples/grpc — 3 commits
• examples/limited — 3 commits
• examples/proxy — 3 commits
• examples/sleep — 3 commits
• spec/falcon — 3 commits
• config/sus.rb — 2 commits
• examples/bug — 2 commits
• examples/call — 2 commits
• examples/cluster — 2 commits

• fix: Bump dependency on protocol-rack for bug fixes.
• fix: Fix WebSockets example.
• fix: Fix context/index.yaml schema.
• fix: Fix falcon virtual and WebSocket HTTP/1 <-> HTTP/2 proxy support.
• fix: Fix requests_active leak when response close raises. (#350)
• fix: Fix compatibility with io-stream changes.
• fix: Fix documentation generation.
• fix: Fix handling of legacy supervisor worker.
• fix: Fix legacy lets_encrypt_tls environment.
• fix: Fix missing glob configuration paths in falcon virtual. (#240)
• fix: Fix position of preload.
• fix: Fix require path for websocket rack adapter.
• fix: Fix supervisor implementation + add more tests.
• fix: Fix syntax highlighting.
• fix: Fix test on ruby-head.
• fix: Fix test workflow.
• fix: Fix tests.
• fix: Fix tests.
• fix: Fix unbundled environment.
• fix: Remove date and server header from response. Fixes #112.
• …and 280 more

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

socketry/falcon was measured the same way every project in this corpus was: the same rubric, at a pinned commit, with the result published in full. Point a surveyor at a repository you know and see whether you agree with it.