onix/CONFIG.md

Beckn-ONIX Configuration Guide

Table of Contents

1. Overview
2. Configuration File Structure
3. Top-Level Configuration
4. HTTP Configuration
5. Logging Configuration
6. Metrics Configuration
7. Plugin Manager Configuration
8. Module Configuration
9. Handler Configuration
10. Plugin Configuration
11. Routing Configuration
12. Deployment Scenarios
13. Configuration Examples

---

Overview

Beckn-ONIX uses YAML configuration files to define its behavior. The plugin based architecture enables beckn enabled network participants to deploy onix adapter in variety of scenarios, all of which can be controlled and configured using the adapter config files and hence, understanding how the configuration is strctured is very critical.

let's start with understanding following key concepts first.

Module Handler

A Module Handler or simply handler encapsulates execution logic (steps and plugins) for partcular scenario. Scenario could be typically classified in 2 buckets, txn caller, outgoing call into Beckn network and txn receiver, incoming call from Beckn network. The handler enables flexibility to execute different steps (peformed by different plugins) for both scenarios. A single deployed onix adapter service can run multiple handlers and hence a single adapter can support multiple BAPs and/or BPPs. Each handler defines its own set of steps and plugin configurations.

Plugins

This is a sub section to the handler, meaning each handler can load a separate set of plugins. Plugins section enlists all plugins to be loaded at the start, and further includes configuration parameters for each of the listed plugin.

Steps

This is a list of steps that executed by the handler in the same given order.

The configuration file is an input to the onix adapter and it is recommended to use different files for different deployment scenarios (local development, production, BAP-only, BPP-only, or combined).

Configuration File Locations

config/
├── local-dev.yaml                    # Local development (with Vault)
├── local-simple.yaml                 # Local development (embedded keys)
├── local-routing.yaml                # Local routing rules
├── onix/                             # Production combined mode
│   ├── adapter.yaml
│   ├── bapTxnCaller-routing.yaml
│   ├── bapTxnReciever-routing.yaml
│   ├── bppTxnCaller-routing.yaml
│   ├── bppTxnReciever-routing.yaml
│   └── plugin.yaml
├── onix-bap/                         # Production BAP-only mode
│   ├── adapter.yaml
│   ├── bapTxnCaller-routing.yaml
│   ├── bapTxnReciever-routing.yaml
│   └── plugin.yaml
└── onix-bpp/                         # Production BPP-only mode
    ├── adapter.yaml
    ├── bppTxnCaller-routing.yaml
    ├── bppTxnReciever-routing.yaml
    └── plugin.yaml

---

Configuration File Structure

Main Configuration File (adapter.yaml)

The main configuration file follows this structure:

appName: "onix-local"
log: {...}
metrics: {...}
http: {...}
pluginManager: {...}
modules: [...]

---

Top-Level Configuration

appName

Type: string
Required: Yes
Description: Application identifier used in logging and monitoring.

Example:

appName: "onix-local"

---

HTTP Configuration

http

Type: object
Required: Yes
Description: HTTP server configuration including port and timeout settings.

Parameters:

port

Type: string
Required: Yes
Description: Port number on which the HTTP server listens.
Example: "8081", "8080"

timeout

Type: object
Required: Yes
Description: HTTP timeout configurations.

timeout.read

Type: integer (seconds)
Required: Yes
Default: 30
Description: Maximum duration for reading the entire request, including the body.

timeout.write

Type: integer (seconds)
Required: Yes
Default: 30
Description: Maximum duration before timing out writes of the response.

timeout.idle

Type: integer (seconds)
Required: Yes
Default: 30
Description: Maximum amount of time to wait for the next request when keep-alives are enabled.

Example:

http:
  port: 8081
  timeout:
    read: 30
    write: 30
    idle: 30

---

Logging Configuration

log

Type: object
Required: Yes
Description: Logging configuration for the application.

Parameters:

level

Type: string
Required: Yes
Options: debug, info, warn, error, fatal
Description: Sets the minimum log level. Messages below this level will not be logged.

