Tochemey/goakt

GoAkt is a distributed actor framework for Go that enables the construction of scalable, fault-tolerant systems through location-transparent actor messaging and clustering. It supports multi-datacenter deployments with configurable service discovery, reliable message delivery, and conflict-free replicated data types (CRDTs) for distributed state management. The system provides reactive stream processing, configurable actor passivation, and comprehensive observability via OpenTelemetry metrics.

64 changes.

This period marks the development of GoAkt v4, introducing a comprehensive distributed actor system with reliable delivery, multi-datacenter support, and work-pulling reactive streams. The release features a major architectural overhaul including a new discovery provider interface, diverse cluster backends (Kubernetes, NATS, Consul, mDNS), and robust serialization via Protobuf and CBOR. Infrastructure improvements include a Docker-based build system, upgraded Go dependencies, and extensive playground examples validating actor lifecycle, supervision, and cluster rebalancing behaviors.

59 changes.

This period focused on building the foundational infrastructure for multi-datacenter support, including CRDT-based state replication, etcd/NATS control planes, and UDP discovery. It introduced a high-performance TCP remoting stack with multiplexing, compression, and reliable delivery, alongside reentrant async request handling and granular configuration options. The work was heavily supported by extensive bug fixes for race conditions, lifecycle management, and crash recovery, validated through a large suite of playground reproduction cases and benchmarks.

The actor package now exposes the core Actor interface with PreStart, Receive, and PostStop lifecycle hooks, alongside the Path interface for location-transparent actor addressing. The public API includes Ask, Tell, BatchTell, and BatchAsk functions for synchronous and asynchronous messaging, with dedicated support for remote PIDs and context-based ask deadlines. This change establishes the foundational messaging and actor definition contracts for the system.

actor · high confidence

This change introduces the internal protocol buffers and serialization logic required for distributed data (CRDTs) and multi-datacenter capabilities. It adds generated protobuf definitions for CRDT types (GCounter, PNCounter, Flag, LWWRegister, ORSet, ORMap, MVRegister) and multi-datacenter metadata (DataCenter, DataCenterState, ControlPlaneEventType), alongside reliable delivery patterns. To support these features, it adds a CRDT codec for encoding/decoding these types to/from protobuf, a composite serializer (CRDTValueSerializer) that routes proto.Message values to ProtoSerializer and others to CBORSerializer, and a BoltDB-backed snapshot store for durable CRDT state recovery.

internal/internalpb · high confidence

A new Go application in the playground demonstrates distributed session management using Conflict-free Replicated Data Types (CRDTs). The demo runs a three-node cluster with an embedded NATS server, utilizing an ORSet to track active sessions across nodes. It illustrates adding and removing sessions via a tracker actor, reading local state, and verifying data replication to other nodes, while also showing how a reporter actor subscribes to change notifications.

playground/issue-1134 · high confidence

GoAkt cluster nodes can now discover each other using HashiCorp Consul or etcd as the service registry. The new Consul provider registers nodes as services with health checks and queries the Consul catalog to find peers, while the etcd provider uses leases and key-value operations under a namespaced prefix for registration and discovery. Both providers implement the standard discovery.Provider interface, allowing users to configure connection details, timeouts, and authentication to bootstrap cluster formation.

discovery/consul · high confidence

A new DNS Service Discovery (DNS-SD) provider has been added to the discovery package, allowing clusters to bootstrap by resolving peer IP addresses via standard DNS lookups (A and AAAA records) for a configured domain name. Users can configure the provider with a required domain name and an optional IPv6 flag, enabling integration with DNS round-robin, load balancers, or Kubernetes headless services. The provider implements the standard discovery interface, performing lookups with a 30-second timeout and returning sorted, deduplicated IP addresses to facilitate initial node joining before gossip takes over.

discovery/dnssd · high confidence

The Kubernetes discovery provider enables GoAkt cluster nodes running inside a Kubernetes cluster to discover each other using the Kubernetes API. It lists pods matching configured labels and derives peer addresses from pod IPs and container ports. The provider deliberately ignores pod readiness conditions to prevent bootstrap deadlocks on cold starts, while excluding terminating and IP-less pods. Configuration requires the namespace, discovery port name, and pod labels; the previously required remoting and peers port names are now deprecated and ignored, as those ports are learned via node metadata after joining.

discovery/kubernetes · high confidence

GoAkt cluster nodes can now discover each other and form a cluster using a NATS server as the discovery backend. This new provider allows nodes to register with NATS, subscribe to a shared subject, and discover peers via request-reply messaging, while relying on Memberlist for ongoing membership gossip. Users can configure the provider by specifying the NATS server URL, discovery subject, node host, and discovery port, with support for custom timeouts, reconnection backoff, and logging.

discovery/nats · high confidence

The internal/metric package now provides comprehensive OpenTelemetry instrumentation for the actor system, cluster, and CRDT replicator. This includes per-actor metrics (e.g., children count, stash size, deadletters, restarts, uptime), system-level metrics (e.g., live actor count, grain count, peer count, uptime), cluster membership metrics (joined/left counts), relocation metrics (duration, success/failure counts), and CRDT replicator metrics (store size, merge/delta counts, cross-DC replication lag). A new Provider initializes these instruments using the global OpenTelemetry MeterProvider, and tests verify correct instrument creation and error handling.

internal/metric · high confidence

The playground sample demonstrates the new capability to schedule timers that are scoped to a grain's activation lifecycle. Users can start interval timers in OnActivate, schedule one-shot timeouts with explicit references for cancellation, and cancel timers from message handlers or self-cancel them. These timers do not prevent the grain from passivating, and all timers are automatically cancelled when the grain deactivates, ensuring a fresh state upon reactivation.

playground/issue-1288 · high confidence

The memory package now provides platform-specific functions to report system memory statistics. On Linux, macOS, Windows, and BSD variants, the Size() and Free() functions expose total and available physical memory using native OS APIs (sysinfo, sysctl, GlobalMemoryStatusEx). Additionally, the Used() function reports the Go application's current heap memory usage via the runtime package. For unsupported platforms, Size() and Free() return an error, while Used() remains functional.

