The Ergo Framework is an implementation of ideas, technologies, and design patterns from the Erlang world in the Go programming language. It is based on the actor model, network transparency, and a set of ready-to-use components for development. This significantly simplifies the creation of complex and distributed solutions while maintaining a high level of reliability and performance.

Features

1. Actor Model: enables the creation of scalable and fault-tolerant systems using isolated actors that interact through message passing. Actors can exchange asynchronous messages as well as perform synchronous requests, offering flexibility in communication patterns.

2. Network Transparency: actors can interact regardless of their physical location, supported by a high-performance implementation of the network stack, which simplifies the creation of distributed systems.

3. Observability: framework includes built-in observability features, including service discovery and static routes, allowing nodes to automatically register themselves and find routes to remote nodes. This mechanism simplifies managing distributed systems by enabling seamless communication and interaction between nodes across the network.

4. Ready-to-use Components: A set of ready-to-use actors simplifying development, including state management and error handling.

5. Support for Distributed Systems: framework includes built-in mechanisms for creating and managing clustered systems, distributed events (publish/subscribe mechanism), remote actor spawning, and remote application startup. These features enable easy scaling, efficient message broadcasting across your cluster, and the ability to manage distributed components seamlessly.

6. Reliability and Fault Tolerance: the framework is designed to minimize failures and ensure automatic recovery, featuring a supervisor tree structure to manage and restart failed actors, which is crucial for mission-critical applications.

7. Flexibility: This framework offers convenient interfaces for customizing network stack components, creating and integrating custom loggers, managing SSL certificates, and more.

In the https://github.com/ergo-services/examples repository, you will find examples that demonstrate a range of the framework's capabilities.

Benchmarks

On a 64-core processor, Ergo Framework demonstrates a performance of over 21 million messages per second locally and nearly 5 million messages per second over the network.

You can find available benchmarks in the following repository https://github.com/ergo-services/benchmarks.

• Messaging performance (local, network)

• Memory consumption per process (demonstrates framework memory footprint).

Observer

To inspect the node, network stack, running applications, and processes, you can use the observer tool

To install the Observer tool, you need to have the Go compiler version 1.20 or higher. Run the following command:

$ go install ergo.tools/observer@latest

You can also embed the Observer application into your node. To see it in action, see example demo at https://github.com/ergo-services/examples. For more information https://docs.ergo.services/tools/observer

Quick start

For a quick start, use the ergo tool — a command-line utility designed to simplify the process of generating boilerplate code for your project based on the Ergo Framework. With this tool, you can rapidly create a complete project structure, including applications, actors, supervisors, network components, and more. It offers a set of arguments that allow you to customize the project according to specific requirements, ensuring it is ready for immediate development.

To install use the following command:

$ go install ergo.tools/ergo@latest

Now, you can create your project with just one command. Here is example:

Supervision tree

  mynode
  ├─ myapp
  │  │
  │  └─ mysup
  │     │
  │     └─ myactor
  ├─ myweb
  └─ myactor2

To generate project for this design use the following command:

$ ergo -init MyNode \
      -with-app MyApp \
      -with-sup MyApp:MySup \
      -with-actor MySup:MyActor \
      -with-web MyWeb \
      -with-actor MyActor2 \
      -with-observer 

as a result you will get generated project:

  mynode
  ├── apps
  │  └── myapp
  │     ├── myactor.go
  │     ├── myapp.go
  │     └── mysup.go
  ├── cmd
  │  ├── myactor2.go
  │  ├── mynode.go
  │  ├── myweb.go
  │  └── myweb_worker.go
  ├── go.mod
  ├── go.sum
  └── README.md

to try it:

$ cd mynode
$ go run ./cmd

Since we included Observer application, open http://localhost:9911 to inspect your node and running processes.

Erlang support

Starting from version 3.0.0, support for the Erlang network stack has been moved to a separate module - https://github.com/ergo-services/proto. Version 3.0 was distributed under the BSL 1.1 license, but starting from version 3.1 it is available under the MIT license. You can find detailed information on using this module in the documentation at https://docs.ergo.services/extra-library/network-protocols/erlang.

Requirements

• Go 1.20.x and above

Changelog

Fully detailed changelog see in the ChangeLog file.

v3.1.0 2025-09-04 [tag version v1.999.310]

New Features

• Cron Scheduler: New gen.Cron interface enables scheduling tasks with cron expressions, supporting second-level precision for precise task execution. See https://docs.ergo.services/basics/cron
• Port Meta Process: New meta.Port allows spawning and managing external OS processes with bidirectional communication through stdin/stdout/stderr. See https://docs.ergo.services/meta-processes/port, example https://github.com/ergo-services/examples/port
• Unit Testing Framework: Comprehensive testing library (testing/unit) provides isolated actor testing with event capture and validation capabilities. See https://docs.ergo.services/testing/unit

Enhancements

• Enhanced Logging: Default logger now supports JSON output format with structured fields, improving observability and log processing
• Environment Management: Added gen.Process.EnvDefault() and gen.Node.EnvDefault() methods
• Logger Fields: Added gen.Log.PushFields() and gen.Log.PopFields() for contextual logging
• EDF Protocol: Added support for encoding.BinaryMarshaler/BinaryUnmarshaler interfaces
• Performance: Multiple optimizations across message handling and network operations

Critical Bug Fixes

• Node Shutdown: Fixed race condition causing "close of closed channel" panic during graceful shutdown
• Supervisor Issues: Fixed OFO supervisor child termination (#213), restart intensity calculation with millisecond precision, and duplicate Terminate callbacks
• SIGTERM Handling: Improved graceful shutdown behavior and SOFO supervisor cleanup
• EDF Codec: Fixed nil slice/map decoding issues
• Local Registrar: Improved resolver detection for service discovery

Extra Library

• Module Independence: All extra library modules (Logger, Meta, Registrar, etc...) are now independent Go modules with dependency management
• Tools Domain: All tools moved to dedicated ergo.tools domain for better organization and distribution
• Proto: erlang23 (Erlang network stack implementation) changed from BSL 1.1 to MIT license for broader adoption and commercial use
• Registrar: New etcd registrar implementation with distributed service discovery, hierarchical configuration, real-time cluster events. See https://docs.ergo.services/extra-library/registrars/etcd-client and example https://github.com/ergo-services/examples/docker
• Logger: Added LogField support in colored logger, banner functionality, and fixed options handling. See https://docs.ergo.services/extra-library/loggers
• Application: Observer application enhanced with new Applications page, Cron job details, and UI fixes. See https://docs.ergo.services/extra-library/applications/observer
• Benchmarks: New serialization benchmarks comparing EDF vs Gob vs Protobuf performance, expanded test suite coverage. See https://github.com/ergo-services/benchmarks

Development and debugging

To enable Golang profiler just add --tags debug in your go run or go build (profiler runs at http://localhost:9009/debug/pprof)

To disable panic recovery use --tags norecover.

To enable trace logging level for the internals (node, network,...) use --tags trace and set the log level gen.LogLevelTrace for your node.

To run tests with cleaned test cache:

go vet
go clean -testcache
go test -v ./testing/tests/...

Commercial support

please, contact [email protected] for more information