PSA/ee/docs/extension-system/implementation_plan.md

Extension System Implementation Plan (Enterprise v2)

This plan specifies the v2 Enterprise extension architecture: out-of-process execution in the Runner, signed/content-addressed bundles, a Next.js API Gateway proxying to Runner /v1/execute, and iframe-only UI served by the Runner.

Phase 0 — Foundations and Switches

• EE-only wiring: ensure extension code paths are included only in enterprise builds
• Env/config for object store, gateway timeout, Runner base/public URL, and trust bundle
• Finalize Manifest v2 schema and example bundle layout

Phase 1 — Database Schema and Registry Services

• Add EE migrations:
  • extension_registry, extension_version, extension_bundle
  • tenant_extension_install, extension_event_subscription
  • extension_execution_log, extension_quota_usage
  • Enforce tenant isolation (RLS where applicable)
• Implement registry service for publish/list/get; version metadata includes content_hash, signature, runtime, precompiled, and api.endpoints
• Implement tenant install service (install/uninstall/enable/disable; granted_caps, config, version_id)
• Implement signature verification utility (trust bundle)

Phase 2 — Bundle Storage Integration

• Use S3‑compatible storage provider (e.g., MinIO)
• Implement bundle helpers: getBundleStream, getBundleIndex, extractSubtree for dist/ and ui/
• Support optional precompiled artifacts (cwasm) indexed by target triple

Phase 3 — Runner Service (Rust + Wasmtime)

• Runner HTTP API: POST /v1/execute
• Configure Wasmtime (pooling allocator, store limits, epoch timeouts, optional fuel)
• Implement host imports: alga.storage.*, alga.http.fetch, alga.secrets.get, alga.log.*, alga.metrics.emit
• Fetch/verify/cache modules by content_hash; LRU policy
• Return normalized {status, headers, body_b64} with standardized error codes and traces

Phase 4 — Next.js API Gateway

• Add route scaffold: server/src/app/api/ext/[extensionId]/[[...path]]/route.ts
• Implement helpers: auth/tenant, registry resolution, endpoint matching, header filtering
• Proxy to Runner POST ${RUNNER_BASE_URL}/v1/execute with service token, timeouts, limited retries
• Enforce quotas and body/header size caps via configuration (EXT_GATEWAY_TIMEOUT_MS, etc.)

Phase 5 — Runner Static UI Hosting

• Serve iframe UI assets from Runner at ${RUNNER_PUBLIC_BASE}/ext-ui/{extensionId}/{content_hash}/[...]
• Immutable caching (ETag + Cache-Control: immutable)
• Runner-managed cache for ui/**/* by content_hash
• Host constructs iframe URL using buildExtUiSrc() and bootstraps via bootstrapIframe()

Phase 6 — Client SDK and UI Kit

• Packages:
  • @alga/extension-iframe-sdk (handshake, postMessage, auth, navigation, theme)
  • @alga/ui-kit (components, tokens, hooks)
• Provide starter React template using SDK and UI kit
• Implement host bridge bootstrap with theme tokens/session propagation

Phase 7 — Knative Serving (Runner)

• KService manifest with concurrency/scale bounds; health and warmup endpoints
• CI/CD step to deploy Runner revision and smoke test /v1/execute

Phase 8 — Admin UX and Install Flows

• Admin UI for per‑tenant installs, versions, and capability grants
• “Open Extension” navigates to iframe app constructed from Runner public base and the installed version’s content_hash

Phase 9 — Security, Quotas, Policy

• Enforce capability grants; deny host imports when missing
• Per‑tenant egress allowlists for http.fetch
• Integrate secrets manager; enforce rotation policies
• Configure per‑tenant/per‑extension quotas and rate limits

Phase 10 — Observability and Ops

• Structured execution logs with correlation IDs; persist to DB
• Prometheus metrics from Runner: duration, memory, fuel, egress bytes, errors
• Dashboards and alerts for failure rates, timeouts, resource breaches

Phase 11 — Docs, Samples, Pilot

• Developer docs for manifest, building, publishing, installing, and iframe development
• Full sample extension (server handlers + iframe UI)
• Pilot with a partner tenant; validate SLOs and collect feedback

Acceptance Criteria (Milestones)

• M1: Registry + Bundle Store + Signing operational; can install signed bundles
• M2: Runner executes hello‑world with quotas/timeouts and audit logs
• M3: Client SDK (iframe) + Runner UI hosting operational; CSP and sandbox enforced
• M4: First partner extension on v2 end‑to‑end

References

• Overview: overview.md
• Routing: api-routing-guide.md
• Security & Signing: security_signing.md
• Registry: registry_implementation.md
• Gateway route scaffold: server/src/app/api/ext/[extensionId]/[[...path]]/route.ts
• Iframe bootstrap and src builder: server/src/lib/extensions/ui/iframeBridge.ts