feat(extstore): add aws-sdk s3 driver package.

Author: cconstable

contrib/external-storage-s3-aws-sdk/README.md

@@ -0,0 +1,23 @@
+# AWS SDK Client for the Temporal S3 External Storage Driver
+
+> ⚠️ **This package is experimental and may be subject to change.** ⚠️
+
+`@temporalio/external-storage-s3-aws-sdk` provides an [`@aws-sdk/client-s3`](https://www.npmjs.com/package/@aws-sdk/client-s3)-backed `S3StorageDriverClient` for [`@temporalio/external-storage-s3`](../external-storage-s3).
+
+`@aws-sdk/client-s3` is a peer dependency, so the driver uses the same `S3Client` (and version) your application already configures.
+
+## Usage
+
+    npm install @temporalio/external-storage-s3 @temporalio/external-storage-s3-aws-sdk @aws-sdk/client-s3
+
+```ts
+import { S3Client } from '@aws-sdk/client-s3';
+import { S3StorageDriver } from '@temporalio/external-storage-s3';
+import { AwsSdkS3StorageDriverClient } from '@temporalio/external-storage-s3-aws-sdk';
+
+const s3Client = new S3Client({ region: 'us-east-1' });
+const driver = new S3StorageDriver({
+  client: new AwsSdkS3StorageDriverClient(s3Client),
+  bucket: 'my-temporal-payloads',
+});
+```

contrib/external-storage-s3-aws-sdk/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@temporalio/external-storage-s3-aws-sdk",
+  "version": "1.17.2",
+  "description": "AWS SDK (@aws-sdk/client-s3) client for the Temporal S3 external storage driver",
+  "main": "lib/index.js",
+  "types": "./lib/index.d.ts",
+  "keywords": [
+    "temporal",
+    "workflow",
+    "external storage",
+    "payload",
+    "s3",
+    "aws"
+  ],
+  "author": "Temporal Technologies Inc. <sdk@temporal.io>",
+  "license": "MIT",
+  "scripts": {
+    "build": "tsc --build",
+    "test": "ava ./lib/__tests__/test-*.js"
+  },
+  "ava": {
+    "timeout": "60s"
+  },
+  "dependencies": {
+    "@temporalio/external-storage-s3": "workspace:*"
+  },
+  "peerDependencies": {
+    "@aws-sdk/client-s3": "^3.0.0"
+  },
+  "devDependencies": {
+    "@aws-sdk/client-s3": "^3.0.0",
+    "ava": "^5.3.1"
+  },
+  "engines": {
+    "node": ">= 20.3.0"
+  },
+  "bugs": {
+    "url": "https://github.com/temporalio/sdk-typescript/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/temporalio/sdk-typescript.git",
+    "directory": "contrib/external-storage-s3-aws-sdk"
+  },
+  "homepage": "https://github.com/temporalio/sdk-typescript/tree/main/contrib/external-storage-s3-aws-sdk",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src",
+    "lib",
+    "!src/__tests__",
+    "!lib/__tests__"
+  ]
+}

contrib/external-storage-s3-aws-sdk/src/__tests__/test-aws-sdk-client.ts