destinations

Type: array
Required: Yes
Description: List of log output destinations.

destinations[].type

Type: string
Options: stdout, file
Description: Type of log destination.

contextKeys

Type: array of string
Required: No
Description: Context keys to include in structured logs for request tracing.
Common Values: transaction_id, message_id, subscriber_id, module_id

Example:

log:
  level: debug
  destinations:
    - type: stdout
  contextKeys:
    - transaction_id
    - message_id
    - subscriber_id
    - module_id

---

Application-Level Plugins Configuration

plugins

Type: object
Required: No
Description: Application-level plugin configurations. These plugins apply to the entire application and are shared across all modules.

plugins.otelsetup

Type: object
Required: No
Description: OpenTelemetry configuration controlling whether the Prometheus exporter is enabled.

Important: This block is optional—omit it to run without telemetry. When present, the /metrics endpoint is exposed on a separate port (configurable via metricsPort) only if enableMetrics: true.

Parameters:

id

Type: string
Required: Yes
Description: Plugin identifier. Must be "otelsetup".

config

Type: object
Required: Yes
Description: Plugin configuration parameters.

config.enableMetrics

Type: string (boolean)
Required: No
Default: "true"
Description: Enables metrics collection and the /metrics endpoint. Must be "true" or "false" as a string.

config.serviceName

Type: string
Required: No
Default: "beckn-onix"
Description: Sets the service.name resource attribute.

config.serviceVersion

Type: string
Required: No
Description: Sets the service.version resource attribute.

config.environment

Type: string
Required: No
Default: "development"
Description: Sets the deployment.environment attribute (e.g., development, staging, production).

config.metricsPort

Type: string
Required: No
Default: "9090"
Description: Port on which the metrics HTTP server will listen. The metrics endpoint is hosted on a separate server from the main application.

Example - Enable Metrics (matches config/local-simple.yaml):

plugins:
  otelsetup:
    id: otelsetup
    config:
      serviceName: "beckn-onix"
      serviceVersion: "1.0.0"
      enableMetrics: "true"
      environment: "development"
      metricsPort: "9090"

Accessing Metrics

When plugins.otelsetup.config.enableMetrics: "true", the metrics endpoint is hosted on a separate HTTP server. Scrape metrics at:

http://your-server:9090/metrics

Note: The metrics server runs on the port specified by config.metricsPort (default: 9090), which is separate from the main application port configured in http.port.

Metrics Collected

Metrics are organized by module for better maintainability and encapsulation:

OTel Setup (from otelsetup plugin)

• Prometheus exporter & /metrics endpoint on separate HTTP server
• Go runtime instrumentation (go_*), resource attributes, and meter provider wiring

Step Execution Metrics (from telemetry package)

• onix_step_executions_total, onix_step_execution_duration_seconds, onix_step_errors_total

Handler Metrics (from handler module)

• beckn_signature_validations_total - Signature validation attempts
• beckn_schema_validations_total - Schema validation attempts
• onix_routing_decisions_total - Routing decisions taken by handler

Cache Metrics (from cache plugin)

• onix_cache_operations_total, onix_cache_hits_total, onix_cache_misses_total

Plugin Metrics (from telemetry package)

• onix_plugin_execution_duration_seconds, onix_plugin_errors_total

Runtime Metrics

• Go runtime metrics (go_*) and Redis instrumentation via redisotel

Each metric includes consistent labels such as module, role, action, status, step, plugin_id, and schema_version to enable low-cardinality dashboards.

Note: Metric definitions are now located in their respective modules:

• OTel setup: pkg/plugin/implementation/otelsetup
• Step metrics: core/module/handler/step_metrics.go
• Handler metrics: core/module/handler/handlerMetrics.go
• Cache metrics: pkg/plugin/implementation/cache/cache_metrics.go
• Plugin metrics: pkg/telemetry/pluginMetrics.go

---

Plugin Manager Configuration

pluginManager

Type: object
Required: Yes
Description: Configuration for the plugin management system.

Parameters:

root

