lambda-deadline-middleware 0.0.0

package/dist/middleware.js

@@ -0,0 +1,76 @@
+// SPDX-FileCopyrightText: 2024 lambda-deadline-middleware contributors
+// SPDX-License-Identifier: MIT
+import { getRemainingTimeInMillis } from "./context-store.js";
+import { DeadlineExceededError } from "./error.js";
+import { milliseconds } from "./types.js";
+export function computeDeadline(config) {
+	const remaining = getRemainingTimeInMillis();
+	if (remaining === undefined) {
+		return { kind: "no-context" };
+	}
+	const deadline = remaining - config.flushBufferMs;
+	if (deadline <= 0) {
+		return {
+			kind: "insufficient-time",
+			remaining: milliseconds(remaining),
+			buffer: config.flushBufferMs
+		};
+	}
+	// oxlint-disable-next-line typescript/no-unsafe-type-assertion -- branded narrowing: deadline is validated > 0 above
+	return {
+		kind: "deadline",
+		value: deadline
+	};
+}
+export function createDeadlineTimer(deadlineMs, config) {
+	const controller = new AbortController();
+	const remaining = milliseconds(deadlineMs + config.flushBufferMs);
+	const error = new DeadlineExceededError({
+		deadlineMs: milliseconds(deadlineMs),
+		flushBufferMs: config.flushBufferMs,
+		remainingMs: remaining
+	});
+	const timeoutId = setTimeout(() => {
+		controller.abort(error);
+	}, deadlineMs);
+	return {
+		controller,
+		[Symbol.dispose]() {
+			clearTimeout(timeoutId);
+		}
+	};
+}
+export function composeSignals(existing, deadline) {
+	if (existing === undefined) return deadline;
+	return AbortSignal.any([existing, deadline]);
+}
+export function deadlineMiddlewareHandler(config) {
+	return (next, _context) => async (args) => {
+		const computation = computeDeadline(config);
+		switch (computation.kind) {
+			case "no-context": return next(args);
+			case "insufficient-time": throw new DeadlineExceededError({
+				deadlineMs: milliseconds(0),
+				flushBufferMs: computation.buffer,
+				remainingMs: computation.remaining
+			});
+			case "deadline": {
+				using timer = createDeadlineTimer(computation.value, config);
+				// oxlint-disable-next-line typescript/no-unsafe-type-assertion -- Smithy request is an opaque object; we access optional signal property
+				const request = args.request;
+				const signal = composeSignals(request?.signal, timer.controller.signal);
+				const result = await next({
+					...args,
+					// oxlint-disable-next-line typescript/no-unsafe-type-assertion -- spreading opaque Smithy request to add signal
+					request: {
+						...args.request,
+						signal
+					}
+				});
+				return result;
+			}
+		}
+	};
+}
+
+//# sourceMappingURL=middleware.js.map

package/dist/middleware.js.map

