Golaxy Framework

English | 简体中文

Golaxy Framework is a Go service framework for real-time, distributed backends. It uses the EC (Entity-Component) system and Actor-style serialized execution model from Golaxy Core as its kernel, then adds application bootstrap, service and runtime assembly, distributed infrastructure, RPC, gateways, and a network protocol stack.

The project is designed for game servers, long-lived connection gateways, stateful business services, remote-control platforms, and other real-time systems that need entity-oriented state management and cross-node communication.

• Positioning
• Key capabilities
• Requirements
• Quick start
• Architecture
• Actor + EC framework in depth
• Configuration
• Programming model
• Add-in system
• Distributed communication and protocols
• Project layout
• Observability and operational guidance
• Development and verification
• Ecosystem and license

Golaxy Framework is the server-side extension layer of the Golaxy ecosystem. It focuses on the following concerns:

• Assemble, start, and stop multiple logical services and replicas in one process.
• Isolate stateful workloads in runtimes, each of which serializes tasks and entity state on its owning goroutine.
• Model business objects with stable identities, composable behavior, and global addressability through entities, components, and prototypes.
• Integrate logging, configuration, messaging, discovery, distributed locks, distributed entities, and RPC behind consistent APIs.
• Provide GAP and GTP protocols plus gateway features for service messaging and long-lived client connections.

This repository is a framework library; it does not bundle application services or infrastructure processes. The default assembly connects to NATS and ETCD. Golaxy Scaffold is the companion game-project scaffold and build-time toolset. Its primary capabilities are Protobuf code generation for Go/Godot and Excel-table schema, code, and data processing; it does not implement friend, mail, or other product services. See Golaxy Examples for end-to-end usage.

• Application and service orchestration: Cobra/Viper-based commands and configuration, multiple services and replicas, signal-driven graceful shutdown, and optional pprof.
• Actor + EC execution model: serialized runtime state, composable entities and components, optional real-time frame loops, and automatic dependency injection.
• Asynchronous coordination: runtime scheduling, lifecycle scopes, background goroutines, timers, distinct Future/Signal/Stream semantics, Future combinators, and Runtime continuations.
• Distributed infrastructure: a NATS broker, ETCD service discovery, ETCD/Redis distributed mutexes, service-node registration, and distributed-entity lookup.
• RPC: Service, Runtime, Entity, and Client targets with unicast, load balancing, broadcast, one-way calls, and future-based results.
• Gateway and routing: TCP/WebSocket sessions, authentication, reconnection, clock synchronization, entity-to-session mappings, logical groups, and multicast.
• Database integrations: GORM for MySQL, PostgreSQL, SQL Server, and SQLite, plus Redis and MongoDB add-ins and tag-based client injection.
• Protocol stack: GAP for application messages and dynamic arguments; GTP for connection handshakes, ordering, heartbeats, compression, and optional encryption.

The default service assembly actively initializes the NATS and ETCD add-ins during startup, so these services must be reachable even for the minimal example. External dependencies may differ after replacing the defaults through installation hooks.

mkdir golaxy-demo
cd golaxy-demo
go mod init example.com/golaxy-demo
go get git.golaxy.org/framework@latest

Start reachable NATS and ETCD instances listening at:

• NATS: localhost:4222
• ETCD: localhost:2379

You can select different endpoints with startup flags or a configuration file.

package main

import "git.golaxy.org/framework"

type LobbyService struct {
	framework.ServiceBehavior
}

func (*LobbyService) OnStarted(svc framework.IService) {
	rt, err := svc.BuildRuntime().
		SetName("main").
		SetEnableFrame(true).
		SetFPS(20).
		New()
	if err != nil {
		svc.S().Panicw("create runtime failed", "error", err)
	}

	svc.S().Infow("lobby service started", "runtime_id", rt.ID())
}

func main() {
	framework.NewApp().
		SetAssembler("lobby", &LobbyService{}).
		Run()
}

go run .

