@dotdo/do 0.1.0

package/dist/do/colo/migrate.js

@@ -0,0 +1,190 @@
+/**
+ * Migration Operations
+ *
+ * Move Digital Objects between colos. Use when usage patterns change
+ * or for optimization.
+ *
+ * @module colo/migrate
+ */
+/**
+ * Migrate this DO to another colo
+ *
+ * Moves the primary DO to a different geographic location. This is useful when:
+ * - User patterns shift (e.g., most users now in Asia instead of US)
+ * - Optimizing for latency based on analytics
+ * - Meeting new jurisdiction requirements
+ *
+ * **Graceful Strategy** (default):
+ * 1. Stop accepting new writes
+ * 2. Wait for in-flight requests to complete
+ * 3. Transfer all state to new location
+ * 4. Update routing to point to new location
+ * 5. Resume normal operation
+ *
+ * **Immediate Strategy**:
+ * 1. Snapshot current state
+ * 2. Create new DO in target colo with snapshot
+ * 3. Immediately switch routing
+ * 4. In-flight requests to old location may fail
+ *
+ * @param state - The DurableObjectState instance
+ * @param env - Environment bindings
+ * @param targetColo - IATA code of target colo (e.g., 'fra', 'nrt')
+ * @param options - Migration configuration options
+ * @throws ColoError if target colo is invalid or migration fails
+ *
+ * @example
+ * ```typescript
+ * // Graceful migration (recommended)
+ * await migrateDO(state, env, 'nrt', {
+ *   strategy: 'graceful',
+ *   timeout: 30000,
+ * })
+ *
+ * // Immediate migration (faster but riskier)
+ * await migrateDO(state, env, 'nrt', {
+ *   strategy: 'immediate',
+ * })
+ *
+ * // Fire and forget (don't wait for completion)
+ * await migrateDO(state, env, 'fra', {
+ *   wait: false,
+ * })
+ * ```
+ */
+export async function migrateDO(state, env, targetColo, options) {
+    // TODO: Implement migrateDO
+    //
+    // 1. Validate target colo
+    //    - Use isValidColo() to check
+    //    - Throw INVALID_COLO error if invalid
+    //
+    // 2. Resolve options with defaults
+    //
+    // 3. Emit MIGRATION_STARTED event
+    //
+    // 4. Based on strategy:
+    //    Graceful:
+    //      a. Set state to 'preparing'
+    //      b. Set state to 'draining', reject new writes
+    //      c. Wait for in-flight requests (with timeout)
+    //      d. Set state to 'transferring', export all storage
+    //      e. Create new DO in target colo
+    //      f. Transfer state to new DO
+    //      g. Set state to 'switching', update routing
+    //      h. Set state to 'completed'
+    //
+    //    Immediate:
+    //      a. Snapshot current state
+    //      b. Create new DO in target colo
+    //      c. Transfer snapshot
+    //      d. Switch routing immediately
+    //
+    // 5. Emit MIGRATION_COMPLETED or MIGRATION_FAILED event
+    //
+    throw new Error('Not implemented');
+}
+/**
+ * Apply default values to migrate options
+ *
+ * @param options - Partial options from caller
+ * @returns Fully resolved options with defaults
+ */
+export function resolveMigrateOptions(options) {
+    return {
+        wait: options?.wait ?? true,
+        timeout: options?.timeout ?? 60000,
+        strategy: options?.strategy ?? 'graceful',
+    };
+}
+/**
+ * Get the current migration status
+ *
+ * @param state - The DurableObjectState instance
+ * @returns Current migration status or null if no migration in progress
+ *
+ * @example
+ * ```typescript
+ * const status = await getMigrationStatus(state)
+ * if (status) {
+ *   console.log(`Migration ${status.progress}% complete`)
+ *   console.log(`${status.entriesTransferred}/${status.totalEntries} entries`)
+ * }
+ * ```
+ */
+export async function getMigrationStatus(state) {
+    // TODO: Implement getMigrationStatus
+    //
+    // 1. Get migration status from storage
+    // 2. Return null if no migration in progress
+    // 3. Return status object
+    //
+    throw new Error('Not implemented');
+}
+/**
+ * Cancel an in-progress migration
+ *
+ * Can only cancel migrations that haven't reached the 'switching' state.
+ * Graceful migrations in 'draining' or 'transferring' state can be cancelled.
+ *
+ * @param state - The DurableObjectState instance
+ * @throws ColoError if no migration in progress or migration cannot be cancelled
+ *
+ * @example
+ * ```typescript
+ * await cancelMigration(state)
+ * // Migration cancelled, DO remains in original colo
+ * ```
+ */
+export async function cancelMigration(state) {
+    // TODO: Implement cancelMigration
+    //
+    // 1. Get current migration status
+    // 2. Validate migration can be cancelled (not in 'switching' or 'completed')
+    // 3. Clean up any partially transferred state
+    // 4. Reset migration status
+    // 5. Resume normal operation
+    //
+    throw new Error('Not implemented');
+}
+/**
+ * Drain in-flight requests during graceful migration
+ *
+ * Waits for active requests to complete before proceeding with state transfer.
+ *
+ * @param state - The DurableObjectState instance
+ * @param timeout - Maximum time to wait in ms
+ * @returns True if all requests drained, false if timeout
+ */
+export async function drainRequests(state, timeout) {
+    // TODO: Implement drainRequests
+    //
+    // 1. Track active request count
+    // 2. Reject new requests with appropriate status
+    // 3. Wait for active count to reach 0
+    // 4. Return true if drained, false if timeout
+    //
+    throw new Error('Not implemented');
+}
+/**
+ * Transfer state to a new DO location
+ *
+ * Exports all storage entries and sends them to the target DO.
+ *
+ * @param state - Source DO state
+ * @param targetRef - Reference to target DO
+ * @param onProgress - Optional callback for progress updates
+ * @returns Number of entries transferred
+ */
+export async function transferState(state, targetRef, onProgress) {
+    // TODO: Implement transferState
+    //
+    // 1. List all storage entries
+    // 2. Batch entries for efficient transfer
+    // 3. Send batches to target DO
+    // 4. Call onProgress callback after each batch
+    // 5. Return total count
+    //
+    throw new Error('Not implemented');
+}
+//# sourceMappingURL=migrate.js.map