Type: string
Required: Yes
Description: Local directory path where plugin binaries (.so files) are stored.
Example: ./plugins, /app/plugins

remoteRoot

Type: string
Required: No
Description: Path to remote plugin bundle (typically in GCS or S3) for production deployments.
Example: /mnt/gcs/plugins/plugins_bundle.zip

Example:

pluginManager:
  root: ./plugins
  remoteRoot: /mnt/gcs/plugins/plugins_bundle.zip

---

Module Configuration

modules

Type: array
Required: Yes
Description: List of transaction processing modules. Each module represents an HTTP endpoint handler with its own configuration.

Module Types:

There are four main module types in Beckn-ONIX:

1. bapTxnReceiver: Receives callback responses at BAP from BPP
2. bapTxnCaller: Sends outgoing requests from BAP to BPP/Gateway
3. bppTxnReceiver: Receives incoming requests at BPP from BAP
4. bppTxnCaller: Sends callback responses from BPP to BAP

Parameters:

name

Type: string
Required: Yes
Description: Unique identifier for the module.
Example: bapTxnReceiver, bapTxnCaller, bppTxnReceiver, bppTxnCaller

path

Type: string
Required: Yes
Description: HTTP path prefix for this module's endpoints.
Example: /bap/receiver/, /bap/caller/, /bpp/receiver/, /bpp/caller/

handler

Type: object
Required: Yes
Description: Handler configuration for processing requests. See Handler Configuration.

Example:

modules:
  - name: bapTxnReceiver
    path: /bap/receiver/
    handler:
      type: std
      role: bap
      # ... handler configuration

---

Handler Configuration

handler

Type: object
Required: Yes
Description: Defines how requests are processed by a module.

Parameters:

type

Type: string
Required: Yes
Options: std (standard handler)
Description: Type of handler. Currently only std is supported.

role

Type: string
Required: Yes
Options: bap, bpp
Description: Role of this handler in the Beckn protocol.

subscriberId

Type: string
Required: No
Description: Subscriber ID for the participant. Used primarily for BPP modules.
Example: bpp1

httpClientConfig

Type: object
Required: Yes
Description: HTTP client configuration for outgoing requests.

maxIdleConns

Type: integer
Default: 1000
Description: Maximum number of idle connections across all hosts.

maxIdleConnsPerHost

Type: integer
Default: 200
Description: Maximum idle connections to keep per host.

idleConnTimeout

Type: duration
Default: 300s
Description: Maximum time an idle connection remains open.

responseHeaderTimeout

Type: duration
Default: 5s
Description: Time to wait for server response headers.

plugins

Type: object
Required: Yes
Description: Plugin configurations. See Plugin Configuration.

steps

Type: array of string
Required: Yes
Description: Ordered list of processing steps to execute for each request.
Common Steps:

• validateSign - Validate digital signature
• addRoute - Determine routing destination
• validateSchema - Validate against JSON schema
• sign - Sign outgoing request
• publish - Publish to message queue

Example:

handler:
  type: std
  role: bap
  httpClientConfig:
    maxIdleConns: 1000
    maxIdleConnsPerHost: 200
    idleConnTimeout: 300s
    responseHeaderTimeout: 5s
  plugins:
    # ... plugin configurations
  steps:
    - validateSign
    - addRoute
    - validateSchema

---

Plugin Configuration

Plugin Structure

Each plugin configuration follows this structure:

pluginName:
  id: plugin-identifier
  config:
    key1: value1
    key2: value2

Available Plugins

1. Registry Plugin

Purpose: Lookup participant information from Beckn registry.

Configuration:

registry:
  id: registry
  config:
    url: http://localhost:8080/reg
    retry_max: 3
    retry_wait_min: 100ms
    retry_wait_max: 500ms

Parameters:

• url: Registry endpoint URL
• retry_max: Maximum number of retry attempts
• retry_wait_min: Minimum wait time between retries
• retry_wait_max: Maximum wait time between retries

---

2. Dediregistry Plugin

