{"id":33926436,"url":"https://github.com/xraph/farp","last_synced_at":"2026-04-12T21:18:21.597Z","repository":{"id":322652077,"uuid":"1089943537","full_name":"xraph/farp","owner":"xraph","description":"Yet another API Gateway/Service Registration and Discovery Protocol","archived":false,"fork":false,"pushed_at":"2025-11-05T17:20:39.000Z","size":295,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-11-05T17:30:10.970Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/xraph.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-05T02:50:45.000Z","updated_at":"2025-11-05T17:20:43.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/xraph/farp","commit_stats":null,"previous_names":["xraph/farp"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/xraph/farp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xraph%2Ffarp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xraph%2Ffarp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xraph%2Ffarp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xraph%2Ffarp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/xraph","download_url":"https://codeload.github.com/xraph/farp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xraph%2Ffarp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":27680626,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-12-12T02:00:06.775Z","response_time":129,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-12-12T10:14:36.563Z","updated_at":"2026-04-12T21:18:21.591Z","avatar_url":"https://github.com/xraph.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# FARP - Forge API Gateway Registration Protocol\n\n[![CI](https://github.com/xraph/farp/workflows/CI/badge.svg)](https://github.com/xraph/farp/actions?query=workflow%3ACI)\n[![Go Report Card](https://goreportcard.com/badge/github.com/xraph/farp)](https://goreportcard.com/report/github.com/xraph/farp)\n[![GoDoc](https://godoc.org/github.com/xraph/farp?status.svg)](https://godoc.org/github.com/xraph/farp)\n[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)\n[![Release](https://img.shields.io/github/v/release/xraph/farp)](https://github.com/xraph/farp/releases)\n\nFARP™ is a service manifest and schema-discovery protocol maintained by XRAPH™.\n\n**Authors**: [Rex Raphael](https://github.com/juicycleff)\n\n**Last Updated**: 2025-11-01\n\n## Overview\n\nFARP (Forge API Gateway Registration Protocol) is a **protocol specification library** that enables service instances to communicate their API schemas, health information, and capabilities to API gateways and service meshes. It provides standardized data structures, schema generation tooling, and merging utilities—but **does not implement HTTP servers, gateway logic, or service discovery**.\n\n### What FARP Is\n\n- **Protocol Specification** - Defines the SchemaManifest format and data structures\n- **Schema Generation Library** - Providers to generate OpenAPI, AsyncAPI, gRPC, GraphQL, oRPC, Thrift, and Avro schemas from code\n- **Schema Merging Utilities** - Tools to compose multiple service schemas into unified API documentation\n- **Service Discovery** - Pluggable discovery with Consul, etcd, Kubernetes, Redis, mDNS, and push-based backends\n- **Auto-Registration** - `ServiceNode` and `GatewayNode` manage the full FARP lifecycle automatically\n- **Validation \u0026 Serialization** - Ensure manifests are spec-compliant\n\n### What FARP Is NOT\n\n- ❌ **Not an API Gateway** - No routing, rate limiting, or traffic management (but provides hints for them)\n- ❌ **Not a Service Framework** - Services mount FARP HTTP handlers on their own router\n\n## Key Features\n\n- **Pluggable Service Discovery**: Consul, etcd, Kubernetes, Redis, mDNS, and push-based — or bring your own\n- **Auto-Lifecycle Management**: `ServiceNode` and `GatewayNode` handle registration, health, schemas, and routes automatically\n- **Push-Based Discovery**: Services push manifests directly to gateways — zero infrastructure needed\n- **Schema-Aware Service Discovery**: Services register with complete API contracts\n- **Multi-Protocol Support**: OpenAPI, AsyncAPI, gRPC, GraphQL, oRPC, Thrift, Avro, and extensible for future protocols\n- **Zero-Downtime Route Updates**: Routes checksum + atomic swap prevents intermittent 404s\n- **Operational Hints**: Rate limiting, circuit breaker, CORS, caching, load balancing, observability — all declarative\n- **FARP HTTP Handler**: Ready-to-mount handler serves `/_farp/manifest`, health, and schema endpoints\n- **Dual Language**: Full Go and Rust implementations with consistent APIs\n- **Backend Agnostic Storage**: Works with Consul KV, etcd, Redis, or in-memory for schema storage\n- **Zero Configuration**: Works with mDNS/Bonjour or push mode for local development without infrastructure\n\n## Architectural Boundaries\n\nFARP provides the protocol, schema tooling, and service discovery — you provide the HTTP router and gateway proxy.\n\n### FARP Library Provides\n\n| Component | Description | Package |\n|-----------|-------------|---------|\n| **Type Definitions** | `SchemaManifest`, `SchemaDescriptor`, routing/auth/hints | `types.go` |\n| **Schema Providers** | Generate schemas from code | `providers/*` |\n| **Service Discovery** | Pluggable backends + auto-lifecycle | `discovery/*` |\n| **FARP HTTP Handler** | Serves manifest, health, and schema endpoints | `discovery/handler.go` |\n| **Gateway Client** | Schema-to-route conversion with atomic swap | `gateway/*` |\n| **Registry + Storage** | Manifest storage and caching | `registry.go`, `storage.go` |\n| **Merging Logic** | Compose multiple schemas into unified docs | `merger/*` |\n| **Validation** | Ensure manifests are spec-compliant | `manifest.go` |\n\n### What You Implement\n\n| Concern | What You Do |\n|---------|-------------|\n| **HTTP Router** | Mount `node.HTTPHandler()` on your router (e.g., chi, gin, echo) |\n| **Gateway Proxy** | Apply routes from `OnRoutesChanged` to your proxy (e.g., reverse proxy, Envoy) |\n| **Schema Providers** | (Optional) Custom providers for your framework's routes |\n| **Webhooks** | (Optional) Implement webhook receivers for gateway events |\n\n## Repository Structure\n\n```text\nfarp/\n├── README.md                    # This file - project overview\n├── docs/\n│   ├── SPECIFICATION.md         # Complete protocol specification\n│   ├── ARCHITECTURE.md          # Architecture and design decisions\n│   ├── DISCOVERY.md             # Service discovery guide\n│   └── IMPLEMENTATION_RESPONSIBILITIES.md\n├── discovery/                   # Service discovery system\n│   ├── discovery.go             # ServiceDiscovery interface, types\n│   ├── node.go                  # ServiceNode + GatewayNode (auto-lifecycle)\n│   ├── handler.go               # FARP HTTP handler + ManifestFetcher\n│   ├── push.go                  # Push-based discovery (service→gateway)\n│   ├── push_handler.go          # Push handler (gateway-side receiver)\n│   ├── consul/                  # Consul backend\n│   ├── etcd/                    # etcd backend\n│   ├── kubernetes/              # Kubernetes backend\n│   ├── redis/                   # Redis backend\n│   └── mdns/                    # mDNS/Bonjour backend\n├── providers/                   # Schema provider implementations\n│   ├── openapi/                 # OpenAPI 3.x provider\n│   ├── asyncapi/                # AsyncAPI 2.x/3.x provider\n│   ├── grpc/                    # gRPC FileDescriptorSet provider\n│   ├── graphql/                 # GraphQL SDL/introspection provider\n│   ├── orpc/                    # oRPC (OpenAPI-based RPC) provider\n│   ├── thrift/                  # Apache Thrift IDL provider\n│   └── avro/                    # Apache Avro schema provider\n├── gateway/                     # Reference gateway client\n├── merger/                      # Multi-schema composition\n├── types.go                     # Core protocol types\n├── manifest.go                  # Schema manifest operations\n├── provider.go                  # Schema provider interface\n├── registry.go                  # Schema registry interface\n├── storage.go                   # Storage abstraction\n├── version.go                   # Protocol version (1.1.0)\n└── farp-rust/                   # Rust implementation\n```\n\n## Quick Start\n\n### Using Schema Providers\n\n```go\nimport (\n    \"github.com/xraph/farp/providers/openapi\"\n    \"github.com/xraph/farp/providers/grpc\"\n    \"github.com/xraph/farp/providers/graphql\"\n    \"github.com/xraph/farp/providers/orpc\"\n    \"github.com/xraph/farp/providers/thrift\"\n    \"github.com/xraph/farp/providers/avro\"\n)\n\n// OpenAPI provider\nopenapiProvider := openapi.NewProvider(\"3.1.0\", \"/openapi.json\")\nschema, err := openapiProvider.Generate(ctx, app)\n\n// gRPC provider (with reflection)\ngrpcProvider := grpc.NewProvider(\"proto3\", nil)\nschema, err = grpcProvider.Generate(ctx, app)\n\n// GraphQL provider (SDL format)\ngraphqlProvider := graphql.NewProvider(\"2021\", \"/graphql\")\ngraphqlProvider.UseSDL()\nschema, err = graphqlProvider.Generate(ctx, app)\n\n// oRPC provider\norpcProvider := orpc.NewProvider(\"1.0.0\", \"/orpc.json\")\nschema, err = orpcProvider.Generate(ctx, app)\n\n// Thrift provider (from IDL files)\nthriftProvider := thrift.NewProvider(\"0.19.0\", []string{\"user.thrift\"})\nschema, err = thriftProvider.Generate(ctx, app)\n\n// Avro provider (from schema files)\navroProvider := avro.NewProvider(\"1.11.1\", []string{\"user.avsc\"})\nschema, err = avroProvider.Generate(ctx, app)\n```\n\n### Service Registration\n\n```go\nimport \"github.com/xraph/farp\"\n\n// Create schema manifest\nmanifest := \u0026farp.SchemaManifest{\n    Version:        farp.ProtocolVersion,\n    ServiceName:    \"user-service\",\n    ServiceVersion: \"v1.2.3\",\n    InstanceID:     \"user-service-abc123\",\n    Schemas: []farp.SchemaDescriptor{\n        {\n            Type:        farp.SchemaTypeOpenAPI,\n            SpecVersion: \"3.1.0\",\n            Location: farp.SchemaLocation{\n                Type: farp.LocationTypeHTTP,\n                URL:  \"http://user-service:8080/openapi.json\",\n            },\n        },\n        {\n            Type:        farp.SchemaTypeGRPC,\n            SpecVersion: \"proto3\",\n            Location: farp.SchemaLocation{\n                Type: farp.LocationTypeInline,\n            },\n        },\n        {\n            Type:        farp.SchemaTypeGraphQL,\n            SpecVersion: \"2021\",\n            Location: farp.SchemaLocation{\n                Type: farp.LocationTypeHTTP,\n                URL:  \"http://user-service:8080/graphql\",\n            },\n        },\n    },\n    Capabilities: []string{\"rest\", \"grpc\", \"graphql\", \"websocket\"},\n    Endpoints: farp.SchemaEndpoints{\n        Health:         \"/health\",\n        Metrics:        \"/metrics\",\n        OpenAPI:        \"/openapi.json\",\n        GraphQL:        \"/graphql\",\n        GRPCReflection: true,\n    },\n}\n\n// Register with backend\nregistry.RegisterManifest(ctx, manifest)\n```\n\n### Service Discovery (Recommended)\n\nThe discovery system handles registration, health, and route management automatically:\n\n```go\nimport (\n    \"github.com/xraph/farp/discovery\"\n    \"github.com/xraph/farp/discovery/consul\"\n)\n\n// === Service side ===\ndisc, _ := consul.New(consul.Config{Address: \"consul:8500\"})\nnode, _ := discovery.NewServiceNode(discovery.ServiceNodeConfig{\n    ServiceName: \"user-service\",\n    Address:     \"10.0.0.5:8080\",\n    Discovery:   disc,\n})\nnode.Start(ctx)\ndefer node.Stop(ctx)\nhttp.Handle(\"/_farp/\", node.HTTPHandler())\n\n// === Gateway side ===\ngw, _ := discovery.NewGatewayNode(discovery.GatewayNodeConfig{\n    Discovery: disc,\n    OnRoutesChanged: func(routes []gateway.ServiceRoute) {\n        for _, route := range routes {\n            proxy.AddRoute(route.Path, route.TargetURL)\n        }\n    },\n})\ngw.Start(ctx)\n```\n\n### Push Mode (Zero Infrastructure)\n\n```go\n// Service pushes directly to gateway — no Consul/etcd needed\nnode, _ := discovery.NewServiceNode(discovery.ServiceNodeConfig{\n    ServiceName: \"user-service\",\n    Address:     \"10.0.0.5:8080\",\n    GatewayURL:  \"http://gateway:9090/_farp/v1\",\n})\nnode.Start(ctx)\n\n// Gateway accepts push registrations\ngw, _ := discovery.NewGatewayNode(discovery.GatewayNodeConfig{\n    EnablePush: true,\n    OnRoutesChanged: updateRoutes,\n})\ngw.Start(ctx)\nhttp.Handle(\"/_farp/v1/\", gw.PushHandler())\n```\n\n### Low-Level Gateway Client\n\n```go\nimport \"github.com/xraph/farp/gateway\"\n\n// For advanced use without the discovery system\nclient := gateway.NewClient(registry)\nclient.WatchServices(ctx, \"\", func(routes []gateway.ServiceRoute) {\n    for _, route := range routes {\n        proxy.AddRoute(route.Path, route.TargetURL)\n    }\n})\n```\n\n## Use Cases\n\n1. **API Gateway Auto-Configuration**: Gateways like Kong, Traefik, or Nginx automatically register routes based on service schemas\n2. **Service Mesh Control Plane**: Enable contract-aware routing and validation in service meshes\n3. **Developer Portals**: Auto-generate API documentation from registered schemas\n4. **Multi-Protocol Systems**: Unified discovery for REST, gRPC, GraphQL, and async protocols\n5. **Contract Testing**: Validate service contracts at deployment time\n6. **Schema Versioning**: Support multiple API versions with zero-downtime migrations\n\n## Protocol Status\n\n- ✅ Core protocol specification (v1.1.0)\n- ✅ Type definitions with route table, routes checksum, and operational hints\n- ✅ Schema providers (OpenAPI, AsyncAPI, gRPC, GraphQL, oRPC, Thrift, Avro)\n- ✅ Service discovery system (Consul, etcd, Kubernetes, Redis, mDNS, Push)\n- ✅ ServiceNode and GatewayNode auto-lifecycle management\n- ✅ Gateway client with atomic route swap (zero-downtime)\n- ✅ Rust implementation with feature-flagged backends\n- ⏳ Community feedback and refinement\n\n## Supported Schema Types\n\n| Protocol | Status | Provider | Spec Version | Content Type |\n|----------|--------|----------|--------------|--------------|\n| **OpenAPI** | ✅ Complete | `providers/openapi` | 3.1.0 (default) | `application/json` |\n| **AsyncAPI** | ✅ Complete | `providers/asyncapi` | 3.0.0 (default) | `application/json` |\n| **gRPC** | ✅ Complete | `providers/grpc` | proto3 (default) | `application/json` |\n| **GraphQL** | ✅ Complete | `providers/graphql` | 2021 (default) | `application/graphql` or `application/json` |\n| **oRPC** | ✅ Complete | `providers/orpc` | 1.0.0 | `application/json` |\n| **Thrift** | ✅ Complete | `providers/thrift` | 0.19.0 (default) | `application/json` |\n| **Avro** | ✅ Complete | `providers/avro` | 1.11.1 (default) | `application/json` |\n\nSee [PROVIDERS_IMPLEMENTATION.md](PROVIDERS_IMPLEMENTATION.md) for detailed provider documentation.\n\n## Documentation\n\n### Essential Reading\n\n- **[Service Discovery Guide](docs/DISCOVERY.md)** - **START HERE** - Full discovery system guide with all backends\n- [Complete Specification](docs/SPECIFICATION.md) - Full protocol specification (v1.1.0)\n- [Architecture Guide](docs/ARCHITECTURE.md) - Design decisions and architectural boundaries\n- [Implementation Responsibilities](docs/IMPLEMENTATION_RESPONSIBILITIES.md) - What FARP provides vs what you implement\n\n### Integration Guides\n\n- [Gateway Discovery Examples](docs/GATEWAY_DISCOVERY_EXAMPLES.md) - Practical gateway integration examples\n- [mDNS Service Type Configuration](docs/MDNS_SERVICE_TYPE_GUIDE.md) - Service type filtering for gateways\n- [Providers Implementation](PROVIDERS_IMPLEMENTATION.md) - Schema provider guide\n\n### Reference\n\n- [FARP Specification](docs/SPECIFICATION.md) - Complete protocol specification\n- [Error Handling](errors.go) - Error types and handling patterns\n\n## Contributing\n\nFARP is part of the Forge framework. Contributions are welcome! Please see the main Forge repository for contribution guidelines.\n\n## License\n\nApache License 2.0 - See LICENSE file in the Forge repository\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxraph%2Ffarp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fxraph%2Ffarp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxraph%2Ffarp/lists"}