@slates/aws-sdk-http-handler 1.0.0-rc.1

package/README.md

@@ -0,0 +1,18 @@
+# @slates/aws-sdk-http-handler
+
+Axios-backed HTTP handler for AWS SDK for JavaScript v3 clients running inside Slates integrations.
+
+```ts
+import { S3Client } from '@aws-sdk/client-s3';
+import { createSlatesAwsSdkHttpHandler } from '@slates/aws-sdk-http-handler';
+
+let s3 = new S3Client({
+  region,
+  credentials,
+  requestHandler: createSlatesAwsSdkHttpHandler()
+});
+```
+
+The handler uses Slates `createAxios()` by default, so SDK requests participate in Slates request context, logging, and sanitized HTTP tracing.
+
+Do not use Axios interceptors to mutate AWS signed request material after the SDK signs the request. That includes method, path, query string, body, `Authorization`, `Host`, `x-amz-*`, and any headers listed in the request's signed headers. Future secret injection that changes signed material should happen through AWS SDK config or middleware before signing.

package/dist/index.cjs

@@ -0,0 +1,136 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  SlatesAwsSdkHttpHandler: () => SlatesAwsSdkHttpHandler,
+  createSlatesAwsSdkHttpHandler: () => createSlatesAwsSdkHttpHandler
+});
+module.exports = __toCommonJS(index_exports);
+var import_protocol_http = require("@smithy/protocol-http");
+var import_querystring_builder = require("@smithy/querystring-builder");
+var import_slates = require("slates");
+var NODE_TIMEOUT_CODES = /* @__PURE__ */ new Set(["ECONNRESET", "ECONNREFUSED", "EPIPE", "ETIMEDOUT"]);
+var NODE_NETWORK_CODES = /* @__PURE__ */ new Set(["EHOSTUNREACH", "ENETUNREACH", "ENOTFOUND"]);
+var isRecord = (value) => typeof value === "object" && value !== null;
+var normalizeHeaders = (headers) => {
+  let raw = headers && typeof headers.toJSON === "function" ? headers.toJSON() : headers;
+  let out = {};
+  for (let [key, value] of Object.entries(raw ?? {})) {
+    if (value == null) continue;
+    out[key.toLowerCase()] = Array.isArray(value) ? value.map(String).join(", ") : String(value);
+  }
+  return out;
+};
+var hasHeader = (headers, name) => Object.keys(headers).some((key) => key.toLowerCase() === name.toLowerCase());
+var buildRequestHeaders = (headers) => {
+  let out = { ...headers };
+  if (!hasHeader(out, "accept")) {
+    out.accept = "*/*";
+  }
+  return out;
+};
+var getSlateCode = (error) => {
+  if (!isRecord(error)) return void 0;
+  return typeof error.code === "string" ? error.code : void 0;
+};
+var getTransportCode = (error) => {
+  if (!isRecord(error)) return void 0;
+  let directCode = typeof error.code === "string" ? error.code : void 0;
+  if (directCode && !directCode.startsWith("upstream.")) return directCode;
+  let baggage = isRecord(error.data) && isRecord(error.data.baggage) ? error.data.baggage : void 0;
+  let axiosCode = baggage && typeof baggage.axiosCode === "string" ? baggage.axiosCode : void 0;
+  if (axiosCode) return axiosCode;
+  return getTransportCode(error.cause);
+};
+var messageForError = (error) => error instanceof Error ? error.message : String(error);
+var createSdkTransportError = (error, name, code) => {
+  let sdkError = new Error(messageForError(error), { cause: error });
+  sdkError.name = name;
+  if (code) {
+    Object.assign(sdkError, { code });
+  }
+  return sdkError;
+};
+var normalizeTransportError = (error) => {
+  let slateCode = getSlateCode(error);
+  let transportCode = getTransportCode(error);
+  if (slateCode === "upstream.timeout" || transportCode === "ECONNABORTED" || transportCode && NODE_TIMEOUT_CODES.has(transportCode)) {
+    return createSdkTransportError(error, "TimeoutError", transportCode ?? "ETIMEDOUT");
+  }
+  if (slateCode === "upstream.network_error" || transportCode && NODE_NETWORK_CODES.has(transportCode)) {
+    return createSdkTransportError(error, "Error", transportCode);
+  }
+  return error;
+};
+var SlatesAwsSdkHttpHandler = class {
+  axiosClient;
+  config;
+  constructor(config = {}) {
+    this.config = config;
+    this.axiosClient = config.axiosInstance ?? (0, import_slates.createAxios)();
+  }
+  updateHttpClientConfig(key, value) {
+    this.config = { ...this.config, [key]: value };
+  }
+  httpHandlerConfigs() {
+    return this.config;
+  }
+  destroy() {
+  }
+  async handle(request, options = {}) {
+    let queryString = request.query ? (0, import_querystring_builder.buildQueryString)(request.query) : "";
+    let port = request.port ? `:${request.port}` : "";
+    let url = `${request.protocol}//${request.hostname}${port}${request.path}` + (queryString ? `?${queryString}` : "");
+    let method = request.method.toUpperCase();
+    try {
+      let axiosResponse = await this.axiosClient.request({
+        url,
+        method,
+        headers: buildRequestHeaders(request.headers),
+        data: method === "GET" || method === "HEAD" ? void 0 : request.body,
+        validateStatus: () => true,
+        responseType: "stream",
+        transformRequest: [(data) => data],
+        transformResponse: [(data) => data],
+        maxRedirects: 0,
+        decompress: false,
+        timeout: options.requestTimeout ?? this.config.requestTimeout,
+        signal: options.abortSignal
+      });
+      return {
+        response: new import_protocol_http.HttpResponse({
+          statusCode: axiosResponse.status,
+          reason: axiosResponse.statusText,
+          headers: normalizeHeaders(axiosResponse.headers),
+          body: axiosResponse.data
+        })
+      };
+    } catch (error) {
+      throw normalizeTransportError(error);
+    }
+  }
+};
+var createSlatesAwsSdkHttpHandler = (config) => new SlatesAwsSdkHttpHandler(config);
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  SlatesAwsSdkHttpHandler,
+  createSlatesAwsSdkHttpHandler
+});

