@radio-garden/ditojs-server 2.85.2-0.5067ad799

package/src/controllers/ControllerAction.js

@@ -0,0 +1,370 @@
+import { isString, isObject, asArray, clone, deprecate } from '@ditojs/utils'
+import { convertModelsToJson } from '../utils/model.js'
+
+export default class ControllerAction {
+  constructor(
+    controller,
+    actions,
+    handler,
+    type,
+    name,
+    method,
+    path,
+    _authorize
+  ) {
+    const {
+      core = false,
+      scope,
+      authorize,
+      transacted,
+      parameters,
+      // TODO: `returns` was deprecated in May 2025 in favour of `response`.
+      // Remove this in 2026.
+      returns,
+      response = returns,
+      options = {},
+      ...additional
+    } = handler
+
+    if (returns) {
+      deprecate(
+        'The `returns` property is deprecated in favour of `response`. ' +
+        'Update your handler definition to use `response` instead.'
+      )
+    }
+
+    this.app = controller.app
+    this.controller = controller
+    this.actions = actions
+    this.handler = handler
+    this.type = type
+    this.name = name
+    this.identifier = `${type}:${name}`
+    this.method = method
+    this.path = path
+    this.scope = scope
+    // Allow action handlers to override the predetermined defaults for
+    // `authorize`:
+    this.authorize = authorize || _authorize
+    this.transacted = !!(
+      transacted ??
+      controller.transacted ??
+      // Core graph and assets operations are always transacted, unless the
+      // method is 'get':
+      (
+        core &&
+        method !== 'get' && (
+          controller.graph ||
+          controller.assets
+        )
+      )
+    )
+    this.authorization = controller.processAuthorize(this.authorize)
+    this.paramsName = ['post', 'put', 'patch'].includes(this.method)
+      ? 'body'
+      : 'query'
+    this.parameters = this.app.compileParametersValidator(parameters, {
+      async: true,
+      ...options.parameters,
+      dataName: this.paramsName
+    })
+    this.response = this.app.compileParametersValidator(asArray(response), {
+      async: true,
+      // Use patch validation for response, as we often don't return the
+      // full model with all properties, but only a subset of them.
+      patch: true,
+      // TODO: `returns` was deprecated in May 2025 in favour of `response`.
+      // Remove this in 2026.
+      ...options.returns,
+      ...options.response,
+      dataName: 'response'
+    })
+    // Copy over the additional properties, e.g. `cached` so application
+    // middleware can implement caching mechanisms:
+    Object.assign(this, additional)
+  }
+
+  // Possible values for `from` are:
+  // - 'path': Use `ctx.params` which is mapped to the route / path
+  // - 'query': Use `ctx.request.query`, regardless of the action's method.
+  // - 'body': Use `ctx.request.body`, regardless of the action's method.
+  getParams(ctx, from = this.paramsName) {
+    const params = from === 'path' ? ctx.params : ctx.request[from]
+    // koa-bodyparser always sets an object, even when there is no body.
+    // Detect this here and return null instead.
+    const isNull = (
+      from === 'body' &&
+      ctx.request.headers['content-length'] === '0' &&
+      Object.keys(params).length === 0
+    )
+    return isNull ? null : params
+  }
+
+  async callAction(ctx) {
+    const { params, wrapped } = await this.validateParameters(ctx)
+    const { args, member } = await this.collectArguments(ctx, params)
+    let filteredQuery = null
+    Object.defineProperty(ctx, 'filteredQuery', {
+      get: () => {
+        filteredQuery ??=
+          params && !wrapped && this.paramsName === 'query'
+            ? this.filterParameters(params)
+            : ctx.query
+        return filteredQuery
+      },
+      enumerable: false,
+      configurable: true
+    })
+    await this.controller.handleAuthorization(this.authorization, ctx, member)
+    const { identifier } = this
+    await this.controller.emitHook(`before:${identifier}`, false, ctx, ...args)
+    const response = await this.callHandler(ctx, ...args)
+    const result =
+      // Don't convert response to JSON if it isn't being validated, or if the
+      // response validation schema contains model references.
+      !this.response.validate || this.response.hasModelRefs
+        ? response
+        : convertModelsToJson(response)
+    return this.validateResponse(
+      await this.controller.emitHook(`after:${identifier}`, true, ctx, result)
+    )
+  }
+
+  async callHandler(ctx, ...args) {
+    return this.handler.call(this.actions, ctx, ...args)
+  }
+
+  createValidationError(options) {
+    return this.app.createValidationError(options)
+  }
+
+  async validateParameters(ctx) {
+    if (!this.parameters.validate) {
+      return { params: null, wrapped: false }
+    }
+    // NOTE: The data can be either an object or an array.
+    const data = this.getParams(ctx)
+    let params = {}
+    const { dataName } = this.parameters
+    let unwrapRoot = false
+    const errors = []
+    for (const {
+      name, // String: Property name to fetch from data. Overridable by `root`
+      type, // String: What type should this validated against / coerced to.
+      from // String: Allow parameters to be 'borrowed' from other objects.
+    } of this.parameters.list) {
+      // Don't validate member parameters as they get resolved separately after.
+      if (from === 'member') continue
+      const root = from === 'root'
+      let wrapRoot = root
+      let paramName = name
+      // If no name is provided, wrap the full root object as value and unwrap
+      // at the end, see `unwrapRoot`.
+      if (!paramName) {
+        paramName = dataName
+        wrapRoot = true
+        unwrapRoot = true
+      }
+      // Since validation also performs coercion, always create clones of the
+      // params so that this doesn't modify the data on `ctx`.
+      if (from && !root) {
+        // Allow parameters to be 'borrowed' from other objects.
+        const source = this.getParams(ctx, from)
+        // See above for an explanation of `clone()`:
+        params[paramName] = clone(wrapRoot ? source : source?.[paramName])
+      } else if (wrapRoot) {
+        // If root is to be used, replace `params` with a new object on which
+        // to set the root object to validate under `parameters.paramName`
+        if (params === data) {
+          params = {}
+        }
+        params[paramName] = clone(data)
+      } else {
+        params[paramName] = clone(data[paramName])
+      }
+      try {
+        const value = params[paramName]
+        // `parameters.validate(params)` coerces data in the query to the
+        // required formats, according to the rules specified here:
+        // https://github.com/epoberezkin/ajv/blob/master/COERCION.md
+        // Coercion isn't currently offered for 'object' and 'date' types,
+        // so handle these cases prior to the call of `parameters.validate()`:
+        const coerced = this.coerceValue(type, value, {
+          // The model validation is handled separately through `$ref`.
+          skipValidation: true
+        })
+        // If coercion happened, replace value in params with coerced one:
+        if (coerced !== value) {
+          params[paramName] = coerced
+        }
+      } catch (err) {
+        // Convert error to Ajv validation error format:
+        errors.push({
+          dataPath: `.${paramName}`, // JavaScript property access notation
+          keyword: 'type',
+          message: err.message || err.toString(),
+          params: { type }
+        })
+      }
+    }
+
+    const getData = () => (unwrapRoot ? params[dataName] : params)
+    try {
+      await this.parameters.validate(params)
+      const data = getData()
+      return { params: data, wrapped: data !== params }
+    } catch (error) {
+      if (error.errors) {
+        errors.push(...error.errors)
+      } else {
+        throw error
+      }
+    }
+    if (errors.length > 0) {
+      throw this.createValidationError({
+        type: 'ParameterValidation',
+        message: 'The provided action parameters are not valid',
+        errors,
+        json: getData()
+      })
+    }
+  }
+
+  async validateResponse(response) {
+    if (this.response.validate) {
+      const responseName = this.handler.response.name
+      const responseWrapped = !!responseName
+      // Use dataName if no name is given, see:
+      // Application.compileParametersValidator(response, { dataName })
+      const dataName = responseName || this.response.dataName
+      const wrapped = { [dataName]: response }
+      // If a named result is defined, return the data wrapped,
+      // otherwise return the original unwrapped result object.
+      const getResult = () => (responseWrapped ? wrapped : response)
+      try {
+        await this.response.validate(wrapped)
+        return getResult()
+      } catch (error) {
+        // If the error contains errors, add them to the validation error:
+        const { errors } = error
+        const regexp = new RegExp(`^/${dataName}`)
+        throw this.createValidationError({
+          type: 'ResultValidation',
+          message: 'The returned action result is not valid',
+          errors: responseWrapped
+            ? errors
+            : errors.map(error => ({
+                ...error,
+                instancePath: error.instancePath.replace(regexp, '')
+              })),
+          json: getResult()
+        })
+      }
+    }
+    return response
+  }
+
+  async collectArguments(ctx, params) {
+    const { list, asObject } = this.parameters
+
+    const args = asObject ? [{}] : []
+    const addArgument = (name, value) => {
+      if (asObject) {
+        args[0][name] = value
+      } else {
+        args.push(value)
+      }
+    }
+
+    let member = null
+    // If we have parameters, add them to the arguments now,
+    // while also keeping track of consumed parameters:
+    for (const param of list) {
+      const { name, from } = param
+      // Handle `{ from: 'member' }` parameters separately, by delegating to
+      // `getMember()` to resolve to the given member.
+      if (from === 'member') {
+        member = await this.getMember(ctx, param)
+        addArgument(name, member)
+      } else {
+        // If no name is provided, use the body object (params)
+        addArgument(name, name ? params[name] : params)
+      }
+    }
+    return { args, member }
+  }
+
+  filterParameters(params) {
+    const filtered = {}
+    const consumedNames = Object.fromEntries(
+      this.parameters.list
+        .filter(param => !!param.name)
+        .map(param => [param.name, true])
+    )
+    for (const [key, value] of Object.entries(params)) {
+      if (!consumedNames[key]) {
+        filtered[key] = value
+      }
+    }
+    return filtered
+  }
+
+  coerceValue(type, value, modelOptions) {
+    // See if param needs additional coercion:
+    if (value && ['date', 'datetime', 'timestamp'].includes(type)) {
+      value = new Date(value)
+    } else {
+      // See if the defined type(s) require coercion to objects:
+      const objectType = asArray(type).find(
+        // Coerce to object if type is 'object' or a known model name.
+        type => type === 'object' || type in this.app.models
+      )
+      if (objectType) {
+        if (value && isString(value)) {
+          if (!/^\{.*\}$/.test(value)) {
+            // Convert simplified Dito.js object notation to JSON, supporting:
+            // - `"key1":X, "key2":Y` (curly braces are added and parsed through
+            //   `JSON.parse()`)
+            // - `key1:X,key2:Y` (a simple parser is applied, splitting into
+            //   entries and key/value pairs, values are parsed with
+            //   `JSON.parse()`, falling back to string.
+            if (/"/.test(value)) {
+              // Just add the curly braces and parse as JSON
+              value = JSON.parse(`{${value}}`)
+            } else {
+              // A simple version of named key/value pairs, values can be
+              // strings or numbers.
+              value = Object.fromEntries(
+                value.split(/\s*,\s*/g).map(entry => {
+                  let [key, val] = entry.split(/\s*:\s*/)
+                  try {
+                    // Try parsing basic types, but fall back to unquoted
+                    // string.
+                    val = JSON.parse(val)
+                  } catch {}
+                  return [key, val]
+                })
+              )
+            }
+          } else {
+            value = JSON.parse(value)
+          }
+        }
+        if (objectType !== 'object' && isObject(value)) {
+          // Convert the Pojo to the desired Dito.js model:
+          const modelClass = this.app.models[objectType]
+          if (modelClass && !(value instanceof modelClass)) {
+            value = modelClass.fromJson(value, modelOptions)
+          }
+        }
+      }
+    }
+    return value
+  }
+
+  async getMember(/* ctx, param */) {
+    // This is only defined in `MemberAction`, where it resolves to the member
+    // represented by the given route.
+    return null
+  }
+}

