chore: import upstream snapshot with attribution

registry/cache/README.md

@@ -0,0 +1,125 @@
+# Registry Cache
+
+Cache is a library that provides a caching layer for the go-micro [registry](https://godoc.org/github.com/micro/go-micro/registry#Registry).
+
+If you're looking for caching in your microservices use the [selector](https://micro.mu/docs/fault-tolerance.html#caching-discovery).
+
+## Features
+
+- **Caching**: Caches registry lookups with configurable TTL
+- **Stale Cache Fallback**: Returns stale cached data when registry is unavailable
+- **Singleflight Protection**: Deduplicates concurrent requests for the same service
+- **Adaptive Throttling**: Rate limits failed lookups to prevent cache penetration (new in v5)
+
+## Interface
+
+```go
+// Cache is the registry cache interface
+type Cache interface {
+	// embed the registry interface
+	registry.Registry
+	// stop the cache watcher
+	Stop()
+}
+```
+
+## Usage
+
+### Basic Usage
+
+```go
+import (
+	"github.com/micro/go-micro/registry"
+	"github.com/micro/go-micro/registry/cache"
+)
+
+r := registry.NewRegistry()
+cache := cache.New(r)
+
+services, _ := cache.GetService("my.service")
+```
+
+### Advanced Configuration
+
+```go
+import (
+	"time"
+	"github.com/micro/go-micro/registry"
+	"github.com/micro/go-micro/registry/cache"
+)
+
+r := registry.NewRegistry()
+
+// Configure cache with custom options
+cache := cache.New(r,
+	cache.WithTTL(2*time.Minute),                    // Cache TTL
+	cache.WithMinimumRetryInterval(10*time.Second),  // Throttle failed lookups
+)
+
+services, _ := cache.GetService("my.service")
+```
+
+## Adaptive Throttling
+
+The cache implements rate limiting on ALL cache refresh attempts (not just errors) to prevent overwhelming the registry. This protects against multiple scenarios:
+
+1. **Registry failures**: When etcd is down/overloaded
+2. **Rolling deployments**: When all caches expire simultaneously under high QPS
+3. **Cache expiration storms**: When many services expire at once
+
+### How It Works
+
+- **Rate limiting**: Refresh attempts are throttled per-service using `MinimumRetryInterval` (default 5s)
+- **Stale cache preference**: If stale cache exists (even if expired), return it instead of calling registry
+- **No cache fallback**: If no cache exists, return `ErrNotFound` and rely on gRPC retry
+- **Singleflight deduplication**: Concurrent requests are still deduplicated
+- **Recovery**: Throttling is reset on successful registry lookup
+
+### Example Scenarios
+
+#### Scenario 1: Registry Failure with Stale Cache
+```go
+cache := cache.New(etcdRegistry, cache.WithMinimumRetryInterval(10*time.Second))
+
+// Initial lookup populates cache
+services, _ := cache.GetService("api")  // → Calls etcd, caches result
+
+// Cache expires after TTL
+time.Sleep(2 * time.Minute)
+
+// Etcd fails, but we have stale cache
+services, err := cache.GetService("api")  // → Returns stale cache WITHOUT calling etcd
+// err == nil, services contains stale data
+```
+
+#### Scenario 2: Rolling Deployment Cache Storm
+```go
+// Scenario: All 1000 upstream pods watch downstream service
+// Downstream does rolling deployment - last pod updated
+// All 1000 upstream caches expire simultaneously
+// High QPS hits the system at this moment
+
+// First request after cache expiration
+services, _ := cache.GetService("downstream")  // → Calls etcd, updates lastRefreshAttempt
+
+// Next 999 requests arrive within MinimumRetryInterval
+services, _ := cache.GetService("downstream")  // → Returns stale cache, NO etcd call
+// Rate limiting prevents 999 stampede requests to etcd
+```
+
+#### Scenario 3: No Cache Available
+```go
+// First lookup when etcd is down (no cache exists yet)
+_, err := cache.GetService("new-service")  // → Calls etcd, fails, records attempt time
+// err != nil
+
+// Immediate retry (< 10s later, still no cache)
+_, err = cache.GetService("new-service")  // → Throttled, returns ErrNotFound immediately
+// err == ErrNotFound
+
+// After MinimumRetryInterval
+time.Sleep(10 * time.Second)
+_, err = cache.GetService("new-service")  // → Allowed to retry, calls etcd again
+```
+
+This prevents cache penetration scenarios where thousands of concurrent requests hammer a failing or overloaded registry.

registry/cache/cache.go

@@ -0,0 +1,585 @@
+// Package cache provides a registry cache
+package cache
+
+import (
+	"math"
+	"math/rand"
+	"sync"
+	"time"
+
+	"golang.org/x/sync/singleflight"
+
+	util "go-micro.dev/v6/internal/util/registry"
+	log "go-micro.dev/v6/logger"
+	"go-micro.dev/v6/registry"
+)
+
+// Cache is the registry cache interface.
+type Cache interface {
+	// embed the registry interface
+	registry.Registry
+	// stop the cache watcher
+	Stop()
+}
+
+type Options struct {
+	Logger log.Logger
+	// TTL is the cache TTL
+	TTL time.Duration
+	// MinimumRetryInterval is the minimum time to wait before retrying a failed service lookup
+	// This prevents cache penetration when registry is failing and there's no stale cache
+	MinimumRetryInterval time.Duration
+}
+
+type Option func(o *Options)
+
+type cache struct {
+	opts Options
+
+	registry.Registry
+	// status of the registry
+	// used to hold onto the cache
+	// in failure state
+	status error
+	// used to prevent cache breakdwon
+	sg      singleflight.Group
+	cache   map[string][]*registry.Service
+	ttls    map[string]time.Time
+	nttls   map[string]map[string]time.Time // node ttls
+	watched map[string]bool
+
+	// used to stop the cache
+	exit chan bool
+
+	// indicate whether its running
+	watchedRunning map[string]bool
+
+	// lastRefreshAttempt tracks the last time we attempted to refresh cache for a service
+	// This is used to rate limit ALL refresh attempts, not just failed ones
+	lastRefreshAttempt map[string]time.Time
+
+	// registry cache
+	sync.RWMutex
+}
+
+var (
+	DefaultTTL = time.Minute
+	// DefaultMinimumRetryInterval is the default minimum time between cache refresh attempts
+	// This applies to ALL refresh attempts (not just errors) to prevent cache penetration
+	// during scenarios like rolling deployments where all caches expire simultaneously
+	DefaultMinimumRetryInterval = 5 * time.Second
+)
+
+func backoff(attempts int) time.Duration {
+	if attempts == 0 {
+		return time.Duration(0)
+	}
+	return time.Duration(math.Pow(10, float64(attempts))) * time.Millisecond
+}
+
+func (c *cache) getStatus() error {
+	c.RLock()
+	defer c.RUnlock()
+	return c.status
+}
+
+func (c *cache) setStatus(err error) {
+	c.Lock()
+	c.status = err
+	c.Unlock()
+}
+
+// isValid checks if the service is valid.
+func (c *cache) isValid(services []*registry.Service, ttl time.Time) bool {
+	// no services exist
+	if len(services) == 0 {
+		return false
+	}
+
+	// ttl is invalid
+	if ttl.IsZero() {
+		return false
+	}
+
+	// time since ttl is longer than timeout
+	if time.Since(ttl) > 0 {
+		return false
+	}
+
+	// a node did not get updated
+	for _, s := range services {
+		for _, n := range s.Nodes {
+			nttl := c.nttls[s.Name][n.Id]
+			if time.Since(nttl) > 0 {
+				return false
+			}
+		}
+	}
+
+	// ok
+	return true
+}
+
+func (c *cache) quit() bool {
+	select {
+	case <-c.exit:
+		return true
+	default:
+		return false
+	}
+}
+
+func (c *cache) del(service string) {
+	// don't blow away cache in error state
+	if err := c.status; err != nil {
+		return
+	}
+	// otherwise delete entries
+	delete(c.cache, service)
+	delete(c.ttls, service)
+	delete(c.nttls, service)
+	delete(c.lastRefreshAttempt, service)
+}
+
+func (c *cache) get(service string) ([]*registry.Service, error) {
+	// read lock
+	c.RLock()
+
+	// check the cache first
+	services := c.cache[service]
+	// get cache ttl
+	ttl := c.ttls[service]
+	// make a copy
+	cp := util.Copy(services)
+
+	// got services, nodes && within ttl so return cache
+	if c.isValid(cp, ttl) {
+		c.RUnlock()
+		// return services
+		return cp, nil
+	}
+
+	// Check rate limiting BEFORE entering singleflight
+	// This prevents blocking when we have stale cache and etcd is down
+	lastRefresh := c.lastRefreshAttempt[service]
+	minimumRetryInterval := c.opts.MinimumRetryInterval
+	if minimumRetryInterval == 0 {
+		minimumRetryInterval = DefaultMinimumRetryInterval
+	}
+
+	// If we're being rate limited AND have stale cache, return it immediately
+	// This avoids blocking all goroutines when etcd has long timeout
+	if !lastRefresh.IsZero() && time.Since(lastRefresh) < minimumRetryInterval && len(cp) > 0 {
+		c.RUnlock()
+		// Return stale cache even if expired
+		return cp, nil
+	}
+
+	// unlock the read lock before potentially blocking operations
+	c.RUnlock()
+
+	// get does the actual request for a service and cache it
+	get := func(service string, cached []*registry.Service) ([]*registry.Service, error) {
+		// Use singleflight to deduplicate concurrent requests
+		val, err, _ := c.sg.Do(service, func() (interface{}, error) {
+			// Inside singleflight - only one goroutine executes this
+
+			// Re-check rate limiting inside singleflight
+			// (in case another goroutine just completed a refresh)
+			c.RLock()
+			currentLastRefresh := c.lastRefreshAttempt[service]
+			currentMinimumRetryInterval := c.opts.MinimumRetryInterval
+			if currentMinimumRetryInterval == 0 {
+				currentMinimumRetryInterval = DefaultMinimumRetryInterval
+			}
+			c.RUnlock()
+
+			if !currentLastRefresh.IsZero() && time.Since(currentLastRefresh) < currentMinimumRetryInterval {
+				// We're being rate limited
+				// Check if we have stale cache to return
+				c.RLock()
+				cachedServices := util.Copy(c.cache[service])
+				c.RUnlock()
+
+				if len(cachedServices) > 0 {
+					// Return stale cache even if expired
+					return cachedServices, nil
+				}
+				// No cache available, return error
+				return nil, registry.ErrNotFound
+			}
+
+			// Track this refresh attempt
+			c.Lock()
+			c.lastRefreshAttempt[service] = time.Now()
+			c.Unlock()
+
+			// Actually call the registry
+			return c.Registry.GetService(service)
+		})
+
+		services, _ := val.([]*registry.Service)
+		if err != nil {
+			// check the cache
+			if len(cached) > 0 {
+				// set the error status
+				c.setStatus(err)
+
+				// return the stale cache
+				return cached, nil
+			}
+			// otherwise return error
+			return nil, err
+		}
+
+		// Success - reset the status
+		if err := c.getStatus(); err != nil {
+			c.setStatus(nil)
+		}
+
+		// cache results
+		cp := util.Copy(services)
+		c.Lock()
+		for _, s := range services {
+			c.updateNodeTTLs(service, s.Nodes)
+		}
+		c.set(service, services)
+		c.Unlock()
+
+		return cp, nil
+	}
+
+	// watch service if not watched
+	c.RLock()
+	_, ok := c.watched[service]
+	c.RUnlock()
+
+	// check if its being watched
+	if c.opts.TTL > 0 && !ok {
+		c.Lock()
+
+		// set to watched
+		c.watched[service] = true
+
+		// only kick it off if not running
+		if !c.watchedRunning[service] {
+			go c.run(service)
+		}
+
+		c.Unlock()
+	}
+
+	// get and return services
+	return get(service, cp)
+}
+
+func (c *cache) set(service string, services []*registry.Service) {
+	c.cache[service] = services
+	c.ttls[service] = time.Now().Add(c.opts.TTL)
+}
+
+func (c *cache) updateNodeTTLs(name string, nodes []*registry.Node) {
+	if c.nttls[name] == nil {
+		c.nttls[name] = make(map[string]time.Time)
+	}
+	for _, node := range nodes {
+		c.nttls[name][node.Id] = time.Now().Add(c.opts.TTL)
+	}
+	// clean up expired nodes
+	for nodeId, nttl := range c.nttls[name] {
+		if time.Since(nttl) > 0 {
+			delete(c.nttls[name], nodeId)
+		}
+	}
+}
+
+func (c *cache) update(res *registry.Result) {
+	if res == nil || res.Service == nil {
+		return
+	}
+
+	c.Lock()
+	defer c.Unlock()
+
+	// only save watched services
+	if _, ok := c.watched[res.Service.Name]; !ok {
+		return
+	}
+
+	services, ok := c.cache[res.Service.Name]
+	if !ok {
+		// we're not going to cache anything
+		// unless there was already a lookup
+		return
+	}
+
+	if len(res.Service.Nodes) == 0 {
+		switch res.Action {
+		case "delete":
+			c.del(res.Service.Name)
+		}
+		return
+	}
+
+	// existing service found
+	var service *registry.Service
+	var index int
+	for i, s := range services {
+		if s.Version == res.Service.Version {
+			service = s
+			index = i
+		}
+	}
+
+	switch res.Action {
+	case "create", "update":
+		c.updateNodeTTLs(res.Service.Name, res.Service.Nodes)
+		if service == nil {
+			c.set(res.Service.Name, append(services, res.Service))
+			return
+		}
+
+		// append old nodes to new service
+		for _, cur := range service.Nodes {
+			var seen bool
+			for _, node := range res.Service.Nodes {
+				if cur.Id == node.Id {
+					seen = true
+					break
+				}
+			}
+			if !seen {
+				res.Service.Nodes = append(res.Service.Nodes, cur)
+			}
+		}
+
+		services[index] = res.Service
+		c.set(res.Service.Name, services)
+	case "delete":
+		if service == nil {
+			return
+		}
+
+		var nodes []*registry.Node
+
+		// filter cur nodes to remove the dead one
+		for _, cur := range service.Nodes {
+			var seen bool
+			for _, del := range res.Service.Nodes {
+				if del.Id == cur.Id {
+					seen = true
+					break
+				}
+			}
+			if !seen {
+				nodes = append(nodes, cur)
+			}
+		}
+
+		// still got nodes, save and return
+		if len(nodes) > 0 {
+			service.Nodes = nodes
+			services[index] = service
+			c.set(service.Name, services)
+			return
+		}
+
+		// zero nodes left
+
+		// only have one thing to delete
+		// nuke the thing
+		if len(services) == 1 {
+			c.del(service.Name)
+			return
+		}
+
+		// still have more than 1 service
+		// check the version and keep what we know
+		var srvs []*registry.Service
+		for _, s := range services {
+			if s.Version != service.Version {
+				srvs = append(srvs, s)
+			}
+		}
+
+		// save
+		c.set(service.Name, srvs)
+	case "override":
+		if service == nil {
+			return
+		}
+
+		c.del(service.Name)
+	}
+}
+
+// run starts the cache watcher loop
+// it creates a new watcher if there's a problem.
+func (c *cache) run(service string) {
+	c.Lock()
+	c.watchedRunning[service] = true
+	c.Unlock()
+	logger := c.opts.Logger
+	// reset watcher on exit
+	defer func() {
+		c.Lock()
+		c.watched = make(map[string]bool)
+		c.watchedRunning[service] = false
+		c.Unlock()
+	}()
+
+	var a, b int
+
+	for {
+		// exit early if already dead
+		if c.quit() {
+			return
+		}
+
+		// jitter before starting
+		j := rand.Int63n(100)
+		time.Sleep(time.Duration(j) * time.Millisecond)
+
+		// create new watcher
+		w, err := c.Watch(registry.WatchService(service))
+		if err != nil {
+			if c.quit() {
+				return
+			}
+
+			d := backoff(a)
+			c.setStatus(err)
+
+			if a > 3 {
+				logger.Logf(log.DebugLevel, "rcache: ", err, " backing off ", d)
+				a = 0
+			}
+
+			time.Sleep(d)
+			a++
+
+			continue
+		}
+
+		// reset a
+		a = 0
+
+		// watch for events
+		if err := c.watch(w); err != nil {
+			if c.quit() {
+				return
+			}
+
+			d := backoff(b)
+			c.setStatus(err)
+
+			if b > 3 {
+				logger.Logf(log.DebugLevel, "rcache: ", err, " backing off ", d)
+				b = 0
+			}
+
+			time.Sleep(d)
+			b++
+
+			continue
+		}
+
+		// reset b
+		b = 0
+	}
+}
+
+// watch loops the next event and calls update
+// it returns if there's an error.
+func (c *cache) watch(w registry.Watcher) error {
+	// used to stop the watch
+	stop := make(chan bool)
+
+	// manage this loop
+	go func() {
+		defer w.Stop()
+
+		select {
+		// wait for exit
+		case <-c.exit:
+			return
+		// we've been stopped
+		case <-stop:
+			return
+		}
+	}()
+
+	for {
+		res, err := w.Next()
+		if err != nil {
+			close(stop)
+			return err
+		}
+
+		// reset the error status since we succeeded
+		if err := c.getStatus(); err != nil {
+			// reset status
+			c.setStatus(nil)
+		}
+
+		c.update(res)
+	}
+}
+
+func (c *cache) GetService(service string, opts ...registry.GetOption) ([]*registry.Service, error) {
+	// get the service
+	services, err := c.get(service)
+	if err != nil {
+		return nil, err
+	}
+
+	// if there's nothing return err
+	if len(services) == 0 {
+		return nil, registry.ErrNotFound
+	}
+
+	// return services
+	return services, nil
+}
+
+func (c *cache) Stop() {
+	c.Lock()
+	defer c.Unlock()
+
+	select {
+	case <-c.exit:
+		return
+	default:
+		close(c.exit)
+	}
+}
+
+func (c *cache) String() string {
+	return "cache"
+}
+
+// New returns a new cache.
+func New(r registry.Registry, opts ...Option) Cache {
+
+	options := Options{
+		TTL:                  DefaultTTL,
+		MinimumRetryInterval: DefaultMinimumRetryInterval,
+		Logger:               log.DefaultLogger,
+	}
+
+	for _, o := range opts {
+		o(&options)
+	}
+
+	return &cache{
+		Registry:           r,
+		opts:               options,
+		watched:            make(map[string]bool),
+		watchedRunning:     make(map[string]bool),
+		cache:              make(map[string][]*registry.Service),
+		ttls:               make(map[string]time.Time),
+		nttls:              make(map[string]map[string]time.Time),
+		lastRefreshAttempt: make(map[string]time.Time),
+		exit:               make(chan bool),
+	}
+}

registry/cache/cache_test.go

@@ -0,0 +1,530 @@
+package cache
+
+import (
+	"errors"
+	"sync"
+	"sync/atomic"
+	"testing"
+	"time"
+
+	"go-micro.dev/v6/logger"
+	"go-micro.dev/v6/registry"
+)
+
+// mockRegistry is a mock implementation of registry.Registry for testing
+type mockRegistry struct {
+	callCount int32
+	delay     time.Duration
+	err       error
+	services  []*registry.Service
+	mu        sync.Mutex
+}
+
+func (m *mockRegistry) Init(...registry.Option) error {
+	return nil
+}
+
+func (m *mockRegistry) Options() registry.Options {
+	return registry.Options{}
+}
+
+func (m *mockRegistry) Register(*registry.Service, ...registry.RegisterOption) error {
+	return nil
+}
+
+func (m *mockRegistry) Deregister(*registry.Service, ...registry.DeregisterOption) error {
+	return nil
+}
+
+func (m *mockRegistry) GetService(name string, opts ...registry.GetOption) ([]*registry.Service, error) {
+	// Increment call count
+	atomic.AddInt32(&m.callCount, 1)
+
+	// Simulate delay (e.g., network latency)
+	if m.delay > 0 {
+		time.Sleep(m.delay)
+	}
+
+	// Return error if configured
+	if m.err != nil {
+		return nil, m.err
+	}
+
+	// Return services
+	return m.services, nil
+}
+
+func (m *mockRegistry) ListServices(...registry.ListOption) ([]*registry.Service, error) {
+	return nil, nil
+}
+
+func (m *mockRegistry) Watch(...registry.WatchOption) (registry.Watcher, error) {
+	return nil, errors.New("not implemented")
+}
+
+func (m *mockRegistry) String() string {
+	return "mock"
+}
+
+func (m *mockRegistry) getCallCount() int32 {
+	return atomic.LoadInt32(&m.callCount)
+}
+
+// TestSingleflightPreventsStampede verifies that concurrent requests for the same service
+// only result in a single call to the underlying registry
+func TestSingleflightPreventsStampede(t *testing.T) {
+	mock := &mockRegistry{
+		delay: 100 * time.Millisecond, // Simulate slow etcd response
+		services: []*registry.Service{
+			{
+				Name:    "test.service",
+				Version: "1.0.0",
+				Nodes: []*registry.Node{
+					{Id: "node1", Address: "localhost:9090"},
+				},
+			},
+		},
+	}
+
+	// Type assertion to *cache is necessary to access internal state for verification
+	c := New(mock, func(o *Options) {
+		o.TTL = time.Minute
+		o.Logger = logger.DefaultLogger
+	}).(*cache)
+
+	// Launch 10 concurrent requests for the same service
+	const concurrency = 10
+	var wg sync.WaitGroup
+	wg.Add(concurrency)
+
+	results := make([][]*registry.Service, concurrency)
+	errs := make([]error, concurrency)
+
+	for i := 0; i < concurrency; i++ {
+		go func(idx int) {
+			defer wg.Done()
+			services, err := c.GetService("test.service")
+			results[idx] = services
+			errs[idx] = err
+		}(i)
+	}
+
+	wg.Wait()
+
+	// Verify that only 1 call was made to the underlying registry
+	callCount := mock.getCallCount()
+	if callCount != 1 {
+		t.Errorf("Expected 1 call to registry, got %d", callCount)
+	}
+
+	// Verify all requests got the same result
+	for i := 0; i < concurrency; i++ {
+		if errs[i] != nil {
+			t.Errorf("Request %d failed: %v", i, errs[i])
+		}
+		if len(results[i]) != 1 {
+			t.Errorf("Request %d got %d services, expected 1", i, len(results[i]))
+		}
+	}
+}
+
+// TestSingleflightWithError verifies that when etcd fails, only one request is made
+// and all concurrent callers receive the error
+func TestSingleflightWithError(t *testing.T) {
+	expectedErr := errors.New("etcd connection failed")
+	mock := &mockRegistry{
+		delay: 50 * time.Millisecond,
+		err:   expectedErr,
+	}
+
+	// Type assertion to *cache is necessary to access internal state for verification
+	c := New(mock, func(o *Options) {
+		o.TTL = time.Minute
+		o.Logger = logger.DefaultLogger
+	}).(*cache)
+
+	// Launch concurrent requests
+	const concurrency = 10
+	var wg sync.WaitGroup
+	wg.Add(concurrency)
+
+	errs := make([]error, concurrency)
+
+	for i := 0; i < concurrency; i++ {
+		go func(idx int) {
+			defer wg.Done()
+			_, err := c.GetService("test.service")
+			errs[idx] = err
+		}(i)
+	}
+
+	wg.Wait()
+
+	// Verify that only 1 call was made to the underlying registry
+	callCount := mock.getCallCount()
+	if callCount != 1 {
+		t.Errorf("Expected 1 call to registry even on error, got %d", callCount)
+	}
+
+	// Verify all requests got the error
+	for i := 0; i < concurrency; i++ {
+		if errs[i] == nil {
+			t.Errorf("Request %d should have failed", i)
+		}
+	}
+}
+
+// TestStaleCacheOnError verifies that stale cache is returned when registry fails
+func TestStaleCacheOnError(t *testing.T) {
+	mock := &mockRegistry{
+		services: []*registry.Service{
+			{
+				Name:    "test.service",
+				Version: "1.0.0",
+				Nodes: []*registry.Node{
+					{Id: "node1", Address: "localhost:9090"},
+				},
+			},
+		},
+	}
+
+	// Type assertion to *cache is necessary to access internal state for verification
+	c := New(mock, func(o *Options) {
+		o.TTL = 100 * time.Millisecond // Short TTL for testing
+		o.Logger = logger.DefaultLogger
+	}).(*cache)
+
+	// First request - should populate cache
+	services, err := c.GetService("test.service")
+	if err != nil {
+		t.Fatalf("First request failed: %v", err)
+	}
+	if len(services) != 1 {
+		t.Fatalf("Expected 1 service, got %d", len(services))
+	}
+
+	// Wait for cache to expire
+	time.Sleep(150 * time.Millisecond)
+
+	// Configure mock to fail
+	mock.err = errors.New("etcd unavailable")
+
+	// Second request - should return stale cache despite error
+	services, err = c.GetService("test.service")
+	if err != nil {
+		t.Errorf("Should have returned stale cache, got error: %v", err)
+	}
+	if len(services) != 1 {
+		t.Errorf("Expected stale cache with 1 service, got %d", len(services))
+	}
+}
+
+// TestCachePenetrationPrevention verifies the complete flow:
+// 1. Cache populated
+// 2. Cache expires
+// 3. Registry fails
+// 4. Concurrent requests don't stampede registry due to rate limiting
+// 5. Stale cache is returned without hitting registry
+func TestCachePenetrationPrevention(t *testing.T) {
+	mock := &mockRegistry{
+		services: []*registry.Service{
+			{
+				Name:    "test.service",
+				Version: "1.0.0",
+				Nodes: []*registry.Node{
+					{Id: "node1", Address: "localhost:9090"},
+				},
+			},
+		},
+	}
+
+	// Type assertion to *cache is necessary to access internal state for verification
+	c := New(mock, func(o *Options) {
+		o.TTL = 100 * time.Millisecond
+		o.Logger = logger.DefaultLogger
+		// Use short retry interval to test rate limiting
+		o.MinimumRetryInterval = 5 * time.Second
+	}).(*cache)
+
+	// Initial request to populate cache
+	_, err := c.GetService("test.service")
+	if err != nil {
+		t.Fatalf("Initial request failed: %v", err)
+	}
+
+	initialCalls := mock.getCallCount()
+	if initialCalls != 1 {
+		t.Fatalf("Expected 1 initial call, got %d", initialCalls)
+	}
+
+	// Wait for cache to expire (but not past retry interval)
+	time.Sleep(150 * time.Millisecond)
+
+	// Configure mock to fail with delay
+	mock.err = errors.New("etcd overloaded")
+	mock.delay = 100 * time.Millisecond
+
+	// Launch many concurrent requests (simulating stampede)
+	const concurrency = 50
+	var wg sync.WaitGroup
+	wg.Add(concurrency)
+
+	successCount := int32(0)
+
+	for i := 0; i < concurrency; i++ {
+		go func() {
+			defer wg.Done()
+			services, err := c.GetService("test.service")
+			// Should return stale cache without error (rate limiting prevents registry call)
+			if err == nil && len(services) > 0 {
+				atomic.AddInt32(&successCount, 1)
+			}
+		}()
+	}
+
+	wg.Wait()
+
+	// Verify:
+	// 1. NO additional calls (rate limiting + stale cache prevented registry access)
+	totalCalls := mock.getCallCount()
+	if totalCalls != 1 { // only initial call, no retry due to rate limiting
+		t.Errorf("Expected 1 total call (rate limiting prevented retry), got %d", totalCalls)
+	}
+
+	// 2. All requests got stale cache (no errors)
+	if successCount != concurrency {
+		t.Errorf("Expected all %d requests to succeed with stale cache, got %d", concurrency, successCount)
+	}
+}
+
+// TestThrottlingWithoutStaleCache verifies that the cache throttles requests
+// when there's no stale cache and the registry is failing
+func TestThrottlingWithoutStaleCache(t *testing.T) {
+	mock := &mockRegistry{
+		err: errors.New("etcd connection failed"),
+	}
+
+	// Create cache with short retry interval for testing
+	c := New(mock, func(o *Options) {
+		o.TTL = time.Minute
+		o.MinimumRetryInterval = 2 * time.Second
+		o.Logger = logger.DefaultLogger
+	}).(*cache)
+
+	// First request - should fail and record the attempt
+	_, err := c.GetService("test.service")
+	if err == nil {
+		t.Fatal("Expected error on first request, got nil")
+	}
+
+	callCount1 := mock.getCallCount()
+	if callCount1 != 1 {
+		t.Fatalf("Expected 1 call on first attempt, got %d", callCount1)
+	}
+
+	// Immediate second request - should be throttled (no registry call)
+	_, err = c.GetService("test.service")
+	if err == nil {
+		t.Fatal("Expected error on throttled request, got nil")
+	}
+
+	callCount2 := mock.getCallCount()
+	if callCount2 != 1 {
+		t.Errorf("Expected throttling (still 1 call), got %d calls", callCount2)
+	}
+
+	// Wait for retry interval to pass
+	time.Sleep(2100 * time.Millisecond)
+
+	// Third request - should be allowed (makes another registry call)
+	_, err = c.GetService("test.service")
+	if err == nil {
+		t.Fatal("Expected error after retry interval, got nil")
+	}
+
+	callCount3 := mock.getCallCount()
+	if callCount3 != 2 {
+		t.Errorf("Expected 2 calls after retry interval, got %d", callCount3)
+	}
+}
+
+// TestThrottlingMultipleConcurrentRequests verifies that throttling works
+// correctly with multiple concurrent requests when there's no stale cache
+func TestThrottlingMultipleConcurrentRequests(t *testing.T) {
+	mock := &mockRegistry{
+		err:   errors.New("etcd overloaded"),
+		delay: 50 * time.Millisecond,
+	}
+
+	c := New(mock, func(o *Options) {
+		o.TTL = time.Minute
+		o.MinimumRetryInterval = 1 * time.Second
+		o.Logger = logger.DefaultLogger
+	}).(*cache)
+
+	// First batch - all concurrent requests should result in single call (singleflight)
+	const concurrency = 20
+	var wg sync.WaitGroup
+	wg.Add(concurrency)
+
+	for i := 0; i < concurrency; i++ {
+		go func() {
+			defer wg.Done()
+			c.GetService("test.service")
+		}()
+	}
+
+	wg.Wait()
+
+	callCount1 := mock.getCallCount()
+	if callCount1 != 1 {
+		t.Errorf("Expected 1 call (singleflight), got %d", callCount1)
+	}
+
+	// Second batch immediately after - should all be throttled (no new calls)
+	wg.Add(concurrency)
+	for i := 0; i < concurrency; i++ {
+		go func() {
+			defer wg.Done()
+			c.GetService("test.service")
+		}()
+	}
+
+	wg.Wait()
+
+	callCount2 := mock.getCallCount()
+	if callCount2 != 1 {
+		t.Errorf("Expected throttling (still 1 call), got %d", callCount2)
+	}
+
+	// Wait for retry interval
+	time.Sleep(1100 * time.Millisecond)
+
+	// Third batch - should result in one more call
+	wg.Add(concurrency)
+	for i := 0; i < concurrency; i++ {
+		go func() {
+			defer wg.Done()
+			c.GetService("test.service")
+		}()
+	}
+
+	wg.Wait()
+
+	callCount3 := mock.getCallCount()
+	if callCount3 != 2 {
+		t.Errorf("Expected 2 calls after retry interval, got %d", callCount3)
+	}
+}
+
+// TestThrottlingDoesNotAffectSuccessfulLookups verifies that throttling
+// doesn't interfere with successful service lookups
+func TestThrottlingDoesNotAffectSuccessfulLookups(t *testing.T) {
+	mock := &mockRegistry{
+		services: []*registry.Service{
+			{
+				Name:    "test.service",
+				Version: "1.0.0",
+				Nodes: []*registry.Node{
+					{Id: "node1", Address: "localhost:9090"},
+				},
+			},
+		},
+	}
+
+	c := New(mock, func(o *Options) {
+		o.TTL = 100 * time.Millisecond
+		o.MinimumRetryInterval = 2 * time.Second
+		o.Logger = logger.DefaultLogger
+	}).(*cache)
+
+	// Multiple successful requests in quick succession
+	for i := 0; i < 5; i++ {
+		services, err := c.GetService("test.service")
+		if err != nil {
+			t.Fatalf("Request %d failed: %v", i, err)
+		}
+		if len(services) != 1 {
+			t.Fatalf("Request %d got %d services, expected 1", i, len(services))
+		}
+		time.Sleep(10 * time.Millisecond)
+	}
+
+	// First request should hit registry, others should use cache
+	callCount := mock.getCallCount()
+	if callCount != 1 {
+		t.Errorf("Expected 1 call (cached), got %d", callCount)
+	}
+}
+
+// TestThrottlingClearedOnSuccess verifies that failed attempt tracking
+// is cleared when a subsequent request succeeds
+func TestThrottlingClearedOnSuccess(t *testing.T) {
+	mock := &mockRegistry{
+		err: errors.New("temporary failure"),
+	}
+
+	c := New(mock, func(o *Options) {
+		o.TTL = time.Minute
+		o.MinimumRetryInterval = 1 * time.Second
+		o.Logger = logger.DefaultLogger
+	}).(*cache)
+
+	// First request fails
+	_, err := c.GetService("test.service")
+	if err == nil {
+		t.Fatal("Expected error on first request")
+	}
+
+	// Second request immediately after should be throttled
+	_, err = c.GetService("test.service")
+	if err == nil {
+		t.Fatal("Expected error on throttled request")
+	}
+
+	callCount1 := mock.getCallCount()
+	if callCount1 != 1 {
+		t.Errorf("Expected 1 call due to throttling, got %d", callCount1)
+	}
+
+	// Wait for retry interval
+	time.Sleep(1100 * time.Millisecond)
+
+	// Fix the mock to return success
+	mock.mu.Lock()
+	mock.err = nil
+	mock.services = []*registry.Service{
+		{
+			Name:    "test.service",
+			Version: "1.0.0",
+			Nodes: []*registry.Node{
+				{Id: "node1", Address: "localhost:9090"},
+			},
+		},
+	}
+	mock.mu.Unlock()
+
+	// Request should succeed now
+	services, err := c.GetService("test.service")
+	if err != nil {
+		t.Fatalf("Expected success after fix, got error: %v", err)
+	}
+	if len(services) != 1 {
+		t.Fatalf("Expected 1 service, got %d", len(services))
+	}
+
+	// Immediate next request should NOT be throttled (throttling cleared)
+	services, err = c.GetService("test.service")
+	if err != nil {
+		t.Fatalf("Expected cached success, got error: %v", err)
+	}
+	if len(services) != 1 {
+		t.Fatalf("Expected 1 service from cache, got %d", len(services))
+	}
+
+	// Should be 2 calls total (1 failed + 1 success), no additional calls for cached request
+	callCount2 := mock.getCallCount()
+	if callCount2 != 2 {
+		t.Errorf("Expected 2 calls total, got %d", callCount2)
+	}
+}

registry/cache/options.go

@@ -0,0 +1,29 @@
+package cache
+
+import (
+	"time"
+
+	"go-micro.dev/v6/logger"
+)
+
+// WithTTL sets the cache TTL.
+func WithTTL(t time.Duration) Option {
+	return func(o *Options) {
+		o.TTL = t
+	}
+}
+
+// WithLogger sets the underline logger.
+func WithLogger(l logger.Logger) Option {
+	return func(o *Options) {
+		o.Logger = l
+	}
+}
+
+// WithMinimumRetryInterval sets the minimum retry interval for failed lookups.
+// This prevents cache penetration when registry is failing and there's no stale cache.
+func WithMinimumRetryInterval(d time.Duration) Option {
+	return func(o *Options) {
+		o.MinimumRetryInterval = d
+	}
+}

registry/consul/consul.go

@@ -0,0 +1,466 @@
+package consul
+
+import (
+	"crypto/tls"
+	"errors"
+	"fmt"
+	"net"
+	"net/http"
+	"runtime"
+	"strconv"
+	"strings"
+	"sync"
+	"time"
+
+	consul "github.com/hashicorp/consul/api"
+	hash "github.com/mitchellh/hashstructure"
+	mnet "go-micro.dev/v6/internal/util/net"
+	mtls "go-micro.dev/v6/internal/util/tls"
+	"go-micro.dev/v6/registry"
+)
+
+type consulRegistry struct {
+	Address []string
+	opts    registry.Options
+
+	client *consul.Client
+	config *consul.Config
+
+	// connect enabled
+	connect bool
+
+	queryOptions *consul.QueryOptions
+
+	sync.Mutex
+	register map[string]uint64
+	// lastChecked tracks when a node was last checked as existing in Consul
+	lastChecked map[string]time.Time
+}
+
+func getDeregisterTTL(t time.Duration) time.Duration {
+	// splay slightly for the watcher?
+	splay := time.Second * 5
+	deregTTL := t + splay
+
+	// consul has a minimum timeout on deregistration of 1 minute.
+	if t < time.Minute {
+		deregTTL = time.Minute + splay
+	}
+
+	return deregTTL
+}
+
+func newTransport(config *tls.Config) *http.Transport {
+	if config == nil {
+		// Use environment-based config - secure by default
+		config = mtls.Config()
+	}
+
+	t := &http.Transport{
+		Proxy: http.ProxyFromEnvironment,
+		Dial: (&net.Dialer{
+			Timeout:   30 * time.Second,
+			KeepAlive: 30 * time.Second,
+		}).Dial,
+		TLSHandshakeTimeout: 10 * time.Second,
+		TLSClientConfig:     config,
+	}
+	runtime.SetFinalizer(&t, func(tr **http.Transport) {
+		(*tr).CloseIdleConnections()
+	})
+	return t
+}
+
+func configure(c *consulRegistry, opts ...registry.Option) {
+	// set opts
+	for _, o := range opts {
+		o(&c.opts)
+	}
+
+	// use default non pooled config
+	config := consul.DefaultNonPooledConfig()
+
+	if c.opts.Context != nil {
+		// Use the consul config passed in the options, if available
+		if co, ok := c.opts.Context.Value(consulConfigKey).(*consul.Config); ok {
+			config = co
+		}
+		if cn, ok := c.opts.Context.Value(consulConnectKey).(bool); ok {
+			c.connect = cn
+		}
+
+		// Use the consul query options passed in the options, if available
+		if qo, ok := c.opts.Context.Value(consulQueryOptionsKey).(*consul.QueryOptions); ok && qo != nil {
+			c.queryOptions = qo
+		}
+		if as, ok := c.opts.Context.Value(consulAllowStaleKey).(bool); ok {
+			c.queryOptions.AllowStale = as
+		}
+	}
+
+	// check if there are any addrs
+	var addrs []string
+
+	// iterate the options addresses
+	for _, address := range c.opts.Addrs {
+		// check we have a port
+		addr, port, err := net.SplitHostPort(address)
+		if ae, ok := err.(*net.AddrError); ok && ae.Err == "missing port in address" {
+			port = "8500"
+			addr = address
+			addrs = append(addrs, net.JoinHostPort(addr, port))
+		} else if err == nil {
+			addrs = append(addrs, net.JoinHostPort(addr, port))
+		}
+	}
+
+	// set the addrs
+	if len(addrs) > 0 {
+		c.Address = addrs
+		config.Address = c.Address[0]
+	}
+
+	if config.HttpClient == nil {
+		config.HttpClient = new(http.Client)
+	}
+
+	// requires secure connection?
+	if c.opts.Secure || c.opts.TLSConfig != nil {
+		config.Scheme = "https"
+		// We're going to support InsecureSkipVerify
+		config.HttpClient.Transport = newTransport(c.opts.TLSConfig)
+	}
+
+	// set timeout
+	if c.opts.Timeout > 0 {
+		config.HttpClient.Timeout = c.opts.Timeout
+	}
+
+	// set the config
+	c.config = config
+
+	// remove client
+	c.client = nil
+
+	// setup the client
+	c.Client()
+}
+
+func (c *consulRegistry) Init(opts ...registry.Option) error {
+	configure(c, opts...)
+	return nil
+}
+
+func (c *consulRegistry) Deregister(s *registry.Service, opts ...registry.DeregisterOption) error {
+	if len(s.Nodes) == 0 {
+		return errors.New("require at least one node")
+	}
+
+	// delete our hash and time check of the service
+	c.Lock()
+	delete(c.register, s.Name)
+	delete(c.lastChecked, s.Name)
+	c.Unlock()
+
+	node := s.Nodes[0]
+	return c.Client().Agent().ServiceDeregister(node.Id)
+}
+
+func (c *consulRegistry) Register(s *registry.Service, opts ...registry.RegisterOption) error {
+	if len(s.Nodes) == 0 {
+		return errors.New("require at least one node")
+	}
+
+	var regTCPCheck bool
+	var regInterval time.Duration
+	var regHTTPCheck bool
+	var httpCheckConfig consul.AgentServiceCheck
+
+	var options registry.RegisterOptions
+	for _, o := range opts {
+		o(&options)
+	}
+
+	if c.opts.Context != nil {
+		if tcpCheckInterval, ok := c.opts.Context.Value(consulTCPCheckKey).(time.Duration); ok {
+			regTCPCheck = true
+			regInterval = tcpCheckInterval
+		}
+		var ok bool
+		if httpCheckConfig, ok = c.opts.Context.Value(consulHTTPCheckConfigKey).(consul.AgentServiceCheck); ok {
+			regHTTPCheck = true
+		}
+	}
+
+	// create hash of service; uint64
+	h, err := hash.Hash(s, nil)
+	if err != nil {
+		return err
+	}
+
+	// use first node
+	node := s.Nodes[0]
+
+	// get existing hash and last checked time
+	c.Lock()
+	v, ok := c.register[s.Name]
+	lastChecked := c.lastChecked[s.Name]
+	c.Unlock()
+
+	// if it's already registered and matches then just pass the check
+	if ok && v == h {
+		if options.TTL == time.Duration(0) {
+			// ensure that our service hasn't been deregistered by Consul
+			if time.Since(lastChecked) <= getDeregisterTTL(regInterval) {
+				return nil
+			}
+			services, _, err := c.Client().Health().Checks(s.Name, c.queryOptions)
+			if err == nil {
+				for _, v := range services {
+					if v.ServiceID == node.Id {
+						return nil
+					}
+				}
+			}
+		} else {
+			// if the err is nil we're all good, bail out
+			// if not, we don't know what the state is, so full re-register
+			if err := c.Client().Agent().PassTTL("service:"+node.Id, ""); err == nil {
+				return nil
+			}
+		}
+	}
+
+	// encode the tags
+	tags := encodeMetadata(node.Metadata)
+	tags = append(tags, encodeEndpoints(s.Endpoints)...)
+	tags = append(tags, encodeVersion(s.Version)...)
+
+	var check *consul.AgentServiceCheck
+
+	if regTCPCheck {
+		deregTTL := getDeregisterTTL(regInterval)
+
+		check = &consul.AgentServiceCheck{
+			TCP:                            node.Address,
+			Interval:                       fmt.Sprintf("%v", regInterval),
+			DeregisterCriticalServiceAfter: fmt.Sprintf("%v", deregTTL),
+		}
+
+	} else if regHTTPCheck {
+		interval, _ := time.ParseDuration(httpCheckConfig.Interval)
+		deregTTL := getDeregisterTTL(interval)
+
+		host, _, _ := net.SplitHostPort(node.Address)
+		healthCheckURI := strings.Replace(httpCheckConfig.HTTP, "{host}", host, 1)
+
+		check = &consul.AgentServiceCheck{
+			HTTP:                           healthCheckURI,
+			Interval:                       httpCheckConfig.Interval,
+			Timeout:                        httpCheckConfig.Timeout,
+			DeregisterCriticalServiceAfter: fmt.Sprintf("%v", deregTTL),
+		}
+
+		// if the TTL is greater than 0 create an associated check
+	} else if options.TTL > time.Duration(0) {
+		deregTTL := getDeregisterTTL(options.TTL)
+
+		check = &consul.AgentServiceCheck{
+			TTL:                            fmt.Sprintf("%v", options.TTL),
+			DeregisterCriticalServiceAfter: fmt.Sprintf("%v", deregTTL),
+		}
+	}
+
+	host, pt, _ := net.SplitHostPort(node.Address)
+	if host == "" {
+		host = node.Address
+	}
+	port, _ := strconv.Atoi(pt)
+
+	// register the service
+	asr := &consul.AgentServiceRegistration{
+		ID:      node.Id,
+		Name:    s.Name,
+		Tags:    tags,
+		Port:    port,
+		Address: host,
+		Meta:    node.Metadata,
+		Check:   check,
+	}
+
+	// Specify consul connect
+	if c.connect {
+		asr.Connect = &consul.AgentServiceConnect{
+			Native: true,
+		}
+	}
+
+	if err := c.Client().Agent().ServiceRegister(asr); err != nil {
+		return err
+	}
+
+	// save our hash and time check of the service
+	c.Lock()
+	c.register[s.Name] = h
+	c.lastChecked[s.Name] = time.Now()
+	c.Unlock()
+
+	// if the TTL is 0 we don't mess with the checks
+	if options.TTL == time.Duration(0) {
+		return nil
+	}
+
+	// pass the healthcheck
+	return c.Client().Agent().PassTTL("service:"+node.Id, "")
+}
+
+func (c *consulRegistry) GetService(name string, opts ...registry.GetOption) ([]*registry.Service, error) {
+	var rsp []*consul.ServiceEntry
+	var err error
+
+	// if we're connect enabled only get connect services
+	if c.connect {
+		rsp, _, err = c.Client().Health().Connect(name, "", false, c.queryOptions)
+	} else {
+		rsp, _, err = c.Client().Health().Service(name, "", false, c.queryOptions)
+	}
+	if err != nil {
+		return nil, err
+	}
+
+	serviceMap := map[string]*registry.Service{}
+
+	for _, s := range rsp {
+		if s.Service.Service != name {
+			continue
+		}
+
+		// version is now a tag
+		version, _ := decodeVersion(s.Service.Tags)
+		// service ID is now the node id
+		id := s.Service.ID
+		// key is always the version
+		key := version
+
+		// address is service address
+		address := s.Service.Address
+
+		// use node address
+		if len(address) == 0 {
+			address = s.Node.Address
+		}
+
+		svc, ok := serviceMap[key]
+		if !ok {
+			svc = &registry.Service{
+				Endpoints: decodeEndpoints(s.Service.Tags),
+				Name:      s.Service.Service,
+				Version:   version,
+			}
+			serviceMap[key] = svc
+		}
+
+		var del bool
+
+		for _, check := range s.Checks {
+			// delete the node if the status is critical
+			if check.Status == "critical" {
+				del = true
+				break
+			}
+		}
+
+		// if delete then skip the node
+		if del {
+			continue
+		}
+
+		svc.Nodes = append(svc.Nodes, &registry.Node{
+			Id:       id,
+			Address:  mnet.HostPort(address, s.Service.Port),
+			Metadata: decodeMetadata(s.Service.Tags),
+		})
+	}
+
+	var services []*registry.Service
+	for _, service := range serviceMap {
+		services = append(services, service)
+	}
+	return services, nil
+}
+
+func (c *consulRegistry) ListServices(opts ...registry.ListOption) ([]*registry.Service, error) {
+	rsp, _, err := c.Client().Catalog().Services(c.queryOptions)
+	if err != nil {
+		return nil, err
+	}
+
+	var services []*registry.Service
+
+	for service := range rsp {
+		services = append(services, &registry.Service{Name: service})
+	}
+
+	return services, nil
+}
+
+func (c *consulRegistry) Watch(opts ...registry.WatchOption) (registry.Watcher, error) {
+	return newConsulWatcher(c, opts...)
+}
+
+func (c *consulRegistry) String() string {
+	return "consul"
+}
+
+func (c *consulRegistry) Options() registry.Options {
+	return c.opts
+}
+
+func (c *consulRegistry) Client() *consul.Client {
+	if c.client != nil {
+		return c.client
+	}
+
+	for _, addr := range c.Address {
+		// set the address
+		c.config.Address = addr
+
+		// create a new client
+		tmpClient, _ := consul.NewClient(c.config)
+
+		// test the client
+		_, err := tmpClient.Agent().Host()
+		if err != nil {
+			continue
+		}
+
+		// set the client
+		c.client = tmpClient
+		return c.client
+	}
+
+	// set the default
+	var err error
+	c.client, err = consul.NewClient(c.config)
+	if err != nil {
+		// Log the error but return nil - caller should handle
+		// This maintains backward compatibility while surfacing the error
+		return nil
+	}
+
+	// return the client
+	return c.client
+}
+
+func NewConsulRegistry(opts ...registry.Option) registry.Registry {
+	cr := &consulRegistry{
+		opts:        registry.Options{},
+		register:    make(map[string]uint64),
+		lastChecked: make(map[string]time.Time),
+		queryOptions: &consul.QueryOptions{
+			AllowStale: true,
+		},
+	}
+	configure(cr, opts...)
+	return cr
+}

registry/consul/encoding.go

@@ -0,0 +1,171 @@
+package consul
+
+import (
+	"bytes"
+	"compress/zlib"
+	"encoding/hex"
+	"encoding/json"
+	"io"
+
+	"go-micro.dev/v6/registry"
+)
+
+func encode(buf []byte) string {
+	var b bytes.Buffer
+	defer b.Reset()
+
+	w := zlib.NewWriter(&b)
+	if _, err := w.Write(buf); err != nil {
+		return ""
+	}
+	w.Close()
+
+	return hex.EncodeToString(b.Bytes())
+}
+
+func decode(d string) []byte {
+	hr, err := hex.DecodeString(d)
+	if err != nil {
+		return nil
+	}
+
+	br := bytes.NewReader(hr)
+	zr, err := zlib.NewReader(br)
+	if err != nil {
+		return nil
+	}
+
+	rbuf, err := io.ReadAll(zr)
+	if err != nil {
+		return nil
+	}
+	zr.Close()
+
+	return rbuf
+}
+
+func encodeEndpoints(en []*registry.Endpoint) []string {
+	var tags []string
+	for _, e := range en {
+		if b, err := json.Marshal(e); err == nil {
+			tags = append(tags, "e-"+encode(b))
+		}
+	}
+	return tags
+}
+
+func decodeEndpoints(tags []string) []*registry.Endpoint {
+	var en []*registry.Endpoint
+
+	// use the first format you find
+	var ver byte
+
+	for _, tag := range tags {
+		if len(tag) == 0 || tag[0] != 'e' {
+			continue
+		}
+
+		// check version
+		if ver > 0 && tag[1] != ver {
+			continue
+		}
+
+		var e *registry.Endpoint
+		var buf []byte
+
+		// Old encoding was plain
+		if tag[1] == '=' {
+			buf = []byte(tag[2:])
+		}
+
+		// New encoding is hex
+		if tag[1] == '-' {
+			buf = decode(tag[2:])
+		}
+
+		if err := json.Unmarshal(buf, &e); err == nil {
+			en = append(en, e)
+		}
+
+		// set version
+		ver = tag[1]
+	}
+	return en
+}
+
+func encodeMetadata(md map[string]string) []string {
+	var tags []string
+	for k, v := range md {
+		if b, err := json.Marshal(map[string]string{
+			k: v,
+		}); err == nil {
+			// new encoding
+			tags = append(tags, "t-"+encode(b))
+		}
+	}
+	return tags
+}
+
+func decodeMetadata(tags []string) map[string]string {
+	md := make(map[string]string)
+
+	var ver byte
+
+	for _, tag := range tags {
+		if len(tag) == 0 || tag[0] != 't' {
+			continue
+		}
+
+		// check version
+		if ver > 0 && tag[1] != ver {
+			continue
+		}
+
+		var kv map[string]string
+		var buf []byte
+
+		// Old encoding was plain
+		if tag[1] == '=' {
+			buf = []byte(tag[2:])
+		}
+
+		// New encoding is hex
+		if tag[1] == '-' {
+			buf = decode(tag[2:])
+		}
+
+		// Now unmarshal
+		if err := json.Unmarshal(buf, &kv); err == nil {
+			for k, v := range kv {
+				md[k] = v
+			}
+		}
+
+		// set version
+		ver = tag[1]
+	}
+	return md
+}
+
+func encodeVersion(v string) []string {
+	return []string{"v-" + encode([]byte(v))}
+}
+
+func decodeVersion(tags []string) (string, bool) {
+	for _, tag := range tags {
+		if len(tag) < 2 || tag[0] != 'v' {
+			continue
+		}
+
+		// Old encoding was plain
+		if tag[1] == '=' {
+			return tag[2:], true
+		}
+
+		// New encoding is hex
+		if tag[1] == '-' {
+			return string(decode(tag[2:])), true
+		}
+	}
+	return "", false
+}

registry/consul/encoding_test.go

@@ -0,0 +1,147 @@
+package consul
+
+import (
+	"encoding/json"
+	"testing"
+
+	"go-micro.dev/v6/registry"
+)
+
+func TestEncodingEndpoints(t *testing.T) {
+	eps := []*registry.Endpoint{
+		{
+			Name: "endpoint1",
+			Request: &registry.Value{
+				Name: "request",
+				Type: "request",
+			},
+			Response: &registry.Value{
+				Name: "response",
+				Type: "response",
+			},
+			Metadata: map[string]string{
+				"foo1": "bar1",
+			},
+		},
+		{
+			Name: "endpoint2",
+			Request: &registry.Value{
+				Name: "request",
+				Type: "request",
+			},
+			Response: &registry.Value{
+				Name: "response",
+				Type: "response",
+			},
+			Metadata: map[string]string{
+				"foo2": "bar2",
+			},
+		},
+		{
+			Name: "endpoint3",
+			Request: &registry.Value{
+				Name: "request",
+				Type: "request",
+			},
+			Response: &registry.Value{
+				Name: "response",
+				Type: "response",
+			},
+			Metadata: map[string]string{
+				"foo3": "bar3",
+			},
+		},
+	}
+
+	testEp := func(ep *registry.Endpoint, enc string) {
+		// encode endpoint
+		e := encodeEndpoints([]*registry.Endpoint{ep})
+
+		// check there are two tags; old and new
+		if len(e) != 1 {
+			t.Fatalf("Expected 1 encoded tags, got %v", e)
+		}
+
+		// check old encoding
+		var seen bool
+
+		for _, en := range e {
+			if en == enc {
+				seen = true
+				break
+			}
+		}
+
+		if !seen {
+			t.Fatalf("Expected %s but not found", enc)
+		}
+
+		// decode
+		d := decodeEndpoints([]string{enc})
+		if len(d) == 0 {
+			t.Fatalf("Expected %v got %v", ep, d)
+		}
+
+		// check name
+		if d[0].Name != ep.Name {
+			t.Fatalf("Expected ep %s got %s", ep.Name, d[0].Name)
+		}
+
+		// check all the metadata exists
+		for k, v := range ep.Metadata {
+			if gv := d[0].Metadata[k]; gv != v {
+				t.Fatalf("Expected key %s val %s got val %s", k, v, gv)
+			}
+		}
+	}
+
+	for _, ep := range eps {
+		// JSON encoded
+		jencoded, err := json.Marshal(ep)
+		if err != nil {
+			t.Fatal(err)
+		}
+
+		// HEX encoded
+		hencoded := encode(jencoded)
+		// endpoint tag
+		hepTag := "e-" + hencoded
+		testEp(ep, hepTag)
+	}
+}
+
+func TestEncodingVersion(t *testing.T) {
+	testData := []struct {
+		decoded string
+		encoded string
+	}{
+		{"1.0.0", "v-789c32d433d03300040000ffff02ce00ee"},
+		{"latest", "v-789cca492c492d2e01040000ffff08cc028e"},
+	}
+
+	for _, data := range testData {
+		e := encodeVersion(data.decoded)
+
+		if e[0] != data.encoded {
+			t.Fatalf("Expected %s got %s", data.encoded, e)
+		}
+
+		d, ok := decodeVersion(e)
+		if !ok {
+			t.Fatalf("Unexpected %t for %s", ok, data.encoded)
+		}
+
+		if d != data.decoded {
+			t.Fatalf("Expected %s got %s", data.decoded, d)
+		}
+
+		d, ok = decodeVersion([]string{data.encoded})
+		if !ok {
+			t.Fatalf("Unexpected %t for %s", ok, data.encoded)
+		}
+
+		if d != data.decoded {
+			t.Fatalf("Expected %s got %s", data.decoded, d)
+		}
+	}
+}

registry/consul/options.go

@@ -0,0 +1,111 @@
+package consul
+
+import (
+	"context"
+	"fmt"
+	"time"
+
+	consul "github.com/hashicorp/consul/api"
+	"go-micro.dev/v6/registry"
+)
+
+// Define a custom type for context keys to avoid collisions.
+type contextKey string
+
+const consulConnectKey contextKey = "consul_connect"
+const consulConfigKey contextKey = "consul_config"
+const consulAllowStaleKey contextKey = "consul_allow_stale"
+const consulQueryOptionsKey contextKey = "consul_query_options"
+const consulTCPCheckKey contextKey = "consul_tcp_check"
+const consulHTTPCheckConfigKey contextKey = "consul_http_check_config"
+
+// Connect specifies services should be registered as Consul Connect services.
+func Connect() registry.Option {
+	return func(o *registry.Options) {
+		if o.Context == nil {
+			o.Context = context.Background()
+		}
+		o.Context = context.WithValue(o.Context, consulConnectKey, true)
+	}
+}
+
+func Config(c *consul.Config) registry.Option {
+	return func(o *registry.Options) {
+		if o.Context == nil {
+			o.Context = context.Background()
+		}
+		o.Context = context.WithValue(o.Context, consulConfigKey, c)
+	}
+}
+
+// AllowStale sets whether any Consul server (non-leader) can service
+// a read. This allows for lower latency and higher throughput
+// at the cost of potentially stale data.
+// Works similar to Consul DNS Config option [1].
+// Defaults to true.
+//
+// [1] https://www.consul.io/docs/agent/options.html#allow_stale
+func AllowStale(v bool) registry.Option {
+	return func(o *registry.Options) {
+		if o.Context == nil {
+			o.Context = context.Background()
+		}
+		o.Context = context.WithValue(o.Context, consulAllowStaleKey, v)
+	}
+}
+
+// QueryOptions specifies the QueryOptions to be used when calling
+// Consul. See `Consul API` for more information [1].
+//
+// [1] https://godoc.org/github.com/hashicorp/consul/api#QueryOptions
+func QueryOptions(q *consul.QueryOptions) registry.Option {
+	return func(o *registry.Options) {
+		if q == nil {
+			return
+		}
+		if o.Context == nil {
+			o.Context = context.Background()
+		}
+		o.Context = context.WithValue(o.Context, consulQueryOptionsKey, q)
+	}
+}
+
+// TCPCheck will tell the service provider to check the service address
+// and port every `t` interval. It will enabled only if `t` is greater than 0.
+// See `TCP + Interval` for more information [1].
+//
+// [1] https://www.consul.io/docs/agent/checks.html
+func TCPCheck(t time.Duration) registry.Option {
+	return func(o *registry.Options) {
+		if t <= time.Duration(0) {
+			return
+		}
+		if o.Context == nil {
+			o.Context = context.Background()
+		}
+		o.Context = context.WithValue(o.Context, consulTCPCheckKey, t)
+	}
+}
+
+// HTTPCheck will tell the service provider to invoke the health check endpoint
+// with an interval and timeout. It will be enabled only if interval and
+// timeout are greater than 0.
+// See `HTTP + Interval` for more information [1].
+//
+// [1] https://www.consul.io/docs/agent/checks.html
+func HTTPCheck(protocol, port, httpEndpoint string, interval, timeout time.Duration) registry.Option {
+	return func(o *registry.Options) {
+		if interval <= time.Duration(0) || timeout <= time.Duration(0) {
+			return
+		}
+		if o.Context == nil {
+			o.Context = context.Background()
+		}
+		check := consul.AgentServiceCheck{
+			HTTP:     fmt.Sprintf("%s://{host}:%s%s", protocol, port, httpEndpoint),
+			Interval: fmt.Sprintf("%v", interval),
+			Timeout:  fmt.Sprintf("%v", timeout),
+		}
+		o.Context = context.WithValue(o.Context, consulHTTPCheckConfigKey, check)
+	}
+}

registry/consul/registry_test.go

@@ -0,0 +1,208 @@
+package consul
+
+import (
+	"bytes"
+	"encoding/json"
+	"errors"
+	"net"
+	"net/http"
+	"testing"
+	"time"
+
+	consul "github.com/hashicorp/consul/api"
+	"go-micro.dev/v6/registry"
+)
+
+type mockRegistry struct {
+	body   []byte
+	status int
+	err    error
+	url    string
+}
+
+func encodeData(obj interface{}) ([]byte, error) {
+	buf := bytes.NewBuffer(nil)
+	enc := json.NewEncoder(buf)
+	if err := enc.Encode(obj); err != nil {
+		return nil, err
+	}
+	return buf.Bytes(), nil
+}
+
+func newMockServer(rg *mockRegistry, l net.Listener) error {
+	mux := http.NewServeMux()
+	mux.HandleFunc(rg.url, func(w http.ResponseWriter, r *http.Request) {
+		if rg.err != nil {
+			http.Error(w, rg.err.Error(), http.StatusInternalServerError)
+			return
+		}
+		w.WriteHeader(rg.status)
+		w.Write(rg.body)
+	})
+	return http.Serve(l, mux)
+}
+
+func newConsulTestRegistry(r *mockRegistry) (*consulRegistry, func()) {
+	l, err := net.Listen("tcp", "localhost:0")
+	if err != nil {
+		// blurgh?!!
+		panic(err.Error())
+	}
+	cfg := consul.DefaultConfig()
+	cfg.Address = l.Addr().String()
+
+	go newMockServer(r, l)
+
+	var cr = &consulRegistry{
+		config:      cfg,
+		Address:     []string{cfg.Address},
+		opts:        registry.Options{},
+		register:    make(map[string]uint64),
+		lastChecked: make(map[string]time.Time),
+		queryOptions: &consul.QueryOptions{
+			AllowStale: true,
+		},
+	}
+	cr.Client()
+
+	return cr, func() {
+		l.Close()
+	}
+}
+
+func newServiceList(svc []*consul.ServiceEntry) []byte {
+	bts, _ := encodeData(svc)
+	return bts
+}
+
+func TestConsul_GetService_WithError(t *testing.T) {
+	cr, cl := newConsulTestRegistry(&mockRegistry{
+		err: errors.New("client-error"),
+		url: "/v1/health/service/service-name",
+	})
+	defer cl()
+
+	if _, err := cr.GetService("test-service"); err == nil {
+		t.Fatalf("Expected error not to be `nil`")
+	}
+}
+
+func TestConsul_GetService_WithHealthyServiceNodes(t *testing.T) {
+	// warning is still seen as healthy, critical is not
+	svcs := []*consul.ServiceEntry{
+		newServiceEntry(
+			"node-name-1", "node-address-1", "service-name", "v1.0.0",
+			[]*consul.HealthCheck{
+				newHealthCheck("node-name-1", "service-name", "passing"),
+				newHealthCheck("node-name-1", "service-name", "warning"),
+			},
+		),
+		newServiceEntry(
+			"node-name-2", "node-address-2", "service-name", "v1.0.0",
+			[]*consul.HealthCheck{
+				newHealthCheck("node-name-2", "service-name", "passing"),
+				newHealthCheck("node-name-2", "service-name", "warning"),
+			},
+		),
+	}
+
+	cr, cl := newConsulTestRegistry(&mockRegistry{
+		status: 200,
+		body:   newServiceList(svcs),
+		url:    "/v1/health/service/service-name",
+	})
+	defer cl()
+
+	svc, err := cr.GetService("service-name")
+	if err != nil {
+		t.Fatal("Unexpected error", err)
+	}
+
+	if exp, act := 1, len(svc); exp != act {
+		t.Fatalf("Expected len of svc to be `%d`, got `%d`.", exp, act)
+	}
+
+	if exp, act := 2, len(svc[0].Nodes); exp != act {
+		t.Fatalf("Expected len of nodes to be `%d`, got `%d`.", exp, act)
+	}
+}
+
+func TestConsul_GetService_WithUnhealthyServiceNode(t *testing.T) {
+	// warning is still seen as healthy, critical is not
+	svcs := []*consul.ServiceEntry{
+		newServiceEntry(
+			"node-name-1", "node-address-1", "service-name", "v1.0.0",
+			[]*consul.HealthCheck{
+				newHealthCheck("node-name-1", "service-name", "passing"),
+				newHealthCheck("node-name-1", "service-name", "warning"),
+			},
+		),
+		newServiceEntry(
+			"node-name-2", "node-address-2", "service-name", "v1.0.0",
+			[]*consul.HealthCheck{
+				newHealthCheck("node-name-2", "service-name", "passing"),
+				newHealthCheck("node-name-2", "service-name", "critical"),
+			},
+		),
+	}
+
+	cr, cl := newConsulTestRegistry(&mockRegistry{
+		status: 200,
+		body:   newServiceList(svcs),
+		url:    "/v1/health/service/service-name",
+	})
+	defer cl()
+
+	svc, err := cr.GetService("service-name")
+	if err != nil {
+		t.Fatal("Unexpected error", err)
+	}
+
+	if exp, act := 1, len(svc); exp != act {
+		t.Fatalf("Expected len of svc to be `%d`, got `%d`.", exp, act)
+	}
+
+	if exp, act := 1, len(svc[0].Nodes); exp != act {
+		t.Fatalf("Expected len of nodes to be `%d`, got `%d`.", exp, act)
+	}
+}
+
+func TestConsul_GetService_WithUnhealthyServiceNodes(t *testing.T) {
+	// warning is still seen as healthy, critical is not
+	svcs := []*consul.ServiceEntry{
+		newServiceEntry(
+			"node-name-1", "node-address-1", "service-name", "v1.0.0",
+			[]*consul.HealthCheck{
+				newHealthCheck("node-name-1", "service-name", "passing"),
+				newHealthCheck("node-name-1", "service-name", "critical"),
+			},
+		),
+		newServiceEntry(
+			"node-name-2", "node-address-2", "service-name", "v1.0.0",
+			[]*consul.HealthCheck{
+				newHealthCheck("node-name-2", "service-name", "passing"),
+				newHealthCheck("node-name-2", "service-name", "critical"),
+			},
+		),
+	}
+
+	cr, cl := newConsulTestRegistry(&mockRegistry{
+		status: 200,
+		body:   newServiceList(svcs),
+		url:    "/v1/health/service/service-name",
+	})
+	defer cl()
+
+	svc, err := cr.GetService("service-name")
+	if err != nil {
+		t.Fatal("Unexpected error", err)
+	}
+
+	if exp, act := 1, len(svc); exp != act {
+		t.Fatalf("Expected len of svc to be `%d`, got `%d`.", exp, act)
+	}
+
+	if exp, act := 0, len(svc[0].Nodes); exp != act {
+		t.Fatalf("Expected len of nodes to be `%d`, got `%d`.", exp, act)
+	}
+}

registry/consul/watcher.go

@@ -0,0 +1,232 @@
+package consul
+
+import (
+	"sync"
+
+	"github.com/hashicorp/consul/api"
+	"github.com/hashicorp/consul/api/watch"
+	mnet "go-micro.dev/v6/internal/util/net"
+	regutil "go-micro.dev/v6/internal/util/registry"
+	"go-micro.dev/v6/registry"
+)
+
+type consulWatcher struct {
+	r        *consulRegistry
+	wo       registry.WatchOptions
+	wp       *watch.Plan
+	watchers map[string]*watch.Plan
+
+	next chan *registry.Result
+	exit chan bool
+
+	sync.RWMutex
+	services map[string][]*registry.Service
+}
+
+func newConsulWatcher(cr *consulRegistry, opts ...registry.WatchOption) (registry.Watcher, error) {
+	var wo registry.WatchOptions
+	for _, o := range opts {
+		o(&wo)
+	}
+
+	cw := &consulWatcher{
+		r:        cr,
+		wo:       wo,
+		exit:     make(chan bool),
+		next:     make(chan *registry.Result, 10),
+		watchers: make(map[string]*watch.Plan),
+		services: make(map[string][]*registry.Service),
+	}
+
+	wp, err := watch.Parse(map[string]interface{}{
+		"service": wo.Service,
+		"type":    "service",
+	})
+	if err != nil {
+		return nil, err
+	}
+
+	wp.Handler = cw.serviceHandler
+	go func() { _ = wp.RunWithClientAndHclog(cr.Client(), wp.Logger) }()
+	cw.wp = wp
+
+	return cw, nil
+}
+
+func (cw *consulWatcher) serviceHandler(idx uint64, data interface{}) {
+	entries, ok := data.([]*api.ServiceEntry)
+	if !ok {
+		return
+	}
+
+	serviceMap := map[string]*registry.Service{}
+	serviceName := ""
+
+	for _, e := range entries {
+		serviceName = e.Service.Service
+		// version is now a tag
+		version, _ := decodeVersion(e.Service.Tags)
+		// service ID is now the node id
+		id := e.Service.ID
+		// key is always the version
+		key := version
+		// address is service address
+		address := e.Service.Address
+
+		// use node address
+		if len(address) == 0 {
+			address = e.Node.Address
+		}
+
+		svc, ok := serviceMap[key]
+		if !ok {
+			svc = &registry.Service{
+				Endpoints: decodeEndpoints(e.Service.Tags),
+				Name:      e.Service.Service,
+				Version:   version,
+			}
+			serviceMap[key] = svc
+		}
+
+		var del bool
+
+		for _, check := range e.Checks {
+			// delete the node if the status is critical
+			if check.Status == "critical" {
+				del = true
+				break
+			}
+		}
+
+		// if delete then skip the node
+		if del {
+			continue
+		}
+
+		svc.Nodes = append(svc.Nodes, &registry.Node{
+			Id:       id,
+			Address:  mnet.HostPort(address, e.Service.Port),
+			Metadata: decodeMetadata(e.Service.Tags),
+		})
+	}
+
+	cw.RLock()
+	// make a copy
+	rservices := make(map[string][]*registry.Service)
+	for k, v := range cw.services {
+		rservices[k] = v
+	}
+	cw.RUnlock()
+
+	var newServices []*registry.Service
+
+	// serviceMap is the new set of services keyed by name+version
+	for _, newService := range serviceMap {
+		// append to the new set of cached services
+		newServices = append(newServices, newService)
+
+		// check if the service exists in the existing cache
+		oldServices, ok := rservices[serviceName]
+		if !ok {
+			// does not exist? then we're creating brand new entries
+			cw.next <- &registry.Result{Action: "create", Service: newService}
+			continue
+		}
+
+		// service exists. ok let's figure out what to update and delete version wise
+		action := "create"
+
+		for _, oldService := range oldServices {
+			// does this version exist?
+			// no? then default to create
+			if oldService.Version != newService.Version {
+				continue
+			}
+
+			// yes? then it's an update
+			action = "update"
+
+			var nodes []*registry.Node
+			// check the old nodes to see if they've been deleted
+			for _, oldNode := range oldService.Nodes {
+				var seen bool
+				for _, newNode := range newService.Nodes {
+					if newNode.Id == oldNode.Id {
+						seen = true
+						break
+					}
+				}
+				// does the old node exist in the new set of nodes
+				// no? then delete that shit
+				if !seen {
+					nodes = append(nodes, oldNode)
+				}
+			}
+
+			// it's an update rather than creation
+			if len(nodes) > 0 {
+				delService := regutil.CopyService(oldService)
+				delService.Nodes = nodes
+				cw.next <- &registry.Result{Action: "delete", Service: delService}
+			}
+		}
+
+		cw.next <- &registry.Result{Action: action, Service: newService}
+	}
+
+	// Now check old versions that may not be in new services map
+	for _, old := range rservices[serviceName] {
+		// old version does not exist in new version map
+		// kill it with fire!
+		if _, ok := serviceMap[old.Version]; !ok {
+			cw.next <- &registry.Result{Action: "delete", Service: old}
+		}
+	}
+
+	// there are no services in the service, empty all services
+	if len(rservices) != 0 && serviceName == "" {
+		for _, services := range rservices {
+			for _, service := range services {
+				cw.next <- &registry.Result{Action: "delete", Service: service}
+			}
+		}
+	}
+
+	cw.Lock()
+	cw.services[serviceName] = newServices
+	cw.Unlock()
+}
+
+func (cw *consulWatcher) Next() (*registry.Result, error) {
+	select {
+	case <-cw.exit:
+		return nil, registry.ErrWatcherStopped
+	case r, ok := <-cw.next:
+		if !ok {
+			return nil, registry.ErrWatcherStopped
+		}
+		return r, nil
+	}
+}
+
+func (cw *consulWatcher) Stop() {
+	select {
+	case <-cw.exit:
+		return
+	default:
+		close(cw.exit)
+		if cw.wp == nil {
+			return
+		}
+		cw.wp.Stop()
+
+		// drain results
+		for {
+			select {
+			case <-cw.next:
+			default:
+				return
+			}
+		}
+	}
+}

registry/consul/watcher_test.go

@@ -0,0 +1,86 @@
+package consul
+
+import (
+	"testing"
+
+	"github.com/hashicorp/consul/api"
+	"go-micro.dev/v6/registry"
+)
+
+func TestHealthyServiceHandler(t *testing.T) {
+	watcher := newWatcher()
+	serviceEntry := newServiceEntry(
+		"node-name", "node-address", "service-name", "v1.0.0",
+		[]*api.HealthCheck{
+			newHealthCheck("node-name", "service-name", "passing"),
+		},
+	)
+
+	watcher.serviceHandler(1234, []*api.ServiceEntry{serviceEntry})
+
+	if len(watcher.services["service-name"][0].Nodes) != 1 {
+		t.Errorf("Expected length of the service nodes to be 1")
+	}
+}
+
+func TestUnhealthyServiceHandler(t *testing.T) {
+	watcher := newWatcher()
+	serviceEntry := newServiceEntry(
+		"node-name", "node-address", "service-name", "v1.0.0",
+		[]*api.HealthCheck{
+			newHealthCheck("node-name", "service-name", "critical"),
+		},
+	)
+
+	watcher.serviceHandler(1234, []*api.ServiceEntry{serviceEntry})
+
+	if len(watcher.services["service-name"][0].Nodes) != 0 {
+		t.Errorf("Expected length of the service nodes to be 0")
+	}
+}
+
+func TestUnhealthyNodeServiceHandler(t *testing.T) {
+	watcher := newWatcher()
+	serviceEntry := newServiceEntry(
+		"node-name", "node-address", "service-name", "v1.0.0",
+		[]*api.HealthCheck{
+			newHealthCheck("node-name", "service-name", "passing"),
+			newHealthCheck("node-name", "serfHealth", "critical"),
+		},
+	)
+
+	watcher.serviceHandler(1234, []*api.ServiceEntry{serviceEntry})
+
+	if len(watcher.services["service-name"][0].Nodes) != 0 {
+		t.Errorf("Expected length of the service nodes to be 0")
+	}
+}
+
+func newWatcher() *consulWatcher {
+	return &consulWatcher{
+		exit:     make(chan bool),
+		next:     make(chan *registry.Result, 10),
+		services: make(map[string][]*registry.Service),
+	}
+}
+
+func newHealthCheck(node, name, status string) *api.HealthCheck {
+	return &api.HealthCheck{
+		Node:        node,
+		Name:        name,
+		Status:      status,
+		ServiceName: name,
+	}
+}
+
+func newServiceEntry(node, address, name, version string, checks []*api.HealthCheck) *api.ServiceEntry {
+	return &api.ServiceEntry{
+		Node: &api.Node{Node: node, Address: name},
+		Service: &api.AgentService{
+			Service: name,
+			Address: address,
+			Tags:    encodeVersion(version),
+		},
+		Checks: checks,
+	}
+}

registry/etcd/PERFORMANCE.md

@@ -0,0 +1,160 @@
+# Etcd Registry Performance Improvements
+
+This document describes the improvements made to address etcd authentication performance issues and cache penetration problems.
+
+## Problem Statement
+
+### Background
+When etcd server authentication is enabled, a serious performance bottleneck can occur at scale. This was observed in production environments with 4000+ service pods.
+
+### Issues Identified
+
+#### 1. High Authentication QPS
+- **Root Cause**: The etcd registry used `KeepAliveOnce` for lease renewal, which requires a new authentication request for each call
+- **Impact**: With 4000+ pods registering every 30s (default RegisterInterval), this creates ~110 QPS of authentication requests
+- **Limitation**: A typical 3-node etcd cluster (64C 256G HDD) can only handle ~100 QPS for authentication
+- **Result**: Authentication requests overwhelm etcd, causing KeepAlive failures and service deregistrations
+
+#### 2. Cache Penetration
+- **Trigger**: When KeepAlive fails, services deregister from etcd
+- **Chain Reaction**: 
+  1. Registry watcher detects deletions
+  2. Cache is cleared based on delete events
+  3. All subsequent service lookups hit etcd directly (cache miss)
+  4. Etcd is already overloaded, causing more failures
+- **Result**: Cascading failure where all gRPC requests fail
+
+## Solution
+
+### 1. Use Long-Lived KeepAlive Channels
+
+**Change**: Replaced `KeepAliveOnce` with `KeepAlive`
+
+**Implementation**:
+- Added keepalive channel management to `etcdRegistry` struct
+- Created `startKeepAlive()` method that establishes a long-lived keepalive stream
+- Modified `registerNode()` to reuse existing keepalive channels
+- Added `stopKeepAlive()` for proper cleanup on deregistration
+
+**Benefits**:
+- **97% reduction in auth requests**: From ~110 QPS to ~3-4 QPS (4000 pods / TTL period)
+- **Single authentication per lease**: KeepAlive authenticates once when establishing the stream
+- **Automatic renewal**: Etcd sends keepalive responses automatically through the channel
+
+**Code Changes**:
+```go
+// Before: New auth request every heartbeat
+if _, err := e.client.KeepAliveOnce(context.TODO(), leaseID); err != nil {
+    // handle error
+}
+
+// After: Single auth request, reused channel
+if err := e.startKeepAlive(s.Name+node.Id, leaseID); err != nil {
+    // handle error
+}
+```
+
+### 2. Verify Cache Penetration Protection
+
+**Existing Protection**: The registry cache already uses `singleflight` pattern to prevent stampede
+
+**How it Works**:
+- When cache expires/is empty, first request triggers etcd query
+- Concurrent requests for same service wait for the first request to complete
+- All waiting requests receive the same result
+- Only ONE etcd query happens regardless of concurrent request count
+
+**Additional Safety**:
+- Stale cache is returned when etcd fails (if cache data exists)
+- Prevents cascading failures by avoiding repeated failed requests to etcd
+
+**Verification**:
+Added comprehensive tests to confirm this behavior works correctly under load.
+
+## Performance Impact
+
+### Authentication Load Reduction
+- **Before**: 4000 pods × (1 auth / 30s) = ~133 auth/sec
+- **After**: 4000 pods × (1 auth / lease_ttl) ≈ 3-4 auth/sec (assuming 15min lease TTL)
+- **Reduction**: ~97%
+
+### Cache Penetration Prevention
+- **Before**: When cache clears, 1000s of concurrent requests → 1000s of etcd queries
+- **After**: When cache clears, 1000s of concurrent requests → 1 etcd query (singleflight)
+- **Reduction**: ~99.9%
+
+## Testing
+
+### Unit Tests
+1. **TestKeepAliveManagement**: Validates keepalive lifecycle
+   - Verifies channels are created on registration
+   - Confirms channels are cleaned up on deregistration
+   
+2. **TestKeepAliveReducesAuthRequests**: Confirms channel reuse
+   - Multiple re-registrations use the same keepalive channel
+   - Validates auth request reduction
+
+3. **TestKeepAliveChannelReconnection**: Tests error handling
+   - Verifies proper cleanup when keepalive channel closes
+
+4. **TestSingleflightPreventsStampede**: Validates cache behavior
+   - 10 concurrent requests → 1 etcd query
+   
+5. **TestStaleCacheOnError**: Confirms graceful degradation
+   - Returns stale cache when etcd fails
+
+6. **TestCachePenetrationPrevention**: End-to-end validation
+   - 50 concurrent requests during etcd failure → 1 etcd query
+   - All requests receive stale cache
+
+### Integration Tests
+- CI workflow runs tests against real etcd instance
+- Validates behavior with actual etcd keepalive channels
+- Tests run with race detector enabled
+
+## Migration Guide
+
+### For Library Users
+No code changes required! The improvements are transparent:
+- Existing applications automatically benefit from reduced auth load
+- No API changes to `registry.Registry` interface
+
+### For Plugin Developers
+If you maintain a custom registry plugin:
+- Consider implementing long-lived keepalive channels
+- Ensure your cache implementation uses singleflight pattern
+- Add tests for concurrent access patterns
+
+## Monitoring Recommendations
+
+### Key Metrics to Track
+1. **Etcd Authentication Rate**: Should drop by ~97%
+2. **Etcd Query Rate**: Monitor for stampede prevention
+3. **Service Registration Success Rate**: Should improve under load
+4. **Cache Hit Rate**: Should remain high even during etcd issues
+
+### Expected Behavior
+- **Normal Operation**: Low auth QPS, high cache hit rate
+- **During Etcd Issues**: Stale cache served, limited etcd queries
+- **After Recovery**: Cache refreshes gradually, no stampede
+
+## Related Issues
+
+- Original Issue: [BUG] etcd authentication performance issue and registry cache penetration
+- Etcd Documentation: https://etcd.io/docs/latest/learning/api/#lease-keepalive
+- Singleflight Pattern: https://pkg.go.dev/golang.org/x/sync/singleflight
+
+## Security Considerations
+
+- **No Authentication Bypass**: Changes only reduce frequency, not security
+- **Proper Cleanup**: Keepalive channels properly closed on deregistration
+- **Race Condition Free**: All map operations properly synchronized
+- **No Resource Leaks**: Goroutines terminate when channels close
+
+## Future Enhancements
+
+Potential improvements for consideration:
+1. **Adaptive TTL**: Adjust keepalive frequency based on load
+2. **Circuit Breaker**: Temporarily stop queries when etcd is degraded
+3. **Metrics**: Expose keepalive channel count, auth rate, etc.
+4. **Backoff**: Exponential backoff on keepalive failures

registry/etcd/etcd.go

@@ -0,0 +1,532 @@
+// Package etcd provides an etcd service registry
+package etcd
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"net"
+	"os"
+	"path"
+	"sort"
+	"strings"
+	"sync"
+	"time"
+
+	hash "github.com/mitchellh/hashstructure"
+	mtls "go-micro.dev/v6/internal/util/tls"
+	"go-micro.dev/v6/logger"
+	"go-micro.dev/v6/registry"
+	"go.etcd.io/etcd/api/v3/v3rpc/rpctypes"
+	clientv3 "go.etcd.io/etcd/client/v3"
+	"go.uber.org/zap"
+)
+
+var (
+	prefix = "/micro/registry/"
+)
+
+type etcdRegistry struct {
+	client  *clientv3.Client
+	options registry.Options
+
+	sync.RWMutex
+	register      map[string]uint64
+	leases        map[string]clientv3.LeaseID
+	keepaliveChs  map[string]<-chan *clientv3.LeaseKeepAliveResponse
+	keepaliveStop map[string]chan bool
+}
+
+func NewEtcdRegistry(opts ...registry.Option) registry.Registry {
+	e := &etcdRegistry{
+		options:       registry.Options{},
+		register:      make(map[string]uint64),
+		leases:        make(map[string]clientv3.LeaseID),
+		keepaliveChs:  make(map[string]<-chan *clientv3.LeaseKeepAliveResponse),
+		keepaliveStop: make(map[string]chan bool),
+	}
+	username, password := os.Getenv("ETCD_USERNAME"), os.Getenv("ETCD_PASSWORD")
+	if len(username) > 0 && len(password) > 0 {
+		opts = append(opts, Auth(username, password))
+	}
+	address := os.Getenv("MICRO_REGISTRY_ADDRESS")
+	if len(address) > 0 {
+		opts = append(opts, registry.Addrs(address))
+	}
+	_ = configure(e, opts...)
+	return e
+}
+
+func configure(e *etcdRegistry, opts ...registry.Option) error {
+	config := clientv3.Config{
+		Endpoints: []string{"127.0.0.1:2379"},
+	}
+
+	for _, o := range opts {
+		o(&e.options)
+	}
+
+	if e.options.Timeout == 0 {
+		e.options.Timeout = 5 * time.Second
+	}
+
+	if e.options.Logger == nil {
+		e.options.Logger = logger.DefaultLogger
+	}
+
+	config.DialTimeout = e.options.Timeout
+
+	if e.options.Secure || e.options.TLSConfig != nil {
+		tlsConfig := e.options.TLSConfig
+		if tlsConfig == nil {
+			// Use environment-based config - secure by default
+			tlsConfig = mtls.Config()
+		}
+
+		config.TLS = tlsConfig
+	}
+
+	if e.options.Context != nil {
+		u, ok := e.options.Context.Value(authKey{}).(*authCreds)
+		if ok {
+			config.Username = u.Username
+			config.Password = u.Password
+		}
+		cfg, ok := e.options.Context.Value(logConfigKey{}).(*zap.Config)
+		if ok && cfg != nil {
+			config.LogConfig = cfg
+		}
+	}
+
+	var cAddrs []string
+
+	for _, address := range e.options.Addrs {
+		if len(address) == 0 {
+			continue
+		}
+		addr, port, err := net.SplitHostPort(address)
+		if ae, ok := err.(*net.AddrError); ok && ae.Err == "missing port in address" {
+			port = "2379"
+			addr = address
+			cAddrs = append(cAddrs, net.JoinHostPort(addr, port))
+		} else if err == nil {
+			cAddrs = append(cAddrs, net.JoinHostPort(addr, port))
+		}
+	}
+
+	// if we got addrs then we'll update
+	if len(cAddrs) > 0 {
+		config.Endpoints = cAddrs
+	}
+
+	cli, err := clientv3.New(config)
+	if err != nil {
+		return err
+	}
+	e.client = cli
+	return nil
+}
+
+func encode(s *registry.Service) string {
+	b, _ := json.Marshal(s)
+	return string(b)
+}
+
+func decode(ds []byte) *registry.Service {
+	var s *registry.Service
+	_ = json.Unmarshal(ds, &s)
+	return s
+}
+
+func nodePath(s, id string) string {
+	service := strings.ReplaceAll(s, "/", "-")
+	node := strings.ReplaceAll(id, "/", "-")
+	return path.Join(prefix, service, node)
+}
+
+func servicePath(s string) string {
+	return path.Join(prefix, strings.ReplaceAll(s, "/", "-"))
+}
+
+func (e *etcdRegistry) Init(opts ...registry.Option) error {
+	return configure(e, opts...)
+}
+
+func (e *etcdRegistry) Options() registry.Options {
+	return e.options
+}
+
+func (e *etcdRegistry) registerNode(s *registry.Service, node *registry.Node, opts ...registry.RegisterOption) error {
+	if len(s.Nodes) == 0 {
+		return errors.New("require at least one node")
+	}
+
+	// check existing lease cache
+	e.RLock()
+	leaseID, ok := e.leases[s.Name+node.Id]
+	e.RUnlock()
+
+	log := e.options.Logger
+
+	if !ok {
+		// missing lease, check if the key exists
+		ctx, cancel := context.WithTimeout(context.Background(), e.options.Timeout)
+		defer cancel()
+
+		// look for the existing key
+		rsp, err := e.client.Get(ctx, nodePath(s.Name, node.Id), clientv3.WithSerializable())
+		if err != nil {
+			return err
+		}
+
+		// get the existing lease
+		for _, kv := range rsp.Kvs {
+			if kv.Lease > 0 {
+				leaseID = clientv3.LeaseID(kv.Lease)
+
+				// decode the existing node
+				srv := decode(kv.Value)
+				if srv == nil || len(srv.Nodes) == 0 {
+					continue
+				}
+
+				// create hash of service; uint64
+				h, err := hash.Hash(srv.Nodes[0], nil)
+				if err != nil {
+					continue
+				}
+
+				// save the info
+				e.Lock()
+				e.leases[s.Name+node.Id] = leaseID
+				e.register[s.Name+node.Id] = h
+				e.Unlock()
+
+				break
+			}
+		}
+	}
+
+	var leaseNotFound bool
+
+	// renew the lease if it exists
+	if leaseID > 0 {
+		log.Logf(logger.TraceLevel, "Renewing existing lease for %s %d", s.Name, leaseID)
+
+		// Start long-lived keepalive channel to reduce auth requests
+		// startKeepAlive checks if already running and is atomic
+		if err := e.startKeepAlive(s.Name+node.Id, leaseID); err != nil {
+			if err != rpctypes.ErrLeaseNotFound {
+				return err
+			}
+
+			log.Logf(logger.TraceLevel, "Lease not found for %s %d", s.Name, leaseID)
+			// lease not found do register
+			leaseNotFound = true
+		}
+	}
+
+	// create hash of service; uint64
+	h, err := hash.Hash(node, nil)
+	if err != nil {
+		return err
+	}
+
+	// get existing hash for the service node
+	e.Lock()
+	v, ok := e.register[s.Name+node.Id]
+	e.Unlock()
+
+	// the service is unchanged, skip registering
+	if ok && v == h && !leaseNotFound {
+		log.Logf(logger.TraceLevel, "Service %s node %s unchanged skipping registration", s.Name, node.Id)
+		return nil
+	}
+
+	service := &registry.Service{
+		Name:      s.Name,
+		Version:   s.Version,
+		Metadata:  s.Metadata,
+		Endpoints: s.Endpoints,
+		Nodes:     []*registry.Node{node},
+	}
+
+	var options registry.RegisterOptions
+	for _, o := range opts {
+		o(&options)
+	}
+
+	ctx, cancel := context.WithTimeout(context.Background(), e.options.Timeout)
+	defer cancel()
+
+	var lgr *clientv3.LeaseGrantResponse
+	if options.TTL.Seconds() > 0 {
+		// get a lease used to expire keys since we have a ttl
+		lgr, err = e.client.Grant(ctx, int64(options.TTL.Seconds()))
+		if err != nil {
+			return err
+		}
+	}
+
+	// create an entry for the node
+	if lgr != nil {
+		log.Logf(logger.TraceLevel, "Registering %s id %s with lease %v and leaseID %v and ttl %v", service.Name, node.Id, lgr, lgr.ID, options.TTL)
+		_, err = e.client.Put(ctx, nodePath(service.Name, node.Id), encode(service), clientv3.WithLease(lgr.ID))
+	} else {
+		log.Logf(logger.TraceLevel, "Registering %s id %s ttl %v", service.Name, node.Id, options.TTL)
+		_, err = e.client.Put(ctx, nodePath(service.Name, node.Id), encode(service))
+	}
+	if err != nil {
+		return err
+	}
+
+	e.Lock()
+	// save our hash of the service
+	e.register[s.Name+node.Id] = h
+	// save our leaseID of the service
+	if lgr != nil {
+		e.leases[s.Name+node.Id] = lgr.ID
+	}
+	e.Unlock()
+
+	// start keepalive for the new lease
+	if lgr != nil {
+		if err := e.startKeepAlive(s.Name+node.Id, lgr.ID); err != nil {
+			log.Logf(logger.WarnLevel, "Failed to start keepalive for %s %s: %v", s.Name, node.Id, err)
+		}
+	}
+
+	return nil
+}
+
+func (e *etcdRegistry) Deregister(s *registry.Service, opts ...registry.DeregisterOption) error {
+	if len(s.Nodes) == 0 {
+		return errors.New("require at least one node")
+	}
+
+	for _, node := range s.Nodes {
+		key := s.Name + node.Id
+
+		e.Lock()
+		// delete our hash of the service
+		delete(e.register, key)
+		// delete our lease of the service
+		delete(e.leases, key)
+		e.Unlock()
+
+		// stop keepalive goroutine
+		e.stopKeepAlive(key)
+
+		ctx, cancel := context.WithTimeout(context.Background(), e.options.Timeout)
+		defer cancel()
+
+		e.options.Logger.Logf(logger.TraceLevel, "Deregistering %s id %s", s.Name, node.Id)
+		_, err := e.client.Delete(ctx, nodePath(s.Name, node.Id))
+		if err != nil {
+			return err
+		}
+	}
+
+	return nil
+}
+
+func (e *etcdRegistry) Register(s *registry.Service, opts ...registry.RegisterOption) error {
+	if len(s.Nodes) == 0 {
+		return errors.New("require at least one node")
+	}
+
+	var gerr error
+
+	// register each node individually
+	for _, node := range s.Nodes {
+		err := e.registerNode(s, node, opts...)
+		if err != nil {
+			gerr = err
+		}
+	}
+
+	return gerr
+}
+
+func (e *etcdRegistry) GetService(name string, opts ...registry.GetOption) ([]*registry.Service, error) {
+	ctx, cancel := context.WithTimeout(context.Background(), e.options.Timeout)
+	defer cancel()
+
+	rsp, err := e.client.Get(ctx, servicePath(name)+"/", clientv3.WithPrefix(), clientv3.WithSerializable())
+	if err != nil {
+		return nil, err
+	}
+
+	if len(rsp.Kvs) == 0 {
+		return nil, registry.ErrNotFound
+	}
+
+	serviceMap := map[string]*registry.Service{}
+
+	for _, n := range rsp.Kvs {
+		if sn := decode(n.Value); sn != nil {
+			s, ok := serviceMap[sn.Version]
+			if !ok {
+				s = &registry.Service{
+					Name:      sn.Name,
+					Version:   sn.Version,
+					Metadata:  sn.Metadata,
+					Endpoints: sn.Endpoints,
+				}
+				serviceMap[s.Version] = s
+			}
+
+			s.Nodes = append(s.Nodes, sn.Nodes...)
+		}
+	}
+
+	services := make([]*registry.Service, 0, len(serviceMap))
+	for _, service := range serviceMap {
+		services = append(services, service)
+	}
+
+	return services, nil
+}
+
+func (e *etcdRegistry) ListServices(opts ...registry.ListOption) ([]*registry.Service, error) {
+	versions := make(map[string]*registry.Service)
+
+	ctx, cancel := context.WithTimeout(context.Background(), e.options.Timeout)
+	defer cancel()
+
+	rsp, err := e.client.Get(ctx, prefix, clientv3.WithPrefix(), clientv3.WithSerializable())
+	if err != nil {
+		return nil, err
+	}
+
+	if len(rsp.Kvs) == 0 {
+		return []*registry.Service{}, nil
+	}
+
+	for _, n := range rsp.Kvs {
+		sn := decode(n.Value)
+		if sn == nil {
+			continue
+		}
+		v, ok := versions[sn.Name+sn.Version]
+		if !ok {
+			versions[sn.Name+sn.Version] = sn
+			continue
+		}
+		// append to service:version nodes
+		v.Nodes = append(v.Nodes, sn.Nodes...)
+	}
+
+	services := make([]*registry.Service, 0, len(versions))
+	for _, service := range versions {
+		services = append(services, service)
+	}
+
+	// sort the services
+	sort.Slice(services, func(i, j int) bool { return services[i].Name < services[j].Name })
+
+	return services, nil
+}
+
+func (e *etcdRegistry) Watch(opts ...registry.WatchOption) (registry.Watcher, error) {
+	return newEtcdWatcher(e, e.options.Timeout, opts...)
+}
+
+func (e *etcdRegistry) String() string {
+	return "etcd"
+}
+
+// startKeepAlive starts a keepalive goroutine for the given lease
+// It uses a long-lived KeepAlive channel instead of KeepAliveOnce to reduce authentication requests
+func (e *etcdRegistry) startKeepAlive(key string, leaseID clientv3.LeaseID) error {
+	e.Lock()
+	defer e.Unlock()
+
+	// check if keepalive is already running
+	if _, ok := e.keepaliveChs[key]; ok {
+		return nil
+	}
+
+	// create keepalive channel
+	ch, err := e.client.KeepAlive(context.Background(), leaseID)
+	if err != nil {
+		return err
+	}
+
+	e.keepaliveChs[key] = ch
+	stopCh := make(chan bool, 1)
+	e.keepaliveStop[key] = stopCh
+
+	// start goroutine to consume keepalive responses
+	go e.keepAliveLoop(key, ch, stopCh)
+
+	return nil
+}
+
+// keepAliveLoop consumes keepalive responses for a lease. It exits and
+// drops the cached lease/registration (via handleKeepAliveClosed) when
+// the keepalive channel closes OR a response reports a non-positive TTL.
+// Both mean the lease is gone — for example a network partition that
+// outlasted the TTL — so the next Register must re-create it rather than
+// be short-circuited by the "unchanged" check in registerNode. Without
+// the TTL guard a silently-expired lease (where the channel does not
+// promptly close) would leave the service de-registered from etcd while
+// the cache still believed it was registered, and nothing would repair it.
+func (e *etcdRegistry) keepAliveLoop(key string, ch <-chan *clientv3.LeaseKeepAliveResponse, stopCh chan bool) {
+	log := e.options.Logger
+	for {
+		select {
+		case <-stopCh:
+			log.Logf(logger.TraceLevel, "Stopping keepalive for %s", key)
+			return
+		case ka, ok := <-ch:
+			if !ok {
+				log.Logf(logger.DebugLevel, "Keepalive channel closed for %s", key)
+				e.handleKeepAliveClosed(key)
+				return
+			}
+			if ka == nil {
+				log.Logf(logger.WarnLevel, "Keepalive response is nil for %s", key)
+				continue
+			}
+			if ka.TTL <= 0 {
+				log.Logf(logger.WarnLevel, "Keepalive TTL expired for %s lease %d; dropping lease to force re-register", key, ka.ID)
+				e.handleKeepAliveClosed(key)
+				return
+			}
+			log.Logf(logger.TraceLevel, "Keepalive response for %s lease %d, TTL %d", key, ka.ID, ka.TTL)
+		}
+	}
+}
+
+// handleKeepAliveClosed is invoked by the keepalive goroutine when the
+// etcd client closes the KeepAlive channel (for example because the lease
+// expired on the server side during a network partition). In addition to
+// removing the channel bookkeeping, it drops the cached lease and
+// registration hash so the next registerNode() performs a full
+// Grant+Put re-registration instead of being short-circuited by the
+// "unchanged" check at the top of registerNode.
+func (e *etcdRegistry) handleKeepAliveClosed(key string) {
+	e.Lock()
+	defer e.Unlock()
+
+	// Only delete if still present to avoid racing with stopKeepAlive.
+	if _, exists := e.keepaliveChs[key]; exists {
+		delete(e.keepaliveChs, key)
+		delete(e.keepaliveStop, key)
+	}
+	delete(e.leases, key)
+	delete(e.register, key)
+}
+
+// stopKeepAlive stops the keepalive goroutine for the given key
+func (e *etcdRegistry) stopKeepAlive(key string) {
+	e.Lock()
+	defer e.Unlock()
+
+	if stopCh, ok := e.keepaliveStop[key]; ok {
+		close(stopCh)
+		delete(e.keepaliveChs, key)
+		delete(e.keepaliveStop, key)
+	}
+}

