velocious 1.0.430 → 1.0.431

package/src/frontend-models/websocket-publishers.js

@@ -0,0 +1,224 @@
+// @ts-check
+
+import AuthorizationBaseResource from "../authorization/base-resource.js"
+import FrontendModelBaseResource from "../frontend-model-resource/base-resource.js"
+import {frontendModelResourcesForBackendProject} from "./resource-definition.js"
+import {serializeFrontendModelTransportValue} from "./transport-serialization.js"
+
+const registeredConfigurationsByModelClass = new WeakMap()
+const channelClassRegisteredConfigurations = new WeakSet()
+
+/** Shared channel name for all frontend-model lifecycle subscriptions. */
+export const FRONTEND_MODELS_CHANNEL_NAME = "frontend-models"
+
+/**
+ * Runs the frontendModelBroadcastChannelName helper.
+ * @param {string} modelName - Model class name.
+ * @returns {string} - Broadcast channel name (legacy, retained for migration compatibility).
+ */
+export function frontendModelBroadcastChannelName(modelName) {
+  return `frontend-models:${modelName}`
+}
+
+/**
+ * Builds a frontend models map from the configuration's ability resources.
+ * Each resource class with a static ModelClass property is keyed by model name.
+ * @param {import("../configuration.js").default} configuration - Configuration instance.
+ * @returns {Record<string, typeof FrontendModelBaseResource>} - Resource definitions keyed by model name.
+ */
+/**
+ * Runs resolve ability resources list.
+ * @param {import("../configuration.js").default} configuration - Configuration instance.
+ * @returns {Promise<import("../configuration-types.js").AbilityResourceClassType[]>} - Resolved ability resources.
+ */
+async function resolveAbilityResourcesList(configuration) {
+  // First check explicitly set ability resources
+  const explicit = configuration.getAbilityResources()
+
+  if (explicit && explicit.length > 0) return explicit
+
+  // Resolve from the ability resolver by calling it with a synthetic context.
+  // The resolver must handle undefined request/response gracefully.
+  const resolver = configuration.getAbilityResolver?.()
+
+  if (typeof resolver === "function") {
+    const ability = await resolver({configuration, params: {}, request: /**
+                                                                         * Narrows the runtime value to the documented type.
+                                                                          @type {?} */ (undefined), response: /**
+                                                                                                               * Narrows the runtime value to the documented type.
+                                                                                                                @type {?} */ (undefined)})
+
+    if (ability?.resources && Array.isArray(ability.resources)) {
+      return ability.resources
+    }
+  }
+
+  return []
+}
+
+/**
+ * Runs frontend model resources from ability resources list.
+ * @param {import("../configuration-types.js").AbilityResourceClassType[]} abilityResources - Ability resource classes.
+ * @returns {Record<string, typeof FrontendModelBaseResource>} - Resource definitions keyed by model name.
+ */
+function frontendModelResourcesFromAbilityResourcesList(abilityResources) {
+  /**
+   * Resources.
+    @type {Record<string, typeof FrontendModelBaseResource>} */
+  const resources = {}
+
+  if (!abilityResources || abilityResources.length === 0) return resources
+
+  if (!Array.isArray(abilityResources)) {
+    throw new Error(`Expected ability resources to be an array but got: ${typeof abilityResources}`)
+  }
+
+  for (const resourceClass of abilityResources) {
+    if (typeof resourceClass !== "function") {
+      throw new Error(`Expected ability resource to be a class but got: ${typeof resourceClass}`)
+    }
+
+    if (resourceClass.prototype instanceof FrontendModelBaseResource) {
+      const modelClass = /**
+                          * Narrows the runtime value to the documented type.
+                           @type {typeof FrontendModelBaseResource} */ (resourceClass).ModelClass
+
+      if (!modelClass) {
+        throw new Error(`Resource class ${resourceClass.name} is missing a static ModelClass property`)
+      }
+
+      const modelName = modelClass.getModelName()
+
+      if (!modelName) {
+        throw new Error(`Model class ${modelClass.name} returned empty model name from getModelName()`)
+      }
+
+      resources[modelName] = /**
+                              * Narrows the runtime value to the documented type.
+                               @type {typeof FrontendModelBaseResource} */ (resourceClass)
+    } else if (resourceClass.prototype instanceof AuthorizationBaseResource) {
+      // Authorization-only resource — valid but not relevant for WebSocket publishing
+    } else {
+      throw new Error(`Unexpected ability resource class: ${resourceClass.name}. Expected AuthorizationBaseResource or FrontendModelBaseResource subclass.`)
+    }
+  }
+
+  return resources
+}
+
+/**
+ * Runs the ensureFrontendModelWebsocketPublishersRegistered helper.
+ * @param {import("../configuration.js").default} configuration - Configuration instance.
+ * @returns {Promise<void>}
+ */
+export async function ensureFrontendModelWebsocketPublishersRegistered(configuration) {
+  const modelClasses = configuration.getModelClasses()
+
+  /**
+   * All frontend models.
+    @type {Record<string, typeof FrontendModelBaseResource>} */
+  let allFrontendModels = {}
+
+  for (const backendProject of configuration.getBackendProjects()) {
+    const projectResources = frontendModelResourcesForBackendProject(backendProject)
+
+    allFrontendModels = {...allFrontendModels, ...projectResources}
+  }
+
+  // Auto-discover from ability resources when backend projects didn't provide any
+  if (Object.keys(allFrontendModels).length === 0) {
+    const abilityResources = await resolveAbilityResourcesList(configuration)
+
+    allFrontendModels = frontendModelResourcesFromAbilityResourcesList(abilityResources)
+  }
+
+  // Phase 3: register the V2 channel class once per configuration so
+  // `subscribeChannel("frontend-models", {params: {model}})` finds it.
+  // Dynamic import keeps server-only WebsocketRequest + Node utilities
+  // out of browser bundles that transitively pull in this module via
+  // configuration → logger.
+  if (!channelClassRegisteredConfigurations.has(configuration)) {
+    channelClassRegisteredConfigurations.add(configuration)
+    const {default: FrontendModelWebsocketChannel} = await import("./websocket-channel.js")
+
+    configuration.registerWebsocketChannel?.(FRONTEND_MODELS_CHANNEL_NAME, FrontendModelWebsocketChannel)
+  }
+
+  for (const modelName of Object.keys(allFrontendModels)) {
+    const modelClass = modelClasses[modelName]
+
+    if (!modelClass) continue
+
+    let registeredConfigurations = registeredConfigurationsByModelClass.get(modelClass)
+
+    if (!registeredConfigurations) {
+      registeredConfigurations = new WeakSet()
+      registeredConfigurationsByModelClass.set(modelClass, registeredConfigurations)
+    }
+
+    if (registeredConfigurations.has(configuration)) continue
+
+    registeredConfigurations.add(configuration)
+
+    modelClass.beforeCreate((model) => {
+      /**
+       * Narrows the runtime value to the documented type.
+        @type {import("../database/record/index.js").default & {__frontendModelWebsocketAction?: "create" | "update"}} */ (model).__frontendModelWebsocketAction = "create"
+    })
+
+    modelClass.beforeUpdate((model) => {
+      /**
+       * Narrows the runtime value to the documented type.
+        @type {import("../database/record/index.js").default & {__frontendModelWebsocketAction?: "create" | "update"}} */ (model).__frontendModelWebsocketAction = "update"
+    })
+
+    modelClass.afterSave((model) => {
+      const modelWithWebsocketAction = /**
+                                        * Narrows the runtime value to the documented type.
+                                         @type {import("../database/record/index.js").default & {__frontendModelWebsocketAction?: "create" | "update"}} */ (model)
+      const action = modelWithWebsocketAction.__frontendModelWebsocketAction
+
+      if (action !== "create" && action !== "update") return
+
+      void model.getModelClass().connection().afterCommit(async () => {
+        broadcastFrontendModelEvent(configuration, modelName, {
+          action,
+          id: model.id(),
+          record: model.attributes()
+        })
+      })
+      delete modelWithWebsocketAction.__frontendModelWebsocketAction
+    })
+
+    modelClass.afterDestroy((model) => {
+      void model.getModelClass().connection().afterCommit(async () => {
+        broadcastFrontendModelEvent(configuration, modelName, {
+          action: "destroy",
+          id: model.id()
+        })
+      })
+    })
+  }
+}
+
+/**
+ * Fans a lifecycle event out to all V2 "frontend-models" subscribers
+ * whose `params.model` matches. Record attributes go through the
+ * transport serializer so Date/undefined/etc. survive the JSON hop.
+ * @param {import("../configuration.js").default} configuration - Configuration instance.
+ * @param {string} modelName - Model class name.
+ * @param {{action: "create" | "update" | "destroy", id: ?, record?: Record<string, ?>}} event - Lifecycle event.
+ * @returns {void}
+ */
+function broadcastFrontendModelEvent(configuration, modelName, event) {
+  if (typeof configuration.broadcastToChannel !== "function") return
+
+  const body = {
+    action: event.action,
+    id: event.id,
+    model: modelName,
+    ...(event.record ? {record: serializeFrontendModelTransportValue(event.record)} : {})
+  }
+
+  configuration.broadcastToChannel(FRONTEND_MODELS_CHANNEL_NAME, {model: modelName}, body)
+}

