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

Alga PSA Extension System Documentation (Enterprise)

Overview

1. Overview

   • Goals and isolation model
   • Architecture components (Runner, Registry, Gateway, UI)
   • Security and quotas

2. Implementation Plan

3. Runner Service

   • Responsibilities and interfaces
   • Static UI asset hosting (Rust ext-ui host; Next.js gate returns 404/redirect when RUNNER_PUBLIC_BASE is authoritative)
   • Execution model, quotas, and host APIs

Technical Specifications

1. Manifest v2 Schema

   • Schema definition and examples
   • Endpoints, ui.iframe, capabilities, precompiled artifacts, assets

2. Registry Implementation

   • Data model (registry, version, bundle, install, logs)
   • Services (publish/list/get/install)

3. API Routing Guide

   • /api/ext/[extensionId]/[...] gateway → Runner
   • Header, limit, and timeout policies

4. Security & Signing

   • Content‑addressed bundles (sha256:…)
   • Signature verification and trust bundles
   • Quotas and egress allowlists

Developer Resources

1. Development Guide

   • Building server handlers (WASM-first) that execute in the Runner
   • Iframe UI with SDK and UI kit (served by the Runner)
   • Packaging, signing, and publishing bundles

2. Local Development Guide

   • Running the Docker-based Extension Runner locally
   • Setting up the development environment
   • Building, installing, and testing extensions
   • Debugging and troubleshooting
   • Workflow tips and advanced configuration

3. DataTable Integration Guide

   • Using the UI kit DataTable in iframe apps

4. Sample Extension

   • Project structure
   • Gateway usage
   • End‑to‑end example

Core Rules (v2-only)

• All extension API requests use /api/ext/[extensionId]/[[...path]] and are proxied to the Runner POST /v1/execute (see server/src/app/api/ext/[extensionId]/[[...path]]/route.ts).
• UI is iframe-only and served by the Runner at ${RUNNER_PUBLIC_BASE}/ext-ui/{extensionId}/{content_hash}/[...]; the Next.js ext-ui route is a gate that returns 404 or redirects to the Runner when rust-host mode is enabled.
• UI→Handler communication uses the postMessage proxy pattern (NOT direct fetch() calls). The iframe sends apiproxy messages to the host, which forwards to /api/ext-proxy/{extensionId}/{route}. Requires cap:ui.proxy capability.
• The host constructs iframe src via buildExtUiSrc() and bootstraps via bootstrapIframe().
• Registry v2 is authoritative for extension versions and bundle metadata (see ExtensionRegistryServiceV2).

See the Implementation Plan for additional details.