65 lines
2.4 KiB
Markdown
65 lines
2.4 KiB
Markdown
# SSR Architecture
|
|
|
|
*Decided 2026-04-07.*
|
|
|
|
Mizan's SSR adapter is a **Django template backend**. It plugs into
|
|
Django's existing `TEMPLATES` setting, replacing the template
|
|
rendering engine.
|
|
|
|
```python
|
|
TEMPLATES = [
|
|
{
|
|
'BACKEND': 'mizan.ssr.MizanTemplates',
|
|
'DIRS': [BASE_DIR / 'frontend'],
|
|
'OPTIONS': {
|
|
'worker': 'path/to/mizan-ssr/src/worker.tsx',
|
|
'timeout': 5,
|
|
},
|
|
}
|
|
]
|
|
```
|
|
|
|
Then `render(request, 'components/Hello.tsx', context)` calls the Bun
|
|
subprocess bridge instead of rendering a Django/Jinja2 template.
|
|
**The template name IS a `.tsx`/`.jsx` file path**, resolved against
|
|
`DIRS`; `get_template` returns a `MizanTemplate` wrapping the absolute
|
|
file path. The context dict becomes the component's props (`request`
|
|
and `csrf_token` stripped). Rendered output is wrapped in
|
|
`<div id="mizan-root">…</div>` plus a
|
|
`<script>window.__MIZAN_SSR_DATA__=…</script>` hydration payload.
|
|
|
|
## AFI boundary
|
|
|
|
| Side | Responsibility |
|
|
|---|---|
|
|
| Backend adapter (`SSRBridge`) | Manages the Bun subprocess lifecycle; gathers props |
|
|
| Bun worker (`worker.tsx`) | `import()`s the file path, `renderToString(createElement(Component, props))` |
|
|
| stdin/stdout JSON-RPC | Newline-delimited; `{id, method:"render", params:{file, props}}` → `{id, html}` / `{id, error}`; `ping` → `{id, pong:true}` |
|
|
|
|
## Why template backend
|
|
|
|
- Django's template system is swappable by design (batteries
|
|
included, but replaceable).
|
|
- Django developers already use `render(request, template, context)`
|
|
— no new API to learn.
|
|
- URL routing, views, middleware, auth — all unchanged.
|
|
|
|
> A `templatetags/` package exists for a future `{% mizan_render %}`
|
|
> convenience tag (base.html shell with Mizan components inside), but
|
|
> it is currently empty — no tag is implemented yet.
|
|
|
|
## Implementation surface
|
|
|
|
The SSR backend (`mizan/ssr/backend.py`) implements Django's template
|
|
backend interface:
|
|
|
|
- `MizanTemplates(BaseEngine)` — requires `OPTIONS['worker']` (path to
|
|
`worker.tsx`); `get_template(name)` resolves a file under `DIRS`
|
|
- `MizanTemplate` with `.render(context, request)` → calls the bridge
|
|
- `SSRBridge` (`bridge.py`) — spawns `bun run <worker>`, holds the
|
|
persistent subprocess, correlates requests by message id, thread-safe,
|
|
auto-restarts on crash, waits for the worker's ready signal
|
|
|
|
Everything Django expects from a template backend, but the actual
|
|
rendering routes to Bun.
|