78 lines
3.7 KiB
Markdown
78 lines
3.7 KiB
Markdown
# WebAssembly integration modules
|
|
|
|
## Purpose
|
|
|
|
A module is a small translator between a game server API and DoGaMa's normalized game API.
|
|
|
|
```text
|
|
Game-specific API <-> WebAssembly adapter <-> normalized DoGaMa API
|
|
```
|
|
|
|
It may query status, list players, request an in-game save, announce, shut down gracefully, kick, ban or unban when the game supports those operations. It does not own container lifecycle, files, users, backups, scheduling or UI.
|
|
|
|
## Package
|
|
|
|
```text
|
|
palworld-rest-1.0.0.dogama-module/
|
|
module.wasm
|
|
manifest.yaml
|
|
README.md
|
|
LICENSE
|
|
```
|
|
|
|
The installed artifact is content-addressed. Manifest, binary checksum, source/trust status and installation time are recorded. A package cannot contain executable helpers or dynamic libraries.
|
|
|
|
## Runtime contract
|
|
|
|
The V1 ABI uses a versioned WebAssembly component/WIT contract or an equivalently typed ABI. JSON may be used at a debugging boundary but is not the authority for function signatures. `specs/normalized-module-api.md` defines semantics.
|
|
|
|
The runtime grants no ambient WASI filesystem, process, environment, raw sockets or arbitrary DNS. Time and randomness are provided only if a documented operation requires them. Host functions include:
|
|
|
|
- bounded HTTP request to logical handle `instance_api`;
|
|
- bounded TCP request only if declared by both template and manifest;
|
|
- secret lookup by declared configuration key without exposing unrelated secrets;
|
|
- structured diagnostic emission with runtime redaction;
|
|
- cancellation/deadline checks.
|
|
|
|
## Instance-scoped networking
|
|
|
|
Modules never receive an arbitrary destination URL. At activation, DoGaMa binds `instance_api` to a specific instance network identity and declared integration port. Every request is checked for protocol, port, method, timeout, redirect, request/response size and concurrency.
|
|
|
|
- No Internet or LAN destinations.
|
|
- No loopback, link-local, metadata or Unix-socket destinations.
|
|
- No redirects outside the bound origin.
|
|
- DNS rebinding cannot change the authorized resolved destination.
|
|
- The management port is preferably unexposed on the host.
|
|
|
|
## Capabilities
|
|
|
|
Capabilities are explicit strings defined by the normalized API. A module may implement a subset. DoGaMa shows actions only when all of these agree:
|
|
|
|
1. template enables the integration and feature;
|
|
2. manifest declares the capability;
|
|
3. module runtime reports the same capability;
|
|
4. current user has permission;
|
|
5. instance state permits the operation.
|
|
|
|
Unknown capabilities are rejected for the current schema version. A claimed capability without its required export blocks activation.
|
|
|
|
## Resource limits
|
|
|
|
Per call, enforce a deadline, instruction/fuel budget, memory ceiling, maximum host calls, maximum payload/response size and cancellation. Limit concurrent calls per module and instance. Repeated traps open a circuit breaker and degrade only the integration; generic container management remains available.
|
|
|
|
## Independent versioning
|
|
|
|
Templates and modules have independent semantic versions.
|
|
|
|
- A template pins an acceptable module ID and version range.
|
|
- A manifest states supported manager module-API versions and game IDs.
|
|
- Installation of a new module does not activate it automatically for existing instances.
|
|
- Activation runs schema, checksum, ABI, capability and connection tests.
|
|
- The previous version stays available for rollback until the new version is healthy.
|
|
- A module update never silently changes instance settings or template snapshots.
|
|
|
|
## Prohibited behavior
|
|
|
|
Modules cannot create/delete containers, read SQLite, access host/game files, create backups, execute commands, manage users, expose routes or UI, contact other instances, or make unrestricted network calls. If a proposed integration needs those powers, the generic DoGaMa contract must be extended safely instead of bypassed.
|
|
|