memory · high confidence

A new \hash\ package introduces a \Hasher\ interface and a default implementation based on xxh3, enabling custom hash code generation for actor partitioning in cluster mode.

hash · high confidence

A new \book/\ directory has been added, containing an introductory README, an architecture overview, and the first three chapters of a deep-dive guide on GoAkt's internal implementation. This resource is intended for maintainers and contributors, covering the actor model, system construction, and the guardian tree, with a strict methodology of verifying statements against the source code and named tests.

book · high confidence

A new mDNS (multicast DNS) discovery provider is introduced in the \discovery/mdns\ package, allowing GoAkt cluster nodes to discover each other on the local network without a central server. The implementation uses the \hashicorp/mdns\ library to advertise and browse for services, enabling nodes to bootstrap connections via multicast. Configuration is handled through a \Config\ struct specifying service name, type, domain, and port, with validation ensuring required fields are present. The provider implements the standard \discovery.Provider\ interface, supporting initialization, registration, deregistration, and peer discovery, and includes comprehensive tests to verify its behavior.

discovery/mdns · high confidence

A new Go example file has been added to the playground/issue-925 directory. This example demonstrates how to initialize an actor system, spawn a long-lived parent actor, and create child actors within the actor's lifecycle, serving as a reference implementation for the specific issue.

playground/issue-925 · high confidence

A new Go example has been added to the playground demonstrating how to configure a GoAkt actor system for remote communication and clustering. The code sets up a DNS-SD discovery service, configures specific ports for discovery (3322) and peer communication (3320), and registers a custom singleton actor kind. It also illustrates the correct pattern for spawning a singleton actor by explicitly ignoring the \ErrSingletonAlreadyExists\ error, which allows for safe rolling upgrades where older hosts might still attempt to spawn the actor.

playground/issue-957 · high confidence

A new living sample in playground/issue-1290 demonstrates non-blocking grain request scheduling (reentrancy) via a checkout pipeline. The sample shows how an OrderGrain can fan out concurrent downstream requests (to inventory, fraud, and payment grains/actors) from a single handler turn, defer the final reply, and join the results in continuations without blocking. It exercises reentrancy modes (AllowAll for responsiveness, StashNonReentrant for consistency), runtime toggling of reentrancy, per-call timeouts with error identity preservation, and completing deferred replies from grain timers.

playground/issue-1290 · high confidence

Added a self-validating Kubernetes (kind) reproduction for issue \#1260 that demonstrates reliable crash recovery on the default cluster configuration. The playground includes a Go application with relocatable workers, an HTTP surface for spawning and verifying actors, and a demo script that simulates a hard pod crash (os.Exit) to verify that the leader reconstructs the relocation set from the replicated cluster registry and publishes a best-effort RelocationStarted event.

playground/issue-1260 · high confidence

A new self-managed discovery provider has been added to the GoAkt cluster system, enabling nodes to discover each other via UDP broadcast on the local network without requiring third-party infrastructure like Consul, etcd, or Kubernetes. This provider implements the standard discovery interface, allowing users to configure cluster formation using only a cluster name and local address, with automatic peer detection and platform-specific optimizations for loopback and multi-node testing on Linux, macOS, and Windows.

discovery/selfmanaged · high confidence

A new static discovery provider has been added to the GoAkt cluster engine, allowing users to bootstrap a cluster using a fixed, pre-configured list of peer addresses (host:port) rather than relying on external service discovery. This provider, located in the \discovery/static\ package, implements the standard \discovery.Provider\ interface with no external dependencies; it validates the provided host list at initialization and returns those peers on every discovery call, making it suitable for small, stable environments where node addresses are known in advance.

discovery/static · high confidence

The internal/locker package now includes a NoCopy type that implements Lock and Unlock methods, providing a mechanism to prevent accidental copying of structs that rely on synchronization primitives.

internal/locker · high confidence

New internal helper functions have been added to support generic slice operations. The \internal/chunk\ package introduces \Chunkify\, which splits a slice into smaller, equal-sized chunks, while the \internal/slices\ package adds \Filter\, allowing users to create a new slice containing only elements that satisfy a given predicate. Both utilities are generic and include corresponding unit tests to verify correct behavior.

internal/chunk, internal/slices · high confidence

The internal/chain package now provides a Chain type that allows users to execute multiple error-returning functions and aggregate results. Depending on configuration, the chain can stop at the first error (fail-fast) or continue to collect all errors into a combined error using go.uber.org/multierr. It supports context propagation and conditional execution via options like WithFailFast, WithRunAll, and WithContext.

internal/chain · high confidence

The internal/pointer package now provides generic helper functions To and Deref. To returns a pointer to a given value, and Deref safely dereferences a pointer, returning a default value if the pointer is nil. These utilities are intended for internal use to simplify pointer handling within the codebase.

internal/pointer · high confidence

A new playground example (playground/issue-1017) has been added to demonstrate and verify that child actors are not relocated when their parent is relocated during a cluster rebalance. The demo sets up two GoAkt actor systems connected via NATS discovery, spawns a parent actor with three children, and simulates a system shutdown to trigger relocation, ensuring the actor hierarchy remains intact on the target node.

playground/issue-1017 · high confidence

A new Go source file (playground/issue-906/main.go) was added to demonstrate actor supervision behavior. It defines two actors, A and B, where actor A is configured with an EscalateDirective to forward errors to its parent, while actor B uses a ResumeDirective to handle those escalated errors and continue processing. This example illustrates how error directives interact within the goakt v4 actor system.

playground/issue-906 · high confidence

A new Go application has been added to the playground/issue-1036 directory that demonstrates how to configure and start a GoAkt actor system with clustering enabled via NATS discovery. The example sets up a local NATS server, configures the actor system with specific discovery and remoting ports, and spawns a singleton actor named 'hello-world'. It also includes logic to send a test message to the singleton and gracefully shut down the system upon receiving an interrupt signal, serving as a reference implementation for cluster-based singleton usage.

