@ayepi/aws 0.2.0 → 0.4.0

package/README.md

@@ -49,6 +49,11 @@ const w = createWork({ queue, pubsub, store, work: [/* ... */] as const })
   and rethrown.
 - **You own the SDK clients.** The clients are optional peer deps — you construct and configure
   them (region, credentials, endpoint) and manage their lifecycle.
+- **Connection pooling.** The SDK's default handler caps outbound connections at `maxSockets: 50`
+  per client — a common bottleneck for a busy S3+SQS work system. `@ayepi/aws/http` exports
+  `pooledRequestHandler({ maxSockets })` and `sharedHttpAgents(...)` — a keep-alive handler with a
+  higher cap to pass as `requestHandler`, or one shared pool across clients:
+  `new S3Client({ requestHandler: pooledRequestHandler({ maxSockets: 256 }) })`.
 
 ## Options
 

package/ayepi-aws.md

@@ -166,6 +166,7 @@ The returned [`Queue`](./ayepi-work-ports.md#queue--the-durable-work-log) maps o
 | `heartbeat(pulled, visibility)` | `ChangeMessageVisibility` | extends the lease to `ceil(visibility/1000)` s, **clamped to ≤ 43200 s** |
 | `ack(pulled)` | `DeleteMessage` | permanently removes the message (+ deletes the offloaded S3 body) |
 | `fail(pulled, delay?)` | `ChangeMessageVisibility` | returns the message early: `VisibilityTimeout` = `ceil((delay ?? 0)/1000)` s, **clamped to ≤ 43200 s** |
+| `size()` | `GetQueueAttributes` | reads `ApproximateNumberOfMessages` and returns it as a number (`0` when absent) |
 
 **SQS range clamping (far-future scheduling).** SQS rejects out-of-range values, so the queue
 clamps each duration into SQS's allowed range: `DelaySeconds` to **0–900 s** (15 min) on `push`,
@@ -184,6 +185,11 @@ horizons or keep distant schedules sparse.
   `max`. Each `PulledWork.attempt` comes from the message's `ApproximateReceiveCount` (delivery
   count, starting at 1); `handle` is an opaque `{ receiptHandle, s3Key? }` you round-trip to
   `heartbeat`/`ack`/`fail`.
+- **`size`** implements the optional `Queue.size()` — a single `GetQueueAttributes` reading
+  `ApproximateNumberOfMessages` (returned as a number, `0` when the attribute is absent, wrapped in
+  `retry` like every other call). It's what lets `@ayepi/work`'s sustained-backlog alarm
+  (`createWork({ onBacklog })`) report real SQS queue depth (`queued`). The count is **approximate**
+  — it's SQS's own `ApproximateNumberOfMessages`, not an exact tally.
 - **Dead-lettering** is the queue's own SQS **redrive policy** — configured on the queue (or its
   DLQ) in AWS, not here. After `maxReceiveCount` failed deliveries SQS moves the message to the
   DLQ natively. (`sqsQueue` does not implement the optional `Queue.deadLetter` hook.)
@@ -205,6 +211,49 @@ deleted. Notes:
 - `store` is any [`@ayepi/files`](./ayepi-files.md) `FileStore` — typically an `s3Files({...})`,
   but a filesystem store or your own works too.
 
