velocious 1.0.431 → 1.0.433

package/build/http-server/client/request-parser.js

@@ -0,0 +1,195 @@
+// @ts-check
+
+import {digg} from "diggerize"
+import EventEmitter from "../../utils/event-emitter.js"
+import {incorporate} from "incorporator"
+import ParamsToObject from "./params-to-object.js"
+import RequestBuffer from "./request-buffer/index.js"
+
+export default class VelociousHttpServerClientRequestParser {
+  /**
+   * Runs constructor.
+   * @param {object} args - Options object.
+   * @param {import("../../configuration.js").default} args.configuration - Configuration instance.
+   */
+  constructor({configuration}) {
+    if (!configuration) throw new Error("No configuration given")
+
+    this.configuration = configuration
+    this.data = []
+    this.events = new EventEmitter()
+    this.hasCompleted = false
+    /**
+     * Narrows the runtime value to the documented type.
+      @type {Record<string, string | string[] | undefined | Record<string, ?> | Array<?>>} */
+    this.params = {}
+
+    this.requestBuffer = new RequestBuffer({configuration})
+    this.requestBuffer.events.on("completed", this.requestDone)
+    this.requestBuffer.events.on("form-data-part", this.onFormDataPart)
+    this.requestBuffer.events.on("request-done", this.requestDone)
+  }
+
+  /**
+   * Runs destroy.
+   * @returns {void} - No return value.
+   */
+  destroy() {
+    this.requestBuffer.events.off("completed", this.requestDone)
+    this.requestBuffer.events.off("form-data-part", this.onFormDataPart)
+    this.requestBuffer.events.off("request-done", this.requestDone)
+    this.requestBuffer.destroy()
+  }
+
+  /**
+   * On form data part.
+   * @param {import("./request-buffer/form-data-part.js").default} formDataPart - Form data part.
+   * @returns {void} - No return value.
+   */
+  onFormDataPart = (formDataPart) => {
+    /**
+     * Unordered params.
+      @type {Record<string, string | string[] | import("./uploaded-file/uploaded-file.js").default>} */
+    const unorderedParams = {}
+
+    unorderedParams[formDataPart.getName()] = formDataPart.getValue()
+
+    try {
+      const paramsToObject = new ParamsToObject(unorderedParams)
+      const newParams = paramsToObject.toObject()
+
+      incorporate(this.params, newParams)
+    } catch (error) {
+      const ensuredError = /**
+                            * Narrows the runtime value to the documented type.
+                             @type {Error & {velociousContext?: Record<string, ?>}} */ (error)
+
+      ensuredError.velociousContext = {
+        ...(ensuredError.velociousContext || {}),
+        requestParsing: {
+          formDataPartName: formDataPart.getName(),
+          httpMethod: this.getHttpMethod(),
+          path: this.getPath(),
+          stage: "form-data-part"
+        }
+      }
+
+      throw ensuredError
+    }
+  }
+
+  /**
+   * Feed.
+   * @param {Buffer} data - Data payload.
+   * @returns {Buffer | undefined} - Remaining data, if any.
+   */
+  feed = (data) => {
+    if (this.hasCompleted) {
+      throw new Error("Request parser already completed")
+    }
+
+    return this.requestBuffer.feed(data)
+  }
+
+  /**
+   * Runs get header.
+   * @param {string} name - Name.
+   * @returns {string} - The header.
+   */
+  getHeader(name) { return this.requestBuffer.getHeader(name)?.value }
+
+  /**
+   * Runs get headers.
+   * @returns {Record<string, string>} - The headers.
+   */
+  getHeaders() { return this.requestBuffer.getHeadersHash() }
+
+  /**
+   * Runs get http method.
+   * @returns {string} - The http method.
+   */
+  getHttpMethod() { return digg(this, "requestBuffer", "httpMethod") }
+
+  /**
+   * Runs get http version.
+   * @returns {string} - The http version.
+   */
+  getHttpVersion() { return digg(this, "requestBuffer", "httpVersion") }
+
+  /**
+   * Runs get host match.
+   * @returns {{host: string, port: string, protocol: string} | null} - Parsed host info, or null when unavailable.
+   */
+  _getHostMatch() {
+    const rawHost = this.requestBuffer.getHeader("origin")?.value
+
+    if (!rawHost) return null
+
+    const match = rawHost.match(/^(.+):\/\/(.+)(|:(\d+))/)
+
+    if (!match) throw new Error(`Couldn't match host: ${rawHost}`)
+
+    return {
+      protocol: match[1],
+      host: match[2],
+      port: match[4]
+    }
+  }
+
+  /**
+   * Runs get host.
+   * @returns {string | void} - The host.
+   */
+  getHost() {
+    const rawHostSplit = this.requestBuffer.getHeader("host")?.value?.split(":")
+
+    if (rawHostSplit && rawHostSplit[0]) return rawHostSplit[0]
+  }
+
+  /**
+   * Runs get path.
+   * @returns {string} - The path.
+   */
+  getPath() { return digg(this, "requestBuffer", "path") }
+
+  /**
+   * Runs get port.
+   * @returns {number | void} - The port.
+   */
+  getPort() {
+    const rawHostSplit = this.requestBuffer.getHeader("host")?.value?.split(":")
+    const httpMethod = this.getHttpMethod()
+
+    if (rawHostSplit && rawHostSplit[1]) {
+      return parseInt(rawHostSplit[1])
+    } else if (httpMethod == "http") {
+      return 80
+    } else if (httpMethod == "https") {
+      return 443
+    }
+  }
+
+  /**
+   * Runs get protocol.
+   * @returns {string | null} - The protocol.
+   */
+  getProtocol() { return this._getHostMatch()?.protocol || null }
+
+  /**
+   * Runs get request buffer.
+   * @returns {RequestBuffer} - The request buffer.
+   */
+  getRequestBuffer() { return this.requestBuffer }
+
+  /**
+   * Request done.
+   * @returns {void} - No return value.
+   */
+  requestDone = () => {
+    this.hasCompleted = true
+    incorporate(this.params, this.requestBuffer.params)
+
+    this.state = "done"
+    this.events.emit("done")
+  }
+}

