@algochad/archcoder 2.0.2

package/server/lib/tunnels/providers/cloudflare.js

@@ -0,0 +1,260 @@
+import {
+  checkCloudflareApiReachability,
+  checkCloudflaredAvailable,
+  inspectManagedLocalCloudflareConfig,
+  normalizeCloudflareTunnelHostname,
+  startCloudflareManagedLocalTunnel,
+  startCloudflareManagedRemoteTunnel,
+  startCloudflareQuickTunnel,
+} from '../../cloudflare-tunnel.js';
+
+import {
+  TUNNEL_INTENT_EPHEMERAL_PUBLIC,
+  TUNNEL_INTENT_PERSISTENT_PUBLIC,
+  TUNNEL_MODE_MANAGED_LOCAL,
+  TUNNEL_MODE_MANAGED_REMOTE,
+  TUNNEL_MODE_QUICK,
+  TUNNEL_PROVIDER_CLOUDFLARE,
+  TunnelServiceError,
+} from '../types.js';
+
+export const cloudflareTunnelProviderCapabilities = {
+  provider: TUNNEL_PROVIDER_CLOUDFLARE,
+  defaults: {
+    mode: TUNNEL_MODE_QUICK,
+    optionDefaults: {},
+  },
+  modes: [
+    {
+      key: TUNNEL_MODE_QUICK,
+      label: 'Quick Tunnel',
+      intent: TUNNEL_INTENT_EPHEMERAL_PUBLIC,
+      requires: [],
+      supports: ['sessionTTL'],
+      stability: 'ga',
+    },
+    {
+      key: TUNNEL_MODE_MANAGED_REMOTE,
+      label: 'Managed Remote Tunnel',
+      intent: TUNNEL_INTENT_PERSISTENT_PUBLIC,
+      requires: ['token', 'hostname'],
+      supports: ['customDomain', 'sessionTTL'],
+      stability: 'ga',
+    },
+    {
+      key: TUNNEL_MODE_MANAGED_LOCAL,
+      label: 'Managed Local Tunnel',
+      intent: TUNNEL_INTENT_PERSISTENT_PUBLIC,
+      requires: [],
+      supports: ['configFile', 'customDomain', 'sessionTTL'],
+      stability: 'ga',
+    },
+  ],
+};
+
+export function createCloudflareTunnelProvider() {
+  const validateTokenShape = (value) => {
+    if (typeof value !== 'string') {
+      return { ok: false, detail: 'Managed remote token is missing.' };
+    }
+    const trimmed = value.trim();
+    if (!trimmed) {
+      return { ok: false, detail: 'Managed remote token is missing.' };
+    }
+    if (/\s/.test(trimmed)) {
+      return { ok: false, detail: 'Managed remote token has whitespace; provide the raw token value.' };
+    }
+    return { ok: true, detail: 'Managed remote token looks valid.' };
+  };
+
+  const createModeSummary = (checks) => {
+    const failures = checks.filter((entry) => entry.status === 'fail').length;
+    const warnings = checks.filter((entry) => entry.status === 'warn').length;
+    return {
+      ready: failures === 0,
+      failures,
+      warnings,
+    };
+  };
+
+  const describeMode = ({ mode, checks }) => {
+    const summary = createModeSummary(checks);
+    const blockers = checks
+      .filter((entry) => entry.status === 'fail' && entry.id !== 'startup_readiness')
+      .map((entry) => entry.detail || entry.label || entry.id);
+    return {
+      mode,
+      checks,
+      summary,
+      ready: summary.ready,
+      blockers,
+    };
+  };
+
+  return {
+    id: TUNNEL_PROVIDER_CLOUDFLARE,
+    capabilities: cloudflareTunnelProviderCapabilities,
+    checkAvailability: async () => {
+      const result = await checkCloudflaredAvailable();
+      if (result.available) {
+        return result;
+      }
+      return {
+        ...result,
+        message: 'cloudflared is not installed. Install it with: brew install cloudflared',
+      };
+    },
+    diagnose: async (request = {}) => {
+      const dependency = await checkCloudflaredAvailable();
+      const network = await checkCloudflareApiReachability();
+
+      const providerChecks = [
+        {
+          id: 'dependency',
+          label: 'cloudflared installed',
+          status: dependency.available ? 'pass' : 'fail',
+          detail: dependency.available
+            ? (dependency.version || dependency.path || 'cloudflared available')
+            : 'cloudflared is not installed. Install it with: brew install cloudflared',
+        },
+        {
+          id: 'network',
+          label: 'Cloudflare API reachable',
+          status: network.reachable ? 'pass' : 'fail',
+          detail: network.reachable
+            ? (network.status ? `HTTP ${network.status}` : 'Reachable')
+            : (network.error || 'Could not reach api.trycloudflare.com'),
+        },
+      ];
+
+      const startupReady = dependency.available && network.reachable;
+      const startupDetail = startupReady
+        ? 'Provider dependency and network checks passed.'
+        : 'Resolve provider checks before starting tunnels.';
+
+      const quickChecks = [
+        {
+          id: 'startup_readiness',
+          label: 'Provider startup readiness',
+          status: startupReady ? 'pass' : 'fail',
+          detail: startupDetail,
+        },
+        {
+          id: 'quick_mode_prerequisites',
+          label: 'Quick tunnel prerequisites',
+          status: network.reachable ? 'pass' : 'fail',
+          detail: network.reachable
+            ? 'Cloudflare edge is reachable for quick tunnels.'
+            : 'Cloudflare edge is not reachable for quick tunnels.',
+        },
+      ];
+
+      const managedLocalInspection = inspectManagedLocalCloudflareConfig({
+        configPath: request.configPath,
+        hostname: request.hostname,
+      });
+      const managedLocalChecks = [
+        {
+          id: 'startup_readiness',
+          label: 'Provider startup readiness',
+          status: startupReady ? 'pass' : 'fail',
+          detail: startupDetail,
+        },
+        {
+          id: 'managed_local_config',
+          label: 'Managed local config',
+          status: managedLocalInspection.ok ? 'pass' : 'fail',
+          detail: managedLocalInspection.ok
+            ? `${managedLocalInspection.effectiveConfigPath}${managedLocalInspection.resolvedHostname ? ` (${managedLocalInspection.resolvedHostname})` : ''}`
+            : managedLocalInspection.error,
+        },
+      ];
+
+      const normalizedHost = normalizeCloudflareTunnelHostname(request.hostname);
+      const hostnameMissing = !normalizedHost;
+      const remoteTokenValidation = validateTokenShape(request.token);
+      const tokenMissing = typeof request.token !== 'string' || request.token.trim().length === 0;
+      const hasSavedManagedRemoteProfile = request.hasSavedManagedRemoteProfile === true;
+      const tokenProvided = request.tokenProvided === true;
+      const hostnameProvided = request.hostnameProvided === true;
+      const hasExplicitManagedRemoteInput = tokenProvided || hostnameProvided;
+      const canUseSavedProfileForHostname = !hasExplicitManagedRemoteInput && hostnameMissing && hasSavedManagedRemoteProfile;
+      const canUseSavedProfileForToken = !hasExplicitManagedRemoteInput && tokenMissing && hasSavedManagedRemoteProfile;
+      const savedProfileReadyDetail = 'at least one saved profile present';
+      const managedRemoteChecks = [
+        {
+          id: 'startup_readiness',
+          label: 'Provider startup readiness',
+          status: startupReady ? 'pass' : 'fail',
+          detail: startupDetail,
+        },
+        {
+          id: 'managed_remote_hostname',
+          label: 'Managed remote hostname',
+          status: normalizedHost || canUseSavedProfileForHostname ? 'pass' : 'fail',
+          detail: normalizedHost
+            ? normalizedHost
+            : canUseSavedProfileForHostname
+              ? savedProfileReadyDetail
+              : 'Managed remote hostname is required (use --hostname).',
+        },
+        {
+          id: 'managed_remote_token',
+          label: 'Managed remote token',
+          status: remoteTokenValidation.ok || canUseSavedProfileForToken ? 'pass' : 'fail',
+          detail: canUseSavedProfileForToken
+            ? savedProfileReadyDetail
+            : remoteTokenValidation.detail,
+        },
+      ];
+
+      const allModes = [
+        describeMode({ mode: TUNNEL_MODE_QUICK, checks: quickChecks }),
+        describeMode({ mode: TUNNEL_MODE_MANAGED_REMOTE, checks: managedRemoteChecks }),
+        describeMode({ mode: TUNNEL_MODE_MANAGED_LOCAL, checks: managedLocalChecks }),
+      ];
+
+      const modeFilter = typeof request.mode === 'string' && request.mode.trim().length > 0
+        ? request.mode.trim().toLowerCase()
+        : null;
+      const modes = modeFilter ? allModes.filter((entry) => entry.mode === modeFilter) : allModes;
+
+      return {
+        providerChecks,
+        modes,
+      };
+    },
+    start: async (request, context = {}) => {
+      if (request.mode === TUNNEL_MODE_MANAGED_REMOTE) {
+        return startCloudflareManagedRemoteTunnel({
+          token: request.token,
+          hostname: request.hostname,
+        });
+      }
+
+      if (request.mode === TUNNEL_MODE_MANAGED_LOCAL) {
+        return startCloudflareManagedLocalTunnel({
+          configPath: request.configPath,
+          hostname: request.hostname,
+        });
+      }
+
+      if (!context.originUrl) {
+        throw new TunnelServiceError('validation_error', 'originUrl is required for quick tunnel mode');
+      }
+
+      return startCloudflareQuickTunnel({
+        originUrl: context.originUrl,
+        port: context.activePort,
+      });
+    },
+    stop: (controller) => {
+      controller?.stop?.();
+    },
+    resolvePublicUrl: (controller) => controller?.getPublicUrl?.() ?? null,
+    getMetadata: (controller) => ({
+      configPath: controller?.getEffectiveConfigPath?.() ?? null,
+      resolvedHostname: controller?.getResolvedHostname?.() ?? null,
+    }),
+  };
+}

