farp

package
v0.6.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Nov 19, 2025 License: Apache-2.0 Imports: 1 Imported by: 0

README

FARP - Forge API Gateway Registration Protocol

Version: 1.0.0
Status: Draft Specification
Authors: Forge Core Team
Last Updated: 2025-11-01

Overview

FARP (Forge API Gateway Registration Protocol) is a protocol specification for enabling service instances to automatically register their API schemas, health information, and capabilities with API gateways and service meshes. It provides a standardized way for services to expose their contracts (OpenAPI, AsyncAPI, gRPC, GraphQL) and enable dynamic route configuration in API gateways.

Key Features

  • Schema-Aware Service Discovery: Services register with complete API contracts
  • Multi-Protocol Support: OpenAPI, AsyncAPI, gRPC, GraphQL, oRPC, Thrift, Avro, and extensible for future protocols
  • Production-Ready Providers: Built-in schema providers for all major API protocols including RPC and data serialization
  • Dynamic Gateway Configuration: API gateways auto-configure routes based on registered schemas
  • Health & Telemetry Integration: Built-in health checks and metrics endpoints
  • Backend Agnostic: Works with Consul, etcd, Kubernetes, mDNS/Bonjour, Eureka, and custom backends
  • Transport Agnostic: Schema metadata propagates through KV stores, DNS TXT records, ConfigMaps, and more
  • Push & Pull Models: Flexible schema distribution strategies
  • Zero-Downtime Updates: Schema versioning and checksum validation
  • Zero Configuration: Works with mDNS/Bonjour for local network discovery without infrastructure

Repository Structure

farp/
├── README.md                    # This file - project overview
├── PROVIDERS_IMPLEMENTATION.md  # Schema providers implementation guide
├── docs/
│   ├── SPECIFICATION.md         # Complete protocol specification
│   ├── ARCHITECTURE.md          # Architecture and design decisions
│   ├── IMPLEMENTATION_GUIDE.md  # Guide for implementers
│   └── GATEWAY_INTEGRATION.md   # Gateway integration guide
├── providers/                   # Schema provider implementations
│   ├── openapi/                 # OpenAPI 3.x provider
│   ├── asyncapi/                # AsyncAPI 2.x/3.x provider
│   ├── grpc/                    # gRPC FileDescriptorSet provider
│   ├── graphql/                 # GraphQL SDL/introspection provider
│   ├── orpc/                    # oRPC (OpenAPI-based RPC) provider
│   ├── thrift/                  # Apache Thrift IDL provider
│   └── avro/                    # Apache Avro schema provider
├── examples/
│   ├── basic/                   # Basic usage examples
│   ├── multi-protocol/          # Multi-protocol service example
│   └── gateway-client/          # Reference gateway client
├── types.go                     # Core protocol types
├── manifest.go                  # Schema manifest types
├── provider.go                  # Schema provider interface
├── registry.go                  # Schema registry interface
├── storage.go                   # Storage abstraction
└── version.go                   # Protocol version constants

Quick Start

Using Schema Providers
import (
    "github.com/xraph/forge/farp/providers/openapi"
    "github.com/xraph/forge/farp/providers/grpc"
    "github.com/xraph/forge/farp/providers/graphql"
    "github.com/xraph/forge/farp/providers/orpc"
    "github.com/xraph/forge/farp/providers/thrift"
    "github.com/xraph/forge/farp/providers/avro"
)

// OpenAPI provider
openapiProvider := openapi.NewProvider("3.1.0", "/openapi.json")
schema, err := openapiProvider.Generate(ctx, app)

// gRPC provider (with reflection)
grpcProvider := grpc.NewProvider("proto3", nil)
schema, err = grpcProvider.Generate(ctx, app)

// GraphQL provider (SDL format)
graphqlProvider := graphql.NewProvider("2021", "/graphql")
graphqlProvider.UseSDL()
schema, err = graphqlProvider.Generate(ctx, app)

// oRPC provider
orpcProvider := orpc.NewProvider("1.0.0", "/orpc.json")
schema, err = orpcProvider.Generate(ctx, app)

// Thrift provider (from IDL files)
thriftProvider := thrift.NewProvider("0.19.0", []string{"user.thrift"})
schema, err = thriftProvider.Generate(ctx, app)

