ipv6-bridge 1.0.0 → 2.1.1

package/src/connect.js

@@ -0,0 +1,142 @@
+/**
+ * IPv6 Bridge - Outbound connection handling
+ *
+ * Establishes upstream connections with failover across the candidate
+ * addresses produced by DNS64, and provides a pooling HTTP agent so repeated
+ * requests to the same host reuse sockets.
+ *
+ * @module connect
+ */
+
+const http = require('http');
+const net = require('net');
+const { resolveCandidates } = require('./dns64');
+const config = require('./config');
+const stats = require('./stats');
+const log = require('./logger');
+
+/**
+ * Open a TCP connection to one candidate address.
+ *
+ * @param {{host: string, family: number}} candidate - Address to try
+ * @param {number} port - Destination port
+ * @param {number} timeout - Per-attempt timeout in milliseconds
+ * @returns {Promise<net.Socket>} Connected socket
+ */
+function attempt(candidate, port, timeout) {
+  return new Promise((resolve, reject) => {
+    const socket = net.connect({
+      host: candidate.host,
+      port,
+      family: candidate.family,
+    });
+
+    const fail = (err) => {
+      socket.destroy();
+      reject(err);
+    };
+
+    socket.setTimeout(timeout, () => {
+      fail(Object.assign(new Error(
+        `Connection to ${candidate.host}:${port} timed out after ${timeout}ms`
+      ), { code: 'ETIMEDOUT' }));
+    });
+
+    socket.once('error', fail);
+
+    socket.once('connect', () => {
+      socket.setTimeout(0);
+      socket.removeListener('error', fail);
+      resolve(socket);
+    });
+  });
+}
+
+/**
+ * Connect to a host, trying each candidate address in preference order.
+ *
+ * A single unreachable address is the normal case on a partially broken
+ * network, so failing on the first attempt would make the bridge far less
+ * reliable than the stack it replaces.
+ *
+ * @param {string} hostname - Target hostname or IP literal
+ * @param {number} port - Destination port
+ * @param {object} [options] - Options
+ * @param {boolean} [options.bypass] - Connect directly, skipping NAT64
+ * @returns {Promise<{socket: net.Socket, candidate: object}>} Connected socket and the candidate used
+ */
+async function connectWithFallback(hostname, port, { bypass = false } = {}) {
+  const candidates = bypass
+    ? [{ host: hostname, family: 0, mode: 'bypassed' }]
+    : await resolveCandidates(hostname);
+
+  const attemptTimeout = Math.min(
+    config.CONNECT_ATTEMPT_TIMEOUT,
+    config.CONNECTION_TIMEOUT
+  );
+
+  const failures = [];
+
+  for (const candidate of candidates) {
+    try {
+      const socket = await attempt(candidate, port, attemptTimeout);
+
+      if (failures.length > 0) {
+        log.debug(
+          `Connected to ${hostname}:${port} via ${candidate.host} (${candidate.mode}) ` +
+          `after ${failures.length} failed candidate(s)`
+        );
+      }
+
+      if (candidate.mode === 'direct-ipv4' && candidates.some((c) => c.mode === 'nat64')) {
+        log.warn(
+          `NAT64 route to ${hostname} failed; connected directly over IPv4 instead. ` +
+          `This request is NOT being translated.`
+        );
+        stats.recordRoute('direct-ipv4-fallback');
+      } else {
+        stats.recordRoute(candidate.mode);
+      }
+
+      return { socket, candidate };
+    } catch (err) {
+      failures.push(`${candidate.host} (${err.code || err.message})`);
+    }
+  }
+
+  const error = new Error(
+    `Unable to connect to ${hostname}:${port}; tried ${failures.join(', ')}`
+  );
+  error.code = 'EHOSTUNREACH';
+  throw error;
+}
+
+/**
+ * HTTP agent that resolves through DNS64 and pools the resulting sockets.
+ *
+ * Sockets are keyed by the original hostname, so pooling survives the fact
+ * that the address the bridge dials is synthesized rather than literal.
+ */
+class BridgeAgent extends http.Agent {
+  constructor(options = {}) {
+    super({
+      keepAlive: true,
+      keepAliveMsecs: config.KEEP_ALIVE_MS,
+      maxSockets: config.MAX_SOCKETS_PER_HOST,
+      timeout: config.CONNECTION_TIMEOUT,
+      ...options,
+    });
+  }
+
+  createConnection(options, callback) {
+    const hostname = options.host;
+    const port = Number(options.port) || 80;
+    const bypass = !config.BYPASS.isEmpty && config.BYPASS.matches(hostname);
+
+    connectWithFallback(hostname, port, { bypass })
+      .then(({ socket }) => callback(null, socket))
+      .catch((err) => callback(err));
+  }
+}
+
+module.exports = { connectWithFallback, BridgeAgent, attempt };

package/src/detect.js