package/dist/do/colo/migrate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"migrate.js","sourceRoot":"","sources":["../../../do/colo/migrate.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AA6DH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAC7B,KAAyB,EACzB,GAAY,EACZ,UAAkB,EAClB,OAAwB;IAExB,4BAA4B;IAC5B,EAAE;IACF,0BAA0B;IAC1B,kCAAkC;IAClC,2CAA2C;IAC3C,EAAE;IACF,mCAAmC;IACnC,EAAE;IACF,kCAAkC;IAClC,EAAE;IACF,wBAAwB;IACxB,eAAe;IACf,mCAAmC;IACnC,qDAAqD;IACrD,qDAAqD;IACrD,0DAA0D;IAC1D,uCAAuC;IACvC,mCAAmC;IACnC,mDAAmD;IACnD,mCAAmC;IACnC,EAAE;IACF,gBAAgB;IAChB,iCAAiC;IACjC,uCAAuC;IACvC,4BAA4B;IAC5B,qCAAqC;IACrC,EAAE;IACF,wDAAwD;IACxD,EAAE;IACF,MAAM,IAAI,KAAK,CAAC,iBAAiB,CAAC,CAAA;AACpC,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,qBAAqB,CAAC,OAAwB;IAC5D,OAAO;QACL,IAAI,EAAE,OAAO,EAAE,IAAI,IAAI,IAAI;QAC3B,OAAO,EAAE,OAAO,EAAE,OAAO,IAAI,KAAK;QAClC,QAAQ,EAAE,OAAO,EAAE,QAAQ,IAAI,UAAU;KAC1C,CAAA;AACH,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,KAAyB;IAEzB,qCAAqC;IACrC,EAAE;IACF,uCAAuC;IACvC,6CAA6C;IAC7C,0BAA0B;IAC1B,EAAE;IACF,MAAM,IAAI,KAAK,CAAC,iBAAiB,CAAC,CAAA;AACpC,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,KAAyB;IAC7D,kCAAkC;IAClC,EAAE;IACF,kCAAkC;IAClC,6EAA6E;IAC7E,8CAA8C;IAC9C,4BAA4B;IAC5B,6BAA6B;IAC7B,EAAE;IACF,MAAM,IAAI,KAAK,CAAC,iBAAiB,CAAC,CAAA;AACpC,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,KAAyB,EACzB,OAAe;IAEf,gCAAgC;IAChC,EAAE;IACF,gCAAgC;IAChC,iDAAiD;IACjD,sCAAsC;IACtC,8CAA8C;IAC9C,EAAE;IACF,MAAM,IAAI,KAAK,CAAC,iBAAiB,CAAC,CAAA;AACpC,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,KAAyB,EACzB,SAA2B,EAC3B,UAAyD;IAEzD,gCAAgC;IAChC,EAAE;IACF,8BAA8B;IAC9B,0CAA0C;IAC1C,+BAA+B;IAC/B,+CAA+C;IAC/C,wBAAwB;IACxB,EAAE;IACF,MAAM,IAAI,KAAK,CAAC,iBAAiB,CAAC,CAAA;AACpC,CAAC"}