package/src/http-client/header.js

@@ -0,0 +1,17 @@
+// @ts-check
+
+export default class Header {
+  /**
+   * Runs constructor.
+   * @param {string} name - Name.
+   * @param {string | number} value - Value to use.
+   */
+  constructor(name, value) {
+    this.name = name
+    this.value = value
+  }
+
+  getName() { return this.name }
+  getValue() { return this.value }
+  toString() { return `${this.getName()}: ${this.getValue()}` }
+}

package/src/http-client/index.js

@@ -0,0 +1,139 @@
+// @ts-check
+
+import net from "net"
+import Request from "./request.js"
+import Response from "./response.js"
+import Logger from "../logger.js"
+
+export default class HttpClient {
+  /**
+   * Runs constructor.
+   * @param {object} args - Options object.
+   * @param {boolean} [args.debug] - Whether debug.
+   * @param {Array<import("./header.js").default>} [args.headers] - Header list.
+   * @param {string} [args.version] - Version.
+   */
+  constructor({debug = false, headers, version = "1.1"}) {
+    this.headers = headers || []
+    this.logger = new Logger(this, {debug})
+    this.version = version
+  }
+
+  connect() {
+    return new Promise((resolve, reject) => {
+      this.connectionReject = reject
+      this.connection = net.createConnection(3006, "127.0.0.1", () => {
+        this.connectionReject = null
+        resolve(null)
+      })
+
+      this.connection.on("data", this.onConnectionData)
+      this.connection.on("end", this.onConnectionEnd)
+      this.connection.on("error", this.onConnectionError)
+    })
+  }
+
+  /**
+   * Runs get.
+   * @param {string} path - Path.
+   * @param {object} [options] - Options object.
+   * @param {Array<import("./header.js").default>} [options.headers] - Header list.
+   * @returns {Promise<{request: import("./request.js").default, response: import("./response.js").default}>} - Resolves with the request/response pair.
+   */
+  get(path, {headers} = {}) {
+    if (!this.connection) throw new Error("Not connected yet")
+
+    return new Promise((resolve, reject) => {
+      this.currentRequestResolve = resolve
+      this.currentRequestReject = reject
+
+      const newHeaders = []
+
+      if (headers) {
+        for (const header of headers) {
+          newHeaders.push(header)
+        }
+      }
+
+      for (const header of this.headers) {
+        const existingNewHeader = newHeaders.find((newHeader) => {
+          return newHeader.getName().toLowerCase().trim() === header.getName().toLowerCase().trim()
+        })
+
+        if (!existingNewHeader) {
+      this.logger.debugLowLevel(() => `Pushing header from connection: ${header.toString()}`)
+          newHeaders.push(header)
+        }
+      }
+
+      this.currentResponse = new Response({method: "GET", onComplete: this.onResponseComplete})
+
+      this.currentRequest = new Request({headers: newHeaders, method: "GET", path, version: "1.0"})
+      this.currentRequest.stream((chunk) => {
+        this.logger.debugLowLevel(() => `Writing: ${chunk}`)
+
+        if (!this.connection) {
+          throw new Error("No connection to write to")
+        }
+
+        this.connection.write(chunk, "utf8", (error) => {
+          if (error) {
+            if (!this.currentRequestReject) throw new Error("No current request reject function")
+
+            this.currentRequestReject(error)
+          }
+        })
+      })
+    })
+  }
+
+  /**
+   * On connection data.
+   * @param {Buffer} data - Data payload.
+   */
+  onConnectionData = (data) => {
+    if (!this.currentResponse) throw new Error("No current response to feed data to")
+
+    this.currentResponse.feed(data)
+  }
+
+  onConnectionEnd = () => {
+    this.connection = null
+  }
+
+  /**
+   * On connection error.
+   * @param {Error} error - Error instance.
+   */
+  onConnectionError = (error) => {
+    if (this.connectionReject) {
+      this.connectionReject(error)
+    } else {
+      this.logger.error("HttpClient onConnectionError", error)
+    }
+  }
+
+  isConnected() {
+    if (this.connection) {
+      return true
+    }
+
+    return false
+  }
+
+  onResponseComplete = () => {
+    if (!this.currentRequestResolve) throw new Error("No current request resolve function")
+    if (!this.currentRequest) throw new Error("No current request")
+    if (!this.currentResponse) throw new Error("No current response")
+
+    this.currentRequestResolve({
+      request: this.currentRequest,
+      response: this.currentResponse
+    })
+
+    this.currentRequestResolve = null
+    this.currentRequestReject = null
+    this.currentRequest = null
+    this.currentResponse = null
+  }
+}

