discovery

type DiscoveryEvent struct {
	Type      farp.EventType  `json:"type"`
	Instance  ServiceInstance `json:"instance"`
	Timestamp time.Time       `json:"timestamp"`

	// Manifest is populated when available (e.g., push mode includes it directly).
	// For registry-based discovery, this may be nil and the gateway fetches it separately.
	Manifest *farp.SchemaManifest `json:"manifest,omitempty"`
}

type DiscoveryEventHandler func(event DiscoveryEvent)

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

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

type GatewayNodeConfig struct {
	// Discovery mode (use one or both):
	// Option A: Registry-based — watch external backend for services
	Discovery ServiceDiscovery
	// Option B: Push-based — accept manifest pushes from services
	EnablePush bool

	// Optional: SchemaRegistry for storing discovered manifests.
	// If nil, uses an in-memory registry internally.
	Registry farp.SchemaRegistry

	// Route change callback — called when routes change.
	// Use this for simple integrations.
	OnRoutesChanged func(routes []gateway.ServiceRoute)

	// OnServiceEvent is called when a service discovery event occurs
	// (add, update, remove). Called before manifest processing, so the
	// gateway can track service lifecycle independently of routes.
	OnServiceEvent func(event DiscoveryEvent)

	// Or use atomic swap handler for zero-downtime route updates.
	RouteHandler farp.RouteUpdateHandler

	// Which services to watch (empty = all services)
	ServiceNames []string

	// HTTP client for fetching manifests from services (registry mode)
	HTTPClient *http.Client

	// ManifestFetcher for custom manifest fetching logic.
	// If nil, uses HTTPManifestFetcher (GET /_farp/manifest).
	Fetcher ManifestFetcher

	// How often to poll for health (for backends that don't push health)
	HealthPollInterval time.Duration // default: 15s

	// Push mode: how long before an instance with no heartbeat is removed
	HeartbeatTimeout time.Duration // default: 30s
}

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

type ListableDiscovery interface {
	// ListServices returns all known service names.
	ListServices(ctx context.Context) ([]string, error)
}

type ManifestFetcher interface {
	// FetchManifest fetches the SchemaManifest from a service instance.
	FetchManifest(ctx context.Context, instance ServiceInstance) (*farp.SchemaManifest, error)
}

type NamedDiscovery interface {
	// Name returns the backend name (e.g., "consul", "etcd", "mdns").
	Name() string

	// Initialize performs any deferred initialization.
	Initialize(ctx context.Context) error
}

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

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

type PushHeartbeat struct {
	Status         farp.InstanceStatus `json:"status"`
	RoutesChecksum string              `json:"routes_checksum,omitempty"`
}

type PushHeartbeatResponse struct {
	Status         string `json:"status"`
	RoutesChecksum string `json:"routes_checksum"`
	SchemasApplied int    `json:"schemas_applied"`
}

type PushRegistration struct {
	Instance ServiceInstance      `json:"instance"`
	Manifest *farp.SchemaManifest `json:"manifest"`
}

type PushRegistrationResponse struct {
	Status         string `json:"status"`
	RoutesChecksum string `json:"routes_checksum"`
	SchemasApplied int    `json:"schemas_applied"`
}

type ServiceDiscovery interface {
	// Discover returns all known instances of a service.
	// If serviceName is empty, returns all instances across all services.
	Discover(ctx context.Context, serviceName string) ([]ServiceInstance, error)

	// Watch watches for changes to instances of a service.
	// The handler is called when instances are added, removed, or change health status.
	// If serviceName is empty, watches all services.
	// The watch runs until the context is cancelled.
	Watch(ctx context.Context, serviceName string, handler DiscoveryEventHandler) error

	// Register registers a service instance in the discovery backend.
	Register(ctx context.Context, instance ServiceInstance) error

	// Deregister removes a service instance from the discovery backend.
	Deregister(ctx context.Context, instanceID string) error

	// ReportHealth reports the health status of a registered instance.
	ReportHealth(ctx context.Context, instanceID string, status farp.InstanceStatus) error

	// Close closes the discovery backend connection and releases resources.
	Close() error

	// Health returns nil if the discovery backend itself is reachable.
	Health(ctx context.Context) error
}

type ServiceInstance struct {
	// Unique ID for this instance (maps to SchemaManifest.InstanceID)
	ID string `json:"id"`

	// Service name (maps to SchemaManifest.ServiceName)
	ServiceName string `json:"service_name"`

	// Service version (maps to SchemaManifest.ServiceVersion)
	Version string `json:"version,omitempty"`

	// Network address (host or host:port)
	Address string `json:"address"`

	// Port number
	Port int `json:"port"`

	// Health status
	Status farp.InstanceStatus `json:"status"`

	// Tags for filtering and labeling
	Tags []string `json:"tags,omitempty"`

	// Metadata tags (key-value pairs for filtering, labeling)
	Metadata map[string]string `json:"metadata,omitempty"`

	// When this instance was registered
	RegisteredAt time.Time `json:"registered_at"`

	// When health was last reported
	LastHealthCheck time.Time `json:"last_health_check"`
}

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

type ServiceNodeConfig struct {
	// Required: Service identity
	ServiceName    string
	ServiceVersion string
	InstanceID     string // auto-generated UUID if empty
	Address        string // host:port this service listens on

	// Discovery mode (use one):
	// Option A: Registry-based — register in external backend
	Discovery ServiceDiscovery
	// Option B: Push-based — push manifest directly to gateway
	GatewayURL string // e.g., "http://gateway:9090/_farp/v1"

	// Optional: SchemaRegistry for publishing manifest to KV store
	Registry farp.SchemaRegistry

	// Optional: Schema providers for auto-generating schemas
	Providers []farp.SchemaProvider

	// Health/TTL configuration
	HealthInterval time.Duration // default: 10s
	TTL            time.Duration // default: 30s
	MaxRetries     int           // default: 5
	RetryBackoff   time.Duration // default: 2s

	// Tags for service instance filtering/labeling
	Tags []string

	// Metadata is additional key-value metadata to include on the registered
	// ServiceInstance. These are merged with the auto-generated FARP metadata
	// keys (farp.enabled, farp.openapi, etc.) — user-provided keys take precedence.
	Metadata map[string]string

	// Endpoints configures the service's introspection endpoints.
	// These flow into the manifest and are also advertised as farp.* metadata
	// keys on the registered ServiceInstance (e.g., farp.openapi, farp.health).
	Endpoints farp.SchemaEndpoints

	// Routing configuration (flows into manifest)
	MountStrategy farp.MountStrategy
	BasePath      string
	PathRules     []farp.PathRule

	// Routes provides route information for OpenAPI schema generation.
	// Can be []farp.RouteDescriptor, map[string]any (OpenAPI paths), or any
	// type that the configured schema provider understands.
	// If nil, the provider's Generate() may fail or produce empty paths.
	Routes any

	// Service hints (flows into manifest)
	Hints *farp.ServiceHints

	// HTTP client for push mode (optional, uses default if nil)
	HTTPClient *http.Client
}

type TagDiscovery interface {
	// DiscoverWithTags returns instances matching all given tags.
	DiscoverWithTags(ctx context.Context, serviceName string, tags []string) ([]ServiceInstance, error)
}