package/src/controllers/MemberAction.js

@@ -0,0 +1,27 @@
+import ControllerAction from './ControllerAction.js'
+
+export default class MemberAction extends ControllerAction {
+  // @override
+  async callAction(ctx) {
+    // Include `ctx.memberId` for convenient access in member actions.
+    return super.callAction(this.controller.getContextWithMemberId(ctx))
+  }
+
+  // @override
+  async getMember(ctx, param) {
+    // member parameters can provide special query parameters as well,
+    // and they can even control `forUpdate()` behavior:
+    // {
+    //   from: 'member',
+    //   query: { ... },
+    //   forUpdate: true,
+    //   modify: query => query.debug()
+    // }
+    // These are passed on to and handled in `CollectionController#getMember()`.
+    // For handling of `from: 'member'` and calling of
+    // `MemberAction.getMember()`, see `ControllerAction#collectArguments()`.
+    // Pass on `this.handler` as `base` for `setupQuery()`,
+    // to handle the setting of `handler.scope` & co. on the query.
+    return this.controller.getMember(ctx, this.handler, param)
+  }
+}

package/src/controllers/ModelController.js

@@ -0,0 +1,63 @@
+import pluralize from 'pluralize'
+import { isObject, camelize } from '@ditojs/utils'
+import { CollectionController } from './CollectionController.js'
+import { RelationController } from './RelationController.js'
+import { ControllerError } from '../errors/index.js'
+import { setupPropertyInheritance } from '../utils/object.js'
+
+export class ModelController extends CollectionController {
+  configure() {
+    super.configure()
+    this.modelClass ||=
+      this.app.models[camelize(pluralize.singular(this.name), true)]
+  }
+
+  setup() {
+    super.setup()
+    this.setProperty('relations', this.setupRelations())
+  }
+
+  setupRelations() {
+    // Inherit `relations` from the controller and / or its sub-classes,
+    // then build inheritance chains for each relation object through
+    // `setupPropertyInheritance()`, before creating the relation controllers,
+    // which then carry on with setting up inheritance for their actions.
+    const relations = this.inheritValues('relations')
+    for (const name in relations) {
+      const relation = setupPropertyInheritance(relations, name)
+      if (isObject(relation)) {
+        relations[name] = this.setupRelation(relation, name)
+      } else {
+        throw new ControllerError(this, `Invalid relation '${name}'.`)
+      }
+    }
+    return relations
+  }
+
+  setupRelation(object, name) {
+    const relationInstance = this.modelClass.getRelations()[name]
+    const relationDefinition = this.modelClass.definition.relations[name]
+    if (!relationInstance || !relationDefinition) {
+      throw new ControllerError(this, `Relation '${name}' not found.`)
+    }
+    const relation = new RelationController(
+      this,
+      object,
+      relationInstance,
+      relationDefinition
+    )
+    // RelationController instances are not registered with the app, but are
+    // managed by their parent controller instead.
+    relation.configure()
+    relation.setup()
+    return relation
+  }
+
+  // @override
+  async execute(ctx, execute) {
+    const trx = ctx.transaction
+    const query = this.modelClass.query(trx)
+    this.setupQuery(query)
+    return execute(query, trx)
+  }
+}

