velocious 1.0.467 → 1.0.469

package/src/error-reporting/request-details.js

@@ -0,0 +1,308 @@
+// @ts-check
+
+import UploadedFile from "../http-server/client/uploaded-file/uploaded-file.js"
+
+const REQUEST_DETAILS_BODY_MAX_SERIALIZED_LENGTH = 12000
+const REQUEST_DETAILS_STRING_MAX_LENGTH = 1000
+const REQUEST_DETAILS_ARRAY_MAX_ITEMS = 50
+const REDACTED_REQUEST_DETAILS_VALUE = "[redacted]"
+
+/**
+ * Extracts request metadata without retaining the request object.
+ * @param {import("../http-server/client/request.js").default | import("../http-server/client/websocket-request.js").default | undefined} request - Request object, when present.
+ * @returns {import("../configuration-types.js").ErrorRequestDetails | null} - Request metadata.
+ */
+export function requestDetails(request) {
+  if (!request) return null
+
+  let details
+
+  try {
+    details = {
+      httpMethod: request.httpMethod(),
+      path: request.path()
+    }
+  } catch {
+    return null
+  }
+
+  const body = requestBodySnapshot(request)
+
+  if (body !== undefined) {
+    return {...details, body}
+  }
+
+  return details
+}
+
+/**
+ * Snapshots parsed request params for error reports.
+ * @param {import("../http-server/client/request.js").default | import("../http-server/client/websocket-request.js").default} request - Request object.
+ * @returns {? | undefined} - Sanitized body snapshot.
+ */
+function requestBodySnapshot(request) {
+  if (typeof request.params !== "function") return undefined
+
+  try {
+    return requestDetailsBodySnapshot(request.params())
+  } catch (error) {
+    return {
+      __unavailable: true,
+      error: error instanceof Error ? error.message : String(error)
+    }
+  }
+}
+
+/**
+ * Builds a bounded, redacted body snapshot for error reports.
+ * @param {?} body - Parsed request body.
+ * @returns {?} - Sanitized body snapshot.
+ */
+function requestDetailsBodySnapshot(body) {
+  const originalLength = serializedLength(body)
+  const sanitized = sanitizeRequestDetailsValue(body)
+  const sanitizedLength = serializedLength(sanitized)
+
+  if (originalLength <= REQUEST_DETAILS_BODY_MAX_SERIALIZED_LENGTH && sanitizedLength <= REQUEST_DETAILS_BODY_MAX_SERIALIZED_LENGTH) {
+    return sanitized
+  }
+
+  const compactFrontendModelBody = compactFrontendModelRequestBody(sanitized, originalLength)
+
+  if (serializedLength(compactFrontendModelBody) <= REQUEST_DETAILS_BODY_MAX_SERIALIZED_LENGTH) {
+    return compactFrontendModelBody
+  }
+
+  return compactRequestDetailsBody(sanitized, originalLength)
+}
+
+/**
+ * Sanitizes a value recursively for request details.
+ * @param {?} value - Value to sanitize.
+ * @param {string} [key] - Current object key.
+ * @param {WeakSet<object>} [seen] - Seen object references.
+ * @returns {?} - Sanitized value.
+ */
+function sanitizeRequestDetailsValue(value, key = "", seen = new WeakSet()) {
+  if (sensitiveRequestDetailsKey(key)) return REDACTED_REQUEST_DETAILS_VALUE
+  if (primitiveRequestDetailsValue(value)) return value
+  if (bufferValue(value)) return bufferRequestDetailsSummary(value)
+  if (value instanceof UploadedFile) return uploadedFileRequestDetailsSummary(value)
+  if (typeof value === "string") return sanitizeRequestDetailsString(value)
+  if (Array.isArray(value)) return sanitizeRequestDetailsArray(value, seen)
+  if (typeof value === "object") return sanitizeRequestDetailsObject(value, seen)
+
+  return String(value)
+}
+
+/**
+ * Checks whether a value can be kept as-is.
+ * @param {?} value - Value.
+ * @returns {boolean} - Whether the value is primitive and safe.
+ */
+function primitiveRequestDetailsValue(value) {
+  return value == null || typeof value === "boolean" || typeof value === "number"
+}
+
+/**
+ * Sanitizes a string value.
+ * @param {string} value - String value.
+ * @returns {string} - Sanitized string.
+ */
+function sanitizeRequestDetailsString(value) {
+  if (value.length <= REQUEST_DETAILS_STRING_MAX_LENGTH) return value
+
+  return `${value.slice(0, REQUEST_DETAILS_STRING_MAX_LENGTH)}... [truncated ${value.length - REQUEST_DETAILS_STRING_MAX_LENGTH} chars]`
+}
+
+/**
+ * Sanitizes an array value.
+ * @param {Array<?>} value - Array value.
+ * @param {WeakSet<object>} seen - Seen object references.
+ * @returns {Array<?>} - Sanitized array.
+ */
+function sanitizeRequestDetailsArray(value, seen) {
+  const entries = value
+    .slice(0, REQUEST_DETAILS_ARRAY_MAX_ITEMS)
+    .map((entry) => sanitizeRequestDetailsValue(entry, "", seen))
+
+  if (value.length > REQUEST_DETAILS_ARRAY_MAX_ITEMS) {
+    entries.push({__omittedItems: value.length - REQUEST_DETAILS_ARRAY_MAX_ITEMS})
+  }
+
+  return entries
+}
+
+/**
+ * Sanitizes a plain object-like value.
+ * @param {object} value - Object value.
+ * @param {WeakSet<object>} seen - Seen object references.
+ * @returns {Record<string, ?> | string} - Sanitized object or circular marker.
+ */
+function sanitizeRequestDetailsObject(value, seen) {
+  if (seen.has(value)) return "[circular]"
+
+  seen.add(value)
+
+  /** @type {Record<string, ?>} */
+  const sanitized = {}
+
+  for (const [entryKey, entryValue] of Object.entries(value)) {
+    sanitized[entryKey] = sanitizeRequestDetailsValue(entryValue, entryKey, seen)
+  }
+
+  seen.delete(value)
+
+  return sanitized
+}
+
+/**
+ * Checks whether a value is a Node.js Buffer.
+ * @param {?} value - Value.
+ * @returns {value is Buffer} - Whether value is a Buffer.
+ */
+function bufferValue(value) {
+  return typeof Buffer !== "undefined" && typeof Buffer.isBuffer === "function" && Buffer.isBuffer(value)
+}
+
+/**
+ * Summarizes raw binary data without serializing bytes.
+ * @param {Buffer} buffer - Uploaded or request buffer.
+ * @returns {Record<string, ?>} - Request-safe buffer summary.
+ */
+function bufferRequestDetailsSummary(buffer) {
+  return {
+    __redacted: true,
+    __type: "Buffer",
+    byteLength: buffer.byteLength
+  }
+}
+
+/**
+ * Summarizes uploaded files without serializing file bytes or temp paths.
+ * @param {UploadedFile} uploadedFile - Uploaded file object.
+ * @returns {Record<string, ?>} - Request-safe upload summary.
+ */
+function uploadedFileRequestDetailsSummary(uploadedFile) {
+  return {
+    __redacted: true,
+    __type: "UploadedFile",
+    contentType: uploadedFile.contentType() ?? null,
+    fieldName: uploadedFile.fieldName(),
+    filename: uploadedFile.filename(),
+    size: uploadedFile.size()
+  }
+}
+
+/**
+ * Checks whether a key should be redacted from request details.
+ * @param {string} key - Object key.
+ * @returns {boolean} - Whether the value is sensitive.
+ */
+function sensitiveRequestDetailsKey(key) {
+  return /authorization|contentBase64|password|secret|sessionToken|token/i.test(key)
+}
+
+/**
+ * Compacts a frontend-model request envelope while preserving debugging shape.
+ * @param {?} value - Sanitized body value.
+ * @param {number} originalSerializedLength - Byte count before redaction or compaction.
+ * @returns {?} - Compacted body value.
+ */
+function compactFrontendModelRequestBody(value, originalSerializedLength) {
+  if (!value || typeof value !== "object" || !Array.isArray(/** @type {Record<string, ?>} */ (value).requests)) {
+    return compactRequestDetailsBody(value, originalSerializedLength)
+  }
+
+  return {
+    __truncated: true,
+    originalSerializedLength,
+    requests: /** @type {Array<?>} */ (/** @type {Record<string, ?>} */ (value).requests).map((request) => {
+      return compactFrontendModelRequest(request)
+    })
+  }
+}
+
+/**
+ * Compacts one frontend-model request entry.
+ * @param {?} value - Candidate request entry from the transport envelope.
+ * @returns {?} - Compacted request.
+ */
+function compactFrontendModelRequest(value) {
+  if (!value || typeof value !== "object") return value
+
+  const request = /** @type {Record<string, ?>} */ (value)
+  /** @type {Record<string, ?>} */
+  const compact = {}
+
+  for (const key of ["requestId", "model", "commandType", "customPath"]) {
+    if (request[key] !== undefined) compact[key] = request[key]
+  }
+
+  if (request.payload !== undefined) {
+    compact.payload = compactFrontendModelPayload(request.payload)
+  }
+
+  return compact
+}
+
+/**
+ * Compacts a frontend-model payload.
+ * @param {?} value - Candidate payload from a request entry.
+ * @returns {?} - Compacted payload.
+ */
+function compactFrontendModelPayload(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return value
+
+  const payload = /** @type {Record<string, ?>} */ (value)
+  /** @type {Record<string, ?>} */
+  const compact = {}
+
+  for (const [key, entryValue] of Object.entries(payload)) {
+    compact[key] = compactFrontendModelPayloadEntry({key, value: entryValue})
+  }
+
+  return compact
+}
+
+/**
+ * Compacts one frontend-model payload entry.
+ * @param {{key: string, value: ?}} args - Payload entry.
+ * @returns {?} - Compacted value.
+ */
+function compactFrontendModelPayloadEntry({key, value}) {
+  if (key !== "attributes" || !value || typeof value !== "object" || Array.isArray(value)) {
+    return value
+  }
+
+  return {__keys: Object.keys(/** @type {Record<string, ?>} */ (value))}
+}
+
+/**
+ * Builds a last-resort compact body summary.
+ * @param {?} value - Sanitized body.
+ * @param {number} originalSerializedLength - Byte count before redaction or compaction.
+ * @returns {Record<string, ?>} - Compact summary.
+ */
+function compactRequestDetailsBody(value, originalSerializedLength) {
+  return {
+    __truncated: true,
+    originalSerializedLength,
+    topLevelKeys: value && typeof value === "object" && !Array.isArray(value)
+      ? Object.keys(/** @type {Record<string, ?>} */ (value))
+      : []
+  }
+}
+
+/**
+ * Measures JSON serialized length.
+ * @param {?} value - Value to measure.
+ * @returns {number} - Serialized length, or Infinity when not serializable.
+ */
+function serializedLength(value) {
+  try {
+    return JSON.stringify(value).length
+  } catch {
+    return Infinity
+  }
+}

