WebAssembly integration modules

Purpose

A module is a small translator between a game server API and DoGaMa's normalized game API.

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.

Template-local package

catalog/palworld/
  template.yaml
  assets/
  module/
    manifest.yaml
    module.wasm
    src/
    README.md
    LICENSE

template.yaml declares the optional manifest as module.path. The path must remain under the template root's module/ directory; absolute paths, traversal and local symbolic links are rejected. The validated module bundle contributes to the template snapshot digest and is retained with that snapshot, so a later local-template update cannot change a pinned instance's adapter. 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.

Go/WASI reactor modules

Go modules targeting wasip1 are built as reactors with -buildmode=c-shared. The resulting WASM must export _initialize and the module exports used by the manifest; the host calls _initialize before invoking an operation. A module must not rely on the WASI command _start entry point. A reproducible build uses CGO_ENABLED=0 GOOS=wasip1 GOARCH=wasm and records the resulting artifact digest in its template-local manifest.

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.

The application service is attached to the fixed DOGAMA_GAMES_NETWORK network so this instance-scoped binding can resolve the selected container. The module still supplies no destination and the host pins every connection to the resolved instance address and declared port.

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:

template enables the integration and feature;
manifest declares the capability;
module runtime reports the same capability;
current user has permission;
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

The manifest retains its module ID and API compatibility contract, but discovery is template-driven: there is no game-to-module registry in the application. An administrator can copy/import my-game/template.yaml, assets/ and module/ together. A module update is accepted on the next local scan and creates a distinct digest; selected snapshots retain their own bundle.

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.

4.6 KiB Raw Blame History