+### `@ayepi/aws/http` — a well-pooled request handler
+
+The SDK's default `NodeHttpHandler` caps outbound connections at **`maxSockets: 50` per client**.
+Under a busy work system (S3 + SQS + more, each its own client) that cap is often the first thing to
+break — calls queue behind 50 sockets and latency balloons, with no error, just slowness. This
+subpath builds a keep-alive handler (and shareable agents) with a higher cap.
+
+```ts
+import { S3Client } from '@aws-sdk/client-s3';
+import { SQSClient } from '@aws-sdk/client-sqs';
+import { pooledRequestHandler, sharedHttpAgents } from '@ayepi/aws/http';
+
+// One handler per client:
+const s3 = new S3Client({ region, requestHandler: pooledRequestHandler({ maxSockets: 256 }) });
+
+// ...or share ONE pool across many clients (bounds total sockets, better reuse):
+const agents = sharedHttpAgents({ maxSockets: 512 });
+const s3b = new S3Client({ requestHandler: pooledRequestHandler(agents) });
+const sqs = new SQSClient({ requestHandler: pooledRequestHandler(agents) });
+```
+
+```ts
+function pooledRequestHandler(opts?: PooledHandlerOptions): NodeHttpHandler
+function sharedHttpAgents(opts?: PooledAgentsOptions): { httpAgent; httpsAgent }
+
+interface PooledAgentsOptions {
+  readonly maxSockets?: number;      // per host (default 128; SDK default 50)
+  readonly maxTotalSockets?: number; // across all hosts (default: unlimited)
+  readonly keepAlive?: boolean;      // default true — avoids TCP churn / port exhaustion
+  readonly keepAliveMsecs?: number;  // default 1000
+}
+interface PooledHandlerOptions extends PooledAgentsOptions {
+  readonly connectionTimeout?: number; // ms
+  readonly requestTimeout?: number;    // ms
+  readonly httpAgent?: HttpAgent;       // bring your own (overrides the pool knobs)
+  readonly httpsAgent?: HttpsAgent;
+}
+```
+
+Keep-alive is on by default so connections are reused instead of churned — which also sidesteps
+ephemeral-port / `TIME_WAIT` exhaustion under sustained load. Requires `@smithy/node-http-handler`
+(an optional peer, already a transitive dependency of the AWS SDK clients).
+
 ### `@ayepi/aws` (root) — the retry seam
 
 The root subpath exports the shared resilience machinery both backends build on. You rarely call

package/dist/http.cjs

@@ -0,0 +1,70 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+let node_http = require("node:http");
+let node_https = require("node:https");
+let _smithy_node_http_handler = require("@smithy/node-http-handler");
+//#region src/http.ts
+/**
+* # @ayepi/aws/http — a well-pooled request handler for the AWS SDK
+*
+* The AWS SDK v3's default `NodeHttpHandler` caps outbound connections at **`maxSockets: 50` per
+* client**. Under a busy work system (S3 + SQS + more, each its own client) that cap is often the
+* first thing to break: calls queue behind 50 sockets and latency balloons — with no error, just
+* mysterious slowness. This module builds a handler (and shareable agents) with keep-alive on and a
+* higher cap, to pass as `requestHandler` to your clients.
+*
+* ```ts
+* import { S3Client } from '@aws-sdk/client-s3';
+* import { SQSClient } from '@aws-sdk/client-sqs';
+* import { pooledRequestHandler, sharedHttpAgents } from '@ayepi/aws/http';
+*
+* // One handler per client:
+* const s3 = new S3Client({ region, requestHandler: pooledRequestHandler({ maxSockets: 256 }) });
+*
+* // ...or share ONE pool across many clients (fewer total sockets, better reuse):
+* const agents = sharedHttpAgents({ maxSockets: 512 });
+* const s3b = new S3Client({ requestHandler: pooledRequestHandler(agents) });
+* const sqs = new SQSClient({ requestHandler: pooledRequestHandler(agents) });
+* ```
+*
+* Keep-alive is on by default so connections are reused instead of churned — which also avoids
+* ephemeral-port / `TIME_WAIT` exhaustion under sustained load. Requires `@smithy/node-http-handler`
+* (a transitive dependency of the AWS SDK clients).
+*
+* @module
+*/
+/** Agent constructor options derived from the pool knobs. */
+function agentConf(opts) {
+	return {
+		keepAlive: opts.keepAlive ?? true,
+		keepAliveMsecs: opts.keepAliveMsecs ?? 1e3,
+		maxSockets: opts.maxSockets ?? 128,
+		maxTotalSockets: opts.maxTotalSockets
+	};
+}
+/**
+* A pair of keep-alive `node:http` / `node:https` agents you can **share across many AWS clients**
+* (pass to {@link pooledRequestHandler}). Sharing one pair bounds total sockets across S3/SQS/etc.
+*/
+function sharedHttpAgents(opts = {}) {
+	const conf = agentConf(opts);
+	return {
+		httpAgent: new node_http.Agent(conf),
+		httpsAgent: new node_https.Agent(conf)
+	};
+}
+/**
+* Build a `NodeHttpHandler` with keep-alive and a higher socket cap than the SDK default — pass it
+* as `requestHandler` to an `S3Client`/`SQSClient`. Reuse one handler (or one {@link sharedHttpAgents}
+* pair) across clients to bound total sockets.
+*/
+function pooledRequestHandler(opts = {}) {
+	return new _smithy_node_http_handler.NodeHttpHandler({
+		httpAgent: opts.httpAgent ?? new node_http.Agent(agentConf(opts)),
+		httpsAgent: opts.httpsAgent ?? new node_https.Agent(agentConf(opts)),
+		connectionTimeout: opts.connectionTimeout,
+		requestTimeout: opts.requestTimeout
+	});
+}
+//#endregion
+exports.pooledRequestHandler = pooledRequestHandler;
+exports.sharedHttpAgents = sharedHttpAgents;