package/dist/index.d.cts

@@ -0,0 +1,22 @@
+import { AxiosInstance } from 'axios';
+import { HttpHandler, HttpRequest, HttpResponse } from '@smithy/protocol-http';
+import { HttpHandlerOptions } from '@smithy/types';
+
+interface SlatesAwsSdkHttpHandlerConfig {
+    axiosInstance?: AxiosInstance;
+    requestTimeout?: number;
+}
+declare class SlatesAwsSdkHttpHandler implements HttpHandler<SlatesAwsSdkHttpHandlerConfig> {
+    private readonly axiosClient;
+    private config;
+    constructor(config?: SlatesAwsSdkHttpHandlerConfig);
+    updateHttpClientConfig<K extends keyof SlatesAwsSdkHttpHandlerConfig>(key: K, value: SlatesAwsSdkHttpHandlerConfig[K]): void;
+    httpHandlerConfigs(): SlatesAwsSdkHttpHandlerConfig;
+    destroy(): void;
+    handle(request: HttpRequest, options?: HttpHandlerOptions): Promise<{
+        response: HttpResponse;
+    }>;
+}
+declare let createSlatesAwsSdkHttpHandler: (config?: SlatesAwsSdkHttpHandlerConfig) => SlatesAwsSdkHttpHandler;
+
+export { SlatesAwsSdkHttpHandler, type SlatesAwsSdkHttpHandlerConfig, createSlatesAwsSdkHttpHandler };

package/dist/index.d.ts

