48 lines
4.1 KiB
Markdown
48 lines
4.1 KiB
Markdown
# Plugin Bridge Contract
|
|
|
|
Plugins use the platform bridge for every privileged action.
|
|
|
|
## Allowed Bridge Areas
|
|
|
|
- `server.instances`: read current server instance context.
|
|
- `jobs.dispatch`: request platform-authorized run jobs.
|
|
- `logs.query`: query historical logs by server, stream, time range, cursor, or analysis window.
|
|
- `artifacts.open`: request platform-mediated artifact download references.
|
|
- `files.request`: request scoped file list/read/patch/replace operations through platform jobs.
|
|
- `remote.access.request`: request plugin-declared FTP, rsync, or run-mediated remote operations through platform jobs.
|
|
- `run.distribution.request`: request platform-mediated run package generation, download, key reset, or self-update orchestration.
|
|
- `dependencies.request`: request typed dependency checks or approved install plans declared by the plugin runtime profile.
|
|
- `logs.backfill.request`: request historical log backfill for a declared log source.
|
|
- `client-manager.request`: request generation/download/key reset or a typed status, deploy, start, stop, restart, update, rollback, session-revoke, retry, or uninstall operation for a plugin-declared companion client manager.
|
|
- `ai.invoke`: request platform-mediated AI assistance.
|
|
- `theme.tokens`: read safe platform theme tokens.
|
|
|
|
## Execution Envelopes
|
|
|
|
Plugin pages build execution requests with `createBridgeExecutionRequest` and hand them to the host-provided bridge transport. The SDK never owns `fetch`, platform authorization headers, run sockets, or provider credentials.
|
|
|
|
Execution responses use `requestId`, plugin/page/server scope, action, status, optional result refs, and optional safe errors. Use `parseBridgeExecutionResponse` before reading results so plugin code handles denied, deferred, and failed states uniformly.
|
|
|
|
AI requests use `createAIInvocationRequest` with an explicit purpose, prompt, scoped context refs, and optional current config. Use `parseAIInvocationResponse` to consume recommendations and safe errors. Plugin code must not include provider API keys, provider base URLs, bearer tokens, or direct transport details in AI request payloads.
|
|
|
|
Artifact open requests use `createArtifactOpenRequest` with an artifact ID that belongs to the current server/job scope. Use `parseArtifactReference` to consume the bridge result. Parsed references contain platform-owned download URLs, filename, content type, size, checksum, expiry, range support, and chunk size; they do not contain bytes or raw storage adapter locations.
|
|
|
|
Remote access requests use `createRemoteAccessRequest` with a plugin-declared `remote.*` capability, logical target key, optional scoped `input://` or `artifact://` ref, and idempotency key. The SDK never accepts FTP passwords, rsync endpoints, database DSNs, RCON passwords, run sockets, or raw host paths in these envelopes.
|
|
|
|
Run distribution, dependency, log backfill, and client-manager requests use `createRunDistributionRequest`, `createDependencyActionRequest`, `createLogBackfillRequest`, and `createClientManagerRequest`. Client-manager lifecycle envelopes carry only operation names, logical profile/installation IDs, target OS/architecture, artifact IDs, expected deployment generations, and idempotency keys. `parseClientManagerLifecycleStatus` whitelists safe state, version, health, job, artifact, and action fields. Raw run/client-manager keys, component sessions, secret refs, host paths, PIDs, sockets, credentials, and direct Run endpoint details are never plugin bridge fields.
|
|
|
|
Client-manager lifecycle requests remain Platform-mediated. A plugin declaration does not grant access by itself: Platform rechecks the installed plugin, server owner/administrator scope, runtime binding, assigned Run endpoint capabilities, current distribution target/revision/key generation, and durable installation state before dispatching a typed job.
|
|
|
|
## Forbidden Data
|
|
|
|
The bridge must not expose:
|
|
|
|
- raw run credentials.
|
|
- raw host paths.
|
|
- AI provider API keys.
|
|
- platform auth storage.
|
|
- storage backend endpoints.
|
|
- unrestricted artifact storage credentials.
|
|
- direct storage URLs or presigned backend URLs.
|
|
- FTP, rsync, database, or RCON credentials.
|