velocious 1.0.430 → 1.0.431

package/src/application.js

@@ -0,0 +1,229 @@
+// @ts-check
+
+import AppRoutes from "./routes/app-routes.js"
+import Logger from "./logger.js"
+import HttpServer from "./http-server/index.js"
+import HttpServerLock from "./http-server/server-lock.js"
+import websocketEventsHost from "./http-server/websocket-events-host.js"
+import restArgsError from "./utils/rest-args-error.js"
+
+/**
+ * HttpServerConfiguration type.
+  @typedef {import("./configuration-types.js").HttpServerConfiguration} HttpServerConfiguration */
+
+export default class VelociousApplication {
+  /**
+   * Runs constructor.
+   * @param {object} args - Options object.
+   * @param {import("./configuration.js").default} args.configuration - Configuration instance.
+   * @param {HttpServerConfiguration} [args.httpServer] - Http server.
+   * @param {string} args.type - Type identifier.
+   */
+  constructor({configuration, httpServer, type, ...restArgs}) {
+    restArgsError(restArgs)
+
+    if (!configuration) throw new Error("configuration is required")
+
+    this.configuration = configuration
+
+    /**
+     * Stores the http server configuration value.
+      @type {HttpServerConfiguration} */
+    this.httpServerConfiguration = httpServer ?? {}
+
+    this.logger = new Logger(this)
+    this._type = type
+    /**
+     * Stores the http server lock value.
+      @type {HttpServerLock | undefined} */
+    this.httpServerLock = undefined
+  }
+
+  /**
+   * Runs get type.
+   * @returns {string} - The type.
+   */
+  getType() { return this._type }
+
+  /**
+   * Runs initialize.
+   * @returns {Promise<void>} - Resolves when complete.
+   */
+  async initialize() {
+    const routes = await AppRoutes.getRoutes(this.configuration)
+
+    await this.configuration.initialize({type: this.getType()})
+
+    this.configuration.setRoutes(routes)
+
+    if (!this.configuration.isDatabasePoolInitialized()) {
+      await this.configuration.initializeDatabasePool()
+    }
+
+  }
+
+  /**
+   * Runs is active.
+   * @returns {boolean} - Whether active.
+   */
+  isActive() {
+    if (this.httpServer) {
+      return this.httpServer?.isActive()
+    }
+
+    return false
+  }
+
+  /**
+   * Runs run.
+   * @param {function() : void} callback - Callback function.
+   * @returns {Promise<void>} - Resolves when complete.
+   */
+  async run(callback) {
+    await this.startHttpServer()
+
+    try {
+      await callback()
+    } finally {
+      await this.stop()
+    }
+  }
+
+  /**
+   * Runs start http server.
+   * @returns {Promise<void>} - Resolves when complete.
+   */
+  async startHttpServer() {
+    const {configuration} = this
+    const httpServerConfiguration = {
+      ...configuration.httpServer,
+      ...this.httpServerConfiguration
+    }
+    const port = httpServerConfiguration.port ?? 3006
+    const host = httpServerConfiguration.host
+
+    await this.logger.debug(`Starting server on port ${port}`)
+    await this.acquireHttpServerLock({configuration, host: host ?? "0.0.0.0", port})
+    await this.startLockedHttpServer({configuration, host, httpServerConfiguration, port})
+  }
+
+  /**
+   * Runs start locked http server.
+   * @param {object} args - HTTP server startup arguments.
+   * @param {import("./configuration.js").default} args.configuration - Configuration instance.
+   * @param {string} [args.host] - HTTP server host.
+   * @param {Record<string, ?>} args.httpServerConfiguration - Merged HTTP server configuration.
+   * @param {number} args.port - HTTP server port.
+   * @returns {Promise<void>} - Resolves after the HTTP server has started.
+   */
+  async startLockedHttpServer({configuration, host, httpServerConfiguration, port}) {
+    try {
+      if (!configuration.getWebsocketEvents()) {
+        configuration.setWebsocketEvents(/**
+                                          * Types the following value.
+                                           @type {?} */ (websocketEventsHost))
+      }
+
+      await configuration.connectBeacon({peerType: "server"})
+
+      this.httpServer = this.createHttpServer({
+        configuration,
+        host,
+        inProcess: httpServerConfiguration.inProcess,
+        maxWorkers: httpServerConfiguration.maxWorkers,
+        port,
+        workers: httpServerConfiguration.workers
+      })
+      this.httpServer.events.on("close", this.onHttpServerClose)
+      configuration._httpServerInstance = this.httpServer
+
+      await this.httpServer.start()
+    } catch (error) {
+      await this.releaseHttpServerLock()
+      configuration._httpServerInstance = undefined
+
+      throw error
+    }
+  }
+
+  /**
+   * Runs acquire http server lock.
+   * @param {object} args - Lock acquisition arguments.
+   * @param {import("./configuration.js").default} args.configuration - Configuration instance.
+   * @param {string} args.host - HTTP server host.
+   * @param {number} args.port - HTTP server port.
+   * @returns {Promise<void>} - Resolves after acquiring the server lock when needed.
+   */
+  async acquireHttpServerLock({configuration, host, port}) {
+    if (this.getType() === "test-runner") return
+
+    const httpServerLock = new HttpServerLock({configuration, host, port})
+    await httpServerLock.acquire()
+    this.httpServerLock = httpServerLock
+  }
+
+  /**
+   * Runs create http server.
+   * @param {object} args - HTTP server arguments.
+   * @param {import("./configuration.js").default} args.configuration - Configuration instance.
+   * @param {string} [args.host] - Host.
+   * @param {boolean} [args.inProcess] - Run HTTP handlers in the main thread.
+   * @param {number} [args.maxWorkers] - Max workers.
+   * @param {number} args.port - Port.
+   * @param {number} [args.workers] - Worker count.
+   * @returns {HttpServer} - HTTP server instance.
+   */
+  createHttpServer({configuration, host, inProcess, maxWorkers, port, workers}) {
+    return new HttpServer({configuration, host, inProcess, maxWorkers, port, workers})
+  }
+
+  /**
+   * Runs stop.
+   * @returns {Promise<void>} - Resolves when complete.
+   */
+  async stop() {
+    await this.logger.debug("Stopping server")
+
+    try {
+      await this.httpServer?.stop()
+      this.configuration._httpServerInstance = undefined
+      await this.configuration.disconnectBeacon()
+      await this.configuration.closeDatabaseConnections()
+    } finally {
+      await this.releaseHttpServerLock()
+    }
+  }
+
+  /**
+   * Runs release http server lock.
+   * @returns {Promise<void>} - Resolves after the HTTP server lock has been released.
+   */
+  async releaseHttpServerLock() {
+    const {httpServerLock} = this
+
+    this.httpServerLock = undefined
+    if (httpServerLock) await httpServerLock.release()
+  }
+
+  /**
+   * On http server close.
+   * @returns {void} - No return value.
+   */
+  onHttpServerClose = () => {
+    this.logger.debug("HTTP server closed")
+
+    if (this.waitResolve) {
+      this.waitResolve()
+    }
+  }
+
+  /**
+   * Runs wait.
+   * @returns {Promise<void>} - Resolves when complete.
+   */
+  wait() {
+    return new Promise((resolve) => {
+      this.waitResolve = resolve
+    })
+  }
+}