package/dist/do/colo/routing.d.ts

@@ -0,0 +1,182 @@
+/**
+ * Colo-Aware Routing
+ *
+ * Find the best colo for a given location, measure latency, and route
+ * requests to the optimal replica.
+ *
+ * @module colo/routing
+ */
+import type { ColoInfo, Region, LocationHint, JurisdictionConfig } from '../../types/colo';
+import type { DigitalObjectRef } from '../../types/identity';
+/**
+ * Ping result with timing information
+ */
+export interface PingResult {
+    /** Target colo */
+    colo: string;
+    /** Round-trip time in ms */
+    latency: number;
+    /** Whether the colo is reachable */
+    reachable: boolean;
+    /** Error message if not reachable */
+    error?: string;
+}
+/**
+ * Routing decision result
+ */
+export interface RoutingDecision {
+    /** Recommended DO reference to route to */
+    target: DigitalObjectRef;
+    /** Colo of the target */
+    colo: string;
+    /** Estimated latency to target */
+    estimatedLatency: number;
+    /** Reason for this routing decision */
+    reason: 'nearest' | 'lowest-latency' | 'jurisdiction' | 'fallback';
+}
+/**
+ * Find the nearest colo to a given geographic location
+ *
+ * Uses the Haversine formula to calculate great-circle distance between
+ * the given coordinates and known colo locations.
+ *
+ * @param latitude - Latitude of the target location
+ * @param longitude - Longitude of the target location
+ * @param filter - Optional region filter or jurisdiction config
+ * @returns ColoInfo for the nearest colo
+ *
+ * @example
+ * ```typescript
+ * // Find nearest colo to Tokyo
+ * const nearest = await findNearestColo(35.6762, 139.6503)
+ * // { colo: 'nrt', region: 'apac', city: 'Tokyo', ... }
+ *
+ * // Find nearest colo in Europe only
+ * const nearestEU = await findNearestColo(48.8566, 2.3522, 'weur')
+ * // { colo: 'cdg', region: 'weur', city: 'Paris', ... }
+ * ```
+ */
+export declare function findNearestColo(latitude: number, longitude: number, filter?: Region | JurisdictionConfig): Promise<ColoInfo>;
+/**
+ * Ping a colo to measure latency
+ *
+ * Sends a lightweight request to a colo to measure round-trip time.
+ * Useful for runtime latency-based routing decisions.
+ *
+ * @param colo - IATA code of the colo to ping
+ * @returns Ping result with latency
+ *
+ * @example
+ * ```typescript
+ * const result = await pingColo('fra')
+ * console.log(`Latency to Frankfurt: ${result.latency}ms`)
+ *
+ * // Check multiple colos
+ * const colos = ['iad', 'fra', 'nrt']
+ * const results = await Promise.all(colos.map(pingColo))
+ * const fastest = results.reduce((a, b) => a.latency < b.latency ? a : b)
+ * console.log(`Fastest colo: ${fastest.colo} (${fastest.latency}ms)`)
+ * ```
+ */
+export declare function pingColo(colo: string): Promise<PingResult>;
+/**
+ * Ping multiple colos in parallel
+ *
+ * @param colos - Array of colo codes to ping
+ * @returns Array of ping results
+ *
+ * @example
+ * ```typescript
+ * const results = await pingColos(['iad', 'fra', 'nrt', 'sin'])
+ * const sorted = results.sort((a, b) => a.latency - b.latency)
+ * console.log(`Fastest: ${sorted[0].colo} at ${sorted[0].latency}ms`)
+ * ```
+ */
+export declare function pingColos(colos: string[]): Promise<PingResult[]>;
+/**
+ * Make a routing decision based on location and available replicas
+ *
+ * Determines the best replica to route a request to based on the client's
+ * location, available replicas, and any jurisdiction constraints.
+ *
+ * @param hint - Location hint from the request
+ * @param replicas - Available replica references with their colos
+ * @param jurisdiction - Optional jurisdiction constraints
+ * @returns Routing decision with target reference
+ *
+ * @example
+ * ```typescript
+ * const decision = await route(
+ *   { clientIp: request.headers.get('cf-connecting-ip') },
+ *   [
+ *     { ref: 'https://...', colo: 'iad' },
+ *     { ref: 'https://...', colo: 'fra' },
+ *     { ref: 'https://...', colo: 'nrt' },
+ *   ]
+ * )
+ *
+ * // Route to the recommended target
+ * const response = await fetch(decision.target, request)
+ * ```
+ */
+export declare function route(hint: LocationHint, replicas: Array<{
+    ref: DigitalObjectRef;
+    colo: string;
+}>, jurisdiction?: JurisdictionConfig): Promise<RoutingDecision>;
+/**
+ * Calculate the great-circle distance between two points
+ *
+ * Uses the Haversine formula for accurate distance calculation.
+ *
+ * @param lat1 - Latitude of first point
+ * @param lon1 - Longitude of first point
+ * @param lat2 - Latitude of second point
+ * @param lon2 - Longitude of second point
+ * @returns Distance in kilometers
+ *
+ * @example
+ * ```typescript
+ * // Distance from New York to London
+ * const distance = haversineDistance(40.7128, -74.0060, 51.5074, -0.1278)
+ * // ~5570 km
+ * ```
+ */
+export declare function haversineDistance(lat1: number, lon1: number, lat2: number, lon2: number): number;
+/**
+ * Estimate latency based on geographic distance
+ *
+ * Uses a simple model: base latency + distance-based latency.
+ * This is a rough estimate; use pingColo for actual measurements.
+ *
+ * @param distanceKm - Distance in kilometers
+ * @returns Estimated latency in milliseconds
+ */
+export declare function estimateLatency(distanceKm: number): number;
+/**
+ * Check if a colo is allowed by jurisdiction config
+ *
+ * @param colo - Colo to check
+ * @param config - Jurisdiction configuration
+ * @returns True if colo is allowed
+ */
+export declare function isColoAllowedByJurisdiction(colo: string, config: JurisdictionConfig): boolean;
+/**
+ * Get all colos in a region
+ *
+ * @param region - Region code
+ * @returns Array of colo codes in the region
+ */
+export declare function getColosInRegion(region: Region): string[];
+/**
+ * Sort colos by distance from a location
+ *
+ * @param latitude - Origin latitude
+ * @param longitude - Origin longitude
+ * @param colos - Colos to sort (defaults to all known colos)
+ * @returns Colos sorted by distance (nearest first)
+ */
+export declare function sortColosByDistance(latitude: number, longitude: number, colos?: string[]): Array<{
+    colo: string;
+    distance: number;
+}>;
+//# sourceMappingURL=routing.d.ts.map