@@ -0,0 +1 @@
+{"mappings":";;AAGA,SAAS,gCAAgC;AACzC,SAAS,6BAA6B;AAEtC,SAAS,oBAAoB;AAU7B,OAAO,SAAS,gBAAgB,QAAuD;CACrF,MAAM,YAAY,yBAAyB;CAE3C,IAAI,cAAc,WAAW;EAC3B,OAAO,EAAE,MAAM,aAAa;CAC9B;CAEA,MAAM,WAAW,YAAY,OAAO;CAEpC,IAAI,YAAY,GAAG;EACjB,OAAO;GACL,MAAM;GACN,WAAW,aAAa,SAAS;GACjC,QAAQ,OAAO;EACjB;CACF;;CAGA,OAAO;EAAE,MAAM;EAAY,OAAO;CAA8B;AAClE;AAOA,OAAO,SAAS,oBACd,YACA,QACe;CACf,MAAM,aAAa,IAAI,gBAAgB;CACvC,MAAM,YAAY,aAAa,aAAa,OAAO,aAAa;CAChE,MAAM,QAAQ,IAAI,sBAAsB;EACtC,YAAY,aAAa,UAAU;EACnC,eAAe,OAAO;EACtB,aAAa;CACf,CAAC;CACD,MAAM,YAAY,iBAAiB;EACjC,WAAW,MAAM,KAAK;CACxB,GAAG,UAAU;CACb,OAAO;EACL;EACA,CAAC,OAAO,WAAW;GACjB,aAAa,SAAS;EACxB;CACF;AACF;AAEA,OAAO,SAAS,eACd,UACA,UACa;CACb,IAAI,aAAa,WAAW,OAAO;CACnC,OAAO,YAAY,IAAI,CAAC,UAAU,QAAQ,CAAC;AAC7C;AAEA,OAAO,SAAS,0BACd,QAC2C;CAC3C,QACE,MACA,aAGA,OAAO,SAAmF;EACxF,MAAM,cAAc,gBAAgB,MAAM;EAE1C,QAAQ,YAAY,MAApB;GACE,KAAK,cACH,OAAO,KAAK,IAAI;GAElB,KAAK,qBACH,MAAM,IAAI,sBAAsB;IAC9B,YAAY,aAAa,CAAC;IAC1B,eAAe,YAAY;IAC3B,aAAa,YAAY;GAC3B,CAAC;GAEH,KAAK,YAAY;IACf,MAAM,QAAQ,oBAAoB,YAAY,OAAO,MAAM;;IAE3D,MAAM,UAAU,KAAK;IACrB,MAAM,SAAS,eAAe,SAAS,QAAQ,MAAM,WAAW,MAAM;IACtE,MAAM,SAAS,MAAM,KAAK;KACxB,GAAG;;KAEH,SAAS;MAAE,GAAI,KAAK;MAAoB;KAAO;IACjD,CAAC;IACD,OAAO;GACT;EACF;CACF;AACJ","names":[],"sources":["src/middleware.ts"],"version":3,"sourcesContent":["// SPDX-FileCopyrightText: 2024 lambda-deadline-middleware contributors\n// SPDX-License-Identifier: MIT\n\nimport { getRemainingTimeInMillis } from \"./context-store.js\";\nimport { DeadlineExceededError } from \"./error.js\";\nimport type { DeadlineComputation, DeadlineMiddlewareConfig, RequestDeadlineMs } from \"./types.js\";\nimport { milliseconds } from \"./types.js\";\n\nimport type {\n  FinalizeHandler,\n  FinalizeHandlerArguments,\n  FinalizeHandlerOutput,\n  FinalizeRequestMiddleware,\n  HandlerExecutionContext,\n} from \"@smithy/types\";\n\nexport function computeDeadline(config: DeadlineMiddlewareConfig): DeadlineComputation {\n  const remaining = getRemainingTimeInMillis();\n\n  if (remaining === undefined) {\n    return { kind: \"no-context\" };\n  }\n\n  const deadline = remaining - config.flushBufferMs;\n\n  if (deadline <= 0) {\n    return {\n      kind: \"insufficient-time\",\n      remaining: milliseconds(remaining),\n      buffer: config.flushBufferMs,\n    };\n  }\n\n  // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- branded narrowing: deadline is validated > 0 above\n  return { kind: \"deadline\", value: deadline as RequestDeadlineMs };\n}\n\nexport interface DeadlineTimer {\n  readonly controller: AbortController;\n  [Symbol.dispose]: () => void;\n}\n\nexport function createDeadlineTimer(\n  deadlineMs: RequestDeadlineMs,\n  config: DeadlineMiddlewareConfig,\n): DeadlineTimer {\n  const controller = new AbortController();\n  const remaining = milliseconds(deadlineMs + config.flushBufferMs);\n  const error = new DeadlineExceededError({\n    deadlineMs: milliseconds(deadlineMs),\n    flushBufferMs: config.flushBufferMs,\n    remainingMs: remaining,\n  });\n  const timeoutId = setTimeout(() => {\n    controller.abort(error);\n  }, deadlineMs);\n  return {\n    controller,\n    [Symbol.dispose]() {\n      clearTimeout(timeoutId);\n    },\n  };\n}\n\nexport function composeSignals(\n  existing: AbortSignal | undefined,\n  deadline: AbortSignal,\n): AbortSignal {\n  if (existing === undefined) return deadline;\n  return AbortSignal.any([existing, deadline]);\n}\n\nexport function deadlineMiddlewareHandler(\n  config: DeadlineMiddlewareConfig,\n): FinalizeRequestMiddleware<object, object> {\n  return (\n    next: FinalizeHandler<object, object>,\n    _context: HandlerExecutionContext,\n  ): FinalizeHandler<object, object> =>\n    // oxlint-disable-next-line typescript/consistent-return -- switch is exhaustive over DeadlineComputation discriminated union\n    async (args: FinalizeHandlerArguments<object>): Promise<FinalizeHandlerOutput<object>> => {\n      const computation = computeDeadline(config);\n\n      switch (computation.kind) {\n        case \"no-context\":\n          return next(args);\n\n        case \"insufficient-time\":\n          throw new DeadlineExceededError({\n            deadlineMs: milliseconds(0),\n            flushBufferMs: computation.buffer,\n            remainingMs: computation.remaining,\n          });\n\n        case \"deadline\": {\n          using timer = createDeadlineTimer(computation.value, config);\n          // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- Smithy request is an opaque object; we access optional signal property\n          const request = args.request as { signal?: AbortSignal } | undefined;\n          const signal = composeSignals(request?.signal, timer.controller.signal);\n          const result = await next({\n            ...args,\n            // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- spreading opaque Smithy request to add signal\n            request: { ...(args.request as object), signal },\n          });\n          return result;\n        }\n      }\n    };\n}\n"]}

package/dist/registration.d.ts

@@ -0,0 +1,10 @@
+import type { Pluggable } from "@smithy/types";
+import type { DeadlineOptions } from "./types.js";
+export declare function deadlineMiddleware(options?: DeadlineOptions): Pluggable<object, object>;
+export declare function withDeadline<T extends {
+	middlewareStack: {
+		use: (pluggable: Pluggable<any, any>) => void;
+	};
+}>(client: T, options?: DeadlineOptions): T;
+
+//# sourceMappingURL=registration.d.ts.map

package/dist/registration.d.ts.map

@@ -0,0 +1 @@
+{"mappings":"AAGA,cAAc,iBAAiB;AAI/B,cAAc,uBAAuB;AAErC,OAAO,iBAAS,mBAAmB,UAAU,kBAAkB;AAkB/D,OAAO,iBAAS,aAEd,UAAU;CAAE,iBAAiB;EAAE,MAAM,WAAW;CAA6B;AAAE,GAC/E,QAAQ,GAAG,UAAU,kBAAkB","names":[],"sources":["src/registration.ts"],"version":3,"sourcesContent":["// SPDX-FileCopyrightText: 2024 lambda-deadline-middleware contributors\n// SPDX-License-Identifier: MIT\n\nimport type { Pluggable } from \"@smithy/types\";\n\nimport { parseConfig } from \"./config.js\";\nimport { deadlineMiddlewareHandler } from \"./middleware.js\";\nimport type { DeadlineOptions } from \"./types.js\";\n\nexport function deadlineMiddleware(options?: DeadlineOptions): Pluggable<object, object> {\n  const config = parseConfig(options);\n\n  return {\n    applyToStack(stack) {\n      stack.add(deadlineMiddlewareHandler(config), {\n        step: \"finalizeRequest\",\n        name: \"deadlineMiddleware\",\n        override: true,\n      });\n    },\n  };\n}\n\n// WeakSet allows GC of discarded clients in long-running processes\n// while still preventing duplicate middleware registration.\nconst registeredClients = new WeakSet<object>();\n\nexport function withDeadline<\n  // oxlint-disable-next-line typescript/no-explicit-any -- AWS SDK clients use varying ServiceInput/OutputTypes generics, making `any` the only correct constraint here\n  T extends { middlewareStack: { use: (pluggable: Pluggable<any, any>) => void } },\n>(client: T, options?: DeadlineOptions): T {\n  if (registeredClients.has(client)) return client;\n  registeredClients.add(client);\n  client.middlewareStack.use(deadlineMiddleware(options));\n  return client;\n}\n"]}

package/dist/registration.js

@@ -0,0 +1,23 @@
+import { parseConfig } from "./config.js";
+import { deadlineMiddlewareHandler } from "./middleware.js";
+export function deadlineMiddleware(options) {
+	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();
+export function withDeadline(client, options) {
+	if (registeredClients.has(client)) return client;
+	registeredClients.add(client);
+	client.middlewareStack.use(deadlineMiddleware(options));
+	return client;
+}
+
+//# sourceMappingURL=registration.js.map

package/dist/registration.js.map

@@ -0,0 +1 @@
+{"mappings":"AAKA,SAAS,mBAAmB;AAC5B,SAAS,iCAAiC;AAG1C,OAAO,SAAS,mBAAmB,SAAsD;CACvF,MAAM,SAAS,YAAY,OAAO;CAElC,OAAO,EACL,aAAa,OAAO;EAClB,MAAM,IAAI,0BAA0B,MAAM,GAAG;GAC3C,MAAM;GACN,MAAM;GACN,UAAU;EACZ,CAAC;CACH,EACF;AACF;;;AAIA,MAAM,oBAAoB,IAAI,QAAgB;AAE9C,OAAO,SAAS,aAGd,QAAW,SAA8B;CACzC,IAAI,kBAAkB,IAAI,MAAM,GAAG,OAAO;CAC1C,kBAAkB,IAAI,MAAM;CAC5B,OAAO,gBAAgB,IAAI,mBAAmB,OAAO,CAAC;CACtD,OAAO;AACT","names":[],"sources":["src/registration.ts"],"version":3,"sourcesContent":["// SPDX-FileCopyrightText: 2024 lambda-deadline-middleware contributors\n// SPDX-License-Identifier: MIT\n\nimport type { Pluggable } from \"@smithy/types\";\n\nimport { parseConfig } from \"./config.js\";\nimport { deadlineMiddlewareHandler } from \"./middleware.js\";\nimport type { DeadlineOptions } from \"./types.js\";\n\nexport function deadlineMiddleware(options?: DeadlineOptions): Pluggable<object, object> {\n  const config = parseConfig(options);\n\n  return {\n    applyToStack(stack) {\n      stack.add(deadlineMiddlewareHandler(config), {\n        step: \"finalizeRequest\",\n        name: \"deadlineMiddleware\",\n        override: true,\n      });\n    },\n  };\n}\n\n// WeakSet allows GC of discarded clients in long-running processes\n// while still preventing duplicate middleware registration.\nconst registeredClients = new WeakSet<object>();\n\nexport function withDeadline<\n  // oxlint-disable-next-line typescript/no-explicit-any -- AWS SDK clients use varying ServiceInput/OutputTypes generics, making `any` the only correct constraint here\n  T extends { middlewareStack: { use: (pluggable: Pluggable<any, any>) => void } },\n>(client: T, options?: DeadlineOptions): T {\n  if (registeredClients.has(client)) return client;\n  registeredClients.add(client);\n  client.middlewareStack.use(deadlineMiddleware(options));\n  return client;\n}\n"]}

package/dist/telemetry.d.ts

@@ -0,0 +1,5 @@
+import type { DeadlineExceededError } from "./error.js";
+import type { DeadlineMiddlewareConfig } from "./types.js";
+export declare function emitDeadlineAbort(error: DeadlineExceededError, config: DeadlineMiddlewareConfig): Promise<void>;
+
+//# sourceMappingURL=telemetry.d.ts.map

package/dist/telemetry.d.ts.map

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

package/dist/telemetry.js

@@ -0,0 +1,82 @@
+let emitter;
+let detected = false;
+async function detectEmitter() {
+	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 = await import(
+			/* webpackIgnore: true */
+			moduleName
+);
+		// oxlint-disable-next-line typescript/no-unsafe-type-assertion -- duck-typing optional OTel API surface
+		const trace = otelApi["trace"];
+		// oxlint-disable-next-line typescript/no-unsafe-type-assertion -- duck-typing optional OTel API surface
+		const SpanStatusCode = otelApi["SpanStatusCode"];
+		if (!trace || !SpanStatusCode) {
+			emitter = undefined;
+			return emitter;
+		}
+		emitter = {
+			recordDeadlineAbort(details) {
+				try {
+					// oxlint-disable-next-line typescript/no-unsafe-type-assertion -- duck-typing OTel span from untyped getActiveSpan()
+					const span = trace.getActiveSpan();
+					if (!span) return;
+					// oxlint-disable-next-line typescript/no-unsafe-type-assertion -- duck-typing OTel span.addEvent method
+					const addEvent = span["addEvent"];
+					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 {}
+			},
+			setDeadlineErrorStatus(error) {
+				try {
+					// oxlint-disable-next-line typescript/no-unsafe-type-assertion -- duck-typing OTel span from untyped getActiveSpan()
+					const span = trace.getActiveSpan();
+					if (!span) return;
+					// oxlint-disable-next-line typescript/no-unsafe-type-assertion -- duck-typing OTel span.setStatus method
+					const setStatus = span["setStatus"];
+					// oxlint-disable-next-line typescript/no-unsafe-type-assertion -- duck-typing OTel span.setAttribute method
+					const setAttribute = span["setAttribute"];
+					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 {}
+			}
+		};
+	} catch {
+		emitter = undefined;
+	}
+	return emitter;
+}
+export async function emitDeadlineAbort(error, config) {
+	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 {}
+}
+
+//# sourceMappingURL=telemetry.js.map

package/dist/telemetry.js.map

@@ -0,0 +1 @@
+{"mappings":"AAiBA,IAAI;AACJ,IAAI,WAAW;AAEf,eAAe,gBAAuD;CACpE,IAAI,UAAU,OAAO;CACrB,WAAW;CAEX,IAAI;;;EAGF,MAAM,aAAa;;EAEnB,MAAM,UAAmC,MAAM;;GAAiC;;;EAEhF,MAAM,QAAQ,QAAQ;;EAGtB,MAAM,iBAAiB,QAAQ;EAM/B,IAAI,CAAC,SAAS,CAAC,gBAAgB;GAC7B,UAAU;GACV,OAAO;EACT;EAEA,UAAU;GACR,oBAAoB,SAA6B;IAC/C,IAAI;;KAEF,MAAM,OAAO,MAAM,cAAc;KACjC,IAAI,CAAC,MAAM;;KAGX,MAAM,WAAW,KAAK;KAGtB,IAAI,OAAO,aAAa,YAAY;KAEpC,SAAS,KAAK,MAAM,oCAAoC;MACtD,wBAAwB,QAAQ;MAChC,4BAA4B,QAAQ;MACpC,yBAAyB,QAAQ;KACnC,CAAC;IACH,QAAQ,CAER;GACF;GAEA,uBAAuB,OAAoC;IACzD,IAAI;;KAEF,MAAM,OAAO,MAAM,cAAc;KACjC,IAAI,CAAC,MAAM;;KAGX,MAAM,YAAY,KAAK;;KAIvB,MAAM,eAAe,KAAK;KAI1B,IAAI,OAAO,cAAc,YAAY;MACnC,UAAU,KAAK,MAAM;OACnB,MAAM,eAAe;OACrB,SAAS,MAAM;MACjB,CAAC;KACH;KAEA,IAAI,OAAO,iBAAiB,YAAY;MACtC,aAAa,KAAK,MAAM,cAAc,uBAAuB;MAC7D,aAAa,KAAK,MAAM,wBAAwB,MAAM,UAAU;MAChE,aAAa,KAAK,MAAM,4BAA4B,MAAM,aAAa;MACvE,aAAa,KAAK,MAAM,yBAAyB,MAAM,WAAW;KACpE;IACF,QAAQ,CAER;GACF;EACF;CACF,QAAQ;EACN,UAAU;CACZ;CAEA,OAAO;AACT;AAEA,OAAO,eAAe,kBACpB,OACA,QACe;CACf,IAAI;EACF,IAAI,CAAC,OAAO,kBAAkB;EAE9B,MAAM,KAAK,MAAM,cAAc;EAC/B,IAAI,CAAC,IAAI;EAET,GAAG,oBAAoB;GACrB,YAAY,MAAM;GAClB,eAAe,MAAM;GACrB,aAAa,MAAM;EACrB,CAAC;EAED,GAAG,uBAAuB,KAAK;CACjC,QAAQ,CAER;AACF","names":[],"sources":["src/telemetry.ts"],"version":3,"sourcesContent":["// SPDX-FileCopyrightText: 2024 lambda-deadline-middleware contributors\n// SPDX-License-Identifier: MIT\n\nimport type { DeadlineExceededError } from \"./error.js\";\nimport type { DeadlineMiddlewareConfig } from \"./types.js\";\n\ninterface AbortDetails {\n  readonly deadlineMs: number;\n  readonly flushBufferMs: number;\n  readonly remainingMs: number;\n}\n\ninterface TelemetryEmitter {\n  recordDeadlineAbort: (details: AbortDetails) => void;\n  setDeadlineErrorStatus: (error: DeadlineExceededError) => void;\n}\n\nlet emitter: TelemetryEmitter | undefined;\nlet detected = false;\n\nasync function detectEmitter(): Promise<TelemetryEmitter | undefined> {\n  if (detected) return emitter;\n  detected = true;\n\n  try {\n    // Variable indirection prevents TypeScript from resolving the module\n    // at compile time — keeps @opentelemetry/api as a purely optional runtime dep.\n    const moduleName = \"@opentelemetry/api\";\n    // oxlint-disable-next-line typescript/no-unsafe-assignment -- dynamic import of optional runtime dependency\n    const otelApi: Record<string, unknown> = await import(/* webpackIgnore: true */ moduleName);\n    // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- duck-typing optional OTel API surface\n    const trace = otelApi[\"trace\"] as { getActiveSpan: () => unknown } | undefined;\n\n    // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- duck-typing optional OTel API surface\n    const SpanStatusCode = otelApi[\"SpanStatusCode\"] as\n      | {\n          ERROR: number;\n        }\n      | undefined;\n\n    if (!trace || !SpanStatusCode) {\n      emitter = undefined;\n      return emitter;\n    }\n\n    emitter = {\n      recordDeadlineAbort(details: AbortDetails): void {\n        try {\n          // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- duck-typing OTel span from untyped getActiveSpan()\n          const span = trace.getActiveSpan() as Record<string, unknown> | undefined;\n          if (!span) return;\n\n          // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- duck-typing OTel span.addEvent method\n          const addEvent = span[\"addEvent\"] as\n            | ((name: string, attributes: Record<string, unknown>) => void)\n            | undefined;\n          if (typeof addEvent !== \"function\") return;\n\n          addEvent.call(span, \"lambda-deadline-middleware.abort\", {\n            \"deadline.duration_ms\": details.deadlineMs,\n            \"deadline.flush_buffer_ms\": details.flushBufferMs,\n            \"deadline.remaining_ms\": details.remainingMs,\n          });\n        } catch {\n          // Telemetry must never disrupt request processing\n        }\n      },\n\n      setDeadlineErrorStatus(error: DeadlineExceededError): void {\n        try {\n          // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- duck-typing OTel span from untyped getActiveSpan()\n          const span = trace.getActiveSpan() as Record<string, unknown> | undefined;\n          if (!span) return;\n\n          // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- duck-typing OTel span.setStatus method\n          const setStatus = span[\"setStatus\"] as\n            | ((status: { code: number; message: string }) => void)\n            | undefined;\n          // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- duck-typing OTel span.setAttribute method\n          const setAttribute = span[\"setAttribute\"] as\n            | ((key: string, value: unknown) => void)\n            | undefined;\n\n          if (typeof setStatus === \"function\") {\n            setStatus.call(span, {\n              code: SpanStatusCode.ERROR,\n              message: error.message,\n            });\n          }\n\n          if (typeof setAttribute === \"function\") {\n            setAttribute.call(span, \"error.type\", \"DeadlineExceededError\");\n            setAttribute.call(span, \"deadline.duration_ms\", error.deadlineMs);\n            setAttribute.call(span, \"deadline.flush_buffer_ms\", error.flushBufferMs);\n            setAttribute.call(span, \"deadline.remaining_ms\", error.remainingMs);\n          }\n        } catch {\n          // Telemetry must never disrupt request processing\n        }\n      },\n    };\n  } catch {\n    emitter = undefined;\n  }\n\n  return emitter;\n}\n\nexport async function emitDeadlineAbort(\n  error: DeadlineExceededError,\n  config: DeadlineMiddlewareConfig,\n): Promise<void> {\n  try {\n    if (!config.telemetryEnabled) return;\n\n    const em = await detectEmitter();\n    if (!em) return;\n\n    em.recordDeadlineAbort({\n      deadlineMs: error.deadlineMs,\n      flushBufferMs: error.flushBufferMs,\n      remainingMs: error.remainingMs,\n    });\n\n    em.setDeadlineErrorStatus(error);\n  } catch {\n    // Telemetry must never disrupt request processing\n  }\n}\n"]}

package/dist/types.d.ts

@@ -0,0 +1,33 @@
+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 declare function milliseconds(value: number): Milliseconds;
+export declare function flushBufferMs(value: number): 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;
+}
+export {};
+
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"mappings":"AAGA,cAAc;KAET;CAAM;CAAG;IAAoB,IAAI;WAAY,cAAc;AAAE;AAElE,YAAY,eAAe,cAAc;AAEzC,YAAY,gBAAgB,cAAc;AAE1C,YAAY,oBAAoB,cAAc;AAE9C,OAAO,iBAAS,aAAa,gBAAgB;AAQ7C,OAAO,iBAAS,cAAc,gBAAgB;AAW9C,YAAY,sBACR;UAAW,MAAM;UAAqB,OAAO;AAAkB,IAC/D;UACW,MAAM;UACN,WAAW;UACX,QAAQ;AACnB,IACA;UAAW,MAAM;AAAa;AAElC,iBAAiB,yBAAyB;UAC/B,eAAe;UACf;AACX;AAEA,iBAAiB,gBAAgB;UACtB;UACA;AACX","names":[],"sources":["src/types.ts"],"version":3,"sourcesContent":["// SPDX-FileCopyrightText: 2024 lambda-deadline-middleware contributors\n// SPDX-License-Identifier: MIT\n\ndeclare const BrandSymbol: unique symbol;\n\ntype Brand<T, B extends string> = T & { readonly [BrandSymbol]: B };\n\nexport type Milliseconds = Brand<number, \"Milliseconds\">;\n\nexport type FlushBufferMs = Brand<number, \"FlushBufferMs\">;\n\nexport type RequestDeadlineMs = Brand<number, \"RequestDeadlineMs\">;\n\nexport function milliseconds(value: number): Milliseconds {\n  if (!Number.isFinite(value)) {\n    throw new TypeError(`milliseconds value must be finite, received: ${value}`);\n  }\n  // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- branded type constructor: value is validated above\n  return value as Milliseconds;\n}\n\nexport function flushBufferMs(value: number): FlushBufferMs {\n  if (!Number.isFinite(value)) {\n    throw new TypeError(`flushBufferMs value must be finite, received: ${value}`);\n  }\n  if (value < 0) {\n    throw new TypeError(`flushBufferMs must be non-negative, received: ${value}`);\n  }\n  // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- branded type constructor: value is validated above\n  return value as FlushBufferMs;\n}\n\nexport type DeadlineComputation =\n  | { readonly kind: \"deadline\"; readonly value: RequestDeadlineMs }\n  | {\n      readonly kind: \"insufficient-time\";\n      readonly remaining: Milliseconds;\n      readonly buffer: FlushBufferMs;\n    }\n  | { readonly kind: \"no-context\" };\n\nexport interface DeadlineMiddlewareConfig {\n  readonly flushBufferMs: FlushBufferMs;\n  readonly telemetryEnabled: boolean;\n}\n\nexport interface DeadlineOptions {\n  readonly flushBufferMs?: number;\n  readonly telemetryEnabled?: boolean;\n}\n"]}

package/dist/types.js

@@ -0,0 +1,19 @@
+export function milliseconds(value) {
+	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;
+}
+export function flushBufferMs(value) {
+	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;
+}
+
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"mappings":"AAaA,OAAO,SAAS,aAAa,OAA6B;CACxD,IAAI,CAAC,OAAO,SAAS,KAAK,GAAG;EAC3B,MAAM,IAAI,UAAU,gDAAgD,OAAO;CAC7E;;CAEA,OAAO;AACT;AAEA,OAAO,SAAS,cAAc,OAA8B;CAC1D,IAAI,CAAC,OAAO,SAAS,KAAK,GAAG;EAC3B,MAAM,IAAI,UAAU,iDAAiD,OAAO;CAC9E;CACA,IAAI,QAAQ,GAAG;EACb,MAAM,IAAI,UAAU,iDAAiD,OAAO;CAC9E;;CAEA,OAAO;AACT","names":[],"sources":["src/types.ts"],"version":3,"sourcesContent":["// SPDX-FileCopyrightText: 2024 lambda-deadline-middleware contributors\n// SPDX-License-Identifier: MIT\n\ndeclare const BrandSymbol: unique symbol;\n\ntype Brand<T, B extends string> = T & { readonly [BrandSymbol]: B };\n\nexport type Milliseconds = Brand<number, \"Milliseconds\">;\n\nexport type FlushBufferMs = Brand<number, \"FlushBufferMs\">;\n\nexport type RequestDeadlineMs = Brand<number, \"RequestDeadlineMs\">;\n\nexport function milliseconds(value: number): Milliseconds {\n  if (!Number.isFinite(value)) {\n    throw new TypeError(`milliseconds value must be finite, received: ${value}`);\n  }\n  // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- branded type constructor: value is validated above\n  return value as Milliseconds;\n}\n\nexport function flushBufferMs(value: number): FlushBufferMs {\n  if (!Number.isFinite(value)) {\n    throw new TypeError(`flushBufferMs value must be finite, received: ${value}`);\n  }\n  if (value < 0) {\n    throw new TypeError(`flushBufferMs must be non-negative, received: ${value}`);\n  }\n  // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- branded type constructor: value is validated above\n  return value as FlushBufferMs;\n}\n\nexport type DeadlineComputation =\n  | { readonly kind: \"deadline\"; readonly value: RequestDeadlineMs }\n  | {\n      readonly kind: \"insufficient-time\";\n      readonly remaining: Milliseconds;\n      readonly buffer: FlushBufferMs;\n    }\n  | { readonly kind: \"no-context\" };\n\nexport interface DeadlineMiddlewareConfig {\n  readonly flushBufferMs: FlushBufferMs;\n  readonly telemetryEnabled: boolean;\n}\n\nexport interface DeadlineOptions {\n  readonly flushBufferMs?: number;\n  readonly telemetryEnabled?: boolean;\n}\n"]}

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "lambda-deadline-middleware",
+  "version": "0.0.0",
+  "description": "AWS SDK v3 middleware for automatic Lambda deadline propagation via AbortController-based timeouts",
+  "license": "MIT",
+  "files": [
+    "dist",
+    "src",
+    "LICENSE",
+    "SECURITY.md"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "devDependencies": {
+    "@aws-sdk/client-dynamodb": "^3.1062.0",
+    "@aws-sdk/client-s3": "^3.1062.0",
+    "@aws-sdk/client-sqs": "^3.1062.0",
+    "@commitlint/cli": "^21.0.2",
+    "@commitlint/config-conventional": "^21.0.2",
+    "@fast-check/vitest": "^0.4.1",
+    "@semantic-release/changelog": "6.0.3",
+    "@semantic-release/commit-analyzer": "13.0.1",
+    "@semantic-release/git": "10.0.1",
+    "@semantic-release/github": "12.0.8",
+    "@semantic-release/npm": "13.1.5",
+    "@semantic-release/release-notes-generator": "14.1.1",
+    "@smithy/types": "^4.14.3",
+    "@types/node": "^25.9.1",
+    "@vitest/coverage-v8": "^4.1.8",
+    "conventional-changelog-conventionalcommits": "^9.3.1",
+    "knip": "^6.15.0",
+    "lefthook": "^2.1.9",
+    "oxc-transform": "^0.134.0",
+    "oxfmt": "^0.53.0",
+    "oxlint": "^1.68.0",
+    "oxlint-tsgolint": "^0.23.0",
+    "semantic-release": "25.0.3",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.8"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "scripts": {
+    "build": "node --experimental-strip-types scripts/build.ts",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "bench": "vitest bench --run --outputJson=bench-results.json && node --experimental-strip-types scripts/validate-bench.ts",
+    "typecheck": "tsc",
+    "lint": "oxlint --type-aware --type-check --fix .",
+    "lint:check": "oxlint --type-aware --type-check .",
+    "fmt": "oxfmt .",
+    "fmt:check": "oxfmt --check .",
+    "lint:knip": "knip",
+    "sast": "scripts/ensure-opengrep.sh scan .",
+    "sast:check": "scripts/ensure-opengrep.sh scan --error .",
+    "sca": "podman run --rm -v \"$(pwd):/src:Z\" ghcr.io/aquasecurity/trivy:0.71.0@sha256:016eae51fdcf989332a5404af7e8f625cd5d95d7c0907a221d080a996f556500 fs --scanners vuln --include-dev-deps --exit-code 1 --severity HIGH,CRITICAL /src",
+    "sca:full": "podman run --rm -v \"$(pwd):/src:Z\" ghcr.io/aquasecurity/trivy:0.71.0@sha256:016eae51fdcf989332a5404af7e8f625cd5d95d7c0907a221d080a996f556500 fs --scanners vuln,secret,misconfig --include-dev-deps /src",
+    "actionlint": "podman run --rm -w /repo -v \"$(pwd):/repo:Z\" docker.io/rhysd/actionlint:1.7.12@sha256:9d36088643581e728c969f35141f88139fec77280b2be23c1f66f8e40e1025e7",
+    "security": "pnpm run sast:check && pnpm run sca && pnpm run actionlint",
+    "sbom": "pnpm sbom --sbom-format cyclonedx --sbom-spec-version 1.5 --sbom-type library > sbom.cdx.json",
+    "release": "semantic-release"
+  }
+}

package/src/config.ts

@@ -0,0 +1,16 @@
+// SPDX-FileCopyrightText: 2024 lambda-deadline-middleware contributors
+// SPDX-License-Identifier: MIT
+
+import { flushBufferMs } from "./types.js";
+import type { DeadlineMiddlewareConfig, DeadlineOptions } from "./types.js";
+
+export function parseConfig(raw: DeadlineOptions | undefined): DeadlineMiddlewareConfig {
+  const buffer = raw?.flushBufferMs ?? 1000;
+  if (buffer < 0) {
+    throw new TypeError(`flushBufferMs option must be non-negative, received: ${buffer}`);
+  }
+  return {
+    flushBufferMs: flushBufferMs(buffer),
+    telemetryEnabled: raw?.telemetryEnabled ?? true,
+  };
+}

package/src/context-store.ts

@@ -0,0 +1,36 @@
+// SPDX-FileCopyrightText: 2024 lambda-deadline-middleware contributors
+// SPDX-License-Identifier: MIT
+
+import { AsyncLocalStorage } from "node:async_hooks";
+
+export interface LambdaContextLike {
+  getRemainingTimeInMillis?: () => number;
+}
+
+// Sentinel allows AsyncLocalStorage.run() to accept null/undefined context
+// without throwing, while the accessor can distinguish "no context stored"
+// from "context present but missing the method".
+const NO_CONTEXT: unique symbol = Symbol("no-context");
+
+type StoreValue = LambdaContextLike | typeof NO_CONTEXT;
+
+const contextStorage = new AsyncLocalStorage<StoreValue>();
+
+export function run<T>(context: LambdaContextLike | null | undefined, fn: () => T): T {
+  const value: StoreValue = context ?? NO_CONTEXT;
+  return contextStorage.run(value, fn);
+}
+
+export function getRemainingTimeInMillis(): number | undefined {
+  const store = contextStorage.getStore();
+
+  if (store === undefined || store === NO_CONTEXT) {
+    return undefined;
+  }
+
+  if (typeof store.getRemainingTimeInMillis !== "function") {
+    return undefined;
+  }
+
+  return store.getRemainingTimeInMillis();
+}

