category: reference

tags: [task, performance, cdn, architecture]

last_updated: 2026-03-14

**Status:** Planned

**Depends on:** Phase 2 complete, [[Dev/E-1_Cold_Start_Benchmarks]], [[Design/CDN_Read_Path]]

**Branch:** `feat/E-2-cdn-read-path` from `phase-2`

The otterwiki Lambda cold starts in ~4.5s (see [[Dev/E-1_Cold_Start_Benchmarks]]). 79% of that is `from otterwiki.server import app`. Wiki pages are read-heavy, write-light. The read path should not depend on the heavy Lambda.

Per [[Design/CDN_Read_Path]], we decouple reads from the otterwiki Lambda:

From the assembly Lambda spike:

| Scenario | Assembly time | Wall time |

|----------|-------------|-----------|

| Warm 256MB | 41ms | 144ms |

| Cold 256MB | 416ms | 1,230ms |

| Cold 128MB | 852ms | 1,708ms |

Behind CloudFront with 30s TTL, most reads are cache hits (~10-50ms). Cache misses hit the assembly Lambda, which stays warm with any traffic. Worst case (cold Lambda + cache miss) is ~1s — still 4x better than the otterwiki Lambda.

`OtterwikiRenderer.markdown(text)` is fully context-free. No Flask request context, no `current_user`, no `url_for` needed. Returns `(html, toc, library_requirements)`.

Wiki links (`[[PageName]]`) render as plain `<a href="/PageName">` tags — no page-exists lookup, no red/blue coloring. Config flags `WIKILINK_STYLE` and `TREAT_UNDERSCORE_AS_SPACE_FOR_TITLES` affect rendering but are static per wiki.

Plugin hooks (`renderer_markdown_preprocess`, `renderer_html_postprocess`) are no-ops for our installed plugins (otterwiki-api and otterwiki-semantic-search inject nothing into rendered HTML).

`SidebarPageIndex` needs:

- `storage.list()` — file list from git (available in the write Lambda at page-save time)

- `app.config` — sidebar mode, focus, max_depth, case settings (static per wiki)

It does NOT need a Flask request context. The focus-mode highlighting depends on `pagepath` (current page), so we have two options:

1. Render a generic sidebar (all nodes collapsed/expanded per mode) and apply current-page highlighting client-side with a tiny JS snippet (~5 lines)

