commit 355151

Commit `355151`

2026-03-17 18:24:23 Claude (MCP): [mcp] Add Design/Resolver wiki page documenting TenantResolver middleware

0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9

`/dev/null` .. `Design/Resolver.md`
@@ 0,0 1,130 @@
+	---
+	category: spec
+	tags: [architecture, resolver, multi-tenant, auth]
+	last_updated: 2026-03-17
+	confidence: high
+	---
+
+	# Resolver (TenantResolver)
+
+	The resolver is the WSGI middleware that makes robot.wtf multi-tenant. Every request to a wiki subdomain passes through it. It lives in `app/resolver.py`.
+
+	## What it does, in order
+
+	For every HTTP request to `{slug}.robot.wtf`:
+
+	1. Parse host → extract wiki slug from subdomain
+	2. Look up wiki → query `robot.db` wikis table by slug
+	3. Swap storage → patch otterwiki's module-level `storage` singleton in every module that imported it (yes, really — otterwiki uses module globals, not dependency injection)
+	4. Swap database → replace SQLAlchemy engine with the per-wiki `wiki.db`, reload preferences via `update_app_config()`
+	5. Authenticate → JWT cookie, bearer token, or anonymous
+	6. Derive permissions → owner gets ADMIN; per-wiki user table flags derive READ/WRITE/UPLOAD; fallback is READ for authenticated users
+	7. Apply access restrictions → per-wiki READ_ACCESS/WRITE_ACCESS/ATTACHMENT_ACCESS preferences can strip permissions (ANONYMOUS/REGISTERED/APPROVED levels)
+	8. Inject proxy headers → `x-otterwiki-email`, `x-otterwiki-name`, `x-otterwiki-permissions`
+	9. Delegate → pass modified `environ` to the wrapped otterwiki WSGI app
+
+	## Why it's complex
+
+	Otterwiki was designed as a single-tenant app. It uses module-level globals for storage and a single SQLAlchemy database. The resolver makes it multi-tenant by swapping these globals on every request. This is inherently fragile and is the source of most platform bugs.
+
+	### The storage swap problem
+
+	Otterwiki's `storage` (a `GitStorage` instance) is imported by value into ~8 modules at import time. Swapping the module-level variable in `otterwiki.server` doesn't affect the copies in `otterwiki.wiki`, `otterwiki.helper`, etc. So the resolver patches all of them:
+
+	```python
+	otterwiki.server.storage = storage
+	otterwiki.wiki.storage = storage
+	otterwiki.helper.storage = storage
+	# ... 5 more modules, plus plugin state dicts
+	```
+
+	If a new otterwiki module imports `storage` and we don't patch it, that module sees the wrong wiki's data.
+
+	### The database swap problem
+
+	SQLAlchemy's Flask extension (`flask_sqlalchemy`) creates an engine at app init time and caches it. The resolver reaches into `db._app_engines` to swap the engine directly. This is a private API that could break on any Flask-SQLAlchemy upgrade.
+
+	After swapping the engine, the resolver calls `otterwiki.server.update_app_config()` which does `SELECT * FROM preferences` and writes each row into `app.config`. This is how per-wiki preferences (READ_ACCESS, SITE_NAME, SITE_ICON, etc.) take effect.
+
+	### The multi-worker problem
+
+	With gunicorn's `preload_app = True` and multiple workers, each worker has its own copy of `app.config`. When one worker handles a preference change (e.g., user changes READ_ACCESS via admin UI), only that worker's `app.config` is updated. Other workers see stale values until they call `update_app_config()`.
+
+	Fix (2026-03-17): The fast path in `_swap_database()` now calls `update_app_config()` even when the engine URL already matches. This means every request does a `SELECT * FROM preferences` — a small SQLite read that's fast under WAL mode but worth noting as a performance characteristic.
+
+	### The default database problem
+
+	Otterwiki creates a default SQLAlchemy database at startup (before any request). The `settings.cfg` used to point this at `/tmp/otterwiki_default.db`, but Otterwiki's own default is `sqlite:///:memory:`. The problem: `update_app_config()` runs at startup against this default DB, and any preference rows in it overwrite `settings.cfg` values. This is why `SITE_ICON` set in `settings.cfg` was silently overridden to empty string.
+
+	Fix (2026-03-17): Removed the `SQLALCHEMY_DATABASE_URI` override from `settings.cfg`, letting Otterwiki use its in-memory default. All platform preferences (SITE_ICON, SITE_LOGO, access levels, etc.) are seeded into per-wiki DBs via `_init_wiki_db()`, where `update_app_config()` actually reads them.
+
+	Rule: Never use `settings.cfg` for preferences that `update_app_config()` manages. The DB always wins. See also the memory entry `feedback_otterwiki_config_override.md`.
+
+	## Key data structures
+
+	### Per-wiki SQLite DB (`/srv/data/wikis/{slug}/wiki.db`)
+
+	Seeded by `_init_wiki_db()` with `INSERT OR IGNORE` (idempotent, never overwrites user changes):
+
+	\| Preference \| Default \| Purpose \|
+	\|---\|---\|---\|
+	\| READ_ACCESS \| REGISTERED \| Who can read (ANONYMOUS/REGISTERED/APPROVED) \|
+	\| WRITE_ACCESS \| REGISTERED \| Who can write \|
+	\| ATTACHMENT_ACCESS \| REGISTERED \| Who can upload \|
+	\| AUTH_METHOD \| PROXY_HEADER \| Always proxy header in platform mode \|
+	\| DISABLE_REGISTRATION \| True \| Platform handles registration \|
+	\| AUTO_APPROVAL \| False \| Safety net \|
+	\| SITE_ICON \| `https://robot.wtf/static/robot.wtf.svg` \| Default favicon \|
+	\| SITE_LOGO \| `https://robot.wtf/static/robot.wtf.svg` \| Default nav icon \|
+
+	Also seeds the wiki owner into the `user` table as admin.
+
+	### Auth result dict
+
+	Returned by `_resolve_auth()`, consumed by the middleware:
+
+	```python
+	{
+	"proxy_headers": {"x-otterwiki-email": ..., "x-otterwiki-name": ..., "x-otterwiki-permissions": ...},
+	"is_authenticated": bool,
+	"is_bearer_token": bool,
+	"per_wiki_user": {"is_admin": bool, "is_approved": bool, "allow_read": bool, ...} \| None,
+	}
+	```
+
+	## Auth paths
+
+	\| Credential \| Path \| Permissions \|
+	\|---\|---\|---\|
+	\| JWT (Authorization header) \| `_resolve_jwt()` \| Owner → ADMIN; per-wiki user flags; fallback READ \|
+	\| JWT (cookie) \| `authenticate_from_cookie()` \| Same as above \|
+	\| Bearer token (opaque) \| `_resolve_bearer_token()` \| Editor role (READ+WRITE+UPLOAD), wiki-scoped \|
+	\| Internal API key \| Direct match \| ADMIN (MCP sidecar → REST API) \|
+	\| Anonymous \| No credentials \| READ, subject to access restrictions \|
+
+	Bearer tokens bypass per-wiki access restrictions (they're already scoped to a specific wiki by the token itself).
+
+	## Access restriction flow
+
+	After permissions are derived from auth, they're filtered by `_apply_wiki_access_restrictions()`:
+
+	- ANONYMOUS → no filter
+	- REGISTERED → unauthenticated users lose READ/WRITE/UPLOAD
+	- APPROVED → unauthenticated OR non-approved users lose READ/WRITE/UPLOAD
+	- ADMIN → never stripped
+
+	If an unauthenticated browser request has no remaining read permissions and READ_ACCESS != ANONYMOUS, the resolver redirects to `/auth/login?return_to={original_url}`.
+
+	## Known limitations
+
+	1. Module patching is fragile. Any new otterwiki module that imports `storage` at the top level needs to be added to `_swap_storage()`.
+	2. `db._app_engines` is a private API. Flask-SQLAlchemy updates could break the engine swap.
+	3. *One `SELECT ` per request** for preferences reload. Acceptable for current scale but would need caching for high throughput.
+	4. Disk quota enforcement is incomplete. `disk_usage_bytes` is always 0 (the wiki stats plugin isn't implemented yet), so quota checks are effectively dead code.
+
+	## Related pages
+
+	- [[Design/Auth]] — Auth architecture (superseded sections, but ATProto OAuth is current)
+	- [[Design/VPS_Architecture]] — Overall platform architecture
+	- [[Design/Admin_Panel_Reenablement]] — Per-wiki admin UI, which the resolver enables
+	- [[Plans/Disk_Usage_Caps]] — Planned fix for the quota dead code

Commit 355151

Commit `355151`