Press Ctrl+C for graceful shutdown. The lobby name passed to SetAssembler is also:

• the service key in startup.services;
• the logical service name returned by IService.Name();
• the configuration subtree returned by IService.ServiceConf();
• the service name advertised by the distributed-service add-in.

When SetAssembler receives an instance or reflection type implementing IService, it creates a fresh instance of that concrete type for every replica; it does not reuse the supplied pointer.

flowchart TB
    subgraph Execution[Execution model]
        App[App<br/>configuration, commands, replicas] --> Service[Service<br/>concurrent service context]
        Service --> Runtime[Runtime<br/>actor goroutine]
        Runtime --> Entity[Entity]
        Entity --> Component[Component]
        Service -.-> ServiceAddins[service add-ins]
        Runtime -.-> RuntimeAddins[runtime add-ins]
    end

    subgraph ClientPath[Client long-connection RPC path]
        direction LR
        ClientRPC[Client / RPCli] <-->|RPC / Oneway RPC| ClientGAP[GAP<br/>Forward wrapping RPC]
        ClientGAP <-->|as GTP Payload| GTPLink[GTP<br/>TCP / WebSocket]
        GTPLink <--> GateNode[Gate<br/>session, authentication, reconnect]
        GateNode <-->|Payload| GateProcessor[Gate RPC Processor<br/>GAP codec and routing]
    end

    subgraph InternalPath[Service-to-service RPC path]
        direction LR
        ServiceCaller[Service / Runtime / Entity] <--> ServiceProcessor[Service RPC Processor]
    end

    GateProcessor <-->|GAP Forward| NatsBus[NATS Broker<br/>GAP messages only]
    ServiceProcessor <-->|GAP RPC Request / Reply / Oneway| NatsBus
    NatsBus <-->|GAP| TargetProcessor[Service / Forward RPC Processor]
    TargetProcessor -.->|dispatch to Service / Runtime / Entity| Service
    ServiceAddins <-->|registration, lookup, leases, locks| ETCD[ETCD]

For a client call, RPCli serializes MsgRPCRequest, MsgOnewayRPC, or MsgRPCReply into MsgForward.TransData. The outer MsgForward is GAP-encoded and sent as a GTP Payload. The Gate RPC Processor receives that Payload from the GTP session, decodes GAP, rebuilds the forwarding origin and destination, and passes it to dsvc for publication through NATS. Consequently, GTP ends at the client connection boundary; the service message bus uniformly carries GAP.

• Every service registered with SetAssembler starts with one replica by default. Override this with startup.services; IService.ReplicaNo() returns a zero-based replica number.
• Each service replica runs in its own goroutine, and one service may own multiple runtimes.
• Ordinary runtime tasks and entity state are serialized on the owning Runtime goroutine. Do not access runtime state from other goroutines unless an API explicitly documents concurrent safety.
• App listens for SIGHUP, SIGINT, SIGTERM, and SIGQUIT. The first signal cancels the shared context, after which the application waits for all service replicas to terminate.

Golaxy combines two orthogonal models: Actor defines who owns mutable state and where code executes, while EC defines how business objects are decomposed, composed, and evolved.

The Actor boundary is the Runtime, not an individual Entity. A Runtime may manage one Entity or a group of entities that require strict execution ordering. EC here means Entity-Component; unlike a conventional data-oriented ECS, its primary programming model is not global System queries and batch processing. Behavior normally lives directly in Entity or Component lifecycle methods.

Every Runtime owns a task queue, entity manager, entity tree, and optional frame loop. Application code should treat the owning Runtime goroutine as the sole ordinary writer of its Entity and Component state:

sequenceDiagram
    participant Source as External goroutine / RPC / timer
    participant Queue as Runtime task queue
    participant RuntimeLoop as Runtime goroutine
    participant EC as Entity / Components
    Source->>Queue: Submit / Post / RPC dispatch
    Queue->>RuntimeLoop: Dequeue in order
    RuntimeLoop->>EC: Execute logic and mutate state
    EC-->>RuntimeLoop: async.Result
    RuntimeLoop-->>Source: Complete Future
    Source->>Queue: Re-enqueue ContinueOn continuation
    Note over Queue,RuntimeLoop: Update and LateUpdate are serialized in the same boundary