package/dist/do/colo/routing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"routing.d.ts","sourceRoot":"","sources":["../../../do/colo/routing.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,YAAY,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAA;AAC1F,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAA;AAG5D;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,kBAAkB;IAClB,IAAI,EAAE,MAAM,CAAA;IACZ,4BAA4B;IAC5B,OAAO,EAAE,MAAM,CAAA;IACf,oCAAoC;IACpC,SAAS,EAAE,OAAO,CAAA;IAClB,qCAAqC;IACrC,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,2CAA2C;IAC3C,MAAM,EAAE,gBAAgB,CAAA;IACxB,yBAAyB;IACzB,IAAI,EAAE,MAAM,CAAA;IACZ,kCAAkC;IAClC,gBAAgB,EAAE,MAAM,CAAA;IACxB,uCAAuC;IACvC,MAAM,EAAE,SAAS,GAAG,gBAAgB,GAAG,cAAc,GAAG,UAAU,CAAA;CACnE;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,eAAe,CACnC,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,MAAM,CAAC,EAAE,MAAM,GAAG,kBAAkB,GACnC,OAAO,CAAC,QAAQ,CAAC,CASnB;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAUhE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC,CAEtE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAsB,KAAK,CACzB,IAAI,EAAE,YAAY,EAClB,QAAQ,EAAE,KAAK,CAAC;IAAE,GAAG,EAAE,gBAAgB,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,EACxD,YAAY,CAAC,EAAE,kBAAkB,GAChC,OAAO,CAAC,eAAe,CAAC,CAW1B;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,GACX,MAAM,CAeR;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAU1D;AAED;;;;;;GAMG;AACH,wBAAgB,2BAA2B,CACzC,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,kBAAkB,GACzB,OAAO,CA+BT;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAezD;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,KAAK,CAAC,EAAE,MAAM,EAAE,GACf,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CAe3C"}

