json-rest-api 1.0.29 → 2.1.0

package/plugins/core/connectors/lib/transport-http-helpers.js

@@ -1,7 +1,31 @@
 import {
+  RestApiWriteError,
   REST_API_FIELDSET_ERROR_CODE,
+  REST_API_INCLUDE_ERROR_CODE,
   REST_API_TEMPORAL_DATA_ERROR_CODE
 } from '../../../../lib/rest-api-errors.js'
+import { isRestApiError } from '../../../../lib/error-context.js'
+import { parse as parseContentType } from 'content-type'
+import vary from 'vary'
+
+export function mergeResponseHeaders (...sources) {
+  const headers = new Map()
+  for (const source of sources) {
+    for (const [name, value] of Object.entries(source || {})) {
+      if (value === undefined || value === null) continue
+      const key = name.toLowerCase()
+      headers.set(key, key === 'vary' ? vary.append(headers.get(key) || '', value) : value)
+    }
+  }
+  return Object.fromEntries(headers)
+}
+
+export function getHttpDiagnosticError (error) {
+  // Parser messages and stacks can quote raw input before a resource is known.
+  // Keep the original error for hooks/responses, but log only this safe preview.
+  if (error?.type !== 'entity.parse.failed') return error
+  return { name: 'SyntaxError', message: 'Invalid JSON request body', type: 'entity.parse.failed', status: 400 }
+}
 
 const JSON_API_WRITE_CONTENT_TYPES = [
   'application/vnd.api+json',
@@ -12,6 +36,10 @@ export function isWriteMethod (method) {
   return ['POST', 'PUT', 'PATCH', 'DELETE'].includes(String(method || '').toUpperCase())
 }
 
+export function isMultipartContentType (contentType) {
+  try { return parseContentType(contentType).type === 'multipart/form-data' } catch { return false }
+}
+
 export function getAllowedWriteContentTypes ({ allowMultipart = false } = {}) {
   return allowMultipart
     ? [...JSON_API_WRITE_CONTENT_TYPES, 'multipart/form-data']
@@ -20,9 +48,40 @@ export function getAllowedWriteContentTypes ({ allowMultipart = false } = {}) {
 
 export function isAllowedWriteContentType (contentType, { allowMultipart = false } = {}) {
   if (!contentType) return true
+  try {
+    const media = parseContentType(contentType)
+    return getAllowedWriteContentTypes({ allowMultipart }).includes(media.type) &&
+      (media.type !== JSON_API_WRITE_CONTENT_TYPES[0] || Object.keys(media.parameters).every(key => key === 'profile'))
+  } catch { return false }
+}
+
+export function acceptsJsonApi (accept) {
+  if (accept === undefined) return true
+  // Split only between media ranges; quoted profile URIs can contain commas.
+  const ranges = (String(accept).match(/(?:[^,"]|"(?:\\.|[^"\\])*")+/g) || []).flatMap(value => {
+    try { return [parseContentType(value.trim())] } catch { return [] }
+  })
+  const vendorType = JSON_API_WRITE_CONTENT_TYPES[0]
+  const validParameters = media => Object.keys(media.parameters).every(key => ['profile', 'q'].includes(key))
+  const vendorRanges = ranges.filter(media => media.type === vendorType)
+  if (vendorRanges.length && !vendorRanges.some(validParameters)) return false
+  const matches = ranges.flatMap(media => {
+    const specificity = [vendorType, 'application/*', '*/*'].indexOf(media.type)
+    if (specificity < 0 || !validParameters(media)) return []
+    const q = media.parameters.q ?? '1'
+    const quality = /^(?:0(?:\.\d{0,3})?|1(?:\.0{0,3})?)$/.test(q) ? Number(q) : 0
+    return [{ specificity, quality }]
+  })
+  matches.sort((a, b) => a.specificity - b.specificity || b.quality - a.quality)
+  return (matches[0]?.quality || 0) > 0
+}
+
+export function getNotAcceptableErrorBody () {
+  return { errors: [{ status: '406', title: 'Not Acceptable', detail: 'Accept must allow application/vnd.api+json without unsupported parameters or extensions' }] }
+}
 
-  return getAllowedWriteContentTypes({ allowMultipart })
-    .some((allowedType) => contentType.includes(allowedType))
+export function getNotFoundErrorBody (method, url) {
+  return { errors: [{ status: '404', title: 'Not Found', detail: `The requested endpoint ${method} ${url} does not exist` }] }
 }
 
 export function getUnsupportedMediaTypeErrorBody ({ allowMultipart = false } = {}) {
@@ -53,6 +112,9 @@ export function determineResponseStatus (method, result) {
 }
 
 export function mapRestApiErrorToHttp (error) {
+  // Read hooks can reject with null or undefined.
+  error ??= {}
+  const statusHint = error.statusCode ?? error.status
   let status = 500
   let errors = [{
     status: '500',
@@ -76,6 +138,15 @@ export function mapRestApiErrorToHttp (error) {
       title: 'Invalid Sparse Fieldset',
       detail: error.message
     }]
+  } else if (error.code === REST_API_INCLUDE_ERROR_CODE) {
+    status = 400
+    errors = [{
+      status: '400',
+      code: error.code,
+      title: 'Invalid Include Path',
+      detail: error.message,
+      source: { parameter: 'include' }
+    }]
   } else if (error.code === REST_API_TEMPORAL_DATA_ERROR_CODE) {
     status = 500
     errors = [{
@@ -101,6 +172,12 @@ export function mapRestApiErrorToHttp (error) {
         ...(error.details ? { source: error.details } : {})
       }]
     }
+  } else if (error.code === 'REST_API_PRECONDITION_FAILED') {
+    status = 412
+    errors = [{ status: '412', code: error.code, title: 'Precondition Failed', detail: error.message }]
+  } else if (error.code === 'REST_API_VERSION_CONFLICT') {
+    status = 409
+    errors = [{ status: '409', code: error.code, title: 'Version Conflict', detail: error.message }]
   } else if (error.code === 'REST_API_RESOURCE') {
     switch (error.subtype) {
       case 'not_found':
@@ -120,15 +197,15 @@ export function mapRestApiErrorToHttp (error) {
         errors = [{ status: '400', title: 'Bad Request', detail: error.message }]
     }
   } else if (error.code === 'REST_API_PAYLOAD') {
-    status = 400
+    status = error.statusCode === 413 ? 413 : 400
     errors = [{
-      status: '400',
-      title: 'Bad Request',
+      status: String(status),
+      title: status === 413 ? 'Content Too Large' : 'Bad Request',
       detail: error.message,
-      ...(error.path ? { source: { pointer: error.path } } : {})
+      ...(error.parameter ? { source: { parameter: error.parameter } } : error.path ? { source: { pointer: error.path } } : {})
     }]
-  } else if (typeof error.statusCode === 'number' && error.statusCode >= 400 && error.statusCode < 500) {
-    status = error.statusCode
+  } else if (typeof statusHint === 'number' && statusHint >= 400 && statusHint < 500) {
+    status = statusHint
     errors = [{
       status: String(status),
       title: status === 415 ? 'Unsupported Media Type' : 'Bad Request',
@@ -136,6 +213,10 @@ export function mapRestApiErrorToHttp (error) {
     }]
   }
 
+  if (isRestApiError(error) && error instanceof RestApiWriteError) {
+    errors = errors.map(item => ({ ...item, meta: { ...item.meta, transactionOutcome: error.transactionOutcome } }))
+  }
+
   return {
     status,
     body: { errors }

package/plugins/core/connectors/lib/transport-route-schemas.js

@@ -1,6 +1,6 @@
 import { getRequestContracts } from '../../lib/querying-writing/request-contracts.js'
 
-export function buildTransportRouteSchema ({ routeMeta, api }) {
+export function getTransportRouteContract ({ routeMeta, api }) {
   if (!routeMeta) {
     return null
   }
@@ -38,7 +38,10 @@ export function buildTransportRouteSchema ({ routeMeta, api }) {
     return null
   }
 
-  return {
-    body: contract.schema.toJsonSchema({ mode: contract.mode, additionalProperties: false })
-  }
+  return contract
+}
+
+export function buildTransportRouteSchema (options) {
+  const contract = getTransportRouteContract(options)
+  return contract ? { body: contract.schema.toJsonSchema({ mode: contract.mode, additionalProperties: false }) } : null
 }

package/plugins/core/file-handling-plugin.js

@@ -1,49 +1,17 @@
-/**
- * File Handling Plugin for JSON REST API
- *
- * This plugin provides automatic file upload handling based on schema definitions.
- * It works with any protocol connector (HTTP, Express, WebSocket, etc.) by using
- * a detector registry pattern.
- *
- * Features:
- * - Schema-driven: Detects file fields from type: 'file' in schemas
- * - Protocol-agnostic: Works with any connector that registers a detector
- * - Storage pluggable: Different fields can use different storage backends
- * - Zero configuration: Just define file fields in your schema
- *
- * Usage:
- * ```javascript
- * // 1. Define schema with file fields
- * const imageSchema = {
- *   title: { type: 'string' },
- *   uploadedImage: {
- *     type: 'file',
- *     storage: S3Storage,
- *     accepts: ['image/jpeg', 'image/png']
- *   }
- * };
- *
- * // 2. Use plugins (order matters - file-handling depends on rest-api)
- * api.use(RestApiPlugin);
- * api.use(FileHandlingPlugin);
- * api.use(ExpressPlugin); // Or any other connector
- *
- * // 3. Files are automatically handled!
- * ```
- */
+/** File detection, uploads and cleanup tied to resource writes. */
 
 import { RestApiValidationError } from '../../lib/rest-api-errors.js'
-import { isRestApiError } from '../../lib/error-context.js'
+import { getOperationDiagnosticContext, wrapUnexpectedError } from '../../lib/error-context.js'
+import { createEnhancedLogger } from '../../lib/enhanced-logger.js'
 
 export const FileHandlingPlugin = {
   name: 'file-handling',
   dependencies: ['rest-api'],
 
-  install ({ addHook, helpers, scopes, log, vars, on, api }) {
-    // Track which scopes have file fields
-    const fileScopes = new Map() // scopeName -> fileField[]
+  install ({ addHook, scopes, log, api }) {
+    const boundedLog = createEnhancedLogger(log)
+    const fileFieldsBySchema = new WeakMap()
 
-    // Registry of file detectors from various protocols
     const detectorRegistry = []
 
     /**
@@ -60,27 +28,31 @@ export const FileHandlingPlugin = {
       }
 
       detectorRegistry.push(detector)
-      log.debug(`Registered file detector: ${detector.name}`)
+      boundedLog.debug(`Registered file detector: ${detector.name}`)
     }
 
-    // Store detectors array for inspection
     api.rest.fileDetectors = detectorRegistry
 
-    const trackUploadedFile = (context, upload) => {
-      if (!context.fileHandlingUploads) {
-        context.fileHandlingUploads = []
+    const recordCleanupFailure = async (context, phase, field, error) => {
+      const errors = context.cleanupErrors ||= []
+      errors.push({ phase, field, error })
+      try {
+        await createEnhancedLogger(log, { schemaInfo: context.schemaInfo }).warn('File cleanup failed', {
+          ...getOperationDiagnosticContext(context, { phase }), field, error
+        })
+      } catch (error) {
+        errors.push({ phase: 'logging', during: phase, field, error })
       }
-      context.fileHandlingUploads.push(upload)
     }
 
-    const cleanupParsedFiles = async (files = {}) => {
-      for (const file of Object.values(files)) {
+    const cleanupParsedFiles = async (files = {}, context) => {
+      for (const [field, file] of Object.entries(files)) {
         if (!file?.cleanup) continue
 
         try {
           await file.cleanup()
         } catch (error) {
-          log.warn('Failed to cleanup temp file:', error)
+          await recordCleanupFailure(context, 'temporaryFileCleanup', field, error)
         }
       }
     }
@@ -89,130 +61,89 @@ export const FileHandlingPlugin = {
       const uploads = context.fileHandlingUploads
       if (!uploads || uploads.length === 0) return
 
-      context.fileHandlingUploads = []
+      const remaining = []
       for (const upload of uploads) {
-        if (!upload?.url || typeof upload.storage?.delete !== 'function') {
+        if (upload.transaction !== context.transaction || !upload.url || typeof upload.storage?.delete !== 'function') {
+          remaining.push(upload)
           continue
         }
 
         try {
           await upload.storage.delete(upload.url)
         } catch (error) {
-          log.warn(`Failed to cleanup uploaded file '${upload.url}' after rollback:`, error)
+          remaining.push(upload)
+          await recordCleanupFailure(context, 'uploadedFileCleanup', upload.field, error)
         }
       }
+      context.fileHandlingUploads = remaining
     }
 
-    /**
-     * Analyze a scope's schema to find file fields
-     */
-    const analyzeScopeSchema = (scopeName, scopeOptions) => {
-      const schema = scopeOptions?.schema
-      if (!schema) return
+    const getFileFields = scopeName => {
+      const schemaInfo = scopes[scopeName]?.vars?.schemaInfo
+      if (!schemaInfo) return []
+      const cached = fileFieldsBySchema.get(schemaInfo)
+      if (cached) return cached
 
       const fileFields = []
-
-      // Look for fields with type: 'file'
-      for (const [fieldName, fieldConfig] of Object.entries(schema)) {
-        if (fieldConfig && fieldConfig.type === 'file') {
+      for (const [fieldName, fieldConfig] of Object.entries(schemaInfo.schemaStructure)) {
+        if (fieldConfig?.type === 'file') {
           fileFields.push({
             field: fieldName,
             storage: fieldConfig.storage,
             accepts: fieldConfig.accepts || ['*'],
-            maxSize: fieldConfig.maxSize,
-            required: fieldConfig.required || false
+            maxSize: fieldConfig.maxSize
           })
         }
       }
-
-      if (fileFields.length > 0) {
-        fileScopes.set(scopeName, fileFields)
-        log.info(`Scope '${scopeName}' has ${fileFields.length} file field(s): ${fileFields.map(f => f.field).join(', ')}`)
-      }
-    }
-
-    // Analyze existing scopes
-    for (const [scopeName, scope] of Object.entries(scopes)) {
-      if (scope._scopeOptions) {
-        analyzeScopeSchema(scopeName, scope._scopeOptions)
-      }
+      fileFieldsBySchema.set(schemaInfo, fileFields)
+      return fileFields
     }
 
-    // Listen for new scopes being added
-    addHook('scope:added', 'analyzeFileFields', {}, ({ context }) => {
-      const { scopeName, scopeOptions } = context
-      analyzeScopeSchema(scopeName, scopeOptions)
-    })
-
-    /**
-     * Process files for a scope if it has file fields
-     */
     const processFiles = async (scopeName, params, context) => {
-      const fileFields = fileScopes.get(scopeName)
-      if (!fileFields || fileFields.length === 0) {
-        return // This scope doesn't have file fields
-      }
+      const fileFields = getFileFields(scopeName)
+      if (fileFields.length === 0) return
 
-      // Try each detector to see if we have files
       let parsed = null
       let detectorUsed = null
 
       for (const detector of detectorRegistry) {
+        let matched
         try {
-          if (await detector.detect(params, context)) {
-            log.debug(`Detector '${detector.name}' matched for scope '${scopeName}'`)
-            parsed = await detector.parse(params, context)
-            detectorUsed = detector.name
-            break
-          }
+          matched = await detector.detect(params, context)
         } catch (error) {
-          if (isRestApiError(error)) throw error
-          log.warn(`Detector '${detector.name}' failed:`, error)
+          throw wrapUnexpectedError(error, {
+            message: `File detector '${detector.name}' failed`,
+            context: { scopeName, detector: detector.name, phase: 'fileDetection' }
+          })
         }
-      }
-
-      if (!parsed) {
-        // No files detected - check if any were required
-        for (const fieldConfig of fileFields) {
-          if (fieldConfig.required && !params.inputRecord?.data?.attributes?.[fieldConfig.field]) {
-            throw new RestApiValidationError(
-              `Required file field '${fieldConfig.field}' is missing`,
-              {
-                fields: [fieldConfig.field],
-                violations: [{
-                  field: fieldConfig.field,
-                  message: 'This field is required'
-                }]
-              }
-            )
-          }
+        if (!matched) continue
+        boundedLog.debug(`Detector '${detector.name}' matched for scope '${scopeName}'`)
+        try {
+          parsed = await detector.parse(params, context)
+        } catch (error) {
+          throw wrapUnexpectedError(error, {
+            message: `File parser '${detector.name}' failed`,
+            context: { scopeName, detector: detector.name, phase: 'fileParsing' }
+          })
         }
-        return
+        detectorUsed = detector.name
+        break
       }
 
-      log.debug(`Processing files with detector '${detectorUsed}'`)
+      if (!parsed) return
+
       const { fields = {}, files = {} } = parsed
 
       try {
-        // Process each file field defined in schema
+        boundedLog.debug(`Processing files with detector '${detectorUsed}'`)
+        const fileNames = new Set(fileFields.map(config => config.field))
+        for (const name of Object.keys(files)) {
+          if (!fileNames.has(name)) throw new RestApiValidationError(`Unknown file field '${name}'`, { fields: [name] })
+        }
         for (const fieldConfig of fileFields) {
           const file = files[fieldConfig.field]
 
-          if (!file) {
-            if (fieldConfig.required) {
-              throw new RestApiValidationError(
-                `Required file field '${fieldConfig.field}' is missing`,
-                {
-                  fields: [fieldConfig.field],
-                  violations: [{
-                    field: fieldConfig.field,
-                    message: 'This field is required'
-                  }]
-                }
-              )
-            }
-            continue
-          }
+          if (!file) continue
 
           // Validate mime type
           if (fieldConfig.accepts[0] !== '*') {
@@ -240,7 +171,7 @@ export const FileHandlingPlugin = {
           }
 
           // Validate file size
-          if (fieldConfig.maxSize) {
+          if (fieldConfig.maxSize !== undefined) {
             const maxBytes = parseSize(fieldConfig.maxSize)
             if (file.size > maxBytes) {
               throw new RestApiValidationError(
@@ -256,75 +187,53 @@ export const FileHandlingPlugin = {
             }
           }
 
-          // Upload to storage
           if (!fieldConfig.storage) {
             throw new Error(`No storage configured for file field '${fieldConfig.field}'`)
           }
 
           try {
             const storedUrl = await fieldConfig.storage.upload(file)
-            fields[fieldConfig.field] = storedUrl
-            trackUploadedFile(context, {
+            Object.defineProperty(fields, fieldConfig.field, { value: storedUrl, enumerable: true, writable: true, configurable: true })
+            const uploads = context.fileHandlingUploads ||= []
+            uploads.push({
               field: fieldConfig.field,
               storage: fieldConfig.storage,
-              url: storedUrl
+              url: storedUrl,
+              transaction: context.transaction
             })
-            log.debug(`Uploaded file for field '${fieldConfig.field}' to: ${storedUrl}`)
+            boundedLog.debug(`Uploaded file for field '${fieldConfig.field}'`)
           } catch (error) {
-            if (isRestApiError(error)) throw error
-            throw new RestApiValidationError(
-              `Failed to upload file for field '${fieldConfig.field}': ${error.message}`,
-              {
-                fields: [fieldConfig.field],
-                violations: [{
-                  field: fieldConfig.field,
-                  message: error.message
-                }]
-              }
-            )
+            throw wrapUnexpectedError(error, {
+              message: `Failed to upload file for field '${fieldConfig.field}'`,
+              context: { scopeName, field: fieldConfig.field, phase: 'fileUpload' }
+            })
           }
         }
 
-        // Replace inputRecord with processed data
-        if (!params.inputRecord) {
-          params.inputRecord = { data: { attributes: {} } }
-        }
-        if (!params.inputRecord.data) {
-          params.inputRecord.data = { attributes: {} }
-        }
-        if (!params.inputRecord.data.attributes) {
-          params.inputRecord.data.attributes = {}
-        }
-
-        // Merge fields into attributes
-        Object.assign(params.inputRecord.data.attributes, fields)
+        // Work on the canonical document, including calls using the plain format.
+        context.inputRecord.data ||= { attributes: {} }
+        context.inputRecord.data.attributes = { ...context.inputRecord.data.attributes, ...fields }
       } finally {
-        await cleanupParsedFiles(files)
+        await cleanupParsedFiles(files, context)
       }
     }
 
-    /**
-     * Hook into REST API methods to process files
-     */
     addHook('beforeProcessing', 'processFiles', {}, async ({ context }) => {
-      const method = context.method
-      const scopeName = context.scopeName
-      const params = context.params
-
-      // Only process for mutation methods
-      if (!['post', 'put', 'patch'].includes(method)) {
-        return
-      }
-
-      // Process files if this scope has file fields
-      await processFiles(scopeName, params, context)
+      if (!['post', 'put', 'patch'].includes(context.method)) return
+      await processFiles(context.scopeName, context.params, context)
     })
 
     addHook('afterRollback', 'cleanupUploadedFiles', {}, async ({ context }) => {
       await cleanupUploadedFiles(context)
     })
 
-    log.info('File handling plugin initialized successfully')
+    addHook('afterCommit', 'releaseUploadedFiles', {}, ({ context }) => {
+      if (context.fileHandlingUploads) {
+        context.fileHandlingUploads = context.fileHandlingUploads.filter(upload => upload.transaction !== context.transaction)
+      }
+    })
+
+    boundedLog.info('File handling plugin initialized successfully')
   }
 }
 
@@ -334,6 +243,7 @@ export const FileHandlingPlugin = {
  * @returns {number} Size in bytes
  */
 function parseSize (size) {
+  if (typeof size === 'number' && Number.isFinite(size) && size >= 0) return size
   const units = {
     b: 1,
     kb: 1024,