registry/etcd/etcd_test.go

@@ -0,0 +1,322 @@
+package etcd
+
+import (
+	"context"
+	"fmt"
+	"os"
+	"testing"
+	"time"
+
+	"go-micro.dev/v6/logger"
+	"go-micro.dev/v6/registry"
+	clientv3 "go.etcd.io/etcd/client/v3"
+)
+
+// TestKeepAliveManagement tests that keepalive channels are properly managed
+func TestKeepAliveManagement(t *testing.T) {
+	// Skip if no etcd server available
+	etcdAddr := os.Getenv("ETCD_ADDRESS")
+	if etcdAddr == "" {
+		etcdAddr = "127.0.0.1:2379"
+	}
+
+	// Try to connect to etcd
+	client, err := clientv3.New(clientv3.Config{
+		Endpoints:   []string{etcdAddr},
+		DialTimeout: 2 * time.Second,
+	})
+	if err != nil {
+		t.Skip("Etcd not available, skipping test:", err)
+		return
+	}
+	defer client.Close()
+
+	// Test connection
+	ctx, cancel := context.WithTimeout(context.Background(), 2*time.Second)
+	defer cancel()
+	_, err = client.Get(ctx, "/test")
+	if err != nil {
+		t.Skip("Etcd not reachable, skipping test:", err)
+		return
+	}
+
+	// Create registry
+	reg := NewEtcdRegistry(
+		registry.Addrs(etcdAddr),
+		registry.Timeout(5*time.Second),
+	).(*etcdRegistry)
+
+	// Create a test service
+	service := &registry.Service{
+		Name:    "test.service",
+		Version: "1.0.0",
+		Nodes: []*registry.Node{
+			{
+				Id:      "test-node-1",
+				Address: "localhost:9090",
+			},
+		},
+	}
+
+	// Register with TTL
+	err = reg.Register(service, registry.RegisterTTL(10*time.Second))
+	if err != nil {
+		t.Fatalf("Failed to register service: %v", err)
+	}
+
+	// Wait a bit for keepalive to start
+	time.Sleep(100 * time.Millisecond)
+
+	// Check that keepalive channel was created
+	reg.RLock()
+	key := service.Name + service.Nodes[0].Id
+	_, hasKeepalive := reg.keepaliveChs[key]
+	_, hasStop := reg.keepaliveStop[key]
+	reg.RUnlock()
+
+	if !hasKeepalive {
+		t.Error("Keepalive channel was not created")
+	}
+	if !hasStop {
+		t.Error("Keepalive stop channel was not created")
+	}
+
+	// Register again (simulating re-registration)
+	// This should reuse the existing keepalive
+	err = reg.Register(service, registry.RegisterTTL(10*time.Second))
+	if err != nil {
+		t.Fatalf("Failed to re-register service: %v", err)
+	}
+
+	// Deregister
+	err = reg.Deregister(service)
+	if err != nil {
+		t.Fatalf("Failed to deregister service: %v", err)
+	}
+
+	// Wait a bit for cleanup
+	time.Sleep(100 * time.Millisecond)
+
+	// Check that keepalive was cleaned up
+	reg.RLock()
+	_, hasKeepalive = reg.keepaliveChs[key]
+	_, hasStop = reg.keepaliveStop[key]
+	reg.RUnlock()
+
+	if hasKeepalive {
+		t.Error("Keepalive channel was not cleaned up")
+	}
+	if hasStop {
+		t.Error("Keepalive stop channel was not cleaned up")
+	}
+}
+
+// TestKeepAliveReducesAuthRequests tests that KeepAlive reduces authentication requests
+// This is a conceptual test - in practice, measuring auth requests requires etcd with auth enabled
+func TestKeepAliveReducesAuthRequests(t *testing.T) {
+	// Skip if no etcd server available
+	etcdAddr := os.Getenv("ETCD_ADDRESS")
+	if etcdAddr == "" {
+		etcdAddr = "127.0.0.1:2379"
+	}
+
+	// Try to connect to etcd
+	client, err := clientv3.New(clientv3.Config{
+		Endpoints:   []string{etcdAddr},
+		DialTimeout: 2 * time.Second,
+	})
+	if err != nil {
+		t.Skip("Etcd not available, skipping test:", err)
+		return
+	}
+	defer client.Close()
+
+	// Test connection
+	ctx, cancel := context.WithTimeout(context.Background(), 2*time.Second)
+	defer cancel()
+	_, err = client.Get(ctx, "/test")
+	if err != nil {
+		t.Skip("Etcd not reachable, skipping test:", err)
+		return
+	}
+
+	// Create registry
+	reg := NewEtcdRegistry(
+		registry.Addrs(etcdAddr),
+		registry.Timeout(5*time.Second),
+	).(*etcdRegistry)
+
+	// Create multiple test services
+	services := make([]*registry.Service, 5)
+	for i := 0; i < 5; i++ {
+		services[i] = &registry.Service{
+			Name:    fmt.Sprintf("test.service.%d", i),
+			Version: "1.0.0",
+			Nodes: []*registry.Node{
+				{
+					Id:      fmt.Sprintf("test-node-%d", i),
+					Address: fmt.Sprintf("localhost:%d", 9090+i),
+				},
+			},
+		}
+
+		// Register with TTL
+		err = reg.Register(services[i], registry.RegisterTTL(10*time.Second))
+		if err != nil {
+			t.Fatalf("Failed to register service %d: %v", i, err)
+		}
+	}
+
+	// Wait for keepalives to start
+	time.Sleep(200 * time.Millisecond)
+
+	// Verify all have keepalive channels
+	reg.RLock()
+	keepaliveCount := len(reg.keepaliveChs)
+	reg.RUnlock()
+
+	if keepaliveCount != 5 {
+		t.Errorf("Expected 5 keepalive channels, got %d", keepaliveCount)
+	}
+
+	// Simulate multiple re-registrations (heartbeats)
+	// With KeepAlive, these should NOT create new auth requests
+	for i := 0; i < 3; i++ {
+		time.Sleep(100 * time.Millisecond)
+		for _, service := range services {
+			err = reg.Register(service, registry.RegisterTTL(10*time.Second))
+			if err != nil {
+				t.Fatalf("Failed to re-register service: %v", err)
+			}
+		}
+	}
+
+	// Still should have only 5 keepalive channels (not 15 or 20)
+	reg.RLock()
+	keepaliveCount = len(reg.keepaliveChs)
+	reg.RUnlock()
+
+	if keepaliveCount != 5 {
+		t.Errorf("After re-registrations, expected 5 keepalive channels, got %d", keepaliveCount)
+	}
+
+	// Cleanup
+	for _, service := range services {
+		err = reg.Deregister(service)
+		if err != nil {
+			t.Logf("Failed to deregister service: %v", err)
+		}
+	}
+}
+
+// TestKeepAliveChannelReconnection tests that keepalive handles channel closure
+func TestKeepAliveChannelReconnection(t *testing.T) {
+	// This test verifies the goroutine properly handles channel closure
+	reg := &etcdRegistry{
+		options: registry.Options{
+			Logger: logger.DefaultLogger,
+		},
+		keepaliveChs:  make(map[string]<-chan *clientv3.LeaseKeepAliveResponse),
+		keepaliveStop: make(map[string]chan bool),
+	}
+
+	// Create a mock keepalive channel that closes immediately
+	ch := make(chan *clientv3.LeaseKeepAliveResponse)
+	close(ch)
+
+	reg.keepaliveChs["test-key"] = ch
+	stopCh := make(chan bool, 1)
+	reg.keepaliveStop["test-key"] = stopCh
+
+	// Start the goroutine manually
+	go func() {
+		log := reg.options.Logger
+		for {
+			select {
+			case <-stopCh:
+				log.Logf(logger.TraceLevel, "Stopping keepalive for test-key")
+				return
+			case ka, ok := <-ch:
+				if !ok {
+					log.Logf(logger.DebugLevel, "Keepalive channel closed for test-key")
+					reg.Lock()
+					delete(reg.keepaliveChs, "test-key")
+					delete(reg.keepaliveStop, "test-key")
+					reg.Unlock()
+					return
+				}
+				if ka == nil {
+					log.Logf(logger.WarnLevel, "Keepalive response is nil for test-key")
+					continue
+				}
+			}
+		}
+	}()
+
+	// Wait for goroutine to detect closure and cleanup
+	time.Sleep(100 * time.Millisecond)
+
+	// Verify cleanup happened
+	reg.RLock()
+	_, hasKeepalive := reg.keepaliveChs["test-key"]
+	_, hasStop := reg.keepaliveStop["test-key"]
+	reg.RUnlock()
+
+	if hasKeepalive {
+		t.Error("Keepalive channel should have been cleaned up after closure")
+	}
+	if hasStop {
+		t.Error("Stop channel should have been cleaned up after closure")
+	}
+}
+
+// TestHandleKeepAliveClosedClearsLease is a regression test for the bug
+// where a closed KeepAlive channel (e.g. because the lease expired on
+// the etcd server during a network partition) left the `leases` and
+// `register` caches populated, causing the next registerNode() to
+// short-circuit on the "unchanged" check and never re-register the
+// service. handleKeepAliveClosed must clear all four maps so that the
+// next heartbeat performs a full Grant+Put re-registration.
+func TestHandleKeepAliveClosedClearsLease(t *testing.T) {
+	reg := &etcdRegistry{
+		options:       registry.Options{Logger: logger.DefaultLogger},
+		register:      map[string]uint64{"svckey": 0xdeadbeef},
+		leases:        map[string]clientv3.LeaseID{"svckey": 42},
+		keepaliveChs:  map[string]<-chan *clientv3.LeaseKeepAliveResponse{"svckey": make(chan *clientv3.LeaseKeepAliveResponse)},
+		keepaliveStop: map[string]chan bool{"svckey": make(chan bool, 1)},
+	}
+
+	reg.handleKeepAliveClosed("svckey")
+
+	reg.RLock()
+	defer reg.RUnlock()
+
+	if _, ok := reg.keepaliveChs["svckey"]; ok {
+		t.Error("keepaliveChs not cleared")
+	}
+	if _, ok := reg.keepaliveStop["svckey"]; ok {
+		t.Error("keepaliveStop not cleared")
+	}
+	if _, ok := reg.leases["svckey"]; ok {
+		t.Error("leases not cleared — next heartbeat will skip re-registration")
+	}
+	if _, ok := reg.register["svckey"]; ok {
+		t.Error("register hash not cleared — next heartbeat will skip re-registration")
+	}
+}
+
+// TestHandleKeepAliveClosedIdempotent verifies that handleKeepAliveClosed
+// does not panic when called with a key that was already removed (which
+// can happen if stopKeepAlive/Deregister ran concurrently).
+func TestHandleKeepAliveClosedIdempotent(t *testing.T) {
+	reg := &etcdRegistry{
+		options:       registry.Options{Logger: logger.DefaultLogger},
+		register:      map[string]uint64{},
+		leases:        map[string]clientv3.LeaseID{},
+		keepaliveChs:  map[string]<-chan *clientv3.LeaseKeepAliveResponse{},
+		keepaliveStop: map[string]chan bool{},
+	}
+
+	// Should be a no-op; no panic.
+	reg.handleKeepAliveClosed("missing")
+}

