Technologies and design patterns of Erlang/OTP have been proven over the years. Now in Golang. Up to x5 times faster than original Erlang/OTP in terms of network messaging. The easiest way to create an OTP-designed application in Golang.
The goal of this project is to leverage Erlang/OTP experience with Golang performance. Ergo Framework implements DIST protocol, ETF data format and OTP design patterns gen.Server
, gen.Supervisor
, gen.Application
which makes you able to create distributed, high performance and reliable microservice solutions having native integration with Erlang infrastructure
gen.Server
behavior support (with atomic state)gen.Supervisor
behavior support with all known restart strategies support
gen.Application
behavior support with all known starting types support
gen.Stage
behavior support (originated from Elixir's GenStage). This is abstraction built on top of gen.Server
to provide a simple way to create a distributed Producer/Consumer architecture, while automatically managing the concept of backpressure. This implementation is fully compatible with Elixir's GenStage. Example is here examples/genstage or just run go run ./examples/genstage
to see it in actiongen.Saga
behavior support. It implements Saga design pattern - a sequence of transactions that updates each service state and publishes the result (or cancels the transaction or triggers the next transaction step). gen.Saga
also provides a feature of interim results (can be used as transaction progress or as a part of pipeline processing), time deadline (to limit transaction lifespan), two-phase commit (to make distributed transaction atomic). Here is example examples/gensaga.gen.Raft
behavior support. It's improved implementation of Raft consensus algorithm. The key improvement is using quorum under the hood to manage the leader election process and make the Raft cluster more reliable. This implementation supports quorums of 3, 5, 7, 9, or 11 quorum members. Here is an example of this feature examples/raft.ServerProcess.Call
, async - ServerProcess.Cast
or Process.Send
in fashion of gen_server:call
, gen_server:cast
, erlang:send
accordinglyetf.TermIntoStruct
, etf.TermProplistIntoStruct
or to the string using etf.TermToString
Marshal
and Unmarshal
interfacesGolang introduced v2 rule a while ago to solve complicated dependency issues. We found this solution very controversial and there is still a lot of discussion around it. So, we decided to keep the old way for the versioning, but have to use the git tag with v1 as a major version (due to "v2 rule" restrictions). Since now we use git tag pattern 1.999.XYZ where X - major number, Y - minor, Z - patch version.
Here are the changes of latest release. For more details see the ChangeLog
gen.Process
:
SetCompression(enable bool)
, Compression() bool
SetCompressionLevel(level int) bool
, CompressionLevel() int
SetCompressionThreshold(threshold int) bool
, CompressionThreshold() int
messages smaller than the threshold will be sent with no compression. The default compression threshold is 1024 bytes.node.Options
:
Compression
these settings are used as defaults for the spawning processesnode.Node
new methods:
AddProxyRoute(...)
, RemoveProxyRoute(...)
ProxyRoute(...)
, ProxyRoutes()
NodesIndirect()
returns list of connected nodes via proxy connectionnode.Options
:
Proxy
for configuring proxy settingsgen.Raft
. It's improved implementation of Raft consensus algorithm. The key improvement is using quorum under the hood to manage the leader election process and make the Raft cluster more reliable. This implementation supports quorums of 3, 5, 7, 9, or 11 quorum members. Here is an example of this feature examples/raft.Resolver
to replace EPMD routines with your solution (e.g., ZooKeeper or any other service registrar)Handshake
allows customizing authorization/authentication processProto
provides the way to implement proprietary protocols (e.g., IoT area)gen.Process
new methods:
NodeUptime()
, NodeName()
, NodeStop()
gen.ServerProcess
new method:
MessageCounter()
shows how many messages have been handled by the gen.Server
callbacksgen.ProcessOptions
new option:
ProcessFallback
allows forward messages to the fallback process if the process mailbox is full. Forwarded messages are wrapped into gen.MessageFallback
struct. Related to issue #96.gen.SupervisorChildSpec
and gen.ApplicationChildSpec
got option gen.ProcessOptions
to customize options for the spawning child processes.gen.Process.Send
, gen.ServerProcess.Cast
, gen.ServerProcess.Call
now return node.ErrProcessIncarnation
if a message is sending to the remote process of the previous incarnation (remote node has been restarted). Making monitor on a remote process of the previous incarnation triggers sending gen.MessageDown
with reason incarnation
.gen.EnvKey
for the environment variablesnode.EnvKeyNode
variable to get access to the node.Node
value.node.Options
has changed. Make sure to adjust your code.Here is simple EndToEnd test demonstrates performance of messaging subsystem
Hardware: workstation with AMD Ryzen Threadripper 3970X (64) @ 3.700GHz
❯❯❯❯ go test -bench=NodeParallel -run=XXX -benchtime=10s
goos: linux
goarch: amd64
pkg: github.com/ergo-services/ergo/tests
cpu: AMD Ryzen Threadripper 3970X 32-Core Processor
BenchmarkNodeParallel-64 4738918 2532 ns/op
BenchmarkNodeParallelSingleNode-64 100000000 429.8 ns/op
PASS
ok github.com/ergo-services/ergo/tests 29.596s
these numbers show almost 500.000 sync requests per second for the network messaging via localhost and 10.000.000 sync requests per second for the local messaging (within a node).
This benchmark shows the performance of compression for sending 1MB message between two nodes (via a network).
❯❯❯❯ go test -bench=NodeCompression -run=XXX -benchtime=10s
goos: linux
goarch: amd64
pkg: github.com/ergo-services/ergo/tests
cpu: AMD Ryzen Threadripper 3970X 32-Core Processor
BenchmarkNodeCompressionDisabled1MBempty-64 2400 4957483 ns/op
BenchmarkNodeCompressionEnabled1MBempty-64 5769 2088051 ns/op
BenchmarkNodeCompressionEnabled1MBstring-64 5202 2077099 ns/op
PASS
ok github.com/ergo-services/ergo/tests 56.708s
It demonstrates more than 2 times improvement.
This benchmark demonstrates how proxy feature and e2e encryption impact a messaging performance.
❯❯❯❯ go test -bench=NodeProxy -run=XXX -benchtime=10s
goos: linux
goarch: amd64
pkg: github.com/ergo-services/ergo/tests
cpu: AMD Ryzen Threadripper 3970X 32-Core Processor
BenchmarkNodeProxy_NodeA_to_NodeC_direct_Message_1KB-64 1908477 6337 ns/op
BenchmarkNodeProxy_NodeA_to_NodeC_via_NodeB_Message_1KB-64 1700984 7062 ns/op
BenchmarkNodeProxy_NodeA_to_NodeC_via_NodeB_Message_1KB_Encrypted-64 1271125 9410 ns/op
PASS
ok github.com/ergo-services/ergo/tests 45.649s
Hardware: laptop with Intel(R) Core(TM) i5-8265U (4 cores. 8 with HT)
sources of these benchmarks are here
Ergo Framework has embedded EPMD implementation in order to run your node without external epmd process needs. By default, it works as a client with erlang' epmd daemon or others ergo's nodes either.
The one thing that makes embedded EPMD different is the behavior of handling connection hangs - if ergo' node is running as an EPMD client and lost connection, it tries either to run its own embedded EPMD service or to restore the lost connection.
It's a standard Erlang tool. Observer is a graphical tool for observing the characteristics of Erlang systems. The tool Observer displays system information, application supervisor trees, process information.
Here you can see this feature in action using one of the examples:
Code below is a simple implementation of gen.Server pattern examples/simple
package main
import (
"fmt"
"time"
"github.com/ergo-services/ergo"
"github.com/ergo-services/ergo/etf"
"github.com/ergo-services/ergo/gen"
"github.com/ergo-services/ergo/node"
)
// simple implementation of Server
type simple struct {
gen.Server
}
func (s *simple) HandleInfo(process *gen.ServerProcess, message etf.Term) gen.ServerStatus {
value := message.(int)
fmt.Printf("HandleInfo: %#v \n", message)
if value > 104 {
return gen.ServerStatusStop
}
// sending message with delay
process.SendAfter(process.Self(), value+1, time.Duration(1*time.Second))
return gen.ServerStatusOK
}
func main() {
// create a new node
node, _ := ergo.StartNode("[email protected]", "cookies", node.Options{})
// spawn a new process of gen.Server
process, _ := node.Spawn("gs1", gen.ProcessOptions{}, &simple{})
// send a message to itself
process.Send(process.Self(), 100)
// wait for the process termination.
process.Wait()
fmt.Println("exited")
node.Stop()
}
here is output of this code
$ go run ./examples/simple
HandleInfo: 100
HandleInfo: 101
HandleInfo: 102
HandleInfo: 103
HandleInfo: 104
HandleInfo: 105
exited
See examples/
for more details
Users of the Elixir Phoenix framework might encounter timeouts when trying to connect a Phoenix node to an ergo node. The reason is that, in addition to global_name_server and net_kernel, Phoenix attempts to broadcast messages to the pg2 PubSub handler
To work with Phoenix nodes, you must create and register a dedicated pg2 GenServer, and spawn it inside your node. The spawning process must have "pg2" as a process name:
type Pg2GenServer struct {
gen.Server
}
func main() {
// ...
pg2 := &Pg2GenServer{}
node1, _ := ergo.StartNode("[email protected]", "cookies", node.Options{})
process, _ := node1.Spawn("pg2", gen.ProcessOptions{}, pg2, nil)
// ...
}
There are options already defined that you might want to use
-ergo.trace
- enable extended debug info-ergo.norecover
- disable panic catching-ergo.warning
- enable/disable warnings (default: enable)To enable Golang profiler just add --tags debug
in your go run
or go build
like this:
go run --tags debug ./examples/genserver/demoGenServer.go
Now golang' profiler is available at http://localhost:9009/debug/pprof
To check test coverage:
go test -coverprofile=cover.out ./...
go tool cover -html=cover.out -o coverage.html
To run tests with cleaned test cache:
go vet
go clean -testcache
go test -v ./...
To run benchmarks:
go test -bench=Node -run=X -benchmem
is your company using Ergo? add your company logo/name here
please, visit https://ergo.services for more information