@aimf/edge

Multi-Region Edge Distribution module for the AI-MCP Framework (AIMF).

Features

• Region Manager: Register and manage geographic regions with endpoints
• Geographic Router: Intelligent request routing with multiple strategies
• Data Replicator: Cross-region data replication with conflict resolution
• Health Monitoring: Automatic endpoint health checks

Installation

pnpm add @aimf/edge

Quick Start

Region Manager

import { createRegionManager } from "@aimf/edge";

const manager = createRegionManager();

// Register a region
manager.registerRegion(
  "us-east-1",
  "US East",
  {
    latitude: 39.0438,
    longitude: -77.4874,
    country: "United States",
    countryCode: "US",
    continent: "North America",
    timezone: "America/New_York",
  },
  {
    supportedModels: ["gpt-4", "claude-3"],
    maxConcurrency: 100,
    gpuAvailable: true,
    storageTypes: ["ssd"],
    complianceRegimes: ["gdpr", "soc2"],
  },
  {
    allowedRegions: ["US", "CA"],
    replicationEnabled: true,
    encryptionRequired: true,
  }
);

// Add endpoints
manager.addEndpoint("us-east-1", {
  type: "gateway",
  url: "https://us-east-1.example.com",
  priority: 1,
  weight: 100,
});

// Find nearest region
const nearest = manager.findNearestRegion(50.1109, 8.6821);

// Start health checks
manager.startHealthChecks(30000);

Geographic Router

import { createRegionManager, createGeoRouter } from "@aimf/edge";

const manager = createRegionManager();
// ... register regions ...

const router = createGeoRouter(manager, {
  strategy: "latency",
  stickySession: true,
  sessionTtl: 3600000,
});

// Route a request
const decision = await router.route(
  {
    ip: "192.168.1.1",
    country: "Germany",
    countryCode: "DE",
    region: "Hesse",
    city: "Frankfurt",
    latitude: 50.1109,
    longitude: 8.6821,
    timezone: "Europe/Berlin",
  },
  "gateway",
  {
    sessionId: "user-session-123",
    dataResidencyCountries: ["EU", "DE"],
  }
);

console.log(`Routed to: ${decision.selectedRegion}`);
console.log(`Endpoint: ${decision.selectedEndpoint}`);
console.log(`Fallbacks: ${decision.fallbacks.join(", ")}`);

Data Replicator

import { createDataReplicator } from "@aimf/edge";

const replicator = createDataReplicator("us-east-1", {
  targets: ["eu-west-1", "ap-south-1"],
  mode: "async",
  conflictResolution: "last-write-wins",
  maxLag: 5000,
});

// Set replication handler
replicator.setReplicateHandler(async (target, key, data) => {
  await sendToRegion(target, key, data);
});

// Replicate data
await replicator.replicate("user-profile:123", {
  name: "John Doe",
  preferences: { theme: "dark" },
});

// Check replication status
const statuses = replicator.getStatus();
for (const status of statuses) {
  console.log(`${status.target}: ${status.status} (lag: ${status.lag}ms)`);
}

Routing Strategies

| Strategy | Description | |----------|-------------| | latency | Routes to lowest latency region (default) | | geographic | Routes to geographically nearest region | | round-robin | Rotates between available regions | | weighted | Routes based on endpoint weights | | failover | Routes to highest priority available region | | cost | Routes to least loaded region |

Data Residency

The router supports data residency requirements for compliance:

const decision = await router.route(clientInfo, "storage", {
  dataResidencyCountries: ["EU", "DE", "FR"], // Only route to EU regions
});

Session Affinity

Enable sticky sessions to maintain consistent routing:

const router = createGeoRouter(manager, {
  stickySession: true,
  sessionTtl: 3600000, // 1 hour
});

// Same session always routes to same region
const decision1 = await router.route(client, "gateway", { sessionId: "sess-1" });
const decision2 = await router.route(client, "gateway", { sessionId: "sess-1" });
// decision1.selectedRegion === decision2.selectedRegion

Replication Modes

| Mode | Description | |------|-------------| | sync | Wait for all replicas before returning | | async | Queue replication and return immediately | | eventual | Best-effort replication with relaxed consistency |

Conflict Resolution

| Strategy | Description | |----------|-------------| | last-write-wins | Most recent timestamp wins | | merge | Merge object properties (shallow) | | manual | Throw error for manual resolution |

API Reference

RegionManager

| Method | Description | |--------|-------------| | registerRegion() | Register a new region | | addEndpoint() | Add endpoint to region | | updateStatus() | Update region status | | updateEndpointHealth() | Update endpoint health | | findNearestRegion() | Find nearest region by coordinates | | findAllowedRegions() | Find regions matching data residency | | startHealthChecks() | Start automatic health monitoring |

GeoRouter

| Method | Description | |--------|-------------| | route() | Route request to optimal region | | setStrategy() | Change routing strategy | | recordLatency() | Record measured latency | | clearSessionAffinity() | Clear session affinity |

DataReplicator

| Method | Description | |--------|-------------| | replicate() | Replicate data to targets | | setReplicateHandler() | Set replication callback | | getStatus() | Get replication status | | addTarget() | Add replication target | | removeTarget() | Remove replication target | | resolveConflict() | Resolve data conflicts |

Events

When used with EventBus:

• edge.region.registered - New region registered
• edge.region.status_changed - Region status changed
• edge.routing.decision - Routing decision made
• edge.replication.completed - Replication job completed
• edge.replication.failed - Replication job failed
• edge.health_check.completed - Health check cycle completed

License

MIT