diff --git a/Archive.zip b/Archive.zip deleted file mode 100644 index f054361..0000000 Binary files a/Archive.zip and /dev/null differ diff --git a/CLAUDE.md b/CLAUDE.md deleted file mode 100644 index cfbdf7a..0000000 --- a/CLAUDE.md +++ /dev/null @@ -1,201 +0,0 @@ -# CLAUDE.md - -This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. - -## Project Overview - -Beckn-ONIX is a middleware adapter system for the Beckn protocol, designed for any Beckn-enabled network. It acts as a bridge between BAP (Beckn Application Platform) and BPP (Beckn Provider Platform) systems, providing a plugin-based architecture for handling HTTP requests, routing, validation, signing, and integration with external services. - -## Technology Stack - -- **Language**: Go 1.23 (with Go 1.23.4 toolchain) -- **Architecture**: Plugin-based middleware system -- **Key Dependencies**: - - Redis (caching) - - RabbitMQ (messaging via amqp091-go) - - HashiCorp Vault (secrets management) - - JSON Schema validation (jsonschema/v6) -- **Containerization**: Docker with Dockerfile.adapter -- **Frontend**: Node.js-based GUI component (onix-gui/) - -## Build and Development Commands - -### Build locally -```bash -go build -o server cmd/adapter/main.go -``` - -### Run with configuration -```bash -./server --config=config/onix/adapter.yaml -``` - -### Docker build -```bash -docker build -f Dockerfile.adapter -t beckn-onix-adapter . -``` - -### Run tests -```bash -go test ./... -``` - -### Run specific test -```bash -go test ./pkg/plugin/implementation/cache -v -``` - -### Run tests with coverage -```bash -go test -coverprofile=coverage.out ./... -go tool cover -html=coverage.out # View coverage in browser -go tool cover -func=coverage.out # View coverage summary -``` - -### Run tests with race detection -```bash -go test -race ./... -``` - -### Format and lint code -```bash -go fmt ./... -go vet ./... -golangci-lint run # Requires golangci-lint installation -``` - -### Clean build artifacts -```bash -rm -f server -rm -rf plugins/*.so -``` - -### Module maintenance -```bash -go mod tidy # Clean up dependencies -go mod download # Download dependencies -go mod verify # Verify dependencies -``` - -### Local Development Setup - -For local development without Docker: - -1. **Build plugins** (required for the plugin-based architecture): -```bash -./build-plugins.sh -``` - -2. **Create required directories**: -```bash -mkdir -p schemas -``` - -3. **Run with local config**: -```bash -go run cmd/adapter/main.go --config=config/local-dev.yaml -``` - -Note: The application requires: -- Redis running on localhost:6379 for caching -- Plugins built as .so files in the ./plugins directory -- Schema files in ./schemas for validation (optional) -- HashiCorp Vault for key management (optional, can be disabled in config) - -## Architecture Overview - -### Core Components - -1. **cmd/adapter/main.go**: Main application entry point that: - - Loads YAML configuration - - Initializes plugin manager - - Sets up HTTP server with configurable timeouts - - Registers modules and their handlers - -2. **core/module/**: Core business logic and module system - - `module.go`: Module registration and management - - `handler/`: HTTP request handlers and processing steps - - `client/`: Client registry for external service connections - -3. **pkg/plugin/**: Extensible plugin system with: - - `definition/`: Plugin interfaces (cache, router, signer, validator, etc.) - - `implementation/`: Concrete implementations of each plugin type - - `manager.go`: Plugin lifecycle management - -### Plugin Types - -The system supports these plugin types: -- **cache**: Redis-based caching -- **router**: Request routing based on YAML configuration -- **signer/signvalidator**: Request signing and validation -- **schemavalidator**: JSON schema validation -- **keymanager**: HashiCorp Vault integration for secrets -- **publisher**: RabbitMQ message publishing -- **encrypter/decrypter**: AES encryption/decryption -- **reqpreprocessor**: Request preprocessing middleware (UUID generation, etc.) - -### Configuration Structure - -The system uses YAML configuration files in `config/` directory: -- `config/local-dev.yaml`: Simplified configuration for local development -- `config/local-routing.yaml`: Routing rules for local development -- `config/onix/`: Combined BAP+BPP configuration for production -- `config/onix-bap/`: BAP-only deployment configuration -- `config/onix-bpp/`: BPP-only deployment configuration - -Each configuration defines: -- HTTP server settings (port, timeouts) -- Plugin manager settings -- Modules with their handlers, plugins, and processing steps - -### Request Flow - -1. HTTP request received by server -2. Routed to appropriate module (bapTxnReceiver, bapTxnCaller, bppTxnReceiver, bppTxnCaller) -3. Processed through configured steps (validateSign, addRoute, validateSchema, sign) -4. Each step uses configured plugins to perform its function -5. Response returned or forwarded based on routing configuration - -## Module Types and Responsibilities - -- **bapTxnReceiver**: Receives incoming requests at BAP (buyer platform) -- **bapTxnCaller**: Makes outgoing calls from BAP to BPP -- **bppTxnReceiver**: Receives incoming requests at BPP (provider platform) -- **bppTxnCaller**: Makes outgoing calls from BPP to BAP - -## Module Configuration Patterns - -Modules follow this structure: -- **name**: Module identifier -- **path**: HTTP endpoint path -- **handler**: Processing configuration including: - - **role**: "bap" or "bpp" - - **plugins**: Plugin instances with their configurations - - **steps**: Ordered list of processing steps - -## Processing Steps - -Available processing steps that can be configured: -- **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 - -## Environment Variables - -The configuration supports environment variable substitution using `${variable}` syntax, commonly used for: -- `${projectID}`: GCP project ID for Vault and Pub/Sub -- Connection strings and service endpoints - -## Testing - -Tests are colocated with source files using `_test.go` suffix. Each plugin implementation has comprehensive test coverage including mock data in `testdata/` directories. - -## CI/CD Pipeline - -The project uses GitHub Actions for CI with the following checks: -- Unit tests with minimum 90% coverage requirement -- golangci-lint for code quality -- Coverage reports uploaded to Codecov \ No newline at end of file diff --git a/README.md b/README.md index b4c8b98..8b13789 100644 --- a/README.md +++ b/README.md @@ -1,353 +1 @@ -# Beckn-ONIX -
- -[![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 deleted file mode 100644 index a402531..0000000 --- a/SETUP.md +++ /dev/null @@ -1,1802 +0,0 @@ -# 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 deleted file mode 100755 index ada7ad2..0000000 --- a/build-plugins.sh +++ /dev/null @@ -1,32 +0,0 @@ -#!/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