package/src/controllers/RelationController.js

@@ -0,0 +1,93 @@
+import { asArray } from '@ditojs/utils'
+import { CollectionController } from './CollectionController.js'
+import { ControllerError } from '../errors/index.js'
+import { setupPropertyInheritance } from '../utils/object.js'
+import { getScope } from '../utils/scope.js'
+
+export class RelationController extends CollectionController {
+  constructor(parent, object, relationInstance, relationDefinition) {
+    super(parent.app, null)
+    if (parent.modelClass !== relationInstance.ownerModelClass) {
+      throw new ControllerError(
+        parent,
+        `Invalid parent controller for relation '${relationInstance.name}'.`
+      )
+    }
+    this.parent = parent
+    this.object = object
+    this.relationInstance = relationInstance
+    this.relationDefinition = relationDefinition
+    this.name = relationInstance.name
+    this.modelClass = relationInstance.relatedModelClass
+    this.isOneToOne = relationInstance.isOneToOne()
+    this.relate = !relationDefinition.owner
+    this.unrelate = !relationDefinition.owner
+    // Inherit parent values:
+    this.graph = parent.graph
+    this.transacted = parent.transacted
+    this.level = parent.level + 1
+    if (parent.scope) {
+      // Inherit only the graph scopes since it's in its nature to propagate to
+      // relations:
+      this.scope = asArray(parent.scope).filter(scope => getScope(scope).graph)
+    }
+    // Copy over all fields in the relation object.
+    for (const key in object) {
+      // On the relation objects, the `collection` actions are stored in a
+      // `relation` object, to make sense both for one- and many-relations:
+      this.setProperty(key === 'relation' ? 'collection' : key, object[key])
+    }
+  }
+
+  // @override
+  configure() {
+    super.configure()
+    this.url = `${this.parent.url}/${this.parent.getPath('member', this.path)}`
+  }
+
+  // @override
+  inheritValues(type) {
+    // Since RelationController are mapped to nested `relations` objects in
+    // ModelController parents and are never extended directly in the user land
+    // code, inheritance works differently here than on the other controllers:
+    // ModelController already sets up inheritance for its `relations` object
+    // and its entries for each relation from which `object` is retrieved.
+    // But the actions per relation still need to have inheritance set up,
+    // using the values in its parent controller and potential super-classes,
+    // falling back on the definitions in RelationController and its inherited
+    // values from ModelController.
+    const values = setupPropertyInheritance(
+      this.object,
+      // On the relation objects, the `collection` actions are stored in a
+      // `relation` object, to make sense both for one- and many-relations:
+      type === 'collection' ? 'relation' : type,
+      // Set up inheritance for RelationController's override of `collection`
+      // and `member` objects, and use it as the base for further inheritance.
+      // NOTE: Currently they're empty, but they could allow local overrides.
+      super.inheritValues(type)
+    )
+    return values
+  }
+
+  // @override
+  async execute(ctx, execute) {
+    const id = this.parent.getMemberId(ctx)
+    return this.parent.execute(ctx, async (parentQuery, trx) => {
+      const model = await parentQuery
+        .ignoreScope()
+        .findById(id)
+        .throwIfNotFound()
+        // Explicitly only select the foreign key ids for more efficiency.
+        .select(...this.relationInstance.ownerProp.props)
+      // This is the same as `ModelController.execute()`, except for the use
+      // of `model.$relatedQuery()` instead of `modelClass.query()`:
+      const query = model.$relatedQuery(this.relationInstance.name, trx)
+      this.setupQuery(query)
+      return execute(query, trx)
+    })
+  }
+
+  collection = this.markAsCoreActions({})
+
+  member = this.markAsCoreActions({})
+}