registry/etcd/keepalive_test.go

@@ -0,0 +1,113 @@
+package etcd
+
+import (
+	"testing"
+	"time"
+
+	"go-micro.dev/v6/logger"
+	clientv3 "go.etcd.io/etcd/client/v3"
+)
+
+func newTestRegistry() *etcdRegistry {
+	e := &etcdRegistry{
+		register:      map[string]uint64{},
+		leases:        map[string]clientv3.LeaseID{},
+		keepaliveChs:  map[string]<-chan *clientv3.LeaseKeepAliveResponse{},
+		keepaliveStop: map[string]chan bool{},
+	}
+	e.options.Logger = logger.DefaultLogger
+	return e
+}
+
+func seedLease(e *etcdRegistry, key string, ch <-chan *clientv3.LeaseKeepAliveResponse, stop chan bool) {
+	e.Lock()
+	e.keepaliveChs[key] = ch
+	e.keepaliveStop[key] = stop
+	e.leases[key] = clientv3.LeaseID(123)
+	e.register[key] = 42
+	e.Unlock()
+}
+
+func leaseCached(e *etcdRegistry, key string) bool {
+	e.RLock()
+	defer e.RUnlock()
+	_, ok := e.leases[key]
+	return ok
+}
+
+// A keepalive response with a non-positive TTL means the lease has
+// expired server-side; the loop must drop the cached lease so the next
+// Register re-registers instead of skipping on the "unchanged" check.
+func TestKeepAliveLoopTTLExpiredDropsLease(t *testing.T) {
+	e := newTestRegistry()
+	key := "svc1node1"
+	ch := make(chan *clientv3.LeaseKeepAliveResponse, 1)
+	stop := make(chan bool, 1)
+	seedLease(e, key, ch, stop)
+
+	done := make(chan struct{})
+	go func() { e.keepAliveLoop(key, ch, stop); close(done) }()
+
+	ch <- &clientv3.LeaseKeepAliveResponse{ID: 123, TTL: 0}
+
+	select {
+	case <-done:
+	case <-time.After(2 * time.Second):
+		t.Fatal("keepAliveLoop did not return after a TTL<=0 response")
+	}
+	if leaseCached(e, key) {
+		t.Error("lease should be dropped after it expired (TTL<=0)")
+	}
+}
+
+// A closed keepalive channel also drops the cached lease.
+func TestKeepAliveLoopChannelClosedDropsLease(t *testing.T) {
+	e := newTestRegistry()
+	key := "svc1node1"
+	ch := make(chan *clientv3.LeaseKeepAliveResponse)
+	stop := make(chan bool, 1)
+	seedLease(e, key, ch, stop)
+
+	done := make(chan struct{})
+	go func() { e.keepAliveLoop(key, ch, stop); close(done) }()
+
+	close(ch)
+
+	select {
+	case <-done:
+	case <-time.After(2 * time.Second):
+		t.Fatal("keepAliveLoop did not return after the channel closed")
+	}
+	if leaseCached(e, key) {
+		t.Error("lease should be dropped after the channel closed")
+	}
+}
+
+// A healthy response must NOT drop the lease, and stopping the loop (as
+// on Deregister) leaves the cache for stopKeepAlive to clean up.
+func TestKeepAliveLoopHealthyKeepsLease(t *testing.T) {
+	e := newTestRegistry()
+	key := "svc1node1"
+	ch := make(chan *clientv3.LeaseKeepAliveResponse, 1)
+	stop := make(chan bool, 1)
+	seedLease(e, key, ch, stop)
+
+	done := make(chan struct{})
+	go func() { e.keepAliveLoop(key, ch, stop); close(done) }()
+
+	ch <- &clientv3.LeaseKeepAliveResponse{ID: 123, TTL: 30}
+	time.Sleep(50 * time.Millisecond)
+	if !leaseCached(e, key) {
+		t.Error("a healthy keepalive must not drop the lease")
+	}
+
+	stop <- true
+	select {
+	case <-done:
+	case <-time.After(2 * time.Second):
+		t.Fatal("keepAliveLoop did not return after stop")
+	}
+	if !leaseCached(e, key) {
+		t.Error("stopping the loop should not drop the lease; stopKeepAlive does that")
+	}
+}

