json-rest-api 1.0.22 → 1.0.24

package/plugins/core/connectors/fastify-plugin.js

@@ -0,0 +1,206 @@
+import { createContext } from './lib/request-helpers.js'
+import { createEnhancedLogger } from '../../../lib/enhanced-logger.js'
+import { buildTransportRouteSchema } from './lib/transport-route-schemas.js'
+import {
+  isWriteMethod,
+  isAllowedWriteContentType,
+  getUnsupportedMediaTypeErrorBody
+} from './lib/transport-http-helpers.js'
+import {
+  extractQueryString,
+  buildTransportRequestData,
+  createConnectorContext,
+  runTransportRequestLifecycle,
+  buildTransportRejectionBody,
+  executeConnectorRoute,
+  handleConnectorError
+} from './lib/connector-core.js'
+
+function applyHeaders (reply, headers = {}) {
+  for (const [headerName, headerValue] of Object.entries(headers)) {
+    reply.header(headerName, headerValue)
+  }
+}
+
+function registerVendorJsonParser (app) {
+  if (typeof app?.addContentTypeParser !== 'function') return
+  if (typeof app?.hasContentTypeParser === 'function' && app.hasContentTypeParser('application/vnd.api+json')) {
+    return
+  }
+
+  app.addContentTypeParser(
+    'application/vnd.api+json',
+    { parseAs: 'string' },
+    (request, body, done) => {
+      if (body === '' || body === undefined || body === null) {
+        done(null, {})
+        return
+      }
+
+      try {
+        done(null, JSON.parse(body))
+      } catch (error) {
+        error.statusCode = 400
+        done(error)
+      }
+    }
+  )
+}
+
+export const FastifyPlugin = {
+  name: 'fastify',
+  dependencies: ['rest-api'],
+
+  async install ({ vars, helpers, pluginOptions, log, api, runHooks, addHook }) {
+    const fastifyOptions = pluginOptions || {}
+    const app = fastifyOptions.app
+
+    if (!app || typeof app.route !== 'function') {
+      throw new Error('FastifyPlugin requires a Fastify instance in pluginOptions.app.')
+    }
+
+    const enhancedLog = createEnhancedLogger(log, {
+      logFullErrors: true,
+      includeStack: true
+    })
+
+    if (!api.http) {
+      api.http = {}
+    }
+    api.http.fastify = { app }
+
+    const mountPath = fastifyOptions.mountPath || ''
+    const strictContentType = fastifyOptions.strictContentType !== false
+
+    vars.transport = {
+      type: 'fastify',
+      matchAll: '*',
+      mountPath
+    }
+
+    registerVendorJsonParser(app)
+
+    const buildFastifyHandler = ({ method, path, handler, routeMeta }) => {
+      const routeSchema = buildTransportRouteSchema({ routeMeta, api })
+
+      const fastifyErrorHandler = async (error, request, reply) => {
+        enhancedLog.logError('Fastify request error', error, {
+          method: request.method,
+          path: request.url
+        })
+
+        const context = request.jsonRestContext || null
+        const transportData = context?.transport || null
+        const { status, body, headers } = await handleConnectorError({
+          error,
+          context,
+          transportData,
+          runHooks
+        })
+
+        applyHeaders(reply, headers)
+        reply.code(status)
+        reply.type('application/vnd.api+json')
+        return reply.send(body)
+      }
+
+      const preValidation = async (request, reply) => {
+        if (!strictContentType || !isWriteMethod(method)) {
+          return
+        }
+
+        const contentType = request.headers?.['content-type'] || ''
+        if (isAllowedWriteContentType(contentType)) {
+          return
+        }
+
+        reply.code(415)
+        reply.type('application/vnd.api+json')
+        return reply.send(getUnsupportedMediaTypeErrorBody())
+      }
+
+      return {
+        method,
+        url: path,
+        ...(routeSchema ? { schema: routeSchema } : {}),
+        errorHandler: fastifyErrorHandler,
+        preValidation,
+        handler: async (request, reply) => {
+          const requestData = buildTransportRequestData({
+            method: request.method,
+            url: request.url,
+            path: request.url,
+            headers: request.headers,
+            body: request.body,
+            params: request.params,
+            query: request.query
+          })
+          const { context, transportData } = createConnectorContext({
+            request,
+            reply,
+            source: 'fastify',
+            mountPath,
+            requestData,
+            createContext
+          })
+          request.jsonRestContext = context
+
+          const { rejected, handled } = await runTransportRequestLifecycle({
+            context,
+            runHooks
+          })
+
+          if (rejected) {
+            const rejectionBody = buildTransportRejectionBody(context)
+            applyHeaders(reply, transportData.response.headers)
+            reply.code(context.rejection.status || 500)
+            reply.type('application/vnd.api+json')
+            return reply.send(rejectionBody)
+          }
+
+          if (handled) {
+            return
+          }
+
+          const outcome = await executeConnectorRoute({
+            method,
+            handler,
+            queryString: extractQueryString(request?.raw?.url || request?.url || ''),
+            headers: request.headers,
+            params: request.params,
+            body: request.body,
+            context,
+            transportData,
+            routeMeta,
+            helpers,
+            mountPath,
+            runHooks
+          })
+
+          applyHeaders(reply, outcome.headers)
+          reply.type('application/vnd.api+json')
+
+          if (outcome.location) {
+            reply.header('Location', outcome.location)
+          }
+
+          if (outcome.status === 204) {
+            reply.code(204)
+            return reply.send()
+          }
+
+          reply.code(outcome.status)
+          return reply.send(outcome.body)
+        }
+      }
+    }
+
+    addHook('addRoute', 'fastifyRouteCreator', {}, async ({ context }) => {
+      const route = buildFastifyHandler(context)
+      app.route(route)
+      log.trace(`Fastify route created: ${context.method} ${context.path}`)
+    })
+
+    log.info('Fastify plugin initialized successfully')
+  }
+}

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