package/src/controllers/UsersController.js

@@ -0,0 +1,64 @@
+import { ModelController } from './ModelController.js'
+
+export class UsersController extends ModelController {
+  collection = {
+    async 'post login'(ctx) {
+      let user
+      let error
+      try {
+        user = await this.modelClass.login(ctx)
+        await user.$patch({ lastLogin: new Date() }, ctx.transaction)
+      } catch (err) {
+        this.app.emit('error', err, ctx)
+        user = null
+        error = err.data?.message || err.message
+        ctx.status = err.status || 401
+      }
+      const success = !!user
+      return {
+        success,
+        authenticated: success && this.isAuthenticated(ctx),
+        user,
+        error
+      }
+    },
+
+    async 'post logout'(ctx) {
+      let success = false
+      if (this.isAuthenticated(ctx)) {
+        await ctx.logout()
+        success = ctx.isUnauthenticated()
+      }
+      return {
+        success,
+        authenticated: this.isAuthenticated(ctx)
+      }
+    },
+
+    'get session'(ctx) {
+      const authenticated = this.isAuthenticated(ctx)
+      return {
+        authenticated,
+        user: authenticated ? ctx.state.user : null
+      }
+    },
+
+    'get self'(ctx) {
+      return this.isAuthenticated(ctx)
+        ? this.member.get.call(
+            this,
+            this.getContextWithMemberId(ctx, ctx.state.user.$id())
+          )
+        : null
+    }
+  }
+
+  member = {
+    authorize: ['$self']
+  }
+
+  isAuthenticated(ctx) {
+    // Make sure the currently logged in user has the correct model-class:
+    return ctx.isAuthenticated() && ctx.state.user instanceof this.modelClass
+  }
+}