• Ordinary tasks, entity lifecycle transitions, and frame callbacks never run concurrently inside one Runtime, so business state within that Runtime normally needs no locks.
• An Entity does not automatically receive its own goroutine. Putting several entities in one Runtime makes them share one serialized execution domain.
• Code outside the Runtime may directly use only explicitly concurrent-safe contexts or read-only surfaces. Schedule state reads and writes through Submit, Post, RPC, or another dispatch entry point.
• Spawn is intended for blocking I/O and independent computation, but its function runs in a new goroutine and must not touch Runtime state directly. Use ContinueOn to schedule subsequent Future handling back onto the Runtime.
• With the frame loop enabled, Update() and LateUpdate() share the execution boundary with ordinary tasks. A slow or blocking callback therefore delays both message handling and frame progress and should be moved off the Actor goroutine.
• Framework-created runtimes use an unbounded task queue by default. This avoids immediate capacity failures for producers, but the application must control backlog through rate limits, timeouts, and metrics.

Service is the concurrent outer scope around runtimes. It holds service add-ins, entity/component prototype libraries, and the global entity index. Even after a cross-runtime or cross-node lookup resolves an entity, the call must still be dispatched to its owning Runtime instead of mutating it concurrently through a side channel.

An Entity may contain several Components with the same name. GetComponent returns the first match, while GetComponents returns all matches. Components reuse the Entity ID by default; enable SetComponentUniqueID(true) to assign independent IDs and make GetComponentByID available.

Entity, Component, and Runtime also expose in-process signal/slot-style events. An event is emitted synchronously on the sender's current goroutine; it neither enters the Runtime task queue nor provides cross-process delivery. Code on an external goroutine must therefore enter the Runtime before emitting a business event. Subscription handles stored in the object's Managed() collection are unbound automatically when their owner is destroyed or terminated.

Scope determines where an Entity can be found, not where it executes:

Scope_Global provides addressability; it does not make an Entity concurrency-safe. Remote calls and service-level lookups must ultimately re-enter the owning Runtime for execution.

The Runtime owns Entity and Component state transitions. Except for the Component enable/disable branch, lifecycles progress from construction toward destruction. Application code should never force a state transition itself:

Entity activation:    Born -> Entered -> Awaking -> Starting -> Alive
Entity deactivation:  Leaving -> Shutting -> Dead -> Destroyed

Component activation: Born -> Attached -> Awaking -> Enabling -> Starting -> Alive
Disable and re-enable: Enabling / Starting / Alive -> Idle; Idle -> Starting -> Alive
Component removal:    Detaching -> Shutting -> Disabling -> Dead -> Destroyed

Initial activation follows this concrete order:

1. Framework resolves component dependencies when automatic injection is enabled;
2. Entity Awake();
3. each Component Awake();
4. enabled Components OnEnable();
5. enabled Components Start();
6. Entity Start(), after which the Entity becomes Alive.

During Entity deactivation, Entity Shut() runs first, followed by Component Shut() in reverse order. Components then receive OnDisable() and Dispose() in reverse order, and Entity Dispose() runs last. Lifecycle interfaces are optional; objects without a particular callback still progress normally through their states.

When AddComponent is called on an active Entity, the Runtime advances the new component through Awake, OnEnable, and Start. Removal invokes the paired shutdown path. Components added directly at runtime are removable by default, while built-in components declared by an Entity Prototype are not; opt in with ComponentDescriptor.SetRemovable(true) when a built-in component must be detachable. Dynamic component changes, SetEnabled, Entity Destroy, and EntityTree mutations must all run inside the owning Runtime.

