feat: add path matching and rules for API route inclusion/exclusion

- Implemented MatchPath function to match URL paths against glob patterns.
- Added PathRule struct to define include/exclude rules for API paths.
- Introduced ShouldIncludePath function to evaluate path rules.
- Created InternalPathRules function for default exclusion of internal endpoints.
- Enhanced BuildPathRules to combine internal and user-defined rules.
- Added comprehensive tests for path matching and rule evaluation.
- Updated RoutingConfig to include PathRules for controlling published routes.

Author: juicycleff

discovery/consul/consul.go

@@ -56,10 +56,10 @@ type Config struct {
 // ConsulDiscovery implements discovery.ServiceDiscovery using Consul.
 // It also implements farp.StorageBackend for KV operations.
 type ConsulDiscovery struct {
-	client    *consulapi.Client
-	config    Config
-	mu        sync.RWMutex
-	closed    bool
+	client *consulapi.Client
+	config Config
+	mu     sync.RWMutex
+	closed bool
 }
 
 // New creates a new Consul-based discovery backend.

discovery/mdns/mdns.go

@@ -228,12 +228,12 @@ func (m *MDNSDiscovery) Register(_ context.Context, instance discovery.ServiceIn
 	}
 
 	server, err := zeroconf.Register(
-		instance.ID,                   // instance name
-		m.config.ServiceType,          // service type
-		m.config.Domain,               // domain
-		port,                          // port
-		txt,                           // TXT records
-		ifaces,                        // interfaces
+		instance.ID,          // instance name
+		m.config.ServiceType, // service type
+		m.config.Domain,      // domain
+		port,                 // port
+		txt,                  // TXT records
+		ifaces,               // interfaces
 	)
 	if err != nil {
 		return fmt.Errorf("%w: mDNS registration failed: %w", farp.ErrRegistrationFailed, err)

discovery/node.go

@@ -55,6 +55,7 @@ func NewServiceNode(config ServiceNodeConfig) (*ServiceNode, error) {
 	manifest := farp.NewManifest(config.ServiceName, config.ServiceVersion, config.InstanceID)
 	manifest.Routing.Strategy = config.MountStrategy
 	manifest.Routing.BasePath = config.BasePath
+	manifest.Routing.PathRules = config.PathRules
 
 	// Wire endpoints from config, falling back to FARP defaults
 	manifest.Endpoints.Health = "/_farp/health"
@@ -387,6 +388,11 @@ func (n *ServiceNode) healthLoop(ctx context.Context, discovery ServiceDiscovery
 
 // pushHealthCheck sends a heartbeat with routes_checksum and handles
 // reconciliation if the gateway's state doesn't match (§17.4.1).
+//
+// Gateway restart recovery: if the heartbeat returns an error (e.g. 404
+// because the gateway lost all state), we re-register with the full
+// manifest so the gateway can rebuild its route table immediately
+// without needing to fetch the manifest back from the service.
 func (n *ServiceNode) pushHealthCheck(ctx context.Context, pushDisc *PushDiscovery) {
 	n.mu.RLock()
 	expectedChecksum := n.manifest.RoutesChecksum
@@ -398,22 +404,36 @@ func (n *ServiceNode) pushHealthCheck(ctx context.Context, pushDisc *PushDiscove
 		expectedChecksum,
 	)
 	if err != nil {
-		// Gateway unreachable — retry registration
-		n.retryRegister(ctx, pushDisc)
+		// Gateway unreachable or returned 404 (service unknown after restart).
+		// Re-register with full manifest so the gateway can rebuild immediately.
+		n.pushReRegisterWithManifest(ctx, pushDisc)
 		return
 	}
 
 	// Reconciliation: if gateway checksum doesn't match, re-register WITH
 	// manifest so the gateway can apply schemas without fetching.
 	if resp.RoutesChecksum != expectedChecksum {
-		n.mu.RLock()
-		manifest := n.manifest
-		n.mu.RUnlock()
+		n.pushReRegisterWithManifest(ctx, pushDisc)
+	}
+}
 
-		instance := n.buildInstance()
-		if _, err := pushDisc.RegisterWithManifest(ctx, instance, manifest); err != nil {
-			// Non-fatal: will retry on next heartbeat
-			_ = err
+// pushReRegisterWithManifest re-registers with the gateway, sending the
+// full manifest inline. This handles both gateway restarts (404) and
+// checksum mismatches without requiring the gateway to fetch back.
+func (n *ServiceNode) pushReRegisterWithManifest(ctx context.Context, pushDisc *PushDiscovery) {
+	n.mu.RLock()
+	manifest := n.manifest
+	n.mu.RUnlock()
+
+	instance := n.buildInstance()
+
+	for attempt := range n.config.MaxRetries {
+		if attempt > 0 {
+			time.Sleep(n.config.RetryBackoff * time.Duration(attempt))
+		}
+
+		if _, err := pushDisc.RegisterWithManifest(ctx, instance, manifest); err == nil {
+			return
 		}
 	}
 }

discovery/options.go

@@ -50,6 +50,7 @@ type ServiceNodeConfig struct {
 	// 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
@@ -144,4 +145,3 @@ func (c *GatewayNodeConfig) setDefaults() {
 		c.HeartbeatTimeout = 30 * time.Second
 	}
 }
-

discovery/push_handler.go

@@ -32,9 +32,9 @@ type PushHandler struct {
 }
 
 type pushEntry struct {
-	Instance    ServiceInstance
-	Manifest    *farp.SchemaManifest
-	LastSeen    time.Time
+	Instance ServiceInstance
+	Manifest *farp.SchemaManifest
+	LastSeen time.Time
 }
 
 // NewPushHandler creates a new push registration handler.

farp-rust/src/merger/mod.rs

@@ -34,6 +34,10 @@ pub struct MergerConfig {
     pub merged_version: String,
     /// Whether to include service tags in operations
     pub include_service_tags: bool,
+    /// When true, all operations from a service are grouped under a single
+    /// tag matching the service name, instead of prefixing individual tags.
+    /// Takes precedence over include_service_tags when both are true.
+    pub collapse_service_tags: bool,
     /// Whether to sort merged content alphabetically
     pub sort_output: bool,
     /// Custom server URLs for the merged spec
@@ -48,6 +52,7 @@ impl Default for MergerConfig {
             merged_description: "Merged API specification from multiple services".to_string(),
             merged_version: "1.0.0".to_string(),
             include_service_tags: true,
+            collapse_service_tags: false,
             sort_output: true,
             servers: Vec::new(),
         }
@@ -254,10 +259,14 @@ impl Merger {
                     &operation_id_prefix,
                     &tag_prefix,
                     &service_name,
+                    self.config.collapse_service_tags,
                     &mut seen_operation_ids,
                     &mut result,
                 );
 
+                // Rewrite $ref strings to match prefixed component names
+                rewrite_path_item_refs(&mut path_item, &component_prefix);
+
                 result.spec.paths.insert(path.clone(), path_item);
                 seen_paths.insert(path, service_name.clone());
             }
@@ -372,26 +381,40 @@ impl Merger {
             }
 
             // Merge tags
-            for mut tag in parsed.tags.clone() {
-                if !tag_prefix.is_empty() && self.config.include_service_tags {
-                    tag.name = format!("{}_{}", tag_prefix, tag.name);
+            if self.config.collapse_service_tags {
+                // Collapse all tags into a single service-level tag
+                let service_tag = Tag {
+                    name: service_name.clone(),
+                    description: Some(format!("Routes from {service_name}")),
+                    extensions: HashMap::new(),
+                };
+                if !seen_tags.contains_key(&service_tag.name) {
+                    seen_tags.insert(service_tag.name.clone(), service_tag.clone());
+                    result.spec.tags.push(service_tag);
                 }
+            } else {
+                for mut tag in parsed.tags.clone() {
+                    if !tag_prefix.is_empty() && self.config.include_service_tags {
+                        tag.name = format!("{}_{}", tag_prefix, tag.name);
+                    }
 
-                if let Some(existing) = seen_tags.get(&tag.name) {
-                    // Merge descriptions
-                    if tag.description.is_some() && existing.description.is_none() {
-                        let mut updated = existing.clone();
-                        updated.description = tag.description;
-                        seen_tags.insert(tag.name.clone(), updated.clone());
-                        // Update in result as well
-                        if let Some(pos) = result.spec.tags.iter().position(|t| t.name == tag.name)
-                        {
-                            result.spec.tags[pos] = updated;
+                    if let Some(existing) = seen_tags.get(&tag.name) {
+                        // Merge descriptions
+                        if tag.description.is_some() && existing.description.is_none() {
+                            let mut updated = existing.clone();
+                            updated.description = tag.description;
+                            seen_tags.insert(tag.name.clone(), updated.clone());
+                            // Update in result as well
+                            if let Some(pos) =
+                                result.spec.tags.iter().position(|t| t.name == tag.name)
+                            {
+                                result.spec.tags[pos] = updated;
+                            }
                         }
+                    } else {
+                        seen_tags.insert(tag.name.clone(), tag.clone());
+                        result.spec.tags.push(tag);
                     }
-                } else {
-                    seen_tags.insert(tag.name.clone(), tag.clone());
-                    result.spec.tags.push(tag);
                 }
             }
         }

farp-rust/src/merger/openapi.rs

@@ -334,7 +334,7 @@ fn apply_mount_strategy(path: &str, manifest: &SchemaManifest) -> String {
     }
 }
 
-/// Adds prefix to component schema names
+/// Adds prefix to component schema names and rewrites $ref strings.
 pub fn prefix_component_names(components: &Components, prefix: &str) -> Components {
     if prefix.is_empty() {
         return components.clone();
@@ -344,7 +344,11 @@ pub fn prefix_component_names(components: &Components, prefix: &str) -> Componen
         schemas: components
             .schemas
             .iter()
-            .map(|(name, schema)| (format!("{prefix}_{name}"), schema.clone()))
+            .map(|(name, schema)| {
+                let mut rewritten = schema.clone();
+                rewrite_refs(&mut rewritten, prefix);
+                (format!("{prefix}_{name}"), rewritten)
+            })
             .collect(),
         responses: components
             .responses
@@ -362,8 +366,97 @@ pub fn prefix_component_names(components: &Components, prefix: &str) -> Componen
             .map(|(name, body)| (format!("{prefix}_{name}"), body.clone()))
             .collect(),
         headers: HashMap::new(),
-        security_schemes: components.security_schemes.clone(), // Don't prefix security schemes
+        security_schemes: components.security_schemes.clone(),
+    }
+}
+
+/// Recursively rewrites $ref strings in a JSON value.
+/// Transforms "#/components/schemas/Foo" → "#/components/schemas/prefix_Foo".
+pub fn rewrite_refs(value: &mut serde_json::Value, prefix: &str) {
+    match value {
+        serde_json::Value::Object(map) => {
+            if let Some(serde_json::Value::String(ref_str)) = map.get("$ref") {
+                let rewritten = rewrite_ref_string(ref_str, prefix);
+                map.insert("$ref".to_string(), serde_json::Value::String(rewritten));
+            }
+            for (key, val) in map.iter_mut() {
+                if key != "$ref" {
+                    rewrite_refs(val, prefix);
+                }
+            }
+        }
+        serde_json::Value::Array(arr) => {
+            for item in arr.iter_mut() {
+                rewrite_refs(item, prefix);
+            }
+        }
+        _ => {}
+    }
+}
+
+fn rewrite_ref_string(ref_str: &str, prefix: &str) -> String {
+    let component_prefixes = [
+        "#/components/schemas/",
+        "#/components/responses/",
+        "#/components/parameters/",
+        "#/components/requestBodies/",
+        "#/components/headers/",
+    ];
+
+    for cp in &component_prefixes {
+        if let Some(name) = ref_str.strip_prefix(cp) {
+            return format!("{cp}{prefix}_{name}");
+        }
+    }
+
+    ref_str.to_string()
+}
+
+/// Rewrites $ref strings in all operations of a PathItem.
+pub fn rewrite_path_item_refs(item: &mut PathItem, prefix: &str) {
+    if prefix.is_empty() {
+        return;
     }
+
+    let rewrite_op = |op: &mut Option<Operation>| {
+        if let Some(operation) = op {
+            // Rewrite refs in responses
+            if let Some(ref mut responses) = operation.responses {
+                for resp in responses.values_mut() {
+                    if let Some(ref mut content) = resp.content {
+                        for media in content.values_mut() {
+                            if let Some(ref mut schema) = media.schema {
+                                rewrite_refs(schema, prefix);
+                            }
+                        }
+                    }
+                }
+            }
+            // Rewrite refs in parameters
+            for param in &mut operation.parameters {
+                if let Some(ref mut schema) = param.schema {
+                    rewrite_refs(schema, prefix);
+                }
+            }
+            // Rewrite refs in request body
+            if let Some(ref mut rb) = operation.request_body {
+                for media in rb.content.values_mut() {
+                    if let Some(ref mut schema) = media.schema {
+                        rewrite_refs(schema, prefix);
+                    }
+                }
+            }
+        }
+    };
+
+    rewrite_op(&mut item.get);
+    rewrite_op(&mut item.post);
+    rewrite_op(&mut item.put);
+    rewrite_op(&mut item.delete);
+    rewrite_op(&mut item.patch);
+    rewrite_op(&mut item.options);
+    rewrite_op(&mut item.head);
+    rewrite_op(&mut item.trace);
 }
 
 /// Applies prefixes to operation IDs and tags
@@ -372,6 +465,7 @@ pub fn apply_operation_prefixes(
     op_id_prefix: &str,
     tag_prefix: &str,
     service_name: &str,
+    collapse_service_tags: bool,
     seen_operation_ids: &mut HashMap<String, String>,
     result: &mut MergeResult,
 ) -> PathItem {
@@ -399,8 +493,10 @@ pub fn apply_operation_prefixes(
                 operation.operation_id = Some(new_id);
             }
 
-            // Prefix tags
-            if !tag_prefix.is_empty() {
+            // Handle tags: collapse all to service name, or prefix individually
+            if collapse_service_tags {
+                operation.tags = vec![service_name.to_string()];
+            } else if !tag_prefix.is_empty() {
                 operation.tags = operation
                     .tags
                     .iter()