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

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

@@ -6,7 +6,6 @@
  * Schema, WriteContext
  * } from './lifecycle-types.js' */
 /** @import { StorageRow } from '../lib/storage/storage-types.js' */
-/** @import { DiagnosticWriter, EnhancedDiagnosticLogger } from '../../../lib/logger-types.js' */
 /** @import { RuntimeLogger } from '../../../types/runtime.js' */
 import { initializeResourceVersion } from '../lib/writing/resource-version.js'
 import {
@@ -16,7 +15,6 @@ import {
 } from '../../../lib/rest-api-errors.js'
 import { transformSimplifiedToJsonApi } from '../lib/querying-writing/simplified-helpers.js'
 import { normalizeRelationshipIdentifiers } from '../lib/querying-writing/resource-id-normalization.js'
-import { createEnhancedLogger } from '../../../lib/enhanced-logger.js'
 import { rejectRemovedOptions, resolveFormat, resolveReturning } from '../lib/querying-writing/response-options.js'
 import {
   getRequestContracts,
@@ -27,26 +25,11 @@ import { normalizeRecordAttributes } from '../lib/querying-writing/database-valu
 import { beginWriteTransaction, commitTransaction, getOperationDiagnosticContext, isTransactionOwner, rollbackAfterError, wrapUnexpectedError } from '../../../lib/error-context.js'
 import { filterVisibleIdentifiers } from '../lib/querying/include-query-helpers.js'
 import { findRelationshipDefinition } from '../lib/querying-writing/relationship-contracts.js'
-import { RELATIONSHIP_READ_BATCH_SIZE } from '../lib/querying-writing/knex-constants.js'
 import { getResourceFieldset, parseFieldset } from '../lib/querying-writing/field-utils.js'
 
 // A trusted connector callback, evaluated after normal write validation and authorization.
 export const writePrecondition = Symbol('writePrecondition')
 
-/**
- * Gets an enhanced logger instance with full error details and stack traces
- * @param {RuntimeLogger} log - The base logger instance
- * @param {{ schemaInfo?: LifecycleSchema }} context - Request context carrying compiled field visibility
- * @returns {EnhancedDiagnosticLogger & { error: DiagnosticWriter }} Enhanced logger instance
- */
-export const getEnhancedLogger = (log, context = {}) => {
-  return createEnhancedLogger(log, {
-    logFullErrors: true,
-    includeStack: true,
-    schemaInfo: context.schemaInfo
-  })
-}
-
 /**
  * Resolves write input, response options and the managed transaction.
  * @param {Pick<LifecycleArguments, 'params' | 'vars' | 'scopes' | 'scopeName' | 'api' | 'helpers' | 'runHooks'> & { context: LifecycleContext<Resource | Resource[] | null, unknown> }} options
@@ -107,11 +90,18 @@ export const handleWriteMethodError = async (error, context, method, scopeName,
   await rollbackAfterError(error, context, context.transaction)
   const cleanupErrors = context.cleanupErrors || (context.cleanupErrors = [])
 
+  // The resource, the operation and error codes only: input, error messages and
+  // SQL can carry the values being written (payment state, ciphertext).
+  /** @param {unknown} value */
+  const codeOf = value => {
+    const { code, name } = /** @type {{ code?: unknown, name?: unknown }} */ (Object(value))
+    return typeof code === 'string' || typeof code === 'number' ? code : typeof name === 'string' ? name : null
+  }
   try {
-    await getEnhancedLogger(log, context).logError(`Error in ${method} method`, error, {
+    await log.error(`Error in ${method} method`, {
       ...getOperationDiagnosticContext(context, { phase: 'writeFailure', scopeName, method: context.method ?? method.toLowerCase() }),
-      inputRecord: context.inputRecord,
-      cleanupErrors
+      code: codeOf(error),
+      cleanupErrors: cleanupErrors.map(({ phase, error }) => ({ phase, code: codeOf(error) }))
     })
   } catch (error) {
     cleanupErrors.push({ phase: 'logging', error })
@@ -294,7 +284,11 @@ export const validateResourceAttributesBeforeWrite = async ({
     ...(hasLogicalIdField && resourceId !== undefined ? { id: resourceId } : {})
   }
 
-  // Physical foreign keys may enter storage only through relationship planning.
+  // Physical foreign keys, and the type and id fields behind a polymorphic
+  // belongs-to, may enter storage only through relationship planning.
+  /** @type {Map<string, string>} */
+  const polymorphicFields = new Map(Object.entries(context.schemaInfo.schemaRelationships || {}).flatMap(([name, relationship]) =>
+    relationship.belongsToPolymorphic ? [[relationship.belongsToPolymorphic.typeField, name], [relationship.belongsToPolymorphic.idField, name]] : []))
   /** @type {StorageRow} */
   const attributesForValidation = { ...attributesToValidate }
   const foreignKeyViolations = []
@@ -308,13 +302,14 @@ export const validateResourceAttributesBeforeWrite = async ({
         message: `Field '${field}' is retired and accepts no new values`
       })
     }
-    if (!definition?.belongsTo || !definition.as || Object.hasOwn(belongsToUpdates, field)) continue
+    const relationshipName = definition?.belongsTo && definition.as ? definition.as : polymorphicFields.get(field)
+    if (!relationshipName || Object.hasOwn(belongsToUpdates, field)) continue
     delete attributesForValidation[field]
     if (value === undefined) continue
     foreignKeyViolations.push({
       field: `data.attributes.${field}`,
       rule: 'foreign_key_in_attributes',
-      message: `Foreign key field '${field}' should not be in attributes. Use 'data.relationships.${definition.as}' instead.`
+      message: `Foreign key field '${field}' should not be in attributes. Use 'data.relationships.${relationshipName}' instead.`
     })
   }
   const [firstRetired] = retiredViolations
@@ -420,66 +415,65 @@ export const collectRelationshipTargets = (inputRecord, api, unique) => {
 
 /**
  * Checks that every target is visible to the caller, with one scoped read per
- * related type and batch.
+ * related type, however many targets there are.
  * @param {ResourceContext} context
  * @param {Identifier[]} targets
  * @param {LifecycleHelpers} helpers
  * @param {LifecycleApi} api
  */
 export const validateRelationshipTargets = async (context, targets, helpers, api) => {
-  for (let offset = 0; offset < targets.length; offset += RELATIONSHIP_READ_BATCH_SIZE) {
-    const batch = targets.slice(offset, offset + RELATIONSHIP_READ_BATCH_SIZE)
-    /** @type {Map<string, Identifier[]>} */
-    const byType = new Map()
-    for (const item of batch) {
-      const items = byType.get(item.type)
-      if (items) items.push(item)
-      else byType.set(item.type, [item])
+  /** @type {Map<string, Identifier[]>} */
+  const byType = new Map()
+  for (const item of targets) {
+    const items = byType.get(item.type)
+    if (items) items.push(item)
+    else byType.set(item.type, [item])
+  }
+  const lookups = new Map()
+  for (const [type, items] of byType) {
+    const relatedScope = api.resources[type]
+    if (!relatedScope) throw new Error(`Unknown resource type: ${type}`)
+    const getContext = {
+      ...context,
+      id: undefined,
+      minimalRecord: undefined,
+      schemaInfo: relatedScope.vars.schemaInfo,
+      scopeName: type,
+      queryParams: {},
+      method: 'get',
+      isUpdate: false
     }
-    const lookups = new Map()
-    for (const [type, items] of byType) {
-      const relatedScope = api.resources[type]
-      if (!relatedScope) throw new Error(`Unknown resource type: ${type}`)
-      const getContext = {
-        ...context,
-        id: undefined,
-        minimalRecord: undefined,
-        schemaInfo: relatedScope.vars.schemaInfo,
-        scopeName: type,
-        queryParams: {},
-        method: 'get',
-        isUpdate: false
-      }
-      const lookup = {
-        scopeName: type,
-        context: getContext,
-        /** @param {import('../lib/storage/storage-types.js').QueryFilteringState} filterParams */
-        applyQueryFilters: filterParams => relatedScope.applyQueryFilters({
-          ...filterParams, schemaInfo: getContext.schemaInfo
-        }, getContext),
-        filters: {},
-        queryPurpose: 'relationship-validation'
-      }
-      const records = await helpers.dataGetMinimal({ ...lookup, ids: items.map(item => item.id) })
-      lookups.set(type, { relatedScope, lookup, records: new Map(records.map(record => [String(record.id), record])) })
+    const lookup = {
+      scopeName: type,
+      context: getContext,
+      /** @param {import('../lib/storage/storage-types.js').QueryFilteringState} filterParams */
+      applyQueryFilters: filterParams => relatedScope.applyQueryFilters({
+        ...filterParams, schemaInfo: getContext.schemaInfo
+      }, getContext),
+      filters: {},
+      queryPurpose: 'relationship-validation'
     }
-    for (const item of batch) {
-      const { relatedScope, lookup, records } = lookups.get(item.type)
-      // A database collation can equate IDs with different spellings.
-      const record = records.get(String(item.id)) || await helpers.dataGetMinimal({
-        ...lookup, context: { ...lookup.context, id: item.id }
-      })
-      if (!record) {
-        throw new RestApiResourceError(
-          `Cannot create relationship to non-existent ${item.type} with id ${item.id}`,
-          { subtype: 'not_found', resourceType: item.type, resourceId: item.id }
-        )
-      }
-      await relatedScope.checkPermissions({
-        method: 'get',
-        originalContext: { ...lookup.context, id: item.id, minimalRecord: record }
-      })
+    const records = new Map()
+    for (const record of await helpers.dataGetMinimal({ ...lookup, ids: items.map(item => item.id) })) records.set(String(record.id), record)
+    lookups.set(type, { relatedScope, lookup, records })
+  }
+  // In the order given, so the first missing or forbidden target is the one reported.
+  for (const item of targets) {
+    const { relatedScope, lookup, records } = lookups.get(item.type)
+    // A database collation can equate IDs with different spellings.
+    const record = records.get(String(item.id)) || await helpers.dataGetMinimal({
+      ...lookup, context: { ...lookup.context, id: item.id }
+    })
+    if (!record) {
+      throw new RestApiResourceError(
+        `Cannot create relationship to non-existent ${item.type} with id ${item.id}`,
+        { subtype: 'not_found', resourceType: item.type, resourceId: item.id }
+      )
     }
+    await relatedScope.checkPermissions({
+      method: 'get',
+      originalContext: { ...lookup.context, id: item.id, minimalRecord: record }
+    })
   }
 }
 
@@ -657,15 +651,61 @@ export const filterToOneResponseLinkage = async (context, scopes) => {
       if ((definition?.belongsTo || definition?.belongsToPolymorphic) && relationship.data) linkages.push(relationship)
     }
   }
-  if (linkages.length === 0) return
+  // A target the response already includes is no secret, so it needs no read.
+  const key = (/** @type {Identifier} */ { type, id }) => `${type}:${id}`
+  const included = new Set((document?.included || []).map(key))
+  // The links collected above are to-one links with a target.
+  const unchecked = linkages.filter(relationship => !included.has(key(/** @type {Identifier} */ (relationship.data))))
+  if (unchecked.length === 0) return
   const visible = new Set(await filterVisibleIdentifiers({
-    identifiers: linkages.map(relationship => relationship.data), scopes, knex: context.db, context
+    identifiers: unchecked.map(relationship => relationship.data), scopes, knex: context.db, context
   }))
-  for (const relationship of linkages) {
+  for (const relationship of unchecked) {
     if (!visible.has(relationship.data)) relationship.data = null
   }
 }
 
+/**
+ * A read shows a link whose target its reader cannot see as null (above), so a
+ * reader that writes the record back sends that null for a link it never saw.
+ * The write keeps such a link: a belongs-to that `updates` sets to null, whose
+ * stored target exists but is hidden from the writer, is dropped from
+ * `updates` and from the input, and stays as stored. A link to
+ * a visible target, or to one that no longer exists, is cleared as asked.
+ * @param {{ context: ResourceContext, scopes: Record<string, LifecycleResource>, schemaInfo: any, rows: Array<{ updates: Record<string, unknown>, stored: any, inputRecord?: any }> }} request
+ */
+export const keepHiddenLinks = async ({ context, scopes, schemaInfo, rows }) => {
+  const links = [
+    ...Object.entries(schemaInfo.schemaStructure)
+      .filter(([, field]) => field.belongsTo && field.as)
+      .map(([name, field]) => ({ name: field.as, fields: [name] })),
+    ...Object.entries(schemaInfo.schemaRelationships || {})
+      .filter(([, relationship]) => relationship.belongsToPolymorphic)
+      .map(([name, { belongsToPolymorphic: { typeField, idField } }]) => ({ name, fields: [typeField, idField] }))
+  ]
+  const cleared = []
+  for (const row of rows) {
+    for (const link of links) {
+      const data = row.stored?.relationships?.[link.name]?.data
+      if (data && link.fields.every(field => Object.hasOwn(row.updates, field) && row.updates[field] === null)) cleared.push({ row, link, data })
+    }
+  }
+  if (!cleared.length) return
+  const visible = new Set(await filterVisibleIdentifiers({ identifiers: cleared.map(entry => entry.data), scopes, knex: context.db, context }))
+  const hidden = cleared.filter(entry => !visible.has(entry.data))
+  if (!hidden.length) return
+  const existing = new Set(await filterVisibleIdentifiers({ identifiers: hidden.map(entry => entry.data), scopes, knex: context.db, context, scoped: false }))
+  for (const { row, link, data } of hidden) {
+    if (!existing.has(data)) continue
+    for (const field of link.fields) {
+      delete row.updates[field]
+      // Validation has merged the belongs-to updates into the input attributes.
+      delete row.inputRecord?.data?.attributes?.[field]
+    }
+    delete row.inputRecord?.data?.relationships?.[link.name]
+  }
+}
+
 /** @param {ResourceContext} context @param {Record<string, LifecycleResource>} scopes @param {string[]} [resourceTypes] */
 export const validateRequestedIncludes = (context, scopes, resourceTypes = [context.scopeName]) => {
   const paths = context.queryParams?.include || []

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

@@ -1,17 +1,21 @@
 // Delete many records by id: one scoped read of the ids the caller may delete
-// per chunk, then one DELETE per chunk and the pivot rows of the deleted records.
+// per chunk (or, with missing: 'skip', the scope inside the DELETE), then one
+// DELETE per chunk and the pivot rows of the deleted records. deleteWhere
+// deletes the rows its selection finds and answers with those it deleted.
 import { beginWriteTransaction } from '../../../lib/error-context.js'
-import { RestApiValidationError } from '../../../lib/rest-api-errors.js'
-import { rejectRemovedOptions, resolveFormat, resolveReturning } from '../lib/querying-writing/response-options.js'
+import { RestApiRecordsNotFoundError, RestApiValidationError } from '../../../lib/rest-api-errors.js'
+import { rejectRemovedOptions, resolveFormat } from '../lib/querying-writing/response-options.js'
 import { requireExistingResourceId } from '../lib/querying-writing/resource-id-normalization.js'
-import { chunk } from '../lib/storage/many-row-data-helpers.js'
+import { chunk, databaseFamily } from '../lib/storage/many-row-data-helpers.js'
 import { commitOwnedTransaction, handleWriteMethodError } from './common.js'
 import {
   keepVisible,
   refuseDuplicateIds,
   refuseUnsupportedResource,
   rejectBulkOptions,
+  requireWhereScope,
   resolveChunkSize,
+  resolveManyRowReturning,
   resolveMissing,
   unsupported,
   validateFilters
@@ -26,46 +30,67 @@ function setup ({ params, context, scopes, scopeName }, method) {
   context.schemaInfo = scopes[scopeName].vars.schemaInfo
   // Deletes return no records; a format is still checked like a single delete's.
   if (params.format !== undefined) resolveFormat(params.format)
-  context.returning = resolveReturning(params.returning, 'none')
-  if (context.returning === 'full') {
-    throw new RestApiValidationError("A delete returns 'none' or 'minimal'", { fields: ['returning'] })
-  }
+  context.returning = resolveManyRowReturning(params.returning, { deletes: true })
   context.params = params
 }
 
-async function runDeleteMany (args, { operation, ids, started = false }) {
-  const { params, context, helpers, scope, runHooks, perRecordHooks, scopeName, api } = args
+/**
+ * @param {any} args
+ * @param {{ operation: string, ids: unknown[], started?: boolean, selection?: { filters?: Record<string, unknown> } }} batch
+ */
+async function runDeleteMany (args, { operation, ids, started = false, selection }) {
+  const { params, context, helpers, scope, runHooks, hasHooks, perRecordHooks, scopeName, api } = args
   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: context.schemaInfo, operation, kind: 'delete', storageHelper: 'dataDeleteByIds' })
   refuseDuplicateIds(ids, storageAdapter, 'ids')
 
   if (!started) await beginWriteTransaction(context, params.transaction, helpers.newTransaction, runHooks)
   context.db = context.transaction
 
-  const visible = new Map()
-  for (const part of chunk(ids, 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: ids, visible, missing, scopeName, storageAdapter })
-  // bulkIndex is the id's position in the request.
-  const positions = new Map(ids.map((id, index) => [String(storageAdapter.translateFilterValue('id', id)), index]))
-  for (const id of kept) {
-    const key = String(storageAdapter.translateFilterValue('id', id))
-    const minimalRecord = visible.get(key)
-    const bulkIndex = positions.get(key)
-    await scope.checkPermissions({ method: 'delete', originalContext: { ...context, method: 'delete', id, minimalRecord, originalMinimalRecord: minimalRecord, bulkIndex } })
+  // With missing: 'skip' and no hook that needs the rows first, the DELETE
+  // decides which rows the caller may delete, carrying the scope (see patchMany,
+  // also for MySQL and selections).
+  const readFirst = !(missing === 'skip' && !hasHooks('checkPermissions') && !hasHooks('beforeDataCallDeleteMany') &&
+    (selection || databaseFamily(context.db) !== 'mysql'))
+  const scoped = Boolean(selection) || !readFirst
+  let kept = ids
+  if (readFirst) {
+    const visible = new Map()
+    for (const part of chunk(ids, 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)
+    }
+    kept = keepVisible({ requested: ids, visible, missing, scopeName, storageAdapter })
+    // bulkIndex is the id's position in the request.
+    const positions = new Map(ids.map((id, index) => [String(storageAdapter.translateFilterValue('id', id)), index]))
+    for (const id of kept) {
+      const key = String(storageAdapter.translateFilterValue('id', id))
+      const minimalRecord = visible.get(key)
+      const bulkIndex = positions.get(key)
+      await scope.checkPermissions({ method: 'delete', originalContext: { ...context, method: 'delete', id, minimalRecord, originalMinimalRecord: minimalRecord, bulkIndex } })
+    }
   }
 
   context.ids = kept.map(String)
   await runHooks('beforeDataCallDeleteMany')
-  if (kept.length) await helpers.dataDeleteByIds({ scopeName, context, ids: kept, chunkSize })
+  const deleted = new Set((kept.length
+    ? await helpers.dataDeleteByIds({ scopeName, context, runHooks, ids: kept, chunkSize, scoped, filters: selection?.filters })
+    : []).map(String))
+  // A row that left the caller's scope after the visibility read is not deleted.
+  if (deleted.size < kept.length && missing === 'throw') throw new RestApiRecordsNotFoundError({ resourceType: scopeName, missing: kept.length - deleted.size })
+  context.ids = kept.map(id => String(storageAdapter.translateFilterValue('id', id))).filter(id => deleted.has(id))
   await runHooks('afterDataCallDeleteMany')
 
   await commitOwnedTransaction(context)
-  return context.returning === 'none' ? undefined : { data: context.ids.map(id => ({ type: scopeName, id })) }
+  return deleteResponse(context, scopeName, context.ids)
+}
+
+/** @param {any} context @param {string} scopeName @param {string[]} ids */
+function deleteResponse (context, scopeName, ids) {
+  if (context.returning === 'count') return { meta: { count: ids.length } }
+  return context.returning === 'none' ? undefined : { data: ids.map(id => ({ type: scopeName, id })) }
 }
 
 /** @param {any} args */
@@ -92,14 +117,15 @@ export async function deleteWhereMethod (args) {
       throw unsupported(scopeName, 'deleteWhere', '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: 'deleteWhere' })
     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 deleteResponse(context, scopeName, [])
     }
-    return await runDeleteMany(args, { operation: 'deleteWhere', ids, started: true })
+    return await runDeleteMany(args, { operation: 'deleteWhere', ids, started: true, selection: { filters } })
   } catch (error) {
     await handleWriteMethodError(error, context, 'DELETE_WHERE', scopeName, log)
   }

package/plugins/core/rest-api-plugin-methods/delete-relationship.js

@@ -22,6 +22,27 @@ import { updateReverseRelationship } from '../lib/writing/reverse-relationship-m
 import { invalidateRemovedPivotVersions } from '../lib/writing/many-to-many-manipulations.js'
 import { getStorageColumn } from '../lib/storage/storage-mapping.js'
 import { RELATIONSHIP_WRITE_BATCH_SIZE } from '../lib/querying-writing/knex-constants.js'
+import { filterVisibleIdentifiers } from '../lib/querying/include-query-helpers.js'
+import { isSystemContext } from '../../../lib/system-context.js'
+
+/**
+ * The identifiers a many-to-many removal may unlink. Targets that ownership
+ * filters or a row policy scope are read for visibility (one read per type and
+ * 1,000 ids), and links to targets the caller cannot see stay, as links to
+ * missing ones always did. Other targets, and every target in a system context,
+ * cost no read. (Reverse hasMany removals check each child's visibility themselves.)
+ * @param {WriteRelationshipContext} context
+ * @param {Identifier[]} identifiers
+ * @param {any} api
+ */
+async function removableTargets (context, identifiers, api) {
+  if (isSystemContext(context)) return identifiers
+  const scoped = (/** @type {Identifier} */ { type }) => Boolean(api.resources[type]?.vars?.schemaInfo?.ownershipFields?.length || api.resources[type]?.vars?.rowPolicy)
+  const checked = identifiers.filter(scoped)
+  if (!checked.length) return identifiers
+  const visible = new Set(await filterVisibleIdentifiers({ identifiers: checked, scopes: api.resources, knex: context.db, context }))
+  return identifiers.filter(identifier => !scoped(identifier) || visible.has(identifier))
+}
 
 /**
  * Remove the identifiers in params.relationshipData from a to-many relationship.
@@ -98,6 +119,7 @@ export default async function deleteRelationshipMethod ({ params, context: calle
 
     // Remove relationships
     if (relDef?.through) {
+      params.relationshipData = await removableTargets(context, params.relationshipData, api)
       if (api.anyapi?.links?.removeMany) {
         await api.anyapi.links.removeMany({
           context,

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,14 @@ 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.
+ * 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.
  * @param {{ api: any, scopeName: string, context: any, ids: unknown[], returning: string, format: string, queryParams?: any }} request
  */
 export async function manyRowResponse ({ api, scopeName, context, ids, returning, format, queryParams = {} }) {
   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()