category: spec

tags: [architecture, resolver, multi-tenant, auth]

last_updated: 2026-03-17

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`.

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

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.

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:

otterwiki.server.storage = storage

otterwiki.wiki.storage = storage

otterwiki.helper.storage = storage

If a new otterwiki module imports `storage` and we don't patch it, that module sees the wrong wiki's data.

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.

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.

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`.

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.

Returned by `_resolve_auth()`, consumed by the middleware:

"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,

| 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).

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}`.

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.

- [[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