json-rest-api 1.0.28 → 2.0.0

package/plugins/core/connectors/lib/connector-core.js

@@ -1,11 +1,26 @@
 import { getUrlPrefix } from '../../lib/querying/url-helpers.js'
+import { lockRelationshipParent } from '../../lib/writing/relationship-processor.js'
+import { parseJsonApiQuery } from '../../lib/querying-writing/connectors-query-parser.js'
+import { serializableTransaction } from '../../../../lib/knex-transaction.js'
+import { cloneRequestHeaders } from './request-helpers.js'
+import { RestApiPreconditionFailedError, RestApiValidationError, RestApiWriteError } from '../../../../lib/rest-api-errors.js'
+import { createStrongEntityTag, matchesIfMatch, parseIfMatch } from './http-validators.js'
+import { getOperationDiagnosticContext, getWriteOutcome, isRestApiError, wrapWriteError } from '../../../../lib/error-context.js'
+import { createEnhancedLogger } from '../../../../lib/enhanced-logger.js'
 import {
   determineResponseStatus,
-  mapRestApiErrorToHttp
+  getHttpDiagnosticError,
+  isWriteMethod,
+  mapRestApiErrorToHttp,
+  mergeResponseHeaders
 } from './transport-http-helpers.js'
 
+const responseLifecycleStarted = Symbol('responseLifecycleStarted')
+
 export function extractQueryString (url = '') {
-  return String(url || '').split('?')[1] || ''
+  const value = String(url || '')
+  const index = value.indexOf('?')
+  return index === -1 ? '' : value.slice(index + 1)
 }
 
 export function buildTransportRequestData ({
@@ -74,6 +89,17 @@ export async function runTransportRequestLifecycle ({ context, runHooks }) {
   }
 }
 
+export function addWriteOutcomeToHttpErrors (body, context) {
+  if (!isWriteMethod(context.transport?.request?.method) || !Array.isArray(body?.errors)) return body
+  return {
+    ...body,
+    errors: body.errors.map(error => ({
+      ...error,
+      meta: { ...error.meta, transactionOutcome: error.meta?.transactionOutcome || getWriteOutcome(context) }
+    }))
+  }
+}
+
 export function buildTransportRejectionBody (context) {
   return {
     errors: [{
@@ -99,7 +125,11 @@ export async function applyTransportResponseLifecycle ({
   transportData.response.body = body
   context.transport = transportData
 
-  await runHooks('transport:response', context)
+  // A failing response hook is reported as an error, without rerunning hooks.
+  if (!context[responseLifecycleStarted]) {
+    context[responseLifecycleStarted] = true
+    await runHooks('transport:response', context)
+  }
 
   return transportData.response.headers || {}
 }
@@ -117,7 +147,7 @@ export function getConnectorLocationHeader ({
   publicBaseUrl = ''
 }) {
   if (String(method || '').toUpperCase() !== 'POST') return null
-  if (!context?.id || !routeMeta?.scopeName || !helpers?.getLocation) return null
+  if (context?.id === undefined || context.id === null || !routeMeta?.scopeName || !helpers?.getLocation) return null
 
   const location = helpers.getLocation({
     scopeName: routeMeta.scopeName,
@@ -131,6 +161,8 @@ export function getConnectorLocationHeader ({
 }
 
 export async function executeConnectorRoute ({
+  api,
+  httpValidators = false,
   method,
   handler,
   queryString,
@@ -145,13 +177,72 @@ export async function executeConnectorRoute ({
   publicBaseUrl = '',
   runHooks
 }) {
-  const result = await handler({
+  const requestMethod = String(method).toUpperCase()
+  const ignoreConditions = ['OPTIONS', 'CONNECT', 'TRACE'].includes(requestMethod)
+  const condition = httpValidators && !ignoreConditions ? parseIfMatch(headers?.['if-match']) : undefined
+  const isGet = ['GET', 'HEAD'].includes(requestMethod)
+  const conditionalWrite = condition !== undefined && !isGet && routeMeta?.kind === 'resource' && ['put', 'patch', 'delete'].includes(routeMeta.operation)
+  if (condition !== undefined && !isGet && !conditionalWrite) {
+    throw new RestApiValidationError('If-Match is not supported for this route', { fields: ['headers.if-match'] })
+  }
+  const request = {
     queryString,
     headers,
     params,
     body,
     context
-  })
+  }
+  let result
+  if (conditionalWrite) {
+    result = await api.transaction(async transaction => {
+      const readTransport = buildTransportData({ ...transportData.request, headers: cloneRequestHeaders(transportData.request.headers), method: 'GET', body: undefined })
+      let readContext
+      if (condition.wildcard) {
+        readContext = { ...context }
+      } else {
+        readContext = {
+          ...context,
+          request: { ...context.request, headers: cloneRequestHeaders(context.request?.headers), method: 'GET' },
+          transport: readTransport,
+          precondition: true
+        }
+      }
+      let preconditionPassed = false
+      const precondition = async () => {
+        preconditionPassed = false
+        let representation
+        try {
+          representation = await api.resources[routeMeta.scopeName].get({
+            id: params.id,
+            format: 'jsonapi',
+            transaction,
+            ...(condition.wildcard ? {} : { queryParams: parseJsonApiQuery(queryString) })
+          }, readContext)
+          await lockRelationshipParent({ context: readContext, helpers, scopeName: routeMeta.scopeName })
+        } catch (error) {
+          // Conditional PUT requires an existing visible representation.
+          if (routeMeta.operation === 'put' && isRestApiError(error) && error.subtype === 'not_found') {
+            throw new RestApiPreconditionFailedError({ resourceType: routeMeta.scopeName, resourceId: params.id })
+          }
+          throw error
+        }
+        if (!condition.wildcard) {
+          await applyTransportResponseLifecycle({ context: readContext, transportData: readTransport, status: 200, body: representation, runHooks })
+          const bytes = JSON.stringify(getConnectorResponseBody(readTransport.response.body))
+          const tag = bytes === undefined ? undefined : parseIfMatch(createStrongEntityTag(bytes)).tags[0]
+          if (!matchesIfMatch(condition, { exists: bytes !== undefined, tag })) {
+            throw new RestApiPreconditionFailedError({ resourceType: routeMeta.scopeName, resourceId: params.id })
+          }
+        }
+        preconditionPassed = true
+      }
+      const result = await handler({ ...request, transaction, precondition })
+      if (!preconditionPassed) throw new RestApiValidationError('Resource handler did not evaluate its HTTP precondition', { fields: ['headers.if-match'] })
+      return result
+    }, { [serializableTransaction]: !condition.wildcard })
+  } else {
+    result = await handler(request)
+  }
 
   const status = determineResponseStatus(method, result)
   const location = getConnectorLocationHeader({
@@ -170,32 +261,65 @@ export async function executeConnectorRoute ({
     runHooks
   })
 
+  let responseBody
+  if (status !== 204) {
+    const response = context && transportData ? transportData.response.body : result
+    responseBody = getConnectorResponseBody(response)
+  }
+  const serialized = httpValidators && isGet && status === 200 && responseBody !== undefined
+  const responseBytes = serialized ? JSON.stringify(responseBody) : undefined
+  const validatorHeaders = serialized ? { etag: createStrongEntityTag(responseBytes) } : undefined
+  if (condition !== undefined && isGet && status >= 200 && status < 300) {
+    const tag = validatorHeaders ? parseIfMatch(validatorHeaders.etag).tags[0] : undefined
+    if (!matchesIfMatch(condition, { exists: status === 200, tag })) {
+      throw new RestApiPreconditionFailedError({ resourceType: routeMeta?.scopeName, resourceId: params?.id })
+    }
+  }
   return {
     status,
-    body: status === 204 ? undefined : getConnectorResponseBody(result),
-    headers: {
-      ...(result?.headers || {}),
-      ...transportHeaders
-    },
+    body: serialized ? responseBytes : responseBody,
+    serialized,
+    headers: mergeResponseHeaders(result?.headers, transportHeaders, validatorHeaders),
     location,
     result
   }
 }
 
+export async function logHttpRequestError ({ error, context, log, scopes, routeMeta, api, method, path, message }) {
+  try {
+    const schemaInfo = scopes[routeMeta?.scopeName]?.vars?.schemaInfo || context.schemaInfo
+    const logger = createEnhancedLogger(log, { schemaInfo, redactFields: ['body', 'headers'] })
+    await logger.logError(message, getHttpDiagnosticError(error), {
+      ...getOperationDiagnosticContext(context, {
+        phase: 'httpError',
+        method,
+        scopeName: routeMeta?.scopeName || context.scopeName,
+        backend: api.knex?.instance?.client?.config?.client
+      }),
+      path
+    })
+  } catch (error) {
+    (context.cleanupErrors ||= []).push({ phase: 'logging', during: 'httpError', error })
+  }
+}
+
 export async function handleConnectorError ({
   error,
   context,
   transportData,
   runHooks
 }) {
+  const write = isWriteMethod(transportData?.request?.method)
+  if (write && !(isRestApiError(error) && error instanceof RestApiWriteError)) error = wrapWriteError(error, context)
   const { status, body } = mapRestApiErrorToHttp(error)
-  const headers = await applyTransportResponseLifecycle({
-    context,
-    transportData,
-    status,
-    body,
-    runHooks
-  })
-
-  return { status, body, headers }
+  try {
+    const headers = await applyTransportResponseLifecycle({ context, transportData, status, body, runHooks })
+    return { status, body: context && transportData ? transportData.response.body : body, headers }
+  } catch (responseError) {
+    const failure = new AggregateError([error, responseError], 'Request and response hook failed', { cause: error })
+    const outcome = mapRestApiErrorToHttp(write ? wrapWriteError(failure, context) : failure)
+    // The first attempt marked the lifecycle started, so this only updates metadata.
+    const headers = await applyTransportResponseLifecycle({ context, transportData, ...outcome, runHooks })
+    return { ...outcome, headers }
+  }
 }

package/plugins/core/connectors/lib/formidable-detector.js

@@ -1,138 +1,81 @@
-/**
- * Formidable File Detector for HTTP Multipart Uploads
- *
- * This detector handles multipart/form-data uploads using the formidable library.
- * Unlike busboy, formidable saves files to disk temporarily, which is better
- * for large files.
- *
- * Features:
- * - Disk-based storage (better for large files)
- * - Automatic temp file cleanup
- * - Progress tracking support
- * - Built-in file type detection
- *
- * Usage:
- * ```javascript
- * import { createFormidableDetector } from 'jsonrestapi/plugins/core/lib/formidable-detector.js';
- *
- * api.use(ExpressPlugin, {
- *   fileParser: 'formidable',
- *   fileParserOptions: {
- *     uploadDir: './uploads/temp',
- *     keepExtensions: true,
- *     maxFileSize: 200 * 1024 * 1024 // 200MB
- *   }
- * });
- * ```
- */
-
-import { requirePackage } from 'hooked-api'
-import { promises as fs } from 'fs'
-import path from 'path'
+import { throwMissingPackage } from '../../../../lib/missing-package.js'
+import { promises as fs } from 'node:fs'
+import path from 'node:path'
+import { tmpdir } from 'node:os'
+import { RestApiPayloadError } from '../../../../lib/rest-api-errors.js'
+import { isMultipartContentType } from './transport-http-helpers.js'
+import { addMultipartField, multipartLimits } from './multipart-helpers.js'
 
 let formidable
-try {
-  formidable = (await import('formidable')).default
-} catch (e) {
-  requirePackage('formidable', 'express/http-connector',
-    'Formidable is required for multipart/form-data file uploads with disk storage. This is a peer dependency.')
+try { formidable = (await import('formidable')).default } catch {
+  throwMissingPackage('formidable', 'express-connector', 'Formidable is required for multipart uploads. Install the optional formidable peer.')
 }
 
-/**
- * Creates a formidable-based file detector
- *
- * @param {Object} options - Formidable configuration options
- * @param {string} options.uploadDir - Directory for temporary files
- * @param {boolean} options.keepExtensions - Keep file extensions
- * @param {number} options.maxFileSize - Max file size in bytes
- * @param {boolean} options.multiples - Allow multiple files per field
- * @returns {Object} Detector object with detect() and parse() methods
- */
+/** Buffer completed uploads, then remove this request's temporary directory. */
 export function createFormidableDetector (options = {}) {
-  // Set default upload directory
-  const uploadDir = options.uploadDir || path.join(process.cwd(), 'uploads', 'temp')
-
+  const uploadDir = path.resolve(options.uploadDir || tmpdir())
   return {
     name: 'formidable-multipart',
-
-    /**
-     * Check if this detector can handle the request
-     * @param {Object} params - Request parameters
-     * @returns {boolean} True if this is a multipart request
-     */
-    detect: (params) => {
-      const req = params._httpReq || params._expressReq
-      if (!req || !req.headers) return false
-
-      const contentType = req.headers['content-type'] || ''
-      return contentType.includes('multipart/form-data')
-    },
-
-    /**
-     * Parse multipart data from the request
-     * @param {Object} params - Request parameters
-     * @returns {Promise<{fields: Object, files: Object}>} Parsed data
-     */
+    detect: params => isMultipartContentType((params._httpReq || params._expressReq)?.headers?.['content-type']),
     parse: async (params) => {
       const req = params._httpReq || params._expressReq
-
-      // Ensure upload directory exists
-      await fs.mkdir(uploadDir, { recursive: true })
-
-      // Create form parser
-      const form = formidable({
-        uploadDir,
-        keepExtensions: true,
-        ...options
-      })
-
-      // Parse the request
-      const [fields, fileUploads] = await form.parse(req)
-
-      // Normalize formidable's file format to our standard format
-      const files = {}
-
-      for (const [fieldname, uploadedFiles] of Object.entries(fileUploads)) {
-        // Formidable returns arrays for multiple files
-        const fileArray = Array.isArray(uploadedFiles) ? uploadedFiles : [uploadedFiles]
-
-        // For now, just take the first file (TODO: handle multiple files per field)
-        const file = fileArray[0]
-
-        if (file) {
-          // Read file data into memory (for small files)
-          // For large files, you might want to keep them on disk
-          const data = await fs.readFile(file.filepath)
-
-          files[fieldname] = {
+      if (!req?.on || req.aborted) throw new RestApiPayloadError('Multipart request is unavailable or aborted')
+      let directory, failure, rejectParsing, result
+      const onAborted = () => rejectParsing?.(new RestApiPayloadError('Multipart request aborted'))
+      req.once('aborted', onAborted)
+      try {
+        await fs.mkdir(uploadDir, { recursive: true })
+        directory = await fs.mkdtemp(path.join(uploadDir, 'json-rest-upload-'))
+        if (req.aborted) throw new RestApiPayloadError('Multipart request aborted')
+        const form = formidable({
+          maxFileSize: multipartLimits.fileSize,
+          maxTotalFileSize: multipartLimits.fileSize * multipartLimits.files,
+          maxFiles: multipartLimits.files,
+          maxFields: multipartLimits.fields,
+          maxFieldsSize: multipartLimits.fieldSize * multipartLimits.fields,
+          allowEmptyFiles: true,
+          minFileSize: 0,
+          ...options,
+          uploadDir: directory
+        })
+        const entries = []
+        const uploads = []
+        form.on('field', (name, value) => entries.push([name, value]))
+        form.on('file', (name, file) => uploads.push([name, file]))
+        await new Promise((resolve, reject) => {
+          rejectParsing = reject
+          // Callback mode avoids an unobserved internal promise on early abort.
+          form.parse(req, error => error ? reject(error) : resolve()).catch(reject)
+        })
+        const fields = new Map()
+        const files = new Map()
+        for (const [name, value] of entries) addMultipartField(fields, name, value)
+        for (const [name, file] of uploads) {
+          if (files.has(name)) throw new RestApiPayloadError(`Multiple files for field '${name}' are not supported`, { path: name })
+          files.set(name, {
             filename: file.originalFilename || 'unknown',
             mimetype: file.mimetype || 'application/octet-stream',
             size: file.size,
-            data,
-            filepath: file.filepath, // Keep for reference
-
-            // Cleanup function to remove temp file
-            cleanup: async () => {
-              try {
-                await fs.unlink(file.filepath)
-              } catch (error) {
-                // File might already be deleted, ignore
-                if (error.code !== 'ENOENT') {
-                  throw error
-                }
-              }
-            }
+            data: await fs.readFile(file.filepath)
+          })
+        }
+        result = { fields: Object.fromEntries(fields), files: Object.fromEntries(files) }
+      } catch (error) {
+        failure = [400, 413].includes(error.httpCode)
+          ? new RestApiPayloadError(error.message, { statusCode: error.httpCode, cause: error })
+          : error
+      } finally {
+        req.removeListener('aborted', onAborted)
+        if (failure) req.resume()
+        if (directory) {
+          try { await fs.rm(directory, { recursive: true, force: true }) } catch (error) {
+            if (failure) failure.cleanupError = error
+            else failure = error
           }
         }
       }
-
-      // Normalize fields (formidable returns arrays for repeated fields)
-      const normalizedFields = {}
-      for (const [key, value] of Object.entries(fields)) {
-        normalizedFields[key] = Array.isArray(value) && value.length === 1 ? value[0] : value
-      }
-
-      return { fields: normalizedFields, files }
+      if (failure) throw failure
+      return result
     }
   }
 }

package/plugins/core/connectors/lib/http-validators.js

@@ -0,0 +1,77 @@
+// @ts-check
+/** @typedef {{ readonly weak: boolean, readonly value: string }} EntityTag */
+/** @typedef {{ readonly wildcard: true, readonly tags: readonly [] } | { readonly wildcard: false, readonly tags: readonly EntityTag[] }} IfMatchCondition */
+import { RestApiValidationError } from '../../../../lib/rest-api-errors.js'
+import { createHash } from 'node:crypto'
+
+const MAX_HEADER_LENGTH = 8192
+const MAX_LIST_ITEMS = 128
+const invalidIfMatch = () => new RestApiValidationError('Invalid or oversized If-Match header', { fields: ['headers.if-match'] })
+
+// Hash serialized bytes only; callers must send these same bytes without reserialization.
+/**
+ * @param {string | Buffer} body
+ * @param {{ contentType?: string, contentEncoding?: string }} [options]
+ * @returns {string}
+ */
+export function createStrongEntityTag (body, { contentType = 'application/vnd.api+json', contentEncoding = 'identity' } = {}) {
+  if (typeof body !== 'string' && !Buffer.isBuffer(body)) throw new TypeError('Entity tags require a serialized string or Buffer')
+  if (typeof contentType !== 'string' || typeof contentEncoding !== 'string') throw new TypeError('Entity tag representation metadata must be strings')
+  const digest = createHash('sha256').update(JSON.stringify([contentType, contentEncoding])).update('\0').update(body).digest('base64url')
+  return `"jra1-${digest}"`
+}
+
+// Entity tags are opaque octets, not JSON strings: backslashes do not escape quotes.
+/** @param {unknown} input @returns {IfMatchCondition | undefined} */
+export function parseIfMatch (input) {
+  if (input === undefined) return undefined
+  /** @type {readonly unknown[]} */
+  const lines = Array.isArray(input) ? input : [input]
+  if (lines.length > MAX_LIST_ITEMS) throw invalidIfMatch()
+  let length = Math.max(0, lines.length - 1)
+  for (const line of lines) {
+    if (typeof line !== 'string' || (length += line.length) > MAX_HEADER_LENGTH) throw invalidIfMatch()
+  }
+  const text = lines.join(',')
+  if (text.replace(/^[ \t]+|[ \t]+$/g, '') === '*') return { wildcard: true, tags: [] }
+  const tags = []
+  let position = 0
+  let separators = 0
+  const whitespace = () => { while (text[position] === ' ' || text[position] === '\t') position++ }
+  while (position < text.length) {
+    whitespace()
+    if (position === text.length) break
+    if (text[position] === ',') {
+      if (++separators > MAX_LIST_ITEMS) throw invalidIfMatch()
+      position++
+      continue
+    }
+    const weak = text.startsWith('W/', position)
+    if (weak) position += 2
+    if (text[position++] !== '"') throw invalidIfMatch()
+    const start = position
+    while (position < text.length && text[position] !== '"') {
+      const code = text.charCodeAt(position++)
+      if (!(code === 0x21 || (code >= 0x23 && code <= 0x7e) || (code >= 0x80 && code <= 0xff))) throw invalidIfMatch()
+    }
+    if (position === text.length) throw invalidIfMatch()
+    tags.push({ weak, value: text.slice(start, position++) })
+    if (tags.length > MAX_LIST_ITEMS) throw invalidIfMatch()
+    whitespace()
+    if (position < text.length && text[position] !== ',') throw invalidIfMatch()
+  }
+  return { wildcard: false, tags }
+}
+
+/**
+ * @param {IfMatchCondition | undefined} condition
+ * @param {{ exists: boolean, tag?: EntityTag }} representation
+ * @returns {boolean}
+ */
+export function matchesIfMatch (condition, { exists, tag }) {
+  if (condition === undefined) return true
+  if (!exists) return false
+  if (condition.wildcard) return true
+  if (!tag || tag.weak) return false
+  return condition.tags.some(candidate => !candidate.weak && candidate.value === tag.value)
+}

package/plugins/core/connectors/lib/multipart-helpers.js

@@ -0,0 +1,18 @@
+import { RestApiPayloadError } from '../../../../lib/rest-api-errors.js'
+
+export const multipartLimits = Object.freeze({
+  fileSize: 10 * 1024 * 1024,
+  files: 10,
+  fields: 100,
+  fieldSize: 64 * 1024,
+  parts: 110
+})
+
+export function addMultipartField (fields, name, value) {
+  if (typeof name !== 'string' || !name) throw new RestApiPayloadError('Multipart fields must have a name')
+  const array = name.match(/^(.+)\[\d*\]$/)
+  const key = array ? array[1] : name
+  if (fields.has(key)) {
+    fields.set(key, [...[].concat(fields.get(key)), value])
+  } else fields.set(key, array ? [value] : value)
+}

package/plugins/core/connectors/lib/request-helpers.js

@@ -3,9 +3,18 @@
  * Used by both HTTP and Express plugins
  */
 
+/**
+ * Copy HTTP header fields, including repeated-value arrays, for a separate view.
+ * @param {import('node:http').IncomingHttpHeaders} [headers]
+ * @returns {import('node:http').IncomingHttpHeaders}
+ */
+export function cloneRequestHeaders (headers = {}) {
+  return Object.fromEntries(Object.entries(headers).map(([name, value]) => [name, Array.isArray(value) ? [...value] : value]))
+}
+
 /**
  * Extract the real client IP address, handling proxies
- * @param {Object} req - The request object (Node.js http.IncomingMessage or Express Request)
+ * @param {Object} req - The request object
  * @returns {string} The client IP address
  */
 export function getClientIP (req) {