@jsenv/server 12.7.5 → 13.1.0

package/README.md

@@ -8,42 +8,23 @@ import { startServer } from "@jsenv/server"
 await startServer({
   protocol: "http",
   port: 8080,
-  requestToResponse: () => {
-    return {
-      status: 200,
-      headers: {
-        "content-type": "text/plain",
+  services: [
+    {
+      handleRequest: () => {
+        return {
+          status: 200,
+          headers: {
+            "content-type": "text/plain",
+          },
+          body: "Hello world",
+        }
       },
-      body: "Hello world",
-    }
-  },
+    },
+  ],
 })
 ```
 
-# Example
-
-_Code starting a server and using [node-fetch](https://github.com/node-fetch/node-fetch) to send a request on that server:_
-
-```js
-import fetch from "node-fetch"
-import { startServer } from "@jsenv/server"
-
-const server = await startServer({
-  requestToResponse: () => {
-    return {
-      status: 200,
-      headers: {
-        "content-type": "text/plain",
-      },
-      body: "Hello world",
-    }
-  },
-})
-
-const response = await fetch(server.origin)
-const responseBodyAsText = await response.text()
-console.log(responseBodyAsText) // "Hello world"
-```
+# Examples
 
 _Code starting a server with 2 request handlers:_
 
@@ -57,22 +38,24 @@ _Code starting a server with 2 request handlers:_
  */
 import { startServer, composeServices } from "@jsenv/server"
 
-const indexService = (request) => {
-  if (request.ressource === "/") {
-    return { status: 200 }
-  }
-  return null // means "I don't handle that request"
-}
-
-const notFoundService = (request) => {
-  return { status: 404 }
-}
-
 const server = await startServer({
-  requestToResponse: composeServices({
-    index: indexService,
-    otherwise: notFoundService,
-  }),
+  services: [
+    {
+      name: "index",
+      handleRequest: (request) => {
+        if (request.ressource === "/") {
+          return { status: 200 }
+        }
+        return null
+      },
+    },
+    {
+      name: "otherwise",
+      handleRequest: () => {
+        return { status: 404 }
+      },
+    },
+  ],
 })
 
 const fetch = await import("node-fetch")
@@ -91,26 +74,25 @@ import { startServer } from "@jsenv/server"
 
 await startServer({
   protocol: "https",
-  certificate: readFileSyncAsString("./server.crt"),
-  privateKey: readFileSyncAsString("./server.key"),
+  certificate: readFileSync(new URL("./server.crt", import.meta.url), "utf8"),
+  privateKey: readFileSync(new URL("./server.key", import.meta.url), "utf8"),
   allowHttpRequestOnHttps: true,
-  requestToResponse: (request) => {
-    const clientUsesHttp = request.origin.startsWith("http:")
-
-    return {
-      status: 200,
-      headers: {
-        "content-type": "text/plain",
+  services: [
+    {
+      handleRequest: (request) => {
+        const clientUsesHttp = request.origin.startsWith("http:")
+
+        return {
+          status: 200,
+          headers: {
+            "content-type": "text/plain",
+          },
+          body: clientUsesHttp ? `Welcome http user` : `Welcome https user`,
+        }
       },
-      body: clientUsesHttp ? `Welcome http user` : `Welcome https user`,
-    }
-  },
+    },
+  ],
 })
-
-function readFileSyncAsString(relativeUrl) {
-  const fileUrl = new URL(relativeUrl, import.meta.url)
-  return String(readFileSync(fileUrl))
-}
 ```
 
 _Code starting a server for static files:_
@@ -119,28 +101,31 @@ _Code starting a server for static files:_
 import { startServer, fetchFileSystem } from "@jsenv/server"
 
 await startServer({
-  requestToResponse: async (request) => {
-    const fileUrl = new URL(request.ressource.slice(1), import.meta.url)
-    const response = await fetchFileSystem(fileUrl, {
-      ...request,
-    })
-    return response
-  },
+  services: [
+    {
+      handleRequest: async (request) => {
+        const fileUrl = new URL(request.ressource.slice(1), import.meta.url)
+        const response = await fetchFileSystem(fileUrl, request)
+        return response
+      },
+    },
+  ],
 })
 ```
 
 # Documentation
 
-- [https](./docs/https/https.md)
-- [Serving files](./docs/serving_files/serving_files.md)
-- [Handling requests](./docs/handling_requests/handling_requests.md)
-- [Handling errors](./docs/handling_errors/handling_errors.md)
-- [Server timing](./docs/server_timing/server_timing.md)
-- [CORS](./docs/cors/cors.md)
-- [Content negotiation](./docs/content_negotiation/content_negotiation.md)
-- [Server Sent Events](./docs/sse/sse.md)
-- [Cluster](./docs/cluster/cluster.md)
-- [Http2 push](./docs/http2_push/http2_push.md)
+- [Handling requests](./docs/handling_requests.md)
+- [Handling errors](./docs/handling_errors.md)
+- [Server timing](./docs/server_timing.md)
+- [CORS](./docs/cors.md)
+- [https](./docs/https.md)
+- [Serving files](./docs/serving_files.md)
+- [Content negotiation](./docs/content_negotiation.md)
+- [Websocket](./docs/websocket.md)
+- [Server Sent Events](./docs/server_sent_events.md)
+- [Cluster](./docs/cluster.md)
+- [Http2 push](./docs/http2_push.md)
 
 # Installation
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jsenv/server",
-  "version": "12.7.5",
+  "version": "13.1.0",
   "description": "Write your Node.js server using pure functions",
   "license": "MIT",
   "author": {
@@ -37,7 +37,8 @@
     "@jsenv/abort": "4.2.3",
     "@jsenv/log": "3.1.0",
     "@jsenv/url-meta": "7.0.0",
-    "@jsenv/utils": "2.0.1"
+    "@jsenv/utils": "2.0.1",
+    "ws": "8.8.1"
   },
   "devDependencies": {
     "@jsenv/fetch": "../fetch/",

package/src/content_negotiation/{applyContentNegotiation.js → pick_accepted_content.js}

@@ -1,11 +1,10 @@
-export const applyContentNegotiation = ({
+export const pickAcceptedContent = ({
   availables,
   accepteds,
   getAcceptanceScore,
 }) => {
   let highestScore = -1
   let availableWithHighestScore = null
-
   let availableIndex = 0
   while (availableIndex < availables.length) {
     const available = availables[availableIndex]
@@ -23,6 +22,5 @@ export const applyContentNegotiation = ({
       }
     }
   }
-
   return availableWithHighestScore
 }

package/src/content_negotiation/{negotiateContentEncoding.js → pick_content_encoding.js}

@@ -1,7 +1,7 @@
 import { parseMultipleHeader } from "../internal/multiple-header.js"
-import { applyContentNegotiation } from "./applyContentNegotiation.js"
+import { pickAcceptedContent } from "./pick_accepted_content.js"
 
-export const negotiateContentEncoding = (request, availableEncodings) => {
+export const pickContentEncoding = (request, availableEncodings) => {
   const { headers = {} } = request
   const requestAcceptEncodingHeader = headers["accept-encoding"]
   if (!requestAcceptEncodingHeader) {
@@ -11,7 +11,7 @@ export const negotiateContentEncoding = (request, availableEncodings) => {
   const encodingsAccepted = parseAcceptEncodingHeader(
     requestAcceptEncodingHeader,
   )
-  return applyContentNegotiation({
+  return pickAcceptedContent({
     accepteds: encodingsAccepted,
     availables: availableEncodings,
     getAcceptanceScore: getEncodingAcceptanceScore,

package/src/content_negotiation/{negotiateContentLanguage.js → pick_content_language.js}

@@ -1,7 +1,7 @@
 import { parseMultipleHeader } from "../internal/multiple-header.js"
-import { applyContentNegotiation } from "./applyContentNegotiation.js"
+import { pickAcceptedContent } from "./pick_accepted_content.js"
 
-export const negotiateContentLanguage = (request, availableLanguages) => {
+export const pickContentLanguage = (request, availableLanguages) => {
   const { headers = {} } = request
   const requestAcceptLanguageHeader = headers["accept-language"]
   if (!requestAcceptLanguageHeader) {
@@ -11,7 +11,7 @@ export const negotiateContentLanguage = (request, availableLanguages) => {
   const languagesAccepted = parseAcceptLanguageHeader(
     requestAcceptLanguageHeader,
   )
-  return applyContentNegotiation({
+  return pickAcceptedContent({
     accepteds: languagesAccepted,
     availables: availableLanguages,
     getAcceptanceScore: getLanguageAcceptanceScore,

package/src/content_negotiation/{negotiateContentType.js → pick_content_type.js}

@@ -1,7 +1,7 @@
 import { parseMultipleHeader } from "../internal/multiple-header.js"
-import { applyContentNegotiation } from "./applyContentNegotiation.js"
+import { pickAcceptedContent } from "./pick_accepted_content.js"
 
-export const negotiateContentType = (request, availableContentTypes) => {
+export const pickContentType = (request, availableContentTypes) => {
   const { headers = {} } = request
   const requestAcceptHeader = headers.accept
   if (!requestAcceptHeader) {
@@ -9,7 +9,7 @@ export const negotiateContentType = (request, availableContentTypes) => {
   }
 
   const contentTypesAccepted = parseAcceptHeader(requestAcceptHeader)
-  return applyContentNegotiation({
+  return pickAcceptedContent({
     accepteds: contentTypesAccepted,
     availables: availableContentTypes,
     getAcceptanceScore: getContentTypeAcceptanceScore,

package/src/fetch_filesystem.js

@@ -12,7 +12,7 @@ import { bufferToEtag } from "./internal/etag.js"
 import { composeTwoResponses } from "./internal/response_composition.js"
 import { convertFileSystemErrorToResponseProperties } from "./internal/convertFileSystemErrorToResponseProperties.js"
 import { timeFunction } from "./server_timing/timing_measure.js"
-import { negotiateContentEncoding } from "./content_negotiation/negotiateContentEncoding.js"
+import { pickContentEncoding } from "./content_negotiation/pick_content_encoding.js"
 import { serveDirectory } from "./serve_directory.js"
 
 export const fetchFileSystem = async (
@@ -360,7 +360,7 @@ const getMtimeResponse = async ({ headers, sourceStat }) => {
 }
 
 const getCompressedResponse = async ({ sourceUrl, headers }) => {
-  const acceptedCompressionFormat = negotiateContentEncoding(
+  const acceptedCompressionFormat = pickContentEncoding(
     { headers },
     Object.keys(availableCompressionFormats),
   )

package/src/internal/dns_resolution.js

@@ -0,0 +1,17 @@
+import { lookup } from "node:dns"
+
+export const applyDnsResolution = async (
+  hostname,
+  { verbatim = false } = {},
+) => {
+  const dnsResolution = await new Promise((resolve, reject) => {
+    lookup(hostname, { verbatim }, (error, address, family) => {
+      if (error) {
+        reject(error)
+      } else {
+        resolve({ address, family })
+      }
+    })
+  })
+  return dnsResolution
+}

package/src/internal/getServerOrigins.js

@@ -1,26 +1,47 @@
 import { networkInterfaces } from "node:os"
 
-export const getServerOrigins = ({ protocol, ip, port }) => {
-  const isInternalIp = ip === "127.0.0.1"
-  const internalOrigin = createServerOrigin({
+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: "localhost",
+    hostname:
+      localhostDnsResolution.address === "127.0.0.1"
+        ? "localhost"
+        : "127.0.0.1",
     port,
   })
-  if (isInternalIp) {
-    return { internal: internalOrigin }
+  if (isLocal) {
+    return { local: localOrigin }
   }
-  const isAnyIp = !ip || ip === "::" || ip === "0.0.0.0"
+  const isAnyIp = WILDCARD_HOSTNAMES.includes(host)
+  const networkOrigin = createServerOrigin({
+    protocol,
+    hostname: isAnyIp ? getExternalIp() : host,
+    port,
+  })
   return {
-    internal: internalOrigin,
-    external: createServerOrigin({
-      protocol,
-      hostname: isAnyIp ? getExternalIp(ip) : ip,
-      port,
-    }),
+    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
@@ -36,10 +57,18 @@ const getExternalIp = () => {
     const networkAddressArray = networkInterfaceMap[key]
     return networkAddressArray.find((networkAddress) => {
       if (networkAddress.internal) return false
-      if (networkAddress.family !== "IPv4") 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"
+}

package/src/internal/listen.js

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

package/src/internal/request_factory.js

@@ -6,7 +6,9 @@ export const fromNodeRequest = (nodeRequest, { serverOrigin, signal }) => {
   const body = nodeStreamToObservable(nodeRequest)
 
   let requestOrigin
-  if (nodeRequest.authority) {
+  if (nodeRequest.upgrade) {
+    requestOrigin = serverOrigin
+  } else if (nodeRequest.authority) {
     requestOrigin = nodeRequest.connection.encrypted
       ? `https://${nodeRequest.authority}`
       : `http://${nodeRequest.authority}`

package/src/internal/server-polyglot.js

@@ -62,6 +62,7 @@ export const createPolyglotServer = async ({
 
 // The async part is just to lazyly import "http2" or "https"
 // so that these module are parsed only if used.
+// https://nodejs.org/api/tls.html#tlscreatesecurecontextoptions
 const createSecureServer = async ({
   certificate,
   privateKey,

package/src/main.js

@@ -4,8 +4,7 @@
  * Ideally this file should be kept simple to help discovering codebase progressively.
  */
 
-export { startServer } from "./startServer.js"
-export { composeServices } from "./service_composition/service_composition.js"
+export { startServer } from "./start_server.js"
 export { setupRoutes } from "./service_composition/routing.js"
 export { readRequestBody } from "./readRequestBody.js"
 export { fetchFileSystem } from "./fetch_filesystem.js"
@@ -18,31 +17,30 @@ export {
   STOP_REASON_PROCESS_EXIT,
   STOP_REASON_NOT_SPECIFIED,
 } from "./stopReasons.js"
+export { jsenvServiceErrorHandler } from "./services/error_handler/jsenv_service_error_handler.js"
 
 // CORS
 export {
-  pluginCORS,
+  jsenvServiceCORS,
   jsenvAccessControlAllowedHeaders,
   jsenvAccessControlAllowedMethods,
-} from "./cors/plugin_cors.js"
+} from "./services/cors/jsenv_service_cors.js"
 
-// server timings
-export { pluginServerTiming } from "./server_timing/plugin_server_timing.js"
+// server timing
 export { timeFunction, timeStart } from "./server_timing/timing_measure.js"
 
 // SSE
-export { createSSERoom } from "./sse/createSSERoom.js"
+export { createSSERoom } from "./sse/sse_room.js"
 
 // content-negotiation
-export { negotiateContentType } from "./content_negotiation/negotiateContentType.js"
-export { negotiateContentEncoding } from "./content_negotiation/negotiateContentEncoding.js"
-export { negotiateContentLanguage } from "./content_negotiation/negotiateContentLanguage.js"
-export { pluginContentNegotiationCheck } from "./content_negotiation/plugin_content_negotiation_check.js"
+export { pickContentType } from "./content_negotiation/pick_content_type.js"
+export { pickContentEncoding } from "./content_negotiation/pick_content_encoding.js"
+export { pickContentLanguage } from "./content_negotiation/pick_content_language.js"
+export { jsenvServiceResponseAcceptanceCheck } from "./services/response_acceptance_check/jsenv_service_response_acceptance_check.js"
 
 // others
 export { serveDirectory } from "./serve_directory.js"
 export { fromFetchResponse } from "./from_fetch_response.js"
 export { composeTwoResponses } from "./internal/response_composition.js"
-export { pluginRessourceAliases } from "./ressource_aliases/plugin_ressource_aliases.js"
-export { pluginRequestWaitingCheck } from "./plugin_request_waiting_check.js"
+export { jsenvServiceRessourceAliases } from "./services/ressource_aliases/jsenv_service_ressource_aliases.js"
 export { findFreePort } from "./internal/listen.js"

package/src/serve_directory.js

@@ -1,6 +1,6 @@
 import { readdirSync } from "node:fs"
 
-import { negotiateContentType } from "./content_negotiation/negotiateContentType.js"
+import { pickContentType } from "./content_negotiation/pick_content_type.js"
 
 export const serveDirectory = (
   url,
@@ -57,7 +57,7 @@ export const serveDirectory = (
       }
     },
   }
-  const bestContentType = negotiateContentType(
+  const bestContentType = pickContentType(
     { headers },
     Object.keys(responseProducers),
   )