@@ -0,0 +1,22 @@
+import { AxiosInstance } from 'axios';
+import { HttpHandler, HttpRequest, HttpResponse } from '@smithy/protocol-http';
+import { HttpHandlerOptions } from '@smithy/types';
+
+interface SlatesAwsSdkHttpHandlerConfig {
+    axiosInstance?: AxiosInstance;
+    requestTimeout?: number;
+}
+declare class SlatesAwsSdkHttpHandler implements HttpHandler<SlatesAwsSdkHttpHandlerConfig> {
+    private readonly axiosClient;
+    private config;
+    constructor(config?: SlatesAwsSdkHttpHandlerConfig);
+    updateHttpClientConfig<K extends keyof SlatesAwsSdkHttpHandlerConfig>(key: K, value: SlatesAwsSdkHttpHandlerConfig[K]): void;
+    httpHandlerConfigs(): SlatesAwsSdkHttpHandlerConfig;
+    destroy(): void;
+    handle(request: HttpRequest, options?: HttpHandlerOptions): Promise<{
+        response: HttpResponse;
+    }>;
+}
+declare let createSlatesAwsSdkHttpHandler: (config?: SlatesAwsSdkHttpHandlerConfig) => SlatesAwsSdkHttpHandler;
+
+export { SlatesAwsSdkHttpHandler, type SlatesAwsSdkHttpHandlerConfig, createSlatesAwsSdkHttpHandler };

package/dist/index.module.js

