@x12i/xronox-router

@x12i/xronox-router

Request routing and tenant resolution for Xronox with dynamic provisioning support.

Env-Ready Component (ERC 2.0)

This component supports zero-config initialization via environment variables using @x12i/env.

Quick Start

# 1. Install the package
npm install @x12i/xronox-router

# 2. Copy .env.example to .env (if using zero-config mode)
cp node_modules/@x12i/xronox-router/.env.example .env

# 3. Fill in required values in .env
# MONGO_URI=mongodb://localhost:27017
# S3_ENDPOINT=http://localhost:9000
# S3_REGION=us-east-1
# S3_ACCESS_KEY=your-access-key
# S3_SECRET_KEY=your-secret-key

# 4. Use with zero config!
import { BridgeRouter } from '@x12i/xronox-router';
const router = new BridgeRouter(); // Auto-discovers from process.env

Configuration Priority

The router supports 3-tier configuration priority:

1. Tier 1: Explicit Config (Advanced Mode) - Pass configuration directly to constructor

   const router = new BridgeRouter({
     dbConnections: { primary: { mongoUri: 'mongodb://...' } },
     spacesConnections: { s3: { /* ... */ } },
     databases: { /* ... */ }
   });

2. Tier 2: Config File - Place xronox.config.json in your project root

   {
     "xronox": {
       "dbConnections": {
         "primary": {
           "mongoUri": "ENV.MONGO_URI"
         }
       },
       "spacesConnections": {
         "s3-primary": {
           "endpoint": "ENV.S3_ENDPOINT",
           "region": "ENV.S3_REGION",
           "accessKey": "ENV.S3_ACCESS_KEY",
           "secretKey": "ENV.S3_SECRET_KEY"
         }
       },
       "databases": { /* ... */ }
     }
   }

   Location: xronox.config.json in project root (same directory as package.json)

3. Tier 3: Environment Variables (Zero-Config Mode) - Auto-discover from .env file

   const router = new BridgeRouter(); // Uses environment variables

Advanced Mode (Programmatic Configuration)

import { BridgeRouter } from '@x12i/xronox-router';

const router = new BridgeRouter({
  dbConnections: { 
    primary: { mongoUri: 'mongodb://localhost:27017' } 
  },
  spacesConnections: { 
    s3: { 
      endpoint: 'http://localhost:9000',
      region: 'us-east-1',
      accessKey: 'minioadmin',
      secretKey: 'minioadmin'
    } 
  },
  databases: {
    metadata: {
      genericDatabase: {
        dbConnRef: 'primary',
        spaceConnRef: 's3',
        dbName: 'athenix_metadata',
        recordsBucket: 'metadata-records'
      },
      domainsDatabases: [],
      tenantDatabases: []
    }
  },
  hashAlgo: 'rendezvous'
});

const backend = router.route(ctx);
console.log(`Routed to: ${backend.mongoUri}`);

Features

• Consistent hashing (Rendezvous/Jump Hash)
• Multi-tier architecture support
• Dynamic tenant provisioning
• Template-based naming
• Multi-bucket support
• Storage adapter abstraction
• ERC 2.0 compliant - Zero-config initialization

Logging

By default, @x12i/xronox-router emits error-only logs (quiet by default).

To enable richer local logs (debug/info/warn), set:

ENABLE_XRONOX_ROUTER_LOGXER=true
XRONOX_ROUTER_LOGS_LEVEL=debug

• If ENABLE_XRONOX_ROUTER_LOGXER is missing/empty/not "true" → rich logging is disabled and the effective level is forced to error.
• If ENABLE_XRONOX_ROUTER_LOGXER=true → XRONOX_ROUTER_LOGS_LEVEL controls the effective level:
  • debug | info | warn | error | off
• Legacy support: XRONOX_ROUTER_LOG_LEVEL is used only if XRONOX_ROUTER_LOGS_LEVEL is not set.

Environment Variables

See .env.example for the complete list of required and optional variables with descriptions.

Required Variables

• MONGO_URI - MongoDB connection URI (required by mongodb package)
• S3_ENDPOINT - S3-compatible storage endpoint URL (required by @aws-sdk/client-s3)
• S3_REGION - AWS region for S3 storage (required by @aws-sdk/client-s3)
• S3_ACCESS_KEY - S3 access key ID (required by @aws-sdk/client-s3)
• S3_SECRET_KEY - S3 secret access key (required by @aws-sdk/client-s3, sensitive)

Optional Variables

All database names and bucket names have defaults. See .env.example for full list.

ERC 2.0 Compliance

• Auto-discovers configuration from environment variables
• Type-safe with automatic coercion and validation
• All dependency requirements documented (ERC and non-ERC)
• Transitive requirements automatically merged
• Automatic manifest and .env.example generation

Dependencies

• @x12i/logxer (ERC 2.0) - requirements auto-merged
• mongodb (non-ERC) - requirements manually documented
• @aws-sdk/client-s3 (non-ERC) - requirements manually documented
• @azure/storage-blob (non-ERC) - requirements manually documented
• @x12i/env (Configuration engine)

Verification

Verify ERC 2.0 compliance:

npx @x12i/env erc-verify

Documentation

See specification.md for complete API documentation.

License

MIT