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.

Package

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:

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

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.

3.7 KiB Raw Blame History