Skip to main content
A guided tour of the codebase. Start with actor/—everything flows from there.

​
Top-level layout

PackagePurpose
actor/Core: ActorSystem, PID, Actor interface, spawn, mailbox, supervision
remote/Remoting config, serializers, wire protocol
client/Standalone cluster client for external callers (Tell, Ask, Spawn)
discovery/Pluggable discovery providers (Consul, etcd, K8s, NATS, mDNS, DNS-SD, static)
datacenter/Multi-DC support, control plane (NATS JetStream, etcd)
supervisor/Supervision strategies and directives
passivation/Passivation strategy types
reentrancy/Reentrancy configuration for async Request/RequestName
extension/Extension (system-wide) and Dependency (per-actor) interfaces
eventstream/In-process event bus for system and cluster events
hash/Consistent hashing for partition-based placement
breaker/Circuit breaker for async outbound calls (e.g. PipeTo)
memory/Memory size helpers
tls/TLS configuration for remoting
log/Logging abstraction
errors/Sentinel errors
testkit/Testing helpers: Probe, GrainProbe, TestKit
mocks/Generated mocks
protos/Protobuf source definitions (.proto files)

​
Key files in actor/

FilePurpose
actor.goActor interface: PreStart, Receive, PostStop
actor_system.goActorSystem implementation; wires cluster, remoting, scheduling
pid.goPID—live reference to an actor; mailbox dispatch loop, metrics
receive_context.goReceiveContext passed to Receive; messaging, stash, behaviors
context.goContext passed to PreStart/PostStop
spawn.goSpawn logic for local, remote, and cross-DC actors
spawn_option.goSpawnOption: mailbox, supervisor, passivation, reentrancy, role
option.goOption for NewActorSystem
cluster_config.goCluster configuration
cluster_singleton.goCluster singleton: single instance across all nodes
mailbox.goMailbox interface
unbounded_mailbox.goDefault FIFO mailbox
bounded_mailbox.goCapacity-capped mailbox; backpressure when full
unbounded_priority_mailbox.goPriority-ordered mailbox
unbounded_fair_mailbox.goFair-scheduled mailbox; prevents starvation
unbounded_segmented_mailbox.goSegmented mailbox for throughput partitioning
grain.goGrain interface and virtual actor machinery
grain_engine.goGrain activation, routing, passivation
grain_pid.goGrainPID—PID variant for virtual actors
grain_context.goGrainContext for grain OnReceive
router.goRouter actor; fans out to routees
routing_strategy.goRound-robin, random, fan-out strategies
scheduler.goScheduled / recurring message delivery
dead_letter.goCaptures messages to stopped/non-existent actors
death_watch.goCleans up terminated actors; removes from tree and cluster
relocator.goRelocates actors/grains when a cluster node departs
remote_server.goTCP server for remoting; handles RemoteTell, RemoteSpawn, etc.
root_guardian.goRoot of the actor hierarchy
system_guardian.goParent of system actors (dead letter, relocator, etc.)
user_guardian.goParent of user-spawned actors
passivation_manager.goTracks idle actors; triggers passivation
stash.goStash buffer for deferred messages
behavior_stack.goBecome/UnBecome stack for behavior switching
reentrancy.goRequestCall, RequestOption; async request handling
reflection.goRuntime type helpers; instantiate actor/grain from type name
data_center_controller.goMulti-DC controller; registers DC with control plane
grain_activation_barrier.goBarrier for grain activation during cluster events
metric.goOpenTelemetry actor metrics
func_actor.goFuncActor—create actor from a plain function
api.goTell, Ask, BatchTell, BatchAsk (top-level API)

​
remote/

FilePurpose
remoting.goRemoting interface; RemoteTell, RemoteAsk, RemoteLookup, RemoteSpawn
config.goConfig for host, port, TLS, compression
spawn_request.goSpawnRequest for remote actor creation
compression.goMessage compression (gzip, brotli, zstd)
cbor_serializer.goCBOR serializer for non-proto messages

​
discovery/

Pluggable service discovery. Each sub-package implements discovery.Provider:
ProviderBackend
consul/HashiCorp Consul
etcd/etcd v3
kubernetes/Kubernetes API (headless services, pod labels)
nats/NATS
mdns/Multicast DNS (local network)
dnssd/DNS Service Discovery
static/Hard-coded peer list

​
datacenter/

FilePurpose
data_center.goDataCenter metadata; DataCenterRecord
config.goDatacenter configuration
control_plane.goControlPlane interface
controlplane/nats/NATS JetStream control plane
controlplane/etcd/etcd control plane

​
client/

Standalone cluster client for callers outside the actor system. See Client for full documentation.
FilePurpose
client.goClient: Tell, Ask, Spawn
balancer.goBalancer interface
round_robin.goRound-robin node selection
random.goRandom node selection
least_load.goLeast-loaded node selection

​
Internal packages

PackagePurpose
internal/address/Address type; parsing, formatting, path operations
internal/cluster/Cluster membership, Olric, actor/grain registry, peer state store
internal/remoteclient/TCP client for remoting; connection pooling, proto frames
internal/net/TCP server, client, frame protocol, compression
internal/codec/Protobuf marshal/unmarshal; encode/decode cluster types
internal/commands/Command types for lifecycle (AsyncRequest, AsyncResponse, etc.)
internal/datacentercontroller/DC controller; registers DC, heartbeats, cache refresh
internal/types/Registry interface; type name → factory for remote spawn
internal/memberlist/Hashicorp Memberlist wrapper (TLS transport)
internal/chain/Middleware-style chain execution
internal/future/Future/promise for Ask async delivery
internal/timer/Timer pool for timeouts
internal/ticker/Ticker abstraction
internal/xsync/Atomic maps, extended sync primitives
internal/validation/Fluent validation helpers
internal/pointer/Generic pointer utilities
internal/metric/OpenTelemetry metric registration
internal/chunk/Chunking utilities (e.g. for relocation allocation)
internal/slices/Slice utilities (Filter, etc.)
internal/internalpb/Generated protobuf Go code (wire types)

​
protos/

protos/
├── internal/   ← Wire types (cluster, remoting, actor, grain, datacenter)
└── test/      ← Test fixture proto messages

​
Dependency summary

PackageDepends on
actorremote, internal/cluster, discovery/*, datacenter, supervisor, passivation, reentrancy, eventstream, extension, log, errors, internal/*
remoteinternal/net, internal/codec
internal/clusterdiscovery, internal/memberlist, hash
clientremote, internal/address
log, errors, extension, eventstream, supervisor, passivation, reentrancy, hash, breaker, memory, tls are leaf packages—they depend on nothing else in this repository.

​
See also