package/build/http-server/client/request-runner.js

@@ -0,0 +1,321 @@
+// @ts-check
+
+import BacktraceCleaner from "../../utils/backtrace-cleaner-node.js"
+import ensureError from "../../utils/ensure-error.js"
+import EventEmitter from "../../utils/event-emitter.js"
+import Logger from "../../logger.js"
+import RequestTiming from "./request-timing.js"
+import Response from "./response.js"
+import RoutesResolver from "../../routes/resolver.js"
+
+/**
+ * Runs stack frame line.
+ * @param {string | undefined} line - Potential header line.
+ * @returns {boolean} - Whether the line is a stack frame.
+ */
+function stackFrameLine(line) {
+  if (!line) return false
+
+  return /^at\s+/u.test(line.trim())
+}
+
+/**
+ * Runs request error summary.
+ * @param {Error} error - Error to format for logging.
+ * @param {string | undefined} cleanedStackWithHeader - Cleaned stack with header line.
+ * @returns {string} - Error summary line with type information.
+ */
+function requestErrorSummary(error, cleanedStackWithHeader) {
+  const stackHeader = cleanedStackWithHeader?.split("\n")[0]?.trim()
+
+  if (stackHeader && !stackFrameLine(stackHeader)) return stackHeader
+
+  const errorCode = typeof /**
+                            * Narrows the runtime value to the documented type.
+                             @type {?} */ (error).code === "string"
+    ? /**
+       * Narrows the runtime value to the documented type.
+        @type {?} */ (error).code
+    : undefined
+  const errorMessage = error.message || String(error)
+
+  if (errorCode) return `${error.name} [${errorCode}]: ${errorMessage}`
+
+  return `${error.name}: ${errorMessage}`
+}
+
+/**
+ * Runs request error log details.
+ * @param {Error} error - Error to format for logging.
+ * @returns {{
+ *   errorSummary: string,
+ *   cleanedBacktrace: string | undefined,
+ * }} - Log details.
+ */
+function requestErrorLogDetails(error) {
+  const cleanedStackWithHeader = BacktraceCleaner.getCleanedStack(error)
+  const errorSummary = requestErrorSummary(error, cleanedStackWithHeader)
+  const cleanedBacktrace = BacktraceCleaner.getCleanedStack(error, {includeErrorHeader: false}) || cleanedStackWithHeader
+
+  return {errorSummary, cleanedBacktrace}
+}
+
+/**
+ * Runs request error log message.
+ * @param {{
+ *   errorSummary: string,
+ *   cleanedBacktrace: string | undefined,
+ * }} logDetails - Log details.
+ * @returns {string} - Single request error log message.
+ */
+function requestErrorLogMessage(logDetails) {
+  if (!logDetails.cleanedBacktrace) {
+    return `Error while running request: ${logDetails.errorSummary}`
+  }
+
+  return `Error while running request: ${logDetails.errorSummary}\nCleaned backtrace:\n${logDetails.cleanedBacktrace}`
+}
+
+/**
+ * Runs response body type for log.
+ * @param {Response} response - Response object.
+ * @returns {string} - Response body type for logging.
+ */
+function responseBodyTypeForLog(response) {
+  if (response.getFilePath()) return "file"
+
+  try {
+    return typeof response.getBody()
+  } catch {
+    return "unset"
+  }
+}
+
+/**
+ * Runs format bucket ms.
+ * @param {number} value - Milliseconds.
+ * @returns {string} - Formatted milliseconds with one decimal place.
+ */
+function formatBucketMs(value) {
+  return `${value.toFixed(1)}ms`
+}
+
+/**
+ * Runs query count label.
+ * @param {number} count - Query count.
+ * @returns {string} - Query count label.
+ */
+function queryCountLabel(count) {
+  return `${count} ${count === 1 ? "query" : "queries"}`
+}
+
+export default class VelociousHttpServerClientRequestRunner {
+  events = new EventEmitter()
+
+  /**
+   * Runs constructor.
+   * @param {object} args - Options object.
+   * @param {import("../../configuration.js").default} args.configuration - Configuration instance.
+   * @param {import("./request.js").default | import("./websocket-request.js").default} args.request - Request object.
+   */
+  constructor({configuration, request}) {
+    if (!configuration) throw new Error("No configuration given")
+    if (!request) throw new Error("No request given")
+
+    this.logger = new Logger(this)
+    this.configuration = configuration
+    this.request = request
+    this.response = new Response({configuration})
+    this.completedRequestLogged = false
+    this.requestTiming = new RequestTiming()
+    this.state = "running"
+  }
+
+  getRequest() { return this.request }
+  getState() { return this.state }
+
+  async run() {
+    this.requestTiming.startedAtMs = Date.now()
+
+    return await this.configuration.runWithRequestTiming(this.requestTiming, async () => {
+      await this._run()
+    })
+  }
+
+  async _run() {
+    const {configuration, request, response} = this
+
+    if (!request) throw new Error("No request?")
+
+    try {
+      await this.logger.debug(() => ["Run request lifecycle", {
+        httpMethod: request.httpMethod(),
+        httpVersion: request.httpVersion(),
+        origin: request.origin(),
+        path: request.path(),
+        remoteAddress: request.remoteAddress()
+      }])
+      // Before we checked if the sec-fetch-mode was "cors", but it seems the sec-fetch-mode isn't always present
+      await this.logger.debug(() => ["Run CORS", {httpMethod: request.httpMethod(), secFetchMode: request.header("sec-fetch-mode")}])
+
+      const cors = configuration.getCors()
+
+      if (cors) {
+        await cors({request, response})
+        await this.logger.debug(() => ["CORS handler done", {
+          httpMethod: request.httpMethod(),
+          path: request.path(),
+          responseStatusCode: response.getStatusCode()
+        }])
+      }
+
+      if (request.httpMethod() == "OPTIONS" && request.header("sec-fetch-mode") == "cors") {
+        response.setStatus(200)
+        response.setBody("")
+        await this.logger.debug(() => ["Handled preflight OPTIONS request", {
+          path: request.path(),
+          responseStatusCode: response.getStatusCode()
+        }])
+      } else {
+        await this.logger.debug("Run request")
+        const routesResolver = new RoutesResolver({configuration, request, response})
+        const startTimeMs = Date.now()
+        /**
+         * Defines timeoutId.
+          @type {ReturnType<typeof setTimeout> | undefined} */
+        let timeoutId
+        /**
+         * Defines timeoutReject.
+          @type {((error: Error) => void) | undefined} */
+        let timeoutReject
+        let timedOut = false
+
+        const setRequestTimeoutSeconds = (/**
+                                           * Narrows the runtime value to the documented type.
+                                            @type {number | undefined} */ timeoutSeconds) => {
+          if (timeoutId) {
+            clearTimeout(timeoutId)
+            timeoutId = undefined
+          }
+
+          if (typeof timeoutSeconds !== "number" || !Number.isFinite(timeoutSeconds) || timeoutSeconds <= 0) {
+            return
+          }
+
+          const timeoutMs = timeoutSeconds * 1000
+          const elapsedMs = Date.now() - startTimeMs
+          const remainingMs = timeoutMs - elapsedMs
+
+          if (remainingMs <= 0) {
+            timeoutReject?.(new Error(`Request timed out after ${timeoutSeconds}s`))
+            return
+          }
+
+          timeoutId = setTimeout(() => {
+            timeoutReject?.(new Error(`Request timed out after ${timeoutSeconds}s`))
+          }, remainingMs)
+        }
+
+        const timeoutPromise = new Promise((_, reject) => {
+          timeoutReject = (error) => {
+            timedOut = true
+            reject(error)
+          }
+        })
+
+        response.setRequestTimeoutMsChangeHandler((timeoutSeconds) => {
+          setRequestTimeoutSeconds(timeoutSeconds)
+        })
+
+        setRequestTimeoutSeconds(configuration.getRequestTimeoutMs?.())
+
+        let resolvePromise
+
+        try {
+          resolvePromise = routesResolver.resolve()
+          // Keep Promise.race here to allow dynamic timeout updates.
+          await Promise.race([resolvePromise, timeoutPromise])
+          await this.logger.debug(() => ["Routes resolver done", {
+            httpMethod: request.httpMethod(),
+            path: request.path(),
+            responseStatusCode: response.getStatusCode(),
+            hasFilePath: Boolean(response.getFilePath()),
+            bodyType: responseBodyTypeForLog(response)
+          }])
+        } catch (error) {
+          if (timedOut && resolvePromise) {
+            void resolvePromise.catch((resolveError) => {
+              this.logger.warn(() => ["Request finished after timeout", resolveError])
+            })
+          }
+          throw error
+        } finally {
+          if (timeoutId) clearTimeout(timeoutId)
+        }
+      }
+    } catch (e) {
+      const error = ensureError(e)
+      const errorWithContext = /**
+                                * Narrows the runtime value to the documented type.
+                                 @type {{velociousContext?: object}} */ (error)
+      const errorContext = errorWithContext.velociousContext || {stage: "request-runner"}
+      const logDetails = requestErrorLogDetails(error)
+
+      await this.logger.error(() => requestErrorLogMessage(logDetails))
+
+      const errorPayload = {
+        context: errorContext,
+        error,
+        request,
+        response
+      }
+
+      configuration.getErrorEvents().emit("framework-error", errorPayload)
+      configuration.getErrorEvents().emit("all-error", {
+        ...errorPayload,
+        errorType: "framework-error"
+      })
+
+      response.setStatus(500)
+      response.setErrorBody(error)
+    }
+
+    await this.logger.debug(() => ["Request runner done", {
+      httpMethod: request.httpMethod(),
+      path: request.path(),
+      responseStatusCode: response.getStatusCode()
+    }])
+    this.state = "done"
+    this.events.emit("done", this)
+  }
+
+  /**
+   * Runs log completed request.
+   * @returns {Promise<void>} - Logs the completed request line after the response has been served.
+   */
+  async logCompletedRequest() {
+    if (this.completedRequestLogged) return
+
+    this.completedRequestLogged = true
+
+    const requestTiming = this.requestTiming
+
+    requestTiming.markResponseServed()
+
+    if (!requestTiming.completedLogSubject || !requestTiming.completedLogMethod) return
+
+    const logger = new Logger(requestTiming.completedLogSubject, {configuration: this.configuration})
+    const summary = requestTiming.summary()
+    const response = this.response
+    const completedMessage = [
+      `Completed ${response.getStatusCode()} ${response.getStatusMessage()} in ${Math.round(summary.totalMs)}ms (`,
+      `Controller: ${formatBucketMs(summary.controllerMs)}`,
+      ` | Views: ${formatBucketMs(summary.viewsMs)}`,
+      ` | DB: ${formatBucketMs(summary.dbMs)} (${queryCountLabel(summary.dbQueryCount)})`,
+      ` | Velocious: ${formatBucketMs(summary.velociousMs)}`,
+      `)`
+    ].join("")
+
+    await logger[requestTiming.completedLogMethod](completedMessage)
+  }
+}

