discovery

package module
v0.2.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 21, 2026 License: MIT Imports: 7 Imported by: 0

README

Etcd Service Discovery for Go

Go Report Card Go Reference

A robust and easy-to-use Go library for service registration and discovery using etcd v3.

This library provides a clean, flexible, and resilient way to manage microservice lifecycle and discovery within an etcd cluster.

Features

  • Clean API: Uses the Functional Options Pattern for clear and extensible configuration.
  • Automatic Keep-Alive: Automatically manages service liveness using etcd's lease and keep-alive features.
  • Robust Lifecycle Management: Clear separation of Register, Deregister, and Close methods for predictable behavior.
  • Background Re-registration: Automatically attempts to re-register the service if the connection or lease is lost.
  • Pluggable Logger: Integrate your own logging solution by implementing a simple Logger interface.
  • Service Discovery: Find and get a list of active service instances.
  • Service Watching: Watch for real-time changes in service instances (new instances, crashes, etc.).
  • Leader Election: Elect a single leader among a group of service instances to perform special tasks.

Installation

go get github.com/jackman0925/discovery

Prerequisites

This library requires a running etcd v3 cluster. You can easily start one for development using Docker:

docker run -d -p 2379:2379 --name etcd-gcr-v3.5.0 gcr.io/etcd-development/etcd:v3.5.0 /usr/local/bin/etcd --listen-client-urls http://0.0.0.0:2379 --advertise-client-urls http://0.0.0.0:2379

Leader Election

In addition to service discovery, the library supports leader election. This is useful in distributed systems where you need to ensure that only one instance of a service is performing a specific task at any given time (e.g., running a cron job, processing a queue, etc.).

The election is built on top of the same etcd client and session, making it efficient and easy to use.

Usage Example

Here is an example of how two service instances can campaign for leadership. One will win, and the other will block until the leader steps down.

package main

import (
	"context"
	"log"
	"os"
	"sync"
	"time"

	"github.com/jackman0925/discovery"
)

func main() {
	// Use a standard logger for the example's own output
	stdLogger := log.New(os.Stdout, "[ELECTION-EXAMPLE] ", log.LstdFlags)

	// Create a logger option for the discovery library.
	// For production, you might use LogLevelWarn to reduce noise.
	libLoggerOption := discovery.WithLoggerAndLevel(stdLogger, discovery.LogLevelInfo)

	etcdEndpoints := []string{"localhost:2379"}

	// Create two separate registry instances to simulate two different nodes
	reg1, err := discovery.NewEtcdRegistry(etcdEndpoints, libLoggerOption)
	if err != nil {
		stdLogger.Fatalf("Failed to create registry 1: %v", err)
	}
	defer reg1.Close()

	reg2, err := discovery.NewEtcdRegistry(etcdEndpoints, libLoggerOption)
	if err != nil {
		stdLogger.Fatalf("Failed to create registry 2: %v", err)
	}
	defer reg2.Close()

	var wg sync.WaitGroup
	wg.Add(2)

	// --- Candidate 1 ---
	go func() {
		defer wg.Done()
		election, err := reg1.NewElection(discovery.ElectionOptions{
			ElectionName: "my-critical-task",
			Proposal:     "candidate-1",
		})
		if err != nil {
			stdLogger.Printf("candidate-1: failed to create election: %v", err)
			return
		}

		stdLogger.Println("candidate-1: Campaigning for leadership...")
		// Campaign for leadership. This call blocks until leadership is won or the context is cancelled.
		if err := election.Campaign(context.Background()); err != nil {
			stdLogger.Printf("candidate-1: campaign failed: %v", err)
			return
		}

		stdLogger.Println("candidate-1: I am the leader!")

		// Hold leadership for 10 seconds, then resign.
		time.Sleep(10 * time.Second)

		stdLogger.Println("candidate-1: Resigning from leadership.")
		if err := election.Resign(context.Background()); err != nil {
			stdLogger.Printf("candidate-1: failed to resign: %v", err)
		}
	}()

	// --- Candidate 2 ---
	go func() {
		defer wg.Done()
		// Give candidate 1 a head start
		time.Sleep(1 * time.Second)

		election, err := reg2.NewElection(discovery.ElectionOptions{
			ElectionName: "my-critical-task",
			Proposal:     "candidate-2",
		})
		if err != nil {
			stdLogger.Printf("candidate-2: failed to create election: %v", err)
			return
		}

		stdLogger.Println("candidate-2: Campaigning for leadership...")
		if err := election.Campaign(context.Background()); err != nil {
			stdLogger.Printf("candidate-2: campaign failed: %v", err)
			return
		}

		// This part will only execute after candidate-1 has resigned.
		stdLogger.Println("candidate-2: I am the leader now!")
		time.Sleep(5 * time.Second)
		stdLogger.Println("candidate-2: Resigning from leadership.")
		if err := election.Resign(context.Background()); err != nil {
			stdLogger.Printf("candidate-2: failed to resign: %v", err)
		}
	}()

	wg.Wait()
	stdLogger.Println("Example finished.")
}