registry/etcd/options.go

@@ -0,0 +1,37 @@
+package etcd
+
+import (
+	"context"
+
+	"go-micro.dev/v6/registry"
+	"go.uber.org/zap"
+)
+
+type authKey struct{}
+
+type logConfigKey struct{}
+
+type authCreds struct {
+	Username string
+	Password string
+}
+
+// Auth allows you to specify username/password.
+func Auth(username, password string) registry.Option {
+	return func(o *registry.Options) {
+		if o.Context == nil {
+			o.Context = context.Background()
+		}
+		o.Context = context.WithValue(o.Context, authKey{}, &authCreds{Username: username, Password: password})
+	}
+}
+
+// LogConfig allows you to set etcd log config.
+func LogConfig(config *zap.Config) registry.Option {
+	return func(o *registry.Options) {
+		if o.Context == nil {
+			o.Context = context.Background()
+		}
+		o.Context = context.WithValue(o.Context, logConfigKey{}, config)
+	}
+}

registry/etcd/watcher.go

@@ -0,0 +1,91 @@
+package etcd
+
+import (
+	"context"
+	"errors"
+	"time"
+
+	"go-micro.dev/v6/registry"
+	clientv3 "go.etcd.io/etcd/client/v3"
+)
+
+type etcdWatcher struct {
+	stop    chan bool
+	w       clientv3.WatchChan
+	client  *clientv3.Client
+	timeout time.Duration
+}
+
+func newEtcdWatcher(r *etcdRegistry, timeout time.Duration, opts ...registry.WatchOption) (registry.Watcher, error) {
+	var wo registry.WatchOptions
+	for _, o := range opts {
+		o(&wo)
+	}
+
+	ctx, cancel := context.WithCancel(context.Background())
+	stop := make(chan bool, 1)
+
+	go func() {
+		<-stop
+		cancel()
+	}()
+
+	watchPath := prefix
+	if len(wo.Service) > 0 {
+		watchPath = servicePath(wo.Service) + "/"
+	}
+
+	return &etcdWatcher{
+		stop:    stop,
+		w:       r.client.Watch(ctx, watchPath, clientv3.WithPrefix(), clientv3.WithPrevKV()),
+		client:  r.client,
+		timeout: timeout,
+	}, nil
+}
+
+func (ew *etcdWatcher) Next() (*registry.Result, error) {
+	for wresp := range ew.w {
+		if wresp.Err() != nil {
+			return nil, wresp.Err()
+		}
+		if wresp.Canceled {
+			return nil, errors.New("could not get next")
+		}
+		for _, ev := range wresp.Events {
+			service := decode(ev.Kv.Value)
+			var action string
+
+			switch ev.Type {
+			case clientv3.EventTypePut:
+				if ev.IsCreate() {
+					action = "create"
+				} else if ev.IsModify() {
+					action = "update"
+				}
+			case clientv3.EventTypeDelete:
+				action = "delete"
+
+				// get service from prevKv
+				service = decode(ev.PrevKv.Value)
+			}
+
+			if service == nil {
+				continue
+			}
+			return &registry.Result{
+				Action:  action,
+				Service: service,
+			}, nil
+		}
+	}
+	return nil, errors.New("could not get next")
+}
+
+func (ew *etcdWatcher) Stop() {
+	select {
+	case <-ew.stop:
+		return
+	default:
+		close(ew.stop)
+	}
+}

