487 lines
18 KiB
Markdown
487 lines
18 KiB
Markdown
# Beckn-ONIX
|
||
|
||
<div align="center">
|
||
|
||
[](https://golang.org)
|
||
[](LICENSE)
|
||
[](https://github.com/beckn/beckn-onix/actions)
|
||
[](https://codecov.io/gh/beckn/beckn-onix)
|
||
|
||
**A production-ready, plugin-based middleware adapter for the Beckn Protocol**
|
||
|
||
[Overview](#overview) • [Features](#features) • [Architecture](#architecture) • [Quick Start](#quick-start) • [Documentation](#documentation) • [Contributing](#contributing)
|
||
|
||
</div>
|
||
|
||
---
|
||
## Latest Update
|
||
In August 2025, a completely new Beckn-ONIX adapter was made available. This version introduces a Plugin framework at it's core.
|
||
The ONIX Adapter previous to this release is archived to a separate branch, [main-pre-plugins](https://github.com/beckn/beckn-onix/tree/main-pre-plugins) for reference.
|
||
|
||
## Overview
|
||
|
||
Beckn-ONIX is an enterprise-grade middleware adapter system designed to facilitate seamless communication in any Beckn-enabled network. It acts as a protocol adapter between Beckn Application Platforms (BAPs - buyer applications) and Beckn Provider Platforms (BPPs - seller platforms), ensuring secure, validated, and compliant message exchange across various commerce networks.
|
||
|
||
### What is Beckn Protocol?
|
||
|
||
The **Beckn Protocol** is an open protocol that enables location-aware, local commerce across any platform and any domain. It allows creation of open, decentralized networks where:
|
||
|
||
- **Platform Independence**: Buyers and sellers can transact regardless of the platforms they use
|
||
- **Interoperability**: Seamless communication between different systems using standardized protocols
|
||
- **Domain Agnostic**: Works across retail, mobility, healthcare, logistics, and other domains
|
||
- **Network Neutral**: Can be deployed in any Beckn-compliant network globally
|
||
|
||
### Key Concepts
|
||
|
||
- **BAP (Beckn Application Platform)**: Buyer-side applications that help users search for and purchase products/services (e.g., consumer apps, aggregators)
|
||
- **BPP (Beckn Provider Platform)**: Seller-side platforms that provide products/services (e.g., merchant platforms, service providers)
|
||
- **Beckn Network**: Any network implementing the Beckn Protocol for enabling open commerce
|
||
|
||
## Features
|
||
|
||
### 🔌 **Plugin-Based Architecture**
|
||
- **Dynamic Plugin Loading**: Load and configure plugins at runtime without code changes
|
||
- **Extensible Design**: Easy to add new functionality through custom plugins
|
||
- **Hot-Swappable Components**: Update plugins without application restart (in development)
|
||
|
||
### 🔐 **Enterprise Security**
|
||
- **Ed25519 Digital Signatures**: Cryptographically secure message signing and validation
|
||
- **HashiCorp Vault Integration**: Centralized secrets and key management
|
||
- **Request Authentication**: Every message is authenticated and validated
|
||
- **TLS/SSL Support**: Encrypted communication channels
|
||
|
||
### ✅ **Protocol Compliance**
|
||
- **JSON Schema Validation**: Ensures all messages comply with Beckn protocol specifications
|
||
- **Version Management**: Support for multiple protocol versions simultaneously
|
||
- **Domain-Specific Schemas**: Tailored validation for different business domains
|
||
|
||
### 🚀 **High Performance**
|
||
- **Redis Caching**: Response caching for improved performance
|
||
- **RabbitMQ Integration**: Asynchronous message processing via message queues
|
||
- **Connection Pooling**: Efficient resource utilization
|
||
- **Configurable Timeouts**: Fine-tuned performance controls
|
||
|
||
### 📊 **Observability**
|
||
- **Structured Logging**: JSON-formatted logs with contextual information
|
||
- **Transaction Tracking**: End-to-end request tracing with unique IDs
|
||
- **OpenTelemetry Metrics**: Pull-based metrics exposed via `/metrics`
|
||
- RED metrics for every module and action (rate, errors, duration)
|
||
- Per-step histograms with error attribution
|
||
- Cache, routing, plugin, and business KPIs (signature/schema validations, Beckn messages)
|
||
- Native Prometheus exporter with Grafana dashboards & alert rules (`monitoring/`)
|
||
- Opt-in: add a `plugins.otelsetup` block in your config to wire the `otelsetup` plugin; omit it to run without metrics. Example:
|
||
|
||
```yaml
|
||
plugins:
|
||
otelsetup:
|
||
id: otelsetup
|
||
config:
|
||
serviceName: "beckn-onix"
|
||
serviceVersion: "1.0.0"
|
||
enableMetrics: "true"
|
||
environment: "development"
|
||
```
|
||
- **Modular Metrics Architecture**: Metrics are organized by module for better maintainability:
|
||
- OTel SDK wiring via `otelsetup` plugin
|
||
- Step execution metrics in `telemetry` package
|
||
- Handler metrics (signature, schema, routing) in `handler` module
|
||
- Cache metrics in `cache` plugin
|
||
- **Runtime Instrumentation**: Go runtime + Redis client metrics baked in
|
||
- **Health Checks**: Liveness and readiness probes for Kubernetes
|
||
|
||
#### Monitoring Quick Start
|
||
```bash
|
||
./install/build-plugins.sh
|
||
go build -o beckn-adapter ./cmd/adapter
|
||
./beckn-adapter --config=config/local-simple.yaml
|
||
cd monitoring && docker-compose -f docker-compose-monitoring.yml up -d
|
||
open http://localhost:3000 # Grafana (admin/admin)
|
||
```
|
||
Resources:
|
||
- `monitoring/prometheus.yml` – scrape config
|
||
- `monitoring/prometheus-alerts.yml` – alert rules (RED, cache, step, plugin)
|
||
- `monitoring/grafana/dashboards/beckn-onix-overview.json` – curated dashboard
|
||
- `docs/METRICS_RUNBOOK.md` – runbook with PromQL recipes & troubleshooting
|
||
|
||
### 🌐 **Multi-Domain Support**
|
||
- **Retail & E-commerce**: Product search, order management, fulfillment tracking
|
||
- **Mobility Services**: Ride-hailing, public transport, vehicle rentals
|
||
- **Logistics**: Shipping, last-mile delivery, returns management
|
||
- **Healthcare**: Appointments, telemedicine, pharmacy services
|
||
- **Financial Services**: Loans, insurance, payments
|
||
|
||
## Architecture
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────┐
|
||
│ HTTP Request │
|
||
└────────────────────────┬────────────────────────────────┘
|
||
│
|
||
┌────────────────────────▼────────────────────────────────┐
|
||
│ Module Handler │
|
||
│ (bapTxnReceiver/Caller or bppTxnReceiver/Caller) │
|
||
└────────────────────────┬────────────────────────────────┘
|
||
│
|
||
┌────────────────────────▼────────────────────────────────┐
|
||
│ Processing Pipeline │
|
||
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
|
||
│ │ Middleware │→ │ Steps │→ │ Plugins │ │
|
||
│ │(preprocess) │ │(validate, │ │(cache,router│ │
|
||
│ └─────────────┘ │route, sign) │ │validator...)│ │
|
||
│ └─────────────┘ └─────────────┘ │
|
||
└────────────────────────┬────────────────────────────────┘
|
||
│
|
||
┌────────────────────────▼────────────────────────────────┐
|
||
│ External Services/Response │
|
||
└─────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
### Core Components
|
||
|
||
#### 1. **Transaction Modules**
|
||
- `bapTxnReceiver`: Receives callback responses at BAP
|
||
- `bapTxnCaller`: Sends requests from BAP to BPP
|
||
- `bppTxnReceiver`: Receives requests at BPP
|
||
- `bppTxnCaller`: Sends responses from BPP to BAP
|
||
|
||
#### 2. **Processing Steps**
|
||
- `validateSign`: Validates digital signatures on incoming requests
|
||
- `addRoute`: Determines routing based on configuration
|
||
- `validateSchema`: Validates against JSON schemas
|
||
- `sign`: Signs outgoing requests
|
||
- `cache`: Caches requests/responses
|
||
- `publish`: Publishes messages to queue
|
||
|
||
#### 3. **Plugin Types**
|
||
- **Cache**: Redis-based response caching
|
||
- **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
|
||
- **Schemav2Validator**: OpenAPI 3.x schema validation with action-based matching
|
||
- **KeyManager**: HashiCorp Vault integration for production key management
|
||
- **SimpleKeyManager**: Embedded key management for local development (no external dependencies)
|
||
- **Publisher**: RabbitMQ message publishing for asynchronous processing
|
||
- **Encrypter**: AES encryption for sensitive data protection
|
||
- **Decrypter**: AES decryption for encrypted data processing
|
||
- **ReqPreprocessor**: Request preprocessing (UUID generation, headers)
|
||
- **ReqMapper**: Middleware to transform payload either between Beckn versions or against other platforms.
|
||
- **Registry**: Standard Beckn registry or Beckn One DeDi registry lookup for participant information
|
||
|
||
## Quick Start
|
||
|
||
### Prerequisites
|
||
|
||
- Go 1.24 or higher
|
||
- Redis (for caching)
|
||
- Docker (optional, for containerized deployment)
|
||
|
||
### Build and Run
|
||
|
||
1. **Clone the repository**
|
||
```bash
|
||
git clone https://github.com/beckn/beckn-onix.git
|
||
cd beckn-onix
|
||
```
|
||
|
||
2. **Build the application**
|
||
```bash
|
||
go build -o server cmd/adapter/main.go
|
||
```
|
||
|
||
3. **Build plugins**
|
||
```bash
|
||
./install/build-plugins.sh
|
||
```
|
||
|
||
4. **Extract schemas**
|
||
```bash
|
||
unzip schemas.zip
|
||
```
|
||
|
||
5. **Start Redis** (if not running)
|
||
```bash
|
||
docker run -d -p 6379:6379 redis:alpine
|
||
```
|
||
|
||
6. **Update the config file**
|
||
|
||
**Note**: You can modify the configuration file to suit your environment before starting the server. ONIX adapter/server must be restarted to reflect any change made to the config file.
|
||
|
||
The following config change is required to all cache related entries in order to connect to `redis` that was started earlier.
|
||
```yaml
|
||
cache:
|
||
id: cache
|
||
config:
|
||
addr: localhost:6379
|
||
```
|
||
|
||
7. **Run the application**
|
||
|
||
```bash
|
||
./server --config=config/local-simple.yaml
|
||
```
|
||
|
||
The server will start on `http://localhost:8081`
|
||
|
||
### Automated Setup (Recommended)
|
||
|
||
For local setup, starts only redis and onix adapter:
|
||
|
||
```bash
|
||
# Clone and setup everything automatically
|
||
git clone https://github.com/beckn/beckn-onix.git
|
||
cd beckn-onix/install
|
||
chmod +x setup.sh
|
||
./setup.sh
|
||
```
|
||
|
||
This automated script will:
|
||
- Start Redis container
|
||
- Build all plugins with correct Go version
|
||
- Build the adapter server
|
||
- Start ONIX adapter in Docker
|
||
- Create environment configuration
|
||
|
||
**Note:**
|
||
- **Schema Validation**: Extract schemas before running: `unzip schemas.zip` (required for `schemavalidator` plugin)
|
||
- **Alternative**: You can use `schemav2validator` plugin instead, which fetches schemas from a URL and doesn't require local schema extraction. See [CONFIG.md](CONFIG.md) for more configuration details.
|
||
- **Optional**: Before running the automated setup, build the adapter image and update `docker-compose-adapter.yaml` to use the correct image
|
||
|
||
```bash
|
||
# from the repository root
|
||
docker build -f Dockerfile.adapter-with-plugins -t beckn-onix:latest .
|
||
```
|
||
|
||
**For detailed setup instructions, see [SETUP.md](SETUP.md)**
|
||
|
||
**Services Started:**
|
||
- Redis: localhost:6379
|
||
- ONIX Adapter: http://localhost:8081
|
||
|
||
### Docker Deployment
|
||
|
||
**Note:** Start redis before before running onix adapter.
|
||
|
||
```bash
|
||
# Build the Docker image
|
||
docker build -t beckn-onix:latest -f Dockerfile.adapter-with-plugins .
|
||
|
||
# Run the container
|
||
docker run -p 8081:8081 \
|
||
-v $(pwd)/config:/app/config \
|
||
-v $(pwd)/schemas:/app/schemas \
|
||
-e CONFIG_FILE="/app/config/local-simple.yaml" \
|
||
beckn-onix:latest
|
||
```
|
||
|
||
### Basic Usage Example
|
||
|
||
#### 1. Search for Products (BAP → BPP)
|
||
|
||
```bash
|
||
curl -X POST http://localhost:8081/bap/caller/search \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"context": {
|
||
"domain": "nic2004:60221",
|
||
"country": "IND",
|
||
"city": "std:080",
|
||
"action": "search",
|
||
"version": "0.9.4",
|
||
"bap_id": "bap.example.com",
|
||
"bap_uri": "https://bap.example.com/beckn",
|
||
"transaction_id": "550e8400-e29b-41d4-a716-446655440000",
|
||
"message_id": "550e8400-e29b-41d4-a716-446655440001",
|
||
"timestamp": "2023-06-15T09:30:00.000Z",
|
||
"ttl": "PT30S"
|
||
},
|
||
"message": {
|
||
"intent": {
|
||
"fulfillment": {
|
||
"start": {
|
||
"location": {
|
||
"gps": "12.9715987,77.5945627"
|
||
}
|
||
},
|
||
"end": {
|
||
"location": {
|
||
"gps": "12.9715987,77.5945627"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}'
|
||
```
|
||
|
||
## Configuration
|
||
|
||
### Configuration Structure
|
||
|
||
```yaml
|
||
appName: "beckn-onix"
|
||
log:
|
||
level: debug
|
||
destinations:
|
||
- type: stdout
|
||
http:
|
||
port: 8080
|
||
timeout:
|
||
read: 30
|
||
write: 30
|
||
idle: 30
|
||
pluginManager:
|
||
root: ./plugins
|
||
modules:
|
||
- name: bapTxnReceiver
|
||
path: /bap/receiver/
|
||
handler:
|
||
type: std
|
||
role: bap
|
||
plugins:
|
||
cache:
|
||
id: cache
|
||
config:
|
||
addr: localhost:6379
|
||
router:
|
||
id: router
|
||
config:
|
||
routingConfig: ./config/routing.yaml
|
||
schemaValidator:
|
||
id: schemavalidator # or schemav2validator
|
||
config:
|
||
schemaDir: ./schemas # for schemavalidator
|
||
# type: url # for schemav2validator
|
||
# location: https://example.com/spec.yaml
|
||
steps:
|
||
- validateSign
|
||
- addRoute
|
||
- validateSchema
|
||
```
|
||
|
||
### Deployment Modes
|
||
|
||
1. **Combined Mode**: Single instance handling both BAP and BPP (`config/onix/`) - Uses `secretskeymanager` (HashiCorp Vault) for production key management
|
||
2. **BAP-Only Mode**: Dedicated buyer-side deployment (`config/onix-bap/`)
|
||
3. **BPP-Only Mode**: Dedicated seller-side deployment (`config/onix-bpp/`)
|
||
4. **Local Development Combined Mode**: Simplified configuration (`config/local-simple.yaml`) - Uses `simplekeymanager` with embedded Ed25519 keys, no vault setup needed.
|
||
5. **Local Development Combined Mode (Alternative)**: Development configuration (`config/local-dev.yaml`) - Uses `keymanager` vault setup needed
|
||
|
||
## API Endpoints
|
||
|
||
### BAP Endpoints
|
||
|
||
| Method | Endpoint | Description |
|
||
|--------|----------|-------------|
|
||
| POST | `/bap/caller/search` | Search for products/services |
|
||
| POST | `/bap/caller/select` | Select specific items |
|
||
| POST | `/bap/caller/init` | Initialize order |
|
||
| POST | `/bap/caller/confirm` | Confirm order |
|
||
| POST | `/bap/caller/status` | Check order status |
|
||
| POST | `/bap/caller/track` | Track order/shipment |
|
||
| POST | `/bap/caller/cancel` | Cancel order |
|
||
| POST | `/bap/caller/update` | Update order |
|
||
| POST | `/bap/caller/rating` | Submit rating |
|
||
| POST | `/bap/caller/support` | Get support |
|
||
|
||
### BPP Endpoints
|
||
|
||
| Method | Endpoint | Description |
|
||
|--------|----------|-------------|
|
||
| POST | `/bpp/receiver/*` | Receives all BAP requests |
|
||
| POST | `/bpp/caller/on_*` | Sends responses back to BAP |
|
||
|
||
### Observability Endpoints
|
||
|
||
| Method | Endpoint | Description |
|
||
|--------|----------|-------------|
|
||
| GET | `/health` | Health check endpoint |
|
||
| GET | `/metrics` | Prometheus metrics endpoint (when telemetry is enabled) |
|
||
|
||
**Note**: The `/metrics` endpoint is available when `telemetry.enableMetrics: true` in the configuration file. It returns metrics in Prometheus format.
|
||
|
||
## Documentation
|
||
|
||
- **[Setup Guide](SETUP.md)**: Complete installation, configuration, and deployment instructions
|
||
- **[Configuration Guide](CONFIG.md)**: Description of Configuration concepts and all config parameters
|
||
- **[Contributing](CONTRIBUTING.md)**: Guidelines for contributors
|
||
- **[Governance](GOVERNANCE.md)**: Project governance model
|
||
- **[License](LICENSE)**: Apache 2.0 license details
|
||
|
||
## GUI Component
|
||
|
||
The project includes a Next.js-based GUI component located in `onix-gui/` that provides:
|
||
- Visual configuration management
|
||
- Request/response monitoring
|
||
- Plugin status dashboard
|
||
- Routing rules editor
|
||
|
||
## Testing
|
||
|
||
```bash
|
||
# Run all tests
|
||
go test ./...
|
||
|
||
# Run tests with coverage
|
||
go test -coverprofile=coverage.out ./...
|
||
go tool cover -html=coverage.out
|
||
|
||
# Run specific test
|
||
go test ./pkg/plugin/implementation/cache -v
|
||
|
||
# Run tests with race detection
|
||
go test -race ./...
|
||
```
|
||
|
||
## Contributing
|
||
|
||
We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details on:
|
||
- Code of Conduct
|
||
- Development process
|
||
- Submitting pull requests
|
||
- Reporting issues
|
||
|
||
## Support
|
||
|
||
- **Issues**: [GitHub Issues](https://github.com/beckn/beckn-onix/issues)
|
||
- **Discussions**: [GitHub Discussions](https://github.com/beckn/beckn-onix/discussions)
|
||
- **Documentation**: [Wiki](https://github.com/beckn/beckn-onix/wiki)
|
||
|
||
## License
|
||
|
||
This project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE) file for details.
|
||
|
||
## Acknowledgments
|
||
|
||
- [Beckn Foundation](https://beckn.org) for the protocol specifications
|
||
|
||
| Contributor | Organization | Github ID |
|
||
|--------|----------|-------------|
|
||
| Ashish Guliya | Google Cloud | ashishkgGoogle |
|
||
| Pooja Joshi | Google Cloud | poojajoshi2 |
|
||
| Deepa Mulchandani | Google Cloud | Deepa-Mulchandani |
|
||
| Ankit | FIDE | ankitShogun |
|
||
| Abhishek | FIDE | em-abee |
|
||
| Viraj Kulkarni | FIDE | viraj89 |
|
||
| Amay Pandey | Google Cloud | |
|
||
| Dipika Prasad | Google Cloud | DipikaPrasad |
|
||
| Tanya Madaan | ONDC | tanyamadaan |
|
||
| Binu | ONDC | |
|
||
| Faiz M | FIDE | faizmagic |
|
||
| Ravi Prakash | FIDE | ravi-prakash-v |
|
||
| Siddharth Prakash | Google Cloud | |
|
||
| Namya Patiyal | Google Cloud | |
|
||
| Saksham Nagpal | Google Cloud | sakshamGoogle |
|
||
| Arpit Bharadwaj | Google Cloud | |
|
||
| Pranoy | Google Cloud | |
|
||
| Mayuresh Nirhali | FIDE Volunteer | nirmay |
|
||
| Madhuvandhini B | Google Cloud | madhuvandhini5856 |
|
||
| Siddhartha Banerjee | Google Cloud | sidb85 |
|
||
|
||
---
|
||
|
||
<div align="center">
|
||
Built with ❤️ for the open Value Network ecosystem
|
||
</div>
|