https://github.com/ifimust/srsr
Really Simple Service Registry
https://github.com/ifimust/srsr
gin go golang microservices slsa
Last synced: about 1 month ago
JSON representation
Really Simple Service Registry
- Host: GitHub
- URL: https://github.com/ifimust/srsr
- Owner: ifIMust
- License: mit
- Created: 2024-07-11T16:55:02.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2024-08-10T05:14:51.000Z (over 1 year ago)
- Last Synced: 2025-02-26T03:34:16.174Z (about 1 year ago)
- Topics: gin, go, golang, microservices, slsa
- Language: Go
- Homepage:
- Size: 6.31 MB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# srsr
Really Simple Service Registry
## Overview
srsr is a lightweight service discovery system that helps microservices find each other. Services register themselves with the registry and can lookup other services by name. When multiple services share the same name, basic load balancing randomly selects one.
**When to Use:**
- Microservices that need to discover each other dynamically
- Development/testing environments where service locations change
- Simple deployments that don't need complex service mesh features
- Applications prioritizing minimal setup over advanced features
**Key Features:**
- HTTP-based JSON API built with [Gin](https://gin-gonic.com/)
- Automatic service cleanup via heartbeat mechanism (30s timeout, 20s client interval)
- Cross-platform server binaries with automated GitHub releases
- Go and Python client libraries with consistent APIs
- Minimal configuration - designed for simplicity over features
## Quick Start
### Running the Server
Download a precompiled binary for your platform from the [releases page](https://github.com/ifIMust/srsr/releases):
```bash
chmod +x ./srsr-linux-amd64
./srsr-linux-amd64 [-p PORT] [-t TIMEOUT_SECONDS]
```
The server maintains an in-memory registry (not persistent between restarts) and listens on port 4214 by default.
### Using Clients
Client libraries handle registration, heartbeats, and cleanup automatically. Simply register when your service starts and deregister on shutdown.
**Python Client:** [srsrpy](https://github.com/ifIMust/srsrpy)
**Go Client:** Available in the `client` package ([documentation](client/README.md))
#### Go Example
```go
import "github.com/ifIMust/srsr/client"
// Register service "my-service" at localhost:3000 with registry at localhost:4214
client := client.NewServiceRegistryClient("my-service", "http://localhost:3000", "http://localhost:4214")
client.Register()
defer client.Deregister()
```
## API Reference
The registry exposes a simple REST API. All endpoints accept JSON POST requests.
| Endpoint | Purpose | Required Fields |
|----------|---------|----------------|
| `/register` | Register a service | `name`, `address` or `port` |
| `/deregister` | Remove a service | `id` |
| `/lookup` | Find a service | `name` |
| `/heartbeat` | Keep registration alive | `id` |
### Detailed API Documentation
### /register
Register a service. The client should do this once at startup, and store the returned ID for later use.
Example request:
```
{"name": "flard_service", "address": "321.123.321.123:4321"}
```
Response:
```
{"success": true, "id": "1ccda9cb-0432-4306-965d-6e0fbad571bc"}
```
The client may specify a port in the address string. If the client service cannot easily determine their binding address, they may specify the port only. The server will attempt to deduce the address.
```
{"name": "flard_service", "port": "1234"}
```
If neither address nor port are specified, the service is registered at `http://localhost`, which might not be correct.
### /deregister
Deregister a service. The client should do this once at shutdown, using the ID stored from registration.
Example request:
```
{"id": "1ccda9cb-0432-4306-965d-6e0fbad571bc"}
```
Response:
```
{"success": "true"}
```
### /lookup
Retrieve an address for a service.
Example request:
```
{"name": "flard_service"}
```
Response examples:
```
{"success": "true", "address": "321.123.321.123:4321"}
{"success": "false", "address": ""}
```
### /heartbeat
Inform the service registry that the client is still up, to avoid automatic deregistration.
Example request:
```
{"id": "1ccda9cb-0432-4306-965d-6e0fbad571bc"}
```
Response:
```
{"success": "true"}
```
## Development
### Releasing
1. Create a new release on GitHub with a version tag (e.g., `v1.0.0`)
2. GitHub Actions automatically builds binaries for all platforms: `linux-amd64`, `linux-arm64`, `darwin-amd64`, `darwin-arm64`, `windows-amd64.exe`, `windows-arm64.exe`
### Testing
#### Unit Tests
```bash
# Run unit tests (default, excludes integration tests)
go test ./...
```
#### Integration Tests
Integration tests validate end-to-end functionality using real servers and clients. See [integration/README.md](integration/README.md) for detailed documentation.
```bash
# Run integration tests
go test -tags=integration ./integration/... -v
# Run all tests (unit + integration)
go test -tags=integration ./... -v
```
### Project Goals
- **Simplicity**: Easy setup and minimal configuration
- **Cross-platform**: Consistent APIs across Go and Python clients
- **Reliability**: Automatic service cleanup via heartbeat mechanism
## Current Limitations & Roadmap
### Configuration Burden
Currently, services must explicitly configure:
- Registry server location (`http://localhost:4214`)
- Their own service address (`http://localhost:3000`)
This creates a double configuration burden, especially for local development and simple deployments.
### Zero-Configuration Vision
The project is moving toward minimal configuration requirements:
**Phase 1: Auto-Detection** (Planned)
- Registry discovery via environment variables and sensible defaults
- Enhanced service address auto-detection from port-only registration
- Improved IP detection for containerized environments
**Phase 2: Local Optimizations** (Future)
- Unix domain socket transport for same-machine services
- Local network discovery (mDNS/multicast) for development
- Container networking auto-detection
**Phase 3: In-Process Integration** (Future)
- Optional in-process registry for testing and simple deployments
- Direct function calls instead of HTTP for same-process services
### Deployment Pattern Support
The architecture aims to support:
- **Distributed microservices**: Full HTTP-based service discovery
- **Local development**: Minimal setup with auto-detected addresses
- **Testing environments**: In-process registry option
- **Simple deployments**: Script-driven with environment-based configuration
## Current Status
- ✅ Basic HTTP service registry with heartbeat mechanism
- ✅ Go and Python clients with consistent APIs
- ✅ Port-only registration (server-side implemented, Go client pending)
- ✅ Comprehensive test suites for both clients
- 🔄 Auto-detection and zero-config improvements (in progress)