86 lines
8.4 KiB
Markdown
86 lines
8.4 KiB
Markdown
# plugins
|
|
|
|
Game management plugin workspace.
|
|
|
|
A game management plugin defines how the platform creates and manages one type of game server. One installed plugin can create many server instances.
|
|
|
|
## Plugin Responsibilities
|
|
|
|
- Manifest identity and server type declaration.
|
|
- Create-server form schema.
|
|
- Lifecycle action definitions.
|
|
- Required run capabilities.
|
|
- Optional remote access methods and remote run capabilities.
|
|
- Optional runtime profiles for discovery, lifecycle modes, dependency probes, install plans, log sources, transports, and client-manager builds.
|
|
- Optional plugin pages hosted by platform_web.
|
|
- AI/file/log permissions declared for platform authorization, including `ai.mediation=platform` and `ai.configWritePolicy=review-required`.
|
|
- Production lifecycle operations, dependency policy, and disruptive approval requirements.
|
|
|
|
## Required Directory Plan
|
|
|
|
Implementation should use dedicated directories for:
|
|
|
|
- `manifests/`: plugin manifest examples or shared manifest schemas.
|
|
- `schemas/`: action, config, and create-form schemas.
|
|
- `sdk/`: plugin bridge SDK and shared contracts.
|
|
- `examples/`: example game management plugins.
|
|
- `tests/`: plugin contract tests and fixtures.
|
|
|
|
Plugins must use the platform bridge and must not connect directly to run, log storage, artifact storage internals, or AI provider endpoints.
|
|
|
|
Manifest validation is the plugin-side installability gate. The shared manifest schema defines identity, version, server type/display metadata, create form schema reference, lifecycle action references, required run capabilities, scoped permissions, remote access declarations, runtime profiles, optional pages, tags, and AI purposes. `scripts/validate-manifest.ts` also scans manifest and create-form content for unsafe raw host path, raw credential, direct run, and raw AI/provider key requests.
|
|
|
|
Remote access declarations describe whether a plugin can use `ftp`, `rsync`, or `run`, and which `remote.*` run capabilities are enabled for that game. Runtime profiles describe how run discovers servers, checks dependencies, tails live logs, backfills historical logs, resolves transports, and builds optional client managers. Plugin pages use platform-mediated bridge actions; they never receive FTP passwords, rsync endpoints, database DSNs, RCON credentials, run/client keys, run sockets, or host paths.
|
|
|
|
Runtime profiles are declarative contracts, not executable scripts. A profile can declare:
|
|
|
|
- discovery probes for logical targets such as Java, Steam app, service, file, or toolchain checks.
|
|
- lifecycle modes such as `local-process`, `hosted-ftp-rcon`, `ftp-only`, or `custom-client`.
|
|
- dependency probes and typed install plans for supported OS targets.
|
|
- log sources for stdout/stderr, file tailing, FTP polling, SQL cursors, or plugin-specific client-manager logs.
|
|
- transport profiles for declared file, FTP/rsync, SQL, RCON, and run-mediated operations.
|
|
- client-manager build profiles for games such as SCUM that need a separate companion executable.
|
|
|
|
Client-manager profiles declare repository URL, revision policy, semantic version, supported target OS/architecture pairs, a fixed build adapter, config template keys, produced artifacts, and an optional complete lifecycle contract. The lifecycle contract names a safe relative executable, fixed arguments, required Run capabilities, bounded start/stop/restart/status/update/rollback/uninstall actions, heartbeat/process health thresholds, component capabilities, compatibility bounds, and a manual staged-update policy. It cannot contain arbitrary shell, absolute/traversing paths, direct sockets, endpoints, raw credentials, or secret/session values.
|
|
|
|
Platform performs target and lifecycle validation, creates a real build record, injects a distinct server/component key into the generated package config, redacts build logs, and publishes a downloadable artifact. For profiles with a complete lifecycle contract, the artifact can then be deployed by a typed Run job into a managed workspace, registered using a separate short-lived component session, health-checked, started/stopped, updated/rolled back, revoked, and safely uninstalled. The Run key and client-manager key/session remain separate; resetting the client-manager key revokes old packages and sessions and requires a current-generation rebuild and redeploy.
|
|
|
|
Plugin pages may request these operations only through bridge helpers:
|
|
|
|
- `createRunDistributionRequest`: generate/download/reset/update run packages.
|
|
- `createDependencyActionRequest`: check or install declared dependency probes/plans.
|
|
- `createLogBackfillRequest`: request historical log cursors for declared sources.
|
|
- `createClientManagerRequest`: generate/download/reset or request safe status/deploy/control/update/rollback/revoke/retry/uninstall operations for declared client-manager packages.
|
|
- `createProductionPluginLifecycleRequest`: request server-bound install/enable/disable/upgrade/rollback/retire/dependency-check through Platform operations.
|
|
- `parseClientManagerLifecycleStatus`: whitelist the plugin-visible status, version, health, artifact/job IDs, deployment generation, and allowed actions without component secrets or machine details.
|
|
|
|
Bridge envelopes carry operation names, profile keys, target platforms, artifact IDs, checkpoint refs, immutable reviewed dependency plan digests, and idempotency keys only. Dependency install bridge helpers require a `sha256:<64 hex>` reviewed plan digest; Platform re-resolves the declaration and rejects stale or missing approvals. The plugin SDK and manifest validation reject raw run keys, client-manager keys, FTP passwords, rsync endpoints, SQL DSNs, RCON passwords, direct run sockets, host paths, and arbitrary shell snippets.
|
|
|
|
Validated manifests are registered through the platform registry API rather than by plugin code importing platform internals. Platform persists the validated runtime-profile declaration with the installed plugin contract and repeats safety validation before a plugin becomes installable. Per-server values are stored separately as platform-owned runtime bindings; plugin pages receive only logical readiness and never the stored values.
|
|
|
|
## Development Baseline
|
|
|
|
Tooling:
|
|
|
|
- Node 22.17.0.
|
|
- npm 11.6.1.
|
|
- TypeScript 5.
|
|
|
|
Commands:
|
|
|
|
```bash
|
|
npm install
|
|
npm run typecheck
|
|
npm run test
|
|
npm run validate:manifest
|
|
```
|
|
|
|
Current plugin behavior includes SDK bridge contracts, manifest schema validation, the `examples/dev-game-plugin`, `examples/scum-server-plugin`, and `examples/minecraft-server-plugin` fixtures, platform registry metadata registration, marketplace projections, hosted plugin-page bridge execution, platform-mediated lifecycle job dispatch, declared remote access envelopes, runtime profile declarations, target-matched typed dependency plan requests, run distribution envelopes, typed dependency/log backfill requests, and a SCUM-style client-manager declaration with a complete bounded lifecycle contract. Minecraft deliberately remains a no-client-manager example so action gating proves the feature is optional. Marketplace package acquisition, private source credentials, public build-worker sandboxing, remote plugin hosting policies, production KMS/code signing/fleet rollout, and external package distribution remain future work.
|
|
|
|
Runtime-profile declarations do not provide a general secret vault, arbitrary machine execution, production code signing/KMS, or fleet orchestration. The durable Client Manager installation/session state, bounded scheduler, process supervisor, and isolated log/artifact/control channels are Platform/Run capabilities; plugins receive only declarations and safe status projections.
|
|
# Client Manager profile contract
|
|
|
|
Plugins may declare a Client Manager profile with version/revision, supported targets, fixed relative executable, deployment mode, lifecycle capabilities, bounded startup/stop/health settings, compatibility constraints, and update policy. Platform enables lifecycle actions only after a real available distribution, complete server binding, an owned online Run endpoint, matching target/revision, and the current component-key generation.
|
|
|
|
Plugin pages and SDK bridge responses expose profile declarations, action availability, logical status/health, version/revision, job progress, and safe failure reasons only. They never receive component keys, sessions, secret refs/values, host paths, PIDs, sockets, credentials, DSNs, or direct Run endpoints. Arbitrary shell, raw credentials, and endpoint-bearing declarations are rejected during manifest validation.
|