GoVerse

GoVerse is a distributed object runtime for Go, inspired by Orleans.
It provides virtual actors, automatic placement, lifecycle management, and streaming RPCs.
Designed for building fault-tolerant backend services and large-scale real-time systems.

v0.1.0 — first tagged release. Core concepts (objects, nodes, gates) are settled and basic failure modes are handled. APIs may still change before v1.0. Production use is at your own risk; see CHANGELOG.md for known issues.

---

Key Features

• Virtual objects with automatic lifecycle & activation

• Exactly-once call semantics for reliable inter-object communication

• Sharded placement using etcd with dynamic object & shard rebalancing across nodes

• Gate architecture with streaming gRPC and HTTP REST API

• Automatic failover & fault recovery

• PostgreSQL persistence with JSONB storage

• Built-in Prometheus metrics and pprof profiling

• Inspector UI for visualizing object topology (demo video)

  

  Click above to watch the cluster bootstrap demonstration visualized by GoVerse Inspector

---

Why GoVerse?

• Exactly-once semantics: Reliable calls ensure each operation executes once, even with failures or retries
• High-level programming model without giving up Go's performance
• Scales horizontally with minimal coordination
• Built for trading infra, backend automation, and real-time apps

---

Quick Start

GoVerse uses a Node + Gate architecture:

• Node hosts distributed objects and handles object lifecycle
• Gate accepts client connections (gRPC and HTTP) and routes calls to nodes

1. Define a Distributed Object

// counter.go
type Counter struct {
    goverseapi.BaseObject
    value atomic.Int32
}

// Object methods use protobuf types for HTTP/gRPC compatibility
func (c *Counter) Add(ctx context.Context, req *wrapperspb.Int32Value) (*wrapperspb.Int32Value, error) {
    newValue := c.value.Add(req.GetValue())
    return &wrapperspb.Int32Value{Value: newValue}, nil
}

2. Start a Node (Object Server)

// node/main.go
func main() {
    config := &goverseapi.ServerConfig{
        ListenAddress:    "localhost:47000",
        AdvertiseAddress: "localhost:47000",
    }
    server, err := goverseapi.NewServerWithConfig(config)
    if err != nil {
        log.Fatalf("Failed to create server: %v", err)
    }
    goverseapi.RegisterObjectType((*Counter)(nil))
    
    // Create Counter object when cluster is ready
    go func() {
        <-goverseapi.ClusterReady()
        _, err := goverseapi.CreateObject(context.Background(), "Counter", "my-counter")
        if err != nil {
            log.Printf("Failed to create counter: %v", err)
        }
    }()
    
    server.Run(context.Background())
}

3. Start a Gate (Client-Facing Server)

# Start the gate with HTTP API enabled
go run ./cmd/gate/ -http-listen=:8080

4. Access via HTTP

Once the node creates the my-counter object, you can call its methods via the gate's HTTP API:

# Call object method (increment by 5)
# The request body is a base64-encoded protobuf Any containing Int32Value{Value: 5}
curl -X POST http://localhost:8080/api/v1/objects/call/Counter/my-counter/Add \
  -H "Content-Type: application/json" \
  -d '{"request":"Ci50eXBlLmdvb2dsZWFwaXMuY29tL2dvb2dsZS5wcm90b2J1Zi5JbnQzMlZhbHVlEgIIBQ=="}'

See HTTP_GATE.md for details on encoding protobuf messages and the httpgate example for a helper to generate these values.

---

Installation

go get github.com/xiaonanln/goverse

---

Command-Line Tools

GoVerse includes several command-line tools for cluster management:

• pgadmin - PostgreSQL database management (init schema, verify connection, etc.)

  go run ./cmd/pgadmin --config config.yml init

  See cmd/pgadmin/README.md for details

• gate - Start a gate server for client connections

  go run ./cmd/gate --config config.yml --gate-id gate-1

• inspector - Start the cluster visualization web UI

  go run ./cmd/inspector

  See docs/INSPECTOR.md for details

• configgen - Generate configuration files for clusters

  go run ./cmd/configgen --nodes 3 --gates 2 config.yml

---

Documentation

Full documentation:

• Getting Started - Complete guide to building with GoVerse
• GoVerse API - API reference for the goverseapi package
• Reliable Calls - Exactly-once semantics for inter-object calls
• Object Model & Architecture - Understanding virtual actors
• Cluster Configuration - YAML config and cluster settings
• Kubernetes Deployment - Deploy Goverse on Kubernetes
• Object Persistence - PostgreSQL integration
• PostgreSQL Setup - Database setup and configuration
• Push Messaging - Real-time server-to-client delivery
• HTTP Gate API - REST/HTTP endpoints for clients
• Object Access Control - Access rules and security
• Prometheus Metrics - Monitoring & observability
• pprof Profiling - Performance profiling and debugging
• Inspector UI - Cluster visualization
• Proto Reference - Protocol buffer definitions

---

Samples

Sample	Description
Counter	Simple counter service demonstrating basic Goverse object operations
Tic Tac Toe	Web-based game demonstrating HTTP Gate with REST API
Chat	Distributed chat application with real-time push messaging and web client
Sharding Demo	Comprehensive demo showcasing sharding, auto-load objects, and distributed object management

---

Status & Roadmap

Current status: v0.1.0 — first tagged release. See CHANGELOG.md for what's in and docs/MILESTONE_V0.1.0.md for the release criteria.

Near-term goals (v0.2.0): access control and auth, TLS/mTLS, graceful shutdown mode, observability improvements.

See Getting Started for the end-to-end tutorial and contribution guidelines.

---

TODO

High-level objectives for future development:

Core System Improvements

• Shard rebalancing based on actual node load - Dynamic rebalancing that considers CPU, memory, and object count
• Configuration hot reload - Support runtime configuration updates without cluster restart for access control, lifecycle rules, and other policies

Gate & Client Features

• Gate authorization mechanism - Fine-grained access control and authentication for client connections
• Gate rate limiting - Per-client and per-object throttling to prevent abuse
• Client reconnection & backoff - Automatic retry logic with exponential backoff

Performance & Scalability

• Runtime shard count reconfiguration - Allow dynamic shard count changes without cluster restart

Observability & Operations

• Enhanced metrics & alerting - More granular Prometheus metrics, SLO tracking
• Inspector UI enhancements - Real-time object visualization, shard distribution graphs, and cluster health dashboard

---

License

Apache-2.0 License