Prototypes separate “what a business object contains” from instance creation. BuildEntityPT(name) declares a template in the Service EntityLib, and BuildEntity(name) constructs an instance from the current template. Redeclaring the same prototype name replaces the previous definition; it does not retroactively alter entities that already exist.

Automatic injection is enabled on runtimes by default. Before an Entity or a newly added component activates, Framework scans every Component on that Entity and injects matching sibling components into pointer or interface fields. Dependencies are therefore available from Component Awake() onward:

type Movement struct {
	framework.ComponentBehavior
	Position *Position `ec:"position"`
}

func (m *Movement) Awake() {
	if m.Position == nil {
		panic("movement requires position")
	}
}

• The tag format is ec:"component name,full component prototype"; either part can be selected as needed. ec:"position" injects by component name.
• An untagged pointer-to-struct field attempts to infer the component name and full prototype name from its type.
• If the tag names a registered component prototype but no matching component is attached, injection may construct and add that component dynamically.
• A missing match leaves the field unchanged, normally nil; validate required dependencies explicitly in Awake().
• Adding a component to an active Entity rescans every Component, allowing existing components to receive the newly available dependency.

Automatic injection targets Component fields. An Entity should obtain its components through the component-manager API while inside the Runtime. Disable reflection-based injection with SetAutoInjection(false) when explicit wiring is preferred or the activation path is especially performance-sensitive.

As a rule, place state that must change in one serialized transaction in the same Runtime, and split state that needs true parallelism across runtimes. Treat cross-Runtime coordination as asynchronous message exchange; do not rely on shared mutable objects or implicit transactions spanning runtimes.

App binds Cobra flags to Viper. For the same key, values are resolved in this order:

1. A value set through app.Conf().Set(...);
2. An explicitly supplied command-line flag;
3. An environment variable;
4. A local configuration file;
5. A remote configuration provider;
6. The built-in flag default.

Set conf.local_path to load a local file; its format is inferred from the extension. Remote configuration is read once at startup through a Viper remote provider. The current dependency supports etcd, etcd3, consul, firestore, and nats; the framework does not automatically watch for subsequent changes.

Environment variables follow Viper's default mapping: keys are uppercased, but dots are retained. With the prefix GAME, for example, log.level maps to GAME_LOG.LEVEL. To use the more conventional GAME_LOG_LEVEL, configure an EnvKeyReplacer on app.Conf() before Run. Because conf.env_prefix is resolved before local and remote configuration are loaded, set it through a command-line flag or app.Conf().Set.

The application-level nats.address and etcd.address settings are single-endpoint shortcuts. Use the corresponding add-in installation hook when you need multiple endpoints, TLS, or an existing client.

log:
  level: info
  encoder: production
  format: json
  async: true

nats:
  address: localhost:4222

etcd:
  address: localhost:2379

service:
  version: v1.0.0
  meta:
    region: cn-east-1
    environment: production
  ttl: 10s
  future_timeout: 3s
  dent_ttl: 10s
  auto_recover: true

startup:
  services:
    lobby: "2"
    gate: "1"

pprof:
  enable: false
  address: 127.0.0.1:6060

lobby:
  tick_interval: 50ms
  matchmaking_region: cn-east-1

Inside the lobby service:

appConf := svc.AppConf()         // the full merged configuration
serviceConf := svc.ServiceConf() // the lobby subtree; it may be nil when absent

Command-line override example:

./your-app \
  --startup.services lobby=2,gate=1 \
  --nats.address localhost:4222 \
  --etcd.address localhost:2379 \
  --conf.local_path ./config.yaml

If a configuration file explicitly defines startup.services, include every service that should run. Registered services omitted from that map are treated as having zero replicas.

• NewApp() creates an independent Cobra root command and Viper instance.
• SetAssembler(name, assembler) can register multiple logical services; registering the same name replaces the previous assembler.
• InitCB adds flags or Cobra subcommands; StartingCB runs after configuration and pprof initialization; TerminateCB runs after every service has stopped.
• App.Cmd() and App.Conf() expose extension points before Run(). Configuration and assembly methods should be called from the same goroutine.
• IService.Memory() is a replica-private concurrent key/value store, while ReplicaNo() returns the current replica number.