package/dist/do/colo/routing.js

@@ -0,0 +1,254 @@
+/**
+ * Colo-Aware Routing
+ *
+ * Find the best colo for a given location, measure latency, and route
+ * requests to the optimal replica.
+ *
+ * @module colo/routing
+ */
+import { COLO_METADATA, getRegionForColo } from './info';
+/**
+ * Find the nearest colo to a given geographic location
+ *
+ * Uses the Haversine formula to calculate great-circle distance between
+ * the given coordinates and known colo locations.
+ *
+ * @param latitude - Latitude of the target location
+ * @param longitude - Longitude of the target location
+ * @param filter - Optional region filter or jurisdiction config
+ * @returns ColoInfo for the nearest colo
+ *
+ * @example
+ * ```typescript
+ * // Find nearest colo to Tokyo
+ * const nearest = await findNearestColo(35.6762, 139.6503)
+ * // { colo: 'nrt', region: 'apac', city: 'Tokyo', ... }
+ *
+ * // Find nearest colo in Europe only
+ * const nearestEU = await findNearestColo(48.8566, 2.3522, 'weur')
+ * // { colo: 'cdg', region: 'weur', city: 'Paris', ... }
+ * ```
+ */
+export async function findNearestColo(latitude, longitude, filter) {
+    // TODO: Implement findNearestColo
+    //
+    // 1. Get list of candidate colos (filtered if region specified)
+    // 2. If JurisdictionConfig provided, filter by allowed/blocked
+    // 3. Calculate distance to each colo using haversineDistance
+    // 4. Return colo with minimum distance
+    //
+    throw new Error('Not implemented');
+}
+/**
+ * Ping a colo to measure latency
+ *
+ * Sends a lightweight request to a colo to measure round-trip time.
+ * Useful for runtime latency-based routing decisions.
+ *
+ * @param colo - IATA code of the colo to ping
+ * @returns Ping result with latency
+ *
+ * @example
+ * ```typescript
+ * const result = await pingColo('fra')
+ * console.log(`Latency to Frankfurt: ${result.latency}ms`)
+ *
+ * // Check multiple colos
+ * const colos = ['iad', 'fra', 'nrt']
+ * const results = await Promise.all(colos.map(pingColo))
+ * const fastest = results.reduce((a, b) => a.latency < b.latency ? a : b)
+ * console.log(`Fastest colo: ${fastest.colo} (${fastest.latency}ms)`)
+ * ```
+ */
+export async function pingColo(colo) {
+    // TODO: Implement pingColo
+    //
+    // 1. Validate colo code
+    // 2. Record start time
+    // 3. Send ping request to colo
+    // 4. Calculate round-trip time
+    // 5. Return result
+    //
+    throw new Error('Not implemented');
+}
+/**
+ * Ping multiple colos in parallel
+ *
+ * @param colos - Array of colo codes to ping
+ * @returns Array of ping results
+ *
+ * @example
+ * ```typescript
+ * const results = await pingColos(['iad', 'fra', 'nrt', 'sin'])
+ * const sorted = results.sort((a, b) => a.latency - b.latency)
+ * console.log(`Fastest: ${sorted[0].colo} at ${sorted[0].latency}ms`)
+ * ```
+ */
+export async function pingColos(colos) {
+    return Promise.all(colos.map(pingColo));
+}
+/**
+ * Make a routing decision based on location and available replicas
+ *
+ * Determines the best replica to route a request to based on the client's
+ * location, available replicas, and any jurisdiction constraints.
+ *
+ * @param hint - Location hint from the request
+ * @param replicas - Available replica references with their colos
+ * @param jurisdiction - Optional jurisdiction constraints
+ * @returns Routing decision with target reference
+ *
+ * @example
+ * ```typescript
+ * const decision = await route(
+ *   { clientIp: request.headers.get('cf-connecting-ip') },
+ *   [
+ *     { ref: 'https://...', colo: 'iad' },
+ *     { ref: 'https://...', colo: 'fra' },
+ *     { ref: 'https://...', colo: 'nrt' },
+ *   ]
+ * )
+ *
+ * // Route to the recommended target
+ * const response = await fetch(decision.target, request)
+ * ```
+ */
+export async function route(hint, replicas, jurisdiction) {
+    // TODO: Implement route
+    //
+    // 1. If hint.colo specified, try to match directly
+    // 2. If hint.region specified, filter replicas to that region
+    // 3. If hint.clientIp, geo-locate IP and find nearest
+    // 4. If hint.coordinates, use findNearestColo
+    // 5. Apply jurisdiction constraints
+    // 6. Return routing decision with reason
+    //
+    throw new Error('Not implemented');
+}
+/**
+ * Calculate the great-circle distance between two points
+ *
+ * Uses the Haversine formula for accurate distance calculation.
+ *
+ * @param lat1 - Latitude of first point
+ * @param lon1 - Longitude of first point
+ * @param lat2 - Latitude of second point
+ * @param lon2 - Longitude of second point
+ * @returns Distance in kilometers
+ *
+ * @example
+ * ```typescript
+ * // Distance from New York to London
+ * const distance = haversineDistance(40.7128, -74.0060, 51.5074, -0.1278)
+ * // ~5570 km
+ * ```
+ */
+export function haversineDistance(lat1, lon1, lat2, lon2) {
+    const R = 6371; // Earth radius in kilometers
+    const toRad = (deg) => (deg * Math.PI) / 180;
+    const dLat = toRad(lat2 - lat1);
+    const dLon = toRad(lon2 - lon1);
+    const a = Math.sin(dLat / 2) * Math.sin(dLat / 2) +
+        Math.cos(toRad(lat1)) * Math.cos(toRad(lat2)) * Math.sin(dLon / 2) * Math.sin(dLon / 2);
+    const c = 2 * Math.atan2(Math.sqrt(a), Math.sqrt(1 - a));
+    return R * c;
+}
+/**
+ * Estimate latency based on geographic distance
+ *
+ * Uses a simple model: base latency + distance-based latency.
+ * This is a rough estimate; use pingColo for actual measurements.
+ *
+ * @param distanceKm - Distance in kilometers
+ * @returns Estimated latency in milliseconds
+ */
+export function estimateLatency(distanceKm) {
+    // Base latency (processing, serialization, etc.)
+    const baseLatency = 10;
+    // Speed of light in fiber: ~200,000 km/s
+    // Round trip, so divide by 100,000 km/s
+    const propagationLatency = distanceKm / 100;
+    // Add some overhead for network hops (~20%)
+    return Math.round((baseLatency + propagationLatency) * 1.2);
+}
+/**
+ * Check if a colo is allowed by jurisdiction config
+ *
+ * @param colo - Colo to check
+ * @param config - Jurisdiction configuration
+ * @returns True if colo is allowed
+ */
+export function isColoAllowedByJurisdiction(colo, config) {
+    // Check blocked colos
+    if (config.blockedColos?.includes(colo.toLowerCase())) {
+        return false;
+    }
+    // Check allowed colos (if specified, must be in list)
+    if (config.allowedColos && !config.allowedColos.includes(colo.toLowerCase())) {
+        return false;
+    }
+    // Check region
+    const region = getRegionForColo(colo);
+    if (region) {
+        if (config.blockedRegions?.includes(region)) {
+            return false;
+        }
+        if (config.allowedRegions && !config.allowedRegions.includes(region)) {
+            return false;
+        }
+    }
+    // Check country
+    const metadata = COLO_METADATA[colo.toLowerCase()];
+    if (metadata && config.requiredCountries) {
+        if (!config.requiredCountries.includes(metadata.country)) {
+            return false;
+        }
+    }
+    return true;
+}
+/**
+ * Get all colos in a region
+ *
+ * @param region - Region code
+ * @returns Array of colo codes in the region
+ */
+export function getColosInRegion(region) {
+    // TODO: Import REGIONS from types at module level when implementing
+    // For now, use the inline data
+    const regionColos = {
+        wnam: ['sjc', 'lax', 'sea', 'den', 'phx', 'pdx', 'yvr'],
+        enam: ['iad', 'dfw', 'atl', 'ord', 'mia', 'yyz', 'bos', 'jfk'],
+        sam: ['gru', 'eze', 'scl', 'bog'],
+        weur: ['lhr', 'cdg', 'fra', 'ams', 'dub', 'mad', 'lis'],
+        eeur: ['waw', 'bud', 'prg', 'vie'],
+        apac: ['nrt', 'sin', 'hkg', 'bom', 'del', 'icn', 'kix'],
+        oc: ['syd', 'mel', 'akl', 'per'],
+        afr: ['jnb', 'cpt', 'nbo'],
+        me: ['dxb', 'tlv', 'ruh'],
+    };
+    return regionColos[region] ?? [];
+}
+/**
+ * Sort colos by distance from a location
+ *
+ * @param latitude - Origin latitude
+ * @param longitude - Origin longitude
+ * @param colos - Colos to sort (defaults to all known colos)
+ * @returns Colos sorted by distance (nearest first)
+ */
+export function sortColosByDistance(latitude, longitude, colos) {
+    const candidates = colos ?? Object.keys(COLO_METADATA);
+    return candidates
+        .map((colo) => {
+        const metadata = COLO_METADATA[colo.toLowerCase()];
+        if (!metadata) {
+            return { colo, distance: Infinity };
+        }
+        return {
+            colo,
+            distance: haversineDistance(latitude, longitude, metadata.latitude, metadata.longitude),
+        };
+    })
+        .sort((a, b) => a.distance - b.distance);
+}
+//# sourceMappingURL=routing.js.map

package/dist/do/colo/routing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"routing.js","sourceRoot":"","sources":["../../../do/colo/routing.ts"],"names":[],"mappings":"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"}