registry/mdns_registry.go

@@ -0,0 +1,618 @@
+// Package mdns is a multicast dns registry
+package registry
+
+import (
+	"bytes"
+	"compress/zlib"
+	"context"
+	"encoding/hex"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net"
+	"strconv"
+	"strings"
+	"sync"
+	"time"
+
+	"github.com/google/uuid"
+	"go-micro.dev/v6/internal/util/mdns"
+	log "go-micro.dev/v6/logger"
+)
+
+var (
+	// use a .micro domain rather than .local.
+	mdnsDomain = "micro"
+)
+
+type mdnsTxt struct {
+	Metadata  map[string]string
+	Service   string
+	Version   string
+	Endpoints []*Endpoint
+}
+
+type mdnsEntry struct {
+	node *mdns.Server
+	id   string
+}
+
+type mdnsRegistry struct {
+	opts     *Options
+	services map[string][]*mdnsEntry
+
+	// watchers
+	watchers map[string]*mdnsWatcher
+
+	// listener
+	listener chan *mdns.ServiceEntry
+	// the mdns domain
+	domain string
+
+	mtx sync.RWMutex
+
+	sync.Mutex
+}
+
+type mdnsWatcher struct {
+	wo   WatchOptions
+	ch   chan *mdns.ServiceEntry
+	exit chan struct{}
+	// the registry
+	registry *mdnsRegistry
+	id       string
+	// the mdns domain
+	domain string
+}
+
+func encode(txt *mdnsTxt) ([]string, error) {
+	b, err := json.Marshal(txt)
+	if err != nil {
+		return nil, err
+	}
+
+	var buf bytes.Buffer
+	defer buf.Reset()
+
+	w := zlib.NewWriter(&buf)
+	if _, err := w.Write(b); err != nil {
+		return nil, err
+	}
+	w.Close()
+
+	encoded := hex.EncodeToString(buf.Bytes())
+
+	// individual txt limit
+	if len(encoded) <= 255 {
+		return []string{encoded}, nil
+	}
+
+	// split encoded string
+	var record []string
+
+	for len(encoded) > 255 {
+		record = append(record, encoded[:255])
+		encoded = encoded[255:]
+	}
+
+	record = append(record, encoded)
+
+	return record, nil
+}
+
+func decode(record []string) (*mdnsTxt, error) {
+	encoded := strings.Join(record, "")
+
+	hr, err := hex.DecodeString(encoded)
+	if err != nil {
+		return nil, err
+	}
+
+	br := bytes.NewReader(hr)
+	zr, err := zlib.NewReader(br)
+	if err != nil {
+		return nil, err
+	}
+
+	rbuf, err := io.ReadAll(zr)
+	if err != nil {
+		return nil, err
+	}
+
+	var txt *mdnsTxt
+
+	if err := json.Unmarshal(rbuf, &txt); err != nil {
+		return nil, err
+	}
+
+	return txt, nil
+}
+func newRegistry(opts ...Option) Registry {
+	mergedOpts := append([]Option{Timeout(time.Millisecond * 100)}, opts...)
+	options := NewOptions(mergedOpts...)
+
+	// set the domain
+	domain := mdnsDomain
+
+	d, ok := options.Context.Value("mdns.domain").(string)
+	if ok {
+		domain = d
+	}
+
+	return &mdnsRegistry{
+		opts:     options,
+		domain:   domain,
+		services: make(map[string][]*mdnsEntry),
+		watchers: make(map[string]*mdnsWatcher),
+	}
+}
+
+func (m *mdnsRegistry) Init(opts ...Option) error {
+	for _, o := range opts {
+		o(m.opts)
+	}
+	return nil
+}
+
+func (m *mdnsRegistry) Options() Options {
+	return *m.opts
+}
+
+func (m *mdnsRegistry) Register(service *Service, opts ...RegisterOption) error {
+	m.Lock()
+	defer m.Unlock()
+
+	logger := m.opts.Logger
+	entries, ok := m.services[service.Name]
+	// first entry, create wildcard used for list queries
+	if !ok {
+		s, err := mdns.NewMDNSService(
+			service.Name,
+			"_services",
+			m.domain+".",
+			"",
+			9999,
+			[]net.IP{net.ParseIP("0.0.0.0")},
+			nil,
+		)
+		if err != nil {
+			return err
+		}
+
+		srv, err := mdns.NewServer(&mdns.Config{Zone: &mdns.DNSSDService{MDNSService: s}})
+		if err != nil {
+			return err
+		}
+
+		// append the wildcard entry
+		entries = append(entries, &mdnsEntry{id: "*", node: srv})
+	}
+
+	var gerr error
+
+	for _, node := range service.Nodes {
+		var seen bool
+		var e *mdnsEntry
+
+		for _, entry := range entries {
+			if node.Id == entry.id {
+				seen = true
+				break
+			}
+		}
+
+		// already registered, continue
+		if seen {
+			continue
+			// doesn't exist
+		} else {
+			e = &mdnsEntry{}
+		}
+
+		txt, err := encode(&mdnsTxt{
+			Service:   service.Name,
+			Version:   service.Version,
+			Endpoints: service.Endpoints,
+			Metadata:  node.Metadata,
+		})
+
+		if err != nil {
+			gerr = err
+			continue
+		}
+
+		host, pt, err := net.SplitHostPort(node.Address)
+		if err != nil {
+			gerr = err
+			continue
+		}
+		port, _ := strconv.Atoi(pt)
+
+		logger.Logf(log.DebugLevel, "[mdns] registry create new service with ip: %s for: %s", net.ParseIP(host).String(), host)
+
+		// we got here, new node
+		s, err := mdns.NewMDNSService(
+			node.Id,
+			service.Name,
+			m.domain+".",
+			"",
+			port,
+			[]net.IP{net.ParseIP(host)},
+			txt,
+		)
+		if err != nil {
+			gerr = err
+			continue
+		}
+
+		srv, err := mdns.NewServer(&mdns.Config{Zone: s, LocalhostChecking: true})
+		if err != nil {
+			gerr = err
+			continue
+		}
+
+		e.id = node.Id
+		e.node = srv
+		entries = append(entries, e)
+	}
+
+	// save
+	m.services[service.Name] = entries
+
+	return gerr
+}
+
+func (m *mdnsRegistry) Deregister(service *Service, opts ...DeregisterOption) error {
+	m.Lock()
+	defer m.Unlock()
+
+	var newEntries []*mdnsEntry
+
+	// loop existing entries, check if any match, shutdown those that do
+	for _, entry := range m.services[service.Name] {
+		var remove bool
+
+		for _, node := range service.Nodes {
+			if node.Id == entry.id {
+				_ = entry.node.Shutdown()
+				remove = true
+				break
+			}
+		}
+
+		// keep it?
+		if !remove {
+			newEntries = append(newEntries, entry)
+		}
+	}
+
+	// last entry is the wildcard for list queries. Remove it.
+	if len(newEntries) == 1 && newEntries[0].id == "*" {
+		_ = newEntries[0].node.Shutdown()
+		delete(m.services, service.Name)
+	} else {
+		m.services[service.Name] = newEntries
+	}
+
+	return nil
+}
+
+func (m *mdnsRegistry) GetService(service string, opts ...GetOption) ([]*Service, error) {
+	logger := m.opts.Logger
+	serviceMap := make(map[string]*Service)
+	entries := make(chan *mdns.ServiceEntry, 10)
+	done := make(chan bool)
+
+	p := mdns.DefaultParams(service)
+	// set context with timeout
+	var cancel context.CancelFunc
+	p.Context, cancel = context.WithTimeout(context.Background(), m.opts.Timeout)
+	defer cancel()
+	// set entries channel
+	p.Entries = entries
+	// set the domain
+	p.Domain = m.domain
+
+	go func() {
+		for {
+			select {
+			case e := <-entries:
+				// list record so skip
+				if p.Service == "_services" {
+					continue
+				}
+				if p.Domain != m.domain {
+					continue
+				}
+				if e.TTL == 0 {
+					continue
+				}
+
+				txt, err := decode(e.InfoFields)
+				if err != nil {
+					continue
+				}
+
+				if txt.Service != service {
+					continue
+				}
+
+				s, ok := serviceMap[txt.Version]
+				if !ok {
+					s = &Service{
+						Name:      txt.Service,
+						Version:   txt.Version,
+						Endpoints: txt.Endpoints,
+					}
+				}
+				addr := ""
+				// prefer ipv4 addrs
+				if len(e.AddrV4) > 0 {
+					addr = net.JoinHostPort(e.AddrV4.String(), fmt.Sprint(e.Port))
+					// else use ipv6
+				} else if len(e.AddrV6) > 0 {
+					addr = net.JoinHostPort(e.AddrV6.String(), fmt.Sprint(e.Port))
+				} else {
+					logger.Logf(log.InfoLevel, "[mdns]: invalid endpoint received: %v", e)
+					continue
+				}
+				s.Nodes = append(s.Nodes, &Node{
+					Id:       strings.TrimSuffix(e.Name, "."+p.Service+"."+p.Domain+"."),
+					Address:  addr,
+					Metadata: txt.Metadata,
+				})
+
+				serviceMap[txt.Version] = s
+			case <-p.Context.Done():
+				close(done)
+				return
+			}
+		}
+	}()
+
+	// execute the query
+	if err := mdns.Query(p); err != nil {
+		return nil, err
+	}
+
+	// wait for completion
+	<-done
+
+	// create list and return
+	services := make([]*Service, 0, len(serviceMap))
+
+	for _, service := range serviceMap {
+		services = append(services, service)
+	}
+
+	return services, nil
+}
+
+func (m *mdnsRegistry) ListServices(opts ...ListOption) ([]*Service, error) {
+	serviceMap := make(map[string]bool)
+	entries := make(chan *mdns.ServiceEntry, 10)
+	done := make(chan bool)
+
+	p := mdns.DefaultParams("_services")
+	// set context with timeout
+	var cancel context.CancelFunc
+	p.Context, cancel = context.WithTimeout(context.Background(), m.opts.Timeout)
+	defer cancel()
+	// set entries channel
+	p.Entries = entries
+	// set domain
+	p.Domain = m.domain
+
+	var services []*Service
+
+	go func() {
+		for {
+			select {
+			case e := <-entries:
+				if e.TTL == 0 {
+					continue
+				}
+				if !strings.HasSuffix(e.Name, p.Domain+".") {
+					continue
+				}
+				name := strings.TrimSuffix(e.Name, "."+p.Service+"."+p.Domain+".")
+				if !serviceMap[name] {
+					serviceMap[name] = true
+					services = append(services, &Service{Name: name})
+				}
+			case <-p.Context.Done():
+				close(done)
+				return
+			}
+		}
+	}()
+
+	// execute query
+	if err := mdns.Query(p); err != nil {
+		return nil, err
+	}
+
+	// wait till done
+	<-done
+
+	return services, nil
+}
+
+func (m *mdnsRegistry) Watch(opts ...WatchOption) (Watcher, error) {
+	var wo WatchOptions
+	for _, o := range opts {
+		o(&wo)
+	}
+
+	md := &mdnsWatcher{
+		id:       uuid.New().String(),
+		wo:       wo,
+		ch:       make(chan *mdns.ServiceEntry, 32),
+		exit:     make(chan struct{}),
+		domain:   m.domain,
+		registry: m,
+	}
+
+	m.mtx.Lock()
+	defer m.mtx.Unlock()
+
+	// save the watcher
+	m.watchers[md.id] = md
+
+	// check of the listener exists
+	if m.listener != nil {
+		return md, nil
+	}
+
+	// start the listener
+	go func() {
+		// go to infinity
+		for {
+			m.mtx.Lock()
+
+			// just return if there are no watchers
+			if len(m.watchers) == 0 {
+				m.listener = nil
+				m.mtx.Unlock()
+				return
+			}
+
+			// check existing listener
+			if m.listener != nil {
+				m.mtx.Unlock()
+				return
+			}
+
+			// reset the listener
+			exit := make(chan struct{})
+			ch := make(chan *mdns.ServiceEntry, 32)
+			m.listener = ch
+
+			m.mtx.Unlock()
+
+			// send messages to the watchers
+			go func() {
+				send := func(w *mdnsWatcher, e *mdns.ServiceEntry) {
+					select {
+					case w.ch <- e:
+					default:
+					}
+				}
+
+				for {
+					select {
+					case <-exit:
+						return
+					case e, ok := <-ch:
+						if !ok {
+							return
+						}
+						m.mtx.RLock()
+						// send service entry to all watchers
+						for _, w := range m.watchers {
+							send(w, e)
+						}
+						m.mtx.RUnlock()
+					}
+				}
+			}()
+
+			// start listening, blocking call
+			_ = mdns.Listen(ch, exit)
+
+			// mdns.Listen has unblocked
+			// kill the saved listener
+			m.mtx.Lock()
+			m.listener = nil
+			close(ch)
+			m.mtx.Unlock()
+		}
+	}()
+
+	return md, nil
+}
+
+func (m *mdnsRegistry) String() string {
+	return "mdns"
+}
+
+func (m *mdnsWatcher) Next() (*Result, error) {
+	for {
+		select {
+		case e := <-m.ch:
+			txt, err := decode(e.InfoFields)
+			if err != nil {
+				continue
+			}
+
+			if len(txt.Service) == 0 || len(txt.Version) == 0 {
+				continue
+			}
+
+			// Filter watch options
+			// wo.Service: Only keep services we care about
+			if len(m.wo.Service) > 0 && txt.Service != m.wo.Service {
+				continue
+			}
+			var action string
+			if e.TTL == 0 {
+				action = "delete"
+			} else {
+				action = "create"
+			}
+
+			service := &Service{
+				Name:      txt.Service,
+				Version:   txt.Version,
+				Endpoints: txt.Endpoints,
+			}
+
+			// skip anything without the domain we care about
+			suffix := fmt.Sprintf(".%s.%s.", service.Name, m.domain)
+			if !strings.HasSuffix(e.Name, suffix) {
+				continue
+			}
+
+			var addr string
+			if len(e.AddrV4) > 0 {
+				addr = net.JoinHostPort(e.AddrV4.String(), fmt.Sprint(e.Port))
+			} else if len(e.AddrV6) > 0 {
+				addr = net.JoinHostPort(e.AddrV6.String(), fmt.Sprint(e.Port))
+			} else {
+				addr = e.Addr.String()
+			}
+
+			service.Nodes = append(service.Nodes, &Node{
+				Id:       strings.TrimSuffix(e.Name, suffix),
+				Address:  addr,
+				Metadata: txt.Metadata,
+			})
+
+			return &Result{
+				Action:  action,
+				Service: service,
+			}, nil
+		case <-m.exit:
+			return nil, ErrWatcherStopped
+		}
+	}
+}
+
+func (m *mdnsWatcher) Stop() {
+	select {
+	case <-m.exit:
+		return
+	default:
+		close(m.exit)
+		// remove self from the registry
+
+		m.registry.mtx.Lock()
+		delete(m.registry.watchers, m.id)
+		m.registry.mtx.Unlock()
+	}
+}
+
+// NewRegistry returns a new default registry which is mdns.
+func NewMDNSRegistry(opts ...Option) Registry {
+	return newRegistry(opts...)
+}

registry/mdns_test.go

@@ -0,0 +1,363 @@
+package registry
+
+import (
+	"os"
+	"testing"
+	"time"
+)
+
+func TestMDNS(t *testing.T) {
+	// skip test in travis because of sendto: operation not permitted error
+	if travis := os.Getenv("TRAVIS"); travis == "true" {
+		t.Skip()
+	}
+
+	testData := []*Service{
+		{
+			Name:    "test1",
+			Version: "1.0.1",
+			Nodes: []*Node{
+				{
+					Id:      "test1-1",
+					Address: "10.0.0.1:10001",
+					Metadata: map[string]string{
+						"foo": "bar",
+					},
+				},
+			},
+		},
+		{
+			Name:    "test2",
+			Version: "1.0.2",
+			Nodes: []*Node{
+				{
+					Id:      "test2-1",
+					Address: "10.0.0.2:10002",
+					Metadata: map[string]string{
+						"foo2": "bar2",
+					},
+				},
+			},
+		},
+		{
+			Name:    "test3",
+			Version: "1.0.3",
+			Nodes: []*Node{
+				{
+					Id:      "test3-1",
+					Address: "10.0.0.3:10003",
+					Metadata: map[string]string{
+						"foo3": "bar3",
+					},
+				},
+			},
+		},
+		{
+			Name:    "test4",
+			Version: "1.0.4",
+			Nodes: []*Node{
+				{
+					Id:      "test4-1",
+					Address: "[::]:10004",
+					Metadata: map[string]string{
+						"foo4": "bar4",
+					},
+				},
+			},
+		},
+	}
+
+	travis := os.Getenv("TRAVIS")
+
+	var opts []Option
+
+	if travis == "true" {
+		opts = append(opts, Timeout(time.Millisecond*100))
+	}
+
+	// new registry
+	r := NewMDNSRegistry(opts...)
+
+	for _, service := range testData {
+		// register service
+		if err := r.Register(service); err != nil {
+			t.Fatal(err)
+		}
+
+		// get registered service
+		s, err := r.GetService(service.Name)
+		if err != nil {
+			t.Fatal(err)
+		}
+
+		if len(s) != 1 {
+			t.Fatalf("Expected one result for %s got %d", service.Name, len(s))
+		}
+
+		if s[0].Name != service.Name {
+			t.Fatalf("Expected name %s got %s", service.Name, s[0].Name)
+		}
+
+		if s[0].Version != service.Version {
+			t.Fatalf("Expected version %s got %s", service.Version, s[0].Version)
+		}
+
+		if len(s[0].Nodes) != 1 {
+			t.Fatalf("Expected 1 node, got %d", len(s[0].Nodes))
+		}
+
+		node := s[0].Nodes[0]
+
+		if node.Id != service.Nodes[0].Id {
+			t.Fatalf("Expected node id %s got %s", service.Nodes[0].Id, node.Id)
+		}
+
+		if node.Address != service.Nodes[0].Address {
+			t.Fatalf("Expected node address %s got %s", service.Nodes[0].Address, node.Address)
+		}
+	}
+
+	services, err := r.ListServices()
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	for _, service := range testData {
+		var seen bool
+		for _, s := range services {
+			if s.Name == service.Name {
+				seen = true
+				break
+			}
+		}
+		if !seen {
+			t.Fatalf("Expected service %s got nothing", service.Name)
+		}
+
+		// deregister
+		if err := r.Deregister(service); err != nil {
+			t.Fatal(err)
+		}
+
+		time.Sleep(time.Millisecond * 5)
+
+		// check its gone
+		s, _ := r.GetService(service.Name)
+		if len(s) > 0 {
+			t.Fatalf("Expected nothing got %+v", s[0])
+		}
+	}
+}
+
+func TestEncoding(t *testing.T) {
+	testData := []*mdnsTxt{
+		{
+			Version: "1.0.0",
+			Metadata: map[string]string{
+				"foo": "bar",
+			},
+			Endpoints: []*Endpoint{
+				{
+					Name: "endpoint1",
+					Request: &Value{
+						Name: "request",
+						Type: "request",
+					},
+					Response: &Value{
+						Name: "response",
+						Type: "response",
+					},
+					Metadata: map[string]string{
+						"foo1": "bar1",
+					},
+				},
+			},
+		},
+	}
+
+	for _, d := range testData {
+		encoded, err := encode(d)
+		if err != nil {
+			t.Fatal(err)
+		}
+
+		for _, txt := range encoded {
+			if len(txt) > 255 {
+				t.Fatalf("One of parts for txt is %d characters", len(txt))
+			}
+		}
+
+		decoded, err := decode(encoded)
+		if err != nil {
+			t.Fatal(err)
+		}
+
+		if decoded.Version != d.Version {
+			t.Fatalf("Expected version %s got %s", d.Version, decoded.Version)
+		}
+
+		if len(decoded.Endpoints) != len(d.Endpoints) {
+			t.Fatalf("Expected %d endpoints, got %d", len(d.Endpoints), len(decoded.Endpoints))
+		}
+
+		for k, v := range d.Metadata {
+			if val := decoded.Metadata[k]; val != v {
+				t.Fatalf("Expected %s=%s got %s=%s", k, v, k, val)
+			}
+		}
+	}
+}
+
+func TestWatcher(t *testing.T) {
+	if travis := os.Getenv("TRAVIS"); travis == "true" {
+		t.Skip()
+	}
+
+	testData := []*Service{
+		{
+			Name:    "test1",
+			Version: "1.0.1",
+			Nodes: []*Node{
+				{
+					Id:      "test1-1",
+					Address: "10.0.0.1:10001",
+					Metadata: map[string]string{
+						"foo": "bar",
+					},
+				},
+			},
+		},
+		{
+			Name:    "test2",
+			Version: "1.0.2",
+			Nodes: []*Node{
+				{
+					Id:      "test2-1",
+					Address: "10.0.0.2:10002",
+					Metadata: map[string]string{
+						"foo2": "bar2",
+					},
+				},
+			},
+		},
+		{
+			Name:    "test3",
+			Version: "1.0.3",
+			Nodes: []*Node{
+				{
+					Id:      "test3-1",
+					Address: "10.0.0.3:10003",
+					Metadata: map[string]string{
+						"foo3": "bar3",
+					},
+				},
+			},
+		},
+		{
+			Name:    "test4",
+			Version: "1.0.4",
+			Nodes: []*Node{
+				{
+					Id:      "test4-1",
+					Address: "[::]:10004",
+					Metadata: map[string]string{
+						"foo4": "bar4",
+					},
+				},
+			},
+		},
+	}
+
+	testFn := func(service, s *Service) {
+		if s == nil {
+			t.Fatalf("Expected one result for %s got nil", service.Name)
+		}
+
+		if s.Name != service.Name {
+			t.Fatalf("Expected name %s got %s", service.Name, s.Name)
+		}
+
+		if s.Version != service.Version {
+			t.Fatalf("Expected version %s got %s", service.Version, s.Version)
+		}
+
+		if len(s.Nodes) != 1 {
+			t.Fatalf("Expected 1 node, got %d", len(s.Nodes))
+		}
+
+		node := s.Nodes[0]
+
+		if node.Id != service.Nodes[0].Id {
+			t.Fatalf("Expected node id %s got %s", service.Nodes[0].Id, node.Id)
+		}
+
+		if node.Address != service.Nodes[0].Address {
+			t.Fatalf("Expected node address %s got %s", service.Nodes[0].Address, node.Address)
+		}
+	}
+
+	travis := os.Getenv("TRAVIS")
+
+	var opts []Option
+
+	if travis == "true" {
+		opts = append(opts, Timeout(time.Millisecond*100))
+	}
+
+	// new registry
+	r := NewMDNSRegistry(opts...)
+
+	w, err := r.Watch()
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer w.Stop()
+
+	for _, service := range testData {
+		// register service
+		if err := r.Register(service); err != nil {
+			t.Fatal(err)
+		}
+
+		for {
+			res, err := w.Next()
+			if err != nil {
+				t.Fatal(err)
+			}
+
+			if res.Service.Name != service.Name {
+				continue
+			}
+
+			if res.Action != "create" {
+				t.Fatalf("Expected create event got %s for %s", res.Action, res.Service.Name)
+			}
+
+			testFn(service, res.Service)
+			break
+		}
+
+		// deregister
+		if err := r.Deregister(service); err != nil {
+			t.Fatal(err)
+		}
+
+		for {
+			res, err := w.Next()
+			if err != nil {
+				t.Fatal(err)
+			}
+
+			if res.Service.Name != service.Name {
+				continue
+			}
+
+			if res.Action != "delete" {
+				continue
+			}
+
+			testFn(service, res.Service)
+			break
+		}
+	}
+}

registry/memory.go

@@ -0,0 +1,274 @@
+package registry
+
+import (
+	"sync"
+	"time"
+
+	"github.com/google/uuid"
+	log "go-micro.dev/v6/logger"
+)
+
+var (
+	sendEventTime = 10 * time.Millisecond
+	ttlPruneTime  = time.Second
+)
+
+type node struct {
+	LastSeen time.Time
+	*Node
+	TTL time.Duration
+}
+
+type record struct {
+	Name      string
+	Version   string
+	Metadata  map[string]string
+	Nodes     map[string]*node
+	Endpoints []*Endpoint
+}
+
+type memRegistry struct {
+	options *Options
+
+	records  map[string]map[string]*record
+	watchers map[string]*memWatcher
+
+	sync.RWMutex
+}
+
+func NewMemoryRegistry(opts ...Option) Registry {
+	options := NewOptions(opts...)
+
+	records := getServiceRecords(options.Context)
+	if records == nil {
+		records = make(map[string]map[string]*record)
+	}
+
+	reg := &memRegistry{
+		options:  options,
+		records:  records,
+		watchers: make(map[string]*memWatcher),
+	}
+
+	go reg.ttlPrune()
+
+	return reg
+}
+
+func (m *memRegistry) ttlPrune() {
+	logger := m.options.Logger
+	prune := time.NewTicker(ttlPruneTime)
+	defer prune.Stop()
+
+	for range prune.C {
+		m.Lock()
+		for name, records := range m.records {
+			for version, record := range records {
+				for id, n := range record.Nodes {
+					if n.TTL != 0 && time.Since(n.LastSeen) > n.TTL {
+						logger.Logf(log.DebugLevel, "Registry TTL expired for node %s of service %s", n.Id, name)
+						delete(m.records[name][version].Nodes, id)
+					}
+				}
+			}
+		}
+		m.Unlock()
+	}
+}
+
+func (m *memRegistry) sendEvent(r *Result) {
+	m.RLock()
+	watchers := make([]*memWatcher, 0, len(m.watchers))
+	for _, w := range m.watchers {
+		watchers = append(watchers, w)
+	}
+	m.RUnlock()
+
+	for _, w := range watchers {
+		select {
+		case <-w.exit:
+			m.Lock()
+			delete(m.watchers, w.id)
+			m.Unlock()
+		default:
+			select {
+			case w.res <- r:
+			case <-time.After(sendEventTime):
+			}
+		}
+	}
+}
+
+func (m *memRegistry) Init(opts ...Option) error {
+	for _, o := range opts {
+		o(m.options)
+	}
+
+	// add services
+	m.Lock()
+	defer m.Unlock()
+
+	records := getServiceRecords(m.options.Context)
+	for name, record := range records {
+		// add a whole new service including all of its versions
+		if _, ok := m.records[name]; !ok {
+			m.records[name] = record
+			continue
+		}
+		// add the versions of the service we dont track yet
+		for version, r := range record {
+			if _, ok := m.records[name][version]; !ok {
+				m.records[name][version] = r
+				continue
+			}
+		}
+	}
+
+	return nil
+}
+
+func (m *memRegistry) Options() Options {
+	return *m.options
+}
+
+func (m *memRegistry) Register(s *Service, opts ...RegisterOption) error {
+	m.Lock()
+	defer m.Unlock()
+	logger := m.options.Logger
+	var options RegisterOptions
+	for _, o := range opts {
+		o(&options)
+	}
+
+	r := serviceToRecord(s, options.TTL)
+
+	if _, ok := m.records[s.Name]; !ok {
+		m.records[s.Name] = make(map[string]*record)
+	}
+
+	if _, ok := m.records[s.Name][s.Version]; !ok {
+		m.records[s.Name][s.Version] = r
+		logger.Logf(log.DebugLevel, "Registry added new service: %s, version: %s", s.Name, s.Version)
+		go m.sendEvent(&Result{Action: "update", Service: s})
+		return nil
+	}
+
+	addedNodes := false
+	for _, n := range s.Nodes {
+		if _, ok := m.records[s.Name][s.Version].Nodes[n.Id]; !ok {
+			addedNodes = true
+			metadata := make(map[string]string)
+			for k, v := range n.Metadata {
+				metadata[k] = v
+			}
+			m.records[s.Name][s.Version].Nodes[n.Id] = &node{
+				Node: &Node{
+					Id:       n.Id,
+					Address:  n.Address,
+					Metadata: metadata,
+				},
+				TTL:      options.TTL,
+				LastSeen: time.Now(),
+			}
+		}
+	}
+
+	if addedNodes {
+		logger.Logf(log.DebugLevel, "Registry added new node to service: %s, version: %s", s.Name, s.Version)
+		go m.sendEvent(&Result{Action: "update", Service: s})
+		return nil
+	}
+
+	// refresh TTL and timestamp
+	for _, n := range s.Nodes {
+		logger.Logf(log.DebugLevel, "Updated registration for service: %s, version: %s", s.Name, s.Version)
+		m.records[s.Name][s.Version].Nodes[n.Id].TTL = options.TTL
+		m.records[s.Name][s.Version].Nodes[n.Id].LastSeen = time.Now()
+	}
+
+	return nil
+}
+
+func (m *memRegistry) Deregister(s *Service, opts ...DeregisterOption) error {
+	m.Lock()
+	defer m.Unlock()
+	logger := m.options.Logger
+	if _, ok := m.records[s.Name]; ok {
+		if _, ok := m.records[s.Name][s.Version]; ok {
+			for _, n := range s.Nodes {
+				if _, ok := m.records[s.Name][s.Version].Nodes[n.Id]; ok {
+					logger.Logf(log.DebugLevel, "Registry removed node from service: %s, version: %s", s.Name, s.Version)
+					delete(m.records[s.Name][s.Version].Nodes, n.Id)
+				}
+			}
+			if len(m.records[s.Name][s.Version].Nodes) == 0 {
+				delete(m.records[s.Name], s.Version)
+				logger.Logf(log.DebugLevel, "Registry removed service: %s, version: %s", s.Name, s.Version)
+			}
+		}
+		if len(m.records[s.Name]) == 0 {
+			delete(m.records, s.Name)
+			logger.Logf(log.DebugLevel, "Registry removed service: %s", s.Name)
+		}
+		go m.sendEvent(&Result{Action: "delete", Service: s})
+	}
+
+	return nil
+}
+
+func (m *memRegistry) GetService(name string, opts ...GetOption) ([]*Service, error) {
+	m.RLock()
+	defer m.RUnlock()
+
+	records, ok := m.records[name]
+	if !ok {
+		return nil, ErrNotFound
+	}
+
+	services := make([]*Service, len(m.records[name]))
+	i := 0
+	for _, record := range records {
+		services[i] = recordToService(record)
+		i++
+	}
+
+	return services, nil
+}
+
+func (m *memRegistry) ListServices(opts ...ListOption) ([]*Service, error) {
+	m.RLock()
+	defer m.RUnlock()
+
+	var services []*Service
+	for _, records := range m.records {
+		for _, record := range records {
+			services = append(services, recordToService(record))
+		}
+	}
+
+	return services, nil
+}
+
+func (m *memRegistry) Watch(opts ...WatchOption) (Watcher, error) {
+	var wo WatchOptions
+	for _, o := range opts {
+		o(&wo)
+	}
+
+	w := &memWatcher{
+		exit: make(chan bool),
+		res:  make(chan *Result),
+		id:   uuid.New().String(),
+		wo:   wo,
+	}
+
+	m.Lock()
+	m.watchers[w.id] = w
+	m.Unlock()
+
+	return w, nil
+}
+
+func (m *memRegistry) String() string {
+	return "memory"
+}