package/src/authorization/ability.js

@@ -0,0 +1,329 @@
+// @ts-check
+
+/**
+ * Defines this typedef.
+ * @template {typeof import("../database/record/index.js").default} [MC=typeof import("../database/record/index.js").default]
+ * @typedef {Record<string, ?> | string | ((query: import("../database/query/model-class-query.js").default<MC>, args: {ability: VelociousAuthorizationAbility, action: string, modelClass: MC}) => void | import("../database/query/model-class-query.js").default<MC>)} AbilityConditionsType
+ */
+
+/**
+ * AbilityRuleType type.
+ * @typedef {object} AbilityRuleType
+ * @property {string[]} actions - Actions covered by rule.
+ * @property {typeof import("../database/record/index.js").default} modelClass - Model class.
+ * @property {AbilityConditionsType | undefined} conditions - Conditions.
+ * @property {"allow" | "deny"} effect - Rule effect.
+ */
+
+/** CanCan-style ability object for query-level access control. */
+export default class VelociousAuthorizationAbility {
+  /**
+   * Create.
+    @type {string[]} */
+  static CREATE = ["create"]
+
+  /**
+   * Read.
+    @type {string[]} */
+  static READ = ["read"]
+
+  /**
+   * Update.
+    @type {string[]} */
+  static UPDATE = ["update"]
+
+  /**
+   * Destroy.
+    @type {string[]} */
+  static DESTROY = ["destroy"]
+
+  /**
+   * Crud.
+    @type {string[]} */
+  static CRUD = ["create", "read", "update", "destroy"]
+
+  /**
+   * Runs constructor.
+   * @param {object} args - Ability args.
+   * @param {Record<string, ?>} [args.context] - Ability context.
+   * @param {Record<string, ?>} [args.locals] - Ability locals.
+   * @param {Array<typeof import("./base-resource.js").default>} [args.resources] - Resource classes.
+   */
+  constructor({context = {}, locals = {}, resources} = {}) {
+    this.context = context
+    this.locals = locals
+    this.resources = resources || this._resolveResourcesFromConfiguration()
+
+    /**
+     * Narrows the runtime value to the documented type.
+      @type {AbilityRuleType[]} */
+    this.rules = []
+
+    /**
+     * Narrows the runtime value to the documented type.
+      @type {Record<string, boolean>} */
+    this.loadedModelClassAbilities = {}
+  }
+
+  /**
+   * Auto-resolves resource classes from the configuration's backendProjects when no explicit resources are provided.
+   * @returns {Array<typeof import("./base-resource.js").default>} Resolved resource classes.
+   */
+  _resolveResourcesFromConfiguration() {
+    const configuration = this.context?.configuration
+
+    if (!configuration || typeof configuration.getBackendProjects !== "function") {
+      return []
+    }
+
+    /**
+     * Resolved.
+      @type {Array<typeof import("./base-resource.js").default>} */
+    const resolved = []
+    const backendProjects = configuration.getBackendProjects()
+
+    for (const backendProject of backendProjects) {
+      const frontendModels = backendProject.frontendModels
+
+      if (!frontendModels || typeof frontendModels !== "object") continue
+
+      for (const resourceDefinition of Object.values(frontendModels)) {
+        if (typeof resourceDefinition === "function" && typeof resourceDefinition.modelClass === "function") {
+          resolved.push(resourceDefinition)
+        }
+      }
+    }
+
+    return resolved
+  }
+
+  /**
+   * Runs get context.
+   * @returns {Record<string, ?>} - Context.
+   */
+  getContext() {
+    return this.context
+  }
+
+  /**
+   * Runs get locals.
+   * @returns {Record<string, ?>} - Locals.
+   */
+  getLocals() {
+    return this.locals
+  }
+
+  /**
+   * Runs current user.
+   * @returns {?} - Current user from context.
+   */
+  currentUser() {
+    return this.context.currentUser
+  }
+
+  /**
+   * Runs can.
+   * @param {string | string[]} actions - Action(s).
+   * @param {typeof import("../database/record/index.js").default} modelClass - Model class.
+   * @param {AbilityConditionsType} [conditions] - Conditions.
+   * @returns {void} - No return value.
+   */
+  can(actions, modelClass, conditions) {
+    this.addRule({actions, conditions, effect: "allow", modelClass})
+  }
+
+  /**
+   * Runs cannot.
+   * @param {string | string[]} actions - Action(s).
+   * @param {typeof import("../database/record/index.js").default} modelClass - Model class.
+   * @param {AbilityConditionsType} [conditions] - Conditions.
+   * @returns {void} - No return value.
+   */
+  cannot(actions, modelClass, conditions) {
+    this.addRule({actions, conditions, effect: "deny", modelClass})
+  }
+
+  /**
+   * Runs add rule.
+   * @param {object} args - Rule args.
+   * @param {string | string[]} args.actions - Action(s).
+   * @param {AbilityConditionsType} [args.conditions] - Conditions.
+   * @param {"allow" | "deny"} args.effect - Effect.
+   * @param {typeof import("../database/record/index.js").default} args.modelClass - Model class.
+   * @returns {void} - No return value.
+   */
+  addRule({actions, conditions, effect, modelClass}) {
+    const normalizedActions = Array.isArray(actions) ? actions : [actions]
+
+    this.rules.push({actions: normalizedActions, conditions, effect, modelClass})
+  }
+
+  /**
+   * Runs load abilities for model class.
+   * @param {typeof import("../database/record/index.js").default} modelClass - Model class.
+   * @returns {void} - No return value.
+   */
+  loadAbilitiesForModelClass(modelClass) {
+    const key = modelClass.getModelName()
+
+    if (this.loadedModelClassAbilities[key]) return
+
+    this.loadedModelClassAbilities[key] = true
+
+    for (const ResourceClass of this.resources) {
+      const resourceModelClass = ResourceClass.modelClass()
+
+      if (!resourceModelClass) continue
+      if (resourceModelClass !== modelClass) continue
+
+      const resourceInstance = new ResourceClass({
+        ability: this,
+        context: this.context,
+        locals: this.locals
+      })
+
+      resourceInstance.abilities()
+    }
+  }
+
+  /**
+   * Runs apply to query.
+   * @param {object} args - Query args.
+   * @param {string} args.action - Requested action.
+   * @param {typeof import("../database/record/index.js").default} args.modelClass - Model class.
+   * @param {import("../database/query/model-class-query.js").default<typeof import("../database/record/index.js").default>} args.query - Query.
+   * @returns {import("../database/query/model-class-query.js").default<typeof import("../database/record/index.js").default>} - Authorized query.
+   */
+  applyToQuery({action, modelClass, query}) {
+    this.loadAbilitiesForModelClass(modelClass)
+
+    const applicableRules = this.rulesFor({action, modelClass})
+    const allowRules = applicableRules.filter((rule) => rule.effect === "allow")
+    const denyRules = applicableRules.filter((rule) => rule.effect === "deny")
+
+    if (allowRules.length === 0) {
+      return query.where("1=0")
+    }
+
+    if (allowRules.some((rule) => !rule.conditions)) {
+      this.applyDenyRules({action, denyRules, modelClass, query})
+      return query
+    }
+
+    const allowSqlParts = this.conditionSqlParts({action, modelClass, query, rules: allowRules})
+
+    if (allowSqlParts.length === 0) {
+      return query.where("1=0")
+    }
+
+    query.where(`(${allowSqlParts.join(" OR ")})`)
+    this.applyDenyRules({action, denyRules, modelClass, query})
+
+    return query
+  }
+
+  /**
+   * Runs rules for.
+   * @param {object} args - Rule lookup args.
+   * @param {string} args.action - Action.
+   * @param {typeof import("../database/record/index.js").default} args.modelClass - Model class.
+   * @returns {AbilityRuleType[]} - Matching rules.
+   */
+  rulesFor({action, modelClass}) {
+    return this.rules.filter((rule) => {
+      if (rule.modelClass !== modelClass) return false
+
+      return rule.actions.includes(action) || rule.actions.includes("manage")
+    })
+  }
+
+  /**
+   * Runs condition sql parts.
+   * @param {object} args - SQL args.
+   * @param {string} args.action - Action.
+   * @param {typeof import("../database/record/index.js").default} args.modelClass - Model class.
+   * @param {import("../database/query/model-class-query.js").default<typeof import("../database/record/index.js").default>} args.query - Base query.
+   * @param {AbilityRuleType[]} args.rules - Rules.
+   * @returns {string[]} - SQL condition parts.
+   */
+  conditionSqlParts({action, modelClass, query, rules}) {
+    const pk = modelClass.primaryKey()
+    const quotedBaseTable = query.driver.quoteTable(modelClass.tableName())
+    const quotedPk = query.driver.quoteColumn(pk)
+    const sqlParts = []
+
+    for (const rule of rules) {
+      if (!rule.conditions) continue
+
+      const scopedQuery = modelClass._newQuery()
+      const resultQuery = this.applyRuleCondition({
+        action,
+        conditions: rule.conditions,
+        modelClass,
+        query: scopedQuery
+      })
+      const finalQuery = resultQuery || scopedQuery
+      const selectedPkSql = `${quotedBaseTable}.${quotedPk}`
+
+      if (finalQuery._distinct) {
+        query.distinct(true)
+      }
+
+      finalQuery.select(selectedPkSql)
+
+      sqlParts.push(`${quotedBaseTable}.${quotedPk} IN (${finalQuery.toSql()})`)
+    }
+
+    return sqlParts
+  }
+
+  /**
+   * Runs apply deny rules.
+   * @param {object} args - Deny args.
+   * @param {string} args.action - Action.
+   * @param {AbilityRuleType[]} args.denyRules - Deny rules.
+   * @param {typeof import("../database/record/index.js").default} args.modelClass - Model class.
+   * @param {import("../database/query/model-class-query.js").default<typeof import("../database/record/index.js").default>} args.query - Query.
+   * @returns {void} - No return value.
+   */
+  applyDenyRules({action, denyRules, modelClass, query}) {
+    if (denyRules.length === 0) return
+
+    if (denyRules.some((rule) => !rule.conditions)) {
+      query.where("1=0")
+      return
+    }
+
+    const denySqlParts = this.conditionSqlParts({action, modelClass, query, rules: denyRules})
+
+    if (denySqlParts.length > 0) {
+      query.where(`NOT (${denySqlParts.join(" OR ")})`)
+    }
+  }
+
+  /**
+   * Runs apply rule condition.
+   * @param {object} args - Condition args.
+   * @param {string} args.action - Action.
+   * @param {AbilityConditionsType} args.conditions - Rule conditions.
+   * @param {typeof import("../database/record/index.js").default} args.modelClass - Model class.
+   * @param {import("../database/query/model-class-query.js").default<typeof import("../database/record/index.js").default>} args.query - Query.
+   * @returns {void | import("../database/query/model-class-query.js").default<typeof import("../database/record/index.js").default>} - Optional replacement query.
+   */
+  applyRuleCondition({action, conditions, modelClass, query}) {
+    if (typeof conditions === "string") {
+      query.where(conditions)
+      return
+    }
+
+    if (typeof conditions === "function") {
+      return conditions(query, {
+        ability: this,
+        action,
+        modelClass
+      })
+    }
+
+    query.where(conditions)
+  }
+}

