@jsenv/server 13.0.0 → 14.1.0

package/README.md

@@ -24,34 +24,7 @@ await startServer({
 })
 ```
 
-# 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({
-  services: [
-    {
-      handleRequest: () => {
-        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:_
 
@@ -70,10 +43,10 @@ const server = await startServer({
     {
       name: "index",
       handleRequest: (request) => {
-        if (request.ressource === "/") {
+        if (request.resource === "/") {
           return { status: 200 }
         }
-        return null // means "I don't handle that request"
+        return null
       },
     },
     {
@@ -101,8 +74,8 @@ 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,
   services: [
     {
@@ -120,11 +93,6 @@ await startServer({
     },
   ],
 })
-
-function readFileSyncAsString(relativeUrl) {
-  const fileUrl = new URL(relativeUrl, import.meta.url)
-  return String(readFileSync(fileUrl))
-}
 ```
 
 _Code starting a server for static files:_
@@ -136,10 +104,8 @@ await startServer({
   services: [
     {
       handleRequest: async (request) => {
-        const fileUrl = new URL(request.ressource.slice(1), import.meta.url)
-        const response = await fetchFileSystem(fileUrl, {
-          ...request,
-        })
+        const fileUrl = new URL(request.resource.slice(1), import.meta.url)
+        const response = await fetchFileSystem(fileUrl, request)
         return response
       },
     },
@@ -149,16 +115,17 @@ await startServer({
 
 # Documentation
 
-- [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)
-- [https](./docs/https/https.md)
-- [Serving files](./docs/serving_files/serving_files.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": "13.0.0",
+  "version": "14.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/fetch_filesystem.js

@@ -64,7 +64,7 @@ export const fetchFileSystem = async (
   }
 
   // here you might be tempted to add || cacheControl === 'no-cache'
-  // but no-cache means ressource can be cache but must be revalidated (yeah naming is strange)
+  // but no-cache means resource can be cache but must be revalidated (yeah naming is strange)
   // https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control#Cacheability
   if (cacheControl === "no-store") {
     if (etagEnabled) {
@@ -206,7 +206,7 @@ const getClientCacheResponse = async ({
   sourceUrl,
 }) => {
   // here you might be tempted to add || headers["cache-control"] === "no-cache"
-  // but no-cache means ressource can be cache but must be revalidated (yeah naming is strange)
+  // but no-cache means resource can be cache but must be revalidated (yeah naming is strange)
   // https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control#Cacheability
 
   if (

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/nodeStreamToObservable.js

@@ -38,7 +38,7 @@ export const nodeStreamToObservable = (nodeStream) => {
     // used in the next ${readableStreamLifetimeInSeconds} otherwise destroys it
     const timeout = setTimeout(() => {
       process.emitWarning(
-        `Readable stream not used after ${readableStreamLifetimeInSeconds} seconds. It will be destroyed to release ressources`,
+        `Readable stream not used after ${readableStreamLifetimeInSeconds} seconds. It will be destroyed to release resources`,
         {
           CODE: "READABLE_STREAM_TIMEOUT",
           // url is for http client request

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}`
@@ -22,8 +24,8 @@ export const fromNodeRequest = (nodeRequest, { serverOrigin, signal }) => {
     signal,
     http2: Boolean(nodeRequest.stream),
     origin: requestOrigin,
-    ...getPropertiesFromRessource({
-      ressource: nodeRequest.url,
+    ...getPropertiesFromResource({
+      resource: nodeRequest.url,
       baseUrl: requestOrigin,
     }),
     method: nodeRequest.method,
@@ -34,13 +36,13 @@ export const fromNodeRequest = (nodeRequest, { serverOrigin, signal }) => {
 
 export const applyRedirectionToRequest = (
   request,
-  { ressource, pathname, ...rest },
+  { resource, pathname, ...rest },
 ) => {
   return {
     ...request,
-    ...(ressource
-      ? getPropertiesFromRessource({
-          ressource,
+    ...(resource
+      ? getPropertiesFromResource({
+          resource,
           baseUrl: request.url,
         })
       : pathname
@@ -53,20 +55,20 @@ export const applyRedirectionToRequest = (
   }
 }
 
-const getPropertiesFromRessource = ({ ressource, baseUrl }) => {
-  const urlObject = new URL(ressource, baseUrl)
+const getPropertiesFromResource = ({ resource, baseUrl }) => {
+  const urlObject = new URL(resource, baseUrl)
   let pathname = urlObject.pathname
 
   return {
     url: String(urlObject),
     pathname,
-    ressource,
+    resource,
   }
 }
 
 const getPropertiesFromPathname = ({ pathname, baseUrl }) => {
-  return getPropertiesFromRessource({
-    ressource: `${pathname}${new URL(baseUrl).search}`,
+  return getPropertiesFromResource({
+    resource: `${pathname}${new URL(baseUrl).search}`,
     baseUrl,
   })
 }
@@ -93,12 +95,12 @@ export const createPushRequest = (request, { signal, pathname, method }) => {
 const getHeadersInheritedByPushRequest = (request) => {
   const headersInherited = { ...request.headers }
   // mtime sent by the client in request headers concerns the main request
-  // Time remains valid for request to other ressources so we keep it
+  // Time remains valid for request to other resources so we keep it
   // in child requests
   // delete childHeaders["if-modified-since"]
 
   // eTag sent by the client in request headers concerns the main request
-  // A request made to an other ressource must not inherit the eTag
+  // A request made to an other resource must not inherit the eTag
   delete headersInherited["if-none-match"]
 
   return headersInherited

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/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/main.js

@@ -4,7 +4,7 @@
  * Ideally this file should be kept simple to help discovering codebase progressively.
  */
 
-export { startServer } from "./server.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"
@@ -42,5 +42,5 @@ export { jsenvServiceResponseAcceptanceCheck } from "./services/response_accepta
 export { serveDirectory } from "./serve_directory.js"
 export { fromFetchResponse } from "./from_fetch_response.js"
 export { composeTwoResponses } from "./internal/response_composition.js"
-export { jsenvServiceRessourceAliases } from "./services/ressource_aliases/jsenv_service_ressource_aliases.js"
+export { jsenvServiceRequestAliases } from "./services/request_aliases/jsenv_service_request_aliases.js"
 export { findFreePort } from "./internal/listen.js"

package/src/service_controller.js

@@ -4,6 +4,7 @@ const HOOK_NAMES = [
   "serverListening",
   "redirectRequest",
   "handleRequest",
+  "handleWebsocket",
   "handleError",
   "onResponsePush",
   "injectResponseHeaders",

package/src/services/request_aliases/jsenv_service_request_aliases.js

@@ -0,0 +1,37 @@
+import { URL_META } from "@jsenv/url-meta"
+
+export const jsenvServiceRequestAliases = (resourceAliases) => {
+  const aliases = {}
+  Object.keys(resourceAliases).forEach((key) => {
+    aliases[asFileUrl(key)] = asFileUrl(resourceAliases[key])
+  })
+  return {
+    name: "jsenv:request_aliases",
+    redirectRequest: (request) => {
+      const resourceBeforeAlias = request.resource
+      const urlAfterAliasing = URL_META.applyAliases({
+        url: asFileUrl(request.pathname),
+        aliases,
+      })
+      const resourceAfterAlias = urlAfterAliasing.slice("file://".length)
+      if (resourceBeforeAlias === resourceAfterAlias) {
+        return null
+      }
+      const resource = replaceResource(resourceBeforeAlias, resourceAfterAlias)
+      return { resource }
+    },
+  }
+}
+
+const asFileUrl = (specifier) => new URL(specifier, "file:///").href
+
+const replaceResource = (resourceBeforeAlias, newValue) => {
+  const urlObject = new URL(resourceBeforeAlias, "file://")
+  const searchSeparatorIndex = newValue.indexOf("?")
+  if (searchSeparatorIndex > -1) {
+    return newValue // let new value override search params
+  }
+  urlObject.pathname = newValue
+  const resource = `${urlObject.pathname}${urlObject.search}`
+  return resource
+}

package/src/sse/sse_room.js

@@ -37,9 +37,7 @@ export const createSSERoom = ({
 
     const lastKnownId =
       request.headers["last-event-id"] ||
-      new URL(request.ressource, request.origin).searchParams.get(
-        "last-event-id",
-      )
+      new URL(request.url).searchParams.get("last-event-id")
 
     if (clients.size >= maxClientAllowed) {
       return {