{"id":27462125,"url":"https://github.com/solviumdream/gorilix","last_synced_at":"2025-04-15T21:47:23.819Z","repository":{"id":287618960,"uuid":"965283753","full_name":"solviumdream/gorilix","owner":"solviumdream","description":"A lightweight, fault-tolerant actor model framework for Go. Inspired by Erlang/OTP, Gorilix enables seamless scalability and robust error recovery in distributed systems. Build resilient, concurrent applications with ease.","archived":false,"fork":false,"pushed_at":"2025-04-12T21:16:34.000Z","size":72,"stargazers_count":7,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-15T21:47:09.857Z","etag":null,"topics":["actor-model","concurrent","distributed-systems","erlang","erlang-otp","fault-tolerance","go","golang","gorilix","resilient"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/solviumdream.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-04-12T20:17:15.000Z","updated_at":"2025-04-15T05:22:31.000Z","dependencies_parsed_at":"2025-04-12T21:42:18.132Z","dependency_job_id":null,"html_url":"https://github.com/solviumdream/gorilix","commit_stats":null,"previous_names":["kleeedolinux/gorilix","solviumdream/gorilix"],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/solviumdream%2Fgorilix","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/solviumdream%2Fgorilix/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/solviumdream%2Fgorilix/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/solviumdream%2Fgorilix/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/solviumdream","download_url":"https://codeload.github.com/solviumdream/gorilix/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249161084,"owners_count":21222465,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["actor-model","concurrent","distributed-systems","erlang","erlang-otp","fault-tolerance","go","golang","gorilix","resilient"],"created_at":"2025-04-15T21:47:23.087Z","updated_at":"2025-04-15T21:47:23.812Z","avatar_url":"https://github.com/solviumdream.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Gorilix\n\n[![Go Reference](https://pkg.go.dev/badge/github.com/kleeedolinux/gorilix.svg)](https://pkg.go.dev/github.com/kleeedolinux/gorilix)\n\nGorilix is a fault-tolerant actor model framework for Go, inspired by the principles behind Erlang and Elixir. It was born out of the need to create systems that are not only resilient but also capable of scaling seamlessly, even in asynchronous and distributed environments.\n\n## Why Gorilix?\n\nAs someone who’s passionate about Go, I wanted to bring the power of the actor model to my favorite stack. The actor model has long been a go-to solution for building robust distributed systems, and frameworks like Erlang and Elixir have shown just how effective it can be for fault tolerance and system reliability. By implementing the actor model in Go, Gorilix aims to offer developers the same reliability and scalability in their Go applications.\n\nThe idea was simple: create a lightweight system where actors (essentially independent units of computation) could communicate via message passing, much like Erlang's approach, but tailored for Go’s concurrency model. This allows for building systems that can recover gracefully from failures while maintaining smooth operation at scale.\n\n## Key Features\n\n- **Actor-based concurrency** - Develop systems using isolated actors that communicate via message passing, enabling easy parallelism and isolation.\n- **Supervisors** - Manage actor lifecycles with customizable supervision strategies to ensure system reliability.\n- **Fault tolerance** - Build systems that automatically recover from failures with adjustable policies.\n- **Circuit breakers** - Prevent cascading failures in distributed environments by automatically halting malfunctioning components.\n- **Backoff strategies** - Control how retries happen in case of failures with linear, exponential, or jittered backoff strategies.\n- **Cluster support** - Build distributed systems across multiple nodes using the gossip protocol for automatic cluster membership and management.\n- **Efficient message serialization** - Protocol Buffers support for efficient and type-safe message serialization in distributed environments.\n\n## Installation\n\n```bash\ngo get github.com/kleeedolinux/gorilix\n```\n\n## Quick Start\n\n```go\npackage main\n\nimport (\n    \"context\"\n    \"fmt\"\n    \"log\"\n    \"time\"\n\n    \"github.com/kleeedolinux/gorilix/actor\"\n    \"github.com/kleeedolinux/gorilix/supervisor\"\n)\n\n// Define an actor\ntype GreeterActor struct {\n    *actor.DefaultActor\n}\n\nfunc NewGreeterActor(id string) *GreeterActor {\n    g := \u0026GreeterActor{}\n    g.DefaultActor = actor.NewActor(id, g.processMessage, 100)\n    return g\n}\n\nfunc (g *GreeterActor) processMessage(ctx context.Context, msg interface{}) error {\n    if name, ok := msg.(string); ok {\n        fmt.Printf(\"Hello, %s!\\n\", name)\n    }\n    return nil\n}\n\nfunc main() {\n    // Create a simple strategy\n    strategy := supervisor.NewStrategy(supervisor.OneForOne, 3, 5)\n    \n    // Create a supervisor\n    sup := supervisor.NewSupervisor(\"root\", strategy)\n    \n    // Add a child actor\n    childSpec := supervisor.ChildSpec{\n        ID: \"greeter\",\n        CreateFunc: func() (actor.Actor, error) {\n            return NewGreeterActor(\"greeter\"), nil\n        },\n        RestartType: supervisor.Permanent,\n    }\n    \n    greeterRef, _ := sup.AddChild(childSpec)\n    \n    // Send a message to the actor\n    greeterRef.Send(context.Background(), \"World\")\n    \n    // Wait a moment to see the output\n    time.Sleep(time.Second)\n}\n```\n\n## Core Concepts\n\n### Actors\n\nActors are the building blocks of a Gorilix application. Each actor:\n- Has its own state, completely isolated from other actors\n- Processes messages one at a time\n- Can create other actors\n- Can send messages to other actors\n\n### Supervisors\n\nSupervisors monitor actors and decide how to handle failures based on predefined strategies.\n\n### Supervision Strategies\n\n- **OneForOne** - When a child fails, only that child is restarted\n- **OneForAll** - When a child fails, all children are restarted\n- **RestForOne** - When a child fails, that child and all children started after it are restarted\n\n### Fault Tolerance\n\nGorilix is designed to handle faults gracefully:\n\n- **Retry with backoff** - Automatically retries failed operations with configurable backoff\n- **Circuit breakers** - Stop operation attempts when a system component is failing, avoiding cascading issues\n- **Failure isolation** - Contain failures to prevent them from affecting the rest of the system\n\n## Advanced Features\n\n### Circuit Breakers\n\nCircuit breakers prevent cascading failures by halting operations when a system component is failing.\n\n```go\noptions := supervisor.StrategyOptions{\n    CircuitBreakerOptions: \u0026supervisor.CircuitBreakerOptions{\n        Enabled:          true,\n        TripThreshold:    5,                // Open after 5 failures\n        FailureWindow:    30 * time.Second, // Count failures in a 30s window\n        ResetTimeout:     5 * time.Second,  // After 5s, try again\n        SuccessThreshold: 2,                // Close after 2 consecutive successes\n    },\n}\n```\n\n### Backoff Strategies\n\nControl retry timing with various backoff strategies:\n\n- **NoBackoff** - No delay between retries\n- **LinearBackoff** - Delay increases linearly with each retry\n- **ExponentialBackoff** - Delay doubles with each retry\n- **JitteredExponentialBackoff** - Exponential backoff with random jitter to prevent overloading systems\n\n```go\noptions := supervisor.StrategyOptions{\n    BackoffType:  supervisor.JitteredExponentialBackoff,\n    BaseBackoff:  100 * time.Millisecond,\n    MaxBackoff:   10 * time.Second,\n    JitterFactor: 0.2,\n}\n```\n\n### Cluster Support\n\nGorilix provides cluster support through the Hashicorp Memberlist library, enabling auto-discovery and management of nodes in a distributed environment:\n\n```go\npackage main\n\nimport (\n    \"context\"\n    \"fmt\"\n    \"log\"\n    \"time\"\n\n    \"github.com/kleeedolinux/gorilix/cluster/bridge\"\n    \"github.com/kleeedolinux/gorilix/system\"\n)\n\nfunc main() {\n    // Create the actor system with a name\n    actorSystem := system.NewActorSystem(\"node1\")\n\n    // Enable clustering with a bridge provider\n    actorSystem.SetClusterProvider(bridge.NewClusterProvider())\n    \n    // Configure and enable clustering\n    clusterConfig := \u0026system.ClusterConfig{\n        NodeName: \"node1\",\n        BindAddr: \"0.0.0.0\",\n        BindPort: 7946,\n        Seeds:    []string{\"othernode:7946\"}, // Optional list of seed nodes\n    }\n    \n    err := actorSystem.EnableClustering(clusterConfig)\n    if err != nil {\n        log.Fatalf(\"Failed to enable clustering: %v\", err)\n    }\n    \n    // Get the cluster instance\n    clusterInstance, _ := actorSystem.GetCluster()\n    \n    // Print cluster members\n    members := clusterInstance.Members()\n    for _, member := range members {\n        fmt.Printf(\"Node: %s at %s:%d\\n\", \n            member.GetName(), member.GetAddress(), member.GetPort())\n    }\n    \n    // Rest of the application...\n}\n```\n\n### Protocol Buffer Serialization\n\nGorilix supports efficient message serialization using Google Protocol Buffers, making it ideal for distributed systems:\n\n1. Define your messages in `.proto` files:\n\n```protobuf\nsyntax = \"proto3\";\npackage myapp;\n\nmessage UserMessage {\n    string user_id = 1;\n    string content = 2;\n    int64 timestamp = 3;\n}\n```\n\n2. Generate Go code with the protoc compiler:\n\n```bash\nprotoc --go_out=. myapp.proto\n```\n\n3. Use the serialization functions in your application:\n\n```go\nimport (\n    \"github.com/kleeedolinux/gorilix/cluster\"\n    pb \"myapp/proto\"\n)\n\n// Create a protobuf message\nuserMsg := \u0026pb.UserMessage{\n    UserId:    \"user123\",\n    Content:   \"Hello from the distributed system!\",\n    Timestamp: time.Now().Unix(),\n}\n\n// Serialize for transmission between nodes\nserialized, err := cluster.SerializeMessage(userMsg)\nif err != nil {\n    log.Fatalf(\"Failed to serialize: %v\", err)\n}\n\n// Send to another node\nclusterInstance.SendToNode(\"other-node\", serialized)\n```\n\n## Documentation\n\nFor more detailed information, check out the following guides:\n- [Fault Tolerance Guide](docs/fault_tolerance.md)\n- [Clustering Guide](docs/clustering.md)\n- [Message Serialization Guide](docs/serialization.md)\n\n## Examples\n\nFeel free to explore the `examples/` directory for more usage examples.\n\n## License\n\nThis project is licensed under the terms of the license included in the repository.\n\n## Contributing\n\nContributions are always welcome! Please feel free to submit a Pull Request.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsolviumdream%2Fgorilix","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsolviumdream%2Fgorilix","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsolviumdream%2Fgorilix/lists"}