// Avro provider (from schema files)
avroProvider := avro.NewProvider("1.11.1", []string{"user.avsc"})
schema, err = avroProvider.Generate(ctx, app)
Service Registration
import "github.com/xraph/forge/farp"

// Create schema manifest
manifest := &farp.SchemaManifest{
    Version:        farp.ProtocolVersion,
    ServiceName:    "user-service",
    ServiceVersion: "v1.2.3",
    InstanceID:     "user-service-abc123",
    Schemas: []farp.SchemaDescriptor{
        {
            Type:        farp.SchemaTypeOpenAPI,
            SpecVersion: "3.1.0",
            Location: farp.SchemaLocation{
                Type: farp.LocationTypeHTTP,
                URL:  "http://user-service:8080/openapi.json",
            },
        },
        {
            Type:        farp.SchemaTypeGRPC,
            SpecVersion: "proto3",
            Location: farp.SchemaLocation{
                Type: farp.LocationTypeInline,
            },
        },
        {
            Type:        farp.SchemaTypeGraphQL,
            SpecVersion: "2021",
            Location: farp.SchemaLocation{
                Type: farp.LocationTypeHTTP,
                URL:  "http://user-service:8080/graphql",
            },
        },
    },
    Capabilities: []string{"rest", "grpc", "graphql", "websocket"},
    Endpoints: farp.SchemaEndpoints{
        Health:         "/health",
        Metrics:        "/metrics",
        OpenAPI:        "/openapi.json",
        GraphQL:        "/graphql",
        GRPCReflection: true,
    },
}

// Register with backend
registry.RegisterManifest(ctx, manifest)
Gateway Integration
import "github.com/xraph/forge/farp/gateway"

// Create gateway client
client := gateway.NewClient(backend)

// Watch for service schema changes
client.WatchServices(ctx, func(routes []gateway.ServiceRoute) {
    // Auto-configure gateway routes
    for _, route := range routes {
        gateway.AddRoute(route)
    }
})

Use Cases

  1. API Gateway Auto-Configuration: Gateways like Kong, Traefik, or Nginx automatically register routes based on service schemas
  2. Service Mesh Control Plane: Enable contract-aware routing and validation in service meshes
  3. Developer Portals: Auto-generate API documentation from registered schemas
  4. Multi-Protocol Systems: Unified discovery for REST, gRPC, GraphQL, and async protocols
  5. Contract Testing: Validate service contracts at deployment time
  6. Schema Versioning: Support multiple API versions with zero-downtime migrations

Protocol Status

  • ✅ Core protocol specification complete
  • ✅ Type definitions
  • ✅ Schema providers (OpenAPI, AsyncAPI, gRPC, GraphQL, oRPC, Thrift, Avro)
  • ✅ Discovery extension integration
  • ✅ mDNS/Bonjour backend support
  • 🚧 Gateway client library (in progress)
  • ⏳ Community feedback and refinement

Supported Schema Types

Protocol Status Provider Spec Version Content Type
OpenAPI ✅ Complete providers/openapi 3.1.0 (default) application/json
AsyncAPI ✅ Complete providers/asyncapi 3.0.0 (default) application/json
gRPC ✅ Complete providers/grpc proto3 (default) application/json
GraphQL ✅ Complete providers/graphql 2021 (default) application/graphql or application/json
oRPC ✅ Complete providers/orpc 1.0.0 application/json
Thrift ✅ Complete providers/thrift 0.19.0 (default) application/json
Avro ✅ Complete providers/avro 1.11.1 (default) application/json

See PROVIDERS_IMPLEMENTATION.md for detailed provider documentation.

Documentation

Contributing

FARP is part of the Forge framework. Contributions are welcome! Please see the main Forge repository for contribution guidelines.

License

Apache License 2.0 - See LICENSE file in the Forge repository

Documentation

Overview

Package farp provides Forge-specific integrations for the FARP protocol.

This package wraps and extends github.com/xraph/farp with Forge-specific functionality, particularly for schema generation from Forge routers.

DEPRECATED: This internal package is being phased out in favor of the external github.com/xraph/farp package. New code should import the external package directly. This package is maintained only for Forge-specific integrations (providers/openapi and providers/asyncapi).

Migration Guide

Old import: 

import "github.com/xraph/forge/farp"

New import: 

import "github.com/xraph/farp"

The providers remain in this package for Forge-specific integration: 

