Principle:OpenHands OpenHands Base App Initialization
| Knowledge Sources | |
|---|---|
| Domains | Server_Architecture, SaaS_Infrastructure |
| Last Updated | 2026-02-11 21:00 GMT |
Overview
Composing an ASGI application from a FastAPI base and SocketIO server produces a unified entry point that handles both HTTP requests and WebSocket connections through a single deployment unit.
Description
The Base App Initialization principle addresses the need to combine multiple ASGI-compatible application layers into a single composite server. In a SaaS context, the core HTTP API (built with FastAPI) and the real-time communication layer (built with python-socketio) must coexist under one process. The composite application pattern wraps these distinct ASGI apps so that incoming connections are routed to the appropriate handler based on the protocol and path. The SocketIO server acts as the outermost wrapper, delegating non-socket requests to the inner FastAPI application. This ensures that both REST endpoints and real-time event channels share the same server lifecycle, configuration, and middleware stack.
Usage
Apply this principle when building a server that must serve both traditional HTTP API endpoints and real-time WebSocket communication channels. It is especially relevant when the base application already provides a complete REST API and the goal is to augment it with bidirectional event-driven messaging without deploying a separate service.
Theoretical Basis
The composite application pattern originates from the need to unify multiple protocol handlers under one ASGI interface. ASGI (Asynchronous Server Gateway Interface) defines a standard callable signature that both FastAPI and python-socketio implement independently. By nesting one ASGI app inside another, the outer app can intercept requests it understands (such as Socket.IO handshake and event frames) while forwarding all other requests to the inner app. This avoids the complexity of reverse-proxy routing or multi-service deployments while maintaining a clean separation of concerns between the HTTP API layer and the real-time event layer. The pattern preserves the ability to apply shared middleware, authentication, and configuration across both transport mechanisms.