feat: Enhance OpenAPI provider to build paths from application routes

- Implemented `build_paths` method in OpenAPIProvider to convert application routes into OpenAPI path items.
- Added support for multiple route representations including `RouteDescriptor` and direct OpenAPI paths.
- Updated OpenAPI schema generation to include dynamically built paths.
- Introduced new WebhookEventType `GatewayShutdown` for gateway shutdown notifications.
- Refactored routing strategy to use `Service` as the default mount strategy.
- Added comprehensive tests for federated schema handling and OpenAPI generation.
- Introduced `FederatedSchemaHandler` to serve merged schema endpoints with caching.
- Enhanced error handling and response validation in the federated handler.

Author: juicycleff

discovery/node.go

@@ -1,9 +1,11 @@
 package discovery
 
 import (
+	"bytes"
 	"context"
 	"crypto/rand"
 	"encoding/hex"
+	"encoding/json"
 	"fmt"
 	"net/http"
 	"strings"
@@ -233,7 +235,7 @@ type serviceApp struct {
 
 func (a *serviceApp) Name() string    { return a.config.ServiceName }
 func (a *serviceApp) Version() string { return a.config.ServiceVersion }
-func (a *serviceApp) Routes() any     { return nil }
+func (a *serviceApp) Routes() any     { return a.config.Routes }
 
 func (n *ServiceNode) generateSchemas(ctx context.Context) error {
 	app := &serviceApp{config: &n.config}
@@ -501,7 +503,12 @@ func (n *GatewayNode) Start(ctx context.Context) error {
 }
 
 // Stop stops watching and cleans up.
+// Before shutting down, it sends a fire-and-forget gateway.shutdown notification
+// to all services that have a webhook endpoint configured.
 func (n *GatewayNode) Stop(_ context.Context) error {
+	// Notify services before stopping (fire-and-forget)
+	n.notifyServicesShutdown()
+
 	if n.cancel != nil {
 		n.cancel()
 		<-n.done
@@ -660,6 +667,67 @@ func (n *GatewayNode) notifyRouteChange() {
 	}
 }
 
+// notifyServicesShutdown sends a gateway.shutdown event to all services that
+// have a webhook endpoint configured. This is fire-and-forget: each notification
+// is dispatched in its own goroutine with a short timeout, and errors are silently
+// discarded. The gateway does not wait for responses.
+func (n *GatewayNode) notifyServicesShutdown() {
+	n.mu.RLock()
+	manifests := make([]*farp.SchemaManifest, 0, len(n.manifests))
+	for _, m := range n.manifests {
+		manifests = append(manifests, m)
+	}
+	n.mu.RUnlock()
+
+	if len(manifests) == 0 {
+		return
+	}
+
+	event := farp.WebhookEvent{
+		Type:      farp.EventGatewayShutdown,
+		Timestamp: time.Now().Unix(),
+		Source:    "gateway",
+	}
+
+	payload, err := json.Marshal(event)
+	if err != nil {
+		return
+	}
+
+	client := n.config.HTTPClient
+	if client == nil {
+		client = &http.Client{Timeout: 3 * time.Second}
+	}
+
+	for _, manifest := range manifests {
+		webhookURL := manifest.Webhook.ServiceWebhook
+		if webhookURL == "" {
+			continue
+		}
+
+		// Fire and forget — each in its own goroutine
+		go func(url string) {
+			ctx, cancel := context.WithTimeout(context.Background(), 3*time.Second)
+			defer cancel()
+
+			req, err := http.NewRequestWithContext(ctx, http.MethodPost, url, bytes.NewReader(payload))
+			if err != nil {
+				return
+			}
+
+			req.Header.Set("Content-Type", "application/json")
+			req.Header.Set("X-Farp-Event", string(farp.EventGatewayShutdown))
+
+			resp, err := client.Do(req)
+			if err != nil {
+				return
+			}
+
+			resp.Body.Close()
+		}(webhookURL)
+	}
+}
+
 // =============================================================================
 // Helpers
 // =============================================================================

discovery/options.go

@@ -51,6 +51,12 @@ type ServiceNodeConfig struct {
 	MountStrategy farp.MountStrategy
 	BasePath      string
 
+	// 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
 

docs/ARCHITECTURE.md

@@ -6,18 +6,18 @@
 
 FARP is a **protocol specification library**, NOT a complete gateway or service framework. This document clarifies what FARP provides versus what implementers (services and gateways) must build.
 
-### Responsibility Matrix
+### Responsibility Matrix (v1.1.0)
 
 | Concern | FARP Library | Service Implementation | Gateway Implementation |
 |---------|--------------|------------------------|------------------------|
 | **Data Structures** | ✅ Defines types | Uses types | Uses types |
 | **Schema Generation** | ✅ Providers | Calls providers | - |
 | **Schema Merging** | ✅ Merge logic | - | Calls merge logic |
-| **HTTP Endpoints** | ❌ Examples only | ✅ **Must implement** | ✅ **Must implement** |
-| **Service Discovery** | ❌ Interface only | ✅ **Must integrate** | ✅ **Must integrate** |
-| **Registry Backend** | ❌ Interface only | ✅ **Must choose/config** | ✅ **Must choose/config** |
-| **Route Configuration** | ❌ Examples only | - | ✅ **Must implement** |
-| **Health Monitoring** | ❌ Not provided | ✅ **Must expose** | ✅ **Must poll** |
+| **HTTP Endpoints** | ✅ `FARPHandler` | Mounts handler on router | - |
+| **Service Discovery** | ✅ 6 backends + push | Uses `ServiceNode` | Uses `GatewayNode` |
+| **Registry Backend** | ✅ Memory + KV via backends | Auto via `ServiceNode` | Auto via `GatewayNode` |
+| **Route Configuration** | ✅ Schema-to-route conversion | - | Applies routes from callback |
+| **Health Monitoring** | ✅ Auto health loop | Auto via `ServiceNode` | Auto via `GatewayNode` |
 | **Webhook Transport** | ❌ Types only | ✅ **Must implement** | ✅ **Must implement** |
 
 ### What FARP Provides (✅)
@@ -42,20 +42,45 @@ FARP is a **protocol specification library**, NOT a complete gateway or service
    - Checksum calculation and verification
    - Version compatibility checks
 
-5. **Storage Abstractions** (`registry.go`)
-   - Interface definitions only
-   - No backend implementations (except `memory` for testing)
+5. **Storage Abstractions** (`registry.go`, `storage.go`)
+   - `SchemaRegistry` and `StorageBackend` interfaces
+   - In-memory implementation for testing (`registry/memory`)
+   - KV-based backends via discovery backends (Consul, etcd, Redis)
+
+6. **Service Discovery** (`discovery/*`)
+   - `ServiceDiscovery` interface with 6 backend implementations
+   - `ServiceNode` — auto-lifecycle for services (register, health, schemas)
+   - `GatewayNode` — auto-lifecycle for gateways (discover, fetch, routes)
+   - `FARPHandler` — ready-to-mount HTTP handler for FARP endpoints
+   - Push-based discovery — no external registry needed
+
+7. **Gateway Client** (`gateway/*`)
+   - Schema-to-route conversion (OpenAPI, AsyncAPI, GraphQL)
+   - Route hash comparison to prevent unnecessary remounts
+   - Atomic route swap via `RouteUpdateHandler` interface
 
 ### What Service Frameworks Must Implement (Services using FARP)
 
-1. **HTTP Server Endpoints**
+With the discovery system, most integration is automatic via `ServiceNode`:
+
+```go
+node, _ := discovery.NewServiceNode(discovery.ServiceNodeConfig{
+    ServiceName: "user-service",
+    Address:     "10.0.0.5:8080",
+    Discovery:   consulBackend,
+})
+node.Start(ctx)
+http.Handle("/_farp/", node.HTTPHandler()) // mount on your router
+```
+
+For manual integration (without `ServiceNode`):
+
+1. **HTTP Server Endpoints** — or use `FARPHandler`
    - `GET /_farp/manifest` - Return `SchemaManifest` JSON
-   - `GET /openapi.json` - Return OpenAPI schema (if using HTTP location)
-   - `GET /asyncapi.json` - Return AsyncAPI schema (if using HTTP location)
-   - `GET /health` - Health check endpoint
-   - `GET /metrics` - Metrics endpoint
+   - `GET /_farp/health` - Health check endpoint
+   - `GET /_farp/schemas/{type}` - Return schema by type
 
-2. **Discovery Backend Integration**
+2. **Discovery Backend Integration** — or use `ServiceNode`
    - Register service with Consul/etcd/K8s/mDNS
    - Store FARP manifest in backend metadata
    - Handle TTL/heartbeats