Extending GoAkt

This page lists the interfaces to implement when extending the framework. Wire implementations via the indicated options.

Discovery provider

Discovery Provider

package discovery

type Provider interface {
    ID() string
    Initialize() error
    Register() error
    Deregister() error
    DiscoverPeers() ([]string, error)
    Close() error
}

ID: Provider name.
Initialize: One-time setup.
Register: Register this node with the discovery backend.
Deregister: Remove this node on shutdown.
DiscoverPeers: Return peer addresses (host:port strings).
Close: Release resources.

Create a sub-package under discovery/. Pass the provider to ClusterConfig when creating the actor system. See discovery/selfmanaged for a built-in zero-config provider using UDP broadcast.

A node queries its provider when it boots, and with the default quorum of 1 it does not query it again. A provider must list a node as soon as Register has returned and must not answer from a stale view, or it must return an error while its view may be incomplete. Otherwise nodes that boot at the same moment can form separate clusters that never merge. See Discovery happens at boot.

Mailbox

package actor

type Mailbox interface {
    Enqueue(msg *ReceiveContext) error
    Dequeue() *ReceiveContext
    IsEmpty() bool
    Len() int64
    Dispose()
}

Enqueue: Push a message. Return error when full (bounded mailbox).
Dequeue: Fetch the next message. Called only from the processing goroutine.
IsEmpty / Len: Query mailbox state.
Dispose: Free resources, unblock any waiters.

Create a file in actor/. Pass via WithMailbox(mailbox) as a SpawnOption. Reference unbounded_mailbox.go and unbounded_priority_mailbox.go.

Extension (system-wide)

package extension

type Extension interface {
    ID() string
}

ID must be unique, alphanumeric, up to 255 chars. Add domain-specific methods to your concrete type. Pass via WithExtensions(ext) when creating the actor system. Actors access via ctx.Extension(id) and type assertion. See Extensions and Dependencies for usage.

Dependency (per-actor)

package extension

type Dependency interface {
    Serializable
    // ID returns the unique identifier for the extension.
    //
    // The identifier must:
    //   - Be no more than 255 characters long.
    //   - Start with an alphanumeric character [a-zA-Z0-9].
    //   - Contain only alphanumeric characters, hyphens (-), or underscores (_) thereafter.
    //
    // Identifiers that do not meet these constraints are considered invalid.
    ID() string
}

type Serializable interface {
    encoding.BinaryMarshaler
    encoding.BinaryUnmarshaler
}

Dependencies must be serializable for cluster relocation. Pass via WithDependencies(dep) as a SpawnOption, or register with the actor system via system.Inject(dep) after startup. Actors access via ctx.Dependencies() in PreStart, Receive, PostStop. See Extensions and Dependencies for usage.

​Discovery provider

​Mailbox

​Extension (system-wide)

​Dependency (per-actor)

Discovery provider

Mailbox

Extension (system-wide)

Dependency (per-actor)