package/server/lib/tunnels/registry.js

@@ -0,0 +1,51 @@
+const REQUIRED_PROVIDER_METHODS = ['start', 'stop', 'checkAvailability', 'resolvePublicUrl'];
+
+export function createTunnelProviderRegistry(initialProviders = []) {
+  const providers = new Map();
+  let sealed = false;
+
+  const register = (provider) => {
+    if (sealed) {
+      throw new Error('Tunnel provider registry is sealed; no further registrations allowed');
+    }
+    if (!provider || typeof provider.id !== 'string' || provider.id.trim().length === 0) {
+      throw new Error('Tunnel provider must define a non-empty id');
+    }
+    for (const method of REQUIRED_PROVIDER_METHODS) {
+      if (typeof provider[method] !== 'function') {
+        throw new Error(`Tunnel provider '${provider.id}' must implement ${method}()`);
+      }
+    }
+    const key = provider.id.trim().toLowerCase();
+    if (providers.has(key)) {
+      throw new Error(`Tunnel provider '${key}' is already registered`);
+    }
+    providers.set(key, provider);
+    return provider;
+  };
+
+  const get = (providerId) => {
+    if (typeof providerId !== 'string' || providerId.trim().length === 0) {
+      return null;
+    }
+    return providers.get(providerId.trim().toLowerCase()) ?? null;
+  };
+
+  const list = () => Array.from(providers.values());
+
+  const listCapabilities = () => list().map((provider) => ({ ...provider.capabilities }));
+
+  for (const provider of initialProviders) {
+    register(provider);
+  }
+
+  const seal = () => { sealed = true; };
+
+  return {
+    register,
+    get,
+    list,
+    listCapabilities,
+    seal,
+  };
+}

