Writing middleware
==================
Middleware allows you to insert code that runs before and after your
handlers. It is useful for cross‑cutting concerns such as logging,
authentication, rate limiting or explicit routing. MicroPie defines
separate middleware classes for HTTP and WebSocket connections.
HTTP middleware
---------------
To create HTTP middleware, subclass :class:`~micropie.HttpMiddleware`
and implement two asynchronous methods:
* :meth:`~micropie.HttpMiddleware.before_request` – called before the
handler is executed. If this method returns a dictionary with
``status_code`` and ``body`` keys, MicroPie immediately sends that
response and skips calling the handler. You can also provide
additional headers via a ``headers`` key.
* :meth:`~micropie.HttpMiddleware.after_request` – called after the
handler has returned a response but before it is sent to the client.
You can modify the status code, body or headers by returning a
dictionary with updated values.
Register your middleware by appending an instance to
:attr:`~micropie.App.middlewares` on your application:
.. code-block:: python
from micropie import App, HttpMiddleware
class LoggingMiddleware(HttpMiddleware):
async def before_request(self, request):
print(f"Incoming request: {request.method} {request.scope['path']}")
# returning None continues processing
async def after_request(self, request, status_code, body, headers):
print(f"Response status: {status_code}")
# returning None uses the original response
class MyApp(App):
async def index(self):
return "Hello, world!"
app = MyApp()
app.middlewares.append(LoggingMiddleware())
WebSocket middleware
--------------------
WebSocket middleware must subclass :class:`~micropie.WebSocketMiddleware`
and implement two methods:
* :meth:`~micropie.WebSocketMiddleware.before_websocket` – called
before a WebSocket handler runs. If this method returns a
dictionary with ``code`` and ``reason``, MicroPie closes the
connection with the given code and reason.
* :meth:`~micropie.WebSocketMiddleware.after_websocket` – called after
the WebSocket handler completes. Use this to perform cleanup.
Example:
.. code-block:: python
from micropie import App, WebSocketMiddleware
class RejectAnonymous(WebSocketMiddleware):
async def before_websocket(self, request):
# Reject connections without a "user" query parameter
if "user" not in request.query_params:
return {"code": 1008, "reason": "User name required"}
async def after_websocket(self, request):
print("WebSocket closed")
class MyApp(App):
async def ws_chat(self, ws, user):
await ws.accept()
await ws.send_text(f"Welcome, {user}!")
await ws.close()
app = MyApp()
app.ws_middlewares.append(RejectAnonymous())
Explicit routing and other patterns
-----------------------------------
You can implement custom routing schemes by writing middleware that
parses the incoming path and sets ``request._route_handler`` or
``request._ws_route_handler`` accordingly. See the examples in the
``examples/middleware`` directory for a complete implementation.
