How asynkron/protoactor-go works
Project Type and Purpose
• This is an open-source Go library implementing a distributed actor framework (“Proto Actor for Go”).
• It provides: a local actor runtime, pluggable middleware, remote messaging over gRPC/Protobuf, clustering (membership, gossip, identity lookup, pub/sub), persistence, routing, scheduling, event streams, metrics, logging, and code-generation tools.
High-Level Module/Directory Breakdown
• actor/ → Core actor runtime, message envelopes, mailbox, dispatch, lifecycle, supervision, futures, behaviors, middleware support
• remote/ → Remoting layer: gRPC server/client (EndpointManager, Activator), serializers (JSON/Proto), remote process/handler, activation, endpoint watcher/writer
• cluster/ → Clustering: membership (gossip, consensus), identity lookup/storage, pub/sub, grain management, providers (etcd, consul, k8s, zk, automanaged), cluster config/context
• persistence/ → Pluggable persistence providers (in-memory, Protobuf-CB), plugin interface, envelope transcoding, writer/receiver
• router/ → Router actors (broadcast, round-robin, consistent-hash, random), router groups/pools, router contracts
• scheduler/ → Timer service and examples
• eventstream/ → Global event bus for publications and subscriptions
• stream/ → Streaming support (typed, untyped)
• extensions/ctxext → Context extensions (propagation helpers)
• metrics/ → Metrics instrumentation for actors
• log/ → Logging middleware
• plugin/ → Actor plugins (e.g., passivation)
• protobuf/ → Codegen tool (protoc-gen-go-grain) for generating actor “grain” stubs from .proto
• internal/ → Internal queue implementations (goring, MPSC)
• examples/ → Dozens of end-to-end usage samples
Core Architectural Components
A. Actor Runtime
• Components: Props, PID, Context, Mailbox, Dispatcher, Behavior, Supervision, Futures.
• Responsibilities: local message dispatch, mailbox management, actor lifecycle, user message handling.
B. Middleware Chain
• Logging, tracing (OpenTracing propagation), protozip compression, custom propagators.
• Chained around message send/receive operations.
C. Remoting
• EndpointManager + Activator actors manage gRPC server listeners.
• EndpointWriter/Watcher handle node discovery and connection.
• Serializer interface for JSON or Protobuf.
D. Clustering
• Membership: gossip protocols, consensus checks, membership events.
• Identity lookup: distributed hash, cache, storage workers.
• Pub/Sub: topic creation, batching, delivery, producer/consumer abstractions.
• Grain activation: spawn remote actors by grain name.
E. Persistence
• PersistenceProvider interface, message encoding via Protobuf-CB.
• Plugin architecture for adding new backends.
F. Routing
• RouterActor with pluggable strategies: broadcast, round robin, consistent hash, random.
• Router groups and pools abstract over sets of routees.
G. Scheduling & Streams
• Timer service for delayed messages.
• Streaming layers for message streams (typed/untyped).
H. Supporting Services
• EventStream: publish/subscribe global events.
• Metrics: actor message counts, mailbox stats.
• Logging: structured actor logs.
• Context Extensions: propagate metadata across actors.
I. Tooling
• protoc-gen-go-grain: code generation tool plugged into protoc to scaffold actor stubs from .proto definitions.
Relationships and Interactions
• The RootContext/ActorSystem sits at the center: client code uses it to spawn actors.
• ActorRuntime core dispatches incoming messages (from local sends, remote deliveries, timers, or cluster/pubsub).
• Middleware wraps message send/receive paths.
• Remote layer and Cluster layer hook into ActorRuntime to route messages across nodes via gRPC or cluster pub/sub.
• Persistence and Plugins attach to actor lifecycles to snapshot or journal messages.
• Router, Scheduler, Stream, EventStream are specialized actor subsystems built on the core.
• Metrics and Logging subscribe to actor events/messages for instrumentation.
• Protoc-gen-go-grain runs at build time to generate message+grain glue code.
Architectural Patterns & Principles
• Actor Model for concurrency and failure isolation (supervision hierarchies).
• Pluggable middleware chain pattern.
• Micro-services style via gRPC streaming.
• Plugin architecture for persistence and codegen.
• Composition over inheritance: glue existing tech (gRPC, Protobuf).
• Event-driven message passing (local & remote).
– “Middleware Chain” (actor/middleware, logging, tracing, protozip)
– “Persistence” (persistence/)
– “Router” (router/)
– “Scheduler” (scheduler/)
– “EventStream” (eventstream/)
– “Stream” (stream/)
7. External dependencies: gRPC, Protobuf, Consul, etcd, Kubernetes API, ZooKeeper.
Final Touches
• Actor → Actor (local dispatch)
• ActorRuntime → Remote/Cluster (message export)
• Remote/Cluster → ActorRuntime (message import)
• ActorRuntime → Persistence (save/load)
• ActorRuntime → Scheduler (delayed send)
• Provide a note on supervision hierarchy (parent/child relationships inside ActorRuntime).