Usage

Here is a complete example of how to register a service and properly shut it down.

package main

import (
	"context"
	"fmt"
	"log"
	"os"
	"time"

	"github.com/jackman0925/discovery"
)

func main() {
	// Use the standard logger for this example
	stdLogger := log.New(os.Stdout, "[DISCOVERY-EXAMPLE] ", log.LstdFlags)
	
	// Create a logger option for the discovery library
	// For production environments, you might want to use a lower log level to reduce log volume
	loggerOption := discovery.WithLoggerAndLevel(stdLogger, discovery.LogLevelWarn)

	// Create a new registry instance
	registry, err := discovery.NewEtcdRegistry(
		[]string{"localhost:2379"},      // Etcd server endpoints
		discovery.WithTTL(15),           // Set lease TTL to 15 seconds
		discovery.WithNamespace("prod"), // Set a namespace for services
		loggerOption,                    // Provide the logger option
	)
	if err != nil {
		log.Fatalf("Failed to create etcd registry: %v", err)
	}

	// It's crucial to close the registry to deregister the service and release resources.
	// defer is a great way to ensure this happens on exit.
	defer registry.Close()

	// Define the service to be registered
	serviceInfo := &discovery.ServiceInfo{
		Name:    "my-awesome-api",
		ID:      "instance-01",
		Address: "192.168.1.100",
		Port:    "8080",
		Version: "1.0.2",
	}

	// Register the service.
	// Use a context with a timeout for the registration call to avoid blocking indefinitely.
	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
	defer cancel()
	if err := registry.Register(ctx, serviceInfo); err != nil {
		log.Fatalf("Failed to register service: %v", err)
	}

	fmt.Println("Service registered successfully. It will be kept alive automatically.")

	// Keep the application running to simulate a live service
	// In a real application, this would be your main application logic (e.g., an HTTP server)
	select {
	case <-time.After(60 * time.Second):
		fmt.Println("Shutting down after 60 seconds...")
	}
}

Service Watching

You can watch service changes in two ways:

  • WatchService: watch a single service name (e.g. only my-awesome-api).
  • WatchNamespace: watch all services in the current namespace.
Watch a single service
serviceName := "my-awesome-api"

err := registry.WatchService(context.Background(), serviceName, func(services []*discovery.ServiceInfo) {
	// services contains all current instances of my-awesome-api
	fmt.Printf("service %s now has %d instance(s)\n", serviceName, len(services))
})
if err != nil {
	log.Fatalf("watch service failed: %v", err)
}
Watch all services in a namespace
err := registry.WatchNamespace(context.Background(), func(services []*discovery.ServiceInfo) {
	// services contains all current instances under the configured namespace
	fmt.Printf("namespace now has %d total instance(s)\n", len(services))
})
if err != nil {
	log.Fatalf("watch namespace failed: %v", err)
}

Testing

The library has a comprehensive test suite that includes both unit and integration tests.

  • Unit Tests: These tests do not have any external dependencies and can be run easily.
  • Integration Tests: These tests require a running Docker environment to spin up an etcd container.

To run all tests:

go test -v ./...