package/dist/http.d.cts

@@ -0,0 +1,44 @@
+import { Agent } from "node:http";
+import { Agent as Agent$1 } from "node:https";
+import { NodeHttpHandler } from "@smithy/node-http-handler";
+
+//#region src/http.d.ts
+
+/** Connection-pool knobs shared by the http + https agents. */
+interface PooledAgentsOptions {
+  /** Max sockets per host (default `128`; the SDK default is `50`). */
+  readonly maxSockets?: number;
+  /** Max sockets across all hosts (default: unlimited). */
+  readonly maxTotalSockets?: number;
+  /** Reuse connections (default `true`). Keep-alive avoids TCP churn and port exhaustion. */
+  readonly keepAlive?: boolean;
+  /** Idle time before a kept-alive socket may close (ms, default `1000`). */
+  readonly keepAliveMsecs?: number;
+}
+/** Options for {@link pooledRequestHandler}: the pool knobs plus timeouts and bring-your-own agents. */
+interface PooledHandlerOptions extends PooledAgentsOptions {
+  /** Socket connect timeout (ms). */
+  readonly connectionTimeout?: number;
+  /** Time to wait for a response (ms). */
+  readonly requestTimeout?: number;
+  /** Bring your own http agent (overrides the pool knobs for http). */
+  readonly httpAgent?: Agent;
+  /** Bring your own https agent (overrides the pool knobs for https). */
+  readonly httpsAgent?: Agent$1;
+}
+/**
+ * A pair of keep-alive `node:http` / `node:https` agents you can **share across many AWS clients**
+ * (pass to {@link pooledRequestHandler}). Sharing one pair bounds total sockets across S3/SQS/etc.
+ */
+declare function sharedHttpAgents(opts?: PooledAgentsOptions): {
+  httpAgent: Agent;
+  httpsAgent: Agent$1;
+};
+/**
+ * Build a `NodeHttpHandler` with keep-alive and a higher socket cap than the SDK default — pass it
+ * as `requestHandler` to an `S3Client`/`SQSClient`. Reuse one handler (or one {@link sharedHttpAgents}
+ * pair) across clients to bound total sockets.
+ */
+declare function pooledRequestHandler(opts?: PooledHandlerOptions): NodeHttpHandler;
+//#endregion
+export { PooledAgentsOptions, PooledHandlerOptions, pooledRequestHandler, sharedHttpAgents };

package/dist/http.d.ts

@@ -0,0 +1,44 @@
+import { Agent } from "node:http";
+import { Agent as Agent$1 } from "node:https";
+import { NodeHttpHandler } from "@smithy/node-http-handler";
+
+//#region src/http.d.ts
+
+/** Connection-pool knobs shared by the http + https agents. */
+interface PooledAgentsOptions {
+  /** Max sockets per host (default `128`; the SDK default is `50`). */
+  readonly maxSockets?: number;
+  /** Max sockets across all hosts (default: unlimited). */
+  readonly maxTotalSockets?: number;
+  /** Reuse connections (default `true`). Keep-alive avoids TCP churn and port exhaustion. */
+  readonly keepAlive?: boolean;
+  /** Idle time before a kept-alive socket may close (ms, default `1000`). */
+  readonly keepAliveMsecs?: number;
+}
+/** Options for {@link pooledRequestHandler}: the pool knobs plus timeouts and bring-your-own agents. */
+interface PooledHandlerOptions extends PooledAgentsOptions {
+  /** Socket connect timeout (ms). */
+  readonly connectionTimeout?: number;
+  /** Time to wait for a response (ms). */
+  readonly requestTimeout?: number;
+  /** Bring your own http agent (overrides the pool knobs for http). */
+  readonly httpAgent?: Agent;
+  /** Bring your own https agent (overrides the pool knobs for https). */
+  readonly httpsAgent?: Agent$1;
+}
+/**
+ * A pair of keep-alive `node:http` / `node:https` agents you can **share across many AWS clients**
+ * (pass to {@link pooledRequestHandler}). Sharing one pair bounds total sockets across S3/SQS/etc.
+ */
+declare function sharedHttpAgents(opts?: PooledAgentsOptions): {
+  httpAgent: Agent;
+  httpsAgent: Agent$1;
+};
+/**
+ * Build a `NodeHttpHandler` with keep-alive and a higher socket cap than the SDK default — pass it
+ * as `requestHandler` to an `S3Client`/`SQSClient`. Reuse one handler (or one {@link sharedHttpAgents}
+ * pair) across clients to bound total sockets.
+ */
+declare function pooledRequestHandler(opts?: PooledHandlerOptions): NodeHttpHandler;
+//#endregion
+export { PooledAgentsOptions, PooledHandlerOptions, pooledRequestHandler, sharedHttpAgents };

package/dist/http.js

@@ -0,0 +1,68 @@
+import { Agent } from "node:http";
+import { Agent as Agent$1 } from "node:https";
+import { NodeHttpHandler } from "@smithy/node-http-handler";
+//#region src/http.ts
+/**
+* # @ayepi/aws/http — a well-pooled request handler for the AWS SDK
+*
+* The AWS SDK v3's default `NodeHttpHandler` caps outbound connections at **`maxSockets: 50` per
+* client**. Under a busy work system (S3 + SQS + more, each its own client) that cap is often the
+* first thing to break: calls queue behind 50 sockets and latency balloons — with no error, just
+* mysterious slowness. This module builds a handler (and shareable agents) with keep-alive on and a
+* higher cap, to pass as `requestHandler` to your clients.
+*
+* ```ts
+* import { S3Client } from '@aws-sdk/client-s3';
+* import { SQSClient } from '@aws-sdk/client-sqs';
+* import { pooledRequestHandler, sharedHttpAgents } from '@ayepi/aws/http';
+*
+* // One handler per client:
+* const s3 = new S3Client({ region, requestHandler: pooledRequestHandler({ maxSockets: 256 }) });
+*
+* // ...or share ONE pool across many clients (fewer total sockets, better reuse):
+* const agents = sharedHttpAgents({ maxSockets: 512 });
+* const s3b = new S3Client({ requestHandler: pooledRequestHandler(agents) });
+* const sqs = new SQSClient({ requestHandler: pooledRequestHandler(agents) });
+* ```
+*
+* Keep-alive is on by default so connections are reused instead of churned — which also avoids
+* ephemeral-port / `TIME_WAIT` exhaustion under sustained load. Requires `@smithy/node-http-handler`
+* (a transitive dependency of the AWS SDK clients).
+*
+* @module
+*/
+/** Agent constructor options derived from the pool knobs. */
+function agentConf(opts) {
+	return {
+		keepAlive: opts.keepAlive ?? true,
+		keepAliveMsecs: opts.keepAliveMsecs ?? 1e3,
+		maxSockets: opts.maxSockets ?? 128,
+		maxTotalSockets: opts.maxTotalSockets
+	};
+}
+/**
+* A pair of keep-alive `node:http` / `node:https` agents you can **share across many AWS clients**
+* (pass to {@link pooledRequestHandler}). Sharing one pair bounds total sockets across S3/SQS/etc.
+*/
+function sharedHttpAgents(opts = {}) {
+	const conf = agentConf(opts);
+	return {
+		httpAgent: new Agent(conf),
+		httpsAgent: new Agent$1(conf)
+	};
+}
+/**
+* Build a `NodeHttpHandler` with keep-alive and a higher socket cap than the SDK default — pass it
+* as `requestHandler` to an `S3Client`/`SQSClient`. Reuse one handler (or one {@link sharedHttpAgents}
+* pair) across clients to bound total sockets.
+*/
+function pooledRequestHandler(opts = {}) {
+	return new NodeHttpHandler({
+		httpAgent: opts.httpAgent ?? new Agent(agentConf(opts)),
+		httpsAgent: opts.httpsAgent ?? new Agent$1(agentConf(opts)),
+		connectionTimeout: opts.connectionTimeout,
+		requestTimeout: opts.requestTimeout
+	});
+}
+//#endregion
+export { pooledRequestHandler, sharedHttpAgents };

package/dist/sqs.cjs

@@ -128,6 +128,13 @@ function sqsQueue(opts) {
 				ReceiptHandle: handleOf(pulled).receiptHandle,
 				VisibilityTimeout: visSecs(delay ?? 0)
 			}));
+		}),
+		size: () => run(async () => {
+			const out = await client.send(new _aws_sdk_client_sqs.GetQueueAttributesCommand({
+				QueueUrl: queueUrl,
+				AttributeNames: ["ApproximateNumberOfMessages"]
+			}));
+			return Number(out.Attributes?.ApproximateNumberOfMessages ?? "0");
 		})
 	};
 }

package/dist/sqs.js

@@ -1,6 +1,6 @@
 import { makeRun } from "./index.js";
 import { randomUUID } from "node:crypto";
-import { ChangeMessageVisibilityCommand, DeleteMessageCommand, ReceiveMessageCommand, SendMessageCommand } from "@aws-sdk/client-sqs";
+import { ChangeMessageVisibilityCommand, DeleteMessageCommand, GetQueueAttributesCommand, ReceiveMessageCommand, SendMessageCommand } from "@aws-sdk/client-sqs";
 //#region src/sqs.ts
 /**
 * # @ayepi/aws/sqs — an SQS-backed `@ayepi/work` {@link Queue}
@@ -127,6 +127,13 @@ function sqsQueue(opts) {
 				ReceiptHandle: handleOf(pulled).receiptHandle,
 				VisibilityTimeout: visSecs(delay ?? 0)
 			}));
+		}),
+		size: () => run(async () => {
+			const out = await client.send(new GetQueueAttributesCommand({
+				QueueUrl: queueUrl,
+				AttributeNames: ["ApproximateNumberOfMessages"]
+			}));
+			return Number(out.Attributes?.ApproximateNumberOfMessages ?? "0");
 		})
 	};
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ayepi/aws",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "AWS backends for ayepi — an SQS @ayepi/work queue (large payloads offloaded to S3) and an S3 @ayepi/files store, all retry-wrapped for throttle resilience",
   "license": "MIT",
   "publishConfig": {
@@ -52,6 +52,16 @@
         "default": "./dist/sqs.cjs"
       }
     },
+    "./http": {
+      "import": {
+        "types": "./dist/http.d.ts",
+        "default": "./dist/http.js"
+      },
+      "require": {
+        "types": "./dist/http.d.cts",
+        "default": "./dist/http.cjs"
+      }
+    },
     "./package.json": "./package.json"
   },
   "engines": {
@@ -62,9 +72,10 @@
     "@aws-sdk/client-sqs": "^3",
     "@aws-sdk/lib-storage": "^3",
     "@aws-sdk/s3-request-presigner": "^3",
-    "@ayepi/core": "^0.2.0",
-    "@ayepi/work": "^0.2.0",
-    "@ayepi/files": "^0.2.0"
+    "@smithy/node-http-handler": "^4",
+    "@ayepi/core": "^0.4.0",
+    "@ayepi/work": "^0.4.0",
+    "@ayepi/files": "^0.4.0"
   },
   "peerDependenciesMeta": {
     "@ayepi/work": {
@@ -84,6 +95,9 @@
     },
     "@aws-sdk/s3-request-presigner": {
       "optional": true
+    },
+    "@smithy/node-http-handler": {
+      "optional": true
     }
   },
   "devDependencies": {
@@ -91,15 +105,16 @@
     "@aws-sdk/client-sqs": "^3.700.0",
     "@aws-sdk/lib-storage": "^3.700.0",
     "@aws-sdk/s3-request-presigner": "^3.700.0",
+    "@smithy/node-http-handler": "^4.0.0",
     "@vitest/coverage-v8": "^2.1.8",
     "publint": "^0.3.0",
     "testcontainers": "^10.13.0",
     "tsdown": "^0.12.0",
     "vitest": "^2.1.8",
     "zod": "^4.4.3",
-    "@ayepi/core": "0.2.0",
-    "@ayepi/work": "0.2.0",
-    "@ayepi/files": "0.2.0"
+    "@ayepi/core": "0.4.0",
+    "@ayepi/files": "0.4.0",
+    "@ayepi/work": "0.4.0"
   },
   "keywords": [
     "ayepi",