The Falcon Web Framework is recognized for its performance, reliability, and minimalist design, making it a popular choice for building RESTful APIs and web application backends in Python.[^1] While Falcon provides foundational support for WebSocket connections through its ASGI (Asynchronous Server Gateway Interface) integration[^2], it currently lacks a higher-level abstraction for routing and handling WebSocket messages in a manner analogous to its well-regarded HTTP routing and request handling mechanisms. This limitation often requires developers to implement custom dispatch logic within a single WebSocket handler, which can become complex for applications with rich real-time interaction.
This report presents a design proposal for an extension library, tentatively named "Falcon-Pachinko," aimed at addressing this gap. The proposed library will provide a structured and Falcon-idiomatic approach to routing WebSocket messages based on their content (e.g., a 'type' field in a JSON payload) and managing WebSocket connections. Furthermore, it will include a mechanism for associating background workers (such as pollers or publish/subscribe event handlers) with active WebSocket connections to facilitate server-initiated updates to clients.
The design prioritizes leveraging Falcon's existing capabilities and adhering to its core principles, particularly the principle of least surprise for developers already familiar with Falcon's HTTP paradigm. The AsyncAPI document, as specified in the use case, will be treated as a design artifact informing the structure of messages and interactions, rather than being directly consumed by the library at runtime. This document will first survey existing solutions and identify the specific needs addressed by the proposed extension. It will then detail the core components and API of Falcon-Pachinko, followed by an illustrative use case. Finally, potential future enhancements and conclusions will be discussed.