json-rest-api 3.0.0 → 3.0.1

package/docs/GUIDE/27-many-row-writes.md

@@ -322,7 +322,13 @@ number of statements per chunk. The records it updates go through a patch's
 checks as well as a create's: `checkPermissions` runs with `method: 'patch'`
 and the matched record as `minimalRecord`, the resource is refused if a
 per-record patch hook without `{ batch: true }` runs for it, and a key that
-matches a record the caller cannot see fails the batch as `forbidden`.
+matches a record the caller cannot see fails the batch as `forbidden`. The
+caller's scope is checked on the records as locked: on MySQL and MariaDB, whose
+plain reads keep a REPEATABLE READ transaction's first snapshot, that check is
+a locking read too, so a matching record another transaction committed after
+this one's first read is merged into, not taken for a hidden one. The records a
+merge returns with `returning: 'full'` are read the same way, so such a record
+is returned even when the merge leaves it unchanged.
 
 With `returning: 'count'` an upsert counts the rows it inserted, and with
 `merge` the records it updated as well.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "json-rest-api",
-  "version": "3.0.0",
+  "version": "3.0.1",
   "main": "index.js",
   "types": "index.d.ts",
   "type": "module",

package/plugins/core/lib/storage/ordinary-data-helpers.js

@@ -8,7 +8,7 @@ import { buildJsonApiResponse } from '../querying/knex-json-api-transformers-que
 import { toJsonApiRecordWithBelongsTo } from '../querying-writing/knex-json-api-transformers.js'
 import { processIncludes } from '../querying/knex-process-includes.js'
 import { loadRelationshipIdentifiers } from '../querying/relationship-identifiers.js'
-import { applyQueryConstraint } from '../querying/query-constraint.js'
+import { applyQueryConstraint, queryConstraint } from '../querying/query-constraint.js'
 import { deleteFoundRow, foundRow, lockFoundRow, updateFoundRow } from './single-row-writes.js'
 import { runAggregateQuery } from '../querying/aggregate-query.js'
 import { RestApiResourceError } from '../../../../lib/rest-api-errors.js'
@@ -21,6 +21,7 @@ import { unwrapQueryBuilderState, withQueryFilteringContext } from '../querying/
 import { serializeJsonApiQuery } from '../querying-writing/connectors-query-parser.js'
 import { applyDatabaseReadOptions, databaseIdentityExpression } from '../querying-writing/database-value-normalizers.js'
 import { whereInIdentifiers } from '../querying/identifier-query.js'
+import { databaseFamily } from './many-row-data-helpers.js'
 
 /**
  * Every update advances the resource's lock version by one, whatever the input says.
@@ -280,7 +281,8 @@ export function createOrdinaryDataHelpers ({ api, scopes, knex, log, getScopeSto
     runHooks,
     applyQueryFilters,
     filters = context.queryParams?.filters,
-    queryPurpose = 'single'
+    queryPurpose = 'single',
+    locked = false
   }) {
     const storageAdapter = getScopeStorageAdapter(scopeName)
     context.storageAdapter = storageAdapter
@@ -332,6 +334,19 @@ export function createOrdinaryDataHelpers ({ api, scopes, knex, log, getScopeSto
       const column = storageAdapter.translateColumn(field)
       return [field === 'id' ? 'id' : column, databaseIdentityExpression(db, `${tableName}.${column}`)]
     }))
+    if (ids !== undefined && locked && databaseFamily(db) === 'mysql') {
+      // InnoDB answers a plain read from the transaction's snapshot and a
+      // locking read from the latest rows. Rows this transaction has locked
+      // are read with a locking read in the scope's own query block, row
+      // policy included, so a row another transaction committed after the
+      // snapshot is seen as it was locked. (PostgreSQL's plain and locking
+      // reads see the same rows; SQLite has one writer.)
+      /** @type {StorageRow[]} */
+      const rows = await applyDatabaseReadOptions(query.clearSelect().select(`${tableName}.*`, identities).forShare())
+      // A policy join can repeat a row.
+      const records = [...new Map(rows.map(row => [String(row.id), row])).values()]
+      return records.map(record => toJsonApiRecordWithBelongsTo(scope, record, scopeName))
+    }
     if (ids !== undefined) {
       // Filtering owns predicates; the id list owns its identity projection.
       query.clearSelect().distinct(`${tableName}.${idProperty}`)
@@ -425,6 +440,9 @@ export function createOrdinaryDataHelpers ({ api, scopes, knex, log, getScopeSto
     })
     const { pageSize } = paginationInfo
 
+    // Rows this transaction has locked, read as its locking reads see them (see dataGetMinimal).
+    const constraint = context[queryConstraint]
+    if (constraint?.scopeName === scopeName && constraint.locked && databaseFamily(db) === 'mysql') query.forShare()
     /** @type {StorageRow[]} */
     const records = await applyDatabaseReadOptions(query)
 

package/plugins/core/lib/storage/storage-types.d.ts

@@ -13,6 +13,8 @@ export interface MandatoryQueryConstraint {
   scopeName: string
   values?: StorageRow
   idsQuery?: StorageQuery
+  /** The caller's transaction holds row locks on the ids: read them as its locking reads see them. */
+  locked?: boolean
 }
 export type SelectColumn = string | Knex.Raw<unknown> | StorageQuery | Record<string, string>
 export type SelectColumns = SelectColumn[] | Record<string, string> | null | undefined
@@ -291,6 +293,8 @@ export type QueryBuilderResult = StorageQuery | { query: QueryBuilderResult }
 export interface DataMinimalRequest extends DataReadRequest {
   filters?: StorageRow
   queryPurpose?: string
+  /** With ids: the caller's transaction holds row locks on them, so read them as its locking reads see them. */
+  locked?: boolean
   applyQueryFilters?: (params: QueryFilteringState & { query: StorageQuery }) => Promise<{ query: QueryBuilderResult } | null | undefined>
 }
 

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

@@ -245,9 +245,10 @@ export function validateFilters ({ filters, scopeName, schemaInfo, vars }) {
 /**
  * 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
+ * `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 } }
@@ -263,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/post-many.js

@@ -108,8 +108,10 @@ async function mergeRows ({ context, helpers, scope, scopes, runHooks, scopeName
   const missing = attributes.flatMap((_row, index) => existing[index] === undefined ? [index] : [])
 
   const visible = new Map()
+  // dataIdsByKeys locked these rows, and may have found one that another
+  // transaction committed after this one's snapshot: read them as locked.
   for (const part of chunk(matched.map(index => existing[index]), VISIBLE_READ_CHUNK)) {
-    const records = await helpers.dataGetMinimal({ scopeName, context, runHooks, ids: part, filters: {}, queryPurpose: 'bulk-write' })
+    const records = await helpers.dataGetMinimal({ scopeName, context, runHooks, ids: part, filters: {}, queryPurpose: 'bulk-write', locked: true })
     for (const record of records) visible.set(String(record.id), record)
   }
   for (const index of matched) {
@@ -285,7 +287,15 @@ export default async function postManyMethod ({
     const response = countsRows
       ? { meta: { count: rows.length } }
       : await manyRowResponse({
-        api, scopeName, context, ids: context.ids || [], returning: context.returning, format: context.format, queryParams: params.queryParams
+        api,
+        scopeName,
+        context,
+        ids: context.ids || [],
+        returning: context.returning,
+        format: context.format,
+        queryParams: params.queryParams,
+        // A merge may match a row committed after this transaction's snapshot and leave it unchanged.
+        locked: onConflict?.action === 'merge'
       })
     await commitOwnedTransaction(context)
     return response