{"id":29178355,"url":"https://github.com/kolkov/voyager","last_synced_at":"2025-07-01T18:46:09.006Z","repository":{"id":301988145,"uuid":"1010075475","full_name":"kolkov/voyager","owner":"kolkov","description":"Production-grade Service Discovery for Go Microservices","archived":false,"fork":false,"pushed_at":"2025-06-30T00:45:23.000Z","size":5,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-06-30T01:32:16.613Z","etag":null,"topics":["cloud-native","distributed-systems","docker","etcd","golang","grpc","kubernetes","microservices","service-discovery"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kolkov.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-28T09:39:02.000Z","updated_at":"2025-06-30T00:45:26.000Z","dependencies_parsed_at":"2025-06-30T01:33:44.642Z","dependency_job_id":"c5b45e3f-6cbd-49f3-a2f9-8fac507945e5","html_url":"https://github.com/kolkov/voyager","commit_stats":null,"previous_names":["kolkov/voyager"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/kolkov/voyager","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kolkov%2Fvoyager","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kolkov%2Fvoyager/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kolkov%2Fvoyager/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kolkov%2Fvoyager/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kolkov","download_url":"https://codeload.github.com/kolkov/voyager/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kolkov%2Fvoyager/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262762408,"owners_count":23360320,"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":["cloud-native","distributed-systems","docker","etcd","golang","grpc","kubernetes","microservices","service-discovery"],"created_at":"2025-07-01T18:46:08.404Z","updated_at":"2025-07-01T18:46:08.984Z","avatar_url":"https://github.com/kolkov.png","language":"Go","readme":"# VoyagerSD - Service Discovery for Go Microservices\n\n[![Go Reference](https://pkg.go.dev/badge/github.com/kolkov/voyager.svg)](https://pkg.go.dev/github.com/kolkov/voyager)\n[![CI Status](https://github.com/kolkov/voyager/actions/workflows/test.yml/badge.svg)](https://github.com/kolkov/voyager/actions)\n[![Coverage Status](https://coveralls.io/repos/github/kolkov/voyager/badge.svg)](https://coveralls.io/github/kolkov/voyager)\n[![GitHub release](https://img.shields.io/github/release/kolkov/voyager.svg)](https://github.com/kolkov/voyager/releases)\n[![Beta Release](https://img.shields.io/badge/release-beta-blue)](https://github.com/kolkov/voyager/releases/tag/v1.0.0-beta)\n[![Go Report Card](https://goreportcard.com/badge/github.com/kolkov/voyager)](https://goreportcard.com/report/github.com/kolkov/voyager)\n[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](https://github.com/kolkov/voyager/blob/main/LICENSE)\n\nVoyagerSD is a production-ready service discovery solution for Go microservices with:\n\n- Dynamic service registration\n- Health checking\n- Load balancing (RoundRobin, Random, LeastConnections)\n- ETCD backend\n- Connection pooling\n- Metrics and tracing\n- Kubernetes-ready design\n\n## Features\n\n- **Automatic Service Registration**: Services register on startup\n- **Health Checks**: Periodic health verification\n- **Intelligent Caching**: Local cache for fast lookups\n- **Connection Pooling**: Reuse gRPC connections efficiently\n- **Multiple Strategies**: RoundRobin, Random, LeastConnections\n- **ETCD Integration**: Persistent storage for service data\n- **Kubernetes Ready**: Designed for container environments\n- **TLS Support**: Secure communication between services\n- **Authentication**: Token-based authentication\n- **Metrics**: Prometheus metrics integration\n- **Production-Ready CLI**: Easy deployment with `voyagerd` command\n\n## Installation\n\n```bash\ngo install github.com/kolkov/voyager/cmd/voyagerd@latest\n```\n\n## Quick Start\n\n### 1. Start Discovery Server\n\n```bash\nvoyagerd --etcd-endpoints=http://localhost:2379 --auth-token=secure-token\n```\n\n### 2. Register a Service\n\n```go\npackage main\n\nimport (\n\t\"log\"\n\t\"net\"\n\n\t\"github.com/kolkov/voyager/client\"\n\t\"google.golang.org/grpc\"\n)\n\nfunc main() {\n\t// Create Voyager client\n\tvoyager, err := client.New(\"localhost:50050\",\n\t\tclient.WithAuthToken(\"secure-token\"))\n\tif err != nil {\n\t\tlog.Fatal(err)\n\t}\n\tdefer voyager.Close()\n\n\t// Get dynamic port\n\tlistener, err := net.Listen(\"tcp\", \":0\")\n\tport := listener.Addr().(*net.TCPAddr).Port\n\n\t// Register service\n\terr = voyager.Register(\"order-service\", \"localhost\", port, map[string]string{\n\t\t\"environment\": \"production\",\n\t\t\"version\":     \"1.0.0\",\n\t})\n\tif err != nil {\n\t\tlog.Fatal(err)\n\t}\n\n\t// Start your gRPC server\n\tserver := grpc.NewServer()\n\t// ... register your service\n\tserver.Serve(listener)\n}\n```\n\n### 3. Discover and Connect to Services\n\n```go\nfunc callPaymentService(ctx context.Context, voyager *client.Client) error {\nconn, err := voyager.Discover(ctx, \"payment-service\")\nif err != nil {\nreturn err\n}\ndefer conn.Close()\n\nclient := paymentv1.NewPaymentServiceClient(conn)\n_, err = client.ProcessPayment(ctx, \u0026paymentv1.PaymentRequest{...})\nreturn err\n}\n```\n\n## Production Deployment\n\n### Docker\n\n```bash\ndocker run -d \\\n  -p 50050:50050 \\\n  -p 2112:2112 \\\n  -e VOYAGER_ETCD_ENDPOINTS=http://etcd1:2379 \\\n  -e VOYAGER_AUTH_TOKEN=your-secure-token \\\n  voyagerd:latest\n```\n\n### Kubernetes\n\n```yaml\napiVersion: apps/v1\nkind: Deployment\nmetadata:\n  name: voyager-discovery\nspec:\n  replicas: 3\n  template:\n    spec:\n      containers:\n        - name: discovery\n          image: registry.example.com/voyagerd:1.0.0\n          ports:\n            - containerPort: 50050\n              name: grpc\n            - containerPort: 2112\n              name: metrics\n          env:\n            - name: VOYAGER_ETCD_ENDPOINTS\n              value: \"etcd-cluster:2379\"\n            - name: VOYAGER_AUTH_TOKEN\n              valueFrom:\n                secretKeyRef:\n                  name: voyager-secrets\n                  key: auth-token\n```\n\n## Dependencies\n\nTo build VoyagerSD from source, you'll need:\n\n- protoc v4.22.3\n- protoc-gen-go v1.28.1\n- protoc-gen-go-grpc v1.2.0\n\nThese are required for generating gRPC code from protocol buffer definitions.\n\n## Build from Source\n\n```bash\n# Clone repository\ngit clone https://github.com/kolkov/voyager.git\ncd voyager\n\n# Install required tools (see Dependencies section)\ngo install google.golang.org/protobuf/cmd/protoc-gen-go@v1.28.1\ngo install google.golang.org/grpc/cmd/protoc-gen-go-grpc@v1.2.0\n\n# Build voyagerd server\nmake build-voyagerd\n\n# Run server\n./bin/voyagerd --etcd-endpoints=http://localhost:2379\n\n# Build Docker image\nmake docker-voyagerd\n```\n\n## Configuration Options\n\n### Server Configuration (voyagerd)\n\n| Option | Description | Default | Environment Variable |\n|--------|-------------|---------|----------------------|\n| `--etcd-endpoints` | ETCD endpoints | `http://localhost:2379` | `VOYAGER_ETCD_ENDPOINTS` |\n| `--cache-ttl` | Cache TTL | `30s` | `VOYAGER_CACHE_TTL` |\n| `--auth-token` | Authentication token | \"\" | `VOYAGER_AUTH_TOKEN` |\n| `--grpc-addr` | gRPC server address | `:50050` | `VOYAGER_GRPC_ADDR` |\n| `--metrics-addr` | Metrics HTTP address | `:2112` | `VOYAGER_METRICS_ADDR` |\n| `--log-interval` | Service logging interval | `15s` | `VOYAGER_LOG_INTERVAL` |\n| `--log-format` | Log format (text/json) | `text` | `VOYAGER_LOG_FORMAT` |\n| `--debug` | Enable debug logging | `false` | `VOYAGER_DEBUG` |\n\n### Client Options\n\n| Option | Description | Default |\n|--------|-------------|---------|\n| `WithTTL` | Cache TTL | 30s |\n| `WithInsecure` | Disable TLS | false |\n| `WithTLS` | Configure TLS | - |\n| `WithBalancerStrategy` | Load balancing strategy | RoundRobin |\n| `WithConnectionTimeout` | Connection timeout | 5s |\n| `WithRetryPolicy` | Retry policy (maxRetries, delay) | 5, 2s |\n| `WithAuthToken` | Authentication token | \"\" |\n\n## Monitoring\n\nVoyagerSD exposes Prometheus metrics:\n\n```bash\ncurl http://localhost:2112/metrics\n```\n\nAvailable metrics:\n\n| Metric | Type | Description |\n|--------|------|-------------|\n| `voyager_registrations_total` | Counter | Total service registrations |\n| `voyager_discoveries_total` | Counter | Total service discoveries |\n| `voyager_service_instances` | Gauge | Number of service instances |\n| `voyager_cache_refreshes_total` | Counter | Total cache refresh operations |\n| `voyager_cache_refresh_errors_total` | Counter | Total cache refresh errors |\n| `voyager_grpc_requests_total` | Counter | Total gRPC requests |\n| `voyager_grpc_response_time_seconds` | Histogram | gRPC response time |\n\nHealth endpoints:\n- `http://localhost:2112/health` - Liveness probe\n- `http://localhost:2112/ready` - Readiness probe\n\n## Makefile Commands\n\n```bash\nmake build              # Build all binaries\nmake build-voyagerd     # Build discovery server\nmake test               # Run unit tests\nmake lint               # Run linters\nmake docker-voyagerd    # Build Docker image\nmake run-voyagerd       # Run discovery server locally\nmake run-full           # Run full stack (server + examples)\nmake deploy-kubernetes  # Deploy to Kubernetes\nmake clean              # Clean build artifacts\n```\n\n## Security Best Practices\n\n1. **Always use TLS** for gRPC communications\n2. **Rotate authentication tokens** regularly\n3. **Use network policies** to restrict access\n4. **Run as non-root user** in containers\n5. **Limit resource usage** with Kubernetes resource quotas\n\n```go\n// Secure client configuration\nvoyager, err := client.New(\"discovery:50050\",\n    client.WithTLSConfig(\u0026tls.Config{\n        // Your TLS configuration\n    }),\n    client.WithAuthToken(\"secure-token\"))\n```\n\n## Getting Help\n\nFor usage questions, bug reports, or feature requests:\n\n- [File a GitHub issue](https://github.com/kolkov/voyager/issues)\n- Join our [Discord community](https://discord.gg/your-invite-link)\n\n## Contributing\n\nWe welcome contributions! Please follow these steps:\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/your-feature`)\n3. Commit your changes (`git commit -am 'Add some feature'`)\n4. Push to the branch (`git push origin feature/your-feature`)\n5. Submit a pull request\n\nBefore submitting, please ensure:\n- All tests pass\n- Code is properly formatted\n- New features include tests\n- Documentation is updated\n\n## License\n\nApache 2.0 - See [LICENSE](LICENSE) for details\n\n---\n\nVoyagerSD is developed and maintained by the Kolkov team with ❤️.  \nSpecial thanks to all our contributors!","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkolkov%2Fvoyager","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkolkov%2Fvoyager","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkolkov%2Fvoyager/lists"}