package/src/http-client/request.js

@@ -0,0 +1,94 @@
+// @ts-check
+
+import Header from "./header.js"
+
+export default class Request {
+  /**
+   * Runs constructor.
+   * @param {object} args - Options object.
+   * @param {string} [args.body] - Request body.
+   * @param {string} args.method - HTTP method.
+   * @param {Header[]} args.headers - Header list.
+   * @param {string} args.path - Path.
+   * @param {string} args.version - Version.
+   */
+  constructor({body, method = "GET", headers = [], path, version = "1.1"}) {
+    this.body = body
+    this.headers = headers
+    this.method = method
+    this.path = path
+    this.version = version
+  }
+
+  asString() {
+    let requestString = ""
+
+    this.stream((chunk) => {
+      requestString += chunk
+    })
+
+    return requestString
+  }
+
+  /**
+   * Runs get header.
+   * @param {string} name - Name.
+   * @returns {Header} - The header.
+   */
+  getHeader(name) {
+    const compareName = name.toLowerCase().trim()
+
+    for (const header of this.headers) {
+      const headerCompareName = header.getName().toLowerCase().trim()
+
+      if (compareName == headerCompareName) {
+        return header
+      }
+    }
+
+    throw new Error(`Header ${name} not found`)
+  }
+
+  /**
+   * Runs add header.
+   * @param {string} name - Name.
+   * @param {string | number} value - Value to use.
+   * @returns {void} - No return value.
+   */
+  addHeader(name, value) {
+    this.headers.push(new Header(name, value))
+  }
+
+  /**
+   * Runs prepare.
+   * @returns {void} - No return value.
+   */
+  prepare() {
+    if (this.body) {
+      this.addHeader("Content-Length", Buffer.from(this.body).byteLength)
+    }
+  }
+
+  /**
+   * Runs stream.
+   * @param {function(string) : void} callback - Callback function.
+   * @returns {void} - No return value.
+   */
+  stream(callback) {
+    this.prepare()
+
+    const requestString = `${this.method} ${this.path} HTTP/${this.version}\r\n`
+
+    callback(requestString)
+
+    for (const header of this.headers) {
+      callback(`${header.toString()}\r\n`)
+    }
+
+    callback(`\r\n`)
+
+    if (this.body) {
+      callback(this.body)
+    }
+  }
+}

