Extensions and Dependencies

GoAkt supports two injection mechanisms: extensions (system-wide) and dependencies (per-actor).

Extensions

Extensions are system-wide plugins registered at actor system creation. They provide cross-cutting capabilities (event sourcing, metrics, service registry) accessible from any actor.

The Extension interface

package extension

type Extension interface {
    ID() string
}

ID must be 2 to 255 characters, start with a letter or digit, and contain only letters, digits, - and _. It must be unique: a later extension with the same ID replaces the earlier one. Add domain-specific methods to your concrete type.

Wiring

Pass extensions via WithExtensions(ext1, ext2, ...) when creating the actor system. Actors access via ctx.Extension(id) or ctx.Extensions() on Context, ReceiveContext, or GrainContext. Type-assert to access your methods.

Use cases

Event sourcing engine
Metrics recorder
Service registry client
Distributed tracing

Dependencies

Dependencies are per-actor resources injected at spawn time. Unlike extensions, they are scoped to a single actor and must be serializable for cluster relocation.

The Dependency interface

package extension

type Dependency interface {
    Serializable
    // ID returns the unique identifier for the extension.
    //
    // The identifier must:
    //   - Be between 2 and 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. The
    // identifier is validated without its surrounding spaces but stored as returned,
    // so it should carry none. A later registration with the same identifier
    // replaces the earlier one.
    ID() string
}

type Serializable interface {
    encoding.BinaryMarshaler
    encoding.BinaryUnmarshaler
}

Wiring

Dependencies can be injected in two ways:

At spawn time: Pass via WithDependencies(dep1, dep2, ...) as a SpawnOption. The actor receives them through ctx.Dependencies() or ctx.Dependency(id) in PreStart, Receive, and PostStop.
Via the actor system: Call system.Inject(dep1, dep2, ...) after the system has started. This registers the dependency types with the actor system’s registry, enabling the framework to restore dependencies during cluster topology changes or when creating actors on remote hosts. A local spawn registers the types of its own dependencies, so Inject matters on the other nodes: those that may receive the actor through relocation or a remote spawn without ever spawning that dependency type themselves.

Use cases

Database client
External API client
Configuration provider

Serializability is required because dependencies travel with the actor during relocation. The framework serializes them to the cluster registry and reconstructs them on the target node.

Quickstart

Actors

Grains

AI Agents

Remoting

Clustering

Advanced

Architecture

Extensions and Dependencies

Extensions

The Extension interface

Wiring

Use cases

Dependencies

The Dependency interface

Wiring

Use cases

​Extensions

​The Extension interface

​Wiring

​Use cases

​Dependencies

​The Dependency interface

​Wiring

​Use cases

Extensions

The Extension interface

Wiring

Use cases

Dependencies

The Dependency interface

Wiring

Use cases