@squiz/db-lib 1.75.1 → 1.77.0

package/src/s3/S3ExternalStorage.spec.ts

@@ -0,0 +1,181 @@
+import { S3ExternalStorage, S3StorageLocation } from './S3ExternalStorage';
+import { S3Client } from '@aws-sdk/client-s3';
+
+const TEST_TENANT_ID = 'test-tenant';
+const TEST_BUCKET = 'dx-test-us-db-fallback';
+
+type S3MockSet = {
+  sendMock: jest.Mock;
+  putObjectCommandMock: jest.Mock;
+  getObjectCommandMock: jest.Mock;
+  deleteObjectCommandMock: jest.Mock;
+  headBucketCommandMock: jest.Mock;
+};
+
+declare global {
+  // eslint-disable-next-line no-var
+  var __s3MockSet: S3MockSet | undefined;
+}
+
+jest.mock('@aws-sdk/client-s3', () => {
+  const buildCommandMock = (name: string) =>
+    jest.fn().mockImplementation((input) => ({
+      name,
+      input,
+    }));
+  const state: S3MockSet = {
+    sendMock: jest.fn(),
+    putObjectCommandMock: buildCommandMock('PutObjectCommand'),
+    getObjectCommandMock: buildCommandMock('GetObjectCommand'),
+    deleteObjectCommandMock: buildCommandMock('DeleteObjectCommand'),
+    headBucketCommandMock: buildCommandMock('HeadBucketCommand'),
+  };
+  (global as any).__s3MockSet = state;
+
+  return {
+    S3Client: jest.fn().mockImplementation(() => ({
+      send: state.sendMock,
+    })),
+    PutObjectCommand: state.putObjectCommandMock,
+    GetObjectCommand: state.getObjectCommandMock,
+    DeleteObjectCommand: state.deleteObjectCommandMock,
+    HeadBucketCommand: state.headBucketCommandMock,
+  };
+});
+
+const { sendMock, putObjectCommandMock, getObjectCommandMock, deleteObjectCommandMock, headBucketCommandMock } = (
+  global as any
+).__s3MockSet as S3MockSet;
+
+jest.mock('crypto', () => ({
+  randomUUID: jest.fn(() => 'fixed-uuid'),
+}));
+
+describe('S3ExternalStorage', () => {
+  beforeEach(() => {
+    sendMock.mockReset();
+    putObjectCommandMock.mockClear();
+    getObjectCommandMock.mockClear();
+    deleteObjectCommandMock.mockClear();
+    headBucketCommandMock.mockClear();
+  });
+
+  const createStorage = () => new S3ExternalStorage(TEST_TENANT_ID, new S3Client({ region: 'us-west-2' }), TEST_BUCKET);
+
+  it('saves payloads to S3 and returns location metadata', async () => {
+    const storage = createStorage();
+    const payload = { foo: 'bar' };
+    sendMock.mockResolvedValueOnce({}); // put object
+
+    const result = await storage.save('test_entity', 'abc', payload);
+
+    expect(putObjectCommandMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        Bucket: 'dx-test-us-db-fallback',
+        Body: JSON.stringify(payload),
+        ContentType: 'application/json',
+        Key: result.location.key,
+      }),
+    );
+    expect(result.location).toMatchObject({
+      type: 's3',
+    });
+    expect(result.location.key).toBe('test-tenant/test_entity/abc.json');
+    expect(result.size).toBe(JSON.stringify(payload).length);
+  });
+
+  it('loads payloads from S3 and parses JSON', async () => {
+    const storage = createStorage();
+    const storedPayload = { baz: 'qux' };
+    const transformer = jest.fn().mockResolvedValue(JSON.stringify(storedPayload));
+    sendMock.mockResolvedValueOnce({
+      Body: {
+        transformToString: transformer,
+      },
+    });
+
+    const location: S3StorageLocation = { type: 's3', key: 'items/foo/bar.json' };
+    const result = await storage.load(location);
+
+    expect(getObjectCommandMock).toHaveBeenCalledWith({
+      Bucket: 'dx-test-us-db-fallback',
+      Key: 'items/foo/bar.json',
+    });
+    expect(transformer).toHaveBeenCalled();
+    expect(result).toEqual(storedPayload);
+  });
+
+  it('deletes payloads from S3 when a location is provided', async () => {
+    const storage = createStorage();
+    const location: S3StorageLocation = { type: 's3', key: 'items/foo.json' };
+    sendMock.mockResolvedValueOnce({}); // delete
+
+    await storage.delete(location);
+
+    expect(deleteObjectCommandMock).toHaveBeenCalledWith({
+      Bucket: 'dx-test-us-db-fallback',
+      Key: 'items/foo.json',
+    });
+  });
+
+  it('handles S3 errors when saving', async () => {
+    const storage = createStorage();
+    const payload = { foo: 'bar' };
+    const s3Error = Object.assign(new Error('AccessDenied'), {
+      name: 'AccessDenied',
+      $metadata: { httpStatusCode: 403 },
+    });
+
+    sendMock.mockRejectedValueOnce(s3Error);
+
+    await expect(storage.save('test_entity', 'first', payload)).rejects.toThrow('AccessDenied');
+  });
+
+  it('does not delete when location is undefined', async () => {
+    const storage = createStorage();
+
+    await storage.delete(undefined);
+
+    expect(deleteObjectCommandMock).not.toHaveBeenCalled();
+  });
+
+  it('generates unique S3 keys for different entity types', async () => {
+    const storage = createStorage();
+    sendMock.mockResolvedValue({});
+
+    const result1 = await storage.save('entity_type_a', 'id-1', { data: 'test' });
+    const result2 = await storage.save('entity_type_b', 'id-2', { data: 'test' });
+
+    expect(result1.location.key).toContain('entity_type_a/id-1');
+    expect(result2.location.key).toContain('entity_type_b/id-2');
+  });
+
+  it('throws error when S3 response has no body', async () => {
+    const storage = createStorage();
+    sendMock.mockResolvedValueOnce({ Body: undefined });
+
+    const location: S3StorageLocation = { type: 's3', key: 'items/foo/bar.json' };
+
+    await expect(storage.load(location)).rejects.toThrow(
+      'Failed to load externalised items from S3 object items/foo/bar.json',
+    );
+  });
+
+  it('handles S3 errors gracefully when loading', async () => {
+    const storage = createStorage();
+    sendMock.mockRejectedValueOnce(new Error('S3 GetObject failed'));
+
+    const location: S3StorageLocation = { type: 's3', key: 'items/foo/bar.json' };
+
+    await expect(storage.load(location)).rejects.toThrow('S3 GetObject failed');
+  });
+
+  it('handles S3 errors gracefully when deleting', async () => {
+    const storage = createStorage();
+    sendMock.mockRejectedValueOnce(new Error('S3 DeleteObject failed'));
+
+    const location: S3StorageLocation = { type: 's3', key: 'items/foo.json' };
+
+    await expect(storage.delete(location)).rejects.toThrow('S3 DeleteObject failed');
+  });
+});

