182 lines
4.7 KiB
Markdown
182 lines
4.7 KiB
Markdown
# Surfaces
|
|
|
|
Dynamic surface lifecycle. Core surfaces are registered at startup.
|
|
Extension surfaces are uploaded by admins and served from the
|
|
`surface_registry` table.
|
|
|
|
## User Endpoints
|
|
|
|
### List Enabled Surfaces
|
|
|
|
```
|
|
GET /surfaces
|
|
```
|
|
|
|
Returns enabled surfaces with minimal nav info (no `source` or `enabled`
|
|
fields — these are admin concerns).
|
|
|
|
```json
|
|
{
|
|
"surfaces": [
|
|
{ "id": "chat", "title": "Chat", "route": "/" },
|
|
{ "id": "editor", "title": "Editor", "route": "/editor" },
|
|
{ "id": "hello-dashboard", "title": "Hello Dashboard", "route": "/s/hello-dashboard" }
|
|
]
|
|
}
|
|
```
|
|
|
|
**Auth:** Authenticated.
|
|
|
|
## Admin Endpoints
|
|
|
|
### List All Surfaces
|
|
|
|
```
|
|
GET /admin/surfaces
|
|
```
|
|
|
|
Returns all surfaces including disabled ones. Each entry is a full
|
|
[Surface Registry Object](#surface-registry-object).
|
|
|
|
```json
|
|
{
|
|
"surfaces": [
|
|
{ "id": "chat", "title": "Chat", "manifest": {...}, "enabled": true, "source": "core", "installed_at": "...", "updated_at": "..." },
|
|
{ "id": "hello-dashboard", "title": "Hello Dashboard", "manifest": {...}, "enabled": false, "source": "extension", "installed_at": "...", "updated_at": "..." }
|
|
]
|
|
}
|
|
```
|
|
|
|
**Auth:** Platform admin.
|
|
|
|
### Get Surface
|
|
|
|
```
|
|
GET /admin/surfaces/:id
|
|
```
|
|
|
|
Returns full surface details including manifest.
|
|
|
|
**Response:** A single [Surface Registry Object](#surface-registry-object).
|
|
|
|
**Errors:**
|
|
- `404` — surface not found (or store error).
|
|
|
|
**Auth:** Platform admin.
|
|
|
|
### Install Surface
|
|
|
|
```
|
|
POST /admin/surfaces/install
|
|
Content-Type: multipart/form-data
|
|
```
|
|
|
|
Field: `file` — a `.surface` or `.zip` archive (zip containing
|
|
`manifest.json` + static assets). The manifest declares `id`, `title`,
|
|
`route`, required data loaders, scripts, and CSS.
|
|
|
|
**Size limit:** 50 MB.
|
|
|
|
**Manifest validation:** `id` and `title` are required.
|
|
|
|
**Errors:**
|
|
- `400` — no file, wrong extension, too large, invalid zip, missing or
|
|
invalid manifest, missing `id`/`title`.
|
|
- `409` — surface ID conflicts with an existing core surface.
|
|
|
|
**Auth:** Platform admin.
|
|
|
|
### Enable / Disable
|
|
|
|
```
|
|
PUT /admin/surfaces/:id/enable
|
|
PUT /admin/surfaces/:id/disable
|
|
```
|
|
|
|
Disabled surfaces redirect to `/` and hide from navigation.
|
|
|
|
**Undisableable surfaces:** `chat` and `admin` cannot be disabled
|
|
(returns `400`).
|
|
|
|
**Errors:**
|
|
- `400` — attempting to disable `chat` or `admin`.
|
|
- `404` — surface not found.
|
|
|
|
**Auth:** Platform admin.
|
|
|
|
### Delete Surface
|
|
|
|
```
|
|
DELETE /admin/surfaces/:id
|
|
```
|
|
|
|
Removes the surface, its DB row, and its extracted static assets.
|
|
Core surfaces cannot be deleted.
|
|
|
|
**Errors:**
|
|
- `400` — attempting to delete a core surface.
|
|
- `404` — surface not found.
|
|
|
|
**Auth:** Platform admin.
|
|
|
|
**Defense-in-depth:** The store layer also enforces
|
|
`WHERE source = 'extension'` on delete, so even if the handler check
|
|
were bypassed, core surfaces are protected.
|
|
|
|
## Surface Registry Object
|
|
|
|
```json
|
|
{
|
|
"id": "hello-dashboard",
|
|
"title": "Hello Dashboard",
|
|
"manifest": { "route": "/s/hello-dashboard", "scripts": [...], "css": [...] },
|
|
"enabled": true,
|
|
"source": "core|extension",
|
|
"installed_at": "...",
|
|
"updated_at": "..."
|
|
}
|
|
```
|
|
|
|
## Internal Store Methods
|
|
|
|
The `SurfaceRegistryStore` interface exposes methods beyond what the
|
|
HTTP API uses directly:
|
|
|
|
- `Seed(ctx, id, title, source, manifest)` — upserts a surface at
|
|
startup. Does **not** overwrite the `enabled` flag (admin toggle
|
|
survives restarts). Called by the page engine's `SeedSurfaces()`.
|
|
- `ListEnabled(ctx) → []string` — returns IDs of all enabled
|
|
surfaces. Used by the page engine for nav rendering
|
|
(`EnabledSurfaceIDs()`), not exposed via HTTP.
|
|
|
|
## Page Routes
|
|
|
|
Extension surfaces are served at `/s/:slug` via `RenderExtensionSurface()`.
|
|
The page engine does a runtime DB lookup — no server restart needed after install.
|
|
|
|
Static assets are served from `/surfaces/:id/` (nginx location block in
|
|
both unified and split deployment). In unified mode, the Go server
|
|
handles this route with path-traversal protection. In split deployment,
|
|
nginx serves directly from `/data/surfaces/`.
|
|
|
|
## Surface Archive Format
|
|
|
|
A `.surface` file is a **zip** archive containing:
|
|
|
|
```
|
|
manifest.json — required (must have "id" and "title")
|
|
js/ — optional (extracted to /data/surfaces/{id}/js/)
|
|
css/ — optional (extracted to /data/surfaces/{id}/css/)
|
|
assets/ — optional (icons, images, etc.)
|
|
```
|
|
|
|
The archive may have a single top-level directory prefix (e.g.,
|
|
`my-surface/manifest.json`) — the installer strips it when locating
|
|
`manifest.json` and when extracting `js/`, `css/`, and `assets/`
|
|
directories. Files outside these directories (e.g., `script.js` at
|
|
root) are not extracted.
|
|
|
|
See [EXTENSION-SURFACES.md](../EXTENSION-SURFACES.md) for the full
|
|
authoring guide including manifest schema, platform API, and CSS
|
|
custom properties.
|