package/server/lib/tunnels/types.js

@@ -0,0 +1,219 @@
+import os from 'os';
+import path from 'path';
+
+export const TUNNEL_PROVIDER_CLOUDFLARE = 'cloudflare';
+
+export const TUNNEL_MODE_QUICK = 'quick';
+export const TUNNEL_MODE_MANAGED_REMOTE = 'managed-remote';
+export const TUNNEL_MODE_MANAGED_LOCAL = 'managed-local';
+
+export const TUNNEL_INTENT_EPHEMERAL_PUBLIC = 'ephemeral-public';
+export const TUNNEL_INTENT_PERSISTENT_PUBLIC = 'persistent-public';
+export const TUNNEL_INTENT_PRIVATE_NETWORK = 'private-network';
+
+const SUPPORTED_TUNNEL_INTENTS = new Set([
+  TUNNEL_INTENT_EPHEMERAL_PUBLIC,
+  TUNNEL_INTENT_PERSISTENT_PUBLIC,
+  TUNNEL_INTENT_PRIVATE_NETWORK,
+]);
+
+const SUPPORTED_TUNNEL_MODES = new Set([
+  TUNNEL_MODE_QUICK,
+  TUNNEL_MODE_MANAGED_REMOTE,
+  TUNNEL_MODE_MANAGED_LOCAL,
+]);
+
+export class TunnelServiceError extends Error {
+  constructor(code, message, details = null) {
+    super(message);
+    this.name = 'TunnelServiceError';
+    this.code = code;
+    this.details = details;
+  }
+}
+
+const SUPPORTED_TUNNEL_PROVIDERS = new Set([
+  TUNNEL_PROVIDER_CLOUDFLARE,
+]);
+
+export function normalizeTunnelProvider(value) {
+  if (typeof value !== 'string') {
+    return TUNNEL_PROVIDER_CLOUDFLARE;
+  }
+  const provider = value.trim().toLowerCase();
+  if (!provider || !SUPPORTED_TUNNEL_PROVIDERS.has(provider)) {
+    return TUNNEL_PROVIDER_CLOUDFLARE;
+  }
+  return provider;
+}
+
+export function normalizeTunnelMode(value) {
+  if (typeof value !== 'string') {
+    return TUNNEL_MODE_QUICK;
+  }
+  const mode = value.trim().toLowerCase();
+  if (!mode) {
+    return TUNNEL_MODE_QUICK;
+  }
+  if (mode === TUNNEL_MODE_QUICK) {
+    return TUNNEL_MODE_QUICK;
+  }
+  if (mode === TUNNEL_MODE_MANAGED_REMOTE) {
+    return TUNNEL_MODE_MANAGED_REMOTE;
+  }
+  if (mode === TUNNEL_MODE_MANAGED_LOCAL) {
+    return TUNNEL_MODE_MANAGED_LOCAL;
+  }
+  return TUNNEL_MODE_QUICK;
+}
+
+export function normalizeTunnelIntent(value) {
+  if (typeof value !== 'string') {
+    return undefined;
+  }
+  const intent = value.trim().toLowerCase();
+  if (!intent || !SUPPORTED_TUNNEL_INTENTS.has(intent)) {
+    return undefined;
+  }
+  return intent;
+}
+
+function modeIntentFallback(mode) {
+  if (mode === TUNNEL_MODE_QUICK) {
+    return TUNNEL_INTENT_EPHEMERAL_PUBLIC;
+  }
+  if (mode === TUNNEL_MODE_MANAGED_REMOTE || mode === TUNNEL_MODE_MANAGED_LOCAL) {
+    return TUNNEL_INTENT_PERSISTENT_PUBLIC;
+  }
+  return undefined;
+}
+
+function normalizeTunnelModeForRequest(value) {
+  if (typeof value === 'string') {
+    const mode = value.trim().toLowerCase();
+    if (mode === TUNNEL_MODE_QUICK || mode === TUNNEL_MODE_MANAGED_REMOTE || mode === TUNNEL_MODE_MANAGED_LOCAL) {
+      return mode;
+    }
+  }
+  return TUNNEL_MODE_QUICK;
+}
+
+export function normalizeOptionalPath(value) {
+  if (value === null) {
+    return null;
+  }
+  if (typeof value !== 'string') {
+    return undefined;
+  }
+  const trimmed = value.trim();
+  if (!trimmed) {
+    return null;
+  }
+  let resolved;
+  if (trimmed === '~') {
+    resolved = os.homedir();
+  } else if (trimmed.startsWith('~/') || trimmed.startsWith('~\\')) {
+    resolved = path.join(os.homedir(), trimmed.slice(2));
+  } else {
+    resolved = path.resolve(trimmed);
+  }
+  const home = os.homedir();
+  if (resolved !== home && !resolved.startsWith(home + path.sep)) {
+    throw new TunnelServiceError(
+      'validation_error',
+      `Config path must be within the home directory (${home}). Got: ${resolved}`
+    );
+  }
+  return resolved;
+}
+
+export function isSupportedTunnelMode(mode) {
+  return SUPPORTED_TUNNEL_MODES.has(mode);
+}
+
+export function normalizeTunnelStartRequest(input = {}, defaults = {}) {
+  const provider = normalizeTunnelProvider(input.provider ?? defaults.provider);
+  const mode = normalizeTunnelModeForRequest(input.mode ?? defaults.mode);
+  const explicitIntent = normalizeTunnelIntent(input.intent ?? defaults.intent);
+  const intent = explicitIntent ?? modeIntentFallback(mode);
+  const configPathValue = Object.prototype.hasOwnProperty.call(input, 'configPath')
+    ? input.configPath
+    : defaults.configPath;
+  const configPath = normalizeOptionalPath(configPathValue);
+
+  const token = typeof (input.token ?? defaults.token) === 'string'
+    ? (input.token ?? defaults.token).trim()
+    : '';
+
+  const hostname = typeof (input.hostname ?? defaults.hostname) === 'string'
+    ? (input.hostname ?? defaults.hostname).trim().toLowerCase()
+    : '';
+
+  return {
+    provider,
+    mode,
+    intent,
+    configPath,
+    token,
+    hostname,
+  };
+}
+
+export function validateTunnelStartRequest(request, capabilities) {
+  if (!request || typeof request !== 'object') {
+    throw new TunnelServiceError('validation_error', 'Tunnel start request must be an object');
+  }
+
+  if (!request.provider) {
+    throw new TunnelServiceError('validation_error', 'Tunnel provider is required');
+  }
+
+  if (!isSupportedTunnelMode(request.mode)) {
+    throw new TunnelServiceError('mode_unsupported', `Unsupported tunnel mode: ${request.mode}`);
+  }
+
+  if (!capabilities || capabilities.provider !== request.provider) {
+    throw new TunnelServiceError('provider_unsupported', `Unsupported tunnel provider: ${request.provider}`);
+  }
+
+  if (!Array.isArray(capabilities.modes)) {
+    throw new TunnelServiceError('mode_unsupported', `Provider '${request.provider}' does not declare tunnel modes`);
+  }
+
+  const modeDescriptor = capabilities.modes.find((entry) => entry?.key === request.mode);
+  if (!modeDescriptor) {
+    throw new TunnelServiceError('mode_unsupported', `Provider '${request.provider}' does not support mode '${request.mode}'`);
+  }
+
+  if (typeof request.intent === 'string' && request.intent.length > 0) {
+    if (!SUPPORTED_TUNNEL_INTENTS.has(request.intent)) {
+      throw new TunnelServiceError('validation_error', `Unsupported tunnel intent: ${request.intent}`);
+    }
+    if (modeDescriptor.intent !== request.intent) {
+      throw new TunnelServiceError(
+        'validation_error',
+        `Tunnel intent '${request.intent}' does not match mode '${request.mode}' (expected '${modeDescriptor.intent}')`
+      );
+    }
+  }
+
+  const requiredFields = Array.isArray(modeDescriptor.requires) ? modeDescriptor.requires : [];
+
+  if (requiredFields.includes('token')) {
+    if (!request.token) {
+      throw new TunnelServiceError('validation_error', 'Managed remote tunnel token is required');
+    }
+  }
+
+  if (requiredFields.includes('hostname')) {
+    if (!request.hostname) {
+      throw new TunnelServiceError('validation_error', 'Managed remote tunnel hostname is required');
+    }
+  }
+
+  if (requiredFields.includes('configPath')) {
+    if (request.configPath === undefined || request.configPath === null || request.configPath === '') {
+      throw new TunnelServiceError('validation_error', `Mode '${request.mode}' requires a configPath`);
+    }
+  }
+}