@@ -101,14 +101,14 @@ export function createBusboyDetector (options = {}) {
           const chunks = []
           let size = 0
 
-          const filePromise = new Promise((fileResolve, fileReject) => {
+          const filePromise = new Promise((resolve, reject) => {
             file.on('data', (chunk) => {
               chunks.push(chunk)
               size += chunk.length
             })
 
             file.on('limit', () => {
-              fileReject(new Error(`File size limit exceeded for field '${fieldname}'`))
+              reject(new Error(`File size limit exceeded for field '${fieldname}'`))
             })
 
             file.on('end', () => {
@@ -119,10 +119,10 @@ export function createBusboyDetector (options = {}) {
                 size,
                 data: Buffer.concat(chunks)
               }
-              fileResolve()
+              resolve()
             })
 
-            file.on('error', fileReject)
+            file.on('error', reject)
           })
 
           filePromises.push(filePromise)

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

@@ -0,0 +1,195 @@
+import { getUrlPrefix } from '../../lib/querying/url-helpers.js'
+import {
+  determineResponseStatus,
+  mapRestApiErrorToHttp
+} from './transport-http-helpers.js'
+
+export function extractQueryString (url = '') {
+  return String(url || '').split('?')[1] || ''
+}
+
+export function buildTransportRequestData ({
+  method,
+  url,
+  path,
+  headers,
+  body,
+  params,
+  query
+}) {
+  return {
+    method,
+    url,
+    path,
+    headers,
+    body,
+    params,
+    query
+  }
+}
+
+export function buildTransportData (requestData) {
+  return {
+    request: requestData,
+    response: {
+      headers: {},
+      status: null
+    }
+  }
+}
+
+export function createConnectorContext ({
+  request,
+  reply,
+  source,
+  mountPath = '',
+  requestData,
+  createContext,
+  urlPrefixOverride
+}) {
+  const context = createContext(request, reply, source)
+
+  if (urlPrefixOverride) {
+    context.urlPrefixOverride = urlPrefixOverride
+  }
+
+  context.urlPrefix = getUrlPrefix(
+    context,
+    { vars: { transport: { mountPath } } },
+    request
+  )
+
+  const transportData = buildTransportData(requestData)
+  context.transport = transportData
+
+  return { context, transportData }
+}
+
+export async function runTransportRequestLifecycle ({ context, runHooks }) {
+  await runHooks('transport:request', context)
+
+  return {
+    rejected: !!context.rejection,
+    handled: !!context.handled
+  }
+}
+
+export function buildTransportRejectionBody (context) {
+  return {
+    errors: [{
+      status: String(context.rejection?.status || 500),
+      title: context.rejection?.title || 'Request Rejected',
+      detail: context.rejection?.message
+    }]
+  }
+}
+
+export async function applyTransportResponseLifecycle ({
+  context,
+  transportData,
+  status,
+  body,
+  runHooks
+}) {
+  if (!context || !transportData) {
+    return {}
+  }
+
+  transportData.response.status = status
+  transportData.response.body = body
+  context.transport = transportData
+
+  await runHooks('transport:response', context)
+
+  return transportData.response.headers || {}
+}
+
+export function getConnectorResponseBody (result) {
+  return result && result.body !== undefined ? result.body : result
+}
+
+export function getConnectorLocationHeader ({
+  method,
+  context,
+  routeMeta,
+  helpers,
+  mountPath = ''
+}) {
+  if (String(method || '').toUpperCase() !== 'POST') return null
+  if (!context?.id || !routeMeta?.scopeName || !helpers?.getLocation) return null
+
+  const location = helpers.getLocation({
+    scopeName: routeMeta.scopeName,
+    id: context.id
+  })
+
+  const baseUrl = context.urlPrefix || mountPath
+  return `${baseUrl}${location}`
+}
+
+export async function executeConnectorRoute ({
+  method,
+  handler,
+  queryString,
+  headers,
+  params,
+  body,
+  context,
+  transportData,
+  routeMeta,
+  helpers,
+  mountPath = '',
+  runHooks
+}) {
+  const result = await handler({
+    queryString,
+    headers,
+    params,
+    body,
+    context
+  })
+
+  const status = determineResponseStatus(method, result)
+  const transportHeaders = await applyTransportResponseLifecycle({
+    context,
+    transportData,
+    status,
+    body: result,
+    runHooks
+  })
+
+  return {
+    status,
+    body: status === 204 ? undefined : getConnectorResponseBody(result),
+    headers: {
+      ...(result?.headers || {}),
+      ...transportHeaders
+    },
+    location: getConnectorLocationHeader({
+      method,
+      context,
+      routeMeta,
+      helpers,
+      mountPath
+    }),
+    result
+  }
+}
+
+export async function handleConnectorError ({
+  error,
+  context,
+  transportData,
+  runHooks
+}) {
+  const { status, body } = mapRestApiErrorToHttp(error)
+  const headers = await applyTransportResponseLifecycle({
+    context,
+    transportData,
+    status,
+    body,
+    runHooks
+  })
+
+  return { status, body, headers }
+}

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

@@ -0,0 +1,122 @@
+const JSON_API_WRITE_CONTENT_TYPES = [
+  'application/vnd.api+json',
+  'application/json'
+]
+
+export function isWriteMethod (method) {
+  return ['POST', 'PUT', 'PATCH', 'DELETE'].includes(String(method || '').toUpperCase())
+}
+
+export function getAllowedWriteContentTypes ({ allowMultipart = false } = {}) {
+  return allowMultipart
+    ? [...JSON_API_WRITE_CONTENT_TYPES, 'multipart/form-data']
+    : [...JSON_API_WRITE_CONTENT_TYPES]
+}
+
+export function isAllowedWriteContentType (contentType, { allowMultipart = false } = {}) {
+  if (!contentType) return true
+
+  return getAllowedWriteContentTypes({ allowMultipart })
+    .some((allowedType) => contentType.includes(allowedType))
+}
+
+export function getUnsupportedMediaTypeErrorBody ({ allowMultipart = false } = {}) {
+  const acceptedTypes = getAllowedWriteContentTypes({ allowMultipart }).join(' or ')
+
+  return {
+    errors: [{
+      status: '415',
+      title: 'Unsupported Media Type',
+      detail: `Content-Type must be ${acceptedTypes}`
+    }]
+  }
+}
+
+export function determineResponseStatus (method, result) {
+  const upperMethod = String(method || '').toUpperCase()
+
+  if (result && typeof result.statusCode === 'number') {
+    return result.statusCode
+  }
+
+  if (upperMethod === 'POST' && result) return 201
+  if (upperMethod === 'POST' && !result) return 204
+  if (upperMethod === 'DELETE') return 204
+  if ((upperMethod === 'PUT' || upperMethod === 'PATCH') && !result) return 204
+
+  return 200
+}
+
+export function mapRestApiErrorToHttp (error) {
+  let status = 500
+  let errors = [{
+    status: '500',
+    title: 'Internal Server Error',
+    detail: error.message
+  }]
+
+  if (error?.validation) {
+    status = 400
+    errors = error.validation.map((issue) => ({
+      status: '400',
+      title: 'Bad Request',
+      detail: issue.message,
+      ...(issue.instancePath ? { source: { pointer: issue.instancePath } } : {})
+    }))
+  } else if (error.code === 'REST_API_VALIDATION') {
+    status = 422
+    if (error.details?.violations?.length) {
+      errors = error.details.violations.map((violation) => ({
+        status: '422',
+        title: 'Validation Error',
+        detail: violation.message,
+        source: { pointer: violation.field }
+      }))
+    } else {
+      errors = [{
+        status: '422',
+        title: 'Validation Error',
+        detail: error.message,
+        ...(error.details ? { source: error.details } : {})
+      }]
+    }
+  } else if (error.code === 'REST_API_RESOURCE') {
+    switch (error.subtype) {
+      case 'not_found':
+        status = 404
+        errors = [{ status: '404', title: 'Not Found', detail: error.message }]
+        break
+      case 'conflict':
+        status = 409
+        errors = [{ status: '409', title: 'Conflict', detail: error.message }]
+        break
+      case 'forbidden':
+        status = 403
+        errors = [{ status: '403', title: 'Forbidden', detail: error.message }]
+        break
+      default:
+        status = 400
+        errors = [{ status: '400', title: 'Bad Request', detail: error.message }]
+    }
+  } else if (error.code === 'REST_API_PAYLOAD') {
+    status = 400
+    errors = [{
+      status: '400',
+      title: 'Bad Request',
+      detail: error.message,
+      ...(error.path ? { source: { pointer: error.path } } : {})
+    }]
+  } else if (typeof error.statusCode === 'number' && error.statusCode >= 400 && error.statusCode < 500) {
+    status = error.statusCode
+    errors = [{
+      status: String(status),
+      title: status === 415 ? 'Unsupported Media Type' : 'Bad Request',
+      detail: error.message
+    }]
+  }
+
+  return {
+    status,
+    body: { errors }
+  }
+}

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

@@ -0,0 +1,92 @@
+import { getRequestContracts } from '../../lib/querying-writing/request-contracts.js'
+
+const STRING_OR_NUMBER_SCHEMA = {
+  anyOf: [
+    { type: 'string' },
+    { type: 'number' }
+  ]
+}
+
+function buildResourceIdentifierSchema () {
+  return {
+    type: 'object',
+    additionalProperties: false,
+    required: ['type', 'id'],
+    properties: {
+      type: { type: 'string', minLength: 1 },
+      id: STRING_OR_NUMBER_SCHEMA
+    }
+  }
+}
+
+function buildRelationshipValueSchema (operation) {
+  if (operation === 'patchRelationship') {
+    return {
+      anyOf: [
+        { type: 'null' },
+        buildResourceIdentifierSchema(),
+        {
+          type: 'array',
+          items: buildResourceIdentifierSchema()
+        }
+      ]
+    }
+  }
+
+  return {
+    type: 'array',
+    items: buildResourceIdentifierSchema()
+  }
+}
+
+function buildRelationshipRouteBodySchema (operation) {
+  if (!['postRelationship', 'patchRelationship', 'deleteRelationship'].includes(operation)) {
+    return null
+  }
+
+  return {
+    type: 'object',
+    additionalProperties: false,
+    required: ['data'],
+    properties: {
+      data: buildRelationshipValueSchema(operation)
+    }
+  }
+}
+
+export function buildTransportRouteSchema ({ routeMeta, api }) {
+  if (!routeMeta) {
+    return null
+  }
+
+  if (routeMeta.kind === 'relationship') {
+    const relationshipBodySchema = buildRelationshipRouteBodySchema(routeMeta.operation)
+    return relationshipBodySchema ? { body: relationshipBodySchema } : null
+  }
+
+  if (routeMeta.kind !== 'resource' || !['post', 'put', 'patch'].includes(routeMeta.operation)) {
+    return null
+  }
+
+  const scope = api.resources?.[routeMeta.scopeName]
+  const schemaInfo = scope?.vars?.schemaInfo
+  if (!schemaInfo?.schemaInstance) {
+    return null
+  }
+
+  const requestContracts = getRequestContracts({
+    scopeName: routeMeta.scopeName,
+    schemaInfo,
+    includeDepthLimit: scope?.vars?.includeDepthLimit,
+    sortableFields: scope?.vars?.sortableFields
+  })
+
+  const contract = requestContracts[routeMeta.operation]
+  if (!contract?.schema) {
+    return null
+  }
+
+  return {
+    body: contract.schema.toJsonSchema({ mode: contract.mode, additionalProperties: false })
+  }
+}