Client

​

Requirements

• Cluster with remoting: Target nodes must run GoAkt with clustering and remoting enabled.
• At least one node: client.New requires a non-empty slice of nodes; it fails with “nodes are required” otherwise.
• Node addresses: Each node is specified as host:port (remoting host and port, e.g. 127.0.0.1:8080). Addresses are validated as TCP addresses.
• Serialization: The client must use the same serializers and compression as the cluster. Pass remote.Config via WithRemoteConfig when creating nodes. Without it, the node uses default remoting settings, which may not match the cluster.

​

Creating a client

import (
    "context"
    "github.com/tochemey/goakt/v4/client"
    "github.com/tochemey/goakt/v4/remote"
)

ctx := context.Background()

nodes := []*client.Node{
    client.NewNode("127.0.0.1:8080", client.WithRemoteConfig(remote.NewConfig("127.0.0.1", 0,
        remote.WithCompression(remote.ZstdCompression),
        remote.WithSerializers(remote.NewProtoSerializer()),
    ))),
    client.NewNode("127.0.0.1:8081", client.WithRemoteConfig(remote.NewConfig("127.0.0.1", 0,
        remote.WithCompression(remote.ZstdCompression),
        remote.WithSerializers(remote.NewProtoSerializer()),
    ))),
}

cl, err := client.New(ctx, nodes)
if err != nil {
    return err
}
defer cl.Close()

​

Node options

• WithRemoteConfig: Set remoting config (compression, serializers, timeouts, TLS). Required for correct serialization.
• WithWeight: Set initial node weight for load balancing (used by LeastLoadStrategy).

​

Connecting to a TLS-enabled cluster

nodes := []*client.Node{
    client.NewNode("127.0.0.1:8080",
        client.WithRemoteConfig(remote.NewConfig("127.0.0.1", 0,
            remote.WithTLS(&tls.Info{ClientConfig: clientTLSConfig}),
        )),
    ),
}

​

Messaging

• Tell: Fire-and-forget to an actor. message must be proto.Message. Returns ErrActorNotFound if the actor is not found.
• Ask: Request-response to an actor. Blocks until reply or timeout. message accepts any (must be serializable). Returns ErrActorNotFound if the actor is not found.
• TellGrain: Tell a grain. message must be proto.Message. The grain kind must be registered on the cluster via RegisterGrainKind. By default the call returns once the hosting node has processed the message and surfaces the error the handler reported; pass client.WithOneWay() to return once that node has enqueued the message, without waiting for the grain to process it. See one-way tells.
• AskGrain: Request-response to a grain. message accepts any. The grain kind must be registered on the cluster.

​

Spawning and lifecycle

• Spawn: Spawn an actor on a node (uses default balancer). Returns error only; does not return the actor address.
• SpawnBalanced: Spawn with a specific balancing strategy for that call.
• ReSpawn: Restart an actor (stop and spawn again). If the actor is not found, returns nil (no error).
• Stop: Stop an actor. If the actor is not found, returns nil (no error).
• Reinstate: Reinstate a suspended actor. If the actor is not found, returns nil (no error).

​

Discovery and inspection

• Exists: Check if an actor is registered in the cluster. Returns (false, nil) when the actor does not exist; returns an error only on lookup failure (e.g. network).
• Kinds: List registered actor kinds. Queries one node (via balancer) and returns kinds from the cluster.

​

Options

• WithBalancerStrategy: Set load-balancing strategy (default: round-robin).
• WithRefresh: Periodically refresh node weights by querying each node’s load. Used by LeastLoadStrategy to prefer the least-loaded node.

​

Balancer strategies

• RoundRobinStrategy: Cycle through nodes in order.
• RandomStrategy: Pick a node at random.
• LeastLoadStrategy: Prefer the node with the lowest load. Requires WithRefresh to update weights; otherwise weights stay at initial values.

​

Thread safety

​

Errors

• ErrActorNotFound: Tell or Ask when the actor is not found in the cluster.
• “nodes are required”: New when the nodes slice is nil or empty.
• Proto errors: Various errors from the remote layer (e.g. CODE_UNAVAILABLE, CODE_DEADLINE_EXCEEDED).
• Network errors: Connection failures, timeouts, etc.

​

See also

• Remoting: Cluster remoting configuration
• Serialization: Message serialization (client must match cluster)
• Code Map: client/ package overview