Minimal actor framework with goodies to build reactive and distributed system in golang using protocol buffers as actor messages.
If you are not familiar with the actor model, the blog post from Brian Storti here is an excellent and short introduction to the actor model. Also, check reference section at the end of the post for more material regarding actor model
- Send a synchronous message to an actor from a non actor system
- Send an asynchronous(fire-and-forget) message to an actor from a non actor system
- Actor to Actor communication (check the examples' folder)
- Enable/Disable Passivation mode to remove/keep idle actors
- PreStart hook for an actor.
- PostStop hook for an actor for a graceful shutdown
- ActorSystem: Actors live and die withing a system.
- Actor to Actor communication via Tell and Ask message patterns.
- Restart an actor
- (Un)Watch an actor
- Stop and actor
- Create a child actor
- Supervisory Strategy (Restart and Stop directive are supported)
- Behaviors (Become/BecomeStacked/UnBecome/UnBecomeStacked)
- Logger interface with a default logger
- Examples (check the examples' folder)
- Integration with OpenTelemetry for traces and metrics.
- Remoting
- Actors can send messages to other actors on a remote system via Tell and Ask message patterns.
- Actors can look up other actors' address on a remote system.
- Cluster Mode
Actors in Go-Akt live within an actor system. They can be long-lived actors or be passivated after some period of time
depending upon the configuration set during their creation. To create an actor one need to implement the Actor
interface.
Actors in Go-Akt use Google Protocol Buffers message as a mean of communication. The choice of protobuf is due to easy serialization over wire
and strong schema definition.
In Go-Akt, actors have the following characteristics:
- Each actor has a process id
PID
. Via the process id any allowable action can be executed by the actor. - Lifecycle via the following methods:
PreStart
,PostStop
. It means they can live and die like any other process. - They handle and respond to messages via the method
Receive
. While handling messages they can:- Create other (child) actors via their process id
PID
SpawnChild
method - Send messages to other actors via their process id
PID
Ask
,RemoteAsk
(request/response fashion) andTell
,RemoteTell
(fire-and-forget fashion) methods - Stop (child) actors via their process id
PID
- Watch/Unwatch (child) actors via their process id
PID
Watch
andUnWatch
methods - Supervise the failure behavior of (child) actors. The supervisory strategy to adopt is set during the creation of the actor system. (Restart and Stop directive are supported) at the moment
- Remotely lookup for an actor on another node via their process id
PID
RemoteLookup
. This allows them to send messages remotely viaRemoteAsk
orRemoteTell
methods
- Create other (child) actors via their process id
- They can adopt various form using the behavior feature
- Few metrics are also accessible:
- Mailbox size at a given time. That information can be accessed via the process id
PID
MailboxSize
method - Total number of messages handled at a given time. That information can be accessed via the process id
PID
ReceivedCount
method - Total number of restart. This is accessible via the process id
PID
RestartCount
method - Total number of panic attacks. This is accessible via the process id
PID
ErrorsCount
method
- Mailbox size at a given time. That information can be accessed via the process id
Without an actor system, it is not possible to create actors in Go-Akt. Only a single actor system is allowed to be created per node when using Go-Akt.
To create an actor system one just need to use the NewActorSystem
method with the various options.
The actor and actor-system metrics as well traces are accessible via the integration with OpenTelemetry.
To run the system in a cluster mode, each node is required to have two different ports open with the following name tags:
clients-port
: help the cluster client to communicate with the rest of cluster.peers-port
: help the cluster engine to communicate with other nodes in the cluster
The rationale behind those ports is that the cluster engine is wholly built on the embed etcd server.
The following outlines the cluster mode operations which can help have a healthy GoAkt cluster:
- One can start a single node cluster or a multiple nodes cluster.
- To add more nodes to the cluster, kindly add them one at a time.
- To remove nodes, kindly remove them one at a time. Remember to have a healthy cluster you will need at least three nodes running.
The cluster engine depends upon the discovery mechanism to find other nodes in the cluster. At the moment the following providers are implemented:
- the kubernetes api integration is provided and fully functional.
- the static provider
To get the kubernetes discovery working as expected, the following pod labels need to be set:
app.kubernetes.io/part-of
: set this label with the actor system nameapp.kubernetes.io/component
: set this label with the application nameapp.kubernetes.io/name
: set this label with the application name
You’ll also have to grant the Service Account that your pods run under access to list pods. The following configuration can be used as a starting point. It creates a Role, pod-reader, which grants access to query pod information. It then binds the default Service Account to the Role by creating a RoleBinding. Adjust as necessary:
kind: Role
apiVersion: rbac.authorization.k8s.io/v1
metadata:
name: pod-reader
rules:
- apiGroups: [""] # "" indicates the core API group
resources: ["pods"]
verbs: ["get", "watch", "list"]
---
kind: RoleBinding
apiVersion: rbac.authorization.k8s.io/v1
metadata:
name: read-pods
subjects:
# Uses the default service account. Consider creating a new one.
- kind: ServiceAccount
name: default
roleRef:
kind: Role
name: pod-reader
apiGroup: rbac.authorization.k8s.io
A working example can be found here with a small doc showing how to run it.
go get github.com/tochemey/goakt
Kindly check out the examples' folder.
Contributions are welcome! The project adheres to Semantic Versioning and Conventional Commits. This repo uses Earthly.
To contribute please:
- Fork the repository
- Create a feature branch
- Submit a pull request
Prior to submitting a pull request, please run:
earthly +test