docs: Update documentation for v2 domain-agnostic routing
This commit is contained in:
101
CONFIG.md
101
CONFIG.md
@@ -622,9 +622,43 @@ routingRules:
|
|||||||
|
|
||||||
#### `domain`
|
#### `domain`
|
||||||
**Type**: `string`
|
**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`)
|
**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`
|
#### `version`
|
||||||
**Type**: `string`
|
**Type**: `string`
|
||||||
**Required**: Yes
|
**Required**: Yes
|
||||||
@@ -792,6 +826,71 @@ routingRules:
|
|||||||
|
|
||||||
**Behavior**: All endpoints route to exactly `http://backend:3000/webhook` without appending the endpoint name.
|
**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
|
## Deployment Scenarios
|
||||||
|
|||||||
@@ -118,7 +118,7 @@ The **Beckn Protocol** is an open protocol that enables location-aware, local co
|
|||||||
|
|
||||||
#### 3. **Plugin Types**
|
#### 3. **Plugin Types**
|
||||||
- **Cache**: Redis-based response caching
|
- **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
|
- **Signer**: Ed25519 digital signature creation for outgoing requests
|
||||||
- **SignValidator**: Ed25519 signature validation for incoming requests
|
- **SignValidator**: Ed25519 signature validation for incoming requests
|
||||||
- **SchemaValidator**: JSON schema validation
|
- **SchemaValidator**: JSON schema validation
|
||||||
|
|||||||
28
SETUP.md
28
SETUP.md
@@ -865,29 +865,39 @@ router:
|
|||||||
|
|
||||||
### Routing Rules Configuration
|
### 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
|
```yaml
|
||||||
routingRules:
|
routingRules:
|
||||||
|
# v1.x.x - domain is required
|
||||||
- domain: "ONDC:RET10"
|
- domain: "ONDC:RET10"
|
||||||
version: "1.0.0"
|
version: "1.0.0"
|
||||||
targetType: "url" # or "publisher"
|
targetType: "url" # or "publisher"
|
||||||
target:
|
target:
|
||||||
url: "https://seller.example.com/beckn"
|
url: "https://seller.example.com/beckn"
|
||||||
# OR for async
|
|
||||||
# queueName: "retail_queue"
|
|
||||||
# routingKey: "retail.*"
|
|
||||||
endpoints:
|
endpoints:
|
||||||
- search
|
- search
|
||||||
- select
|
- select
|
||||||
- init
|
- init
|
||||||
- confirm
|
- confirm
|
||||||
headers: # Optional additional headers
|
|
||||||
X-Custom-Header: "value"
|
# v2.x.x - domain is optional (domain-agnostic routing)
|
||||||
timeout: 60 # seconds
|
- version: "2.0.0"
|
||||||
retryPolicy:
|
targetType: "url"
|
||||||
maxRetries: 3
|
target:
|
||||||
backoff: exponential
|
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
|
### Processing Steps
|
||||||
|
|
||||||
Available steps for configuration:
|
Available steps for configuration:
|
||||||
|
|||||||
Reference in New Issue
Block a user