registry/memory_test.go

@@ -0,0 +1,244 @@
+package registry
+
+import (
+	"fmt"
+	"os"
+	"testing"
+	"time"
+)
+
+var (
+	testData = map[string][]*Service{
+		"foo": {
+			{
+				Name:    "foo",
+				Version: "1.0.0",
+				Nodes: []*Node{
+					{
+						Id:      "foo-1.0.0-123",
+						Address: "localhost:9999",
+					},
+					{
+						Id:      "foo-1.0.0-321",
+						Address: "localhost:9999",
+					},
+				},
+			},
+			{
+				Name:    "foo",
+				Version: "1.0.1",
+				Nodes: []*Node{
+					{
+						Id:      "foo-1.0.1-321",
+						Address: "localhost:6666",
+					},
+				},
+			},
+			{
+				Name:    "foo",
+				Version: "1.0.3",
+				Nodes: []*Node{
+					{
+						Id:      "foo-1.0.3-345",
+						Address: "localhost:8888",
+					},
+				},
+			},
+		},
+		"bar": {
+			{
+				Name:    "bar",
+				Version: "default",
+				Nodes: []*Node{
+					{
+						Id:      "bar-1.0.0-123",
+						Address: "localhost:9999",
+					},
+					{
+						Id:      "bar-1.0.0-321",
+						Address: "localhost:9999",
+					},
+				},
+			},
+			{
+				Name:    "bar",
+				Version: "latest",
+				Nodes: []*Node{
+					{
+						Id:      "bar-1.0.1-321",
+						Address: "localhost:6666",
+					},
+				},
+			},
+		},
+	}
+)
+
+func TestMemoryRegistry(t *testing.T) {
+	m := NewMemoryRegistry()
+
+	fn := func(k string, v []*Service) {
+		services, err := m.GetService(k)
+		if err != nil {
+			t.Errorf("Unexpected error getting service %s: %v", k, err)
+		}
+
+		if len(services) != len(v) {
+			t.Errorf("Expected %d services for %s, got %d", len(v), k, len(services))
+		}
+
+		for _, service := range v {
+			var seen bool
+			for _, s := range services {
+				if s.Version == service.Version {
+					seen = true
+					break
+				}
+			}
+			if !seen {
+				t.Errorf("expected to find version %s", service.Version)
+			}
+		}
+	}
+
+	// register data
+	for _, v := range testData {
+		serviceCount := 0
+		for _, service := range v {
+			if err := m.Register(service); err != nil {
+				t.Errorf("Unexpected register error: %v", err)
+			}
+			serviceCount++
+			// after the service has been registered we should be able to query it
+			services, err := m.GetService(service.Name)
+			if err != nil {
+				t.Errorf("Unexpected error getting service %s: %v", service.Name, err)
+			}
+			if len(services) != serviceCount {
+				t.Errorf("Expected %d services for %s, got %d", serviceCount, service.Name, len(services))
+			}
+		}
+	}
+
+	// using test data
+	for k, v := range testData {
+		fn(k, v)
+	}
+
+	services, err := m.ListServices()
+	if err != nil {
+		t.Errorf("Unexpected error when listing services: %v", err)
+	}
+
+	totalServiceCount := 0
+	for _, testSvc := range testData {
+		for range testSvc {
+			totalServiceCount++
+		}
+	}
+
+	if len(services) != totalServiceCount {
+		t.Errorf("Expected total service count: %d, got: %d", totalServiceCount, len(services))
+	}
+
+	// deregister
+	for _, v := range testData {
+		for _, service := range v {
+			if err := m.Deregister(service); err != nil {
+				t.Errorf("Unexpected deregister error: %v", err)
+			}
+		}
+	}
+
+	// after all the service nodes have been deregistered we should not get any results
+	for _, v := range testData {
+		for _, service := range v {
+			services, err := m.GetService(service.Name)
+			if err != ErrNotFound {
+				t.Errorf("Expected error: %v, got: %v", ErrNotFound, err)
+			}
+			if len(services) != 0 {
+				t.Errorf("Expected %d services for %s, got %d", 0, service.Name, len(services))
+			}
+		}
+	}
+}
+
+func TestMemoryRegistryTTL(t *testing.T) {
+	m := NewMemoryRegistry()
+
+	for _, v := range testData {
+		for _, service := range v {
+			if err := m.Register(service, RegisterTTL(time.Millisecond)); err != nil {
+				t.Fatal(err)
+			}
+		}
+	}
+
+	time.Sleep(ttlPruneTime * 2)
+
+	for name := range testData {
+		svcs, err := m.GetService(name)
+		if err != nil {
+			t.Fatal(err)
+		}
+
+		for _, svc := range svcs {
+			if len(svc.Nodes) > 0 {
+				t.Fatalf("Service %q still has nodes registered", name)
+			}
+		}
+	}
+}
+
+func TestMemoryRegistryTTLConcurrent(t *testing.T) {
+	concurrency := 1000
+	waitTime := ttlPruneTime * 2
+	m := NewMemoryRegistry()
+
+	for _, v := range testData {
+		for _, service := range v {
+			if err := m.Register(service, RegisterTTL(waitTime/2)); err != nil {
+				t.Fatal(err)
+			}
+		}
+	}
+
+	if len(os.Getenv("IN_TRAVIS_CI")) == 0 {
+		t.Logf("test will wait %v, then check TTL timeouts", waitTime)
+	}
+
+	errChan := make(chan error, concurrency)
+	syncChan := make(chan struct{})
+
+	for i := 0; i < concurrency; i++ {
+		go func() {
+			<-syncChan
+			for name := range testData {
+				svcs, err := m.GetService(name)
+				if err != nil {
+					errChan <- err
+					return
+				}
+
+				for _, svc := range svcs {
+					if len(svc.Nodes) > 0 {
+						errChan <- fmt.Errorf("Service %q still has nodes registered", name)
+						return
+					}
+				}
+			}
+
+			errChan <- nil
+		}()
+	}
+
+	time.Sleep(waitTime)
+	close(syncChan)
+
+	for i := 0; i < concurrency; i++ {
+		if err := <-errChan; err != nil {
+			t.Fatal(err)
+		}
+	}
+}

registry/memory_util.go

@@ -0,0 +1,87 @@
+package registry
+
+import (
+	"time"
+)
+
+func serviceToRecord(s *Service, ttl time.Duration) *record {
+	metadata := make(map[string]string, len(s.Metadata))
+	for k, v := range s.Metadata {
+		metadata[k] = v
+	}
+
+	nodes := make(map[string]*node, len(s.Nodes))
+	for _, n := range s.Nodes {
+		nodes[n.Id] = &node{
+			Node:     n,
+			TTL:      ttl,
+			LastSeen: time.Now(),
+		}
+	}
+
+	endpoints := make([]*Endpoint, len(s.Endpoints))
+	copy(endpoints, s.Endpoints)
+
+	return &record{
+		Name:      s.Name,
+		Version:   s.Version,
+		Metadata:  metadata,
+		Nodes:     nodes,
+		Endpoints: endpoints,
+	}
+}
+
+func recordToService(r *record) *Service {
+	metadata := make(map[string]string, len(r.Metadata))
+	for k, v := range r.Metadata {
+		metadata[k] = v
+	}
+
+	endpoints := make([]*Endpoint, len(r.Endpoints))
+	for i, e := range r.Endpoints {
+		request := new(Value)
+		if e.Request != nil {
+			*request = *e.Request
+		}
+		response := new(Value)
+		if e.Response != nil {
+			*response = *e.Response
+		}
+
+		metadata := make(map[string]string, len(e.Metadata))
+		for k, v := range e.Metadata {
+			metadata[k] = v
+		}
+
+		endpoints[i] = &Endpoint{
+			Name:     e.Name,
+			Request:  request,
+			Response: response,
+			Metadata: metadata,
+		}
+	}
+
+	nodes := make([]*Node, len(r.Nodes))
+	i := 0
+	for _, n := range r.Nodes {
+		metadata := make(map[string]string, len(n.Metadata))
+		for k, v := range n.Metadata {
+			metadata[k] = v
+		}
+
+		nodes[i] = &Node{
+			Id:       n.Id,
+			Address:  n.Address,
+			Metadata: metadata,
+		}
+		i++
+	}
+
+	return &Service{
+		Name:      r.Name,
+		Version:   r.Version,
+		Metadata:  metadata,
+		Endpoints: endpoints,
+		Nodes:     nodes,
+	}
+}

registry/memory_watcher.go

@@ -0,0 +1,35 @@
+package registry
+
+import (
+	"errors"
+)
+
+type memWatcher struct {
+	wo   WatchOptions
+	res  chan *Result
+	exit chan bool
+	id   string
+}
+
+func (m *memWatcher) Next() (*Result, error) {
+	for {
+		select {
+		case r := <-m.res:
+			if len(m.wo.Service) > 0 && m.wo.Service != r.Service.Name {
+				continue
+			}
+			return r, nil
+		case <-m.exit:
+			return nil, errors.New("watcher stopped")
+		}
+	}
+}
+
+func (m *memWatcher) Stop() {
+	select {
+	case <-m.exit:
+		return
+	default:
+		close(m.exit)
+	}
+}

registry/nats/nats.go

@@ -0,0 +1,417 @@
+// Package nats provides a NATS registry using broadcast queries
+package nats
+
+import (
+	"context"
+	"encoding/json"
+	"strings"
+	"sync"
+	"time"
+
+	"github.com/nats-io/nats.go"
+	"go-micro.dev/v6/registry"
+)
+
+type natsRegistry struct {
+	addrs          []string
+	opts           registry.Options
+	nopts          nats.Options
+	queryTopic     string
+	watchTopic     string
+	registerAction string
+
+	sync.RWMutex
+	conn      *nats.Conn
+	services  map[string][]*registry.Service
+	listeners map[string]chan bool
+}
+
+var (
+	defaultQueryTopic     = "micro.nats.query"
+	defaultWatchTopic     = "micro.nats.watch"
+	defaultRegisterAction = "create"
+)
+
+func configure(n *natsRegistry, opts ...registry.Option) error {
+	for _, o := range opts {
+		o(&n.opts)
+	}
+
+	natsOptions := nats.GetDefaultOptions()
+	if n, ok := n.opts.Context.Value(optionsKey{}).(nats.Options); ok {
+		natsOptions = n
+	}
+
+	queryTopic := defaultQueryTopic
+	if qt, ok := n.opts.Context.Value(queryTopicKey{}).(string); ok {
+		queryTopic = qt
+	}
+
+	watchTopic := defaultWatchTopic
+	if wt, ok := n.opts.Context.Value(watchTopicKey{}).(string); ok {
+		watchTopic = wt
+	}
+
+	registerAction := defaultRegisterAction
+	if ra, ok := n.opts.Context.Value(registerActionKey{}).(string); ok {
+		registerAction = ra
+	}
+
+	// Options have higher priority than nats.Options
+	// only if Addrs, Secure or TLSConfig were not set through a Option
+	// we read them from nats.Option
+	if len(n.opts.Addrs) == 0 {
+		n.opts.Addrs = natsOptions.Servers
+	}
+
+	if !n.opts.Secure {
+		n.opts.Secure = natsOptions.Secure
+	}
+
+	if n.opts.TLSConfig == nil {
+		n.opts.TLSConfig = natsOptions.TLSConfig
+	}
+
+	// check & add nats:// prefix (this makes also sure that the addresses
+	// stored in natsaddrs and n.opts.Addrs are identical)
+	n.opts.Addrs = setAddrs(n.opts.Addrs)
+
+	n.addrs = n.opts.Addrs
+	n.nopts = natsOptions
+	n.queryTopic = queryTopic
+	n.watchTopic = watchTopic
+	n.registerAction = registerAction
+
+	return nil
+}
+
+func setAddrs(addrs []string) []string {
+	var cAddrs []string
+	for _, addr := range addrs {
+		if len(addr) == 0 {
+			continue
+		}
+		if !strings.HasPrefix(addr, "nats://") {
+			addr = "nats://" + addr
+		}
+		cAddrs = append(cAddrs, addr)
+	}
+	if len(cAddrs) == 0 {
+		cAddrs = []string{nats.DefaultURL}
+	}
+	return cAddrs
+}
+
+func (n *natsRegistry) newConn() (*nats.Conn, error) {
+	opts := n.nopts
+	opts.Servers = n.addrs
+	opts.Secure = n.opts.Secure
+	opts.TLSConfig = n.opts.TLSConfig
+
+	// secure might not be set
+	if opts.TLSConfig != nil {
+		opts.Secure = true
+	}
+
+	return opts.Connect()
+}
+
+func (n *natsRegistry) getConn() (*nats.Conn, error) {
+	n.Lock()
+	defer n.Unlock()
+
+	if n.conn != nil {
+		return n.conn, nil
+	}
+
+	c, err := n.newConn()
+	if err != nil {
+		return nil, err
+	}
+	n.conn = c
+
+	return n.conn, nil
+}
+
+func (n *natsRegistry) register(s *registry.Service) error {
+	conn, err := n.getConn()
+	if err != nil {
+		return err
+	}
+
+	n.Lock()
+	defer n.Unlock()
+
+	// cache service
+	n.services[s.Name] = addServices(n.services[s.Name], cp([]*registry.Service{s}))
+
+	// create query listener
+	if n.listeners[s.Name] == nil {
+		listener := make(chan bool)
+
+		// create a subscriber that responds to queries
+		sub, err := conn.Subscribe(n.queryTopic, func(m *nats.Msg) {
+			var result *registry.Result
+
+			if err := json.Unmarshal(m.Data, &result); err != nil {
+				return
+			}
+
+			var services []*registry.Service
+
+			switch result.Action {
+			// is this a get query and we own the service?
+			case "get":
+				if result.Service.Name != s.Name {
+					return
+				}
+				n.RLock()
+				services = cp(n.services[s.Name])
+				n.RUnlock()
+			// it's a list request, but we're still only a
+			// subscriber for this service... so just get this service
+			// totally suboptimal
+			case "list":
+				n.RLock()
+				services = cp(n.services[s.Name])
+				n.RUnlock()
+			default:
+				// does not match
+				return
+			}
+
+			// respond to query
+			for _, service := range services {
+				b, err := json.Marshal(service)
+				if err != nil {
+					continue
+				}
+				_ = conn.Publish(m.Reply, b)
+			}
+		})
+		if err != nil {
+			return err
+		}
+
+		// Unsubscribe if we're told to do so
+		go func() {
+			<-listener
+			_ = sub.Unsubscribe()
+		}()
+
+		n.listeners[s.Name] = listener
+	}
+
+	return nil
+}
+
+func (n *natsRegistry) deregister(s *registry.Service) error {
+	n.Lock()
+	defer n.Unlock()
+
+	services := delServices(n.services[s.Name], cp([]*registry.Service{s}))
+	if len(services) > 0 {
+		n.services[s.Name] = services
+		return nil
+	}
+
+	// delete cached service
+	delete(n.services, s.Name)
+
+	// delete query listener
+	if listener, lexists := n.listeners[s.Name]; lexists {
+		close(listener)
+		delete(n.listeners, s.Name)
+	}
+
+	return nil
+}
+
+func (n *natsRegistry) query(s string, quorum int) ([]*registry.Service, error) {
+	conn, err := n.getConn()
+	if err != nil {
+		return nil, err
+	}
+
+	var action string
+	var service *registry.Service
+
+	if len(s) > 0 {
+		action = "get"
+		service = &registry.Service{Name: s}
+	} else {
+		action = "list"
+	}
+
+	inbox := nats.NewInbox()
+
+	response := make(chan *registry.Service, 10)
+
+	sub, err := conn.Subscribe(inbox, func(m *nats.Msg) {
+		var service *registry.Service
+		if err := json.Unmarshal(m.Data, &service); err != nil {
+			return
+		}
+		select {
+		case response <- service:
+		case <-time.After(n.opts.Timeout):
+		}
+	})
+	if err != nil {
+		return nil, err
+	}
+	defer func() { _ = sub.Unsubscribe() }()
+
+	b, err := json.Marshal(&registry.Result{Action: action, Service: service})
+	if err != nil {
+		return nil, err
+	}
+
+	if err := conn.PublishMsg(&nats.Msg{
+		Subject: n.queryTopic,
+		Reply:   inbox,
+		Data:    b,
+	}); err != nil {
+		return nil, err
+	}
+
+	timeoutChan := time.After(n.opts.Timeout)
+
+	serviceMap := make(map[string]*registry.Service)
+
+loop:
+	for {
+		select {
+		case service := <-response:
+			key := service.Name + "-" + service.Version
+			srv, ok := serviceMap[key]
+			if ok {
+				srv.Nodes = append(srv.Nodes, service.Nodes...)
+				serviceMap[key] = srv
+			} else {
+				serviceMap[key] = service
+			}
+
+			if quorum > 0 && len(serviceMap[key].Nodes) >= quorum {
+				break loop
+			}
+		case <-timeoutChan:
+			break loop
+		}
+	}
+
+	var services []*registry.Service
+	for _, service := range serviceMap {
+		services = append(services, service)
+	}
+	return services, nil
+}
+
+func (n *natsRegistry) Init(opts ...registry.Option) error {
+	return configure(n, opts...)
+}
+
+func (n *natsRegistry) Options() registry.Options {
+	return n.opts
+}
+
+func (n *natsRegistry) Register(s *registry.Service, opts ...registry.RegisterOption) error {
+	if err := n.register(s); err != nil {
+		return err
+	}
+
+	conn, err := n.getConn()
+	if err != nil {
+		return err
+	}
+
+	b, err := json.Marshal(&registry.Result{Action: n.registerAction, Service: s})
+	if err != nil {
+		return err
+	}
+
+	return conn.Publish(n.watchTopic, b)
+}
+
+func (n *natsRegistry) Deregister(s *registry.Service, opts ...registry.DeregisterOption) error {
+	if err := n.deregister(s); err != nil {
+		return err
+	}
+
+	conn, err := n.getConn()
+	if err != nil {
+		return err
+	}
+
+	b, err := json.Marshal(&registry.Result{Action: "delete", Service: s})
+	if err != nil {
+		return err
+	}
+	return conn.Publish(n.watchTopic, b)
+}
+
+func (n *natsRegistry) GetService(s string, opts ...registry.GetOption) ([]*registry.Service, error) {
+	services, err := n.query(s, getQuorum(n.opts))
+	if err != nil {
+		return nil, err
+	}
+	return services, nil
+}
+
+func (n *natsRegistry) ListServices(opts ...registry.ListOption) ([]*registry.Service, error) {
+	s, err := n.query("", 0)
+	if err != nil {
+		return nil, err
+	}
+
+	var services []*registry.Service
+	serviceMap := make(map[string]*registry.Service)
+
+	for _, v := range s {
+		serviceMap[v.Name] = &registry.Service{Name: v.Name, Version: v.Version}
+	}
+
+	for _, v := range serviceMap {
+		services = append(services, v)
+	}
+
+	return services, nil
+}
+
+func (n *natsRegistry) Watch(opts ...registry.WatchOption) (registry.Watcher, error) {
+	conn, err := n.getConn()
+	if err != nil {
+		return nil, err
+	}
+
+	sub, err := conn.SubscribeSync(n.watchTopic)
+	if err != nil {
+		return nil, err
+	}
+
+	var wo registry.WatchOptions
+	for _, o := range opts {
+		o(&wo)
+	}
+
+	return &natsWatcher{sub, wo}, nil
+}
+
+func (n *natsRegistry) String() string {
+	return "nats"
+}
+
+func NewNatsRegistry(opts ...registry.Option) registry.Registry {
+	options := registry.Options{
+		Timeout: time.Millisecond * 100,
+		Context: context.Background(),
+	}
+
+	n := &natsRegistry{
+		opts:      options,
+		services:  make(map[string][]*registry.Service),
+		listeners: make(map[string]chan bool),
+	}
+	_ = configure(n, opts...)
+	return n
+}

registry/nats/nats_assert_test.go

@@ -0,0 +1,18 @@
+package nats_test
+
+import (
+	"reflect"
+	"testing"
+)
+
+func assertNoError(tb testing.TB, actual error) {
+	if actual != nil {
+		tb.Errorf("expected no error, got %v", actual)
+	}
+}
+
+func assertEqual(tb testing.TB, expected, actual interface{}) {
+	if !reflect.DeepEqual(expected, actual) {
+		tb.Errorf("expected %v, got %v", expected, actual)
+	}
+}

registry/nats/nats_environment_test.go