Purpose: Lookup participant information from a Decentralized Discovery (DeDi) registry.

Configuration:

registry:
  id: dediregistry
  config:
    url: "https://dedi-wrapper.example.com/dedi"
    registryName: "subscribers.beckn.one"
    timeout: 30
    retry_max: 3
    retry_wait_min: 1s
    retry_wait_max: 5s

Parameters:

• url: DeDi wrapper API base URL (Required)
• registryName: Name of the registry (Required)
• timeout: Request timeout in seconds (Optional, default: client default)
• retry_max: Maximum number of retry attempts (Optional, default: 4)
• retry_wait_min: Minimum wait time between retries in duration format (Optional, default: 1s)
• retry_wait_max: Maximum wait time between retries in duration format (Optional, default: 30s)

---

3. Key Manager Plugin

Purpose: Manage cryptographic keys for signing and verification.

Vault-based Key Manager (Production)

keyManager:
  id: keymanager
  config:
    projectID: beckn-onix-local
    vaultAddr: http://localhost:8200
    kvVersion: v2
    mountPath: beckn

Parameters:

• projectID: GCP project ID or identifier
• vaultAddr: HashiCorp Vault address
• kvVersion: Vault KV secrets engine version (v1 or v2)
• mountPath: Vault mount path for secrets

Secrets Manager Key Manager (Production)

keyManager:
  id: secretskeymanager
  config:
    projectID: ${projectID}

Parameters:

• projectID: GCP project ID (supports environment variable substitution)

Simple Key Manager (Development)

keyManager:
  id: simplekeymanager
  config: {}

Parameters: None required. Uses embedded Ed25519 keys stored in the binary.

---

3. Cache Plugin

Purpose: Redis-based caching for responses.

cache:
  id: cache
  config:
    addr: localhost:6379

Or for production with Redis cluster:

cache:
  id: redis
  config:
    addr: 10.81.192.4:6379

Or with TLS enabled:

cache:
  id: cache
  config:
    addr: redis.example.com:6380
    use_tls: "true"

Parameters:

• addr: Redis server address and port
• use_tls: Enable TLS connection to Redis ("true" to enable, omit or any other value to disable). Default: disabled.

---

4. Schema Validator Plugin

Purpose: Validate requests/responses against JSON schemas.

schemaValidator:
  id: schemavalidator
  config:
    schemaDir: ./schemas

Parameters:

• schemaDir: Directory containing JSON schema files organized by domain and version

---

5. Schema2Validator Plugin

Purpose: Validate requests against OpenAPI 3.x specifications. Supports core protocol validation and optional extended validation for domain-specific objects with @context references.

schemaValidator:
  id: schemav2validator
  config:
    type: url
    location: https://raw.githubusercontent.com/beckn/protocol-specifications-new/refs/heads/draft/api-specs/beckn-protocol-api.yaml
    cacheTTL: "3600"
    extendedSchema_enabled: "true"
    extendedSchema_cacheTTL: "86400"
    extendedSchema_maxCacheSize: "100"
    extendedSchema_downloadTimeout: "30"
    extendedSchema_allowedDomains: "beckn.org,example.com"

Or for local files:

schemaValidator:
  id: schemav2validator
  config:
    type: file
    location: ./validation-scripts/l2-config/mobility_1.1.0_openapi_3.1.yaml
    cacheTTL: "3600"
    extendedSchema_enabled: "false"

Parameters:

• type: Source type - "url" for remote specs, "file" for local files
• location: URL or file path to OpenAPI 3.1 specification
• cacheTTL: Cache TTL in seconds before reloading spec (default: "3600")
• extendedSchema_enabled: Enable extended schema validation for @context objects (default: "false")
• extendedSchema_cacheTTL: Domain schema cache TTL in seconds (default: "86400")
• extendedSchema_maxCacheSize: Max cached schemas (default: "100")
• extendedSchema_downloadTimeout: Schema download timeout in seconds (default: "30")
• extendedSchema_allowedDomains: Comma-separated domain whitelist (empty = all allowed)

---

6. Sign Validator Plugin

