Migrating from v3 to v4

​

What changed

• One actor reference. *PID stands for local and remote actors alike.
• One lookup. ActorOf finds an actor on this node or anywhere in the cluster.
• One scheduler. The same Schedule* methods serve local and remote actors.
• Any message type. Messages are any instead of proto.Message. Protocol Buffers still work, and plain Go types can cross the network through the CBOR or JSON serializer.
• Configured remoting. You enable remoting with a remote.Config. The client the actor system uses to reach other nodes is internal.
• Paths instead of addresses. The Path interface replaces *address.Address.

​

Quick reference

​

Breaking changes

​

1. Module path

​

2. Messages are any

• actor.Tell, actor.Ask, PID.Tell, PID.Ask and their batch forms.
• ReceiveContext.Message, ReceiveContext.Response, ReceiveContext.Tell and ReceiveContext.Ask.
• PID.PipeTo and PID.PipeToName: the task is func() (any, error).
• ScheduleOnce, Schedule and ScheduleWithCron.
• AskGrain and TellGrain.

package orders

import (
	"github.com/tochemey/goakt/v4/actor"
)

// PlaceOrder and OrderPlaced are plain Go types. Protocol Buffers messages work the same way.
type PlaceOrder struct{ ID string }
type OrderPlaced struct{ ID string }

type OrderActor struct{}

var _ actor.Actor = (*OrderActor)(nil)

func (a *OrderActor) PreStart(*actor.Context) error { return nil }

func (a *OrderActor) Receive(ctx *actor.ReceiveContext) {
	switch msg := ctx.Message().(type) {
	case *actor.PostStart:
		ctx.Logger().Info("order actor started")
	case *PlaceOrder:
		ctx.Response(&OrderPlaced{ID: msg.ID})
	default:
		ctx.Unhandled()
	}
}

func (a *OrderActor) PostStop(*actor.Context) error { return nil }

​

3. System messages moved to the actor package

package watch

import (
	"github.com/tochemey/goakt/v4/actor"
)

type Watcher struct{}

func (w *Watcher) PreStart(*actor.Context) error { return nil }

func (w *Watcher) Receive(ctx *actor.ReceiveContext) {
	switch msg := ctx.Message().(type) {
	case *actor.Terminated:
		ctx.Logger().Infof("%s stopped at %s", msg.ActorPath().String(), msg.TerminatedAt())
	default:
		ctx.Unhandled()
	}
}

func (w *Watcher) PostStop(*actor.Context) error { return nil }

​

4. *PID is the only actor reference

​

5. One lookup: ActorOf

type ActorSystem interface {
	ActorOf(ctx context.Context, actorName string) (*PID, error)
	// ...
}

package orders

import (
	"context"
	"errors"
	"fmt"

	"github.com/tochemey/goakt/v4/actor"
	gerrors "github.com/tochemey/goakt/v4/errors"
)

func placeOrder(ctx context.Context, system actor.ActorSystem) error {
	pid, err := system.ActorOf(ctx, "orders")
	if err != nil {
		if errors.Is(err, gerrors.ErrActorNotFound) {
			return fmt.Errorf("orders actor is not running: %w", err)
		}
		return err
	}

	if pid.IsRemote() {
		fmt.Printf("orders runs on %s\n", pid.Path().HostPort())
	}

	return actor.Tell(ctx, pid, &PlaceOrder{ID: "42"})
}

​

6. Actors replaces ActorRefs

// v3
Actors() []*PID
ActorRefs(ctx, timeout) ([]ActorRef, error)

// v4
Actors(ctx context.Context, timeout time.Duration) ([]*PID, error)

​

7. Remote scheduling uses the ordinary scheduler

package reports

import (
	"context"
	"time"

	"github.com/tochemey/goakt/v4/actor"
)

type Tick struct{}

func scheduleTick(ctx context.Context, system actor.ActorSystem) error {
	pid, err := system.ActorOf(ctx, "reporter")
	if err != nil {
		return err
	}

	return system.Schedule(ctx, &Tick{}, pid, time.Minute, actor.WithReference("reporter-tick"))
}

​

8. GetPartition is now Partition

​

9. Addresses became paths

• ctx.SenderAddress() becomes ctx.Sender().Path().
• ctx.ReceiverAddress() becomes ctx.Self().Path().
• testkit.Probe.SenderAddress() becomes Probe.Sender(), then Path() or IsRemote() on the PID it returns. Probe.Sender() is nil until an Expect method of the probe has taken a message.

package audit

import (
	"github.com/tochemey/goakt/v4/actor"
)

type Auditor struct{}

func (a *Auditor) PreStart(*actor.Context) error { return nil }

func (a *Auditor) Receive(ctx *actor.ReceiveContext) {
	sender := ctx.Sender()
	if sender.Equals(ctx.ActorSystem().NoSender()) {
		ctx.Logger().Info("message without a sender")
		return
	}

	ctx.Logger().Infof("%s (remote: %t) sent a message to %s",
		sender.Path().String(), sender.IsRemote(), ctx.Self().Path().String())
}