package/src/frontend-model-controller.js

@@ -8,6 +8,7 @@ import {frontendModelResourcesWithBuiltInsForBackendProject} from "./frontend-mo
 import {frontendModelResourceClassFromDefinition, frontendModelResourceConfigurationFromDefinition, frontendModelResourcePath, frontendModelResourcesForBackendProject} from "./frontend-models/resource-definition.js"
 import {FrontendModelQueryError, normalizeGroup as normalizeQueryGroup, normalizeJoins as normalizeQueryJoins, normalizePluck as normalizeQueryPluck, normalizePreload as normalizeQueryPreload, normalizeSearchOperator as normalizeQuerySearchOperator, normalizeSort as normalizeQuerySort} from "./frontend-models/query.js"
 import {assignSafeProperty, deserializeFrontendModelTransportValue, isBackendModelInstance, serializeFrontendModelTransportValue} from "./frontend-models/transport-serialization.js"
+import {requestDetails} from "./error-reporting/request-details.js"
 import RoutesResolver from "./routes/resolver.js"
 import {ValidationError} from "./database/record/index.js"
 import { normalizeDateStringForWrite } from "./database/datetime-storage.js"
@@ -584,6 +585,12 @@ export default class FrontendModelController extends Controller {
    * Frontend model ability override.
    * @type {import("./authorization/ability.js").default | undefined} */
   _frontendModelAbilityOverride = undefined
+  /**
+   * Original deserialized custom-command client payload, captured before route
+   * framework params are merged in, so a typed command method receives the client's
+   * own arguments rather than the route metadata. Only set on the shared-endpoint path.
+   * @type {Record<string, ?> | undefined} */
+  _frontendModelCustomCommandClientArguments = undefined
 
   /**
    * Runs frontend model params.
@@ -3177,7 +3184,8 @@ export default class FrontendModelController extends Controller {
     const errorPayload = {
       context: errorContext,
       error: error instanceof Error ? error : new Error(String(error)),
-      request: this.getRequest()
+      request: this.getRequest(),
+      requestDetails: requestDetails(this.getRequest())
     }
 
     this.getConfiguration().getErrorEvents().emit("framework-error", errorPayload)
@@ -3578,6 +3586,14 @@ export default class FrontendModelController extends Controller {
       viewPath
     })
 
+    // Preserve the client's own command arguments before route framework params won
+    // the `controllerParams` merge above, so a typed command method (`async name(args)`)
+    // receives the client payload — not the route's member id / model / controller keys.
+    const customCommandController = /** @type {FrontendModelController} */ (/** @type {unknown} */ (controllerInstance))
+
+    customCommandController._frontendModelCustomCommandClientArguments =
+      (payload && typeof payload === "object" && !Array.isArray(payload)) ? /** @type {Record<string, ?>} */ (payload) : {}
+
     await this.withFrontendModelRequestContext(controllerParams, response, async () => {
       await controllerInstance._runBeforeCallbacks()
       const controllerMethods = /** @type {Record<string, () => Promise<void> | void>} */ (/** @type {?} */ (controllerInstance))
@@ -3757,7 +3773,13 @@ export default class FrontendModelController extends Controller {
       return this.frontendModelErrorPayload(`Missing frontend-model custom command '${methodName}'.`)
     }
 
-    const responsePayload = await commandMethod.call(resource)
+    // Pass the client command arguments as the method's first argument so a command
+    // method can take a typed args object (`async name(args)`) and the generated
+    // frontend method can forward the backend method's `@param`. `this.params()` is
+    // unchanged, so existing parameterless methods keep working. The args are untrusted
+    // client input typed only by the declared contract, so methods must still validate.
+    const commandArguments = this.frontendModelCustomCommandArguments(params)
+    const responsePayload = await commandMethod.call(resource, commandArguments)
 
     if (!responsePayload || typeof responsePayload !== "object") {
       return {status: "success"}
@@ -3772,6 +3794,32 @@ export default class FrontendModelController extends Controller {
     )
   }
 
+  /**
+   * Resolves the typed argument object passed to a custom command method. On the
+   * shared-endpoint path the original client payload was captured before route
+   * framework params were merged, so it is returned verbatim (a client `id` survives
+   * a member route). On the direct path it falls back to the request params with the
+   * framework keys the command route hook injected stripped out.
+   * @param {Record<string, ?>} params - Deserialized frontend-model params.
+   * @returns {Record<string, ?>} - Client command arguments.
+   */
+  frontendModelCustomCommandArguments(params) {
+    if (this._frontendModelCustomCommandClientArguments) {
+      return this._frontendModelCustomCommandClientArguments
+    }
+
+    const {
+      action: _action,
+      controller: _controller,
+      frontendModelCustomCommandMethodName: _methodName,
+      frontendModelCustomCommandScope: _scope,
+      model: _model,
+      ...commandArguments
+    } = params
+
+    return commandArguments
+  }
+
   /**
    * Walks a custom-command response payload and replaces any backend `Record`
    * instance with the resource's per-action serialized form so handlers can