package/src/authorization/base-resource.js

@@ -0,0 +1,143 @@
+// @ts-check
+
+/** Base class for authorization resources defining abilities for a model. */
+export default class AuthorizationBaseResource {
+  /**
+   * Model class.
+    @type {typeof import("../database/record/index.js").default | undefined} */
+  static ModelClass = undefined
+
+  /**
+   * Runs constructor.
+   * @param {object} args - Resource args.
+   * @param {import("./ability.js").default} [args.ability] - Ability instance.
+   * @param {import("../configuration-types.js").VelociousLooseObject} [args.context] - Ability context.
+   * @param {import("../configuration-types.js").VelociousLooseObject} [args.locals] - Ability locals.
+   */
+  constructor({ability, context = {}, locals = {}}) {
+    this.ability = ability
+    this.context = context
+    this.locals = locals
+  }
+
+  /**
+   * Runs model class.
+   * @returns {typeof import("../database/record/index.js").default | undefined} - Model class handled by this resource.
+   */
+  static modelClass() {
+    return this.ModelClass
+  }
+
+  /**
+   * Runs can.
+   * @template {typeof import("../database/record/index.js").default} MC
+   * @param {string | string[]} actions - Ability action(s).
+   * @param {import("./ability.js").AbilityConditionsType<MC>} [conditions] - Conditions.
+   * @returns {void} - No return value.
+   */
+  can(actions, conditions) {
+    this.assertResourceConditionsSignature({conditions, methodName: "can"})
+    this.requiredAbility().can(actions, this.requiredModelClass(), /** Narrows conditions to the runtime resource model class. @type {import("./ability.js").AbilityConditionsType<typeof import("../database/record/index.js").default> | undefined} */ (conditions))
+  }
+
+  /**
+   * Runs cannot.
+   * @template {typeof import("../database/record/index.js").default} MC
+   * @param {string | string[]} actions - Ability action(s).
+   * @param {import("./ability.js").AbilityConditionsType<MC>} [conditions] - Conditions.
+   * @returns {void} - No return value.
+   */
+  cannot(actions, conditions) {
+    this.assertResourceConditionsSignature({conditions, methodName: "cannot"})
+    this.requiredAbility().cannot(actions, this.requiredModelClass(), /** Narrows conditions to the runtime resource model class. @type {import("./ability.js").AbilityConditionsType<typeof import("../database/record/index.js").default> | undefined} */ (conditions))
+  }
+
+  /**
+   * Runs required ability.
+   * @returns {import("./ability.js").default} - Ability instance.
+   */
+  requiredAbility() {
+    if (!this.ability) {
+      throw new Error(`${this.constructor.name} requires an ability instance before defining abilities.`)
+    }
+
+    return this.ability
+  }
+
+  /**
+   * Runs required model class.
+   * @returns {typeof import("../database/record/index.js").default} - Model class handled by this resource.
+   */
+  requiredModelClass() {
+    const modelClass = /**
+                        * Narrows the runtime value to the documented type.
+                         @type {typeof AuthorizationBaseResource} */ (this.constructor).modelClass()
+
+    if (!modelClass) {
+      throw new Error(`${this.constructor.name} must define static ModelClass before calling ability helpers.`)
+    }
+
+    return modelClass
+  }
+
+  /**
+   * Runs assert resource conditions signature.
+   * @param {object} args - Signature args.
+   * @param {?} args.conditions - Conditions value.
+   * @param {"can" | "cannot"} args.methodName - Method name.
+   * @returns {void}
+   */
+  assertResourceConditionsSignature({conditions, methodName}) {
+    if (typeof conditions === "function" && "primaryKey" in conditions && "_newQuery" in conditions) {
+      throw new Error(`${this.constructor.name}.${methodName}(...) no longer accepts a model class. Define static ModelClass and pass only conditions.`)
+    }
+  }
+
+  /**
+   * Runs get context.
+   * @returns {import("../configuration-types.js").VelociousLooseObject} - Ability context.
+   */
+  getContext() {
+    return this.context
+  }
+
+  /**
+   * Runs get locals.
+   * @returns {import("../configuration-types.js").VelociousLooseObject} - Ability locals.
+   */
+  getLocals() {
+    return this.locals
+  }
+
+  /**
+   * Runs current user.
+   * @returns {import("../configuration-types.js").VelociousLooseObject | null | undefined} - Current user from context.
+   */
+  currentUser() {
+    return this.context.currentUser
+  }
+
+  /**
+   * Runs request.
+   * @returns {import("../http-server/client/request.js").default | import("../http-server/client/websocket-request.js").default | undefined} - Request from context.
+   */
+  request() {
+    return this.context.request
+  }
+
+  /**
+   * Runs params.
+   * @returns {import("../configuration-types.js").VelociousLooseObject | undefined} - Params from context.
+   */
+  params() {
+    return this.context.params
+  }
+
+  /**
+   * Runs abilities.
+   * @returns {void} - Implement in subclasses to define abilities.
+   */
+  abilities() {
+    // No-op by default.
+  }
+}