---
title: Functions
description: Public API reference for the Discovery extension
---

## Extension Entry Points

| Function | Description |
|---|---|
| `NewExtension(opts ...ConfigOption) forge.Extension` | Create the discovery extension with functional options |
| `NewExtensionWithConfig(config Config) forge.Extension` | Create the extension with a complete config |
| `DefaultConfig() Config` | Returns the default configuration |

## DI Helpers

| Function | Description |
|---|---|
| `GetService(c forge.Container) (*Service, error)` | Resolve the discovery service from the container |
| `MustGetService(c forge.Container) *Service` | Same but panics on error |
| `GetServiceFromApp(app forge.App) (*Service, error)` | Resolve from an app instance |
| `MustGetServiceFromApp(app forge.App) *Service` | Same but panics on error |

## Service -- Registration

| Method | Description |
|---|---|
| `Register(ctx, instance) error` | Register a service instance |
| `Deregister(ctx, instance) error` | Remove a service instance |

## Service -- Discovery

| Method | Description |
|---|---|
| `Discover(ctx, serviceName) ([]*ServiceInstance, error)` | Find all instances of a service |
| `DiscoverWithTags(ctx, serviceName, tags) ([]*ServiceInstance, error)` | Find instances matching tags |
| `DiscoverHealthy(ctx, serviceName) ([]*ServiceInstance, error)` | Find only healthy instances |
| `SelectInstance(ctx, serviceName) (*ServiceInstance, error)` | Pick one instance (load balanced) |
| `GetServiceURL(ctx, serviceName) (string, error)` | Get the URL of a healthy instance |
| `ListServices(ctx) ([]string, error)` | List all registered service names |

## Service -- Watching

| Method | Description |
|---|---|
| `Watch(ctx, serviceName, callback) error` | Subscribe to service change events |

## Service -- Backend Access

| Method | Description |
|---|---|
| `Backend() Backend` | Access the underlying backend directly |
| `Health(ctx) error` | Check discovery service health |

## FARP Config Options

| Function | Description |
|---|---|
| `WithFARP(cfg FARPConfig) ConfigOption` | Set the full FARP configuration |
| `WithFARPEnabled(bool) ConfigOption` | Enable or disable FARP schema registration |
| `WithFARPAutoRegister(bool) ConfigOption` | Auto-register schemas on startup |
| `WithFARPStrategy(string) ConfigOption` | Set strategy: `push`, `pull`, or `hybrid` |
| `WithFARPSchemas(schemas ...FARPSchemaConfig) ConfigOption` | Set schema configurations |
| `WithFARPEndpoints(FARPEndpointsConfig) ConfigOption` | Set endpoint configuration |
| `WithFARPCapabilities(caps ...string) ConfigOption` | Set advertised capabilities |

## mDNS Config Options

| Function | Description |
|---|---|
| `WithMDNS(domain string) ConfigOption` | Set backend to mDNS with optional domain |
| `WithMDNSServiceType(string) ConfigOption` | Set the mDNS service type for registration |
| `WithMDNSServiceTypes(types ...string) ConfigOption` | Set service types to browse for discovery |
| `WithMDNSBrowseTimeout(time.Duration) ConfigOption` | Set browse operation timeout |
| `WithMDNSTTL(uint32) ConfigOption` | Set DNS record TTL |
| `WithMDNSWatchInterval(time.Duration) ConfigOption` | Set watch polling interval |
| `WithMDNSInterface(string) ConfigOption` | Bind to a specific network interface |
| `WithMDNSIPv6(bool) ConfigOption` | Enable IPv6 support |

## Service Identity Options

| Function | Description |
|---|---|
| `WithServiceID(string) ConfigOption` | Set the unique service instance identifier |
| `WithServiceVersion(string) ConfigOption` | Set the service version string |
| `WithAutoDeregister(bool) ConfigOption` | Auto-deregister on shutdown |

## FARP Endpoints

When FARP is enabled, the following HTTP endpoints are registered:

| Endpoint | Description |
|---|---|
| `GET /_farp/manifest` | FARP manifest describing the service's API schemas |
| `GET /_farp/discovery` | Discovery information for other services |