Additional Service lifecycle interfaces cover entity prototypes, component prototypes, and global-entity registration and deregistration. See service_lifecycle.go for the complete contracts.

This section covers the builder APIs; see Actor + EC framework in depth for execution boundaries, state machines, and composition rules.

BuildRuntime() starts from these defaults:

Customize these values with SetName, SetPersistID, SetMainEntity, SetEnableFrame, SetFPS, SetAutoInjection, and SetPanicHandling. A runtime terminates automatically after its main entity is deactivated.

The following example declares a global player prototype and creates an entity:

package main

import (
	"git.golaxy.org/core/ec"
	"git.golaxy.org/framework"
)

const playerPrototype = "player"

type GameService struct {
	framework.ServiceBehavior
}

type Player struct {
	framework.EntityBehavior
}

type Position struct {
	framework.ComponentBehavior
	X float64
	Y float64
}

type Movement struct {
	framework.ComponentBehavior
	Position  *Position `ec:"position"`
	VelocityX float64
	VelocityY float64
}

func (m *Movement) Awake() {
	if m.Position == nil {
		panic("movement requires position")
	}
	m.VelocityX = 0.25
}

func (m *Movement) Update() {
	m.Position.X += m.VelocityX
	m.Position.Y += m.VelocityY
}

func (*GameService) OnBuilt(svc framework.IService) {
	svc.BuildEntityPT(playerPrototype).
		SetInstance(&Player{}).
		SetScope(ec.Scope_Global).
		AddComponent(&Position{}, "position").
		AddComponent(&Movement{}, "movement").
		Declare()
}

func (*GameService) OnStarted(svc framework.IService) {
	_, err := svc.BuildEntity(playerPrototype).
		SetRuntimeCreator(
			svc.BuildRuntime().
				SetEnableFrame(true).
				SetFPS(20),
		).
		SetMeta(map[string]any{"region": "cn-east-1"}).
		New()
	if err != nil {
		svc.S().Panicw("create player failed", "error", err)
	}
}

• BuildEntityPT(...).Declare() registers the prototype in the current Service's entity library.
• IService.BuildEntity() creates a new Runtime and makes the new Entity its main entity.
• Movement.Position is injected before Component Awake(). The frame loop targets 20 FPS and calls Update() serially with the Runtime's other tasks.
• IService.BuildEntity() is dedicated to creating the main Entity of a new Runtime. To add an Entity to an existing Runtime, call IRuntime.BuildEntity() on that Runtime's goroutine.
• Only ec.Scope_Global entities are advertised to ETCD by the default distributed-entity registry.
• Custom entities and components embed EntityBehavior and ComponentBehavior respectively to gain direct access to the owning Runtime, Service, logger, async helpers, and RPC helpers.

A Future retains one replayable result, a Signal reports result-free lifecycle completion, and a Stream carries continuous results to one consumer. Service and Runtime contexts, Entities, Components, Gate Sessions, and Clients expose an AsyncScope() bound to their lifetime; use Spawn or SpawnVoid to start managed background work. Once an owner starts closing, its Scope cancels existing tasks and rejects new ones.

There are two ways to replace a default:

1. Install an add-in with the same name during OnBirth;
2. Implement the corresponding InstallService... or InstallRuntime... interface.

For every capability, the framework checks “already installed → instance installation hook → assembler installation hook → default implementation” and requires the capability to exist afterward. This example replaces the default ETCD-backed distributed mutex with Redis:

import (
	"git.golaxy.org/framework"
	"git.golaxy.org/framework/addins"
)

func (*LobbyService) InstallDistSync(svc framework.IService) {
	addins.DsyncRedis.Install(svc,
		addins.DsyncRedisWith.RedisURL(
			svc.AppConf().GetString("redis.url"),
		),
	)
}

