@naturalcycles/backend-lib 9.76.0 → 9.77.0

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/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/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.0",
   "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/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/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,