Purpose: Validate Ed25519 digital signatures on incoming requests.

signValidator:
  id: signvalidator

Parameters: None required. Uses key manager for public key lookup.

---

7. Router Plugin

Purpose: Determine routing destination based on rules.

router:
  id: router
  config:
    routingConfig: ./config/local-routing.yaml

Or for production:

router:
  id: router
  config:
    routingConfigPath: /mnt/gcs/configs/bapTxnCaller-routing.yaml

Parameters:

• routingConfig or routingConfigPath: Path to routing rules YAML file

---

8. Signer Plugin

Purpose: Sign outgoing requests with Ed25519 signature.

signer:
  id: signer

Parameters: None required. Uses key manager for private key.

---

9. Publisher Plugin

Purpose: Publish messages to RabbitMQ or Pub/Sub for asynchronous processing.

publisher:
  id: publisher
  config:
    project: ${projectID}
    topic: bapNetworkReciever

Parameters:

• project: GCP project ID for Pub/Sub
• topic: Pub/Sub topic name

---

10. Middleware Plugin

Purpose: Request preprocessing like UUID generation and header manipulation.

middleware:
  - id: reqpreprocessor
    config:
      uuidKeys: transaction_id,message_id
      role: bap

Parameters:

• uuidKeys: Comma-separated list of fields to auto-generate UUIDs for if missing
• role: BAP or BPP role for request processing

---

11. Reqmapper Plugin

Purpose: Transform Beckn payloads between protocol versions or shapes using JSONata before the request continues through the handler. Mount it inside the middleware list wherever translation is required.

middleware:
  - id: reqmapper
    config:
      role: bap               # Use `bpp` when running inside a BPP handler
      mappingsFile: ./config/mappings.yaml

Parameters:

• role: Required. Determines which JSONata expression is evaluated (bapMappings or bppMappings) for the current action.
• mappingsFile: Required. Absolute or relative path to a YAML file that contains the JSONata expressions for every action.

Mapping file structure:

mappings:
  <action-name>:
    bapMappings: |
      # JSONata expression applied when `role: bap`
    bppMappings: |
      # JSONata expression applied when `role: bpp`

Each action entry is optional—if no mapping exists for the current action, the original request body is passed through unchanged. JSONata expressions receive the entire Beckn request as input ($) and must return the full payload that should replace it.

Sample mapping file:

mappings:
  search:
    bapMappings: |
      {
        "context": {
          "action": "discover",
          "version": "2.0.0",
          "domain": "beckn.one:retail",
          "bap_id": $.context.bap_id,
          "bap_uri": $.context.bap_uri,
          "transaction_id": $.context.transaction_id,
          "message_id": $.context.message_id,
          "timestamp": $.context.timestamp
        },
        "message": {
          "filters": $.message.intent.category ? {
            "type": "jsonpath",
            "expression": "$[?(@.category.code == '" & $.message.intent.category.descriptor.code & "')]"
          } : null
        }
      }
    bppMappings: |
      {
        "context": {
          "action": "search",
          "version": "1.1.0",
          "domain": "retail",
          "bap_id": $.context.bap_id,
          "bap_uri": $.context.bap_uri,
          "transaction_id": $.context.transaction_id,
          "message_id": $.context.message_id,
          "timestamp": $.context.timestamp
        },
        "message": {
          "intent": {
            "category": $.message.filters ? {
              "descriptor": {
                "code": $substringAfter($substringBefore($.message.filters.expression, "'"), "== '")
              }
            } : null
          }
        }
      }
  on_search:
    bapMappings: |
      {
        "context": $.context,
        "message": {
          "catalog": {
            "descriptor": $.message.catalogs[0]."beckn:descriptor" ? {
              "name": $.message.catalogs[0]."beckn:descriptor"."schema:name"
            } : null
          }
        }
      }
    bppMappings: |
      {
        "context": $.context,
        "message": {
          "catalogs": [{
            "@type": "beckn:Catalog",
            "beckn:items": $.message.catalog.providers[].items[].
              {
                "@type": "beckn:Item",
                "beckn:id": id
              }
          }]
        }
      }

