@naturalcycles/backend-lib 9.76.0 → 9.77.1

package/dist/index.d.ts

@@ -18,4 +18,5 @@ export type * from './server/server.model.js';
 export * from './server/serverStatsMiddleware.js';
 export * from './server/serverStatusMiddleware.js';
 export * from './server/simpleRequestLoggerMiddleware.js';
+export * from './server/trace.util.js';
 export * from './util.js';

package/dist/index.js

@@ -17,4 +17,5 @@ export * from './server/safeJsonMiddleware.js';
 export * from './server/serverStatsMiddleware.js';
 export * from './server/serverStatusMiddleware.js';
 export * from './server/simpleRequestLoggerMiddleware.js';
+export * from './server/trace.util.js';
 export * from './util.js';

package/dist/server/genericErrorMiddleware.js

@@ -53,7 +53,8 @@ export function respondWithError(req, res, err) {
     const httpError = _errorLikeToErrorObject(originalError);
     if (!includeErrorStack)
         delete httpError.stack;
-    httpError.data.backendResponseStatusCode ||= 500; // default to 500
+    // http-errors (express itself, its body parsers) carry the status they should be answered with
+    httpError.data.backendResponseStatusCode ||= getHttpErrorStatusCode(originalError) || 500; // default to 500
     _objectAssign(httpError.data, {
         errorId,
         headersSent: headersSent || undefined,
@@ -63,3 +64,18 @@ export function respondWithError(req, res, err) {
         error: httpError,
     });
 }
+/**
+ * Errors created by the `http-errors` package (express itself, body-parser, raw-body, send)
+ * carry the HTTP status they are meant to be answered with: `status` and `statusCode` (always equal),
+ * plus `expose` (whether the message is safe to show to the client).
+ * All three together are the marker: other libraries also put a `statusCode` on their errors
+ * (e.g a gateway's response status), which says nothing about how we should respond.
+ */
+function getHttpErrorStatusCode(err) {
+    const { status, statusCode, expose } = err;
+    if (typeof expose !== 'boolean' || typeof statusCode !== 'number' || status !== statusCode)
+        return;
+    if (!Number.isInteger(statusCode) || statusCode < 400 || statusCode > 599)
+        return;
+    return statusCode;
+}

package/dist/server/logMiddleware.js

@@ -5,6 +5,7 @@ import { _safeJsonStringify } from '@naturalcycles/js-lib/string/safeJsonStringi
 import { _objectAssign } from '@naturalcycles/js-lib/types';
 import { logEntryToString } from '@naturalcycles/nodejs-lib';
 import { dimGrey } from '@naturalcycles/nodejs-lib/colors';
+import { getRequestTraceId } from './trace.util.js';
 const { GOOGLE_CLOUD_PROJECT, GAE_INSTANCE, K_SERVICE, APP_ENV } = process.env;
 const isGAE = !!GAE_INSTANCE;
 const isCloudRun = !!K_SERVICE;
@@ -75,11 +76,11 @@ export function logMiddleware() {
             // gcloud run deploy my-service \
             //   --update-env-vars=GOOGLE_CLOUD_PROJECT=$(gcloud config get-value project)
             if (GOOGLE_CLOUD_PROJECT) {
-                const traceHeader = req.header('x-cloud-trace-context');
-                if (traceHeader) {
-                    const [trace] = traceHeader.split('/');
-                    meta['logging.googleapis.com/trace'] = `projects/${GOOGLE_CLOUD_PROJECT}/traces/${trace}`;
-                    req.requestId = trace;
+                const traceId = getRequestTraceId(req);
+                if (traceId) {
+                    meta['logging.googleapis.com/trace'] =
+                        `projects/${GOOGLE_CLOUD_PROJECT}/traces/${traceId}`;
+                    req.requestId = traceId;
                 }
             }
             if (isGAE) {

package/dist/server/request.util.js

@@ -43,6 +43,6 @@ function buildRequestEndpoint(req, stripPrefix, sanitize) {
 // the exact bytes are not worth preserving here, `req.url` still has them.
 const UNSAFE_PATH_CHAR = /[^\w\-./:@%!$*+,;=~]/gu;
 function sanitizePath(path) {
-    return path.replace(UNSAFE_PATH_CHAR, '_');
+    return path.replaceAll(UNSAFE_PATH_CHAR, '_');
 }
 const identity = (path) => path;

package/dist/server/trace.util.d.ts

@@ -0,0 +1,16 @@
+import type { BackendRequest } from './server.model.js';
+/**
+ * The trace a request belongs to, as carried by the W3C `traceparent` header.
+ */
+export interface TraceContext {
+    traceId: string;
+    spanId: string;
+    sampled: boolean;
+}
+/**
+ * The trace id of the request, from `traceparent`. Cached per request, so it is cheap to call on
+ * every log line.
+ */
+export declare function getRequestTraceId(req: BackendRequest): string | undefined;
+export declare function getRequestTraceContext(req: BackendRequest): TraceContext | undefined;
+export declare function parseTraceparent(header: string | undefined): TraceContext | undefined;

package/dist/server/trace.util.js

@@ -0,0 +1,35 @@
+// https://www.w3.org/TR/trace-context/#traceparent-header
+// Version `ff` is invalid. Higher versions may append `-` fields, which are ignored (forward
+// compatibility), while version `00` must not have any.
+const TRACEPARENT_REGEX = /^(?!ff)([\da-f]{2})-([\da-f]{32})-([\da-f]{16})-([\da-f]{2})(-.*)?$/;
+const INVALID_TRACE_ID = '0'.repeat(32);
+const INVALID_SPAN_ID = '0'.repeat(16);
+const traceIdByRequest = new WeakMap();
+/**
+ * The trace id of the request, from `traceparent`. Cached per request, so it is cheap to call on
+ * every log line.
+ */
+export function getRequestTraceId(req) {
+    let traceId = traceIdByRequest.get(req);
+    if (traceId === undefined) {
+        traceId = getRequestTraceContext(req)?.traceId ?? null;
+        traceIdByRequest.set(req, traceId);
+    }
+    return traceId ?? undefined;
+}
+export function getRequestTraceContext(req) {
+    // Reads from `req.headers` and not `req.header()`, so a bare request object (as in tests) works too
+    const header = req.headers?.['traceparent'];
+    return parseTraceparent(typeof header === 'string' ? header : undefined);
+}
+export function parseTraceparent(header) {
+    const match = header ? TRACEPARENT_REGEX.exec(header) : null;
+    if (!match)
+        return;
+    const [, version, traceId, spanId, flags, extension] = match;
+    if (version === '00' && extension !== undefined)
+        return;
+    if (traceId === INVALID_TRACE_ID || spanId === INVALID_SPAN_ID)
+        return;
+    return { traceId, spanId, sampled: Number.parseInt(flags, 16) % 2 === 1 };
+}

package/dist/upload/getUploadedFiles.js

@@ -75,7 +75,9 @@ async function parseMultipart(req, maxFileSize) {
             stream.on('close', () => {
                 const data = Buffer.concat(chunks);
                 files[name] = {
-                    name: info.filename,
+                    // busboy reports `filename` as undefined for a bare `application/octet-stream` part with
+                    // no filename; normalize to `""`, same as a blank file input (`filename=""`) yields.
+                    name: info.filename ?? '',
                     mimeType: info.mimeType,
                     encoding: info.encoding,
                     data,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@naturalcycles/backend-lib",
   "type": "module",
-  "version": "9.76.0",
+  "version": "9.77.1",
   "dependencies": {
     "@naturalcycles/db-lib": "^10",
     "@naturalcycles/js-lib": "^15",

package/src/index.ts

@@ -18,4 +18,5 @@ export type * from './server/server.model.js'
 export * from './server/serverStatsMiddleware.js'
 export * from './server/serverStatusMiddleware.js'
 export * from './server/simpleRequestLoggerMiddleware.js'
+export * from './server/trace.util.js'
 export * from './util.js'

package/src/server/genericErrorMiddleware.ts

@@ -1,5 +1,6 @@
 import type { BackendErrorResponseObject, ErrorObject } from '@naturalcycles/js-lib/error'
 import { _anyToError, _errorLikeToErrorObject } from '@naturalcycles/js-lib/error'
+import type { HttpStatusCode } from '@naturalcycles/js-lib/http'
 import { _objectAssign } from '@naturalcycles/js-lib/types'
 import type { BackendErrorRequestHandler, BackendRequest, BackendResponse } from './server.model.js'
 
@@ -89,7 +90,8 @@ export function respondWithError(req: BackendRequest, res: BackendResponse, err:
   const httpError = _errorLikeToErrorObject(originalError)
   if (!includeErrorStack) delete httpError.stack
 
-  httpError.data.backendResponseStatusCode ||= 500 // default to 500
+  // http-errors (express itself, its body parsers) carry the status they should be answered with
+  httpError.data.backendResponseStatusCode ||= getHttpErrorStatusCode(originalError) || 500 // default to 500
   _objectAssign(httpError.data, {
     errorId,
     headersSent: headersSent || undefined,
@@ -101,3 +103,23 @@ export function respondWithError(req: BackendRequest, res: BackendResponse, err:
     error: httpError,
   } satisfies BackendErrorResponseObject)
 }
+
+interface HttpErrorLike {
+  status: number
+  statusCode: number
+  expose: boolean
+}
+
+/**
+ * Errors created by the `http-errors` package (express itself, body-parser, raw-body, send)
+ * carry the HTTP status they are meant to be answered with: `status` and `statusCode` (always equal),
+ * plus `expose` (whether the message is safe to show to the client).
+ * All three together are the marker: other libraries also put a `statusCode` on their errors
+ * (e.g a gateway's response status), which says nothing about how we should respond.
+ */
+function getHttpErrorStatusCode(err: Error): HttpStatusCode | undefined {
+  const { status, statusCode, expose } = err as Partial<HttpErrorLike>
+  if (typeof expose !== 'boolean' || typeof statusCode !== 'number' || status !== statusCode) return
+  if (!Number.isInteger(statusCode) || statusCode < 400 || statusCode > 599) return
+  return statusCode
+}

package/src/server/logMiddleware.ts

@@ -8,6 +8,7 @@ import type { AnyObject } from '@naturalcycles/js-lib/types'
 import { logEntryToString } from '@naturalcycles/nodejs-lib'
 import { dimGrey } from '@naturalcycles/nodejs-lib/colors'
 import type { BackendRequestHandler } from './server.model.js'
+import { getRequestTraceId } from './trace.util.js'
 
 const { GOOGLE_CLOUD_PROJECT, GAE_INSTANCE, K_SERVICE, APP_ENV } = process.env
 const isGAE = !!GAE_INSTANCE
@@ -88,11 +89,11 @@ export function logMiddleware(): BackendRequestHandler {
       // gcloud run deploy my-service \
       //   --update-env-vars=GOOGLE_CLOUD_PROJECT=$(gcloud config get-value project)
       if (GOOGLE_CLOUD_PROJECT) {
-        const traceHeader = req.header('x-cloud-trace-context')
-        if (traceHeader) {
-          const [trace] = traceHeader.split('/')
-          meta['logging.googleapis.com/trace'] = `projects/${GOOGLE_CLOUD_PROJECT}/traces/${trace}`
-          req.requestId = trace
+        const traceId = getRequestTraceId(req)
+        if (traceId) {
+          meta['logging.googleapis.com/trace'] =
+            `projects/${GOOGLE_CLOUD_PROJECT}/traces/${traceId}`
+          req.requestId = traceId
         }
       }
       if (isGAE) {

package/src/server/request.util.ts

@@ -55,7 +55,7 @@ function buildRequestEndpoint(
 const UNSAFE_PATH_CHAR = /[^\w\-./:@%!$*+,;=~]/gu
 
 function sanitizePath(path: string): string {
-  return path.replace(UNSAFE_PATH_CHAR, '_')
+  return path.replaceAll(UNSAFE_PATH_CHAR, '_')
 }
 
 const identity = (path: string): string => path

package/src/server/trace.util.ts

@@ -0,0 +1,54 @@
+import type { BackendRequest } from './server.model.js'
+
+/**
+ * The trace a request belongs to, as carried by the W3C `traceparent` header.
+ */
+export interface TraceContext {
+  traceId: string
+  spanId: string
+  sampled: boolean
+}
+
+// https://www.w3.org/TR/trace-context/#traceparent-header
+// Version `ff` is invalid. Higher versions may append `-` fields, which are ignored (forward
+// compatibility), while version `00` must not have any.
+const TRACEPARENT_REGEX = /^(?!ff)([\da-f]{2})-([\da-f]{32})-([\da-f]{16})-([\da-f]{2})(-.*)?$/
+const INVALID_TRACE_ID = '0'.repeat(32)
+const INVALID_SPAN_ID = '0'.repeat(16)
+
+const traceIdByRequest = new WeakMap<BackendRequest, string | null>()
+
+/**
+ * The trace id of the request, from `traceparent`. Cached per request, so it is cheap to call on
+ * every log line.
+ */
+export function getRequestTraceId(req: BackendRequest): string | undefined {
+  let traceId = traceIdByRequest.get(req)
+  if (traceId === undefined) {
+    traceId = getRequestTraceContext(req)?.traceId ?? null
+    traceIdByRequest.set(req, traceId)
+  }
+  return traceId ?? undefined
+}
+
+export function getRequestTraceContext(req: BackendRequest): TraceContext | undefined {
+  // Reads from `req.headers` and not `req.header()`, so a bare request object (as in tests) works too
+  const header = req.headers?.['traceparent']
+  return parseTraceparent(typeof header === 'string' ? header : undefined)
+}
+
+export function parseTraceparent(header: string | undefined): TraceContext | undefined {
+  const match = header ? TRACEPARENT_REGEX.exec(header) : null
+  if (!match) return
+  const [, version, traceId, spanId, flags, extension] = match as unknown as [
+    string,
+    string,
+    string,
+    string,
+    string,
+    string?,
+  ]
+  if (version === '00' && extension !== undefined) return
+  if (traceId === INVALID_TRACE_ID || spanId === INVALID_SPAN_ID) return
+  return { traceId, spanId, sampled: Number.parseInt(flags, 16) % 2 === 1 }
+}

package/src/upload/getUploadedFiles.ts

@@ -102,7 +102,9 @@ async function parseMultipart(
       stream.on('close', () => {
         const data = Buffer.concat(chunks)
         files[name] = {
-          name: info.filename,
+          // busboy reports `filename` as undefined for a bare `application/octet-stream` part with
+          // no filename; normalize to `""`, same as a blank file input (`filename=""`) yields.
+          name: info.filename ?? '',
           mimeType: info.mimeType,
           encoding: info.encoding,
           data,