Service add-ins may be installed in OnBirth, an installation hook, or OnBuilt, and are frozen before the Starting callback. Because OnBuilt runs after default assembly, use it to append custom add-ins; replace a default in OnBirth or the corresponding installation hook. During shutdown, regular Service add-ins are stopped in reverse installation order and removed before OnTerminated. The default logging and configuration add-ins implement service.RetainedAddIn, remain available in that callback, and do not receive Shut. Custom replacements that need the same lifetime must implement that marker and must not own tasks or external resources requiring explicit shutdown. Runtime add-ins may be installed or removed while running, but those operations should execute on the owning Runtime goroutine; Runtime does not apply Service add-in retention.

The root addins package re-exports built-in add-in descriptors and their With option entry points for convenient use in assembly code.

dsvc creates five broker address classes for every service node:

• global broadcast;
• global load balancing;
• same-service broadcast;
• same-service load balancing;
• node unicast.

During bring-up, a node subscribes to its addresses before acquiring a distributed lock, checking for duplicates, and registering with discovery. This prevents an advertised node from losing messages before its subscriptions are ready. The current dsvc processing chain requires the broker to report AtMostOnce delivery semantics; a replacement broker must satisfy that constraint.

RPC builds on this addressing model and provides:

• Service, Runtime, Entity, and Client targets;
• named-service calls, random load balancing, and global load balancing;
• same-service and global one-way broadcasts;
• call-chain propagation and typed parse/assert helpers for up to 16 return values.

Protocol boundary: GTP is used only for the TCP/WebSocket connection between Client and Gate. Client RPC is a GAP message carried in a GTP Payload. After Gate enters the service domain, and for every service-to-service RPC, NATS transports GAP only; GTP is never nested into the NATS path.

Wire compatibility: Correlation IDs are unsigned 64-bit values. GAP encodes them as unsigned varints, while GTP time-sync messages use fixed-width uint64 fields. GAP peers using the former signed-varint encoding are not wire-compatible and must be upgraded together; the GTP field retains the same eight-byte layout for nonnegative IDs.

Security note: GTP supports ECDHE, signing, and verification, but does not provide certificate validation itself. For high-security deployments, enable TLS below GTP on TCP/WebSocket and consider disabling GTP's built-in payload encryption; protocol signatures are not a replacement for a complete PKI trust chain. Do not expose pprof directly to untrusted networks either.

• Logging uses Zap. Production deployments will typically choose log.encoder=production and log.format=json; the framework flushes buffered logging during shutdown.
• service.auto_recover=false is the default. When enabled, the Service and default Runtimes recover execution panics and report them through an error channel; the application must still decide whether continuing is safe for its consistency model.
• pprof is disabled by default. When enabled, bind pprof.address to loopback or a management network and add access control at the network boundary.
• Service and entity TTLs must be at least 3 seconds. Set production values according to ETCD latency, network jitter, and failure-detection goals rather than minimizing them blindly.
• Gate listen addresses, TLS, maximum packet size, compression threshold, authenticator, I/O timeouts, and session inbox capacities are independently configurable through gate.With.
• Replace the relevant default add-in when you need multiple NATS/ETCD endpoints, TLS, or custom client ownership. Clients supplied by the caller are not closed when an add-in shuts down.

# Format
go fmt ./...

# Run all tests
go test ./...

# Check for data races on supported platforms
go test -race ./...

# Static analysis
go vet ./...

Protocol and low-level utility tests are concentrated in net/gap/variant, net/gtp, net/gtp/codec, net/gtp/method, net/gtp/transport, utils/binaryutil, utils/correlation, and utils/fanout.

• Golaxy Core: EC system and Runtime/Service execution kernel.
• Golaxy Scaffold: game-project scaffold centered on Protobuf generation and Excel-table processing.
• Golaxy Examples: end-to-end service, gateway, and RPC examples.

This project is licensed under the GNU Lesser General Public License v2.1.