@@ -0,0 +1,110 @@
+// src/index.ts
+import { HttpResponse } from "@smithy/protocol-http";
+import { buildQueryString } from "@smithy/querystring-builder";
+import { createAxios } from "slates";
+var NODE_TIMEOUT_CODES = /* @__PURE__ */ new Set(["ECONNRESET", "ECONNREFUSED", "EPIPE", "ETIMEDOUT"]);
+var NODE_NETWORK_CODES = /* @__PURE__ */ new Set(["EHOSTUNREACH", "ENETUNREACH", "ENOTFOUND"]);
+var isRecord = (value) => typeof value === "object" && value !== null;
+var normalizeHeaders = (headers) => {
+  let raw = headers && typeof headers.toJSON === "function" ? headers.toJSON() : headers;
+  let out = {};
+  for (let [key, value] of Object.entries(raw ?? {})) {
+    if (value == null) continue;
+    out[key.toLowerCase()] = Array.isArray(value) ? value.map(String).join(", ") : String(value);
+  }
+  return out;
+};
+var hasHeader = (headers, name) => Object.keys(headers).some((key) => key.toLowerCase() === name.toLowerCase());
+var buildRequestHeaders = (headers) => {
+  let out = { ...headers };
+  if (!hasHeader(out, "accept")) {
+    out.accept = "*/*";
+  }
+  return out;
+};
+var getSlateCode = (error) => {
+  if (!isRecord(error)) return void 0;
+  return typeof error.code === "string" ? error.code : void 0;
+};
+var getTransportCode = (error) => {
+  if (!isRecord(error)) return void 0;
+  let directCode = typeof error.code === "string" ? error.code : void 0;
+  if (directCode && !directCode.startsWith("upstream.")) return directCode;
+  let baggage = isRecord(error.data) && isRecord(error.data.baggage) ? error.data.baggage : void 0;
+  let axiosCode = baggage && typeof baggage.axiosCode === "string" ? baggage.axiosCode : void 0;
+  if (axiosCode) return axiosCode;
+  return getTransportCode(error.cause);
+};
+var messageForError = (error) => error instanceof Error ? error.message : String(error);
+var createSdkTransportError = (error, name, code) => {
+  let sdkError = new Error(messageForError(error), { cause: error });
+  sdkError.name = name;
+  if (code) {
+    Object.assign(sdkError, { code });
+  }
+  return sdkError;
+};
+var normalizeTransportError = (error) => {
+  let slateCode = getSlateCode(error);
+  let transportCode = getTransportCode(error);
+  if (slateCode === "upstream.timeout" || transportCode === "ECONNABORTED" || transportCode && NODE_TIMEOUT_CODES.has(transportCode)) {
+    return createSdkTransportError(error, "TimeoutError", transportCode ?? "ETIMEDOUT");
+  }
+  if (slateCode === "upstream.network_error" || transportCode && NODE_NETWORK_CODES.has(transportCode)) {
+    return createSdkTransportError(error, "Error", transportCode);
+  }
+  return error;
+};
+var SlatesAwsSdkHttpHandler = class {
+  axiosClient;
+  config;
+  constructor(config = {}) {
+    this.config = config;
+    this.axiosClient = config.axiosInstance ?? createAxios();
+  }
+  updateHttpClientConfig(key, value) {
+    this.config = { ...this.config, [key]: value };
+  }
+  httpHandlerConfigs() {
+    return this.config;
+  }
+  destroy() {
+  }
+  async handle(request, options = {}) {
+    let queryString = request.query ? buildQueryString(request.query) : "";
+    let port = request.port ? `:${request.port}` : "";
+    let url = `${request.protocol}//${request.hostname}${port}${request.path}` + (queryString ? `?${queryString}` : "");
+    let method = request.method.toUpperCase();
+    try {
+      let axiosResponse = await this.axiosClient.request({
+        url,
+        method,
+        headers: buildRequestHeaders(request.headers),
+        data: method === "GET" || method === "HEAD" ? void 0 : request.body,
+        validateStatus: () => true,
+        responseType: "stream",
+        transformRequest: [(data) => data],
+        transformResponse: [(data) => data],
+        maxRedirects: 0,
+        decompress: false,
+        timeout: options.requestTimeout ?? this.config.requestTimeout,
+        signal: options.abortSignal
+      });
+      return {
+        response: new HttpResponse({
+          statusCode: axiosResponse.status,
+          reason: axiosResponse.statusText,
+          headers: normalizeHeaders(axiosResponse.headers),
+          body: axiosResponse.data
+        })
+      };
+    } catch (error) {
+      throw normalizeTransportError(error);
+    }
+  }
+};
+var createSlatesAwsSdkHttpHandler = (config) => new SlatesAwsSdkHttpHandler(config);
+export {
+  SlatesAwsSdkHttpHandler,
+  createSlatesAwsSdkHttpHandler
+};

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@slates/aws-sdk-http-handler",
+  "version": "1.0.0-rc.1",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src/**",
+    "dist/**",
+    "README.md",
+    "package.json"
+  ],
+  "author": "Tobias Herber",
+  "license": "FSL 1.1",
+  "type": "module",
+  "source": "src/index.ts",
+  "exports": {
+    "bun": "./src/index.ts",
+    "types": "./dist/index.d.ts",
+    "require": "./dist/index.cjs",
+    "import": "./dist/index.module.js",
+    "default": "./dist/index.module.js"
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.module.js",
+  "types": "dist/index.d.ts",
+  "unpkg": "./dist/index.module.js",
+  "scripts": {
+    "test": "vitest run --config vitest.config.ts --passWithNoTests",
+    "lint": "prettier src/**/*.ts --check",
+    "build": "tsup --config ../../tsup.packages.config.ts",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@smithy/protocol-http": "^5.3.14",
+    "@smithy/querystring-builder": "^4.2.14",
+    "@smithy/types": "^4.14.1",
+    "axios": "^1.13.2",
+    "slates": "1.0.0-rc.10"
+  },
+  "devDependencies": {
+    "@slates/tsconfig": "1.0.0-rc.1",
+    "@types/node": "^20",
+    "typescript": "5.8.2",
+    "vitest": "^3.1.2"
+  }
+}

package/src/index.test.ts

