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
112 lines
13 KiB
Markdown
112 lines
13 KiB
Markdown
# Extension Documentation Overhaul Notes
|
|
|
|
Objective: track progress while reviewing and updating extension-related docs; capture issues, mismatches with code, and re-review needs.
|
|
|
|
## Doc inventory & status
|
|
- [x] ee/docs/extension-system/index.md
|
|
- [x] ee/docs/extension-system/overview.md
|
|
- [x] ee/docs/extension-system/README.md
|
|
- [x] ee/docs/extension-system/development_guide.md
|
|
- [x] ee/docs/extension-system/api-routing-guide.md
|
|
- [x] ee/docs/extension-system/serving-system.md
|
|
- [x] ee/docs/extension-system/template-system-guide.md
|
|
- [x] ee/docs/extension-system/datatable-integration-guide.md
|
|
- [x] ee/docs/extension-system/manifest_schema.md
|
|
- [x] ee/docs/schemas/extension-manifest.v2.schema.json (schema source)
|
|
- [x] ee/docs/extension-system/registry_implementation.md
|
|
- [x] ee/docs/extension-system/enterprise-build-workflow.md
|
|
- [x] ee/docs/extension-system/knative-app-domains.md
|
|
- [x] ee/docs/extension-system/runner.md
|
|
- [x] ee/docs/extension-system/runner_guest_abi.md
|
|
- [x] ee/docs/extension-system/runner-s3-integration.md
|
|
- [x] ee/docs/extension-system/storage-api-contract.md
|
|
- [x] ee/docs/extension-system/storage-api-operations.md
|
|
- [x] ee/docs/extension-system/storage-api-schema.md
|
|
- [x] ee/docs/extension-system/storage-api-validation.md
|
|
- [x] ee/docs/extension-system/storage-api-access-control.md
|
|
- [x] ee/docs/extension-system/storage-api-runner.md
|
|
- [x] ee/docs/extension-system/storage-api-rollout.md
|
|
- [x] ee/docs/extension-system/security_signing.md
|
|
- [x] ee/docs/extension-system/sample_template.md
|
|
- [x] ee/docs/extension-system/samples/hello-world-e2e.md
|
|
- [x] ee/docs/extension-system/e2e-minio-walkthrough.md
|
|
- [x] ee/docs/extension-system/implementation_plan.md
|
|
- [x] ee/docs/extension-system/implementation_scratchpad.md
|
|
- [x] ee/docs/extension-system/descriptor-architecture-implementation-plan.md
|
|
- [x] ee/docs/extension-system/comprehensive-analysis-report.md
|
|
- [x] docs/skills/extension-system-troubleshooting.md
|
|
- [x] ee/docs/examples/extension-bundle-v2/README.md
|
|
- [x] ee/docs/examples/extension-react-app/README.md
|
|
- [x] extension-related plan docs (ee/docs/plans/*extension*).*Triage for relevance/retirement*
|
|
|
|
## Re-review candidates
|
|
- (Add items here when a doc needs a second pass after new discoveries.)
|
|
|
|
## Findings & actions
|
|
- Index/README/Overview reviewed:
|
|
- Links point to `ee/server/src/lib/extensions/ui/iframeBridge.ts` and `/api/ext` route without `[[...path]]`; actual gateway handler lives at `server/src/app/api/ext/[extensionId]/[[...path]]/route.ts` and is aliased via `@ee`, so links should target `server/src/...`. The ext-ui builder with session/theming is in `server/src/lib/extensions/ui/iframeBridge.ts`, while the `ee/server` version is a minimal sandbox+resize helper—docs need to clarify which one is canonical.
|
|
- Docs assert "no Next.js route for ext-ui". Code has a gate at `server/src/app/ext-ui/[extensionId]/[contentHash]/[...path]/route.ts` that returns 404/redirect when `EXT_UI_HOST_MODE=rust`; documentation should mention this guard instead of absence.
|
|
- buildExtUiSrc references should point at `server/src/lib/extensions/assets/url.shared.ts` (single source of truth) rather than the `ee/server` bridge file which no longer exports it.
|
|
- Development Guide reviewed:
|
|
- Gateway description still includes manifest endpoint matching; the live handler in `server/src/app/api/ext/[extensionId]/[[...path]]/route.ts` does not load or enforce manifest endpoints (no `matchEndpoint` call). Need to note this advisory-only status and update examples to reflect current code.
|
|
- Markdown links to iframe helpers use `../../server/...` which resolves to `ee/server/...` and misses the canonical implementation in `server/src/lib/extensions/ui/iframeBridge.ts` + `assets/url.shared.ts`. Update links and clarify that sandbox defaults differ (runtime uses `allow-scripts` only, not `allow-same-origin`).
|
|
- API Routing Guide reviewed:
|
|
- Request header forwarding in docs lists `x-idempotency-key`, `x-alga-tenant`, etc.; actual `filterRequestHeaders` only forwards `x-request-id`, `accept`, `content-type`, `accept-encoding`, `user-agent` and strips auth before the handler adds tenant/extension ids. Update header policy section to match `server/src/lib/extensions/gateway/headers.ts`.
|
|
- Manifest endpoint resolution step is described but not implemented in the current route handler; call out as future work with pointer to alignment plan.
|
|
- Body limit currently hard-coded to 10 MiB and timeout default 5s; reflect these exact values.
|
|
- Runner doc reviewed:
|
|
- Same iframe helper link issue: should reference `server/src/lib/extensions/ui/iframeBridge.ts` (canonical) + `assets/url.shared.ts`; the `ee/server` helper has divergent sandbox defaults.
|
|
- Header allowlist notes mention custom `x-ext-*` headers; Runner/Gateway code only allows `content-type`, `cache-control`, `etag` from Runner today (`server/src/lib/extensions/gateway/headers.ts`). Need to reconcile or update code if x-ext headers are required.
|
|
- Document states host enforces sandbox without `allow-same-origin`, aligning with `server/src/lib/extensions/ui/iframeBridge.ts`, but the `@ee/lib` version defaults to `allow-same-origin`; clarify target implementation.
|
|
- Manifest Schema doc reviewed:
|
|
- Relies on manifest endpoints having `handler` strings even though Gateway no longer uses them for routing (no `endpoint` in execute payload). Clarify whether `handler` is for docs/telemetry only and align JSON schema accordingly.
|
|
- UI delivery + iframe helper links again point to `../../server/...` (resolving to `ee/server`); canonical helper lives in `server/src/lib/extensions/ui/iframeBridge.ts` with builder in `assets/url.shared.ts`. Update paths.
|
|
- Routing section mentions manifest enforcement; reconcile with current Gateway behavior (no matchEndpoint) and note ext-ui Next.js gate that returns 404/redirect when rust host is authoritative.
|
|
- Serving System doc reviewed:
|
|
- Claims "no Next.js route for ext-ui" and suggests optional manifest resolution; actual code has ext-ui gate (`server/src/app/ext-ui/[extensionId]/[contentHash]/[...path]/route.ts`) and Gateway does not match endpoints. Mentions idempotency/retry behavior that is not implemented in the handler (no retries, idempotency key set to request id only).
|
|
- Template & DataTable guides reviewed:
|
|
- Gateway links still point to `ee/server/.../[...path]`; canonical route is `server/src/app/api/ext/[extensionId]/[[...path]]/route.ts`. Both guides assert no ext-ui route and reference iframe helpers in `ee/server`; update to `server/src/lib/extensions/ui/iframeBridge.ts` + `assets/url.shared.ts` and mention the ext-ui gate behavior.
|
|
- Runner S3 Integration reviewed:
|
|
- Execution section still refers to `{ handler, payload }` flow; Gateway now sends componentized payload without `handler` selection. Update to reflect `context/http/limits/config/providers/secret_envelope` shape from the live handler.
|
|
- Storage API docs (contract/operations/schema/validation/access-control/runner/rollout):
|
|
- Marked "archived" but the platform still exposes install-scoped storage endpoints and capabilities (`ee/server/src/app/api/internal/ext-storage/install/[installId]/route.ts`, manifest schema includes `storage.kv`, runner providers in `ee/runner/src/providers/mod.rs`). Need to either update docs to reflect current behavior or plan code deprecation; access-control section still lists quotas/feature flags that are not connected to current code.
|
|
- Registry Implementation reviewed:
|
|
- Gateway flow step lists manifest endpoint matching and `[...path]`; live route uses `[[...path]]` and does not match endpoints. Update data flow to match actual handler and modern registry facade (`server/src/app/api/ext/...`).
|
|
- Runner Guest ABI reviewed:
|
|
- Describes legacy alloc/handler JSON ABI; current runtime uses Wasmtime Component Model (`runtime: "wasm-js@1"`, WIT in `sdk/alga-client-sdk/templates/component-basic/wit/extension-runner.wit`). Document should be archived or rewritten for the component ABI and host capabilities.
|
|
- Security & Signing reviewed:
|
|
- Same path/link drift (gateway link uses `ee/server/.../[...path]`, iframe helpers point to `ee/server`), and asserts manifest matching + x-ext response headers that are not implemented (`filterResponseHeaders` allows only content-type/cache-control/etag). Needs alignment with gateway code and ext-ui gate wording.
|
|
- Sample Template & UI guides reviewed:
|
|
- Sample template still shows direct `.wasm` handler artifacts and manifest endpoints with `handler` paths, not the componentized `wasm-js@1` flow currently documented elsewhere. Update examples to use componentized output + SDK bootstrap. Gateway links again use `ee/server/.../[...path]` instead of `server/.../[[...path]]`.
|
|
- Hello World sample & MinIO walkthrough reviewed:
|
|
- MinIO walkthrough uses a manifest format (`extension`, `entry.wasm`) that does not match manifest v2 schema (expects `name/publisher/runtime`). Needs rewrite to align with current manifest and signing rules.
|
|
- Hello World sample instructions assume Runner-served UI is auto-wired; ensure install UI/page references are still correct (they point to `ee/server` components) and consider adding a componentized server handler example, not just UI-only.
|
|
- Implementation Plan reviewed:
|
|
- References gateway route at `ee/server/.../[...path]` and includes manifest endpoint matching + retries that are not present. Should update milestone descriptions to match actual behavior (no endpoint enforcement, canonical iframe helper path, ext-ui gate).
|
|
- Knative app domains doc reviewed:
|
|
- Operational flow assumes Runner exposes `/` redirect and `/ext-ui` validation endpoints; need to verify against current runner implementation before keeping. Could fold into infra runbook section once validated.
|
|
- Extension-related plan docs reviewed:
|
|
- Pluggable runner backend: implemented (env `RUNNER_BACKEND`, backend abstraction, dev compose); ext-ui same-origin proxy/testing still open.
|
|
- Debug stream UI: runner→Redis→SSE→UI path exists; authz/capability gating still pending.
|
|
- Runtime metadata/secrets: gateway now forwards config/providers/secretEnvelope; runner host provides secrets/storage; need schema/doc alignment and install_id propagation.
|
|
- Storage API: runner storage capability and internal ext-storage API exist; quotas/RBAC alignment pending.
|
|
- Upload proxy streaming: server upload-proxy route streams to S3 with rate limits; need UI adoption confirmation.
|
|
- Client portal extension support: manifest/client portal UI/runtime delivered; add tests/docs.
|
|
- Troubleshooting skill doc reviewed:
|
|
- Assumes bundle paths include tenant/extension prefix (`tenants/<tenant>/extensions/<ext>/sha256/...`) and advises adding `?tenant` query for iframe; current storage layout and `buildExtUiSrc` produce content-hash-only paths with `extensionId`+`path` params (tenant optional). Update steps and commands (MinIO paths, env vars) to reflect canonical `sha256/<hash>` layout.
|
|
- Example bundle v2 README reviewed:
|
|
- States UI is served via API gateway cache; current architecture serves via Runner (`RUNNER_PUBLIC_BASE`) with Next.js gate returning 404/redirect. Example still uses `.wasm` handler artifacts instead of componentized output. Update to match Runner host model and manifest v2 requirements.
|
|
- Manifest schema source (JSON) vs runtime schema reviewed:
|
|
- JSON schema now aligned with runtime schema: `api` optional, `capabilities` default [], `entry` removed. Need to keep docs in sync and decide on any future entry usage.
|
|
- Implementation Scratchpad reviewed:
|
|
- Checklists reference `/api/ext/[extensionId]/[...path]` and early phases; does not reflect current code (route is `[[...path]]`, manifest enforcement removed, bundles/runner implemented). Needs refresh or archival to avoid confusion with main implementation plan.
|
|
- Descriptor/Architecture plan reviewed:
|
|
- Still references `/api/ext/[...path]` and claims no Next.js ext-ui route; same iframe helper link drift. Should be trimmed or merged into overview/index to avoid duplicating outdated claims.
|
|
- Comprehensive analysis report reviewed:
|
|
- Duplicates overview content but still references `/api/ext/[...path]`, endpoint resolution, and iframe links to `ee/server`. Consider consolidating into overview once paths and enforcement notes are corrected.
|
|
|
|
## Structural reorg ideas
|
|
- Nominate a single canonical host reference file (`server/src/lib/extensions/ui/iframeBridge.ts` + `assets/url.shared.ts`) and fix all links; add a short “Host embedding quickstart” doc.
|
|
- Consolidate overview/index/analysis/descriptor docs into one authoritative overview; demote/retire duplicates once updated paths/enforcement notes are in place.
|
|
- Replace archived-but-active storage docs with an up-to-date “Storage capability” doc aligned to current runner/API code, or explicitly plan code removal; move remaining archived files to an `archive/` subfolder.
|