package/build/http-server/client/request-timing.js

@@ -0,0 +1,171 @@
+// @ts-check
+
+/**
+ * RequestTimingBucket type.
+ * @typedef {"controller" | "db" | "views"} RequestTimingBucket
+ */
+
+/**
+ * Defines this typedef.
+ * @typedef {{bucket: RequestTimingBucket, startedAtMs: number}} ActiveTimingBucket
+ */
+
+/**
+ * Tracks exclusive request timing buckets. When a nested bucket starts,
+ * the currently active bucket is paused until the nested bucket exits.
+ */
+export default class RequestTiming {
+  /**
+   * Buckets.
+    @type {Record<RequestTimingBucket, number>} */
+  buckets = {
+    controller: 0,
+    db: 0,
+    views: 0
+  }
+
+  /**
+   * Bucket stack.
+    @type {ActiveTimingBucket[]} */
+  bucketStack = []
+
+  dbQueryCount = 0
+  /**
+   * Completed log method.
+    @type {"debug" | "info" | undefined} */
+  completedLogMethod = undefined
+  /**
+   * Completed log subject.
+    @type {string | undefined} */
+  completedLogSubject = undefined
+  /**
+   * Response served at ms.
+    @type {number | undefined} */
+  responseServedAtMs = undefined
+  startedAtMs = Date.now()
+
+  /**
+   * Runs measure.
+   * @template T
+   * @param {RequestTimingBucket} bucket - Bucket name.
+   * @param {() => Promise<T> | T} callback - Callback to measure.
+   * @returns {Promise<T>} - Callback result.
+   */
+  async measure(bucket, callback) {
+    this._pushBucket(bucket)
+
+    try {
+      return await callback()
+    } finally {
+      this._popBucket()
+    }
+  }
+
+  /**
+   * Runs measure sync.
+   * @template T
+   * @param {RequestTimingBucket} bucket - Bucket name.
+   * @param {() => T} callback - Callback to measure.
+   * @returns {T} - Callback result.
+   */
+  measureSync(bucket, callback) {
+    this._pushBucket(bucket)
+
+    try {
+      return callback()
+    } finally {
+      this._popBucket()
+    }
+  }
+
+  /**
+   * Runs measure db query.
+   * @template T
+   * @param {() => Promise<T>} callback - Query callback.
+   * @returns {Promise<T>} - Query result.
+   */
+  async measureDbQuery(callback) {
+    this.dbQueryCount += 1
+
+    return await this.measure("db", callback)
+  }
+
+  /**
+   * Runs mark response served.
+   * @returns {void} - Marks the response as fully served.
+   */
+  markResponseServed() {
+    this.responseServedAtMs = Date.now()
+  }
+
+  /**
+   * Runs summary.
+   * @returns {{controllerMs: number, dbMs: number, totalMs: number, velociousMs: number, viewsMs: number, dbQueryCount: number}} - Timing summary.
+   */
+  summary() {
+    const now = this.responseServedAtMs || Date.now()
+    const buckets = this._bucketTotalsAt(now)
+    const totalMs = now - this.startedAtMs
+    const controllerMs = buckets.controller
+    const dbMs = buckets.db
+    const viewsMs = buckets.views
+    const velociousMs = Math.max(totalMs - controllerMs - dbMs - viewsMs, 0)
+
+    return {
+      controllerMs,
+      dbMs,
+      dbQueryCount: this.dbQueryCount,
+      totalMs,
+      velociousMs,
+      viewsMs
+    }
+  }
+
+  /**
+   * Runs bucket totals at.
+   * @param {number} now - Timestamp to calculate active bucket elapsed time against.
+   * @returns {Record<RequestTimingBucket, number>} - Bucket totals.
+   */
+  _bucketTotalsAt(now) {
+    const buckets = Object.assign({}, this.buckets)
+    const activeBucket = this.bucketStack[this.bucketStack.length - 1]
+
+    if (activeBucket) {
+      buckets[activeBucket.bucket] += Math.max(now - activeBucket.startedAtMs, 0)
+    }
+
+    return buckets
+  }
+
+  /**
+   * Runs push bucket.
+   * @param {RequestTimingBucket} bucket - Bucket name.
+   * @returns {void} - No return value.
+   */
+  _pushBucket(bucket) {
+    const now = Date.now()
+    const activeBucket = this.bucketStack[this.bucketStack.length - 1]
+
+    if (activeBucket) {
+      this.buckets[activeBucket.bucket] += now - activeBucket.startedAtMs
+    }
+
+    this.bucketStack.push({bucket, startedAtMs: now})
+  }
+
+  /**
+   * Runs pop bucket.
+   * @returns {void} - No return value.
+   */
+  _popBucket() {
+    const now = Date.now()
+    const activeBucket = this.bucketStack.pop()
+
+    if (!activeBucket) throw new Error("No active request timing bucket")
+
+    this.buckets[activeBucket.bucket] += now - activeBucket.startedAtMs
+
+    const parentBucket = this.bucketStack[this.bucketStack.length - 1]
+    if (parentBucket) parentBucket.startedAtMs = now
+  }
+}