discovery

Forge Discovery: service registration and discovery for Go microservices

Forge Discovery is the service discovery extension for Forge, the Go backend framework. When your app starts it registers itself in a service registry (Consul, etcd, mDNS/Bonjour, an HTTP seed list or an in-memory registry), keeps its health status up to date, and deregisters on shutdown. You get a Service in the container for finding other services by name or tag, with round-robin or random load balancing, and an optional FARP manifest that tells an API gateway about your routes and OpenAPI or AsyncAPI schemas.

Documentation · Quick start · Features · Backends · Finding services · FARP · Configuration · FAQ

Quick start

You need Go 1.26 or later. Add Forge and the extension to your module:

go get github.com/xraph/forge@latest
go get github.com/xraph/forge/extensions/discovery@latest

Save this as main.go. It registers an orders service in the in-memory registry and adds a route that looks services up:

package main

import (
	"log"
	"net/http"

	"github.com/xraph/forge"
	"github.com/xraph/forge/extensions/discovery"
)

func main() {
	app := forge.NewApp(forge.AppConfig{
		Name:        "orders",
		Version:     "1.0.0",
		HTTPAddress: ":8080",
		Extensions: []forge.Extension{
			discovery.NewExtension(
				discovery.WithBackend("memory"),
				discovery.WithServiceName("orders"),
				discovery.WithServiceID("orders-1"),
				discovery.WithServiceTags("api", "v1"),
			),
		},
	})

	err := app.Router().GET("/instances/:service", func(ctx forge.Context) error {
		svc, err := forge.Inject[*discovery.Service](app.Container())
		if err != nil {
			return err
		}

		instances, err := svc.Discover(ctx.Context(), ctx.Param("service"))
		if err != nil {
			return err
		}

		return ctx.JSON(http.StatusOK, instances)
	})
	if err != nil {
		log.Fatal(err)
	}

	if err := app.Run(); err != nil {
		log.Fatal(err)
	}
}

Run it with go mod tidy && go run ., then ask for the instance you just registered:

curl http://localhost:8080/instances/orders
# [{"id":"orders-1","name":"orders","version":"1.0.0","address":"my-host.local",
#   "port":8080,"tags":["api","v1"],"metadata":{},"status":"passing","last_heartbeat":...}]

The memory registry lives inside one process. Use it for development and tests. Swap WithBackend("memory") for WithConsul("127.0.0.1:8500", token) or another backend from the table below and the rest of the code stays the same.

Always give each replica a stable instance ID, with WithServiceID or the FORGE_INSTANCE_ID environment variable. Without one, the extension makes up a new ID (<name>-<unix nanoseconds>) each time it builds the instance, and the health check loop, which re-registers every health_check.interval, adds a fresh entry to the registry on every tick. Shutdown then deregisters an ID that was never registered.

Features

Backends

The Consul backend attaches a 30-second TTL check to the registration, which the health loop keeps passing, and tells Consul to drop the instance after a minute in a critical state. The mDNS backend has its own options for multi-service browsing (WithMDNSServiceTypes), the watch interval, the browse timeout, TTL, network interface and IPv6.

Find other services

The service is in the container as *discovery.Service, also under the names discovery and discovery.Service:

svc, err := forge.Inject[*discovery.Service](app.Container())
if err != nil {
	return err
}

// Every instance, or only those with all of these tags.
all, err := svc.Discover(ctx, "payments")
v2, err := svc.DiscoverWithTags(ctx, "payments", []string{"v2"})

// Only instances whose status is passing.
healthy, err := svc.DiscoverHealthy(ctx, "payments")

// One healthy instance, picked round-robin, as a base URL.
url, err := svc.GetServiceURL(ctx, "payments", "http", discovery.LoadBalanceRoundRobin)

If you want the instance and not a URL, call SelectInstance. Two strategies work: LoadBalanceRoundRobin and LoadBalanceRandom. You'll also see LoadBalanceLeastConnections and LoadBalanceWeightedRoundRobin in the package, but they fall back to round-robin today.

To react when the instances of a service change, either pass a callback when you build the extension:

discovery.NewExtension(
	discovery.WithBackend("consul"),
	discovery.WithWatch([]string{"payments"}, func(instances []*discovery.ServiceInstance) {
		log.Printf("payments now has %d instances", len(instances))
	}),
)

