diff --git a/CONFIG.md b/CONFIG.md index 991eb43..45ae6c5 100644 --- a/CONFIG.md +++ b/CONFIG.md @@ -622,9 +622,43 @@ routingRules: #### `domain` **Type**: `string` -**Required**: Yes +**Required**: Conditional (Required for v1.x.x, Optional for v2.x.x) **Description**: Beckn domain identifier (e.g., `retail:1.1.0`, `ONDC:TRV10`, `nic2004:60221`) +**Version-Specific Behavior**: +- **Beckn Protocol v1.x.x**: Domain is **required**. Each rule must specify a domain, and routing uses domain as a key. +- **Beckn Protocol v2.x.x**: Domain is **optional** and ignored during routing. If provided, a warning is logged. All v2 rules are domain-agnostic. +- **Conflict Detection**: For v2, multiple rules with the same version and endpoint (regardless of domain) will cause a configuration error. + +**Examples**: +```yaml +# Valid v1 rule - domain required +- domain: "ONDC:TRV10" + version: "1.1.0" + targetType: "url" + target: + url: "http://backend:3000" + endpoints: + - search + +# Valid v2 rule - domain optional (omitted) +- version: "2.0.0" + targetType: "url" + target: + url: "http://backend:3000" + endpoints: + - search + +# Valid v2 rule - domain provided (warning logged, but ignored) +- domain: "ONDC:TRV10" + version: "2.0.0" + targetType: "url" + target: + url: "http://backend:3000" + endpoints: + - search +``` + #### `version` **Type**: `string` **Required**: Yes @@ -792,6 +826,71 @@ routingRules: **Behavior**: All endpoints route to exactly `http://backend:3000/webhook` without appending the endpoint name. +#### Example 5: Beckn Protocol v2 Domain-Agnostic Routing + +```yaml +routingRules: + # v2 rule without domain (recommended) + - version: "2.0.0" + targetType: "url" + target: + url: "https://gateway.example.com/v2" + endpoints: + - search + - select + - init + - confirm + + # v1 rules still require domain + - domain: "ONDC:TRV10" + version: "1.1.0" + targetType: "url" + target: + url: "https://gateway.example.com/v1/trv" + endpoints: + - search +``` + +**Behavior**: +- v2 requests (version `2.0.0`) route to gateway regardless of domain in request +- v1 requests (version `1.1.0`) route based on domain matching +- Domain field is ignored for v2 routing decisions + +#### Example 6: v2 Conflict Detection + +```yaml +# INVALID CONFIGURATION - Will fail at startup +routingRules: + - domain: "ONDC:TRV10" + version: "2.0.0" + targetType: "url" + target: + url: "https://backend-a.com" + endpoints: + - search + + - domain: "ONDC:TRV11" # Different domain, but same version and endpoint + version: "2.0.0" + targetType: "url" + target: + url: "https://backend-b.com" + endpoints: + - search # ERROR: Duplicate v2 rule for 'search' endpoint +``` + +**Error**: Configuration will fail with: `duplicate endpoint 'search' found for version 2.0.0. For v2.x.x, domain is ignored, so you can only define each endpoint once per version. Please remove the duplicate rule` + +**Fix**: For v2, use a single rule per endpoint since domain is ignored: +```yaml +routingRules: + - version: "2.0.0" + targetType: "url" + target: + url: "https://unified-backend.com" + endpoints: + - search +``` + --- ## Deployment Scenarios diff --git a/README.md b/README.md index b524d58..4b25424 100644 --- a/README.md +++ b/README.md @@ -118,7 +118,7 @@ The **Beckn Protocol** is an open protocol that enables location-aware, local co #### 3. **Plugin Types** - **Cache**: Redis-based response caching -- **Router**: YAML-based routing rules engine for request forwarding +- **Router**: YAML-based routing rules engine for request forwarding (supports domain-agnostic routing for Beckn v2.x.x) - **Signer**: Ed25519 digital signature creation for outgoing requests - **SignValidator**: Ed25519 signature validation for incoming requests - **SchemaValidator**: JSON schema validation diff --git a/SETUP.md b/SETUP.md index fb563a4..f31e341 100644 --- a/SETUP.md +++ b/SETUP.md @@ -865,29 +865,39 @@ router: ### Routing Rules Configuration +**For complete routing configuration documentation including v2 domain-agnostic routing, see [CONFIG.md - Routing Configuration](CONFIG.md#routing-configuration).** + +Basic example: + ```yaml routingRules: + # v1.x.x - domain is required - domain: "ONDC:RET10" version: "1.0.0" targetType: "url" # or "publisher" target: url: "https://seller.example.com/beckn" - # OR for async - # queueName: "retail_queue" - # routingKey: "retail.*" endpoints: - search - select - init - confirm - headers: # Optional additional headers - X-Custom-Header: "value" - timeout: 60 # seconds - retryPolicy: - maxRetries: 3 - backoff: exponential + + # v2.x.x - domain is optional (domain-agnostic routing) + - version: "2.0.0" + targetType: "url" + target: + url: "https://seller.example.com/v2/beckn" + endpoints: + - search + - select ``` +**Key Points**: +- **v1.x.x**: Domain field is required and used for routing +- **v2.x.x**: Domain field is optional and ignored (domain-agnostic) +- See CONFIG.md for target types: `url`, `bpp`, `bap`, `publisher` + ### Processing Steps Available steps for configuration: