lambda-deadline-middleware 0.0.0

package/src/registration.ts

@@ -0,0 +1,36 @@
+// SPDX-FileCopyrightText: 2024 lambda-deadline-middleware contributors
+// SPDX-License-Identifier: MIT
+
+import type { Pluggable } from "@smithy/types";
+
+import { parseConfig } from "./config.js";
+import { deadlineMiddlewareHandler } from "./middleware.js";
+import type { DeadlineOptions } from "./types.js";
+
+export function deadlineMiddleware(options?: DeadlineOptions): Pluggable<object, object> {
+  const config = parseConfig(options);
+
+  return {
+    applyToStack(stack) {
+      stack.add(deadlineMiddlewareHandler(config), {
+        step: "finalizeRequest",
+        name: "deadlineMiddleware",
+        override: true,
+      });
+    },
+  };
+}
+
+// WeakSet allows GC of discarded clients in long-running processes
+// while still preventing duplicate middleware registration.
+const registeredClients = new WeakSet<object>();
+
+export function withDeadline<
+  // oxlint-disable-next-line typescript/no-explicit-any -- AWS SDK clients use varying ServiceInput/OutputTypes generics, making `any` the only correct constraint here
+  T extends { middlewareStack: { use: (pluggable: Pluggable<any, any>) => void } },
+>(client: T, options?: DeadlineOptions): T {
+  if (registeredClients.has(client)) return client;
+  registeredClients.add(client);
+  client.middlewareStack.use(deadlineMiddleware(options));
+  return client;
+}

package/src/telemetry.ts

@@ -0,0 +1,129 @@
+// SPDX-FileCopyrightText: 2024 lambda-deadline-middleware contributors
+// SPDX-License-Identifier: MIT
+
+import type { DeadlineExceededError } from "./error.js";
+import type { DeadlineMiddlewareConfig } from "./types.js";
+
+interface AbortDetails {
+  readonly deadlineMs: number;
+  readonly flushBufferMs: number;
+  readonly remainingMs: number;
+}
+
+interface TelemetryEmitter {
+  recordDeadlineAbort: (details: AbortDetails) => void;
+  setDeadlineErrorStatus: (error: DeadlineExceededError) => void;
+}
+
+let emitter: TelemetryEmitter | undefined;
+let detected = false;
+
+async function detectEmitter(): Promise<TelemetryEmitter | undefined> {
+  if (detected) return emitter;
+  detected = true;
+
+  try {
+    // Variable indirection prevents TypeScript from resolving the module
+    // at compile time — keeps @opentelemetry/api as a purely optional runtime dep.
+    const moduleName = "@opentelemetry/api";
+    // oxlint-disable-next-line typescript/no-unsafe-assignment -- dynamic import of optional runtime dependency
+    const otelApi: Record<string, unknown> = await import(/* webpackIgnore: true */ moduleName);
+    // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- duck-typing optional OTel API surface
+    const trace = otelApi["trace"] as { getActiveSpan: () => unknown } | undefined;
+
+    // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- duck-typing optional OTel API surface
+    const SpanStatusCode = otelApi["SpanStatusCode"] as
+      | {
+          ERROR: number;
+        }
+      | undefined;
+
+    if (!trace || !SpanStatusCode) {
+      emitter = undefined;
+      return emitter;
+    }
+
+    emitter = {
+      recordDeadlineAbort(details: AbortDetails): void {
+        try {
+          // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- duck-typing OTel span from untyped getActiveSpan()
+          const span = trace.getActiveSpan() as Record<string, unknown> | undefined;
+          if (!span) return;
+
+          // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- duck-typing OTel span.addEvent method
+          const addEvent = span["addEvent"] as
+            | ((name: string, attributes: Record<string, unknown>) => void)
+            | undefined;
+          if (typeof addEvent !== "function") return;
+
+          addEvent.call(span, "lambda-deadline-middleware.abort", {
+            "deadline.duration_ms": details.deadlineMs,
+            "deadline.flush_buffer_ms": details.flushBufferMs,
+            "deadline.remaining_ms": details.remainingMs,
+          });
+        } catch {
+          // Telemetry must never disrupt request processing
+        }
+      },
+
+      setDeadlineErrorStatus(error: DeadlineExceededError): void {
+        try {
+          // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- duck-typing OTel span from untyped getActiveSpan()
+          const span = trace.getActiveSpan() as Record<string, unknown> | undefined;
+          if (!span) return;
+
+          // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- duck-typing OTel span.setStatus method
+          const setStatus = span["setStatus"] as
+            | ((status: { code: number; message: string }) => void)
+            | undefined;
+          // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- duck-typing OTel span.setAttribute method
+          const setAttribute = span["setAttribute"] as
+            | ((key: string, value: unknown) => void)
+            | undefined;
+
+          if (typeof setStatus === "function") {
+            setStatus.call(span, {
+              code: SpanStatusCode.ERROR,
+              message: error.message,
+            });
+          }
+
+          if (typeof setAttribute === "function") {
+            setAttribute.call(span, "error.type", "DeadlineExceededError");
+            setAttribute.call(span, "deadline.duration_ms", error.deadlineMs);
+            setAttribute.call(span, "deadline.flush_buffer_ms", error.flushBufferMs);
+            setAttribute.call(span, "deadline.remaining_ms", error.remainingMs);
+          }
+        } catch {
+          // Telemetry must never disrupt request processing
+        }
+      },
+    };
+  } catch {
+    emitter = undefined;
+  }
+
+  return emitter;
+}
+
+export async function emitDeadlineAbort(
+  error: DeadlineExceededError,
+  config: DeadlineMiddlewareConfig,
+): Promise<void> {
+  try {
+    if (!config.telemetryEnabled) return;
+
+    const em = await detectEmitter();
+    if (!em) return;
+
+    em.recordDeadlineAbort({
+      deadlineMs: error.deadlineMs,
+      flushBufferMs: error.flushBufferMs,
+      remainingMs: error.remainingMs,
+    });
+
+    em.setDeadlineErrorStatus(error);
+  } catch {
+    // Telemetry must never disrupt request processing
+  }
+}

package/src/types.ts

@@ -0,0 +1,50 @@
+// SPDX-FileCopyrightText: 2024 lambda-deadline-middleware contributors
+// SPDX-License-Identifier: MIT
+
+declare const BrandSymbol: unique symbol;
+
+type Brand<T, B extends string> = T & { readonly [BrandSymbol]: B };
+
+export type Milliseconds = Brand<number, "Milliseconds">;
+
+export type FlushBufferMs = Brand<number, "FlushBufferMs">;
+
+export type RequestDeadlineMs = Brand<number, "RequestDeadlineMs">;
+
+export function milliseconds(value: number): Milliseconds {
+  if (!Number.isFinite(value)) {
+    throw new TypeError(`milliseconds value must be finite, received: ${value}`);
+  }
+  // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- branded type constructor: value is validated above
+  return value as Milliseconds;
+}
+
+export function flushBufferMs(value: number): FlushBufferMs {
+  if (!Number.isFinite(value)) {
+    throw new TypeError(`flushBufferMs value must be finite, received: ${value}`);
+  }
+  if (value < 0) {
+    throw new TypeError(`flushBufferMs must be non-negative, received: ${value}`);
+  }
+  // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- branded type constructor: value is validated above
+  return value as FlushBufferMs;
+}
+
+export type DeadlineComputation =
+  | { readonly kind: "deadline"; readonly value: RequestDeadlineMs }
+  | {
+      readonly kind: "insufficient-time";
+      readonly remaining: Milliseconds;
+      readonly buffer: FlushBufferMs;
+    }
+  | { readonly kind: "no-context" };
+
+export interface DeadlineMiddlewareConfig {
+  readonly flushBufferMs: FlushBufferMs;
+  readonly telemetryEnabled: boolean;
+}
+
+export interface DeadlineOptions {
+  readonly flushBufferMs?: number;
+  readonly telemetryEnabled?: boolean;
+}