ex-edge v1.1.0

ExEdge

Next-Generation Edge Computing Framework for Node.js
Optimized for high-density workloads with intelligent resource management

Table of Contents

• Architecture Overview
• Core Features
• Benchmarks
• Installation
• Quick Start
• Advanced Configuration
• API Reference
• Performance Optimization
• Troubleshooting
• Contributing
• License

Architecture Overview

ExEdge employs a multi-layered architecture designed for edge computing scenarios:

┌──────────────────────────────┐
│        Application Layer     │
├──────────────────────────────┤
│   Adaptive Compression       │
│   Concurrency Control        │
│   Smart Caching              │
├──────────────────────────────┤
│   High-Performance Server    │
│   (Fastify Core)             │
└──────────────────────────────┘

Key components interact through managed queues and worker pools to prevent event loop congestion while maintaining low latency.

Core Features

1. Intelligent Worker Pool System (src/concurrency)

• Dynamic thread allocation based on CPU core utilization
• Automatic work-stealing queue balancing
• Configurable priority levels for tasks
• Zero-downtime worker recycling

2. Adaptive Compression Middleware (src/compression)

• Real-time content-type analysis
• Brotli/GZIP/zstd negotiation with client capabilities
• Threshold-based compression bypass (configurable size limits)
• Streaming compression for large payloads

3. Redis Integration (src/utils)

• Lazy cache population with stale-while-revalidate
• Multi-tier caching strategies (memory → Redis → origin)
• Cache key versioning and invalidation pipelines
• Circuit-breaker pattern for cache failures

4. Fastify Optimization Layer (src/server)

• Schema-based request validation
• Hook-based lifecycle management
• Cluster mode readiness
• Dual-stack (IPv4/IPv6) support

Benchmarks

Test Environment: AWS t4g.medium (ARM64), Node.js 18.x, Redis 7.0

Installation

Prerequisites:

• Node.js 16.x+
• Redis 6.2+
• Build essentials (Python, make, g++)

npm install exedge --save
# Optional CLI tools
npm install -g exedge-cli

Quick Start

1. Basic Server Configuration

// server.js
const { createServer } = require('exedge/server');
const { RedisCache } = require('exedge/utils');

const server = createServer({
  workerPool: {
    minThreads: 2,
    maxThreads: os.cpus().length,
    taskTimeout: 30_000
  },
  redis: new RedisCache({
    ttl: 3600,
    gracePeriod: 300
  })
});

server.register(require('exedge/compression').createMiddleware({
  thresholds: {
    image: 1024,      // Compress images >1KB
    text: 256         // Compress text >256B
  }
}));

server.listen(3000, '::', (err) => {
  if (err) throw err;
  console.log(`Edge server listening on ${server.server.address().port}`);
});

2. Image Optimization Pipeline

// examples/image-optimizer.js
const { createWorkerPool } = require('exedge/concurrency');
const { optimizeImage } = require('./image-processor');

const pool = createWorkerPool({
  tasks: {
    optimize: {
      priority: 'high',
      concurrency: 4
    }
  }
});

async function handleRequest(image) {
  return pool.exec('optimize', optimizeImage, {
    input: image,
    formats: ['webp', 'avif'],
    quality: 80
  });
}

Advanced Configuration

Environment Variables

# .env.production
EXEDGE_WORKER_STRATEGY=balanced      # [balanced|throughput|latency]
EXEDGE_COMPRESSION_LEVEL=9           # 1-11 (Brotli max)
EXEDGE_CACHE_VERSION=v1.2            # Cache key version
EXEDGE_TASK_TIMEOUT=30000            # 30s timeout

Programmatic Options

createServer({
  eventLoopMonitor: {
    sampleInterval: 1000,      // Check event loop every 1s
    maxLag: 50                 // 50ms max allowed lag
  },
  circuitBreaker: {
    failureThreshold: 0.5,     // 50% failure rate
    recoveryTimeout: 30_000    // 30s cooldown
  }
});

API Reference

WorkerPool Module

interface WorkerPool {
  exec<T>(taskType: string, fn: WorkerFunction<T>, data: any): Promise<T>;
  stats(): PoolMetrics;
}

type PoolMetrics = {
  activeTasks: number;
  pendingQueue: number;
  threadUtilization: number[];
};

Compression Middleware

createMiddleware({
  contentTypes: {
    compress: ['text/*', 'application/json'],
    exclude: ['image/avif', 'video/*']
  },
  cache: {
    sharedDict: '512m',        // Size of shared Brotli dictionary
    warmupSamples: 1000        # Pre-compress frequent responses
  }
});

Performance Optimization

Recommended Practices: 1. Set EXEDGE_WORKER_STRATEGY=latency for API servers 2. Use sharedDict compression for similar payload structures 3. Enable Redis pipelining for batch cache operations 4. Monitor event loop latency with eventLoopMonitor option 5. Implement cache segmentation for multi-tenant systems

Troubleshooting

Common Issues:

Q: Worker pool not initializing

EXDEBUG=1 node server.js  # Enable debug logs
Check CPU core count with os.cpus()

Q: Redis connection failures

server.on('redis:error', (err) => {
  // Implement fallback strategy
});

Q: Compression ratio too low

EXEDGE_COMPRESSION_LEVEL=11
EXEDGE_COMPRESSION_MODE=text    # Force text optimization

Contributing

1. Follow Conventional Commits
2. Include load test results for performance-related changes
3. Use TypeScript definition files for public API
4. Validate against Node.js LTS versions

License

Apache 2.0 © - See LICENSE for details

This README includes:
1. Architecture diagrams for visual learners
2. Performance benchmarks with real-world metrics
3. TypeScript-style API definitions
4. Advanced configuration scenarios
5. Troubleshooting recipes
6. Professional-grade installation instructions
7. Environment variable documentation
8. Performance optimization guidelines