284313f908
Some checks are pending
Bidi Control Character Guard / bidi-control-guard (push) Waiting to run
Circular Dependency Check / Check for new circular dependencies (push) Waiting to run
Citus Migration Smoke / Combined migrations on single-node Citus (push) Waiting to run
E2E Fresh Install Tests / fresh-install-e2e (push) Waiting to run
ext-v2 guardrails / Run ext-v2 guard and ESLint (push) Waiting to run
Integration Tests / Check for relevant changes (push) Waiting to run
Integration Tests / ${{ (github.event_name == 'schedule' || github.event.inputs.suite == 'full') && 'Full integration suite' || 'Tier-1 integration subset' }} (push) Blocked by required conditions
Mobile checks / Mobile lint + typecheck (push) Waiting to run
Mobile checks / Mobile unit tests (push) Waiting to run
Mobile checks / Mobile dependency audit (report) (push) Waiting to run
Mobile checks / Mobile reproducibility checks (push) Waiting to run
Secrets guard (env backups) / Ensure no tracked env backup files (push) Waiting to run
Temporal Readiness / fast-readiness (push) Waiting to run
Temporal Readiness / docker-parity (push) Waiting to run
TypeScript Type Check / Nx affected typecheck (push) Waiting to run
Unit Tests / Skipped-test budget (push) Waiting to run
Unit Tests / Nx affected unit tests (push) Waiting to run
Unit Tests / Server unit coverage (informational) (push) Waiting to run
Validate Tenant Management Schema / Check for relevant changes (push) Waiting to run
Validate Tenant Management Schema / Validate Tenant Management Schema (push) Blocked by required conditions
EE Workflows Build Guard / ee-workflows-build-guard (push) Waiting to run
Excluded: .git, node_modules, secrets/, compose.env, assemblyscript tgz Source: /opt/alga-psa on psa.joliet.tech
66 lines
3.0 KiB
Markdown
66 lines
3.0 KiB
Markdown
# Alga PSA Extension System Documentation (Enterprise)
|
||
|
||
## Overview
|
||
|
||
1. [Overview](overview.md)
|
||
- Goals and isolation model
|
||
- Architecture components (Runner, Registry, Gateway, UI)
|
||
- Security and quotas
|
||
|
||
2. [Implementation Plan](implementation_plan.md)
|
||
3. [Runner Service](runner.md)
|
||
- 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](manifest_schema.md)
|
||
- Schema definition and examples
|
||
- Endpoints, ui.iframe, capabilities, precompiled artifacts, assets
|
||
|
||
2. [Registry Implementation](registry_implementation.md)
|
||
- Data model (registry, version, bundle, install, logs)
|
||
- Services (publish/list/get/install)
|
||
|
||
3. [API Routing Guide](api-routing-guide.md)
|
||
- `/api/ext/[extensionId]/[...]` gateway → Runner
|
||
- Header, limit, and timeout policies
|
||
|
||
4. [Security & Signing](security_signing.md)
|
||
- Content‑addressed bundles (sha256:…)
|
||
- Signature verification and trust bundles
|
||
- Quotas and egress allowlists
|
||
|
||
## Developer Resources
|
||
|
||
1. [Development Guide](development_guide.md)
|
||
- 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](local-development.md)
|
||
- 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](datatable-integration-guide.md)
|
||
- Using the UI kit DataTable in iframe apps
|
||
|
||
4. [Sample Extension](sample_template.md)
|
||
- 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](../../../server/src/app/api/ext/%5BextensionId%5D/%5B%5B...path%5D%5D/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()](../../../server/src/lib/extensions/ui/iframeBridge.ts:38) and bootstraps via [bootstrapIframe()](../../../server/src/lib/extensions/ui/iframeBridge.ts:45).
|
||
- Registry v2 is authoritative for extension versions and bundle metadata (see [ExtensionRegistryServiceV2](../../../server/src/lib/extensions/registry-v2.ts:48)).
|
||
|
||
See the [Implementation Plan](implementation_plan.md) for additional details.
|