@@ -0,0 +1,297 @@
+import {
+  createServer,
+  type IncomingMessage,
+  type Server,
+  type ServerResponse
+} from 'node:http';
+import type { AddressInfo } from 'node:net';
+import { HttpRequest } from '@smithy/protocol-http';
+import { SlateContext, runWithContext } from 'slates';
+import { describe, expect, it } from 'vitest';
+import { SlatesAwsSdkHttpHandler } from './index';
+
+let logger = {
+  info() {},
+  warn() {},
+  error() {},
+  progress() {}
+};
+
+let withSlateContext = async <T>(
+  run: (context: SlateContext<any, any, any>) => Promise<T>
+) => {
+  let context = new SlateContext(
+    {},
+    {},
+    {},
+    { key: 'aws-sdk-http-handler-test' } as any,
+    logger as any
+  );
+  let result = await runWithContext(context, () => run(context));
+
+  return { context, result };
+};
+
+let listen = async (
+  handler: (req: IncomingMessage, res: ServerResponse) => void | Promise<void>
+) => {
+  let server = createServer((req, res) => {
+    void handler(req, res);
+  });
+
+  await new Promise<void>((resolve, reject) => {
+    server.once('error', reject);
+    server.listen(0, '127.0.0.1', resolve);
+  });
+
+  return {
+    server,
+    port: (server.address() as AddressInfo).port
+  };
+};
+
+let closeServer = (server: Server) =>
+  new Promise<void>((resolve, reject) => {
+    server.close(error => (error ? reject(error) : resolve()));
+  });
+
+let readBody = (req: IncomingMessage) =>
+  new Promise<string>((resolve, reject) => {
+    let chunks: Buffer[] = [];
+    req.on('data', chunk => chunks.push(Buffer.from(chunk)));
+    req.on('error', reject);
+    req.on('end', () => resolve(Buffer.concat(chunks).toString('utf8')));
+  });
+
+let requestFor = (
+  port: number,
+  options: Partial<ConstructorParameters<typeof HttpRequest>[0]>
+) =>
+  new HttpRequest({
+    protocol: 'http:',
+    hostname: '127.0.0.1',
+    port,
+    path: '/',
+    method: 'GET',
+    headers: {},
+    ...options
+  });
+
+describe('@slates/aws-sdk-http-handler', () => {
+  it('forwards AWS SDK HTTP requests through Axios', async () => {
+    let captured:
+      | {
+          method?: string;
+          url?: string;
+          headers: IncomingMessage['headers'];
+          body: string;
+        }
+      | undefined;
+    let { server, port } = await listen(async (req, res) => {
+      captured = {
+        method: req.method,
+        url: req.url,
+        headers: req.headers,
+        body: await readBody(req)
+      };
+      res.statusCode = 201;
+      res.setHeader('X-Result', 'accepted');
+      res.end('ok');
+    });
+
+    try {
+      let handler = new SlatesAwsSdkHttpHandler();
+
+      let { result } = await withSlateContext(() =>
+        handler.handle(
+          requestFor(port, {
+            path: '/things',
+            method: 'POST',
+            query: {
+              z: 'last',
+              a: ['one', 'two'],
+              bare: null,
+              empty: ''
+            },
+            headers: {
+              'content-type': 'text/plain',
+              'x-custom': 'custom'
+            },
+            body: 'payload'
+          })
+        )
+      );
+
+      expect(result.response.statusCode).toBe(201);
+      expect(result.response.headers['x-result']).toBe('accepted');
+      expect(captured).toMatchObject({
+        method: 'POST',
+        url: '/things?a=one&a=two&bare&empty=&z=last',
+        body: 'payload'
+      });
+      expect(captured?.headers['x-custom']).toBe('custom');
+      expect(captured?.headers.accept).toBe('*/*');
+      expect(captured?.headers['x-slates-provider']).toBe('aws-sdk-http-handler-test');
+    } finally {
+      await closeServer(server);
+    }
+  });
+
+  it('preserves an AWS SDK provided Accept header', async () => {
+    let capturedAccept: string | string[] | undefined;
+    let { server, port } = await listen((req, res) => {
+      capturedAccept = req.headers.accept;
+      res.end();
+    });
+
+    try {
+      let handler = new SlatesAwsSdkHttpHandler();
+      await withSlateContext(() =>
+        handler.handle(
+          requestFor(port, {
+            headers: {
+              Accept: 'application/xml'
+            }
+          })
+        )
+      );
+
+      expect(capturedAccept).toBe('application/xml');
+    } finally {
+      await closeServer(server);
+    }
+  });
+
+  it('returns upstream error responses to the AWS SDK', async () => {
+    let { server, port } = await listen((_req, res) => {
+      res.statusCode = 503;
+      res.statusMessage = 'Service Unavailable';
+      res.end('try later');
+    });
+
+    try {
+      let handler = new SlatesAwsSdkHttpHandler();
+      let { result } = await withSlateContext(() =>
+        handler.handle(requestFor(port, { path: '/unavailable' }))
+      );
+
+      expect(result.response.statusCode).toBe(503);
+      expect(result.response.reason).toBe('Service Unavailable');
+    } finally {
+      await closeServer(server);
+    }
+  });
+
+  it('records sanitized Slates HTTP traces', async () => {
+    let { server, port } = await listen(async (req, res) => {
+      await readBody(req);
+      res.statusCode = 200;
+      res.setHeader('Content-Type', 'application/json');
+      res.end(JSON.stringify({ ok: true, token: 'server-secret' }));
+    });
+
+    try {
+      let handler = new SlatesAwsSdkHttpHandler();
+      let { context } = await withSlateContext(async () => {
+        await handler.handle(
+          requestFor(port, {
+            path: '/trace',
+            method: 'POST',
+            query: {
+              visible: 'yes',
+              token: 'client-token'
+            },
+            headers: {
+              'content-type': 'application/json',
+              authorization: 'Bearer client-secret',
+              'x-api-key': 'client-api-key'
+            },
+            body: JSON.stringify({
+              visible: 'yes',
+              secret: 'client-secret'
+            })
+          })
+        );
+      });
+
+      let trace = context.getHttpTraces()[0];
+      expect(trace?.request.method).toBe('POST');
+      expect(trace?.request.url).toContain('visible=yes');
+      expect(trace?.request.url).not.toContain('client-token');
+      expect(trace?.request.headers).toMatchObject({
+        'x-slates-provider': 'aws-sdk-http-handler-test'
+      });
+      expect(trace?.request.headers).not.toHaveProperty('authorization');
+      expect(trace?.request.headers).not.toHaveProperty('x-api-key');
+      expect(trace?.request.body?.text).toContain('[redacted]');
+      expect(trace?.request.body?.text).not.toContain('client-secret');
+      expect(trace?.response?.status).toBe(200);
+    } finally {
+      await closeServer(server);
+    }
+  });
+
+  it('does not follow redirects for signed AWS requests', async () => {
+    let targetHit = false;
+    let { server, port } = await listen((req, res) => {
+      if (req.url === '/target') {
+        targetHit = true;
+      }
+
+      res.statusCode = 302;
+      res.setHeader('Location', '/target');
+      res.end();
+    });
+
+    try {
+      let handler = new SlatesAwsSdkHttpHandler();
+      let { result } = await withSlateContext(() =>
+        handler.handle(requestFor(port, { path: '/start' }))
+      );
+
+      expect(result.response.statusCode).toBe(302);
+      expect(targetHit).toBe(false);
+    } finally {
+      await closeServer(server);
+    }
+  });
+
+  it('maps Axios timeouts back to Smithy-classifiable errors', async () => {
+    let { server, port } = await listen(() => {
+      // Keep the request open until Axios aborts it.
+    });
+
+    try {
+      let handler = new SlatesAwsSdkHttpHandler({ requestTimeout: 5 });
+      let error = await withSlateContext(() =>
+        handler.handle(requestFor(port, { path: '/timeout' }))
+      )
+        .then(() => null)
+        .catch(err => err as Error & { code?: string; cause?: unknown });
+
+      expect(error).toBeInstanceOf(Error);
+      expect(error?.name).toBe('TimeoutError');
+      expect(error?.cause).toBeTruthy();
+    } finally {
+      await closeServer(server);
+    }
+  });
+
+  it('preserves Node network error codes for Smithy retry classification', async () => {
+    let { server, port } = await listen((_req, res) => {
+      res.end();
+    });
+    await closeServer(server);
+
+    let handler = new SlatesAwsSdkHttpHandler({ requestTimeout: 100 });
+    let error = await withSlateContext(() =>
+      handler.handle(requestFor(port, { path: '/refused' }))
+    )
+      .then(() => null)
+      .catch(err => err as Error & { code?: string; cause?: unknown });
+
+    expect(error).toBeInstanceOf(Error);
+    expect(error?.code).toBe('ECONNREFUSED');
+    expect(error?.cause).toBeTruthy();
+  });
+});

