From 8dc4c93a1429dd67edb13af59c13a3a14ef328a0 Mon Sep 17 00:00:00 2001 From: Abhijeet Singh Rathor Date: Wed, 13 Aug 2025 13:43:57 +0530 Subject: [PATCH] docs:added readme and setup files --- Archive.zip | Bin 0 -> 8020 bytes CLAUDE.md | 201 ++++++ README.md | 352 +++++++++ SETUP.md | 1802 ++++++++++++++++++++++++++++++++++++++++++++++ build-plugins.sh | 32 + 5 files changed, 2387 insertions(+) create mode 100644 Archive.zip create mode 100644 CLAUDE.md create mode 100644 SETUP.md create mode 100755 build-plugins.sh diff --git a/Archive.zip b/Archive.zip new file mode 100644 index 0000000000000000000000000000000000000000..f0543614a92e96396182c79f92deb7bf62b4dfec GIT binary patch literal 8020 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 + +[![Go Version](https://img.shields.io/badge/Go-1.23-blue.svg)](https://golang.org) +[![License](https://img.shields.io/badge/License-Apache%202.0-green.svg)](LICENSE) +[![CI Status](https://img.shields.io/github/actions/workflow/status/beckn/beckn-onix/ci.yml)](https://github.com/beckn/beckn-onix/actions) +[![Coverage](https://img.shields.io/badge/Coverage-90%25-brightgreen.svg)](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) + + + +--- + +## 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 +- **Metrics Support**: Performance and business metrics collection +- **Health Checks**: Liveness and readiness probes for Kubernetes + +### 🌐 **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 +- **Signer/SignValidator**: Ed25519 signature handling +- **SchemaValidator**: JSON schema validation +- **KeyManager**: HashiCorp Vault integration +- **Publisher**: RabbitMQ message publishing +- **Encrypter/Decrypter**: AES encryption/decryption +- **ReqPreprocessor**: Request preprocessing (UUID generation, headers) + +## Quick Start + +### Prerequisites + +- Go 1.23 or higher +- Redis (for caching) +- Docker (optional, for containerized deployment) +- HashiCorp Vault (optional, for production key management) +- RabbitMQ (optional, for async messaging) + +### Installation + +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 +./build-plugins.sh +``` + +4. **Start Redis** (if not running) +```bash +docker run -d -p 6379:6379 redis:alpine +``` + +5. **Run the application** +```bash +./server --config=config/local-dev.yaml +``` + +The server will start on `http://localhost:8081` + +### Docker Deployment + +```bash +# Build the Docker image +docker build -f Dockerfile.adapter -t beckn-onix:latest . + +# Run the container +docker run -p 8080:8080 \ + -v $(pwd)/config:/app/config \ + -v $(pwd)/schemas:/app/schemas \ + 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" \ + -H "Authorization: Signature keyId=\"bap.example.com|key1|ed25519\",algorithm=\"ed25519\",created=\"1234567890\",expires=\"1234567990\",headers=\"(created) (expires) digest\",signature=\"base64signature\"" \ + -d '{ + "context": { + "domain": "nic2004:60221", + "country": "IND", + "city": "std:080", + "action": "search", + "core_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 + config: + schemaDir: ./schemas + steps: + - validateSign + - addRoute + - validateSchema +``` + +### Deployment Modes + +1. **Combined Mode**: Single instance handling both BAP and BPP (`config/onix/`) +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**: Simplified configuration (`config/local-dev.yaml`) + +## 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 | + +## Documentation + +- **[Setup Guide](SETUP.md)**: Complete installation, configuration, and deployment instructions +- **[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 +- All contributors and community members + +--- + +
+Built with ❤️ for the open commerce ecosystem +
\ No newline at end of file diff --git a/SETUP.md b/SETUP.md new file mode 100644 index 0000000..a402531 --- /dev/null +++ b/SETUP.md @@ -0,0 +1,1802 @@ +# Beckn-ONIX Setup Guide + +This comprehensive guide walks you through setting up Beckn-ONIX from development to production deployment. + +## Table of Contents + +1. [Prerequisites](#prerequisites) +2. [Development Setup](#development-setup) +3. [Production Setup](#production-setup) +4. [Configuration Guide](#configuration-guide) +5. [External Services Setup](#external-services-setup) +6. [GUI Component Setup](#gui-component-setup) +7. [Docker Deployment](#docker-deployment) +8. [Kubernetes Deployment](#kubernetes-deployment) +9. [Testing Your Setup](#testing-your-setup) +10. [Troubleshooting](#troubleshooting) +11. [Sample Payloads](#sample-payloads) + +--- + +## Prerequisites + +### System Requirements + +- **Operating System**: Linux, macOS, or Windows (with WSL2) +- **CPU**: 2+ cores recommended +- **RAM**: 4GB minimum, 8GB recommended +- **Disk Space**: 2GB free space + +### Software Requirements + +#### Required +- **Go 1.23+**: [Download Go](https://golang.org/dl/) +- **Git**: [Download Git](https://git-scm.com/downloads) +- **Redis 6.0+**: For caching functionality + +#### Optional (for production) +- **Docker 20.10+**: For containerized deployment +- **HashiCorp Vault 1.12+**: For secrets management +- **RabbitMQ 3.10+**: For async messaging +- **Kubernetes 1.25+**: For orchestrated deployment + +### Verify Installation + +```bash +# Check Go version +go version +# Expected: go version go1.23.x + +# Check Git +git --version + +# Check Docker (optional) +docker --version + +# Check Redis +redis-cli --version +``` + +--- + +## Development Setup + +### Step 1: Clone the Repository + +```bash +git clone https://github.com/beckn/beckn-onix.git +cd beckn-onix +``` + +### Step 2: Install Dependencies + +```bash +# Download Go dependencies +go mod download + +# Verify dependencies +go mod verify +``` + +### Step 3: Build the Application + +```bash +# Build the main server binary +go build -o server cmd/adapter/main.go + +# Make it executable +chmod +x server +``` + +### Step 4: Build Plugins + +The application uses a plugin architecture. Build all plugins: + +```bash +# Make the build script executable +chmod +x build-plugins.sh + +# Build all plugins +./build-plugins.sh +``` + +This creates `.so` files in the `plugins/` directory: +- `cache.so` - Redis caching +- `router.so` - Request routing +- `signer.so` - Message signing +- `signvalidator.so` - Signature validation +- `schemavalidator.so` - JSON schema validation +- `keymanager.so` - Vault integration +- `publisher.so` - RabbitMQ publishing +- `encrypter.so` / `decrypter.so` - Encryption/decryption +- `reqpreprocessor.so` - Request preprocessing + +### Step 5: Setup Redis (Local) + +#### Option A: Using Docker +```bash +docker run -d \ + --name redis-onix \ + -p 6379:6379 \ + redis:alpine +``` + +#### Option B: Native Installation + +**macOS:** +```bash +brew install redis +brew services start redis +``` + +**Ubuntu/Debian:** +```bash +sudo apt update +sudo apt install redis-server +sudo systemctl start redis-server +sudo systemctl enable redis-server +``` + +**Verify Redis:** +```bash +redis-cli ping +# Expected: PONG +``` + +### Step 6: Create Required Directories + +```bash +# Create schemas directory for validation +mkdir -p schemas + +# Create logs directory (optional) +mkdir -p logs +``` + +### Step 7: Configure for Local Development + +Create or modify `config/local-dev.yaml`: + +```yaml +appName: "onix-local" +log: + level: debug + destinations: + - type: stdout + contextKeys: + - transaction_id + - message_id + - subscriber_id + - module_id +http: + port: 8081 + timeout: + read: 30 + write: 30 + idle: 30 +pluginManager: + root: ./plugins +modules: + - name: bapTxnReceiver + path: /bap/receiver/ + handler: + type: std + role: bap + registryUrl: http://localhost:8080/reg + plugins: + cache: + id: cache + config: + addr: localhost:6379 + schemaValidator: + id: schemavalidator + config: + schemaDir: ./schemas + signValidator: + id: signvalidator + router: + id: router + config: + routingConfig: ./config/local-routing.yaml + middleware: + - id: reqpreprocessor + config: + uuidKeys: transaction_id,message_id + role: bap + steps: + - addRoute + - validateSchema + + - name: bapTxnCaller + path: /bap/caller/ + handler: + type: std + role: bap + registryUrl: http://localhost:8080/reg + plugins: + cache: + id: cache + config: + addr: localhost:6379 + router: + id: router + config: + routingConfig: ./config/local-routing.yaml + signer: + id: signer + middleware: + - id: reqpreprocessor + config: + uuidKeys: transaction_id,message_id + role: bap + steps: + - addRoute + - sign + + - name: bppTxnReceiver + path: /bpp/receiver/ + handler: + type: std + role: bpp + registryUrl: http://localhost:8080/reg + plugins: + cache: + id: cache + config: + addr: localhost:6379 + schemaValidator: + id: schemavalidator + config: + schemaDir: ./schemas + signValidator: + id: signvalidator + router: + id: router + config: + routingConfig: ./config/local-routing.yaml + steps: + - validateSign + - addRoute + - validateSchema + + - name: bppTxnCaller + path: /bpp/caller/ + handler: + type: std + role: bpp + registryUrl: http://localhost:8080/reg + plugins: + cache: + id: cache + config: + addr: localhost:6379 + router: + id: router + config: + routingConfig: ./config/local-routing.yaml + signer: + id: signer + steps: + - addRoute + - sign +``` + +### Step 8: Create Routing Configuration + +Create `config/local-routing.yaml`: + +```yaml +routingRules: + - domain: "nic2004:60221" # Mobility domain + version: "0.9.4" + targetType: "url" + target: + url: "http://localhost:9001/beckn" + endpoints: + - search + - select + - init + - confirm + - status + - track + - cancel + - update + - rating + - support + + - domain: "nic2004:52110" # Retail domain + version: "1.0.0" + targetType: "url" + target: + url: "http://localhost:9002/beckn" + endpoints: + - search + - select + - init + - confirm + - status + - track + - cancel + - update + - rating + - support +``` + +### Step 9: Run the Application + +```bash +# Run with local configuration +./server --config=config/local-dev.yaml + +# Or using go run +go run cmd/adapter/main.go --config=config/local-dev.yaml +``` + +The server will start on `http://localhost:8081` + +### Step 10: Verify Setup + +```bash +# Check health endpoint +curl http://localhost:8081/health + +# Check if modules are loaded +curl http://localhost:8081/bap/receiver/ +# Expected: 404 with proper error (means module is loaded) +``` + +--- + +## Production Setup + +### Additional Requirements for Production + +1. **HashiCorp Vault** for key management +2. **RabbitMQ** for message queuing +3. **TLS certificates** for secure communication +4. **Load balancer** for high availability + +### Step 1: Setup HashiCorp Vault + +#### Install Vault +```bash +# Download and install +wget https://releases.hashicorp.com/vault/1.15.0/vault_1.15.0_linux_amd64.zip +unzip vault_1.15.0_linux_amd64.zip +sudo mv vault /usr/local/bin/ +``` + +#### Configure Vault +```bash +# Start Vault in dev mode (for testing only) +vault server -dev -dev-root-token-id="root" + +# In production, use proper configuration +cat > vault-config.hcl < + +# Or use different port in config +``` + +#### 6. Vault Authentication Issues + +**Error**: `vault: authentication failed` + +**Solution**: +```bash +# Check Vault status +vault status + +# Verify authentication +vault login -method=approle \ + role_id=${VAULT_ROLE_ID} \ + secret_id=${VAULT_SECRET_ID} + +# Check policy permissions +vault policy read beckn-policy +``` + +### Debug Mode + +Enable debug logging: + +```yaml +log: + level: debug + destinations: + - type: stdout + config: + pretty: true + includeCalller: true +``` + +Or via environment variable: +```bash +LOG_LEVEL=debug ./server --config=config/adapter.yaml +``` + +### Performance Tuning + +#### System Limits +```bash +# Increase file descriptors +ulimit -n 65536 + +# Add to /etc/security/limits.conf +beckn soft nofile 65536 +beckn hard nofile 65536 +``` + +#### Go Runtime +```bash +# Set GOMAXPROCS +export GOMAXPROCS=8 + +# Enable profiling +./server --config=config/adapter.yaml --profile +``` + +#### Redis Optimization +```bash +# Redis configuration +redis-cli CONFIG SET maxclients 10000 +redis-cli CONFIG SET tcp-keepalive 60 +redis-cli CONFIG SET timeout 300 +``` + +--- + +## Sample Payloads + +### Search Request (Retail) + +```json +{ + "context": { + "domain": "nic2004:52110", + "country": "IND", + "city": "std:080", + "action": "search", + "core_version": "1.0.0", + "bap_id": "buyerapp.com", + "bap_uri": "https://buyerapp.com/beckn", + "transaction_id": "6d5f4c3b-2a1e-4b8c-9f7d-3e2a1b5c8d9f", + "message_id": "a9f8e7d6-c5b4-3a2e-1f0d-9e8c7b6a5d4f", + "timestamp": "2024-01-15T10:30:00.000Z", + "ttl": "PT30S" + }, + "message": { + "intent": { + "item": { + "descriptor": { + "name": "Laptop" + } + }, + "fulfillment": { + "type": "Delivery", + "end": { + "location": { + "gps": "12.9715987,77.5945627", + "area_code": "560001" + } + } + }, + "payment": { + "buyer_app_finder_fee_type": "percent", + "buyer_app_finder_fee_amount": "3" + } + } + } +} +``` + +### Select Request + +```json +{ + "context": { + "domain": "nic2004:52110", + "country": "IND", + "city": "std:080", + "action": "select", + "core_version": "1.0.0", + "bap_id": "buyerapp.com", + "bap_uri": "https://buyerapp.com/beckn", + "bpp_id": "sellerapp.com", + "bpp_uri": "https://sellerapp.com/beckn", + "transaction_id": "6d5f4c3b-2a1e-4b8c-9f7d-3e2a1b5c8d9f", + "message_id": "b8e7f6d5-c4a3-2b1e-0f9d-8e7c6b5a4d3f", + "timestamp": "2024-01-15T10:31:00.000Z", + "ttl": "PT30S" + }, + "message": { + "order": { + "provider": { + "id": "P1", + "locations": [ + { + "id": "L1" + } + ] + }, + "items": [ + { + "id": "I1", + "quantity": { + "count": 2 + } + } + ], + "fulfillment": { + "end": { + "location": { + "gps": "12.9715987,77.5945627", + "address": { + "door": "21A", + "name": "ABC Apartments", + "building": "Tower 1", + "street": "100 Feet Road", + "locality": "Indiranagar", + "city": "Bengaluru", + "state": "Karnataka", + "country": "India", + "area_code": "560001" + } + }, + "contact": { + "phone": "9876543210", + "email": "customer@example.com" + } + } + } + } + } +} +``` + +### Init Request + +```json +{ + "context": { + "domain": "nic2004:52110", + "country": "IND", + "city": "std:080", + "action": "init", + "core_version": "1.0.0", + "bap_id": "buyerapp.com", + "bap_uri": "https://buyerapp.com/beckn", + "bpp_id": "sellerapp.com", + "bpp_uri": "https://sellerapp.com/beckn", + "transaction_id": "6d5f4c3b-2a1e-4b8c-9f7d-3e2a1b5c8d9f", + "message_id": "c7f6e5d4-b3a2-1e0f-9d8e-7c6b5a4d3e2f", + "timestamp": "2024-01-15T10:32:00.000Z", + "ttl": "PT30S" + }, + "message": { + "order": { + "provider": { + "id": "P1", + "locations": [ + { + "id": "L1" + } + ] + }, + "items": [ + { + "id": "I1", + "quantity": { + "count": 2 + }, + "fulfillment_id": "F1" + } + ], + "billing": { + "name": "John Doe", + "address": { + "door": "21A", + "name": "ABC Apartments", + "building": "Tower 1", + "street": "100 Feet Road", + "locality": "Indiranagar", + "city": "Bengaluru", + "state": "Karnataka", + "country": "India", + "area_code": "560001" + }, + "email": "john.doe@example.com", + "phone": "9876543210", + "created_at": "2024-01-15T10:32:00.000Z", + "updated_at": "2024-01-15T10:32:00.000Z" + }, + "fulfillment": { + "id": "F1", + "type": "Delivery", + "tracking": false, + "end": { + "location": { + "gps": "12.9715987,77.5945627", + "address": { + "door": "21A", + "name": "ABC Apartments", + "building": "Tower 1", + "street": "100 Feet Road", + "locality": "Indiranagar", + "city": "Bengaluru", + "state": "Karnataka", + "country": "India", + "area_code": "560001" + } + }, + "contact": { + "phone": "9876543210", + "email": "customer@example.com" + } + } + }, + "payment": { + "type": "ON-ORDER", + "collected_by": "BAP", + "buyer_app_finder_fee_type": "percent", + "buyer_app_finder_fee_amount": "3", + "settlement_details": [ + { + "settlement_counterparty": "seller-app", + "settlement_phase": "sale-amount", + "settlement_type": "neft", + "settlement_bank_account_no": "1234567890", + "settlement_ifsc_code": "SBIN0001234", + "beneficiary_name": "Seller Name", + "bank_name": "State Bank of India", + "branch_name": "Koramangala" + } + ] + } + } + } +} +``` + +### Confirm Request + +```json +{ + "context": { + "domain": "nic2004:52110", + "country": "IND", + "city": "std:080", + "action": "confirm", + "core_version": "1.0.0", + "bap_id": "buyerapp.com", + "bap_uri": "https://buyerapp.com/beckn", + "bpp_id": "sellerapp.com", + "bpp_uri": "https://sellerapp.com/beckn", + "transaction_id": "6d5f4c3b-2a1e-4b8c-9f7d-3e2a1b5c8d9f", + "message_id": "d8f7e6d5-c4b3-2a1e-0f9d-8e7c6b5a4d3f", + "timestamp": "2024-01-15T10:33:00.000Z", + "ttl": "PT30S" + }, + "message": { + "order": { + "id": "ORDER123", + "state": "Created", + "provider": { + "id": "P1", + "locations": [ + { + "id": "L1" + } + ] + }, + "items": [ + { + "id": "I1", + "fulfillment_id": "F1", + "quantity": { + "count": 2 + } + } + ], + "quote": { + "price": { + "currency": "INR", + "value": "4000" + }, + "breakup": [ + { + "item_id": "I1", + "item_quantity": { + "count": 2 + }, + "title_type": "item", + "title": "Laptop", + "price": { + "currency": "INR", + "value": "3800" + } + }, + { + "item_id": "F1", + "title_type": "delivery", + "title": "Delivery charges", + "price": { + "currency": "INR", + "value": "100" + } + }, + { + "item_id": "F1", + "title_type": "packing", + "title": "Packing charges", + "price": { + "currency": "INR", + "value": "50" + } + }, + { + "item_id": "I1", + "title_type": "tax", + "title": "Tax", + "price": { + "currency": "INR", + "value": "50" + } + } + ], + "ttl": "P1D" + }, + "payment": { + "uri": "https://ondc.transaction.com/payment", + "tl_method": "http/get", + "params": { + "transaction_id": "TXN123456", + "amount": "4000", + "currency": "INR" + }, + "type": "ON-ORDER", + "status": "PAID", + "collected_by": "BAP", + "buyer_app_finder_fee_type": "percent", + "buyer_app_finder_fee_amount": "3", + "settlement_details": [ + { + "settlement_counterparty": "seller-app", + "settlement_phase": "sale-amount", + "settlement_type": "neft", + "settlement_bank_account_no": "1234567890", + "settlement_ifsc_code": "SBIN0001234", + "beneficiary_name": "Seller Name", + "bank_name": "State Bank of India", + "branch_name": "Koramangala" + } + ] + }, + "fulfillment": { + "id": "F1", + "type": "Delivery", + "tracking": true, + "start": { + "location": { + "id": "L1", + "descriptor": { + "name": "Seller Store" + }, + "gps": "12.9715987,77.5945627", + "address": { + "locality": "Koramangala", + "city": "Bengaluru", + "area_code": "560034", + "state": "Karnataka" + } + }, + "time": { + "range": { + "start": "2024-01-15T11:00:00.000Z", + "end": "2024-01-15T12:00:00.000Z" + } + }, + "contact": { + "phone": "9988776655", + "email": "seller@example.com" + } + }, + "end": { + "location": { + "gps": "12.9715987,77.5945627", + "address": { + "door": "21A", + "name": "ABC Apartments", + "building": "Tower 1", + "street": "100 Feet Road", + "locality": "Indiranagar", + "city": "Bengaluru", + "state": "Karnataka", + "country": "India", + "area_code": "560001" + } + }, + "time": { + "range": { + "start": "2024-01-15T14:00:00.000Z", + "end": "2024-01-15T18:00:00.000Z" + } + }, + "person": { + "name": "John Doe" + }, + "contact": { + "phone": "9876543210", + "email": "customer@example.com" + } + } + }, + "created_at": "2024-01-15T10:33:00.000Z", + "updated_at": "2024-01-15T10:33:00.000Z" + } + } +} +``` + +### Authorization Header Structure + +All requests must include proper authorization: + +``` +Authorization: Signature keyId="{subscriber_id}|{key_id}|{algorithm}",algorithm="{algorithm}",created="{created}",expires="{expires}",headers="(created) (expires) digest",signature="{base64_signature}" +``` + +Example generation in bash: +```bash +#!/bin/bash + +# Variables +SUBSCRIBER_ID="buyerapp.com" +KEY_ID="key1" +ALGORITHM="ed25519" +CREATED=$(date +%s) +EXPIRES=$((CREATED + 300)) +PRIVATE_KEY="path/to/private_key.pem" + +# Create string to sign +STRING_TO_SIGN="(created): ${CREATED} +(expires): ${EXPIRES} +digest: SHA-256=${DIGEST}" + +# Sign with Ed25519 +SIGNATURE=$(echo -n "$STRING_TO_SIGN" | \ + openssl pkeyutl -sign -inkey $PRIVATE_KEY -rawin | \ + base64 -w 0) + +# Create header +AUTH_HEADER="Signature keyId=\"${SUBSCRIBER_ID}|${KEY_ID}|${ALGORITHM}\",algorithm=\"${ALGORITHM}\",created=\"${CREATED}\",expires=\"${EXPIRES}\",headers=\"(created) (expires) digest\",signature=\"${SIGNATURE}\"" + +echo $AUTH_HEADER +``` + +--- + +## Conclusion + +This setup guide covers all aspects of deploying Beckn-ONIX from local development to production. Key points: + +1. **Start Simple**: Begin with local development setup +2. **Test Thoroughly**: Use provided test scripts and payloads +3. **Scale Gradually**: Move from single instance to clustered deployment +4. **Monitor Continuously**: Use logs and metrics for observability +5. **Secure Always**: Implement proper authentication and encryption + +For additional help: +- Check [GitHub Issues](https://github.com/beckn/beckn-onix/issues) +- Join [Community Discussions](https://github.com/beckn/beckn-onix/discussions) +- Review [API Documentation](https://docs.beckn.org) + +Happy deploying! 🚀 \ No newline at end of file diff --git a/build-plugins.sh b/build-plugins.sh new file mode 100755 index 0000000..ada7ad2 --- /dev/null +++ b/build-plugins.sh @@ -0,0 +1,32 @@ +#!/bin/bash + +# Create plugins directory +mkdir -p plugins + +# Build each plugin as a shared library +echo "Building plugins..." + +plugins=( + "cache" + "decrypter" + "encrypter" + "keymanager" + "publisher" + "reqpreprocessor" + "router" + "schemavalidator" + "signer" + "signvalidator" +) + +for plugin in "${plugins[@]}"; do + echo "Building $plugin plugin..." + go build -buildmode=plugin -o "plugins/${plugin}.so" "./pkg/plugin/implementation/${plugin}/cmd/plugin.go" + if [ $? -eq 0 ]; then + echo "✓ Successfully built $plugin plugin" + else + echo "✗ Failed to build $plugin plugin" + fi +done + +echo "All plugins built in ./plugins directory" \ No newline at end of file