To run only the unit tests (which is faster and doesn't require Docker):

go test -v -short ./...

Configuration Options

The NewEtcdRegistry function accepts the following Option functions for configuration:

Function Description
WithNamespace(string) Sets a namespace to isolate services (default: default).
WithTTL(int64) Sets the service lease Time-To-Live in seconds (default: 30).
WithAuth(user, pass) Sets the username and password for etcd authentication.
WithKeyPrefix(string) Sets the root prefix for all keys (default: /etcd_registry).
WithLogger(Logger) Provides a custom logger that implements the Logger interface.
WithLogLevel(level) Sets the log level for the registry (default: LogLevelInfo).
WithLoggerAndLevel(logger, level) Convenience function that sets both logger and level.
WithDialTimeout(d) Sets the dial timeout for the etcd client.

Log Levels

The library supports four log levels:

  • LogLevelError: Only logs errors
  • LogLevelWarn: Logs warnings and errors
  • LogLevelInfo: Logs info, warnings, and errors (default)
  • LogLevelDebug: Logs all messages including debug
Production Environment Example

For production environments where you want to reduce log volume:

registry, err := discovery.NewEtcdRegistry(
    []string{"localhost:2379"},
    discovery.WithLoggerAndLevel(myLogger, discovery.LogLevelWarn), // Only log warnings and errors
    discovery.WithTTL(15),
    discovery.WithNamespace("prod"),
)
Development Environment Example

For development environments where you want detailed logging:

registry, err := discovery.NewEtcdRegistry(
    []string{"localhost:2379"},
    discovery.WithLoggerAndLevel(myLogger, discovery.LogLevelDebug), // Log everything
    discovery.WithTTL(15),
    discovery.WithNamespace("dev"),
)

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Election added in v0.1.0 

type Election struct {
	// contains filtered or unexported fields
}

Election manages a leadership election campaign.

func (*Election) Campaign added in v0.1.0 

func (e *Election) Campaign(ctx context.Context) error

Campaign puts a candidate into a leadership election. This method blocks until the candidate wins the election or the context is cancelled. After winning, it will hold the leadership until the context is cancelled, the underlying session is closed, or Resign is called.

func (*Election) Done added in v0.1.0 

func (e *Election) Done() <-chan struct{}

Done returns a channel that is closed when the underlying session is lost. This indicates that leadership is lost and the candidate should stop any leader-specific work.

func (*Election) IsLeader added in v0.1.0 

func (e *Election) IsLeader() bool

IsLeader returns true if this candidate is currently the leader. Note: This method performs a network call to etcd to get the current leader.

func (*Election) Leader added in v0.1.0 

func (e *Election) Leader(ctx context.Context) (string, error)

Leader returns the current leader's proposal. This is a non-blocking call and may return an error if the leader is not yet known.

func (*Election) Observe added in v0.1.0 

func (e *Election) Observe(ctx context.Context) <-chan string

Observe returns a channel that streams leader changes. When a new leader is elected, it will be sent on the channel. If the context is cancelled, the channel will be closed.

func (*Election) Resign added in v0.1.0 

func (e *Election) Resign(ctx context.Context) error

Resign gives up leadership. If the candidate is not a leader, this is a no-op. It returns an error if the resignation fails.

type ElectionOptions added in v0.1.0 

type ElectionOptions struct {
	// ElectionName is the name of the election, which will be used as a prefix for etcd keys.
	ElectionName string
	// Proposal is the value this candidate proposes for the election.
	// If it's empty, a default value will be generated.
	Proposal string
	// TTL is the session TTL in seconds for the leadership election.
	TTL int
}

ElectionOptions holds configuration for an Election.

type EtcdRegistry 

type EtcdRegistry struct {
	// contains filtered or unexported fields
}

EtcdRegistry provides service registration and discovery using etcd.

func NewEtcdRegistry 

func NewEtcdRegistry(endpoints []string, opts ...Option) (*EtcdRegistry, error)

NewEtcdRegistry creates a new EtcdRegistry instance.

func (*EtcdRegistry) Close 

func (e *EtcdRegistry) Close() error

Close safely shuts down the registry.

func (*EtcdRegistry) DeleteServiceByPrefix 

func (e *EtcdRegistry) DeleteServiceByPrefix(ctx context.Context, namePrefix string) (int64, error)

DeleteServiceByPrefix deletes multiple service registration keys by prefix.

func (*EtcdRegistry) DeleteServiceKey 

func (e *EtcdRegistry) DeleteServiceKey(ctx context.Context, name, id string) error

DeleteServiceKey manually deletes a service registration key.

func (*EtcdRegistry) Deregister 

func (e *EtcdRegistry) Deregister() error

Deregister unregisters the service from etcd.

func (*EtcdRegistry) GetNamespaceServices added in v0.2.1 

func (e *EtcdRegistry) GetNamespaceServices(ctx context.Context) ([]*ServiceInfo, error)

GetNamespaceServices retrieves all service instances in the current namespace.

func (*EtcdRegistry) GetService 

func (e *EtcdRegistry) GetService(ctx context.Context, name string) ([]*ServiceInfo, error)

GetService retrieves all instances of a specific service.

func (*EtcdRegistry) NewElection added in v0.1.0 

func (e *EtcdRegistry) NewElection(opts ElectionOptions) (*Election, error)

NewElection creates a new Election instance for a leadership campaign. The proposal is the value that this candidate is putting forward for the election. Typically this would be the candidate's own ID or address.

func (*EtcdRegistry) Register 

func (e *EtcdRegistry) Register(ctx context.Context, info *ServiceInfo) error

Register registers a service with etcd.

func (*EtcdRegistry) WatchNamespace added in v0.2.1 

func (e *EtcdRegistry) WatchNamespace(ctx context.Context, callback func([]*ServiceInfo)) error

WatchNamespace watches for all service changes in the current namespace and triggers a callback with the full service instance list in that namespace.

func (*EtcdRegistry) WatchService 

func (e *EtcdRegistry) WatchService(ctx context.Context, name string, callback func([]*ServiceInfo)) error

WatchService watches for changes in a service and triggers a callback.

type LogLevel added in v0.2.0 

type LogLevel int

LogLevel represents the level of logging. 

const (
	// LogLevelError logs only errors.
	LogLevelError LogLevel = iota
	// LogLevelWarn logs warnings and errors.
	LogLevelWarn
	// LogLevelInfo logs info, warnings, and errors.
	LogLevelInfo
	// LogLevelDebug logs all messages including debug.
	LogLevelDebug
)

type Logger 

type Logger interface {
	Errorf(format string, v ...interface{})
	Warnf(format string, v ...interface{})
	Infof(format string, v ...interface{})
	Debugf(format string, v ...interface{})
}

Logger defines the interface for logging. This allows users to use their own logger.

type Option 

type Option func(*Options)

Option configures an EtcdRegistry.

func WithAuth 

func WithAuth(username, password string) Option

WithAuth sets the username and password for etcd authentication.

func WithDialTimeout 

func WithDialTimeout(timeout time.Duration) Option

WithDialTimeout sets the dial timeout for the etcd client.

func WithKeyPrefix 

func WithKeyPrefix(prefix string) Option

WithKeyPrefix sets the root prefix for all keys.

func WithLogLevel added in v0.2.0 

func WithLogLevel(level LogLevel) Option

WithLogLevel sets the log level for the registry.

func WithLogger 

func WithLogger(logger Logger) Option

WithLogger sets the logger for the registry.

func WithLoggerAndLevel added in v0.2.0 

func WithLoggerAndLevel(logger interface {
	Printf(format string, v ...interface{})
}, level LogLevel) Option

WithLoggerAndLevel sets both the logger and log level for the registry. This is a convenience function that wraps the provided logger with a leveled logger.

func WithNamespace 

func WithNamespace(namespace string) Option

WithNamespace sets the namespace for service discovery.

func WithTTL 

func WithTTL(ttl int64) Option

WithTTL sets the lease time-to-live in seconds.

type Options 

type Options struct {
	Namespace         string
	TTL               int64
	Username          string
	Password          string
	DialTimeout       time.Duration
	DialKeepAliveTime time.Duration
	KeyPrefix         string
	Logger            Logger
	LogLevel          LogLevel
}

Options holds configuration for the EtcdRegistry.

type ServiceInfo 

type ServiceInfo struct {
	Name     string            `json:"name"`
	ID       string            `json:"id"`
	Address  string            `json:"address"`
	Port     string            `json:"port"`
	Version  string            `json:"version"`
	Weight   int               `json:"weight"`
	Metadata map[string]string `json:"metadata"`
}

ServiceInfo holds information about a registered service.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.