mods

Documentation

Overview

Package servicemods holds the app.ModName constants for every service in this repository, and the small helpers their Mods share.

The names live in one table rather than one per package for the same reason roost-kit keeps its own: a capability name is a global key in the registry, so a collision is a runtime failure that two separately-correct packages can cause together. One table is where a collision is visible by reading.

The names are prefixed "service." so they cannot collide with roost-kit's infrastructure capabilities — a service named "chat" and a hypothetical kit transport named "chat" would otherwise be the same key.

Index

• Constants
• Variables
• func Duration(cfg *viper.Viper, key string, fallback time.Duration) (time.Duration, error)
• func KeyPrefix(cfg *viper.Viper, service string) (string, error)
• func Redis(r *app.Registry) (fredis.IRedis, error)
• func RegisterAll(registry *app.Registry, capabilities ...Capability) error
• func RequiredDuration(cfg *viper.Viper, key string) (time.Duration, error)
• func Secret(cfg *viper.Viper, key string) (string, error)
• type Capability
• type PersistenceSelection
  • func ResolvePersistenceEngine(cfg *viper.Viper) (PersistenceSelection, error)

Constants

const (
	ModMongo          app.ModName = "mongo"
	ModHealth         app.ModName = app.ModHealth
	ModMetrics        app.ModName = app.ModMetrics
	ModAdmin          app.ModName = app.ModAdmin
	ModAdminMetadata  app.ModName = app.ModAdminMetadata
	ModLifecycle      app.ModName = app.ModLifecycle
	ModRuntimeFailure app.ModName = app.ModRuntimeFailure

	ModRedis      app.ModName = "redis"
	ModRedisLock  app.ModName = "redis.lock"
	ModRedisVLock app.ModName = "redis.versioned_lock"

	ModNats          app.ModName = "nats"
	ModNatsRpc       app.ModName = "nats.rpc"
	ModNatsJetStream app.ModName = "nats.jetstream"
	ModBus           app.ModName = "bus"

	ModEtcd         app.ModName = "etcd"
	ModEtcdDiscov   app.ModName = "etcd.discovery"
	ModEtcdElection app.ModName = "etcd.election"

	ModRoom                    app.ModName = "room"
	ModDataEngine              app.ModName = "dataengine"
	ModRemoteEntity            app.ModName = "remote_entity"
	ModRemoteEntityAtomicStore app.ModName = "remote_entity.atomic_store"
	ModLock                    app.ModName = "lock"
	ModOps                     app.ModName = "ops"
	ModStatsLog                app.ModName = "stats_log"
	ModConfigData              app.ModName = "config_data"
	ModNest                    app.ModName = "nest"
	ModSaga                    app.ModName = "saga"
	ModEntityRuntime           app.ModName = "entity.runtime"
	ModManager                 app.ModName = "manager"
)

ModName constants for reusable service runtime mods.

const (
	ModAccount   app.ModName = "service.account"
	ModChat      app.ModName = "service.chat"
	ModDirectory app.ModName = "service.directory"
	ModGlobal    app.ModName = "service.global"
	// ModGlobalActivity is the cross-server activity coordination service. It
	// is a separate capability from ModGlobal because the two share no state
	// — routing and leases answer "where does this game belong and is it
	// alive", activity coordination answers "has every game reached the phase
	// yet" — and joining them would give the activity side a reason to reach
	// into the lease store.
	//
	// The name keeps "global" because that is what the service coordinates
	// across, and because it was published under this name. The CODE no
	// longer lives in package global: two capabilities in one package meant
	// two things that deploy separately sharing one Go package, since
	// app.Service is one per process. It is package global/activity, and
	// activity.CapabilityName is checked against this constant in the
	// integration tests.
	ModGlobalActivity app.ModName = "service.global.activity"
	ModMail           app.ModName = "service.mail"
	ModMatch          app.ModName = "service.match"
	ModPlatform       app.ModName = "service.platform"
	ModRank           app.ModName = "service.rank"
	ModSession        app.ModName = "service.session"
)

Capability names for the services in this repository.

const (
	PersistenceDataEngine = "dataengine"
)

Variables

var All = []app.ModName{
	ModAccount, ModChat, ModDirectory, ModGlobal, ModGlobalActivity,
	ModMail, ModMatch, ModPlatform, ModRank, ModSession,
}

All is every consumer-facing capability name this repository can register.

It exists so a test can assert that the table has no duplicates — the one failure a name table is supposed to prevent, and the one that a table nobody checks does not prevent at all.

It lists the CONSUMER-facing names only. A service whose transport is generated also publishes an owner-only name derived from this one (<name>.local), which is how a process knows it holds the implementation rather than a client to it; that name is not a lookup any consumer writes, so listing it here would invite one.

Each generated service also declares its own CapabilityName constant, so its transport does not depend on this file. That is two literals of the same name, so integration/ asserts they are equal rather than trusting it.

var ErrPersistenceEngineSelection = errors.New("persistence: dataengine is the only supported engine")

Functions

func Duration

func Duration(cfg *viper.Viper, key string, fallback time.Duration) (time.Duration, error)

Duration reads an optional duration, falling back to a default.

A negative value is refused rather than clamped: a caller that wrote -1 meant something, and silently reading it as the default hides the mistake.

func KeyPrefix

func KeyPrefix(cfg *viper.Viper, service string) (string, error)

KeyPrefix reads a service's Redis key prefix from configuration.

The prefix is REQUIRED to be non-empty and there is no default, which is a deliberate choice rather than an oversight. A default would be the same string in every deployment, so two services of the same kind sharing one Redis — a staging environment beside production, two shards, a replay harness — would silently share state. Refusing at startup makes that a configuration error instead of a data corruption.

func Redis

func Redis(r *app.Registry) (fredis.IRedis, error)

Redis returns the Redis capability, or an error naming what is missing.

Every service Mod in this repository needs it, and every one of them should fail the same way when it is absent: with the capability name, at Provide time, rather than with a nil dereference on the first request.

func RegisterAll

func RegisterAll(registry *app.Registry, capabilities ...Capability) error

RegisterAll preflights the complete capability set before publishing it. App performs Provide serially, so after this validation the individual registrations cannot conflict with another Mod midway through the batch.

func RequiredDuration

func RequiredDuration(cfg *viper.Viper, key string) (time.Duration, error)

RequiredDuration reads a duration that has no sensible default.

func Secret

func Secret(cfg *viper.Viper, key string) (string, error)

Secret reads a required secret from configuration.

Empty is refused at startup. The implementation this repository replaces checked its payment secret at call time, so an unset secret turned every provider callback into an invalid-signature refusal — a silent outage that looked like an attack.

Types

type Capability

type Capability struct {
	Name  app.ModName
	Value any
}

Capability describes one startup-time Registry publication.

type PersistenceSelection

type PersistenceSelection struct {
	Engine            string
	DataEngineEnabled bool
}

func ResolvePersistenceEngine

func ResolvePersistenceEngine(cfg *viper.Viper) (PersistenceSelection, error)