@@ -0,0 +1,69 @@
+package nats_test
+
+import (
+	"os"
+	"testing"
+
+	log "go-micro.dev/v6/logger"
+	"go-micro.dev/v6/registry"
+	"go-micro.dev/v6/registry/nats"
+)
+
+type environment struct {
+	registryOne   registry.Registry
+	registryTwo   registry.Registry
+	registryThree registry.Registry
+
+	serviceOne registry.Service
+	serviceTwo registry.Service
+
+	nodeOne   registry.Node
+	nodeTwo   registry.Node
+	nodeThree registry.Node
+}
+
+var e environment
+
+func TestMain(m *testing.M) {
+	natsURL := os.Getenv("NATS_URL")
+	if natsURL == "" {
+		log.Infof("NATS_URL is undefined - skipping tests")
+		return
+	}
+
+	e.registryOne = nats.NewNatsRegistry(registry.Addrs(natsURL), nats.Quorum(1))
+	e.registryTwo = nats.NewNatsRegistry(registry.Addrs(natsURL), nats.Quorum(1))
+	e.registryThree = nats.NewNatsRegistry(registry.Addrs(natsURL), nats.Quorum(1))
+
+	e.serviceOne.Name = "one"
+	e.serviceOne.Version = "default"
+	e.serviceOne.Nodes = []*registry.Node{&e.nodeOne}
+
+	e.serviceTwo.Name = "two"
+	e.serviceTwo.Version = "default"
+	e.serviceTwo.Nodes = []*registry.Node{&e.nodeOne, &e.nodeTwo}
+
+	e.nodeOne.Id = "one"
+	e.nodeTwo.Id = "two"
+	e.nodeThree.Id = "three"
+
+	if err := e.registryOne.Register(&e.serviceOne); err != nil {
+		log.Fatal(err)
+	}
+
+	if err := e.registryOne.Register(&e.serviceTwo); err != nil {
+		log.Fatal(err)
+	}
+
+	result := m.Run()
+
+	if err := e.registryOne.Deregister(&e.serviceOne); err != nil {
+		log.Fatal(err)
+	}
+
+	if err := e.registryOne.Deregister(&e.serviceTwo); err != nil {
+		log.Fatal(err)
+	}
+
+	os.Exit(result)
+}

registry/nats/nats_options.go

@@ -0,0 +1,87 @@
+package nats
+
+import (
+	"context"
+
+	"github.com/nats-io/nats.go"
+	"go-micro.dev/v6/registry"
+)
+
+type contextQuorumKey struct{}
+type optionsKey struct{}
+type watchTopicKey struct{}
+type queryTopicKey struct{}
+type registerActionKey struct{}
+
+var (
+	DefaultQuorum = 0
+)
+
+func getQuorum(o registry.Options) int {
+	if o.Context == nil {
+		return DefaultQuorum
+	}
+
+	value := o.Context.Value(contextQuorumKey{})
+	if v, ok := value.(int); ok {
+		return v
+	} else {
+		return DefaultQuorum
+	}
+}
+
+func Quorum(n int) registry.Option {
+	return func(o *registry.Options) {
+		o.Context = context.WithValue(o.Context, contextQuorumKey{}, n)
+	}
+}
+
+// Options allow to inject a nats.Options struct for configuring
+// the nats connection.
+func NatsOptions(nopts nats.Options) registry.Option {
+	return func(o *registry.Options) {
+		if o.Context == nil {
+			o.Context = context.Background()
+		}
+		o.Context = context.WithValue(o.Context, optionsKey{}, nopts)
+	}
+}
+
+// QueryTopic allows to set a custom nats topic on which service registries
+// query (survey) other services. All registries listen on this topic and
+// then respond to the query message.
+func QueryTopic(s string) registry.Option {
+	return func(o *registry.Options) {
+		if o.Context == nil {
+			o.Context = context.Background()
+		}
+		o.Context = context.WithValue(o.Context, queryTopicKey{}, s)
+	}
+}
+
+// WatchTopic allows to set a custom nats topic on which registries broadcast
+// changes (e.g. when services are added, updated or removed). Since we don't
+// have a central registry service, each service typically broadcasts in a
+// determined frequency on this topic.
+func WatchTopic(s string) registry.Option {
+	return func(o *registry.Options) {
+		if o.Context == nil {
+			o.Context = context.Background()
+		}
+		o.Context = context.WithValue(o.Context, watchTopicKey{}, s)
+	}
+}
+
+// RegisterAction allows to set the action to use when registering to nats.
+// As of now there are three different options:
+// - "create" (default) only registers if there is noone already registered under the same key.
+// - "update" only updates the registration if it already exists.
+// - "put" creates or updates a registration
+func RegisterAction(s string) registry.Option {
+	return func(o *registry.Options) {
+		if o.Context == nil {
+			o.Context = context.Background()
+		}
+		o.Context = context.WithValue(o.Context, registerActionKey{}, s)
+	}
+}

registry/nats/nats_registry.go

@@ -0,0 +1,5 @@
+package nats
+
+var (
+	DefaultRegistry = NewNatsRegistry()
+)

registry/nats/nats_test.go

@@ -0,0 +1,95 @@
+package nats_test
+
+import (
+	"testing"
+
+	"go-micro.dev/v6/registry"
+)
+
+func TestRegister(t *testing.T) {
+	service := registry.Service{Name: "test"}
+	assertNoError(t, e.registryOne.Register(&service))
+	defer e.registryOne.Deregister(&service)
+
+	services, err := e.registryOne.ListServices()
+	assertNoError(t, err)
+	assertEqual(t, 3, len(services))
+
+	services, err = e.registryTwo.ListServices()
+	assertNoError(t, err)
+	assertEqual(t, 3, len(services))
+}
+
+func TestDeregister(t *testing.T) {
+	service1 := registry.Service{Name: "test-deregister", Version: "v1"}
+	service2 := registry.Service{Name: "test-deregister", Version: "v2"}
+
+	assertNoError(t, e.registryOne.Register(&service1))
+	services, err := e.registryOne.GetService(service1.Name)
+	assertNoError(t, err)
+	assertEqual(t, 1, len(services))
+
+	assertNoError(t, e.registryOne.Register(&service2))
+	services, err = e.registryOne.GetService(service2.Name)
+	assertNoError(t, err)
+	assertEqual(t, 2, len(services))
+
+	assertNoError(t, e.registryOne.Deregister(&service1))
+	services, err = e.registryOne.GetService(service1.Name)
+	assertNoError(t, err)
+	assertEqual(t, 1, len(services))
+
+	assertNoError(t, e.registryOne.Deregister(&service2))
+	services, err = e.registryOne.GetService(service1.Name)
+	assertNoError(t, err)
+	assertEqual(t, 0, len(services))
+}
+
+func TestGetService(t *testing.T) {
+	services, err := e.registryTwo.GetService("one")
+	assertNoError(t, err)
+	assertEqual(t, 1, len(services))
+	assertEqual(t, "one", services[0].Name)
+	assertEqual(t, 1, len(services[0].Nodes))
+}
+
+func TestGetServiceWithNoNodes(t *testing.T) {
+	services, err := e.registryOne.GetService("missing")
+	assertNoError(t, err)
+	assertEqual(t, 0, len(services))
+}
+
+func TestGetServiceFromMultipleNodes(t *testing.T) {
+	services, err := e.registryOne.GetService("two")
+	assertNoError(t, err)
+	assertEqual(t, 1, len(services))
+	assertEqual(t, "two", services[0].Name)
+	assertEqual(t, 2, len(services[0].Nodes))
+}
+
+func BenchmarkGetService(b *testing.B) {
+	for n := 0; n < b.N; n++ {
+		services, err := e.registryTwo.GetService("one")
+		assertNoError(b, err)
+		assertEqual(b, 1, len(services))
+		assertEqual(b, "one", services[0].Name)
+	}
+}
+
+func BenchmarkGetServiceWithNoNodes(b *testing.B) {
+	for n := 0; n < b.N; n++ {
+		services, err := e.registryOne.GetService("missing")
+		assertNoError(b, err)
+		assertEqual(b, 0, len(services))
+	}
+}
+
+func BenchmarkGetServiceFromMultipleNodes(b *testing.B) {
+	for n := 0; n < b.N; n++ {
+		services, err := e.registryTwo.GetService("two")
+		assertNoError(b, err)
+		assertEqual(b, 1, len(services))
+		assertEqual(b, "two", services[0].Name)
+		assertEqual(b, 2, len(services[0].Nodes))
+	}
+}

registry/nats/nats_util.go

@@ -0,0 +1,107 @@
+package nats
+
+import "go-micro.dev/v6/registry"
+
+func cp(current []*registry.Service) []*registry.Service {
+	var services []*registry.Service
+
+	for _, service := range current {
+		// copy service
+		s := new(registry.Service)
+		*s = *service
+
+		// copy nodes
+		var nodes []*registry.Node
+		for _, node := range service.Nodes {
+			n := new(registry.Node)
+			*n = *node
+			nodes = append(nodes, n)
+		}
+		s.Nodes = nodes
+
+		// copy endpoints
+		var eps []*registry.Endpoint
+		for _, ep := range service.Endpoints {
+			e := new(registry.Endpoint)
+			*e = *ep
+			eps = append(eps, e)
+		}
+		s.Endpoints = eps
+
+		// append service
+		services = append(services, s)
+	}
+
+	return services
+}
+
+func addNodes(old, neu []*registry.Node) []*registry.Node {
+	for _, n := range neu {
+		var seen bool
+		for i, o := range old {
+			if o.Id == n.Id {
+				seen = true
+				old[i] = n
+				break
+			}
+		}
+		if !seen {
+			old = append(old, n)
+		}
+	}
+	return old
+}
+
+func addServices(old, neu []*registry.Service) []*registry.Service {
+	for _, s := range neu {
+		var seen bool
+		for i, o := range old {
+			if o.Version == s.Version {
+				s.Nodes = addNodes(o.Nodes, s.Nodes)
+				seen = true
+				old[i] = s
+				break
+			}
+		}
+		if !seen {
+			old = append(old, s)
+		}
+	}
+	return old
+}
+
+func delNodes(old, del []*registry.Node) []*registry.Node {
+	var nodes []*registry.Node
+	for _, o := range old {
+		var rem bool
+		for _, n := range del {
+			if o.Id == n.Id {
+				rem = true
+				break
+			}
+		}
+		if !rem {
+			nodes = append(nodes, o)
+		}
+	}
+	return nodes
+}
+
+func delServices(old, del []*registry.Service) []*registry.Service {
+	var services []*registry.Service
+	for i, o := range old {
+		var rem bool
+		for _, s := range del {
+			if o.Version == s.Version {
+				old[i].Nodes = delNodes(o.Nodes, s.Nodes)
+				if len(old[i].Nodes) == 0 {
+					rem = true
+				}
+			}
+		}
+		if !rem {
+			services = append(services, o)
+		}
+	}
+	return services
+}

registry/nats/nats_watcher.go

@@ -0,0 +1,39 @@
+package nats
+
+import (
+	"encoding/json"
+	"time"
+
+	"github.com/nats-io/nats.go"
+	"go-micro.dev/v6/registry"
+)
+
+type natsWatcher struct {
+	sub *nats.Subscription
+	wo  registry.WatchOptions
+}
+
+func (n *natsWatcher) Next() (*registry.Result, error) {
+	var result *registry.Result
+	for {
+		m, err := n.sub.NextMsg(time.Minute)
+		if err != nil && err == nats.ErrTimeout {
+			continue
+		} else if err != nil {
+			return nil, err
+		}
+		if err := json.Unmarshal(m.Data, &result); err != nil {
+			return nil, err
+		}
+		if len(n.wo.Service) > 0 && result.Service.Name != n.wo.Service {
+			continue
+		}
+		break
+	}
+
+	return result, nil
+}
+
+func (n *natsWatcher) Stop() {
+	_ = n.sub.Unsubscribe()
+}

registry/options.go

@@ -0,0 +1,171 @@
+package registry
+
+import (
+	"context"
+	"crypto/tls"
+	"time"
+
+	"go-micro.dev/v6/logger"
+)
+
+type Options struct {
+	Logger logger.Logger
+	// Other options for implementations of the interface
+	// can be stored in a context
+	Context   context.Context
+	TLSConfig *tls.Config
+	Addrs     []string
+	Timeout   time.Duration
+	Secure    bool
+}
+
+type RegisterOptions struct {
+	// Other options for implementations of the interface
+	// can be stored in a context
+	Context context.Context
+	TTL     time.Duration
+}
+
+type WatchOptions struct {
+	// Other options for implementations of the interface
+	// can be stored in a context
+	Context context.Context
+	// Specify a service to watch
+	// If blank, the watch is for all services
+	Service string
+}
+
+type DeregisterOptions struct {
+	Context context.Context
+}
+
+type GetOptions struct {
+	Context context.Context
+}
+
+type ListOptions struct {
+	Context context.Context
+}
+
+func NewOptions(opts ...Option) *Options {
+	options := Options{
+		Context: context.Background(),
+		Logger:  logger.DefaultLogger,
+	}
+
+	for _, o := range opts {
+		o(&options)
+	}
+
+	return &options
+}
+
+// Addrs is the registry addresses to use.
+func Addrs(addrs ...string) Option {
+	return func(o *Options) {
+		o.Addrs = addrs
+	}
+}
+
+func Timeout(t time.Duration) Option {
+	return func(o *Options) {
+		o.Timeout = t
+	}
+}
+
+// Secure communication with the registry.
+func Secure(b bool) Option {
+	return func(o *Options) {
+		o.Secure = b
+	}
+}
+
+// Specify TLS Config.
+func TLSConfig(t *tls.Config) Option {
+	return func(o *Options) {
+		o.TLSConfig = t
+	}
+}
+
+func RegisterTTL(t time.Duration) RegisterOption {
+	return func(o *RegisterOptions) {
+		o.TTL = t
+	}
+}
+
+func RegisterContext(ctx context.Context) RegisterOption {
+	return func(o *RegisterOptions) {
+		o.Context = ctx
+	}
+}
+
+// Watch a service.
+func WatchService(name string) WatchOption {
+	return func(o *WatchOptions) {
+		o.Service = name
+	}
+}
+
+func WatchContext(ctx context.Context) WatchOption {
+	return func(o *WatchOptions) {
+		o.Context = ctx
+	}
+}
+
+func DeregisterContext(ctx context.Context) DeregisterOption {
+	return func(o *DeregisterOptions) {
+		o.Context = ctx
+	}
+}
+
+func GetContext(ctx context.Context) GetOption {
+	return func(o *GetOptions) {
+		o.Context = ctx
+	}
+}
+
+func ListContext(ctx context.Context) ListOption {
+	return func(o *ListOptions) {
+		o.Context = ctx
+	}
+}
+
+type servicesKey struct{}
+
+func getServiceRecords(ctx context.Context) map[string]map[string]*record {
+	memServices, ok := ctx.Value(servicesKey{}).(map[string][]*Service)
+	if !ok {
+		return nil
+	}
+
+	services := make(map[string]map[string]*record)
+
+	for name, svc := range memServices {
+		if _, ok := services[name]; !ok {
+			services[name] = make(map[string]*record)
+		}
+		// go through every version of the service
+		for _, s := range svc {
+			services[s.Name][s.Version] = serviceToRecord(s, 0)
+		}
+	}
+
+	return services
+}
+
+// Services is an option that preloads service data.
+func Services(s map[string][]*Service) Option {
+	return func(o *Options) {
+		if o.Context == nil {
+			o.Context = context.Background()
+		}
+		o.Context = context.WithValue(o.Context, servicesKey{}, s)
+	}
+}
+
+// Logger sets the underline logger.
+func Logger(l logger.Logger) Option {
+	return func(o *Options) {
+		o.Logger = l
+	}
+}

registry/options_test.go

@@ -0,0 +1,166 @@
+//go:build nats
+// +build nats
+
+package registry
+
+import (
+	"fmt"
+	"log"
+	"os"
+	"sync"
+	"testing"
+	"time"
+
+	"github.com/nats-io/nats.go"
+)
+
+var addrTestCases = []struct {
+	name        string
+	description string
+	addrs       map[string]string // expected address : set address
+}{
+	{
+		"registryOption",
+		"set registry addresses through a registry.Option in constructor",
+		map[string]string{
+			"nats://192.168.10.1:5222": "192.168.10.1:5222",
+			"nats://10.20.10.0:4222":   "10.20.10.0:4222"},
+	},
+	{
+		"natsOption",
+		"set registry addresses through the nats.Option in constructor",
+		map[string]string{
+			"nats://192.168.10.1:5222": "192.168.10.1:5222",
+			"nats://10.20.10.0:4222":   "10.20.10.0:4222"},
+	},
+	{
+		"default",
+		"check if default Address is set correctly",
+		map[string]string{
+			nats.DefaultURL: "",
+		},
+	},
+}
+
+func TestInitAddrs(t *testing.T) {
+	for _, tc := range addrTestCases {
+		t.Run(fmt.Sprintf("%s: %s", tc.name, tc.description), func(t *testing.T) {
+			var reg Registry
+			var addrs []string
+
+			for _, addr := range tc.addrs {
+				addrs = append(addrs, addr)
+			}
+
+			switch tc.name {
+			case "registryOption":
+				// we know that there are just two addrs in the dict
+				reg = NewRegistry(Addrs(addrs[0], addrs[1]))
+			case "natsOption":
+				nopts := nats.GetDefaultOptions()
+				nopts.Servers = addrs
+				reg = NewRegistry(Options(nopts))
+			case "default":
+				reg = NewRegistry()
+			}
+
+			// if err := reg.Register(dummyService); err != nil {
+			// 	t.Fatal(err)
+			// }
+
+			natsRegistry, ok := reg.(*natsRegistry)
+			if !ok {
+				t.Fatal("Expected registry to be of types *natsRegistry")
+			}
+			// check if the same amount of addrs we set has actually been set
+			if len(natsRegistry.addrs) != len(tc.addrs) {
+				t.Errorf("Expected Addr = %v, Actual Addr = %v",
+					natsRegistry.addrs, tc.addrs)
+				t.Errorf("Expected Addr count = %d, Actual Addr count = %d",
+					len(natsRegistry.addrs), len(tc.addrs))
+			}
+
+			for _, addr := range natsRegistry.addrs {
+				_, ok := tc.addrs[addr]
+				if !ok {
+					t.Errorf("Expected Addr = %v, Actual Addr = %v",
+						natsRegistry.addrs, tc.addrs)
+					t.Errorf("Expected '%s' has not been set", addr)
+				}
+			}
+		})
+	}
+}
+
+func TestWatchQueryTopic(t *testing.T) {
+	natsURL := os.Getenv("NATS_URL")
+	if natsURL == "" {
+		log.Println("NATS_URL is undefined - skipping tests")
+		return
+	}
+
+	watchTopic := "custom.test.watch"
+	queryTopic := "custom.test.query"
+	wt := WatchTopic(watchTopic)
+	qt := QueryTopic(queryTopic)
+
+	// connect to NATS and subscribe to the Watch & Query topics where the
+	// registry will publish a msg
+	nopts := nats.GetDefaultOptions()
+	nopts.Servers = setAddrs([]string{natsURL})
+	conn, err := nopts.Connect()
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	wg := sync.WaitGroup{}
+	wg.Add(2)
+
+	okCh := make(chan struct{})
+
+	// Wait until we have received something on both topics
+	go func() {
+		wg.Wait()
+		close(okCh)
+	}()
+
+	// handler just calls wg.Done()
+	rcvdHdlr := func(m *nats.Msg) {
+		wg.Done()
+	}
+
+	_, err = conn.Subscribe(queryTopic, rcvdHdlr)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	_, err = conn.Subscribe(watchTopic, rcvdHdlr)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	dummyService := &Service{
+		Name:    "TestInitAddr",
+		Version: "1.0.0",
+	}
+
+	reg := NewRegistry(qt, wt, Addrs(natsURL))
+
+	// trigger registry to send out message on watchTopic
+	if err := reg.Register(dummyService); err != nil {
+		t.Fatal(err)
+	}
+
+	// trigger registry to send out message on queryTopic
+	if _, err := reg.ListServices(); err != nil {
+		t.Fatal(err)
+	}
+
+	// make sure that we received something on tc.topic
+	select {
+	case <-okCh:
+		// fine - we received on both topics a message from the registry
+	case <-time.After(time.Millisecond * 200):
+		t.Fatal("timeout - no data received on watch topic")
+	}
+}

registry/registry.go

@@ -0,0 +1,99 @@
+// Package registry is an interface for service discovery
+package registry
+
+import (
+	"errors"
+)
+
+var (
+	// Not found error when GetService is called.
+	ErrNotFound = errors.New("service not found")
+	// Watcher stopped error when watcher is stopped.
+	ErrWatcherStopped = errors.New("watcher stopped")
+)
+
+// The registry provides an interface for service discovery
+// and an abstraction over varying implementations
+// {consul, etcd, zookeeper, ...}.
+type Registry interface {
+	Init(...Option) error
+	Options() Options
+	Register(*Service, ...RegisterOption) error
+	Deregister(*Service, ...DeregisterOption) error
+	GetService(string, ...GetOption) ([]*Service, error)
+	ListServices(...ListOption) ([]*Service, error)
+	Watch(...WatchOption) (Watcher, error)
+	String() string
+}
+
+type Service struct {
+	Name      string            `json:"name"`
+	Version   string            `json:"version"`
+	Metadata  map[string]string `json:"metadata"`
+	Endpoints []*Endpoint       `json:"endpoints"`
+	Nodes     []*Node           `json:"nodes"`
+}
+
+type Node struct {
+	Metadata map[string]string `json:"metadata"`
+	Id       string            `json:"id"`
+	Address  string            `json:"address"`
+}
+
+type Endpoint struct {
+	Request  *Value            `json:"request"`
+	Response *Value            `json:"response"`
+	Metadata map[string]string `json:"metadata"`
+	Name     string            `json:"name"`
+}
+
+type Value struct {
+	Name   string   `json:"name"`
+	Type   string   `json:"type"`
+	Values []*Value `json:"values"`
+}
+
+type Option func(*Options)
+
+type RegisterOption func(*RegisterOptions)
+
+type WatchOption func(*WatchOptions)
+
+type DeregisterOption func(*DeregisterOptions)
+
+type GetOption func(*GetOptions)
+
+type ListOption func(*ListOptions)
+
+// Register a service node. Additionally supply options such as TTL.
+func Register(s *Service, opts ...RegisterOption) error {
+	return DefaultRegistry.Register(s, opts...)
+}
+
+// Deregister a service node.
+func Deregister(s *Service) error {
+	return DefaultRegistry.Deregister(s)
+}
+
+// Retrieve a service. A slice is returned since we separate Name/Version.
+func GetService(name string) ([]*Service, error) {
+	return DefaultRegistry.GetService(name)
+}
+
+// List the services. Only returns service names.
+func ListServices() ([]*Service, error) {
+	return DefaultRegistry.ListServices()
+}
+
+// Watch returns a watcher which allows you to track updates to the registry.
+func Watch(opts ...WatchOption) (Watcher, error) {
+	return DefaultRegistry.Watch(opts...)
+}
+
+func String() string {
+	return DefaultRegistry.String()
+}
+
+var (
+	DefaultRegistry = NewMDNSRegistry()
+)

registry/watcher.go

@@ -0,0 +1,56 @@
+package registry
+
+import "time"
+
+// Watcher is an interface that returns updates
+// about services within the registry.
+type Watcher interface {
+	// Next is a blocking call
+	Next() (*Result, error)
+	Stop()
+}
+
+// Result is returned by a call to Next on
+// the watcher. Actions can be create, update, delete.
+type Result struct {
+	Service *Service
+	Action  string
+}
+
+// EventType defines registry event type.
+type EventType int
+
+const (
+	// Create is emitted when a new service is registered.
+	Create EventType = iota
+	// Delete is emitted when an existing service is deregsitered.
+	Delete
+	// Update is emitted when an existing servicec is updated.
+	Update
+)
+
+// String returns human readable event type.
+func (t EventType) String() string {
+	switch t {
+	case Create:
+		return "create"
+	case Delete:
+		return "delete"
+	case Update:
+		return "update"
+	default:
+		return "unknown"
+	}
+}
+
+// Event is registry event.
+type Event struct {
+	// Timestamp is event timestamp
+	Timestamp time.Time
+	// Service is registry service
+	Service *Service
+	// Id is registry id
+	Id string
+	// Type defines type of event
+	Type EventType
+}