The sample illustrates how a single mapping file can convert search requests and on_search responses between Beckn 1.1.0 (BAP) and Beckn 2.0.0 (BPP) payload shapes. You can define as many action entries as needed, and the plugin will compile and cache the JSONata expressions on startup.

---

Routing Configuration

Routing Rules File Structure

Routing configuration is stored in separate YAML files referenced by the router plugin.

routingRules:
  - domain: "retail:1.1.0"
    version: "1.1.0"
    targetType: "url"
    target:
      url: "http://localhost:9001/beckn"
      excludeAction: false
    endpoints:
      - search
      - select
      - init
      - confirm

Routing Rule Parameters

domain

Type: string
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:

# 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
Description: Protocol version for this domain

targetType

Type: string
Required: Yes
Options: url, bpp, bap, msgq
Description: Type of routing destination

Target Types Explained:

1. url: Route to a specific URL

   targetType: "url"
   target:
     url: "http://backend-service:3000/api"
     excludeAction: false  # If true, don't append endpoint to URL
   

2. bpp: Route to BPP specified in request's bpp_uri

   targetType: "bpp"
   target:
     url: "https://gateway.example.com"  # Optional fallback URL
   endpoints:
     - search
   

3. bap: Route to BAP specified in request's bap_uri

   targetType: "bap"
   endpoints:
     - on_search
     - on_select
   

4. msgq: Route to message queue (Pub/Sub)

   targetType: "msgq"
   target:
     topic_id: "search_requests"
   

target

Type: object
Required: Depends on targetType
Description: Target destination details

target.url

Type: string
Description: Target URL for url type, or fallback URL for bpp/bap types

target.excludeAction

Type: boolean
Default: false
Description: For url type, whether to exclude appending endpoint name to URL path

target.topic_id

Type: string
Description: Pub/Sub topic ID for msgq type

target.publisherId

Type: string
Description: Publisher ID for publisher type (deprecated in favor of msgq)

endpoints

Type: array of string
Required: Yes
Description: List of Beckn protocol endpoints this rule applies to

Common Endpoints:

• BAP Caller: search, select, init, confirm, status, track, cancel, update, rating, support
• BPP Caller: on_search, on_select, on_init, on_confirm, on_status, on_track, on_cancel, on_update, on_rating, on_support

Routing Configuration Examples

Example 1: Simple URL Routing

routingRules:
  - domain: "retail:1.1.0"
    version: "1.1.0"
    targetType: "url"
    target:
      url: "http://backend-service:3000/retail/v1"
    endpoints:
      - search
      - select
      - init

Behavior: All search, select, and init requests for retail:1.1.0 will be routed to:

• http://backend-service:3000/retail/v1/search
• http://backend-service:3000/retail/v1/select
• http://backend-service:3000/retail/v1/init

Example 2: BPP Dynamic Routing

routingRules:
  - domain: "ONDC:TRV10"
    version: "2.0.0"
    targetType: "bpp"
    target:
      url: "https://gateway.example.com"
    endpoints:
      - search
  
  - domain: "ONDC:TRV10"
    version: "2.0.0"
    targetType: "bpp"
    endpoints:
      - select
      - init
      - confirm

Behavior:

• For search: Route to gateway URL if bpp_uri is missing from request
• For other endpoints: Route to bpp_uri from request context (required)

Example 3: Mixed Routing

routingRules:
  - domain: "ONDC:TRV10"
    version: "2.0.0"
    targetType: "url"
    target:
      url: "https://services-backend/trv/v1"
    endpoints:
      - select
      - init
      - confirm

  - domain: "ONDC:TRV10"
    version: "2.0.0"
    targetType: "msgq"
    target:
      topic_id: "trv_search_requests"
    endpoints:
      - search

Behavior:

• select, init, confirm: Routed to backend URL
• search: Published to Pub/Sub topic for asynchronous processing

Example 4: URL with excludeAction