func (a *Auditor) PostStop(*actor.Context) error { return nil }

​

10. Remoting is configured, not constructed

• Replace WithRemoting with actor.WithRemote(remote.NewConfig(bindAddr, bindPort, opts...)).
• Message remote actors through PIDs: get one with ActorOf, PID.RemoteLookup or ReceiveContext.RemoteLookup, then use Tell and Ask as for a local actor. PID.RemoteStop and PID.RemoteReSpawn stop and restart an actor on a given node.
• To spawn an actor on a given node, pass actor.WithHostAndPort(host, port) to Spawn. The target node must have registered the actor type with system.Register(ctx, actor). Spawn forwards these options to that node: WithRelocationDisabled, WithDependencies, WithStashing, WithPassivationStrategy, WithReentrancy, WithSupervisor, WithRole and WithInitTimeout, and, in cluster mode, the reliable-delivery options such as AsReliableProducer and AsReliableConsumer.
• From a program that does not run an actor system, use the client package: client.New(ctx, nodes) with nodes from client.NewNode(address, client.WithRemoteConfig(config)).
• Configure TLS with remote.WithTLS on the remote config. actor.WithTLS is deprecated, and when both are set the remote config wins.

package main

import (
	"context"
	"os"

	"github.com/tochemey/goakt/v4/actor"
	"github.com/tochemey/goakt/v4/log"
	"github.com/tochemey/goakt/v4/remote"
)

type PlaceOrder struct{ ID string }
type OrderPlaced struct{ ID string }

func main() {
	ctx := context.Background()

	config := remote.NewConfig("127.0.0.1", 3321,
		remote.WithCompression(remote.ZstdCompression),
		remote.WithSerializables(new(PlaceOrder), new(OrderPlaced)),
	)

	system, err := actor.NewActorSystem("orders",
		actor.WithLogger(log.NewSlog(log.InfoLevel, os.Stdout)),
		actor.WithRemote(config),
	)
	if err != nil {
		panic(err)
	}

	if err := system.Start(ctx); err != nil {
		panic(err)
	}

	_ = system.Stop(ctx)
}

​

11. The Logger interface

• InfoContext, InfofContext, WarnContext, WarnfContext, ErrorContext, ErrorfContext, DebugContext and DebugfContext, which take a context.Context first so trace data can reach the log.
• LogLevel() Level: the minimum level the logger writes.
• Enabled(level Level) bool: whether a level is written; check it before expensive work.
• With(keyValues ...any) Logger: a logger that adds the given fields to every entry. Keys and values alternate, and keys are strings.
• Flush() error: writes buffered entries.
• StdLogger() *log.Logger: a standard library logger for dependencies that need one.

​

New in v4

​

Serializers for any Go type

• ProtoSerializer is registered for every proto.Message by default. Protocol Buffers users change nothing.
• CBORSerializer and JSONSerializer encode plain Go types. Register types with remote.WithSerializables(new(MyMessage)) for CBOR or remote.WithJSONSerializables(new(MyMessage)) for JSON. A typed nil interface pointer, such as (*MyInterface)(nil), registers every type that implements the interface.
• A custom serializer implements remote.Serializer and is registered with remote.WithSerializers(new(MyMessage), mySerializer).

​

New error sentinels

• errors.ErrRemotingDisabled: a remote operation was attempted but remoting is not enabled.
• errors.ErrNotLocal: the operation needs a local PID but got a remote one.

​

PID.Kind

​

Logger implementations

• log.NewSlog(level, writers...): a logger built on the standard library slog that writes JSON. log.NewSlogFrom(logger, level) wraps a *slog.Logger you already have.
• log.NewZap(level, writers...): a logger built on Zap. Debug, info and warning entries written to files are buffered, so call Flush at shutdown.
• log.DiscardLogger: a logger that writes nothing.

​

Migration checklist

• Change imports from github.com/tochemey/goakt/v3 to github.com/tochemey/goakt/v4.
• Replace proto.Message with any in handlers and call sites.
• Replace goaktpb.* with actor.*; build messages with their constructors and read them with their accessors.
• Replace ActorRef with *PID.
• Replace LocalActor and RemoteActor with ActorOf(ctx, name), and update callers of ActorOf to its two return values.
• Replace ActorRefs with Actors(ctx, timeout).
• Replace RemoteSchedule* with Schedule* on a PID from ActorOf; give ScheduleWithCron a WithReference in cluster mode.
• Replace GetPartition with Partition.
• Replace pid.Address() with pid.Path(), and remove imports of the address package.
• Replace ctx.SenderAddress() and ctx.ReceiverAddress() with ctx.Sender().Path() and ctx.Self().Path().
• Replace Probe.SenderAddress() with Probe.Sender() and Path().
• Replace WithRemoting and any use of remote.Remoting or remote.Client with WithRemote(config), PID methods, or the client package.
• Register serializers for every message type that crosses the network and is not Protocol Buffers.
• Add the new methods to custom Logger implementations.