@@ -1,77 +1,116 @@
 /**
  * IPv6 Bridge - Network Detection
  *
- * Detects whether the system is on an IPv6-only network and whether
- * the bridge is needed to reach IPv4-only servers.
+ * Decides whether the bridge is needed. The bridge only helps a host that has
+ * IPv6 but cannot reach IPv4-only servers, so detection has to establish both
+ * facts before reporting that it is needed.
  *
  * @module detect
  */
 
 const http = require('http');
 const { resolveIPv6 } = require('./dns64');
-const { IPV6_GOOGLE, IPV4_GOOGLE } = require('./config');
+const config = require('./config');
+const log = require('./logger');
+
+const {
+  IPV6_TEST_URL,
+  IPV4_TEST_URL,
+  NAT64_TEST_HOST,
+  DNS_TIMEOUT,
+} = config;
 
 /**
- * Test if the network has IPv6 connectivity.
+ * Probe a URL over a specific IP family.
  *
- * Connects to an IPv6-capable server to verify that IPv6 is available.
+ * Any 2xx or 3xx response counts as reachable; requiring exactly 200 would
+ * misreport a network as broken the moment the endpoint starts redirecting.
  *
- * @returns {Promise<boolean>} true if IPv6 is available
+ * @param {string} url - URL to request
+ * @param {number} family - IP family (4 or 6)
+ * @returns {Promise<boolean>} true if the endpoint responded
  */