package/server/lib/utils/lru.js

@@ -0,0 +1,107 @@
+export function createLruMap(maxEntries, onEvict) {
+  const map = new Map();
+  const accessOrder = new Map();
+  let accessCounter = 0;
+
+  const touch = (key) => {
+    accessOrder.set(key, accessCounter++);
+  };
+
+  const evictIfNeeded = () => {
+    if (map.size <= maxEntries) return;
+    
+    let oldestKey = null;
+    let oldestAccess = Infinity;
+    
+    for (const [key, access] of accessOrder) {
+      if (access < oldestAccess) {
+        oldestAccess = access;
+        oldestKey = key;
+      }
+    }
+    
+    if (oldestKey !== null) {
+      const value = map.get(oldestKey);
+      map.delete(oldestKey);
+      accessOrder.delete(oldestKey);
+      if (onEvict && value !== undefined) {
+        onEvict(oldestKey, value);
+      }
+    }
+  };
+
+  return {
+    get: (key) => {
+      const value = map.get(key);
+      if (value !== undefined) {
+        touch(key);
+      }
+      return value;
+    },
+
+    set: (key, value) => {
+      if (map.has(key)) {
+        map.set(key, value);
+        touch(key);
+      } else {
+        evictIfNeeded();
+        map.set(key, value);
+        touch(key);
+      }
+    },
+
+    delete: (key) => {
+      const deleted = map.delete(key);
+      accessOrder.delete(key);
+      return deleted;
+    },
+
+    has: (key) => {
+      return map.has(key);
+    },
+
+    clear: () => {
+      map.clear();
+      accessOrder.clear();
+    },
+
+    get size() {
+      return map.size;
+    },
+
+    entries: () => {
+      return map.entries();
+    },
+
+    keys: () => {
+      return map.keys();
+    },
+
+    values: () => {
+      return map.values();
+    },
+  };
+}
+
+const EVICTION_WARNING_THRESHOLD = 10;
+const EVICTION_WINDOW_MS = 60000;
+
+export function createLruMapWithWarnings(maxEntries, mapName) {
+  let evictionCount = 0;
+  let lastWarning = 0;
+
+  const lruMap = createLruMap(maxEntries, () => {
+    evictionCount++;
+    const now = Date.now();
+    
+    if (evictionCount >= EVICTION_WARNING_THRESHOLD && now - lastWarning > EVICTION_WINDOW_MS) {
+      console.warn(`[LRU] ${mapName}: ${evictionCount} evictions in the last minute. Consider increasing maxEntries (current: ${maxEntries})`);
+      lastWarning = now;
+    }
+  });
+
+  return {
+    ...lruMap,
+    getEvictionStats: () => ({ count: evictionCount, lastWarning }),
+  };
+}