Documentation
¶
Index ¶
- Constants
- func CardinalShardContainerName(namespace, instanceID string) string
- func CardinalShardImageName(namespace, shardID string) string
- func GameServiceContainerName(project, id string) string
- func NeedsAutoProjectDB(worldToml worldtoml.Config) bool
- func ProjectDBContainerName(project string) string
- type Builder
- type Config
- type Service
- type ServiceOrder
Constants ¶
const ( // DefaultCardinalDebugPort is the Cardinal debug server port. DefaultCardinalDebugPort = 8080 // DefaultCardinalDebugHostPort is the host port for Cardinal debug. DefaultCardinalDebugHostPort = 8081 // DBDSNEnvVar is the uniform env var carrying the shared project database DSN // to every shard and every db = true service. DBDSNEnvVar = "DB_DSN" )
const ( // DefaultNetworkMode is the docker network shared by all services. DefaultNetworkMode = "world-engine-network" // CardinalNamespaceLabel labels Cardinal shard containers/images by namespace. CardinalNamespaceLabel = "com.world.cardinal.namespace" // GameServiceLabel labels [[services]] containers by project. GameServiceLabel = "com.world.service.project" // BaseImage is the distroless runtime base for built-from-source images. BaseImage = "gcr.io/distroless/base-debian12" // GoBuilderImage is the Go toolchain build stage shared by Cardinal shards and // built-from-source game services. Keep the Go version in sync with .prototools // (go = "..."). GoBuilderImage = "golang:1.27.1-bookworm" )
Common string values used across service configurations.
const ( // DefaultNatsClientPort is the default NATS client port. DefaultNatsClientPort = 4222 // DefaultNatsMonitorPort is the default NATS monitoring port. DefaultNatsMonitorPort = 8222 // DefaultNatsClusterPort is the default NATS cluster port. DefaultNatsClusterPort = 6222 // DefaultNatsWebsocketPort is the default NATS websocket port. DefaultNatsWebsocketPort = 4443 // DefaultNatsImage is the default Docker image for the NATS service. DefaultNatsImage = "nats:" // DefaultNatsContainerName is the default container name for the NATS service. DefaultNatsContainerName = "world-engine-nats" )
Variables ¶
This section is empty.
Functions ¶
func CardinalShardContainerName ¶
CardinalShardContainerName returns the per-instance container name for a Cardinal shard (e.g. "game-2").
func CardinalShardImageName ¶
CardinalShardImageName returns the image tag shared by a Cardinal shard pool, keyed by the world.toml shard ID.
func GameServiceContainerName ¶
GameServiceContainerName returns the container name for a [[services]] entry. Keyed off the world.toml project (not the directory-derived namespace) so hostname-referencing env values (e.g. a postgres DSN) stay deterministic across checkout directories.
func NeedsAutoProjectDB ¶
NeedsAutoProjectDB reports whether the docker backend must auto-provision the shared "{project}-db" Postgres: some service set db = true and no config_db service was declared to satisfy it.
func ProjectDBContainerName ¶
ProjectDBContainerName returns a project's shared database container/host name ("{project}-db"). One database per project, reached via DB_DSN.
Types ¶
type Builder ¶
func BuildCardinalShards ¶
func BuildGameServices ¶
BuildGameServices returns one builder per [[services]] entry in declaration order (which drives start order). When a service sets db = true and no config_db service satisfies it, the auto-provisioned "{project}-db" Postgres is prepended so it goes healthy first; it rides here (not just the start path) so stop/purge tear it down with the project.
func GetServices ¶
func GetServices(cfg *Config, order ServiceOrder) []Builder
GetServices returns Cardinal shard builders plus game services and NATS. Game services keep their world.toml declaration order (it drives start order); the auto-provisioned project database (when db = true is used) rides in from BuildGameServices, prepended so it comes up first.
type Service ¶
type Service struct {
container.Config
container.HostConfig
network.NetworkingConfig
ocispec.Platform
Name string
// Dependencies are other services that need to be pull before this service
Dependencies []Service
// Dockerfile is the content of the Dockerfile
Dockerfile string
// BuildTarget is the target build of the Dockerfile e.g. builder or runtime
BuildTarget string
// BuildArgs are ARGs passed to the Docker build (e.g., SOURCE_PATH)
BuildArgs map[string]string
}
Service represents a Docker service configuration. It contains the name of the container and a function to get the container and host config.
func CardinalFromShard ¶
func GameServiceFromConfig ¶
func GameServiceFromConfig(cfg *Config, svc worldtoml.GameService) Service
GameServiceFromConfig builds the docker service for one [[services]] entry. Image-kind entries run a pulled image; path-kind entries ride the Cardinal shard build pipeline and carry the namespace label so they build/prune like shard images.
func ProjectDBService ¶
ProjectDBService builds the auto-provisioned shared project database: a single "{project}-db" Postgres reached via DB_DSN, initialized with world-cli's default credentials and a project-named database (matching projectDBDSN). It carries the game-service label (so start/stop/purge bucket it like any service), a healthcheck (so dependents wait), and a volume name == container name (so purge cleans it up). Only added when NeedsAutoProjectDB(worldToml) is true.
Known limitation: it binds host port 5432, so only one db = true project can run on a host at a time, and it clashes with a local Postgres already on 5432.
type ServiceOrder ¶
type ServiceOrder int
ServiceOrder controls how shared service builders are ordered for consumers.
const ( // CardinalShardsFirst lists shard services first, then game services and NATS. CardinalShardsFirst ServiceOrder = iota // InfrastructureFirst lists NATS first, then game services and shard services. InfrastructureFirst )
Source Files