270 lines
12 KiB
HTML
270 lines
12 KiB
HTML
<!DOCTYPE html>
|
|
<html lang="en">
|
|
<head>
|
|
<meta charset="UTF-8">
|
|
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
|
<title>ASGI Mounting - pyserve</title>
|
|
<link rel="stylesheet" href="../style.css">
|
|
</head>
|
|
<body>
|
|
<div id="container">
|
|
<div id="header">
|
|
<h1>pyserve</h1>
|
|
<div class="tagline">python application orchestrator</div>
|
|
</div>
|
|
|
|
<div class="breadcrumb">
|
|
<a href="../index.html">pyserve</a> » <a href="index.html">Guides</a> » ASGI Mounting
|
|
</div>
|
|
|
|
<div id="content">
|
|
<h2>ASGI Application Mounting (In-Process)</h2>
|
|
|
|
<p>The <code>asgi</code> extension mounts ASGI and WSGI applications directly in the pyserve process.
|
|
This is simpler and has lower latency, but all apps share the same process.</p>
|
|
|
|
<div class="note">
|
|
<strong>For production use cases requiring isolation, consider
|
|
<a href="process-orchestration.html">Process Orchestration</a></strong> which runs each app
|
|
in a separate subprocess with health monitoring and auto-restart.
|
|
</div>
|
|
|
|
<h3>Overview</h3>
|
|
<p>The ASGI mounting system provides:</p>
|
|
<ul class="indent">
|
|
<li><strong>Multi-framework support</strong> — Mount FastAPI, Flask, Django, Starlette, or custom ASGI apps</li>
|
|
<li><strong>Path-based routing</strong> — Each app handles requests at its mounted path</li>
|
|
<li><strong>WSGI compatibility</strong> — Automatic WSGI-to-ASGI conversion for Flask/Django</li>
|
|
<li><strong>Factory pattern support</strong> — Create apps dynamically with arguments</li>
|
|
<li><strong>Path stripping</strong> — Optionally strip mount path from requests</li>
|
|
</ul>
|
|
|
|
<h3>Configuration</h3>
|
|
<p>ASGI applications are mounted via the <code>asgi</code> extension:</p>
|
|
|
|
<pre><span class="directive">extensions:</span>
|
|
- <span class="directive">type:</span> <span class="value">asgi</span>
|
|
<span class="directive">config:</span>
|
|
<span class="directive">mounts:</span>
|
|
- <span class="directive">path:</span> <span class="value">"/api"</span>
|
|
<span class="directive">app_path:</span> <span class="value">"myapp.api:app"</span>
|
|
<span class="directive">app_type:</span> <span class="value">asgi</span>
|
|
<span class="directive">name:</span> <span class="value">"api-app"</span>
|
|
<span class="directive">strip_path:</span> <span class="value">true</span></pre>
|
|
|
|
<h3>Mount Configuration Options</h3>
|
|
<dl>
|
|
<dt>path</dt>
|
|
<dd>URL path where the application will be mounted. Example: <code>/api</code></dd>
|
|
|
|
<dt>app_path</dt>
|
|
<dd>Python import path to the application. Format: <code>module.submodule:attribute</code></dd>
|
|
|
|
<dt>app_type</dt>
|
|
<dd>Application type: <code>asgi</code> or <code>wsgi</code>. Default: <code>asgi</code></dd>
|
|
|
|
<dt>module_path</dt>
|
|
<dd>Optional path to add to <code>sys.path</code> for module resolution</dd>
|
|
|
|
<dt>factory</dt>
|
|
<dd>If <code>true</code>, <code>app_path</code> points to a factory function. Default: <code>false</code></dd>
|
|
|
|
<dt>factory_args</dt>
|
|
<dd>Dictionary of arguments to pass to the factory function</dd>
|
|
|
|
<dt>name</dt>
|
|
<dd>Friendly name for logging. Default: uses <code>app_path</code></dd>
|
|
|
|
<dt>strip_path</dt>
|
|
<dd>Remove mount path from request URL. Default: <code>true</code></dd>
|
|
</dl>
|
|
|
|
<h3>Mounting FastAPI</h3>
|
|
<p>FastAPI applications are native ASGI:</p>
|
|
|
|
<pre><span class="comment"># myapp/api.py</span>
|
|
from fastapi import FastAPI
|
|
|
|
app = FastAPI()
|
|
|
|
@app.get("/users")
|
|
async def get_users():
|
|
return [{"id": 1, "name": "Alice"}]</pre>
|
|
|
|
<pre><span class="directive">extensions:</span>
|
|
- <span class="directive">type:</span> <span class="value">asgi</span>
|
|
<span class="directive">config:</span>
|
|
<span class="directive">mounts:</span>
|
|
- <span class="directive">path:</span> <span class="value">"/api"</span>
|
|
<span class="directive">app_path:</span> <span class="value">"myapp.api:app"</span>
|
|
<span class="directive">app_type:</span> <span class="value">asgi</span>
|
|
<span class="directive">name:</span> <span class="value">"fastapi-app"</span></pre>
|
|
|
|
<p>With this configuration:</p>
|
|
<ul class="indent">
|
|
<li><code>GET /api/users</code> → handled by FastAPI as <code>GET /users</code></li>
|
|
<li>FastAPI docs available at <code>/api/docs</code></li>
|
|
</ul>
|
|
|
|
<h3>Mounting Flask</h3>
|
|
<p>Flask applications are WSGI and will be automatically wrapped:</p>
|
|
|
|
<pre><span class="comment"># myapp/flask_api.py</span>
|
|
from flask import Flask
|
|
|
|
app = Flask(__name__)
|
|
|
|
@app.route("/hello")
|
|
def hello():
|
|
return {"message": "Hello from Flask!"}</pre>
|
|
|
|
<pre><span class="directive">extensions:</span>
|
|
- <span class="directive">type:</span> <span class="value">asgi</span>
|
|
<span class="directive">config:</span>
|
|
<span class="directive">mounts:</span>
|
|
- <span class="directive">path:</span> <span class="value">"/flask"</span>
|
|
<span class="directive">app_path:</span> <span class="value">"myapp.flask_api:app"</span>
|
|
<span class="directive">app_type:</span> <span class="value">wsgi</span>
|
|
<span class="directive">name:</span> <span class="value">"flask-app"</span></pre>
|
|
|
|
<div class="note">
|
|
<strong>Note:</strong> WSGI wrapping requires either <code>a2wsgi</code> or <code>asgiref</code>
|
|
to be installed. Install with: <code>pip install a2wsgi</code>
|
|
</div>
|
|
|
|
<h3>Mounting Django</h3>
|
|
<p>Django can be mounted using its ASGI application:</p>
|
|
|
|
<pre><span class="directive">extensions:</span>
|
|
- <span class="directive">type:</span> <span class="value">asgi</span>
|
|
<span class="directive">config:</span>
|
|
<span class="directive">mounts:</span>
|
|
- <span class="directive">path:</span> <span class="value">"/django"</span>
|
|
<span class="directive">django_settings:</span> <span class="value">"myproject.settings"</span>
|
|
<span class="directive">module_path:</span> <span class="value">"/path/to/django/project"</span>
|
|
<span class="directive">name:</span> <span class="value">"django-app"</span></pre>
|
|
|
|
<h3>Factory Pattern</h3>
|
|
<p>Use factory functions to create apps with custom configuration:</p>
|
|
|
|
<pre><span class="comment"># myapp/api.py</span>
|
|
from fastapi import FastAPI
|
|
|
|
def create_app(debug: bool = False, prefix: str = "/v1") -> FastAPI:
|
|
app = FastAPI(debug=debug)
|
|
|
|
@app.get(f"{prefix}/status")
|
|
async def status():
|
|
return {"debug": debug}
|
|
|
|
return app</pre>
|
|
|
|
<pre><span class="directive">extensions:</span>
|
|
- <span class="directive">type:</span> <span class="value">asgi</span>
|
|
<span class="directive">config:</span>
|
|
<span class="directive">mounts:</span>
|
|
- <span class="directive">path:</span> <span class="value">"/api"</span>
|
|
<span class="directive">app_path:</span> <span class="value">"myapp.api:create_app"</span>
|
|
<span class="directive">app_type:</span> <span class="value">asgi</span>
|
|
<span class="directive">factory:</span> <span class="value">true</span>
|
|
<span class="directive">factory_args:</span>
|
|
<span class="directive">debug:</span> <span class="value">true</span>
|
|
<span class="directive">prefix:</span> <span class="value">"/v2"</span></pre>
|
|
|
|
<h3>Path Stripping</h3>
|
|
<p>By default, <code>strip_path: true</code> removes the mount prefix from requests:</p>
|
|
|
|
<table class="dirindex">
|
|
<tr>
|
|
<td>Request</td>
|
|
<td><code>strip_path: true</code></td>
|
|
<td><code>strip_path: false</code></td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>GET /api/users</code></td>
|
|
<td>App sees <code>/users</code></td>
|
|
<td>App sees <code>/api/users</code></td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>GET /api/</code></td>
|
|
<td>App sees <code>/</code></td>
|
|
<td>App sees <code>/api/</code></td>
|
|
</tr>
|
|
</table>
|
|
|
|
<h3>Multiple Mounts</h3>
|
|
<p>Mount multiple applications at different paths:</p>
|
|
|
|
<pre><span class="directive">extensions:</span>
|
|
- <span class="directive">type:</span> <span class="value">asgi</span>
|
|
<span class="directive">config:</span>
|
|
<span class="directive">mounts:</span>
|
|
<span class="comment"># FastAPI for REST API</span>
|
|
- <span class="directive">path:</span> <span class="value">"/api"</span>
|
|
<span class="directive">app_path:</span> <span class="value">"apps.api:app"</span>
|
|
<span class="directive">app_type:</span> <span class="value">asgi</span>
|
|
|
|
<span class="comment"># Flask admin panel</span>
|
|
- <span class="directive">path:</span> <span class="value">"/admin"</span>
|
|
<span class="directive">app_path:</span> <span class="value">"apps.admin:app"</span>
|
|
<span class="directive">app_type:</span> <span class="value">wsgi</span>
|
|
|
|
<span class="comment"># Starlette websocket handler</span>
|
|
- <span class="directive">path:</span> <span class="value">"/ws"</span>
|
|
<span class="directive">app_path:</span> <span class="value">"apps.websocket:app"</span>
|
|
<span class="directive">app_type:</span> <span class="value">asgi</span>
|
|
|
|
<span class="comment"># Standard routing for static files</span>
|
|
- <span class="directive">type:</span> <span class="value">routing</span>
|
|
<span class="directive">config:</span>
|
|
<span class="directive">regex_locations:</span>
|
|
<span class="value">"__default__"</span>:
|
|
<span class="directive">root:</span> <span class="value">"./static"</span></pre>
|
|
|
|
<h3>Mount Priority</h3>
|
|
<p>Mounts are matched by path length (longest first). Given mounts at
|
|
<code>/api</code> and <code>/api/v2</code>:</p>
|
|
<ul class="indent">
|
|
<li><code>/api/v2/users</code> → matches <code>/api/v2</code> mount</li>
|
|
<li><code>/api/users</code> → matches <code>/api</code> mount</li>
|
|
</ul>
|
|
|
|
<h3>Combining with Routing</h3>
|
|
<p>ASGI mounts work alongside the routing extension. The <code>asgi</code> extension
|
|
should be listed before <code>routing</code> to handle mounted paths first:</p>
|
|
|
|
<pre><span class="directive">extensions:</span>
|
|
<span class="comment"># ASGI apps handle /api/* and /admin/*</span>
|
|
- <span class="directive">type:</span> <span class="value">asgi</span>
|
|
<span class="directive">config:</span>
|
|
<span class="directive">mounts:</span>
|
|
- <span class="directive">path:</span> <span class="value">"/api"</span>
|
|
<span class="directive">app_path:</span> <span class="value">"myapp:api"</span>
|
|
<span class="directive">app_type:</span> <span class="value">asgi</span>
|
|
|
|
<span class="comment"># Routing handles everything else</span>
|
|
- <span class="directive">type:</span> <span class="value">routing</span>
|
|
<span class="directive">config:</span>
|
|
<span class="directive">regex_locations:</span>
|
|
<span class="value">"=/health"</span>:
|
|
<span class="directive">return:</span> <span class="value">"200 OK"</span>
|
|
<span class="value">"__default__"</span>:
|
|
<span class="directive">spa_fallback:</span> <span class="value">true</span>
|
|
<span class="directive">root:</span> <span class="value">"./dist"</span></pre>
|
|
|
|
<h3>Python API</h3>
|
|
<p>For programmatic mounting, see <a href="../reference/asgi-mount.html">ASGI Mount API Reference</a>.</p>
|
|
|
|
<div class="warning">
|
|
<strong>Warning:</strong> Mounted applications share the same process.
|
|
Ensure your applications are compatible and don't have conflicting global state.
|
|
</div>
|
|
</div>
|
|
|
|
<div id="footer">
|
|
<p>pyserve © 2024-2025 | MIT License</p>
|
|
</div>
|
|
</div>
|
|
</body>
|
|
</html>
|