package/src/index.ts

@@ -0,0 +1,174 @@
+import type { AxiosInstance } from 'axios';
+import { HttpResponse, type HttpHandler, type HttpRequest } from '@smithy/protocol-http';
+import { buildQueryString } from '@smithy/querystring-builder';
+import type { HttpHandlerOptions } from '@smithy/types';
+import { createAxios } from 'slates';
+
+export interface SlatesAwsSdkHttpHandlerConfig {
+  axiosInstance?: AxiosInstance;
+  requestTimeout?: number;
+}
+
+let NODE_TIMEOUT_CODES = new Set(['ECONNRESET', 'ECONNREFUSED', 'EPIPE', 'ETIMEDOUT']);
+let NODE_NETWORK_CODES = new Set(['EHOSTUNREACH', 'ENETUNREACH', 'ENOTFOUND']);
+
+let isRecord = (value: unknown): value is Record<string, any> =>
+  typeof value === 'object' && value !== null;
+
+let normalizeHeaders = (headers: unknown): Record<string, string> => {
+  let raw =
+    headers && typeof (headers as { toJSON?: () => unknown }).toJSON === 'function'
+      ? (headers as { toJSON: () => unknown }).toJSON()
+      : headers;
+
+  let out: Record<string, string> = {};
+
+  for (let [key, value] of Object.entries((raw ?? {}) as Record<string, unknown>)) {
+    if (value == null) continue;
+    out[key.toLowerCase()] = Array.isArray(value)
+      ? value.map(String).join(', ')
+      : String(value);
+  }
+
+  return out;
+};
+
+let hasHeader = (headers: Record<string, string>, name: string) =>
+  Object.keys(headers).some(key => key.toLowerCase() === name.toLowerCase());
+
+let buildRequestHeaders = (headers: Record<string, string>) => {
+  let out = { ...headers };
+
+  if (!hasHeader(out, 'accept')) {
+    // Axios defaults to asking for JSON, which makes AWS Query services such as
+    // STS, IAM, and SNS return JSON even though the SDK deserializers expect XML.
+    out.accept = '*/*';
+  }
+
+  return out;
+};
+
+let getSlateCode = (error: unknown): string | undefined => {
+  if (!isRecord(error)) return undefined;
+
+  return typeof error.code === 'string' ? error.code : undefined;
+};
+
+let getTransportCode = (error: unknown): string | undefined => {
+  if (!isRecord(error)) return undefined;
+
+  let directCode = typeof error.code === 'string' ? error.code : undefined;
+  if (directCode && !directCode.startsWith('upstream.')) return directCode;
+
+  let baggage =
+    isRecord(error.data) && isRecord(error.data.baggage) ? error.data.baggage : undefined;
+  let axiosCode =
+    baggage && typeof baggage.axiosCode === 'string' ? baggage.axiosCode : undefined;
+  if (axiosCode) return axiosCode;
+
+  return getTransportCode(error.cause);
+};
+
+let messageForError = (error: unknown) =>
+  error instanceof Error ? error.message : String(error);
+
+let createSdkTransportError = (error: unknown, name: string, code?: string) => {
+  let sdkError = new Error(messageForError(error), { cause: error });
+  sdkError.name = name;
+
+  if (code) {
+    Object.assign(sdkError, { code });
+  }
+
+  return sdkError;
+};
+
+let normalizeTransportError = (error: unknown) => {
+  let slateCode = getSlateCode(error);
+  let transportCode = getTransportCode(error);
+
+  if (
+    slateCode === 'upstream.timeout' ||
+    transportCode === 'ECONNABORTED' ||
+    (transportCode && NODE_TIMEOUT_CODES.has(transportCode))
+  ) {
+    return createSdkTransportError(error, 'TimeoutError', transportCode ?? 'ETIMEDOUT');
+  }
+
+  if (
+    slateCode === 'upstream.network_error' ||
+    (transportCode && NODE_NETWORK_CODES.has(transportCode))
+  ) {
+    return createSdkTransportError(error, 'Error', transportCode);
+  }
+
+  return error;
+};
+
+export class SlatesAwsSdkHttpHandler implements HttpHandler<SlatesAwsSdkHttpHandlerConfig> {
+  private readonly axiosClient: AxiosInstance;
+  private config: SlatesAwsSdkHttpHandlerConfig;
+
+  constructor(config: SlatesAwsSdkHttpHandlerConfig = {}) {
+    this.config = config;
+    this.axiosClient = config.axiosInstance ?? createAxios();
+  }
+
+  updateHttpClientConfig<K extends keyof SlatesAwsSdkHttpHandlerConfig>(
+    key: K,
+    value: SlatesAwsSdkHttpHandlerConfig[K]
+  ): void {
+    this.config = { ...this.config, [key]: value };
+  }
+
+  httpHandlerConfigs(): SlatesAwsSdkHttpHandlerConfig {
+    return this.config;
+  }
+
+  destroy(): void {
+    // The default Slates Axios client does not own sockets or agents.
+  }
+
+  async handle(
+    request: HttpRequest,
+    options: HttpHandlerOptions = {}
+  ): Promise<{ response: HttpResponse }> {
+    let queryString = request.query ? buildQueryString(request.query) : '';
+    let port = request.port ? `:${request.port}` : '';
+    let url =
+      `${request.protocol}//${request.hostname}${port}${request.path}` +
+      (queryString ? `?${queryString}` : '');
+    let method = request.method.toUpperCase();
+
+    try {
+      let axiosResponse = await this.axiosClient.request({
+        url,
+        method,
+        headers: buildRequestHeaders(request.headers),
+        data: method === 'GET' || method === 'HEAD' ? undefined : request.body,
+        validateStatus: () => true,
+        responseType: 'stream',
+        transformRequest: [data => data],
+        transformResponse: [data => data],
+        maxRedirects: 0,
+        decompress: false,
+        timeout: options.requestTimeout ?? this.config.requestTimeout,
+        signal: options.abortSignal as AbortSignal | undefined
+      });
+
+      return {
+        response: new HttpResponse({
+          statusCode: axiosResponse.status,
+          reason: axiosResponse.statusText,
+          headers: normalizeHeaders(axiosResponse.headers),
+          body: axiosResponse.data
+        })
+      };
+    } catch (error) {
+      throw normalizeTransportError(error);
+    }
+  }
+}
+
+export let createSlatesAwsSdkHttpHandler = (config?: SlatesAwsSdkHttpHandlerConfig) =>
+  new SlatesAwsSdkHttpHandler(config);