routingRules:
  - domain: "retail:1.1.0"
    version: "1.1.0"
    targetType: "url"
    target:
      url: "http://backend:3000/webhook"
      excludeAction: true
    endpoints:
      - search
      - select

Behavior: All endpoints route to exactly http://backend:3000/webhook without appending the endpoint name.

Example 5: Beckn Protocol v2 Domain-Agnostic Routing

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

# 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:

routingRules:
  - version: "2.0.0"
    targetType: "url"
    target:
      url: "https://unified-backend.com"
    endpoints:
      - search

---

Deployment Scenarios

1. Local Development (Simple Mode)

File: config/local-simple.yaml

Characteristics:

• Uses simplekeymanager (no Vault required)
• Embedded Ed25519 keys
• Local Redis
• Simplified routing
• Optional metrics collection (available on separate port when enabled)

Use Case: Quick local development and testing

appName: "onix-local"
log:
  level: debug
metrics:
  enabled: true
  exporterType: prometheus
  serviceName: onix-local
http:
  port: 8081
modules:
  - name: bapTxnReceiver
    handler:
      plugins:
        keyManager:
          id: simplekeymanager
          config: {}

Metrics Access: When enabled, access metrics at http://localhost:9090/metrics (default metrics port, configurable via plugins.otelsetup.config.metricsPort)

2. Local Development (Vault Mode)

File: config/local-dev.yaml

Characteristics:

• Uses keymanager with local Vault
• Full production-like setup
• Local Redis and Vault

Use Case: Testing with production key management

modules:
  - name: bapTxnReceiver
    handler:
      plugins:
        keyManager:
          id: keymanager
          config:
            projectID: beckn-onix-local
            vaultAddr: http://localhost:8200

3. Production Combined Mode

File: config/onix/adapter.yaml

Characteristics:

• Handles both BAP and BPP
• GCP Secrets Manager for keys
• Production Redis
• Remote plugin loading
• Pub/Sub integration
• OpenTelemetry metrics enabled (available on separate port, default: 9090)

Use Case: Single deployment serving both roles

appName: "onix-production"
log:
  level: info
  destinations:
    - type: stdout
metrics:
  enabled: true
  exporterType: prometheus
  serviceName: beckn-onix
  serviceVersion: "1.0.0"
pluginManager:
  root: /app/plugins
  remoteRoot: /mnt/gcs/plugins/plugins_bundle.zip
modules:
  - name: bapTxnReciever
    handler:
      plugins:
        keyManager:
          id: secretskeymanager
          config:
            projectID: ${projectID}
        cache:
          id: redis
          config:
            addr: 10.81.192.4:6379
        publisher:
          id: publisher
          config:
            project: ${projectID}
            topic: bapNetworkReciever

Metrics Access:

• Prometheus scraping: http://your-server:9090/metrics (default metrics port, configurable via plugins.otelsetup.config.metricsPort)

4. Production BAP-Only Mode

File: config/onix-bap/adapter.yaml

Characteristics:

• Only BAP modules (bapTxnReceiver, bapTxnCaller)
• Dedicated BAP deployment
• Production infrastructure

Use Case: Separate BAP service for scalability

5. Production BPP-Only Mode

File: config/onix-bpp/adapter.yaml

Characteristics:

• Only BPP modules (bppTxnReceiver, bppTxnCaller)
• Dedicated BPP deployment
• Production infrastructure

Use Case: Separate BPP service for scalability

---

Configuration Examples

Complete BAP Receiver Configuration

appName: "onix-bap"
log:
  level: info
  destinations:
    - type: stdout
  contextKeys:
    - transaction_id
    - message_id
    - subscriber_id

http:
  port: 8080
  timeout:
    read: 30
    write: 30
    idle: 30

pluginManager:
  root: /app/plugins

modules:
  - name: bapTxnReceiver
    path: /bap/receiver/
    handler:
      type: std
      role: bap
      httpClientConfig:
        maxIdleConns: 1000
        maxIdleConnsPerHost: 200
        idleConnTimeout: 300