gateway

Documentation

Overview

Package gateway provides a REFERENCE IMPLEMENTATION for API gateway integration with FARP.

⚠️ IMPORTANT: This is NOT production-ready code. It serves as an example/helper to demonstrate how gateways should integrate with FARP.

What This Package Provides

- Example of how to watch for manifest changes - Example of how to convert schemas to routes - Example of how to cache schemas - Integration with the merger package

What This Package Does NOT Provide

- Complete HTTP client (HTTP schema fetch implemented) - Production-ready error handling - Gateway-specific route application - Health monitoring - Load balancing logic - Retry logic with exponential backoff - Circuit breaker patterns

For Production Gateways

Real gateway implementations (Kong, Traefik, Envoy, custom) should:

1. Implement their own HTTP client to fetch schemas 2. Implement their own service discovery watchers (Consul, etcd, K8s, mDNS) 3. Implement gateway-specific route configuration 4. Add production-ready error handling and observability 5. Use this package as a reference/inspiration, not a dependency

See docs/IMPLEMENTATION_RESPONSIBILITIES.md for complete guidance.

Index

• type Client
  • func NewClient(registry farp.SchemaRegistry, opts ...ClientOption) *Client
  • func NewClientWithConfig(registry farp.SchemaRegistry, mergerConfig merger.MergerConfig, ...) *Client
  • func (c *Client) ClearCache()
  • func (c *Client) ConvertToRoutes(manifests []*farp.SchemaManifest) []ServiceRoute
  • func (c *Client) GenerateMergedOpenAPI(ctx context.Context, serviceName string) (*merger.MergeResult, error)
  • func (c *Client) GenerateMergedSchemas(ctx context.Context, serviceName string) (*merger.MultiProtocolResult, error)
  • func (c *Client) GetManifest(instanceID string) (*farp.SchemaManifest, bool)
  • func (c *Client) GetMergedOpenAPIJSON(ctx context.Context, serviceName string) ([]byte, error)
  • func (c *Client) WatchServices(ctx context.Context, serviceName string, onChange func([]ServiceRoute)) error
• type ClientOption
  • func WithHTTPClient(httpClient *http.Client) ClientOption
• type ServiceRoute

Types

type Client

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

Client is a reference implementation for API gateway integration. It demonstrates how to watch for service schema changes and provides conversion utilities.

For production use, gateways should implement their own logic tailored to their specific architecture, error handling, and performance requirements.

func NewClient

func NewClient(registry farp.SchemaRegistry, opts ...ClientOption) *Client

NewClient creates a new gateway client with default merger config. Options can be provided to customize the client behavior.

Example:

client := gateway.NewClient(registry, gateway.WithHTTPClient(customHTTPClient))

func NewClientWithConfig

func NewClientWithConfig(registry farp.SchemaRegistry, mergerConfig merger.MergerConfig, opts ...ClientOption) *Client

NewClientWithConfig creates a new gateway client with custom merger config. Options can be provided to customize the client behavior.

Example:

config := merger.DefaultMergerConfig()
config.Timeout = 60 * time.Second
client := gateway.NewClientWithConfig(registry, config, gateway.WithHTTPClient(customHTTPClient))

func (*Client) ClearCache

func (c *Client) ClearCache()

ClearCache clears the schema cache.

func (*Client) ConvertToRoutes

func (c *Client) ConvertToRoutes(manifests []*farp.SchemaManifest) []ServiceRoute

ConvertToRoutes converts service manifests to gateway routes This is a reference implementation - actual gateways should customize this.

func (*Client) GenerateMergedOpenAPI

func (c *Client) GenerateMergedOpenAPI(ctx context.Context, serviceName string) (*merger.MergeResult, error)

Deprecated: Use GenerateMergedSchemas for multi-protocol support.

func (*Client) GenerateMergedSchemas

func (c *Client) GenerateMergedSchemas(ctx context.Context, serviceName string) (*merger.MultiProtocolResult, error)

GenerateMergedSchemas generates unified specs for all protocol types from registered services.

func (*Client) GetManifest

func (c *Client) GetManifest(instanceID string) (*farp.SchemaManifest, bool)

GetManifest retrieves a cached manifest by instance ID.

func (*Client) GetMergedOpenAPIJSON

func (c *Client) GetMergedOpenAPIJSON(ctx context.Context, serviceName string) ([]byte, error)

GetMergedOpenAPIJSON returns the merged OpenAPI spec as JSON.

func (*Client) WatchServices

func (c *Client) WatchServices(ctx context.Context, serviceName string, onChange func([]ServiceRoute)) error

WatchServices watches for service registrations and schema updates onChange is called whenever services are added, updated, or removed.

type ClientOption

type ClientOption func(*Client)

ClientOption configures a Client.

func WithHTTPClient

func WithHTTPClient(httpClient *http.Client) ClientOption

WithHTTPClient sets a custom HTTP client for schema fetching. This is useful when you need custom authentication, TLS configuration, or other HTTP client settings.

Example:

client := http.Client{
	Timeout: 60 * time.Second,
	Transport: &http.Transport{
		TLSClientConfig: &tls.Config{InsecureSkipVerify: true},
	},
}
gatewayClient := gateway.NewClient(registry, gateway.WithHTTPClient(&client))

type ServiceRoute

type ServiceRoute struct {
	// Path is the route path pattern
	Path string

	// Methods are HTTP methods for this route (e.g., ["GET", "POST"])
	Methods []string

	// TargetURL is the backend service URL
	TargetURL string

	// HealthURL is the health check URL
	HealthURL string

	// Middleware are middleware names to apply
	Middleware []string

	// Metadata contains additional route information
	Metadata map[string]any

	// ServiceName is the name of the backend service
	ServiceName string

	// ServiceVersion is the version of the backend service
	ServiceVersion string
}

ServiceRoute represents a route configuration for the gateway.