package/src/http-client/response.js

@@ -0,0 +1,151 @@
+// @ts-check
+
+import Header from "./header.js"
+import {deserializeFrontendModelTransportValue} from "../frontend-models/transport-serialization.js"
+
+export default class Response {
+  /**
+   * Runs constructor.
+   * @param {object} args - Options object.
+   * @param {string} args.method - HTTP method.
+   * @param {function() : void} args.onComplete - On complete.
+   */
+  constructor({method = "GET", onComplete}) {
+    if (!method) throw new Error(`Invalid method given: ${method}`)
+
+    /**
+     * Narrows the runtime value to the documented type.
+      @type {Header[]} */
+    this.headers = []
+
+    this.method = method.toUpperCase().trim()
+    this.onComplete = onComplete
+    this.state = "status-line"
+
+    /**
+     * Narrows the runtime value to the documented type.
+      @type {Buffer} */
+    this.response = Buffer.alloc(0);
+  }
+
+  /**
+   * Runs feed.
+   * @param {Buffer} data - Response data chunk.
+   */
+  feed(data) {
+    this.response = Buffer.concat([this.response, data])
+    this.tryToParse()
+  }
+
+  /**
+   * Runs get header.
+   * @param {string} name - Name.
+   * @returns {Header} - The header.
+   */
+  getHeader(name) {
+    const compareName = name.toLowerCase().trim()
+
+    for (const header of this.headers) {
+      const headerCompareName = header.getName().toLowerCase().trim()
+
+      if (compareName == headerCompareName) {
+        return header
+      }
+    }
+
+    throw new Error(`Header ${name} not found`)
+  }
+
+  json() {
+    const contentTypeHeader = this.getHeader("Content-Type")?.getValue()
+
+    if (typeof contentTypeHeader != "string") throw new Error(`Content-Type wasn't a string: ${contentTypeHeader}`)
+
+    if (!contentTypeHeader.toLowerCase().trim().startsWith("application/json")) {
+      throw new Error(`Content-Type is not JSON: ${contentTypeHeader}`)
+    }
+
+    const body = this.response.toString()
+    const json = JSON.parse(body)
+
+    return deserializeFrontendModelTransportValue(json)
+  }
+
+  tryToParse() {
+    while (true) {
+      if (this.state == "body") {
+        const contentLengthNumber = this._contentLengthNumber()
+
+        if (this.response.byteLength >= contentLengthNumber) {
+          this.completeResponse()
+          break
+        }
+      } else {
+        const response = this.response.toString()
+        let lineEndIndex = response.indexOf("\r\n")
+        let lineEndLength = 2
+
+        if (lineEndIndex === -1) {
+          lineEndIndex = response.indexOf("\n")
+          lineEndLength = 1
+        }
+
+        if (lineEndIndex === -1) {
+          break // We need to get fed more to continue reading
+        } else {
+          const line = response.substring(0, lineEndIndex)
+
+          this.response = this.response.slice(lineEndIndex + lineEndLength)
+
+          if (this.state == "status-line") {
+            this.statusLine = line
+            this.state = "headers"
+          } else if (this.state == "headers") {
+            if (line == "") {
+              const contentLengthNumber = this._contentLengthNumber()
+
+              if (!contentLengthNumber) {
+                this.completeResponse()
+                break
+              } else {
+                this.state = "body"
+              }
+            } else {
+              const headerMatch = line.match(/^(.+?):\s*(.+)$/)
+
+              if (!headerMatch) throw new Error(`Invalid header: ${line}`)
+
+              const header = new Header(headerMatch[1], headerMatch[2])
+
+              this.headers.push(header)
+            }
+          } else {
+            throw new Error(`Unexpected state: ${this.state}`)
+          }
+        }
+      }
+    }
+  }
+
+  completeResponse() {
+    this.state = "done"
+    this.onComplete()
+  }
+
+  /**
+   * Runs content length number.
+   * @returns {number} - The content length number.
+   */
+  _contentLengthNumber() {
+    const header = this.headers.find((currentHeader) => currentHeader.getName().toLowerCase() == "content-length")
+
+    if (!header) return 0
+
+    const contentLengthValue = header.getValue()
+
+    if (typeof contentLengthValue === "number") return contentLengthValue
+    if (typeof contentLengthValue === "string") return parseInt(contentLengthValue)
+
+    throw new Error(`Content-Length is not a number: ${contentLengthValue}`)
+  }
+}

package/src/http-client/websocket-client.js

@@ -0,0 +1,27 @@
+// @ts-check
+
+import SnapReqWebSocketClient from "snapreq/websocket"
+import {deserializeFrontendModelTransportValue} from "../frontend-models/transport-serialization.js"
+
+const DEFAULT_URL = "ws://127.0.0.1:3006/websocket"
+
+/**
+ * Velocious's WebSocket client. The cross-platform connection/session/channel
+ * machinery lives in snapreq's `SnapReqWebSocketClient`; this thin subclass only
+ * pre-wires the two Velocious-specific defaults: the local development websocket
+ * URL and frontend-model transport deserialization inside `response.json()`.
+ * @augments SnapReqWebSocketClient
+ */
+export default class VelociousWebsocketClient extends SnapReqWebSocketClient {
+  /**
+   * Runs constructor.
+   * @param {Partial<ConstructorParameters<typeof SnapReqWebSocketClient>[0]>} [args] - Options forwarded to `SnapReqWebSocketClient`.
+   */
+  constructor(args = {}) {
+    super({
+      ...args,
+      url: args.url ?? DEFAULT_URL,
+      deserialize: args.deserialize ?? deserializeFrontendModelTransportValue
+    })
+  }
+}