How ergo-services/ergo works
Project type and purpose
• This is a Go-based framework (library) implementing the Erlang-style actor model, network transparency, and supervision trees.
• Purpose: provide a highly concurrent, distributed, fault-tolerant runtime with ready-to-use components (actors, supervisors, network stack, meta-processes) and tooling (code generator, observer).
File structure
• Top-level modules:
• act/: core actor runtime (Actor, Pool, Supervisor strategies, WebWorker)
• node/: high-level Node orchestration (application registry, logging, networking integration)
• net/: pluggable network stack (EDF codec, handshake, protocol, registrar)
• meta/: meta-process actors for built-in services (HTTP, TCP, UDP servers, port processes)
• gen/: code-generation interfaces (Node, Application, Process, Cron, Logger, Mailbox)
• app/: example “system” application (observer backend)
• lib/: utility sub-packages (buffers, maps, OS-deps, tracing)
• testing/: unit and integration test harness and staged distributed tests
• Key config & entry points:
• ergo.go / debug.go / version.go
• go.mod / go.sum
Insights from the README
• Core features: Actor Model, Network Transparency, Observability, Supervision, Cron scheduler, Port meta-process.
• Extension points: custom loggers, cert manager, network stack interfaces.
• Tools: “ergo” CLI for code generation; “observer” for runtime inspection.
Components
a. Main components:
1. Core Actor Runtime (act/)
2. Node Manager (node/)
3. Supervisor Tree & Actors (act/supervisor + app logic)
4. Messaging Subsystem (mailbox, message passing, gen/mailbox.go)
5. Network Stack (net/edf, net/handshake, net/proto, net/registrar)
6. Meta-Processes (meta/web_server, meta/tcp_server, meta/udp_server, meta/port)
7. Utilities & Codegen (gen/, lib/)
8. Observer Application (app/system)
9. CLI Tools (ergo, observer)
10. Testing Framework (testing/)
b. Relationships & interactions:
• Node Manager instantiates Applications via gen.Node interfaces.
• Applications define Supervisor trees; Supervisors spawn and monitor Actors.
• Actors communicate via asynchronous message passing into Mailboxes.
• Node Manager registers with Registrar (net/registrar) for service discovery.
• Network Stack uses EDF codec to serialize messages over TCP/UDP transports.
• Handshake module negotiates connections between nodes.
• Meta-Processes run as Actors to provide HTTP/TCP/UDP server functionality or manage external OS processes.
• Observer Application runs over meta/web_server to expose runtime state.
• CLI Tools (ergo) use gen/ to scaffold new Node/App/Actor code.
• Testing harness uses mock nodes, in-memory network, and event capture (testing/unit).
c. Architectural patterns & principles:
• Actor Model for isolation and concurrency
• Supervision Tree for fault tolerance
• Modular networking (pluggable codecs, handshake, registrar)
• Meta-process pattern for embedding services as Actors
• Code Generation for consistency and boilerplate reduction
• Layered design: Core → Node → App → Meta → External
d. Key technologies & libraries:
• Go 1.20+
• act, node, net, meta, gen, lib internal packages
• External CLI tools: ergo.tools/ergo, ergo.tools/observer