playground/issue-1036 · high confidence

A new Go example in the playground demonstrates how to configure and activate a grain with a specific activation role ('game-worker') and eager relocation settings using the goakt v4 actor framework. This sample illustrates the setup of a clustered actor system with NATS-based discovery, showing how grains retain their role context when moved between nodes in the cluster.

playground/issue-1334 · high confidence

A new Go source file has been added to the playground/issue-847 directory, providing a runnable example that demonstrates actor supervision behavior. The code defines a parent actor (Foo) that spawns a child actor (Bar) with a custom supervisor strategy configured to escalate errors. When the child actor encounters an error during its PostStart phase, the parent actor is designed to stop the sender, illustrating the interaction between the actor lifecycle, error handling, and supervision directives within the GoAct framework.

playground/issue-847 · high confidence

A new playground example has been added to demonstrate the fix for issue-973. This example sets up a multi-node actor system using NATS for discovery and remote communication, spawning multiple actors and grains to verify that grain activation strategies (specifically LeastLoad) function correctly across the cluster.

playground/issue-973 · high confidence

A new Go script has been added to the playground/discussion-811 directory that demonstrates a parent-child actor hierarchy using the GoAct v4 library. The example shows how to configure a parent actor to spawn a child actor with a time-based passivation strategy and a supervisor directive that stops the child on any error. It also illustrates handling child termination events and sending asynchronous messages to the child actor.

playground/discussion-811 · high confidence

New example programs have been added to the playground demonstrating core actor system usage. The issue-778 example shows how to create an actor system with a custom logger, spawn a long-lived actor, trigger a restart, and handle lifecycle events like PreStart, PostStart, and PostStop. The issue-788 example demonstrates spawning multiple actors in a loop and properly handling errors during system startup, actor spawning, and system shutdown.

playground/issue-778, playground/issue-788 · high confidence

New playground examples have been added to demonstrate specific actor system behaviors. The \issue-908\ example illustrates actor supervision by spawning child actors with a resume directive and handling panic signals, while the \issue-914\ example demonstrates scalability and cluster configuration by spawning 10,000 actors in both standalone and cluster modes with remote communication enabled.

playground/issue-908, playground/issue-914 · high confidence

New standalone Go programs in the playground demonstrate GoAkt v4 cluster behavior, specifically actor relocation and rebalancing across multiple systems. The example in playground/issue-791 validates that stopping one actor system causes its remote actors to relocate to a surviving peer, while playground/issue-x tests repeated restarts of two systems to verify that actors correctly move back and forth (rebalance) between them over multiple passes.

playground/issue-x · high confidence

New playground scripts in issue-779 and issue-886 demonstrate specific actor system behaviors: issue-779 shows how to register and execute a custom shutdown hook that pauses during system termination, while issue-886 illustrates the lifecycle of a long-lived actor, verifying that it is properly removed from the system after explicit shutdown.

playground/issue-779, playground/issue-886 · high confidence

The internal strconvx package now provides Int2Int32 and ParseInt32 functions that perform explicit bounds checking when converting integers or parsing strings to int32, returning errors for out-of-range values instead of silent overflow. This ensures safer numeric handling within the system's internal ID and serialization logic.

internal/strconvx · high confidence

Users can now specify a custom directory for the cluster node's peer state storage (BoltDB) instead of being forced to use the default location under the home directory. This change allows cluster nodes to start successfully in environments with read-only root filesystems, test sandboxes without a home directory, or processes where the home directory is not writable, by using the new \WithStoreDir\ configuration option.

playground/issue-1403 · high confidence

Added a new playground sample and README for issue \#1408 that documents the two rules a discovery provider must guarantee so that nodes booting simultaneously form a single cluster: visibility before read and consistent reads. The sample demonstrates six scenarios using a built-in NATS provider, custom in-memory providers, and a \requirePeers\ wrapper that forces retries when no peers are listed, illustrating how providers that break these rules result in separate clusters while compliant or retried providers form one.

playground/issue-1408 · high confidence

GoAkt v4 adds reliable delivery for actor endpoints, ensuring exactly-once message processing through a sequenced, flow-controlled protocol with optional durable storage and automatic resend of unconfirmed messages. The framework now supports multi-datacenter deployments, allowing actors to be spawned across distinct data centers with a control-plane-based registry for active DC discovery and lease management. Additionally, the streams package introduces a work-pulling model alongside the existing push-based flows, enabling back-pressure-aware processing where workers pull items from a shared pending pool. These changes are accompanied by a revamped actor system interface and internal relocation engine to support these distributed capabilities.

github.com/tochemey/goakt/v4 · high confidence

This change adds the foundational CRDT (Conflict-free Replicated Data Type) library to the \crdt\ package, providing a replicator for distributed state management. It introduces a \Config\ struct with options for anti-entropy intervals, delta sizes, pruning, tombstone TTL, role-based filtering, and cross-datacenter replication settings. A \Coordination\ type is added to allow users to enforce consistency levels (Majority, All, DCMajority, DCAll) for read and write operations. The package includes implementations for several CRDT types: \GCounter\ (grow-only counter), \PNCounter\ (positive-negative counter), \Flag\ (boolean), \LWWRegister\, \MVRegister\, \ORSet\, and \ORMap\, all implementing the \ReplicatedData\ interface for merge, delta, and clone operations. Additionally, a \StateHasher\ interface and canonical hashing utilities are provided to support efficient anti-entropy synchronization and state verification.

crdt · high confidence

