Mounting¶
Mounting applications of other frameworks.
This document describes how Pyjoyment.Plugin.Mount runs the
applications of other frameworks next to the routes of an application of
Pyjoyment, in the same process and on the same server: WSGI and
ASGI applications of Python frameworks, FastCGI applications, as PHP
on php-fpm, CGI programs and event functions of AWS Lambda. A whole
application of Pyjoyment is mounted as Routing describes it.
Python frameworks¶
A WSGI application, as one of Flask, runs with Pyjo.App.WSGI, and
an ASGI application, as one of Starlette, whose __call__ is a
coroutine function, with Pyjo.App.ASGI. The application is the object
itself, or the name of its module and its attribute, as the WSGI and
ASGI servers take it.
from Pyjoyment.Lite import *
# A WSGI and an ASGI application of their own modules, by the names that their servers take
plugin('Mount', {'/legacy': 'legacy:app'})
plugin('Mount', {'/api': 'api:app'})
@get('/')
def index(c):
c.render(text='Hello from Pyjoyment!')
app.start()
# A WSGI application, as an application of Flask is one
def app(environ, start_response):
start_response('200 OK', [('Content-Type', 'text/plain')])
return [f'Hello from WSGI at {environ["SCRIPT_NAME"]} for {environ["PATH_INFO"]}!'.encode()]
import json
# An ASGI application, as an application of Starlette is one, with server-sent events and a WebSocket
async def app(scope, receive, send):
if scope['type'] == 'websocket':
await receive()
await send({'type': 'websocket.accept'})
while (message := await receive())['type'] == 'websocket.receive':
await send({'type': 'websocket.send', 'text': f'echo: {message["text"]}'})
return
if scope['path'] == f'{scope["root_path"]}/events':
await send({'type': 'http.response.start', 'status': 200, 'headers': [(b'content-type', b'text/event-stream')]})
for n in range(3):
await send({'type': 'http.response.body', 'body': f'data: {n}\n\n'.encode(), 'more_body': True})
await send({'type': 'http.response.body', 'body': b''})
return
body = json.dumps({'root_path': scope['root_path'], 'path': scope['path']}).encode()
await send({'type': 'http.response.start', 'status': 200, 'headers': [(b'content-type', b'application/json')]})
await send({'type': 'http.response.body', 'body': body})
The path that an application is mounted under is its SCRIPT_NAME of
WSGI, or its root_path of ASGI, with which its path begins, so
the URLs that the application builds, as with url_for of Flask or
Starlette, have the prefix of the mount.
WSGI¶
A WSGI application blocks, and it runs in the event loop, which waits for
it as for any other blocking operation, and which it sees as not running, so
that a library that refuses to block in a running loop of asyncio, as
Django, runs, as Pyjo.IOLoop.blocking() does for other blocking code.
The pre-forking and the pre-threading servers run it in their workers at the
same time, best with few connections for each worker.
$ python myapp.py prefork -w 8 -c 1
Django serves a project of Django this way, and From gunicorn translates the options of gunicorn.
ASGI¶
An ASGI application runs as a coroutine of the event loop: with
Pyjo.Reactor.Asyncio, the default reactor, a task of asyncio,
which can await anything of asyncio, and whose responses stream at the
pace of the client, as the server-sent events of api.py do. Its
WebSockets are WebSockets of the server of Pyjoyment, as the echo of
api.py, whose handshake waits for the application to accept it. A reactor
without asyncio, as Pyjo.Reactor.Poll, runs only an application
that awaits nothing but receive and send.
Lifespan¶
The lifespan of an ASGI application starts with its first request in
each process, which waits for its startup, and gets a copy of its state, and
it shuts down once the server has stopped gracefully, as the hook
after_server_stop of Pyjoyment comes then, so that what the
application has started, as a pool of connections, outlives the requests.
Pings¶
The servers of Pyjoyment close a connection that has been inactive for
their inactivity timeout, 30 seconds by default, as a WebSocket without
messages, so the WebSockets of an ASGI application are pinged every 20
seconds, as an ASGI server pings them, which
ping_interval changes. A WebSocket of
Pyjoyment is pinged with
heartbeat().
import Pyjo.App.ASGI
import api
# Pings every 60 seconds
plugin('Mount', {'/api': Pyjo.App.ASGI.new(app=api.app, ping_interval=60)})
# A WebSocket of Pyjoyment pinged every 20 seconds
@websocket('/echo')
def echo(c):
c.tx.heartbeat()
c.on('message', lambda c, msg: c.send(f'echo: {msg}'))
MCP servers¶
A server of the MCP SDK, MCPServer of the package mcp, is an ASGI
application of Starlette with its transport of Streamable HTTP, whose lifespan
runs the manager of its sessions, so that the tools of an agent of AI run next
to the routes of the application, on the same server. Its path is / under
the mount, so that a client connects to the URL of the mount with a slash at
the end, as http://localhost:3000/mcp/, which Starlette would otherwise
redirect to on each request.
from Pyjoyment.Lite import *
from mcp.server.mcpserver import MCPServer
# A server of the MCP SDK with a tool, whose transport of Streamable HTTP is an ASGI application of Starlette, under
# /mcp/, as uv run --group servers python examples/mount/mount_mcp.py daemon serves it on http://localhost:3000/mcp/
mcp = MCPServer('Pyjoyment')
@mcp.tool()
def add(a: int, b: int) -> int:
"""Add two numbers."""
return a + b
plugin('Mount', {'/mcp': mcp.streamable_http_app(streamable_http_path='/')})
get('/', {'text': 'I ♥ Pyjoyment!'})
app.start()
The sessions are kept by the process that has started them, so with the
workers of the pre-forking server the server runs without them, with
stateless_http=True, as with any server that has more than one process.
The manager of the sessions runs once, in one event loop, so the server does
not run in the threads of the pre-threading server, whose lifespan fails in
the second one.
plugin('Mount', {'/mcp': mcp.streamable_http_app(streamable_http_path='/', stateless_http=True)})
$ python mount_mcp.py prefork -w 4
Paths¶
The path of a mount is a pattern of a route, which matches the beginning of
the path of a request, as in Mojolicious, so that /legacy matches
/legacy.css and /legacyx too, which an application of another
framework answers with 404 Not Found, as its SCRIPT_NAME or
root_path can only end with a slash. A regular expression matches the
whole path instead, as the ones of PromQL do: its group path is the rest of
the path for the application, and its other named groups are captures.
Pyjo.q() makes one shorter than re.compile() does.
from Pyjo import q
from Pyjoyment.Lite import *
# Only /legacy and the paths under it
plugin('Mount', {q(r'/legacy(?P<path>/.*)?'): 'legacy:app'})
# The API of each user, whose name is a capture
plugin('Mount', {q(r'/(?P<user>\w+)/api(?P<path>/.*)?'): 'api:app'})
# Only one path
plugin('Mount', {q(r'/status\.json'): 'api:app'})
Static files¶
The static files of Pyjoyment.Static are served before the routes, so
an application mounted on / can have its static files served by
Pyjoyment, as the output of collectstatic of Django, in the place of
whitenoise. STATIC_URL of /static/ maps onto the directory static
of a directory of paths, so the
path is the parent of STATIC_ROOT, which can also have the files of /,
as favicon.ico and robots.txt, which whitenoise serves from
WHITENOISE_ROOT.
prefix serves a STATIC_ROOT
of another name, but all the static files of Pyjoyment are then under it.
Pyjoyment serves its own /favicon.ico and the images of /pyjo/, which
its exception and not found pages use, from
extra, after the files of
paths, so a favicon.ico there
is served in its place. An application that serves its /favicon.ico from
a route, or has none, gets the requests of it without the one of Pyjoyment,
which del app.static.extra['favicon.ico'] removes, and
app.static.extra = {} leaves out the images too.
The names of ManifestStaticFilesStorage of Django, as
site.2fcb528ecde1.css, or of a bundler, have a hash of their content and
never change, so immutable lets
browsers keep them for a year, and
cache_control makes them
revalidate the other files after a while.
import re
from pathlib import Path
from Pyjoyment.Lite import *
# STATIC_ROOT = BASE_DIR / 'public' / 'static', for STATIC_URL = '/static/', and favicon.ico and robots.txt in public
BASE_DIR = Path(__file__).resolve().parent
app.static.paths = [str(BASE_DIR / 'public')]
# The hashed names of ManifestStaticFilesStorage never change, the other files are revalidated after a minute
app.static.immutable = re.compile(r'^static/.+\.[0-9a-f]{12}\.[^/.]+$')
app.static.cache_control = 'public, max-age=60'
# The project of Django
plugin('Mount', {'/': 'legacy:app'})
CompressedManifestStaticFilesStorage of whitenoise writes the .gz and
.br variants of the files next to them, which
Pyjoyment.Static serves too, as Rendering says of
precompressed static files.
FastCGI¶
A FastCGI application, as PHP on php-fpm, runs in a process of its own,
which Pyjo.App.FastCGI connects to for each request, through the
TCP/IP socket of fcgi:// or the UNIX domain socket of fcgi+unix://,
the location that is mounted. Its query tells which script answers a path,
without rules of rewriting:
scriptis the one script for every path, as the one entry of an application that takes every path, as mod_rewrite sends them all toindex.php;document_rootis the directory of the scripts, as a web server runs them: the path up to its first part that ends with.php, or with one of the extensions ofscript_extensions, names the script, and a path that ends with a slash namesindex.php,indexwith the first of them;both together send every path that names no script of the directory to the one script, as
try_filesof nginx does for WordPress;staticreplies with the files of the directory for the paths that name them, as the stylesheets and the images of WordPress, before the one script, for an application on the same file system as Pyjoyment;sendfilelets the application reply with a file of its directories by the headerX-Sendfile, as private files, also more than one, repeated in the query, and the attribute ofPyjo.App.FastCGItakes regular expressions of the whole path of the file too.
The paths are the ones that php-fpm sees, which may be in another container, so Pyjoyment does not look for the files.
The static files of Pyjoyment.Static, as the directory public
next to the application, are served before the routes, so the scripts of a
document_root or a script in them would be served as files, with
their source, as public/index.php of Laravel or Symfony with the
configuration of its database. The server does not start then, for the
paths that are on the file system of Pyjoyment, unless public_source
says that it is on purpose. The scripts go to another directory, as www
next to the application, whose files static serves, and public keeps
the files of Pyjoyment.
# PHP of www next to the script, with its files
www = curfile().sibling('www').to_str()
plugin('Mount', {'/': Pyjo.App.FastCGI.new(url='fcgi://127.0.0.1:9000', document_root=www, static=True)})
# Every path to the one entry of the application
plugin('Mount', {'/app': 'fcgi://127.0.0.1:9000?script=/srv/app/public/index.php'})
# The scripts of a directory
plugin('Mount', {'/php': 'fcgi+unix://%2Frun%2Fphp%2Fphp-fpm.sock?document_root=/var/www/php'})
# WordPress: its scripts, its files, and its index.php for every other path
plugin('Mount', {'/blog': 'fcgi://127.0.0.1:9000?document_root=/var/www/wordpress&script=index.php&static=1'})
The query also takes inactivity_timeout and connect_timeout, in
seconds, for an application that answers slowly, which the client waits for
without the inactivity timeout of the server until the response starts, and
max_connections, the number of idle connections that are kept for the
next requests, as fastcgi_keep_conn of nginx keeps them, where php-fpm
keeps a worker of its pm.max_children for each of them, also while it is
idle. The attributes of Pyjo.App.FastCGI take the same, and more, as
parameters of its own for the environment of each request.
CGI¶
A CGI program runs in a process of its own for each request, which
Pyjo.App.CGI starts, mounted as an object of it, as a string is the
path of a script of Pyjoyment. Its attributes tell which program
answers a path, as for FastCGI:
scriptis the one program for every path;document_rootis the directory of the programs, as cgi-bin: the path up to its first part that is a file of the directory names the program;commandruns the scripts with an interpreter, as php-cgi, andscript_extensionstells them from the other files, which are not run, and whichstaticreplies with.
The programs are not in the static files of the application, as for
FastCGI, unless public_source says that it is on purpose. A program
whose name starts with nph- writes the start line of its response, as nph tells of the others. The event loop reads the pipes of
the process, which it can on POSIX systems, not on Windows.
import Pyjo.App.CGI
# The programs of cgi-bin
plugin('Mount', {'/cgi-bin': Pyjo.App.CGI.new(document_root='/usr/lib/cgi-bin')})
# PHP on php-cgi, with its files
php = Pyjo.App.CGI.new(command=['php-cgi'], document_root='/var/www/php', script_extensions=['.php'], static=True)
plugin('Mount', {'/php': php})
AWS Lambda¶
An event function of AWS Lambda runs in a process of its own, which
Pyjo.App.Lambda starts on the first request and keeps for the next
ones, which it gets one after another through the Runtime API of Lambda, as
an execution environment of Lambda does, mounted as an object of it. A handler
of Python, module.function in the directory of task_root, runs with the
runtime client of Pyjo.Server.Lambda, also one of another framework
that runs an event loop of its own, as Mangum, and command runs a function
of another runtime. The request is an event of the payload format of
payload, 2.0 of Function URLs and HTTP APIs by default, 1.0 of
REST APIs or alb, and the path of the mount is its stage, so that the same
function runs here, live and in the tests of Pyjo.Test.Pyjo, as on AWS.
import Pyjo.App.Lambda
# The handler "handler" of myfunction.py of the directory of the function
plugin('Mount', {'/function': Pyjo.App.Lambda.new(function='myfunction.handler', task_root='functions')})
# Another runtime, with the events of a REST API
plugin('Mount', {'/node': Pyjo.App.Lambda.new(command=['node', 'runtime.js'], payload='1.0')})
More¶
The page of Examples has PHP on php-fpm with the pool of php-fpm that
runs it, PHP on php-cgi, a program of Python in cgi-bin, and event functions of
AWS Lambda, also Starlette on Mangum, and an application of Pyjoyment on
Pyjo.Server.Lambda in the same file.
You can continue with Guides now.