@@ -0,0 +1,55 @@
+import test from 'ava';
+import type { S3Client } from '@aws-sdk/client-s3';
+import { AwsSdkS3StorageDriverClient } from '../aws-sdk-client';
+
+/** Minimal S3Client stand-in: only `send` and `config.region` are exercised. */
+function fakeS3Client(send: (command: unknown) => Promise<unknown>, region?: string): S3Client {
+  return { send, config: { region } } as unknown as S3Client;
+}
+
+test('objectExists maps a NotFound error to false', async (t) => {
+  const client = new AwsSdkS3StorageDriverClient(
+    fakeS3Client(() => Promise.reject(Object.assign(new Error('not found'), { name: 'NotFound' })))
+  );
+  t.false(await client.objectExists('b', 'k'));
+});
+
+test('objectExists maps a 404 status to false', async (t) => {
+  const client = new AwsSdkS3StorageDriverClient(
+    fakeS3Client(() => Promise.reject(Object.assign(new Error('nope'), { $metadata: { httpStatusCode: 404 } })))
+  );
+  t.false(await client.objectExists('b', 'k'));
+});
+
+test('objectExists rethrows non-404 errors', async (t) => {
+  const client = new AwsSdkS3StorageDriverClient(
+    fakeS3Client(() => Promise.reject(Object.assign(new Error('denied'), { $metadata: { httpStatusCode: 403 } })))
+  );
+  await t.throwsAsync(() => client.objectExists('b', 'k'), { message: 'denied' });
+});
+
+test('objectExists returns true when the head succeeds', async (t) => {
+  const client = new AwsSdkS3StorageDriverClient(fakeS3Client(() => Promise.resolve({})));
+  t.true(await client.objectExists('b', 'k'));
+});
+
+test('getObject reads the response body as bytes', async (t) => {
+  const bytes = new Uint8Array([1, 2, 3]);
+  const client = new AwsSdkS3StorageDriverClient(fakeS3Client(() => Promise.resolve({ Body: { transformToByteArray: async () => bytes } })));
+  t.deepEqual(await client.getObject('b', 'k'), bytes);
+});
+
+test('getObject throws when the response has no body', async (t) => {
+  const client = new AwsSdkS3StorageDriverClient(fakeS3Client(() => Promise.resolve({})));
+  await t.throwsAsync(() => client.getObject('b', 'k'), { message: /empty body/ });
+});
+
+test('describe surfaces a plain-string region', (t) => {
+  const client = new AwsSdkS3StorageDriverClient(fakeS3Client(() => Promise.resolve({}), 'us-west-2'));
+  t.deepEqual(client.describe?.(), { clientRegion: 'us-west-2' });
+});
+
+test('describe omits region when unavailable', (t) => {
+  const client = new AwsSdkS3StorageDriverClient(fakeS3Client(() => Promise.resolve({})));
+  t.deepEqual(client.describe?.(), {});
+});

contrib/external-storage-s3-aws-sdk/src/aws-sdk-client.ts

@@ -0,0 +1,53 @@
+import { PutObjectCommand, GetObjectCommand, HeadObjectCommand } from '@aws-sdk/client-s3';
+import type { S3Client as AwsS3Client } from '@aws-sdk/client-s3';
+import type { S3StorageDriverClient, S3RequestOptions } from '@temporalio/external-storage-s3';
+
+/**
+ * An {@link S3StorageDriverClient} backed by an `@aws-sdk/client-s3` `S3Client`,
+ * for use with `S3StorageDriver`.
+ *
+ * @experimental
+ */
+export class AwsSdkS3StorageDriverClient implements S3StorageDriverClient {
+  constructor(private readonly client: AwsS3Client) {}
+
+  describe(): Record<string, string> {
+    // v3 normalizes `region` to an async provider, so it is usually unavailable
+    // synchronously here; surface it only when it was supplied as a plain string.
+    const region = this.client.config?.region;
+    return typeof region === 'string' && region ? { clientRegion: region } : {};
+  }
+
+  async objectExists(bucket: string, key: string, options?: S3RequestOptions): Promise<boolean> {
+    try {
+      await this.client.send(new HeadObjectCommand({ Bucket: bucket, Key: key }), { abortSignal: options?.abortSignal });
+      return true;
+    } catch (err) {
+      if (isNotFound(err)) {
+        return false;
+      }
+      throw err;
+    }
+  }
+
+  async putObject(bucket: string, key: string, data: Uint8Array, options?: S3RequestOptions): Promise<void> {
+    await this.client.send(new PutObjectCommand({ Bucket: bucket, Key: key, Body: data }), {
+      abortSignal: options?.abortSignal,
+    });
+  }
+
+  async getObject(bucket: string, key: string, options?: S3RequestOptions): Promise<Uint8Array> {
+    const response = await this.client.send(new GetObjectCommand({ Bucket: bucket, Key: key }), {
+      abortSignal: options?.abortSignal,
+    });
+    if (!response.Body) {
+      throw new Error(`S3 GetObject returned an empty body [bucket=${bucket}, key=${key}]`);
+    }
+    return response.Body.transformToByteArray();
+  }
+}
+
+function isNotFound(err: unknown): boolean {
+  const e = err as { name?: string; $metadata?: { httpStatusCode?: number } };
+  return e?.name === 'NotFound' || e?.$metadata?.httpStatusCode === 404;
+}

contrib/external-storage-s3-aws-sdk/src/index.ts

@@ -0,0 +1,4 @@
+/**
+ * @experimental The External Storage S3 driver is an experimental feature and may be subject to change.
+ */
+export { AwsSdkS3StorageDriverClient } from './aws-sdk-client';

contrib/external-storage-s3-aws-sdk/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "./lib",
+    "rootDir": "./src"
+  },
+  "references": [{ "path": "../external-storage-s3" }],
+  "include": ["./src/**/*.ts"]
+}