@jsenv/server 13.1.0 → 14.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jsenv/server",
-  "version": "13.1.0",
+  "version": "14.0.0",
   "description": "Write your Node.js server using pure functions",
   "license": "MIT",
   "author": {

package/src/internal/hostname_parser.js

@@ -0,0 +1,48 @@
+import { isIP } from "node:net"
+
+export const parseHostname = (hostname) => {
+  if (hostname === "0.0.0.0") {
+    return {
+      type: "ip",
+      label: "unspecified",
+      version: 4,
+    }
+  }
+  if (
+    hostname === "::" ||
+    hostname === "0000:0000:0000:0000:0000:0000:0000:0000"
+  ) {
+    return {
+      type: "ip",
+      label: "unspecified",
+      version: 6,
+    }
+  }
+  if (hostname === "127.0.0.1") {
+    return {
+      type: "ip",
+      label: "loopback",
+      version: 4,
+    }
+  }
+  if (
+    hostname === "::1" ||
+    hostname === "0000:0000:0000:0000:0000:0000:0000:0001"
+  ) {
+    return {
+      type: "ip",
+      label: "loopback",
+      version: 6,
+    }
+  }
+  const ipVersion = isIP(hostname)
+  if (ipVersion === 0) {
+    return {
+      type: "hostname",
+    }
+  }
+  return {
+    type: "ip",
+    version: ipVersion,
+  }
+}

package/src/internal/listen.js

@@ -6,7 +6,7 @@ const listen = async ({
   server,
   port,
   portHint,
-  host,
+  hostname,
 }) => {
   const listeningOperation = Abort.startOperation()
 
@@ -17,11 +17,11 @@ const listen = async ({
       listeningOperation.throwIfAborted()
       port = await findFreePort(portHint, {
         signal: listeningOperation.signal,
-        host,
+        hostname,
       })
     }
     listeningOperation.throwIfAborted()
-    port = await startListening({ server, port, host })
+    port = await startListening({ server, port, hostname })
     listeningOperation.addAbortCallback(() => stopListening(server))
     listeningOperation.throwIfAborted()
 
@@ -35,7 +35,7 @@ export const findFreePort = async (
   initialPort = 1,
   {
     signal = new AbortController().signal,
-    host = "127.0.0.1",
+    hostname = "127.0.0.1",
     min = 1,
     max = 65534,
     next = (port) => port + 1,
@@ -56,26 +56,26 @@ export const findFreePort = async (
       const nextPort = next(port)
       if (nextPort > max) {
         throw new Error(
-          `${host} has no available port between ${min} and ${max}`,
+          `${hostname} has no available port between ${min} and ${max}`,
         )
       }
-      return testUntil(nextPort, host)
+      return testUntil(nextPort, hostname)
     }
-    const freePort = await testUntil(initialPort, host)
+    const freePort = await testUntil(initialPort, hostname)
     return freePort
   } finally {
     await findFreePortOperation.end()
   }
 }
 
-const portIsFree = async (port, host) => {
+const portIsFree = async (port, hostname) => {
   const server = createServer()
 
   try {
     await startListening({
       server,
       port,
-      host,
+      hostname,
     })
   } catch (error) {
     if (error && error.code === "EADDRINUSE") {
@@ -91,7 +91,7 @@ const portIsFree = async (port, host) => {
   return true
 }
 
-const startListening = ({ server, port, host }) => {
+const startListening = ({ server, port, hostname }) => {
   return new Promise((resolve, reject) => {
     server.on("error", reject)
     server.on("listening", () => {
@@ -99,7 +99,7 @@ const startListening = ({ server, port, host }) => {
       // https://nodejs.org/api/net.html#net_server_listen_port_host_backlog_callback
       resolve(server.address().port)
     })
-    server.listen(port, host)
+    server.listen(port, hostname)
   })
 }
 

package/src/internal/server_ips.js

@@ -0,0 +1,49 @@
+import { networkInterfaces } from "node:os"
+
+export const createIpGetters = () => {
+  const networkAddresses = []
+  const networkInterfaceMap = networkInterfaces()
+  for (const key of Object.keys(networkInterfaceMap)) {
+    for (const networkAddress of networkInterfaceMap[key]) {
+      networkAddresses.push(networkAddress)
+    }
+  }
+  return {
+    getFirstInternalIp: ({ preferIpv6 }) => {
+      const isPref = preferIpv6 ? isIpV6 : isIpV4
+      let firstInternalIp
+      for (const networkAddress of networkAddresses) {
+        if (networkAddress.internal) {
+          firstInternalIp = networkAddress.address
+          if (isPref(networkAddress)) {
+            break
+          }
+        }
+      }
+      return firstInternalIp
+    },
+    getFirstExternalIp: ({ preferIpv6 }) => {
+      const isPref = preferIpv6 ? isIpV6 : isIpV4
+      let firstExternalIp
+      for (const networkAddress of networkAddresses) {
+        if (!networkAddress.internal) {
+          firstExternalIp = networkAddress.address
+          if (isPref(networkAddress)) {
+            break
+          }
+        }
+      }
+      return firstExternalIp
+    },
+  }
+}
+
+const isIpV4 = (networkAddress) => {
+  // node 18.5
+  if (typeof networkAddress.family === "number") {
+    return networkAddress.family === 4
+  }
+  return networkAddress.family === "IPv4"
+}
+
+const isIpV6 = (networkAddress) => !isIpV4(networkAddress)

package/src/start_server.js

@@ -1,3 +1,4 @@
+import { isIP } from "node:net"
 import http from "node:http"
 import cluster from "node:cluster"
 import { createDetailedMessage, createLogger } from "@jsenv/log"
@@ -23,7 +24,6 @@ import {
   statusToType,
   colorizeResponseStatus,
 } from "./internal/colorizeResponseStatus.js"
-import { getServerOrigins } from "./internal/getServerOrigins.js"
 import { listen, stopListening } from "./internal/listen.js"
 import { composeTwoResponses } from "./internal/response_composition.js"
 import { listenRequest } from "./internal/listenRequest.js"
@@ -40,6 +40,10 @@ import {
 } from "./stopReasons.js"
 import { composeTwoHeaders } from "./internal/headers_composition.js"
 
+import { createIpGetters } from "./internal/server_ips.js"
+import { parseHostname } from "./internal/hostname_parser.js"
+import { applyDnsResolution } from "./internal/dns_resolution.js"
+
 export const startServer = async ({
   signal = new AbortController().signal,
   logLevel,
@@ -52,7 +56,8 @@ export const startServer = async ({
   redirectHttpToHttps,
   allowHttpRequestOnHttps = false,
   acceptAnyIp = false,
-  host = acceptAnyIp ? undefined : "localhost",
+  preferIpv6,
+  hostname = "localhost",
   port = 0, // assign a random available port
   portHint,
   privateKey,
@@ -83,6 +88,8 @@ export const startServer = async ({
     )
   },
 } = {}) => {
+  const logger = createLogger({ logLevel })
+
   if (protocol !== "http" && protocol !== "https") {
     throw new Error(`protocol must be http or https, got ${protocol}`)
   }
@@ -98,7 +105,6 @@ export const startServer = async ({
     throw new Error(`http2 needs "https" but protocol is "${protocol}"`)
   }
 
-  const logger = createLogger({ logLevel })
   if (
     redirectHttpToHttps === undefined &&
     protocol === "https" &&
@@ -137,6 +143,9 @@ export const startServer = async ({
   let nodeServer
   const startServerOperation = Abort.startOperation()
   const stopCallbackList = createCallbackListNotifiedOnce()
+  const serverOrigins = {
+    local: "", // favors hostname when possible
+  }
 
   try {
     startServerOperation.addAbortSignal(signal)
@@ -163,12 +172,73 @@ export const startServer = async ({
       nodeServer.unref()
     }
 
+    const createOrigin = (hostname) => {
+      if (isIP(hostname) === 6) {
+        return `${protocol}://[${hostname}]`
+      }
+      return `${protocol}://${hostname}`
+    }
+
+    const ipGetters = createIpGetters()
+    let hostnameToListen
+    if (acceptAnyIp) {
+      const firstInternalIp = ipGetters.getFirstInternalIp({ preferIpv6 })
+      serverOrigins.local = createOrigin(firstInternalIp)
+      serverOrigins.localip = createOrigin(firstInternalIp)
+      const firstExternalIp = ipGetters.getFirstExternalIp({ preferIpv6 })
+      serverOrigins.externalip = createOrigin(firstExternalIp)
+      hostnameToListen = preferIpv6 ? "::" : "0.0.0.0"
+    } else {
+      hostnameToListen = hostname
+    }
+    const hostnameInfo = parseHostname(hostname)
+    if (hostnameInfo.type === "ip") {
+      if (acceptAnyIp) {
+        throw new Error(
+          `hostname cannot be an ip when acceptAnyIp is enabled, got ${hostname}`,
+        )
+      }
+
+      preferIpv6 = hostnameInfo.version === 6
+      const firstInternalIp = ipGetters.getFirstInternalIp({ preferIpv6 })
+      serverOrigins.local = createOrigin(firstInternalIp)
+      serverOrigins.localip = createOrigin(firstInternalIp)
+      if (hostnameInfo.label === "unspecified") {
+        const firstExternalIp = ipGetters.getFirstExternalIp({ preferIpv6 })
+        serverOrigins.externalip = createOrigin(firstExternalIp)
+      } else if (hostnameInfo.label === "loopback") {
+      } else {
+        serverOrigins.local = createOrigin(hostname)
+      }
+    } else {
+      const hostnameDnsResolution = await applyDnsResolution(hostname, {
+        verbatim: true,
+      })
+      if (hostnameDnsResolution) {
+        const hostnameIp = hostnameDnsResolution.address
+        serverOrigins.localip = createOrigin(hostnameIp)
+        serverOrigins.local = createOrigin(hostname)
+      } else {
+        const firstInternalIp = ipGetters.getFirstInternalIp({ preferIpv6 })
+        // fallback to internal ip because there is no ip
+        // associated to this hostname on operating system (in hosts file)
+        hostname = firstInternalIp
+        hostnameToListen = firstInternalIp
+        serverOrigins.local = createOrigin(firstInternalIp)
+      }
+    }
+
     port = await listen({
       signal: startServerOperation.signal,
       server: nodeServer,
       port,
       portHint,
-      host,
+      hostname: hostnameToListen,
+    })
+
+    // normalize origins (remove :80 when port is 80 for instance)
+    Object.keys(serverOrigins).forEach((key) => {
+      serverOrigins[key] = new URL(`${serverOrigins[key]}:${port}`).origin
     })
 
     serviceController.callHooks("serverListening", { port })
@@ -180,6 +250,18 @@ export const startServer = async ({
     await startServerOperation.end()
   }
 
+  // the main server origin
+  // - when protocol is http
+  //   node-fetch do not apply local dns resolution to map localhost back to 127.0.0.1
+  //   despites localhost being mapped so we prefer to use the internal ip
+  //   (127.0.0.1)
+  // - when protocol is https
+  //   using the hostname becomes important because the certificate is generated
+  //   for hostnames, not for ips
+  //   so we prefer https://locahost or https://local_hostname
+  //   over the ip
+  const serverOrigin = serverOrigins.local
+
   // now the server is started (listening) it cannot be aborted anymore
   // (otherwise an AbortError is thrown to the code calling "startServer")
   // we can proceed to create a stop function to stop it gacefully
@@ -218,8 +300,6 @@ export const startServer = async ({
   }
 
   status = "opened"
-  const serverOrigins = await getServerOrigins({ protocol, host, port })
-  const serverOrigin = serverOrigins.local
 
   const removeConnectionErrorListener = listenServerConnectionError(
     nodeServer,
@@ -829,7 +909,9 @@ export const startServer = async ({
       const { WebSocketServer } = await import("ws")
       let websocketServer = new WebSocketServer({ noServer: true })
       const websocketOrigin =
-        protocol === "https" ? `wss://${host}:${port}` : `ws://${host}:${port}`
+        protocol === "https"
+          ? `wss://${hostname}:${port}`
+          : `ws://${hostname}:${port}`
       server.websocketOrigin = websocketOrigin
       const upgradeCallback = (nodeRequest, socket, head) => {
         websocketServer.handleUpgrade(
@@ -884,6 +966,7 @@ export const startServer = async ({
   Object.assign(server, {
     getStatus: () => status,
     port,
+    hostname,
     origin: serverOrigin,
     origins: serverOrigins,
     nodeServer,

package/src/internal/getServerOrigins.js

@@ -1,74 +0,0 @@
-import { networkInterfaces } from "node:os"
-
-import { applyDnsResolution } from "./dns_resolution.js"
-
-export const getServerOrigins = async ({ protocol, host, port }) => {
-  const isLocal = LOOPBACK_HOSTNAMES.includes(host)
-  const localhostDnsResolution = await applyDnsResolution("localhost")
-  const localOrigin = createServerOrigin({
-    protocol,
-    hostname:
-      localhostDnsResolution.address === "127.0.0.1"
-        ? "localhost"
-        : "127.0.0.1",
-    port,
-  })
-  if (isLocal) {
-    return { local: localOrigin }
-  }
-  const isAnyIp = WILDCARD_HOSTNAMES.includes(host)
-  const networkOrigin = createServerOrigin({
-    protocol,
-    hostname: isAnyIp ? getExternalIp() : host,
-    port,
-  })
-  return {
-    local: localOrigin,
-    network: networkOrigin,
-  }
-}
-
-const LOOPBACK_HOSTNAMES = [
-  "localhost",
-  "127.0.0.1",
-  "::1",
-  "0000:0000:0000:0000:0000:0000:0000:0001",
-]
-
-const WILDCARD_HOSTNAMES = [
-  undefined,
-  "0.0.0.0",
-  "::",
-  "0000:0000:0000:0000:0000:0000:0000:0000",
-]
-
-const createServerOrigin = ({ protocol, hostname, port }) => {
-  const url = new URL("https://127.0.0.1:80")
-  url.protocol = protocol
-  url.hostname = hostname
-  url.port = port
-  return url.origin
-}
-
-const getExternalIp = () => {
-  const networkInterfaceMap = networkInterfaces()
-  let internalIPV4NetworkAddress
-  Object.keys(networkInterfaceMap).find((key) => {
-    const networkAddressArray = networkInterfaceMap[key]
-    return networkAddressArray.find((networkAddress) => {
-      if (networkAddress.internal) return false
-      if (!isIpV4(networkAddress)) return false
-      internalIPV4NetworkAddress = networkAddress
-      return true
-    })
-  })
-  return internalIPV4NetworkAddress ? internalIPV4NetworkAddress.address : null
-}
-
-const isIpV4 = (networkAddress) => {
-  // node 18+
-  if (typeof networkAddress.family === "number") {
-    return networkAddress.family === 4
-  }
-  return networkAddress.family === "IPv4"
-}