package/src/error.ts

@@ -0,0 +1,34 @@
+// SPDX-FileCopyrightText: 2024 lambda-deadline-middleware contributors
+// SPDX-License-Identifier: MIT
+
+import type { FlushBufferMs, Milliseconds } from "./types.js";
+
+interface DeadlineExceededInit {
+  readonly deadlineMs: Milliseconds;
+  readonly flushBufferMs: FlushBufferMs;
+  readonly remainingMs: Milliseconds;
+}
+
+export class DeadlineExceededError extends Error {
+  override readonly name = "DeadlineExceededError" as const;
+  readonly deadlineMs: Milliseconds;
+  readonly flushBufferMs: FlushBufferMs;
+  readonly remainingMs: Milliseconds;
+
+  constructor(init: DeadlineExceededInit) {
+    super(
+      `Request deadline exceeded: ${init.deadlineMs}ms deadline (${init.flushBufferMs}ms flush buffer)`,
+    );
+    this.deadlineMs = init.deadlineMs;
+    this.flushBufferMs = init.flushBufferMs;
+    this.remainingMs = init.remainingMs;
+  }
+}
+
+// Structural check rather than instanceof — works across module boundaries
+// and serialization boundaries where prototype chain may be broken.
+export function isDeadlineExceeded(error: unknown): error is DeadlineExceededError {
+  if (error === null || error === undefined) return false;
+  if (typeof error !== "object") return false;
+  return (error as { name?: unknown }).name === "DeadlineExceededError";
+}