package/src/s3/S3ExternalStorage.ts

@@ -0,0 +1,118 @@
+/*!
+ * @file S3ExternalStorage.ts
+ * @description This file contains the S3ExternalStorage class, which is used to store and retrieve page contents from S3.
+ * @author Dean Heffernan
+ * @copyright 2025 Squiz
+ */
+
+// External
+import { DeleteObjectCommand, GetObjectCommand, PutObjectCommand, S3Client } from '@aws-sdk/client-s3';
+
+/**
+ * Represents the storage location of page contents in S3.
+ */
+export interface S3StorageLocation {
+  type: 's3';
+  key: string;
+}
+
+/**
+ * The S3ExternalStorage class is used to store and retrieve page contents from S3.
+ * @class S3ExternalStorage
+ * @constructor
+ * @param {string} bucket - The name of the S3 bucket to use for storing page contents.
+ * @param {number} thresholdBytes - The threshold in bytes above which page contents will be stored externally.
+ * @param {S3Client} s3Client - The S3 client to use for storing and retrieving page contents.
+ * @returns {S3ExternalStorage} A new instance of the S3ExternalStorage class.
+ */
+export class S3ExternalStorage {
+  /**
+   * The config to use for storing and retrieving page contents.
+   * @type {Config}
+   */
+  private readonly tenantId: string;
+  /**
+   * The name of the S3 bucket to use for storing page contents.
+   * @type {string}
+   */
+  private readonly bucket: string;
+  /**
+   * The S3 client to use for storing and retrieving page contents.
+   * @type {S3Client}
+   */
+  private readonly s3Client: S3Client;
+
+  /**
+   * Creates a new instance of the S3ExternalStorage class.
+   * @constructor
+   * @param {S3Client} s3Client - The S3 client to use for storing and retrieving page contents.
+   * @returns {S3ExternalStorage} A new instance of the S3ExternalStorage class.
+   */
+  constructor(tenantId: string, s3Client: S3Client, bucket: string) {
+    this.tenantId = tenantId;
+    this.bucket = bucket;
+    this.s3Client = s3Client;
+  }
+
+  /**
+   * Saves a payload to S3.
+   * @param {string} entityName - The name of the entity to save the payload for.
+   * @param {string} referenceId - The reference ID of the payload.
+   * @param {object} payload - The payload to save.
+   * @returns {Promise<{ location: S3StorageLocation; size: number }>} A promise that resolves to the location and size of the saved payload.
+   */
+  public async save(
+    entityName: string,
+    referenceId: string,
+    payload: object,
+  ): Promise<{ location: S3StorageLocation; size: number }> {
+    const body = JSON.stringify(payload);
+    const key = `${this.tenantId}/${entityName}/${referenceId}.json`;
+    await this.s3Client.send(
+      new PutObjectCommand({
+        Bucket: this.bucket,
+        Key: key,
+        Body: body,
+        ContentType: 'application/json',
+      }),
+    );
+    return {
+      location: {
+        type: 's3',
+        key,
+      },
+      size: Buffer.byteLength(body, 'utf8'),
+    };
+  }
+
+  /**
+   * Loads a payload from S3.
+   * @param location - The location of the payload to load.
+   * @returns {Promise<Record<string, unknown>>} A promise that resolves to the loaded payload.
+   */
+  public async load(location: S3StorageLocation): Promise<Record<string, unknown>> {
+    const response = await this.s3Client.send(
+      new GetObjectCommand({
+        Bucket: this.bucket,
+        Key: location.key,
+      }),
+    );
+    if (!response.Body) {
+      throw new Error(`Failed to load externalised items from S3 object ${location.key}`);
+    }
+    const contents = await response.Body.transformToString();
+    return JSON.parse(contents);
+  }
+
+  public async delete(location?: S3StorageLocation) {
+    if (!location || !this.bucket) {
+      return;
+    }
+    await this.s3Client.send(
+      new DeleteObjectCommand({
+        Bucket: this.bucket,
+        Key: location.key,
+      }),
+    );
+  }
+}