package/src/controllers/index.js

@@ -0,0 +1,5 @@
+export * from './Controller.js'
+export * from './ModelController.js'
+export * from './RelationController.js'
+export * from './AdminController.js'
+export * from './UsersController.js'

package/src/errors/AssetError.js

@@ -0,0 +1,7 @@
+import { ResponseError } from './ResponseError.js'
+
+export class AssetError extends ResponseError {
+  constructor(error) {
+    super(error, { message: 'Asset error', status: 400 })
+  }
+}

package/src/errors/AuthenticationError.js

@@ -0,0 +1,7 @@
+import { ResponseError } from './ResponseError.js'
+
+export class AuthenticationError extends ResponseError {
+  constructor(error) {
+    super(error, { message: 'Authentication error', status: 401 })
+  }
+}

package/src/errors/AuthorizationError.js

@@ -0,0 +1,7 @@
+import { ResponseError } from './ResponseError.js'
+
+export class AuthorizationError extends ResponseError {
+  constructor(error) {
+    super(error, { message: 'Unauthorized Access', status: 401 })
+  }
+}

package/src/errors/ControllerError.js

@@ -0,0 +1,14 @@
+import { isFunction } from '@ditojs/utils'
+import { ResponseError } from './ResponseError.js'
+
+export class ControllerError extends ResponseError {
+  constructor(controller, error) {
+    const { name } = isFunction(controller)
+      ? controller
+      : controller.constructor
+    super(`Controller ${name}: ${error}`, {
+      message: `Controller ${name}: Controller error`,
+      status: 400
+    })
+  }
+}