package/src/handler-wrapper.ts

@@ -0,0 +1,19 @@
+// SPDX-FileCopyrightText: 2024 lambda-deadline-middleware contributors
+// SPDX-License-Identifier: MIT
+
+import { run } from "./context-store.js";
+import type { LambdaContextLike } from "./context-store.js";
+import type { DeadlineOptions } from "./types.js";
+
+type AsyncHandler<TEvent, TResult> = (
+  event: TEvent,
+  context: LambdaContextLike,
+) => Promise<TResult>;
+
+export function withLambdaDeadline<TEvent, TResult>(
+  handler: AsyncHandler<TEvent, TResult>,
+  _options?: DeadlineOptions,
+): AsyncHandler<TEvent, TResult> {
+  return async (event: TEvent, context: LambdaContextLike): Promise<TResult> =>
+    run(context, async () => handler(event, context));
+}

package/src/index.ts

@@ -0,0 +1,18 @@
+// SPDX-FileCopyrightText: 2024 lambda-deadline-middleware contributors
+// SPDX-License-Identifier: MIT
+
+export { withLambdaDeadline } from "./handler-wrapper.js";
+export { deadlineMiddleware, withDeadline } from "./registration.js";
+export { DeadlineExceededError, isDeadlineExceeded } from "./error.js";
+export { getRemainingTimeInMillis } from "./context-store.js";
+
+export type {
+  Milliseconds,
+  FlushBufferMs,
+  RequestDeadlineMs,
+  DeadlineComputation,
+  DeadlineMiddlewareConfig,
+  DeadlineOptions,
+} from "./types.js";
+
+export type { LambdaContextLike } from "./context-store.js";

package/src/middleware.ts

@@ -0,0 +1,109 @@
+// SPDX-FileCopyrightText: 2024 lambda-deadline-middleware contributors
+// SPDX-License-Identifier: MIT
+
+import { getRemainingTimeInMillis } from "./context-store.js";
+import { DeadlineExceededError } from "./error.js";
+import type { DeadlineComputation, DeadlineMiddlewareConfig, RequestDeadlineMs } from "./types.js";
+import { milliseconds } from "./types.js";
+
+import type {
+  FinalizeHandler,
+  FinalizeHandlerArguments,
+  FinalizeHandlerOutput,
+  FinalizeRequestMiddleware,
+  HandlerExecutionContext,
+} from "@smithy/types";
+
+export function computeDeadline(config: DeadlineMiddlewareConfig): DeadlineComputation {
+  const remaining = getRemainingTimeInMillis();
+
+  if (remaining === undefined) {
+    return { kind: "no-context" };
+  }
+
+  const deadline = remaining - config.flushBufferMs;
+
+  if (deadline <= 0) {
+    return {
+      kind: "insufficient-time",
+      remaining: milliseconds(remaining),
+      buffer: config.flushBufferMs,
+    };
+  }
+
+  // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- branded narrowing: deadline is validated > 0 above
+  return { kind: "deadline", value: deadline as RequestDeadlineMs };
+}
+
+export interface DeadlineTimer {
+  readonly controller: AbortController;
+  [Symbol.dispose]: () => void;
+}
+
+export function createDeadlineTimer(
+  deadlineMs: RequestDeadlineMs,
+  config: DeadlineMiddlewareConfig,
+): DeadlineTimer {
+  const controller = new AbortController();
+  const remaining = milliseconds(deadlineMs + config.flushBufferMs);
+  const error = new DeadlineExceededError({
+    deadlineMs: milliseconds(deadlineMs),
+    flushBufferMs: config.flushBufferMs,
+    remainingMs: remaining,
+  });
+  const timeoutId = setTimeout(() => {
+    controller.abort(error);
+  }, deadlineMs);
+  return {
+    controller,
+    [Symbol.dispose]() {
+      clearTimeout(timeoutId);
+    },
+  };
+}
+
+export function composeSignals(
+  existing: AbortSignal | undefined,
+  deadline: AbortSignal,
+): AbortSignal {
+  if (existing === undefined) return deadline;
+  return AbortSignal.any([existing, deadline]);
+}
+
+export function deadlineMiddlewareHandler(
+  config: DeadlineMiddlewareConfig,
+): FinalizeRequestMiddleware<object, object> {
+  return (
+    next: FinalizeHandler<object, object>,
+    _context: HandlerExecutionContext,
+  ): FinalizeHandler<object, object> =>
+    // oxlint-disable-next-line typescript/consistent-return -- switch is exhaustive over DeadlineComputation discriminated union
+    async (args: FinalizeHandlerArguments<object>): Promise<FinalizeHandlerOutput<object>> => {
+      const computation = computeDeadline(config);
+
+      switch (computation.kind) {
+        case "no-context":
+          return next(args);
+
+        case "insufficient-time":
+          throw new DeadlineExceededError({
+            deadlineMs: milliseconds(0),
+            flushBufferMs: computation.buffer,
+            remainingMs: computation.remaining,
+          });
+
+        case "deadline": {
+          using timer = createDeadlineTimer(computation.value, config);
+          // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- Smithy request is an opaque object; we access optional signal property
+          const request = args.request as { signal?: AbortSignal } | undefined;
+          const signal = composeSignals(request?.signal, timer.controller.signal);
+          const result = await next({
+            ...args,
+            // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- spreading opaque Smithy request to add signal
+            request: { ...(args.request as object), signal },
+          });
+          return result;
+        }
+      }
+    };
+}