Lakona.Game.Cluster 0.5.6

Lakona.Game.Cluster

Lakona.Game.Cluster contains optional explicit cluster routing contracts for Lakona.Game.

This package is intentionally small. It defines node identity, node-directory abstractions, route identity, generation-aware route locations, message envelopes, route directory abstractions, router abstractions, a loopback messenger, and in-memory implementations for tests or local single-process validation.

Diagnostics are exposed through the Lakona.Game.Cluster Meter and ActivitySource. Metrics use low-cardinality tags such as stage, status, delivery, and message kind.

It does not provide a production network adapter, Redis-specific state, external platform discovery bindings, remote actor proxies, actor migration, or durable route state. RPC-specific clients, binders, and fixed TCP + MemoryPack transport behavior live inside Lakona.Game.Server.

Actor route helpers produce route keys from application-chosen actor ids only. They do not encode node ids, endpoints, execution lanes, or local actor-kernel scheduler internals.

Route locations include a route generation, node epoch, endpoint, lease expiration, and metadata. In-memory registration rejects stale generations and older node epochs, and lease refresh requires the caller to present the matching route owner. This keeps restarted nodes and moved route owners from accidentally reviving old ownership.

Cluster Configuration

Runtime configuration uses the application Lakona root. Static settings tell a node its own identity, which actor kinds it may host, which client endpoints to expose, which cluster endpoint to advertise, and which seed endpoints can reach the cluster directory. The live cluster view comes from the node directory.

In Lakona.Game cluster terminology, a node is one .NET server process. Machine, process, and node are treated as the same deployment unit. Actor hosting capability is configured inside a node. A development node can host all actor kinds in one process, while production can split actor kinds across several nodes without changing route or messaging code.

All-In-One Development Node

{
  "Lakona": {
    "Node": {
      "Id": "dev-1"
    },
    "ActorHosts": [ "room", "matchmaking", "leaderboard" ],
    "Endpoints": [
      {
        "Transport": "websocket",
        "Serializer": "json",
        "Host": "127.0.0.1",
        "Port": 20000,
        "Path": "/ws",
        "RpcServices": [ "login", "player" ]
      },
      {
        "Transport": "kcp",
        "Serializer": "json",
        "Host": "127.0.0.1",
        "Port": 20001,
        "RpcServices": [ "battle" ]
      }
    ],
    "Cluster": {
      "Endpoint": "tcp://127.0.0.1:21000",
      "Serializer": "json",
      "Seeds": [ "tcp://127.0.0.1:21000" ],
      "RouteLeaseSeconds": 30
    }
  }
}

This layout is for local development and smoke tests. The node-directory and route-directory implementations are ordinary DI services supplied by the game server process or project configuration. Their storage can be in-memory for local validation.

Split Production Nodes

{
  "Lakona": {
    "Node": {
      "Id": "data-1"
    },
    "ActorHosts": [ "matchmaking", "leaderboard" ],
    "Cluster": {
      "Endpoint": "tcp://10.0.0.1:21001",
      "Seeds": [ "tcp://10.0.0.1:21001" ],
      "RouteLeaseSeconds": 30
    }
  }
}

{
  "Lakona": {
    "Node": {
      "Id": "gateway-1"
    },
    "ActorHosts": [],
    "Endpoints": [
      {
        "Transport": "websocket",
        "Serializer": "json",
        "Host": "0.0.0.0",
        "AdvertisedHost": "gateway-1",
        "Port": 20000,
        "Path": "/ws",
        "RpcServices": [ "login", "player" ]
      }
    ],
    "Cluster": {
      "Endpoint": "tcp://10.0.0.2:21002",
      "Seeds": [ "tcp://10.0.0.1:21001" ]
    }
  }
}

The nodes above join the same ephemeral replicated control plane through their seed endpoints. The gateway node hosts no application actors because ActorHosts is empty, but it still exposes client RPC services and a node-to-node cluster endpoint.

Startup service groups are declared in hotfix code. Every node whose ActorHosts includes the actor kind starts one replica and advertises a ready descriptor through the node directory. Replica state is node-local.

Every node that configures Lakona:Cluster:Endpoint must listen on that endpoint. Framework-owned cluster endpoint hosting binds node-directory RPC, route-directory RPC, notification relay, and remote actor dispatch when the corresponding local services are registered in DI.

Lakona.Game.Server supplies one framework-owned node-to-node channel using TCP and MemoryPack. This is separate from endpoint-local client RPC serializer names. Cluster peers negotiate lakona.cluster.memorypack.v1 before RPC starts.

Node Directory Storage

The core package includes transport-neutral node-directory contracts and an in-memory implementation for local validation. Under replicated hosting, directory reads are projections of the locally replicated membership snapshot; they do not query a database or seed endpoint.

Framework-owned membership and route state is intentionally ephemeral. Product state that must survive cluster loss belongs in application-owned persistence, outside the cluster directory contracts.

Route Key Conventions

ClusterActorRouteKeys provides standard route key helpers:

• ForActor("player/alice") → route key "actor:player/alice" for actor-targeted messages.
• ForReply(nodeId) → route key "actor-reply:<nodeId>" for reply messages used by RemoteActorGateway.

These are conventions, not protocol requirements. Projects can define their own route key schemes.