import "github.com/xraph/forge/farp/providers/openapi"
import "github.com/xraph/forge/farp/providers/asyncapi"

For full FARP documentation, see: https://github.com/xraph/farp

Index

Constants

View Source 
const (
	SchemaTypeOpenAPI  = farp.SchemaTypeOpenAPI
	SchemaTypeAsyncAPI = farp.SchemaTypeAsyncAPI
	SchemaTypeGRPC     = farp.SchemaTypeGRPC
	SchemaTypeGraphQL  = farp.SchemaTypeGraphQL
	SchemaTypeORPC     = farp.SchemaTypeORPC
	SchemaTypeThrift   = farp.SchemaTypeThrift
	SchemaTypeAvro     = farp.SchemaTypeAvro
	SchemaTypeCustom   = farp.SchemaTypeCustom

	LocationTypeHTTP     = farp.LocationTypeHTTP
	LocationTypeRegistry = farp.LocationTypeRegistry
	LocationTypeInline   = farp.LocationTypeInline

	CapabilityREST      = farp.CapabilityREST
	CapabilityGRPC      = farp.CapabilityGRPC
	CapabilityWebSocket = farp.CapabilityWebSocket
	CapabilitySSE       = farp.CapabilitySSE
	CapabilityGraphQL   = farp.CapabilityGraphQL
	CapabilityMQTT      = farp.CapabilityMQTT
	CapabilityAMQP      = farp.CapabilityAMQP

	EventTypeAdded   = farp.EventTypeAdded
	EventTypeUpdated = farp.EventTypeUpdated
	EventTypeRemoved = farp.EventTypeRemoved

	ProtocolVersion = farp.ProtocolVersion
)

Constant re-exports

Variables

View Source 
var (
	ErrInvalidManifest     = farp.ErrInvalidManifest
	ErrInvalidSchema       = farp.ErrInvalidSchema
	ErrInvalidLocation     = farp.ErrInvalidLocation
	ErrUnsupportedType     = farp.ErrUnsupportedType
	ErrChecksumMismatch    = farp.ErrChecksumMismatch
	ErrIncompatibleVersion = farp.ErrIncompatibleVersion
	ErrManifestNotFound    = farp.ErrManifestNotFound
	ErrSchemaNotFound      = farp.ErrSchemaNotFound
)

Error re-exports

View Source 
var (
	NewManifest               = farp.NewManifest
	CalculateManifestChecksum = farp.CalculateManifestChecksum
	CalculateSchemaChecksum   = farp.CalculateSchemaChecksum
	FromJSON                  = farp.FromJSON
	ValidateSchemaDescriptor  = farp.ValidateSchemaDescriptor
	DiffManifests             = farp.DiffManifests
	IsCompatible              = farp.IsCompatible
	DefaultRegistryConfig     = farp.DefaultRegistryConfig
)

Function re-exports

Functions

This section is empty.

Types

type Application 

type Application = farp.Application

Type re-exports

type Capability 

type Capability = farp.Capability

Type re-exports

type EventType 

type EventType = farp.EventType

Type re-exports

type LocationType 

type LocationType = farp.LocationType

Type re-exports

type ManifestEvent 

type ManifestEvent = farp.ManifestEvent

Type re-exports

type RegistryConfig 

type RegistryConfig = farp.RegistryConfig

Type re-exports

type SchemaDescriptor 

type SchemaDescriptor = farp.SchemaDescriptor

Type re-exports

type SchemaEndpoints 

type SchemaEndpoints = farp.SchemaEndpoints

Type re-exports

type SchemaEvent 

type SchemaEvent = farp.SchemaEvent

Type re-exports

type SchemaLocation 

type SchemaLocation = farp.SchemaLocation

Type re-exports

type SchemaManifest 

type SchemaManifest = farp.SchemaManifest

Type re-exports

type SchemaProvider 

type SchemaProvider = farp.SchemaProvider

Type re-exports

type SchemaRegistry 

type SchemaRegistry = farp.SchemaRegistry

Type re-exports

type SchemaType 

type SchemaType = farp.SchemaType

Type re-exports

type ValidationError 

type ValidationError = farp.ValidationError

Type re-exports

Source Files

View all Source files

Directories

Path Synopsis
examples
basic command
providers
asyncapi
avro
graphql
grpc
openapi
orpc
thrift
registry
memory

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.