2. Render per-page sidebars (expensive for large wikis, doesn't scale)

The sidebar shortcut links (Home, A-Z, Create Page) are gated by `has_permission('READ')` and `has_permission('WRITE')`. For the CDN read path, we show the READ-level shortcuts only. Write-level features (Create Page, Edit button) are not relevant to the read path.

The otterwiki template hierarchy is `page.html` → `wiki.html` → `layout.html`.

The shell needs to include:

- CSS links: `halfmoon.min.css`, `otterwiki.css`, `print.css`, `fontawesome-all.min.css`, `pygments.css`, `roboto.css`

- JS: `halfmoon.min.js`, `otterwiki.js`

- Site name, logo, search form (static per wiki)

- `{{SIDEBAR}}` and `{{CONTENT}}` placeholders

What we strip from the shell:

- Edit/Rename/Delete buttons (write operations — not on read path)

- Login/Logout dropdown (auth — not on CDN read path)

- `request.cookies.get('halfmoon_preferredMode')` — handle dark mode client-side via JS (read cookie, apply class before first paint to avoid flash)

- Flash messages (session-scoped, not applicable)

- CSRF tokens (none in page view anyway)

Both otterwiki-api and otterwiki-semantic-search implement zero template injection hooks. The four injection points (`plugin_html_head_inject`, `plugin_html_body_inject`, `plugin_sidebar_left_inject`, `plugin_sidebar_right_inject`) all return empty strings. Safe to omit from shell.

New otterwiki plugin hook implementation or resolver middleware that fires on page save:

1. `app/cdn/fragment_renderer.py` — Fragment generation module:

- `render_content_fragment(markdown_text, config) -> str` — calls `OtterwikiRenderer.markdown()`, returns content HTML

- `render_sidebar_fragment(file_list, config) -> str` — builds page tree, renders menutree HTML without request context

- `render_shell_template(wiki_config) -> str` — generates the static shell HTML with `{{SIDEBAR}}` and `{{CONTENT}}` placeholders

2. `app/cdn/s3_publisher.py` — S3 upload module:

- `publish_content(user_id, wiki_slug, page_path, html)` — uploads to `s3://bucket/fragments/{user_id}/{wiki_slug}/pages/{page_path}.html`

- `publish_sidebar(user_id, wiki_slug, html)` — uploads sidebar fragment

- `publish_shell(user_id, wiki_slug, html)` — uploads shell template

- Uses boto3 with `ContentType: text/html` and `CacheControl: max-age=31536000` (fragments are immutable — cache invalidation happens by serving new content through the assembly Lambda)

3. Integration point — two options:

- **Option A: otterwiki plugin hook** — implement `page_saved(app, storage, pagepath, message)` hook. Fires after every page save. Natural integration point, already used by semantic-search plugin.

- **Option B: resolver middleware** — intercept successful write responses in `TenantResolver` and trigger fragment generation post-response. More complex, but doesn't require modifying the otterwiki plugin.

- **Decision: Option A** — plugin hook is cleaner and already proven.

4. Sidebar regeneration triggers:

- Page create (new file in tree) — regenerate sidebar

- Page delete — regenerate sidebar

- Page rename — regenerate sidebar

- Content-only edit — do NOT regenerate sidebar (file list unchanged)

- Detection: compare `storage.list()` before/after, or check if the `page_saved` hook's metadata indicates a new page vs edit

5. Shell regeneration triggers:

- Wiki settings change (site name, logo, sidebar config)

- Deploy (template/CSS changes)

- Rare — can be manual or triggered by management API

**Tests:** ~15 unit tests with mocked S3 and a real OtterwikiRenderer instance.

Based on the validated spike (`app/poc/assembly_lambda.py`):

1. `app/cdn/assembly_handler.py` — Production assembly Lambda:

- Parse request: extract `{username}/{wiki_slug}/{page_path}` from CloudFront-forwarded path

- Fetch 3 fragments from S3 in parallel (ThreadPoolExecutor)

- String-substitute into shell template

- Apply sidebar current-page highlighting (inject `data-current-page` attribute, let client JS handle)

- Return assembled HTML with `Cache-Control: public, max-age=30`

- Handle 404 (missing fragments → page not found)

- Handle conditional rendering (MathJax/Mermaid JS inclusion based on content fragment metadata or markers)

2. `infra/__main__.py` additions:

- S3 bucket for fragments (or reuse existing `lambda-code-bucket`)

- `SimpleLambdaComponent` for assembly Lambda (256MB, no VPC)

- IAM: S3 GetObject on `fragments/*`

- CloudFront distribution:

- Origin 1: Assembly Lambda (read path, default behavior)

- Origin 2: API Gateway (write path — `/admin/*`, MCP, API routes)

- Behaviors: `GET /{username}/{wiki}/*` → Assembly Lambda origin; `POST/PUT/DELETE *` → API Gateway origin; static assets → S3 or passthrough

- CloudFront cache policy: 30s TTL, cache by path only (not cookies/headers for public wikis)

- DNS: point `*.wikibot.io` at CloudFront (currently points at API Gateway)

3. Cache invalidation:

- On page save, the fragment renderer publishes new fragments to S3

- The assembly Lambda always fetches fresh fragments (S3 reads, not cached in Lambda memory)

- CloudFront TTL of 30s means pages are at most 30s stale — acceptable for a wiki

- Optional: explicit CloudFront invalidation via API on page save (adds complexity, saves 30s staleness)

**Tests:** ~10 unit tests for assembly handler. Integration test: invoke Lambda, verify HTML output.

1. CloudFront Functions (viewer-request):

- Check if wiki is public (lookup from a lightweight config file in S3, or baked into CloudFront Function config)

- Public wiki: pass through

- Private wiki: validate JWT from `Authorization` header or cookie

- JWT validation in CloudFront Functions is limited (no async, no network calls) — must use symmetric signing (HMAC) or pre-validated tokens

- Alternative: Lambda@Edge for full JWT validation (adds ~5ms latency, supports RS256)

2. Design decision needed: how to communicate wiki visibility to CloudFront

- Option: S3 metadata file per wiki (`fragments/{user}/{wiki}/config.json` with `is_public: true/false`)

- Option: CloudFront Function reads a KV store (CloudFront KeyValueStore)

- Option: Assembly Lambda handles auth (simplest — add auth check before fragment fetch)

**Decision: Defer to implementation time.** For MVP, the assembly Lambda can check auth. Move to CloudFront Functions later for performance.

1. Backfill existing wiki pages:

- Script to iterate all wikis in DynamoDB, read all pages from EFS, render fragments, upload to S3

- Run once before cutover

2. DNS cutover:

- Point `*.wikibot.io` at CloudFront instead of API Gateway

- CloudFront routes reads to assembly Lambda, writes to API Gateway origin

- `dev.wikibot.io` continues to point at API Gateway (management/admin)

3. Verify:

- Page reads served from CloudFront (check `X-Cache` header)

- Page writes still work (MCP, API)

- New pages appear within 30s of creation

- Sidebar updates on page create/delete

1. **MathJax/Mermaid conditional loading:** The current `page.html` includes MathJax/Mermaid JS only when `library_requirements` indicates the page uses them. The assembly Lambda needs this signal — either embed it as a data attribute in the content fragment, or always include the JS (adds ~100KB to page weight but simplifies assembly).

2. **Search:** The search form POSTs to the otterwiki Lambda. With CloudFront in front, search requests need to route to the API Gateway origin. This is a CloudFront behavior routing question.

3. **Static assets:** otterwiki serves CSS/JS/fonts from Flask's static file handler. These should be served from S3/CloudFront for performance. Either extract otterwiki's static directory to S3 at build time, or configure CloudFront to forward `/static/*` to the API Gateway origin (slower but simpler for MVP).

4. **TOC (Table of Contents):** The right sidebar "On this page" TOC is generated from the page content. It could be included in the content fragment as a separate `{{TOC}}` placeholder, or rendered client-side from heading elements.

5. **Page history/blame/diff:** These dynamic views cannot be pre-rendered. They should route to the otterwiki Lambda via API Gateway origin. CloudFront behavior: `/-/*` → API Gateway.

- S3 fragment storage: pennies (few KB per page × number of pages)

- CloudFront: free tier (1TB/month, 10M requests/month)

- Assembly Lambda: scales to zero, ~$0/month at low traffic

| Wave | Effort | Dependencies |

|------|--------|-------------|

| E-2a: Fragment renderer | 1 day | OtterwikiRenderer API |

| E-2b: Assembly Lambda + CloudFront | 1 day | E-2a |

| E-2c: Auth | 0.5 day | E-2b |

| E-2d: Migration + cutover | 0.5 day | E-2a, E-2b |

Total: ~3 days via agent delegation model.