json-rest-api 3.0.0-rc.0 → 3.0.1

package/plugins/core/rest-api-plugin-methods/get.js

@@ -78,52 +78,58 @@ export default async function getMethod ({
 
   const identityContext = /** @type {IdentityContext} */ (context)
 
-  // Fetch minimal record for authorization checks
-  const minimalRecord = await helpers.dataGetMinimal({
-    scopeName,
-    context: identityContext,
-    runHooks
+  const notFound = () => new RestApiResourceError('Resource not found', {
+    subtype: 'not_found',
+    resourceType: scopeName,
+    resourceId: context.id
   })
 
-  if (!minimalRecord) {
-    throw new RestApiResourceError(
-      'Resource not found',
-      {
-        subtype: 'not_found',
-        resourceType: scopeName,
-        resourceId: context.id
-      }
-    )
+  // The minimal record serves the permission checks and the hooks before the
+  // data call. A resource without them reads once: the scoped full read also
+  // answers whether the row exists. Any permission hook keeps both reads.
+  const readOnce = ['checkPermissions', 'checkDataPermissions', 'checkDataPermissionsGet', 'beforeData', 'beforeDataGet'].some(event => hasHooks(event))
+    ? undefined
+    : helpers.dataGetScoped
+
+  if (readOnce) {
+    try {
+      await validateRequestedFieldsets(context, scopes)
+      validateRequestedIncludes(context, scopes)
+    } catch (error) {
+      // A missing row answers 404 before a bad fieldset, as with two reads.
+      if (!(await helpers.dataGetMinimal({ scopeName, context: identityContext, runHooks }))) throw notFound()
+      throw error
+    }
+    context.record = await readOnce({ scopeName, context: identityContext, runHooks })
+  } else {
+    // Fetch minimal record for authorization checks
+    const minimalRecord = await helpers.dataGetMinimal({
+      scopeName,
+      context: identityContext,
+      runHooks
+    })
+    if (!minimalRecord) throw notFound()
+
+    context.minimalRecord = minimalRecord
+
+    await scope.checkPermissions({
+      method: 'get',
+      originalContext: context,
+    })
+
+    await validateRequestedFieldsets(context, scopes)
+    validateRequestedIncludes(context, scopes)
+    await runHooks('beforeData')
+    await runHooks('beforeDataGet')
+
+    context.record = await helpers.dataGet({
+      scopeName,
+      context: identityContext,
+      runHooks
+    })
   }
 
-  context.minimalRecord = minimalRecord
-
-  await scope.checkPermissions({
-    method: 'get',
-    originalContext: context,
-  })
-
-  await validateRequestedFieldsets(context, scopes)
-  validateRequestedIncludes(context, scopes)
-  await runHooks('beforeData')
-  await runHooks('beforeDataGet')
-
-  context.record = await helpers.dataGet({
-    scopeName,
-    context: identityContext,
-    runHooks
-  })
-
-  if (!context.record || !context.record.data) {
-    throw new RestApiResourceError(
-      'Resource not found',
-      {
-        subtype: 'not_found',
-        resourceType: scopeName,
-        resourceId: context.id
-      }
-    )
-  }
+  if (!context.record || !context.record.data) throw notFound()
 
   context.record = normalizeRecordAttributes(context.record, scopes)
 

package/plugins/core/rest-api-plugin-methods/many-row-common.js

@@ -70,8 +70,13 @@ export function refuseUnsupportedResource ({ api, helpers, perRecordHooks, scope
   }
   const hooks = perRecordHooks(PER_RECORD_EVENTS[kind])
   if (hooks.length) {
-    const names = hooks.map(hook => `${hook.event}:${hook.name}`).join(', ')
-    throw unsupported(scopeName, operation, `per-record hooks without a batch form run for it (${names}); register them with { batch: true } and a batch hook`)
+    // The hook names stay in the error details, which HTTP responses leave out.
+    throw new RestApiBulkWriteUnsupportedError({
+      resourceType: scopeName,
+      operation,
+      reason: 'per-record hooks without a batch form run for it; register them with { batch: true } and a batch hook',
+      hooks: hooks.map(hook => `${hook.event}:${hook.name}`)
+    })
   }
 }
 
@@ -84,6 +89,20 @@ export function resolveChunkSize (value) {
   return /** @type {number} */ (value)
 }
 
+/**
+ * What a many-row write returns: nothing (the default), identifiers, the
+ * records (not for deletes) or `{ meta: { count } }`, the number of rows it
+ * wrote.
+ * @param {unknown} value
+ * @param {{ deletes?: boolean }} [options]
+ * @returns {'none' | 'minimal' | 'full' | 'count'}
+ */
+export function resolveManyRowReturning (value, { deletes = false } = {}) {
+  const returning = value === undefined ? 'none' : value
+  if (returning === 'none' || returning === 'minimal' || returning === 'count' || (returning === 'full' && !deletes)) return returning
+  throw new RestApiValidationError(deletes ? "A delete returns 'none', 'minimal' or 'count'" : "returning must be 'none', 'minimal', 'full' or 'count'", { fields: ['returning'] })
+}
+
 /** @param {unknown} value */
 export function resolveMissing (value) {
   if (value === undefined) return 'throw'
@@ -129,7 +148,13 @@ export function toDocument ({ record, inputKey, scopeName, schemaInfo, allowRaw
   let attributes = inputKey === 'data' ? record : record.attributes
   if (attributes && typeof attributes === 'object') {
     for (const [field, value] of Object.entries(attributes)) {
-      if (!isRawValue(value)) continue
+      if (!isRawValue(value)) {
+        // Knex would run any object carrying the flag as SQL; JSON input can carry the flag.
+        if (value && typeof value === 'object' && Object.hasOwn(value, 'isRawInstance')) {
+          throw new RestApiValidationError(`Field '${field}' holds an object that is not a Knex raw value`, { fields: [field] })
+        }
+        continue
+      }
       if (!allowRaw) throw new RestApiValidationError(`Field '${field}' cannot take a raw SQL value here`, { fields: [field] })
       raw[field] = value
     }
@@ -191,6 +216,22 @@ export function requireLockTransaction ({ transaction, scopeName, operation }) {
   }
 }
 
+/**
+ * patchWhere and deleteWhere need filters, or `all: true` to act on every row
+ * the caller can see (in a system context, the whole table).
+ * @param {{ filters: Record<string, unknown> | undefined, all: unknown, missing?: unknown, operation: string }} request
+ */
+export function requireWhereScope ({ filters, all, missing, operation }) {
+  // A selection writes the rows it finds and answers with those; no row is missing.
+  if (missing !== undefined) throw new RestApiValidationError(`${operation} writes the rows its selection finds; missing applies to lists of ids`, { fields: ['missing'] })
+  if (all !== undefined && all !== true) throw new RestApiValidationError('all must be true when given', { fields: ['all'] })
+  const filtered = Boolean(filters && Object.keys(filters).length)
+  if (all && filtered) throw new RestApiValidationError(`${operation} takes filters or all: true, not both`, { fields: ['all'] })
+  if (!all && !filtered) {
+    throw new RestApiValidationError(`${operation} needs filters, or all: true to act on every row the caller can see`, { fields: ['filters'] })
+  }
+}
+
 /**
  * Validates filters as `query` would, so many-row operations accept the same
  * search fields and values.
@@ -202,13 +243,15 @@ export function validateFilters ({ filters, scopeName, schemaInfo, vars }) {
 }
 
 /**
- * The response of a many-row write: identifiers, full records read through
- * `query` in the write's transaction, or nothing.
- * @param {{ api: any, scopeName: string, context: any, ids: unknown[], returning: string, format: string, queryParams?: any }} request
+ * The response of a many-row write: the count of written rows, identifiers,
+ * full records read through `query` in the write's transaction, or nothing.
+ * `locked`: the transaction holds row locks on the ids, so they are read as locked.
+ * @param {{ api: any, scopeName: string, context: any, ids: unknown[], returning: string, format: string, queryParams?: any, locked?: boolean }} request
  */
-export async function manyRowResponse ({ api, scopeName, context, ids, returning, format, queryParams = {} }) {
+export async function manyRowResponse ({ api, scopeName, context, ids, returning, format, queryParams = {}, locked = false }) {
   if (returning === 'none') return undefined
   const present = ids.filter(id => id !== undefined && id !== null).map(String)
+  if (returning === 'count') return { meta: { count: present.length } }
   if (returning === 'minimal') return { data: present.map(id => ({ type: scopeName, id })) }
 
   const byId = new Map()
@@ -221,7 +264,7 @@ export async function manyRowResponse ({ api, scopeName, context, ids, returning
       transaction: context.transaction,
       pageSizeLimit: part.length,
       queryParams: { fields: queryParams.fields, include: queryParams.include, sort: ['id'], page: { size: part.length } },
-      [queryConstraint]: { scopeName, idsQuery: part }
+      [queryConstraint]: { scopeName, idsQuery: part, locked }
     }, { ...context, method: undefined, knexQuery: undefined })
     for (const record of page.data) byId.set(String(record.id), record)
     for (const resource of page.included || []) included.set(`${resource.type}:${resource.id}`, resource)

package/plugins/core/rest-api-plugin-methods/patch-many.js

@@ -2,17 +2,18 @@
 // ids the caller may change (one scoped read per chunk), then run one UPDATE per
 // chunk with CASE expressions. patchWhereIds and patchWhere reuse the same path.
 import { lockRelationshipTargets, processRelationships } from '../lib/writing/relationship-processor.js'
-import { rejectRemovedOptions, resolveFormat, resolveReturning } from '../lib/querying-writing/response-options.js'
+import { rejectRemovedOptions, resolveFormat } from '../lib/querying-writing/response-options.js'
 import { requireExistingResourceId } from '../lib/querying-writing/resource-id-normalization.js'
 import { validateUpdateRequest } from '../lib/querying-writing/request-contracts.js'
 import { beginWriteTransaction } from '../../../lib/error-context.js'
-import { RestApiValidationError } from '../../../lib/rest-api-errors.js'
-import { chunk } from '../lib/storage/many-row-data-helpers.js'
+import { RestApiRecordsNotFoundError, RestApiValidationError } from '../../../lib/rest-api-errors.js'
+import { chunk, databaseFamily } from '../lib/storage/many-row-data-helpers.js'
 import {
   applyFieldSetters,
   collectRelationshipTargets,
   commitOwnedTransaction,
   handleWriteMethodError,
+  keepHiddenLinks,
   validateRelationshipTargets,
   validateResourceAttributesBeforeWrite
 } from './common.js'
@@ -24,7 +25,9 @@ import {
   refuseDuplicateIds,
   refuseUnsupportedResource,
   rejectBulkOptions,
+  requireWhereScope,
   resolveChunkSize,
+  resolveManyRowReturning,
   resolveMissing,
   selectManyInput,
   toDocument,
@@ -50,12 +53,16 @@ function protectedFields (schemaInfo) {
   return { fields, relationships }
 }
 
-function refuseProtectedInput ({ document, raw, schemaInfo, index }) {
-  const { fields, relationships } = protectedFields(schemaInfo)
-  const attributes = document.data.attributes || {}
-  for (const field of [...Object.keys(attributes), ...Object.keys(raw)]) {
+function refuseProtectedFields (names, schemaInfo, index) {
+  const { fields } = protectedFields(schemaInfo)
+  for (const field of names) {
     if (fields.has(field)) throw atIndex(invalid(`data.attributes.${field}`, `'${field}' cannot be changed by a many-row patch`), index)
   }
+}
+
+function refuseProtectedInput ({ document, raw, schemaInfo, index }) {
+  const { relationships } = protectedFields(schemaInfo)
+  refuseProtectedFields([...Object.keys(document.data.attributes || {}), ...Object.keys(raw)], schemaInfo, index)
   for (const name of Object.keys(document.data.relationships || {})) {
     if (relationships.has(name)) throw atIndex(invalid(`data.relationships.${name}`, `'${name}' sets ownership and cannot be changed by a many-row patch`), index)
   }
@@ -83,16 +90,18 @@ function resolveOnlyIf (onlyIf, { schemaInfo, storageAdapter }) {
 }
 
 /**
- * The shared path: `entries` are { id, document, raw } in input order.
+ * The shared path: `entries` are { id, document, raw } in input order. A
+ * `selection` (patchWhere) gives the filters that found the ids: its rows are
+ * never missing, and the write answers with the rows it changed.
  * @param {any} args
- * @param {{ operation: string, entries: Array<{ id: unknown, document: any, raw: Record<string, unknown> }>, started?: boolean }} batch
+ * @param {{ operation: string, entries: Array<{ id: unknown, document: any, raw: Record<string, unknown> }>, started?: boolean, selection?: { filters?: Record<string, unknown> } }} batch
  */
-async function runPatchMany (args, { operation, entries, started = false }) {
-  const { params, context, vars, helpers, scope, runHooks, perRecordHooks, scopeOptions, scopeName, api } = args
+async function runPatchMany (args, { operation, entries, started = false, selection }) {
+  const { params, context, vars, helpers, scope, runHooks, hasHooks, perRecordHooks, scopeOptions, scopeName, api } = args
   const schemaInfo = context.schemaInfo
   const storageAdapter = helpers.getStorageAdapter(scopeName)
   const chunkSize = resolveChunkSize(params.chunkSize)
-  const missing = resolveMissing(params.missing)
+  const missing = selection ? 'skip' : resolveMissing(params.missing)
   refuseUnsupportedResource({ api, helpers, perRecordHooks, scopeName, schemaInfo, operation, kind: 'patch', storageHelper: 'dataUpdateByIds' })
   const onlyIf = resolveOnlyIf(params.onlyIf, { schemaInfo, storageAdapter })
   entries.forEach((entry, index) => refuseProtectedInput({ ...entry, schemaInfo, index }))
@@ -100,18 +109,21 @@ async function runPatchMany (args, { operation, entries, started = false }) {
   if (!started) await beginWriteTransaction(context, params.transaction, helpers.newTransaction, runHooks)
   context.db = context.transaction
   context.inputRecords = entries.map(entry => entry.document)
+  // Fields set by raw SQL values, which plugins that refuse fields check too.
+  context.rawFields = [...new Set(entries.flatMap(entry => Object.keys(entry.raw)))]
   await runHooks('beforeProcessingPatchMany')
 
   const targets = new Map()
   const rows = entries.map((entry, index) => {
     const rowContext = { ...context, method: 'patch', inputRecord: entry.document, originalInputAttributes: undefined, bulkIndex: index }
-    // A row of raw values alone still carries an (empty) attributes object.
-    if (Object.keys(entry.raw).length) entry.document.data.attributes ||= {}
+    // A row of raw values alone, or one that only advances a lock version,
+    // still carries an (empty) attributes object.
+    if (Object.keys(entry.raw).length || schemaInfo.lockVersionField) entry.document.data.attributes ||= {}
     try {
       validateUpdateRequest({ method: 'patch', params: {}, context: rowContext, vars, scopeOptions, scopeName })
     } catch (error) { throw atIndex(error, index) }
     collectRelationshipTargets(rowContext.inputRecord, api, targets)
-    return { rowContext, raw: entry.raw, index }
+    return { rowContext, raw: entry.raw, index, clearsLink: false }
   })
   refuseDuplicateIds(rows.map(row => row.rowContext.id), storageAdapter)
   await validateRelationshipTargets(context, [...targets.values()], helpers, api)
@@ -126,26 +138,52 @@ async function runPatchMany (args, { operation, entries, started = false }) {
       }
       await validateResourceAttributesBeforeWrite({ context: rowContext, schema: schemaInfo.schemaInstance, belongsToUpdates, runHooks: noHooks, isPartialValidation: true })
       rowContext.inputRecord.data.attributes = { ...rowContext.inputRecord.data.attributes, ...belongsToUpdates }
-      if (!Object.keys(rowContext.inputRecord.data.attributes).length && !Object.keys(row.raw).length) {
+      row.clearsLink = Object.values(belongsToUpdates).includes(null)
+      // A polymorphic relationship writes its own type and id columns, which may be ownership fields.
+      refuseProtectedFields(Object.keys(rowContext.inputRecord.data.attributes), schemaInfo, index)
+      // A row with no fields still advances a lock version.
+      if (!Object.keys(rowContext.inputRecord.data.attributes).length && !Object.keys(row.raw).length && !schemaInfo.lockVersionField) {
         throw invalid('data', 'A patch row must change at least one field')
       }
       parents.push(...belongsToTargets)
     } catch (error) { throw atIndex(error, index) }
   }
 
-  // Which of the requested rows the caller may change: one scoped read per chunk.
-  const visible = new Map()
-  for (const part of chunk(rows.map(row => row.rowContext.id), VISIBLE_READ_CHUNK)) {
-    const records = await helpers.dataGetMinimal({ scopeName, context, runHooks, ids: part, filters: {}, queryPurpose: 'bulk-write' })
-    for (const record of records) visible.set(String(storageAdapter.translateFilterValue('id', record.id)), record)
-  }
-  const kept = keepVisible({ requested: rows.map(row => row.rowContext.id), visible, missing, scopeName, storageAdapter })
-  const keptRows = rows.filter(row => kept.includes(row.rowContext.id))
-  for (const { rowContext, index } of keptRows) {
-    rowContext.minimalRecord = visible.get(String(storageAdapter.translateFilterValue('id', rowContext.id)))
-    try {
-      await scope.checkPermissions({ method: 'patch', originalContext: rowContext })
-    } catch (error) { throw atIndex(error, index) }
+  // Which of the requested rows the caller may change. With missing: 'skip' and
+  // no hook that needs the rows first, the UPDATE decides it, carrying the
+  // scope, and its changed rows answer. Otherwise one scoped read per chunk
+  // gives each row's minimal record to the permission check. On MySQL a
+  // locking read locks every listed row before it checks the scope, so ids
+  // from the caller always get that read first; a selection's ids come from
+  // its own scoped read. A selection's UPDATE carries the scope and its filters
+  // either way, so it changes only rows that still match.
+  // A row that clears a link reads first too, to keep a link to a hidden target.
+  const readFirst = rows.some(row => row.clearsLink) || !(missing === 'skip' && !hasHooks('checkPermissions') && !hasHooks('beforeDataCallPatchMany') &&
+    (selection || databaseFamily(context.db) !== 'mysql'))
+  const scoped = Boolean(selection) || !readFirst
+  let keptRows = rows
+  if (readFirst) {
+    const visible = new Map()
+    for (const part of chunk(rows.map(row => row.rowContext.id), VISIBLE_READ_CHUNK)) {
+      const records = await helpers.dataGetMinimal({ scopeName, context, runHooks, ids: part, filters: {}, queryPurpose: 'bulk-write' })
+      for (const record of records) visible.set(String(storageAdapter.translateFilterValue('id', record.id)), record)
+    }
+    const kept = keepVisible({ requested: rows.map(row => row.rowContext.id), visible, missing, scopeName, storageAdapter })
+    keptRows = rows.filter(row => kept.includes(row.rowContext.id))
+    for (const { rowContext } of keptRows) {
+      rowContext.minimalRecord = visible.get(String(storageAdapter.translateFilterValue('id', rowContext.id)))
+    }
+    await keepHiddenLinks({
+      context,
+      scopes: api.resources,
+      schemaInfo,
+      rows: keptRows.filter(row => row.clearsLink).map(({ rowContext }) => ({ updates: rowContext.inputRecord.data.attributes, stored: rowContext.minimalRecord, inputRecord: rowContext.inputRecord }))
+    })
+    for (const { rowContext, index } of keptRows) {
+      try {
+        await scope.checkPermissions({ method: 'patch', originalContext: rowContext })
+      } catch (error) { throw atIndex(error, index) }
+    }
   }
 
   context.ids = keptRows.map(row => String(row.rowContext.id))
@@ -164,8 +202,16 @@ async function runPatchMany (args, { operation, entries, started = false }) {
     updates.push({ id: rowContext.id, row })
   }
 
-  const changed = updates.length ? await helpers.dataUpdateByIds({ scopeName, context, updates, onlyIf, chunkSize }) : []
-  context.ids = changed.map(String)
+  const changed = new Set((updates.length
+    ? await helpers.dataUpdateByIds({ scopeName, context, runHooks, updates, onlyIf, chunkSize, scoped, filters: selection?.filters })
+    : []).map(String))
+  // A row that left the caller's scope after the visibility read is not written.
+  const unchanged = updates.length - changed.size
+  if (unchanged && !onlyIf && missing === 'throw') throw new RestApiRecordsNotFoundError({ resourceType: scopeName, missing: unchanged })
+  // After-hooks see the changed rows' ids and inputs, paired by position.
+  const written = keptRows.filter(row => changed.has(String(storageAdapter.translateFilterValue('id', row.rowContext.id))))
+  context.ids = written.map(row => String(storageAdapter.translateFilterValue('id', row.rowContext.id)))
+  context.inputRecords = written.map(row => row.rowContext.inputRecord)
   await runHooks('afterDataCallPatchMany')
 
   const response = await manyRowResponse({
@@ -183,7 +229,7 @@ function setupManyWrite ({ params, context, vars, scopes, scopeName }, method) {
   context.schemaInfo = scopes[scopeName].vars.schemaInfo
   context.format = resolveFormat(params.format, vars.format)
   context.simplified = context.format === 'plain'
-  context.returning = resolveReturning(params.returning, 'none')
+  context.returning = resolveManyRowReturning(params.returning)
   context.params = params
 }
 
@@ -269,16 +315,17 @@ export async function patchWhereMethod (args) {
       throw unsupported(scopeName, 'patchWhere', 'its storage plugin has no many-row support (AnyAPI storage takes single writes)')
     }
     const filters = validateFilters({ filters: params.filters, scopeName, schemaInfo: context.schemaInfo, vars })
+    requireWhereScope({ filters, all: params.all, missing: params.missing, operation: 'patchWhere' })
     // The visible ids are read in the write's transaction, so open it first.
     await beginWriteTransaction(context, params.transaction, helpers.newTransaction, args.runHooks)
     context.db = context.transaction
     const ids = await visibleIdsByFilters(args, filters)
     if (!ids.length) {
       await commitOwnedTransaction(context)
-      return context.returning === 'none' ? undefined : { data: [] }
+      return context.returning === 'count' ? { meta: { count: 0 } } : context.returning === 'none' ? undefined : { data: [] }
     }
     return await runPatchMany(args, {
-      operation: 'patchWhere', entries: entriesFor(ids, shared, { scopeName, schemaInfo: context.schemaInfo }), started: true
+      operation: 'patchWhere', entries: entriesFor(ids, shared, { scopeName, schemaInfo: context.schemaInfo }), started: true, selection: { filters }
     })
   } catch (error) {
     await handleWriteMethodError(error, context, 'PATCH_WHERE', scopeName, log)

package/plugins/core/rest-api-plugin-methods/patch.js

@@ -18,7 +18,8 @@ import {
   validatePivotResource,
   handleRecordReturnAfterWrite,
   handleWriteMethodError,
-  commitOwnedTransaction
+  commitOwnedTransaction,
+  keepHiddenLinks
 } from './common.js'
 
 /**
@@ -90,6 +91,7 @@ export default async function patchMethod ({
     }
 
     context.minimalRecord = minimalRecord
+    await keepHiddenLinks({ context, scopes, schemaInfo: context.schemaInfo, rows: [{ updates: belongsToUpdates, stored: minimalRecord, inputRecord: context.inputRecord }] })
 
     await scope.checkPermissions({
       method: 'patch',