Commit d2ecf9
2026-03-14 17:22:04 Claude (MCP): [mcp] [mcp] E-2: CDN read path implementation plan| /dev/null .. Tasks/E-2_CDN_Read_Path.md | |
| @@ 0,0 1,225 @@ | |
| + | --- |
| + | category: reference |
| + | tags: [task, performance, cdn, architecture] |
| + | last_updated: 2026-03-14 |
| + | confidence: high |
| + | --- |
| + | |
| + | # E-2: CDN Read Path Implementation |
| + | |
| + | **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` |
| + | |
| + | ## Problem |
| + | |
| + | 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. |
| + | |
| + | ## Solution: Option A — Thin Assembly Lambda |
| + | |
| + | Per [[Design/CDN_Read_Path]], we decouple reads from the otterwiki Lambda: |
| + | |
| + | ``` |
| + | Write path (unchanged): |
| + | MCP/API → API Gateway → Otterwiki Lambda (VPC+EFS) → git repo |
| + | |
| + | Read path (new): |
| + | Browser → CloudFront → [cache hit] → HTML (~10-50ms) |
| + | → [cache miss] → Assembly Lambda (no VPC) → S3 fragments (~40ms warm, ~1s cold) |
| + | ``` |
| + | |
| + | ### Benchmarked Performance |
| + | |
| + | 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. |
| + | |
| + | ## Technical Feasibility (Validated) |
| + | |
| + | ### Content fragment rendering |
| + | |
| + | `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). |
| + | |
| + | ### Sidebar fragment rendering |
| + | |
| + | `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) |
| + | |
| + | **Decision: Option 1 — generic sidebar + client-side highlighting.** |
| + | |
| + | 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. |
| + | |
| + | ### Shell template |
| + | |
| + | 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) |
| + | |
| + | ### Plugin injection points |
| + | |
| + | 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. |
| + | |
| + | ## Implementation Plan |
| + | |
| + | ### Wave 1: Fragment Generation |
| + | |
| + | **Task E-2a: Write-time fragment renderer** |
| + | |
| + | 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. |
| + | |
| + | ### Wave 2: Assembly Lambda + Infrastructure |
| + | |
| + | **Task E-2b: Assembly Lambda** |
| + | |
| + | 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. |
| + | |
| + | ### Wave 3: Auth (Private Wikis) |
| + | |
| + | **Task E-2c: CloudFront auth for private wikis** |
| + | |
| + | 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. |
| + | |
| + | ### Wave 4: Migration + Cutover |
| + | |
| + | **Task E-2d: DNS cutover and backfill** |
| + | |
| + | 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 |
| + | |
| + | ## Open Questions |
| + | |
| + | 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. |
| + | |
| + | ## Cost |
| + | |
| + | - 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 |
| + | - **Total additional cost: ~$0/month** |
| + | |
| + | ## Estimated Effort |
| + | |
| + | | 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. |