The internal/address package now provides a canonical Address type that identifies actors by system, host, port, name, and a unique incarnation ID. Addresses are validated on construction (via New and NewWithParent) to enforce naming patterns, length limits, and parent-child consistency (system, host, and name constraints). The String() method renders a hierarchical path including all ancestors (e.g., goakt://system@host:port/grand/parent/child), and a separate NewReference constructor allows referencing actors without an incarnation ID. A NoSender sentinel is supported for use as a zero/empty parent in message envelopes.

internal/address · high confidence

Users can now control when virtual actors (grains) are passivated by selecting from three distinct strategies: TimeBasedStrategy, which passivates actors after a specified period of inactivity; MessagesCountBasedStrategy, which triggers passivation after a set number of messages have been processed; and LongLivedStrategy, which keeps actors active indefinitely. This change provides a flexible API for managing actor lifecycle and resource usage based on specific application needs.

passivation · high confidence

The internal memberlist package now includes a new TCP-based transport implementation (\Transport\) that replaces the previous default, allowing cluster nodes to communicate over TCP for both packet and stream operations. This transport supports optional TLS encryption via the \TransportConfig\ and handles address resolution, including automatic private IP discovery when binding to \0.0.0.0\. The change introduces new internal types like \addr\ and \messageType\ to support this networking layer, along with comprehensive tests for connection handling, port binding, and TLS configuration.

internal/memberlist · high confidence

The eventstream package has been added to provide a thread-safe event stream broker. It introduces a Stream interface and an EventsStream implementation that manages subscribers and topics using internal synchronization primitives. Users can now subscribe to topics, publish messages, and broadcast to multiple topics, with the broker handling subscriber lifecycle management and ensuring inactive subscribers are skipped during delivery. The package also includes a dedicated Message type and a benchmark suite to measure publish performance across different fan-out sizes.

eventstream · high confidence

The actor system now supports pluggable extensions and external dependencies through new interfaces defined in the extension package. The Extension interface allows custom capabilities (such as metrics or event sourcing) to be injected into the system and accessed by actors, while the Dependency interface enables actors to interact with external services like databases or APIs. Both interfaces require a unique, validated string ID and ensure serializability for distribution across cluster nodes or persistence during restarts.

extension · high confidence

The internal/future package now provides a new Future type for handling asynchronous computations, allowing callers to await a result or error via a context. The implementation has been generalized to use any for result values instead of proto.Message, enabling custom remote serialization and broader applicability beyond protobuf types.

internal/future · high confidence

The datacenter package now provides the foundational configuration and interface definitions required for multi-datacenter support. Users can configure runtime behaviors such as heartbeat intervals, cache refresh rates, and leader check frequencies via the new Config struct, which defaults to strict consistency (failing operations on stale cache data). The package also defines the ControlPlane interface, allowing providers to implement custom coordination logic for datacenter registration, heartbeating, state management, and event watching, alongside supporting types for datacenter metadata and record states.

datacenter · high confidence

The \stream\ package now provides a reactive stream processing API, allowing users to build data pipelines with sources, flows, and sinks. This includes configuration options for backpressure (buffer sizes, demand thresholds), error handling strategies (FailFast, Resume, Retry), and a Graph DSL for constructing complex topologies like fan-out, fan-in, and merges. The implementation introduces a \StreamHandle\ for lifecycle management (Stop, Abort) and observability (Metrics), along with comprehensive tests for the new functionality.

stream · high confidence

The internal command layer now supports reliable, sequenced message delivery and reentrant asynchronous requests. New command types (RegisterConsumer, RegistrationAck, Request, Ack, SequencedMessage) and their protobuf-based serializers enable a producer-consumer model with sequence tracking, chunking, and demand control. Async requests and responses are wrapped in dedicated envelopes with correlation IDs and reply targets (actor or grain), allowing replies to resolve pending asks even when the response arrives on a different turn or node. A pending-asks table manages these waits, ensuring that late replies or timeouts are handled without leaving orphaned channels.

internal/commands · high confidence

The breaker package now provides a new, thread-safe CircuitBreaker implementation that protects downstream calls by tracking success and failure rates over a rolling time window. Users can configure the breaker via functional options, including the failure rate threshold, minimum request count, open timeout, window duration, bucket count, and the maximum number of concurrent calls allowed during the half-open state. The breaker exposes a Metrics snapshot containing success/failure counts, failure rate, and timestamps, and supports a fallback function to handle errors when the circuit is open or when the protected function fails. Context cancellation is treated as non-failure, while panics are recovered and recorded as failures.

breaker · high confidence

A new \internal/timer\ package has been added, providing a \Pool\ type that manages a reusable collection of \time.Timer\ instances. This allows the system to recycle timer objects rather than allocating new ones for every timeout operation, which can reduce garbage collection pressure and improve performance in scenarios with frequent timer creation and disposal.

internal/timer · high confidence

The discovery package now exposes a formal Provider interface that defines the lifecycle methods (Initialize, Register, Deregister, DiscoverPeers, Close) and a unique ID for service discovery implementations. It also introduces a Node struct to represent discovered cluster members, including their name, host, specific ports for discovery, peers, and remoting, along with role support. A set of named constants (ProviderConsul, ProviderNATS, ProviderStatic, ProviderDNS, ProviderEtcd, ProviderSelfManaged, ProviderMDNS, ProviderKubernetes) is provided to identify these provider types, and specific error variables are defined to handle initialization, registration, and configuration states.

discovery · high confidence

The cluster engine now includes a new \BoltStore\ implementation that persists peer state to a local BoltDB file, ensuring durability across restarts. This store handles peer state lifecycle operations (persist, get, delete) with explicit synchronization to prevent read-after-write visibility issues, and supports configurable storage directories. Tests verify the store's lifecycle, idempotent closing, context cancellation handling, and error cases like missing buckets or directory creation failures.

internal/cluster · high confidence

The tls package now exposes an Info struct that encapsulates both ClientConfig and ServerConfig as tls.Config instances. This allows users to manage mutual TLS (mTLS) settings and shared root Certificate Authorities in a single, reusable structure, simplifying the setup of secure connections where both sides need to authenticate against the same CA.

tls · high confidence

Added a new \playground/issue-1301\ sample that measures the throughput of the multiplexed duplex remoting engine. This single-process benchmark adapts the standard ping/pong topology to allow tuning of parameters such as sender count, duration, lane sharding, and protocol pinning (duplex vs. legacy), providing a way to validate performance characteristics of the new remoting path.

playground/issue-1301 · high confidence

The client package now provides a new Cluster Client for remote communication with Go-Akt actor system nodes. This client supports three load-balancing strategies—Round Robin, Random, and Least Load—to distribute actor spawning and requests across the cluster. It includes built-in TLS support for secure connections and allows users to configure node weights for optimized load distribution. The client also introduces a one-way messaging mode for grain interactions, enabling fire-and-forget semantics where the caller returns immediately after the message is enqueued.

client · high confidence

This change introduces two new implementations of the datacenter control plane interface: one backed by etcd and another by NATS JetStream KeyValue. The etcd provider stores datacenter records under a configurable namespace (defaulting to /goakt/datacenters) using etcd leases for liveness and optimistic concurrency control (OCC) via revisions. The NATS provider uses a JetStream KV bucket (defaulting to goakt\_datacenters) with bucket TTL for liveness and OCC via key revisions. Both providers include configuration structs with validation and sanitization logic, and comprehensive test suites using testcontainers (for etcd) and an embedded NATS server (for NATS) to verify registration, conflict handling, and liveness behaviors.

datacenter/controlplane · high confidence

The internal/codec package has been introduced to handle serialization and deserialization of GoAkts internal protobuf messages. This new component provides specific encoders and decoders for passivation strategies (time-based, message-count-based, and long-lived), supervisor specifications (including retry policies, timeouts, and error directives), dependencies, and reentrancy configurations. By centralizing these serialization logic, the framework ensures consistent remote communication and state transfer for actors, supporting features like multi-data center replication and custom remote serialization.

internal/codec · high confidence

The internal \xsync\ package now provides three new generic, thread-safe collections: \List\, \Map\, and \TTLMap\. The \List\ is a duplicate-free, ordered collection optimized for low garbage collection overhead by reusing its backing array. The \Map\ is a standard concurrent key-value store featuring atomic \LoadAndDelete\ and \SetIfAbsent\ operations. The \TTLMap\ supports time-to-live expiration with a low-GC design that stores entries inline and evicts them lazily without background goroutines. These additions are accompanied by comprehensive test coverage for all three types.

internal/xsync · high confidence

The \internal/remoteclient\ package introduces a new client-side implementation for interacting with remote actors in a Go-Akt cluster. This client supports a multiplexed, lane-based remoting protocol (with legacy fallback) and enables reliable delivery, one-way messaging, and batched tell/ask operations. It handles transport configuration (TCP/TLS), payload compression, and serialization (including CBOR and protobuf), and provides features like peer state persistence, connection pooling, and coalesced fire-and-forget messaging to improve efficiency and reliability in distributed actor systems.

internal/remoteclient · high confidence

This change introduces two new internal packages. The \internal/retry\ package provides a \Retrier\ that executes operations with exponential backoff and jitter, configurable maximum tries, and support for terminal errors via a \Stop\ marker; it also ensures that context cancellation returns the last operation error rather than the context error. The \internal/tlstest\ package provides a \Load\ function that reads shared TLS fixture files (CA, server, and client certificates) and returns verified \tls.Config\ objects configured for mutual TLS with a minimum of TLS 1.3 and HTTP/2 support, simplifying the setup for tests requiring secure connections.

internal/retry, internal/tlstest · high confidence

The internal validation package now provides a composable validation system built around a \Validator\ interface and a \Chain\ builder. Users can construct validation pipelines using options like \FailFast\ (stop on first error) or \AllErrors\ (collect all violations), and add specific checks such as \NewBooleanValidator\ for conditional logic, \NewEmptyStringValidator\ for required fields, \NewPatternValidator\ for regex matching, and \NewIDValidator\ for alphanumeric ID constraints. A \TCPAddressValidator\ is also included to ensure host-port strings are valid. This change introduces new internal capabilities for data integrity checks rather than modifying existing product behavior.

internal/validation · high confidence

Added \scripts/test-shard.sh\ and \scripts/unit-test.sh\ to enable running the Go test suite locally in a manner consistent with the CI matrix. The new \unit-test.sh\ script orchestrates parallel test shards (actor, infra, core, memory) inside isolated Docker containers, handling cleanup of previous runs and providing progress logging, while \test-shard.sh\ defines the specific test packages and flags for each shard.

scripts · high confidence

Added a new \reentrancy\ package that introduces a \Reentrancy\ configuration struct, allowing users to control how actors handle messages while awaiting async responses. The configuration supports three modes: \Off\ (disables async requests, preserving legacy behavior), \AllowAll\ (processes all messages concurrently to improve throughput but risks state races), and \StashNonReentrant\ (stashes user messages until the async response completes to ensure strict ordering). It also includes a \WithMaxInFlight\ option to cap the number of outstanding async requests per actor instance, helping to bound memory and mailbox pressure. Tests verify default values, mode selection, and validation of invalid modes.

reentrancy · high confidence

Added a new playground example (discussion-320) that demonstrates how to use the reentrancy feature to prevent deadlocks in bidirectional actor communication. The example shows ActorA using non-blocking RequestName to call ActorB, while ActorB uses blocking Ask to request data back from ActorA, allowing ActorA to continue processing messages during the wait. Users can run this demo to see how reentrancy enables safe request/response cycles without blocking the caller.

playground/discussion-320 · high confidence

Added living samples in \playground/issue-1296\ that demonstrate point-to-point reliable delivery with effectively-once semantics. The single-node sample (\main.go\) shows an order publisher and processor using \AsReliableProducer\ and \AsReliableConsumer\ spawn options, handling the controller handshake (\RequestNext\, \Produced\, \Stored\, \StoredAck\, \Delivery\, \Confirmed\), idempotent deduplication, and operator recovery via \ReSpawn\ after a terminal failure. The cluster sample (\cluster/main.go\) extends this to a two-node GoAkt cluster, demonstrating how controllers resolve each other through the cluster registry and how sequenced messages cross the network via remoting.

playground/issue-1296 · high confidence

The remote package introduces a built-in CBOR serializer as a high-performance alternative to the existing protobuf serializer, alongside a built-in JSON serializer using the Sonic library. Users can now configure remote connections with granular control over duplex transport features, including lane-based multiplexing, credit windows, chunk sizes, and compression algorithms (Zstd, Gzip, Brotli). Additionally, the system now supports cross-node context propagation for tracing and metadata, and exposes a remote state query API allowing clients to check if remote actors are running, suspended, stopping, relocatable, or singletons.

remote · high confidence

The log package now provides a new \Logger\ interface and two concrete implementations: \Slog\, which wraps the standard library \log/slog\ package, and \Zap\, which wraps \go.uber.org/zap\. This introduces new factory functions \NewSlog\ and \NewZap\ to create loggers, as well as \NewSlogFrom\ and \NewZapFrom\ to wrap existing external logger instances. A \DiscardLogger\ is also added for no-op logging scenarios. The package defines a \Level\ type with constants for Debug, Info, Warning, Error, Fatal, and Panic, and the interface supports structured fields via \With\, context-aware logging via \\*Context\ methods, and output flushing.

log · high confidence

Added a new playground example in the issue-1031 directory that demonstrates creating and activating grains within a GoAkt cluster using NATS for discovery. The example configures an actor system with remote capabilities and shows how to instantiate grains and send messages using a custom protobuf message type, serving as a reference for the behavior changes related to grain creation and remote serialization.

playground/issue-1031 · high confidence

Added a new playground example (playground/issue-1400) that reproduces the issue where the dispatcher worker pool size is fixed to max(GOMAXPROCS, 2) and cannot be configured. The sample runs 200 independent grains with simulated I/O waits to measure throughput, comparing the default pool against a pool sized to 256 workers via the new WithDispatcherPoolSize option, thereby illustrating the performance impact of the fix.

playground/issue-1400 · high confidence

Added a new playground example in \playground/issue-1402\ that reproduces and verifies the fix for issue \#1402. The sample demonstrates how to use \WithGrainDefaultOptions\ to register specific idle timeouts for different grain kinds, ensuring that these configurations are preserved when grains are passivated and subsequently reactivated via bare sends, rather than reverting to package defaults.

playground/issue-1402 · high confidence

Added a new playground example in \playground/issue-1405\ that reproduces a scenario where a grain with a full bounded mailbox rejects the shutdown PoisonPill, preventing \OnDeactivate\ from running and causing \Stop\ to return an error. The sample demonstrates the expected behavior after the fix: the shutdown pill bypasses the mailbox capacity, allowing the grain to process pending messages, run \OnDeactivate\, and shut down cleanly even when the mailbox is full.

playground/issue-1405 · high confidence

The supervisor component introduces options to control how child actors are restarted after failures. Users can now configure a restart budget with \WithRetry\ to limit the number of consecutive restarts and define a timeout window for resetting the failure counter. Additionally, \WithExponentialBackoff\ allows setting initial, maximum, and reset delays to introduce increasing pauses between restart attempts, helping to prevent crash-loops and give failing dependencies time to recover. The default supervision strategy remains OneForOne, with panic errors defaulting to Stop and nil panics to Restart.

supervisor · high confidence

The testkit now includes utilities for testing Grains, mirroring the existing actor testing capabilities. This adds \GrainOf\ and \NodeGrainOf\ functions to retrieve or activate Grains in single-node and multi-node test environments, along with a \GrainProbe\ interface for validating Grain message handling (including \Send\, \SendSync\, and various \Expect\ assertions). The \TestKit.GrainIdentity\ method is marked as deprecated in favor of the new generic \GrainOf\ function, and tests for the new Grain-specific probes and multi-node leader election behavior have been added.

testkit · high confidence

This change introduces the v4.0.0 internal protobuf schema (package internalpb) that defines the wire format for the actor system. It establishes the serialization structures for Actor and Grain records, including support for supervisor strategies, reentrancy, reliable delivery, and passivation. It also defines the protocol for cluster operations such as peer state synchronization, rebalancing, and relocation, alongside the handshake, remoting, and CRDT replication messages required for distributed coordination.

protos/internal · high confidence

The custom \logging\ package, which provided a \Logger\ interface with methods for Info, Warning, Error, Fatal, and Panic levels along with a standard logger instance, has been removed from the codebase. This eliminates the application's internal logging implementation and its associated verbosity controls.

logging · high confidence

The \actors\ package has removed the legacy \ActorRef\ struct, the \Actor\ interface, and all associated supporting files (including \bucket.go\, \errors.go\, \messages.go\, \options.go\, and \waiter.go\). This deletion eliminates the previous actor reference model, its mailbox handling, passivation logic, and configuration options, indicating a structural shift in how actors are defined and managed within the system.

actors · high confidence

Previously, only GrainOf and GrainIdentity released the registry record of a grain owner that was stopping or had left the cluster, leaving AskGrain and TellGrain to fail or return a refusal. These methods now release the stale record themselves, allowing messages to be delivered to the grain re-activated on the calling node without requiring a retry via GrainOf. This change also introduces an internal refusal error mark to distinguish node refusals from other errors, ensuring callers are not handed refusal errors for messages that did not run.

internal/refusal, playground/issue-1435 · high confidence

The internal types package now automatically registers all standard Go primitive types (such as string, int, bool, and float variants) in the global CBOR type registry at startup. This change ensures that CRDT types storing any-typed values, like ORSet elements and LWWRegister values, can be encoded and decoded correctly without requiring explicit user registration. The update also introduces a global type registry interface and helper functions to manage type mappings for remote serialization, while excluding protobuf messages from this specific registry.

internal/types · high confidence

The \errors\ package has been extracted into its own module, consolidating all error variables (such as \ErrInvalidActorName\, \ErrRemoteSendBackpressure\, and \ErrReliableStore\) and providing typed constructors (e.g., \NewErrInvalidActorName\, \NewErrRemoteSendFailure\) that wrap underlying causes. This change standardizes error handling across the actor system, grains, and remoting layers, ensuring consistent error messages and enabling callers to reliably check for specific failure conditions like backpressure, relocation in progress, or reliable delivery store failures.

errors · high confidence

This playground sample demonstrates fixes for two defects in the runtime metrics system. First, instruments that report absolute values capable of decreasing during normal operation (such as live actor count, connected peers, child actors, stashed messages, uptime, and time since last message) have been changed from monotonic \Int64ObservableCounter\ to \Int64ObservableGauge\; this prevents exporters from misinterpreting natural decreases as counter resets. Second, the per-actor metrics callback now requests a single snapshot of all per-address deadletter counts from the deadletter actor per scrape, rather than asking for a count once per running actor, which eliminates linear mailbox flooding and ensures scrape cost remains constant regardless of actor population.

playground/issue-1322 · high confidence

This entry documents a reproduction case for issue \#1227, where cross-node grain activations in a GoAkt cluster failed with an identity validation error ('must contain only word characters'). The root cause was that the remote activation request incorrectly included the full 'kind/name' identity in the Name field, causing the receiving node to double-prefix the identity (e.g., 'kind/kind/name') during validation. The provided code demonstrates the setup of a two-node cluster using NATS discovery and shows that with the fix, grains activated via round-robin placement across nodes now succeed and maintain well-formed identities.

playground/issue-1227 · high confidence

The internal queue package now uses a Michael-Scott lock-free queue implementation instead of Go channels. This change replaces the previous channel-based mailbox mechanism with a dedicated queue type that supports multiple producers and a single consumer, aiming to improve performance and reduce overhead in internal message passing.

internal/queue · high confidence

The internal networking layer has been replaced with a new implementation featuring a thread-safe TCP client with configurable connection pooling (defaulting to 32 idle connections), pooled buffered readers to reduce allocations, and support for message chunking to handle large payloads. The new stack includes built-in compression wrappers for Brotli, Gzip, and Zstd, allowing users to reduce network bandwidth usage. This change introduces new configuration options for dial timeouts, keep-alive intervals, and maximum frame sizes, fundamentally changing how the system handles remote communication performance and reliability.

internal/net · high confidence

The remoting server now detaches its base context from the Start context using context.WithoutCancel, preventing remote operations from failing with 'context deadline exceeded' once the bounded startup context (e.g., a DI OnStart hook timeout) expires. This ensures that remote lookups and asks continue to work correctly after the initial startup phase, even if the startup context has a short deadline.

playground/issue-1252 · high confidence

The project has been reorganized to enforce stricter contribution standards and simplify the local development environment. A new AGENTS.md file establishes zero-spam and anti-AI-authorship policies, while CODING\_STANDARDS.md and CONTRIBUTING.md define the required workflow, including semantic commit formatting and mandatory local checks. The build system has migrated from Earthly to a Docker-based Makefile (Dockerfile.tools), which encapsulates tooling like golangci-lint, buf, and mockery, removing the need for local tool installation. Additionally, the repository now includes a formal Contributor License Agreement (CLA.md), a structured changelog system under changelogs/, and updated configuration files for linting (.golangci.yml), code coverage (codecov.yml), and dependency management (renovate.json5).

(repo-wide) · high confidence

This change resolves a race condition where a child actor's \Terminated\ message could be processed by its parent before the parent's own \PostStart\ lifecycle event. Because \Terminated\ is a control message delivered via a priority queue, it was draining before the user mailbox's \PostStart\, causing the user guardian to panic when handling the termination of a newly spawned actor. The fix ensures that \PostStart\ is properly delivered and handled before any subsequent lifecycle messages, preventing the actor system from crashing during rapid spawn-and-stop scenarios.

playground/issue-1422 · high confidence

Resolves a concurrency bug where replies to stashed Ask messages were silently dropped after an Unstash operation. Under concurrent load, recycled ReceiveContext objects retained a tripped 'late-reply guard' state, causing subsequent Response calls to fail silently. This fix ensures that all Ask requests receive their expected replies when using actor stashing.

playground/issue-1312 · high confidence

This change resolves a lifecycle bug where grains could be deactivated (OnDeactivate called) while still processing a message, leading to multiple grain instances running concurrently or messages being handled by a deactivated instance. The fix ensures that passivation only occurs when a grain is truly idle, preserving the guarantees of one activation at a time, one message at a time, and OnDeactivate running last.

playground/issue-1397 · high confidence

This change resolves a crash that occurred when a node stopped while its cluster events goroutine was processing a peer departure (NodeLeft). Previously, the Stop method would reset the system and clear the cluster store before the event handler finished, causing a nil pointer dereference when the handler attempted to read the cleared store. The fix ensures the system handles this race condition gracefully, preventing the process from terminating unexpectedly during rolling restarts or when loggers are slow.

playground/issue-1444 · high confidence

This change resolves a race condition in the actor system where calling \Spawn\ for an actor name immediately after \Kill\ returns could incorrectly yield the old, stopped Process ID (PID) instead of a new, running one. The issue occurred because the actor's name remained in the local registry until the death watch processed the termination message; the fix ensures the name is freed before the kill operation completes, guaranteeing that subsequent spawns receive a fresh, active actor instance.

playground/issue-1423 · high confidence

Added a reproduction test for issue \#1411 that demonstrates a fix for a remote deserialization bug. Previously, when a node sent a request using one serializer (e.g., CBOR) and received a reply using a different serializer (e.g., Protocol Buffers), the client incorrectly attempted to decode the reply using the request's serializer, causing failures. The fix ensures the client falls back to trying all registered serializers when the initial one fails, allowing cross-serializer communication between grains and actors in a cluster to work correctly.

playground/issue-1411 · high confidence

Added a self-validating reproduction case in playground/issue-1201/main.go that verifies the NewSlogFrom function correctly enforces a minimum log level. The example confirms that when a GoAkt logger is floored at WARNING, INFO records from the underlying application logger are suppressed, while WARNING and higher levels are still emitted.

playground/issue-1201 · high confidence

The MergeSubstreams operator now properly applies backpressure from the downstream consumer to the upstream source. Previously, a slow downstream could cause the stream to buffer an unbounded number of elements and drop data (especially with the default DropTail strategy). With this fix, the source is held back when the downstream is blocked, ensuring that the number of held elements remains bounded and no elements are dropped due to downstream congestion, regardless of the configured overflow strategy.

playground/issue-1434 · high confidence

When a grain on one node sends a request to a grain on another node, error sentinels (such as ErrMailboxFull) are now correctly preserved and returned to the caller, allowing applications to distinguish between backpressure and other failures using standard error checks. Additionally, expected error outcomes are no longer logged at the ERROR level, reducing log noise.

playground/issue-1409 · high confidence

When the remoting configuration uses a wildcard bind address (0.0.0.0 or ::), the server now correctly listens on every available network interface instead of binding to a single guessed private IP. This allows connections via loopback (127.0.0.1) and other interfaces, enables actor systems to start on hosts without private/public addresses, and ensures the IPv6 wildcard serves both IPv4 and IPv6 peers. The advertised address for peer discovery remains a concrete IP (first private, then public, then loopback), preserving existing routing behavior while fixing connectivity issues.

playground/issue-1374 · high confidence

The node shutdown process now tolerates scenarios where listed peers are unreachable or leaving, and where registry record removal fails due to concurrent shutdowns. Previously, \Stop\ would return errors if state replication to peers failed or if actor/grain records could not be cleaned up from the cluster registry. With this fix, \Stop\ returns nil in these cases, as the cluster is designed to handle stale records and missing peers gracefully during recovery.

playground/issue-1415 · high confidence

Add Docker Compose reproduction for cluster topology change bug; Added a regression test for passivation heap memory retention; Added cluster interface mock for testing; Added comprehensive benchmark suite for actors, grains, and clusters; Added generated test protocol buffer definitions; Added mock client for remote communication testing; Added mock implementation for discovery Provider; Added regression guard for actor heap footprint and GC cost; Added regression harness for actor relocation at scale; Added reproduction case for duplicate grain activation issue; Added reproduction case for grain lifecycle issue \#1396; Added reproduction case for node-left delay issue; Added reproduction case for non-relocatable actor registry cleanup on node crash; Added reproduction case for singleton spawn transient errors during cluster churn; Added reproduction playground for concurrent actor spawn race condition; Added reproduction sample for local grain message optimization; Added test fixtures for TLS certificate validation; Added test protocol buffer definitions for actor testing scenarios; Added unit tests for the datacenter controller; Demonstration of non-relocatable actor recovery during cluster convergence; Playground samples added for Ask timeout and context deadline fixes; Reproduction case for CRDT tombstone TTL bug (issue \#1437); Reproduction case for actor name lookup panic during shutdown; Reproduction sample for crash recovery defects in cluster nodes; Updated Hasher mock generation to use mockery v3; Updated auto-generated mocks for Extension and Dependency types.

The project has upgraded its Go version from 1.19 to 1.26.0 and performed a comprehensive update of its Go module dependencies. This includes significant version bumps for core libraries such as NATS (nats-server/v2 to v2.15.0, nats.go to v1.54.0), Redis (go-redis/v9 to v9.23.0), Kubernetes client libraries (k8s.io/\* to v0.37.1), and OpenTelemetry (otel to v1.47.0). Additionally, the module path has been updated to github.com/tochemey/goakt/v4, and new dependencies like hashicorp/mdns and Workiva/go-datastructures have been introduced.

(dependencies) · high confidence

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

• First survey — no prior run to compare against. CAI 74.

• Code Health 84
• Architecture 88
• Maturity 73
• Readiness 82
• Security 69
• Performance 80

• 300 commits — 246 feature/other, 54 fixes

• (root) — 164 commits
• .github/workflows — 19 commits
• internal/cluster — 14 commits
• actor/actor_system.go — 8 commits
• changelogs/unreleased.md — 7 commits
• docs/actor — 7 commits
• internal/net — 5 commits
• internal/remoteclient — 5 commits
• book/chapters — 4 commits
• docs/architecture — 4 commits
• docs/assets — 4 commits
• discovery/kubernetes — 3 commits
• docs/advanced — 3 commits
• actor/actor_path.go — 2 commits
• actor/actor_system_test.go — 2 commits
• docs/clustering — 2 commits
• docs/grains — 2 commits
• internal/address — 2 commits
• internal/ddata — 2 commits
• internal/internalpb — 2 commits

• fix: chore(deps): upgrade dependencies and fix broken etcd control plane test
• fix: fix(actor): :zap: fix possible memory leak on topic actor (#1215)
• fix: fix(actor): claim the actor name on first publication so concurrent spawns leave one actor (#1377) (#1384)
• fix: fix(actor): deliver reentrant Request and RequestName across nodes (#1291)
• fix: fix(actor): ensure PostStart properly delivered (#1424)
• fix: fix(actor): ensure address path are properly created and rendered (#1381)
• fix: fix(actor): fix runtime panic error on metrics (#1190)
• fix: fix(actor): fix the singleton incorrect design (#1274)
• fix: fix(actor): fixed metrics instrumentation bugs (#1325)
• fix: fix(actor): fixed spawn singleton transient errors handling (#1210)
• fix: fix(actor): free a stopped actor's name before the stop returns (#1425)
• fix: fix(actor): key registry records and local lookups by qualified actor name (#1380) (#1382)
• fix: fix(actor): prevent duplicate actors on concurrent same-name spawns (#1277)
• fix: fix(actor): release popped passivation heap entries (#1317)
• fix: fix(actor): stop crash recovery with the node and keep a rejoined node recoverable (#1427)
• fix: fix(actor): stop dropping replies to stashed Asks after unstash (#1313)
• fix: fix(grain): cross-node grain activation no longer fails identity validation (#1229)
• fix: fix(grain): fix grain lifecycle message handling issues (#1418)
• fix: fix(grain): let the shutdown PoisonPill past a full bounded mailbox (#1419)
• fix: fix(remote): listen on every interface when the bind address is a wildcard (#1375)
• …and 280 more

• 0 containers · 1 bounded contexts · 0 dependency edges (baseline)

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

Tochemey/goakt was measured the same way every project in this corpus was: the same rubric, at a pinned commit, with the result published in full. Point a surveyor at a repository you know and see whether you agree with it.