or call svc.Watch(ctx, "payments", onChange) yourself. Each ServiceInstance has URL(scheme), HasTag, HasAllTags, IsHealthy and GetMetadata helpers.

Where the address comes from

You can set service.address and service.port directly. When you don't, the extension works it out:

A wildcard listen address such as 0.0.0.0 or :: is never advertised. In a Kubernetes pod, expose POD_IP through the downward API and you get the pod's IP.

Publish routes to a gateway with FARP

FARP is the Forge API gateway registration protocol, implemented in xraph/farp. Turn it on and the extension adds four routes to your app:

The manifest is built after every extension has started (in a PhaseAfterStart hook), so it sees all of your routes, including the ones other extensions add during their own start. Until then the first three answer 503. With gateway_url set, the extension also posts its registration to <gateway_url>/_farp/v1/register once the HTTP server is listening, retries with backoff until that works, and calls /_farp/v1/deregister/<name> on shutdown.

discovery.NewExtension(
	discovery.WithBackend("mdns"),
	discovery.WithServiceName("users"),
	discovery.WithServiceID("users-1"),
	discovery.WithFARPEnabled(true),
	discovery.WithFARPGatewayURL("http://localhost:7903"),
	discovery.WithFARPPathRules(
		farp.PathRule{Pattern: "/internal/**", Action: farp.PathRuleExclude},
	),
)

Internal paths (/_/*, /_farp/* and similar) are left out of the published schemas unless you call WithFARPExcludeInternalPaths(false). Path rules are checked in order and the first match wins. When farp.schemas is empty and farp.auto_register is on (the default), the extension publishes whichever of the OpenAPI and AsyncAPI specs your app has turned on.

Configuration

The extension reads extensions.discovery from your config, falling back to discovery. Options you pass in code are applied on top of the file. Here's a Consul setup:

extensions:
  discovery:
    enabled: true
    backend: consul
    service:
      name: orders
      id: orders-1
      version: 1.0.0
      port: 8080
      tags: [api, v1]
      metadata:
        team: checkout
      enable_auto_deregister: true
    health_check:
      enabled: true
      interval: 10s
      timeout: 5s
    watch:
      enabled: true
      services: [payments]
    consul:
      address: 127.0.0.1:8500
      token: ""
      datacenter: dc1

The common settings have With... options in config.go: WithServiceName, WithServiceID, WithServiceAddress, WithServiceTags, WithServiceMetadata, WithHealthCheck, WithWatch, WithConsul, WithEtcd, WithKubernetes, WithMDNS, WithHTTPSeeds, the WithFARP... family and more. WithConfig replaces the whole config.

A few keys are read but have no effect yet: health_check.http, health_check.tcp, health_check.grpc and health_check.deregister_critical_service_after (the loop always uses your app's health checks, and Consul's deregistration delay is fixed at one minute), watch.tags, and farp.strategy.

Documentation

FAQ

How do I register a Go service with Consul?

Add discovery.NewExtension(discovery.WithConsul("127.0.0.1:8500", token), discovery.WithServiceID("orders-1")) to your Forge app. It registers on start with the app's name and HTTP port, reports health every ten seconds and deregisters on shutdown.

Can Go services find each other without Consul or etcd?

Yes. On one machine or a local network, use the mdns backend, which needs no server. Across hosts without a registry, use the http backend with a list of seed URLs that run the extension with FARP on.

Does Forge Discovery do client-side load balancing?

It does simple client-side picks. SelectInstance and GetServiceURL choose a healthy instance round-robin or at random. Connection counting and weights aren't implemented.

Why does my service show up many times in the registry?

You haven't set an instance ID. Set WithServiceID, service.id or FORGE_INSTANCE_ID, and the health loop updates one entry.

Contributing

The extension is its own Go module inside the Forge repository. Test it from its directory:

cd extensions/discovery
GOWORK=off go test -race ./...
GOWORK=off golangci-lint run ./...

AGENTS.md has the full build, lint and release rules for the repository, and CONTRIBUTING.md has the contribution guidelines.

License

Forge Discovery is part of Forge and is available under the Apache License 2.0.