-async function hasIPv6() {
+function probe(url, family) {
   return new Promise((resolve) => {
-    const req = http.get(IPV6_GOOGLE, { family: 6 }, (res) => {
-      // Consume response body to free resources
+    let settled = false;
+    const finish = (result) => {
+      if (settled) return;
+      settled = true;
+      resolve(result);
+    };
+
+    const req = http.get(url, { family }, (res) => {
       res.resume();
-      resolve(res.statusCode === 200);
+      finish(res.statusCode >= 200 && res.statusCode < 400);
     });
-    req.on('error', () => resolve(false));
-    req.setTimeout(5000, () => {
+
+    req.on('error', () => finish(false));
+    req.setTimeout(DNS_TIMEOUT, () => {
       req.destroy();
-      resolve(false);
+      finish(false);
     });
   });
 }
 
 /**
- * Determine if the bridge is needed.
+ * Test whether the network has working IPv6 connectivity.
+ *
+ * @returns {Promise<boolean>} true if IPv6 is available
+ */
+function hasIPv6() {
+  return probe(IPV6_TEST_URL, 6);
+}
+
+/**
+ * Test whether the network has working IPv4 connectivity.
  *
- * The bridge is needed when:
- * 1. IPv6 is available, AND
- * 2. IPv4 servers are NOT reachable via the ISP's NAT64 gateway
+ * @returns {Promise<boolean>} true if IPv4 is available
+ */
+function hasIPv4() {
+  return probe(IPV4_TEST_URL, 4);
+}
+
+/**
+ * Test whether an upstream NAT64 gateway is already translating traffic.
  *
- * @returns {Promise<boolean>} true if bridge is needed
+ * @returns {Promise<boolean>} true if NAT64 works without the bridge
+ */
+async function hasWorkingNAT64() {
+  try {
+    const addresses = await resolveIPv6(NAT64_TEST_HOST);
+    if (!addresses || addresses.length === 0) return false;
+    return await probe(`http://[${addresses[0]}]`, 6);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Determine whether the bridge is needed.
+ *
+ * The bridge is needed only when IPv4 is unreachable, IPv6 works, and the
+ * network provides no NAT64 gateway of its own.
+ *
+ * @returns {Promise<boolean>} true if the bridge is needed
  */
 async function needsBridge() {
-  const hasV6 = await hasIPv6();
-  if (!hasV6) {
-    // No IPv6 means we're on IPv4 or a broken network.
-    // Either way, the bridge can't help.
+  if (await hasIPv4()) {
+    log.debug('IPv4 connectivity works; bridge is not needed');
     return false;
   }
 
-  try {
-    const ipv6 = await resolveIPv6(IPV4_GOOGLE);
-    if (!ipv6 || ipv6.length === 0) {
-      return true;
-    }
+  if (!await hasIPv6()) {
+    log.debug('Neither IPv4 nor IPv6 connectivity works; the bridge cannot help');
+    return false;
+  }
 
-    // Try connecting to the synthesized IPv6 address.
-    // If this works, the ISP has a working NAT64 gateway.
-    return new Promise((resolve) => {
-      const req = http.get(`http://[${ipv6[0]}]`, { family: 6 }, (res) => {
-        res.resume();
-        resolve(res.statusCode !== 200);
-      });
-      req.on('error', () => resolve(true));
-      req.setTimeout(5000, () => {
-        req.destroy();
-        resolve(true);
-      });
-    });
-  } catch {
-    return true;
+  if (await hasWorkingNAT64()) {
+    log.debug('Upstream NAT64 gateway is already working; bridge is not needed');
+    return false;
   }
+
+  log.debug('IPv6-only network with no working NAT64; bridge is needed');
+  return true;
 }
 
-module.exports = { hasIPv6, needsBridge };
+module.exports = { hasIPv6, hasIPv4, hasWorkingNAT64, needsBridge };

package/src/discovery.js

@@ -0,0 +1,122 @@
+/**
+ * IPv6 Bridge - NAT64 prefix discovery (RFC 7050)
+ *
+ * Networks that provide NAT64 rarely use the well-known prefix; most operators
+ * assign their own. RFC 7050 defines how to find it: resolve AAAA records for
+ * the special name "ipv4only.arpa", whose only real records are the two IPv4
+ * addresses below. A DNS64 resolver synthesizes AAAA records for that name, so
+ * whatever wraps those known IPv4 addresses is the network's NAT64 prefix.
+ *
+ * @module discovery
+ */
+
+const { lookupAll } = require('./dns64');
+const { parseIPv6, formatIPv6, extractIPv4, VALID_PREFIX_LENGTHS } = require('./ipv6');
+const config = require('./config');
+const log = require('./logger');
+
+/** The well-known name and its fixed IPv4 addresses (RFC 7050 section 3). */
+const DISCOVERY_NAME = 'ipv4only.arpa';
+const WELL_KNOWN_IPV4 = ['192.0.0.170', '192.0.0.171'];
+
+/**
+ * Derive the NAT64 prefix from a synthesized IPv4-embedded address.
+ *
+ * @param {string} address - Synthesized IPv6 address
+ * @returns {{prefix: string, length: number, bytes: Buffer}|null} Prefix, or null if no match
+ */
+function prefixFromSynthesized(address) {
+  for (const length of VALID_PREFIX_LENGTHS) {
+    const embedded = extractIPv4(address, length);
+    if (!embedded || !WELL_KNOWN_IPV4.includes(embedded)) continue;
+
+    const bytes = parseIPv6(address);
+    if (!bytes) continue;
+
+    // Zero everything after the prefix to get the prefix itself.
+    const prefixBytes = Buffer.from(bytes);
+    for (let bit = length; bit < 128; bit++) {
+      const index = Math.floor(bit / 8);
+      prefixBytes[index] &= ~(1 << (7 - (bit % 8))) & 0xff;
+    }
+
+    return { prefix: formatIPv6(prefixBytes), length, bytes: prefixBytes };
+  }
+
+  return null;
+}
+
+/**
+ * Discover the NAT64 prefix this network uses.
+ *
+ * @param {object} [options] - Options
+ * @param {number} [options.timeout] - DNS timeout in milliseconds
+ * @returns {Promise<{prefix: string, length: number, bytes: Buffer, source: string}|null>}
+ *   The discovered prefix, or null if the network provides no DNS64 resolver
+ */
+async function discoverPrefix({ timeout = config.DNS_TIMEOUT } = {}) {
+  let records;
+  try {
+    records = await lookupAll(DISCOVERY_NAME, timeout);
+  } catch (err) {
+    log.debug(`NAT64 prefix discovery: ${DISCOVERY_NAME} did not resolve (${err.code || err.message})`);
+    return null;
+  }
+
+  const synthesized = records.filter((r) => r.family === 6).map((r) => r.address);
+  if (synthesized.length === 0) {
+    log.debug('NAT64 prefix discovery: no AAAA records, so this resolver does not provide DNS64');
+    return null;
+  }
+
+  for (const address of synthesized) {
+    const found = prefixFromSynthesized(address);
+    if (found) {
+      return { ...found, source: address };
+    }
+  }
+
+  log.debug(
+    `NAT64 prefix discovery: ${DISCOVERY_NAME} returned ${synthesized.join(', ')}, ` +
+    `but no RFC 6052 prefix length embeds ${WELL_KNOWN_IPV4.join(' or ')}`
+  );
+  return null;
+}
+
+/**
+ * Discover the prefix and adopt it if it differs from the configured one.
+ *
+ * @returns {Promise<{prefix: string, length: number}|null>} The adopted prefix, if any
+ */
+async function discoverAndApply() {
+  const discovered = await discoverPrefix();
+  if (!discovered) return null;
+
+  const current = config.getPrefix();
+  const spec = `${discovered.prefix}/${discovered.length}`;
+
+  if (current.prefix === discovered.prefix && current.length === discovered.length) {
+    log.debug(`NAT64 prefix discovery confirmed the configured prefix ${spec}`);
+    return discovered;
+  }
+
+  if (process.env.NAT64_PREFIX) {
+    log.warn(
+      `This network advertises NAT64 prefix ${spec}, but NAT64_PREFIX is set to ` +
+      `${current.prefix}/${current.length}. Keeping the configured value.`
+    );
+    return null;
+  }
+
+  log.info(`Discovered NAT64 prefix ${spec} via ${DISCOVERY_NAME} (RFC 7050)`);
+  config.setPrefix(discovered);
+  return discovered;
+}
+
+module.exports = {
+  DISCOVERY_NAME,
+  WELL_KNOWN_IPV4,
+  discoverPrefix,
+  discoverAndApply,
+  prefixFromSynthesized,
+};