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:

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

Also seeds the wiki owner into the user table as admin.

Auth result dict

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

Auth paths

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