feat: add format query string to control the image format

carlalexander · carlalexander · commit 4fd64577fbb5 · 2025-04-11T13:40:35.000-04:00
diff --git a/index.js b/index.js
@@ -10,67 +10,54 @@ exports.handler = async (event, context, callback) => {
     const request = event.Records[0].cf.request;
     const response = event.Records[0].cf.response;
 
-    if (
-      '200' !== response.status ||
-      !request.origin ||
-      !request.origin.s3 ||
-      !request.origin.s3.domainName
-    ) {
+    if (shouldSkipProcessing(request, response)) {
       return callback(null, response);
     }
 
-    const match = request.origin.s3.domainName.match(/([^.]*)\.s3(\.[^.]*)?\.amazonaws\.com/i);
+    const bucketDetails = extractBucketDetails(request);
 
-    if (!match || !match[1] || 'string' !== typeof match[1]) {
+    if (!bucketDetails) {
       return callback(null, response);
     }
 
     const allowedContentTypes = ['image/gif', 'image/jpeg', 'image/png'];
-    const bucket = match[1];
+    const bucket = bucketDetails;
     const key = decodeURIComponent(request.uri.substring(1));
+    const params = new URLSearchParams(request.querystring);
+    const formatSetting = params.get('format');
 
-    const getObjectCommand = new GetObjectCommand({ Bucket: bucket, Key: key });
-    const objectResponse = await s3Client.send(getObjectCommand);
+    const objectResponse = await fetchOriginalImage(bucket, key);
 
-    if (
-      !objectResponse.ContentType ||
-      !allowedContentTypes.includes(objectResponse.ContentType) ||
-      ('image/gif' === objectResponse.ContentType &&
-        animated(await streamToBuffer(objectResponse.Body)))
-    ) {
+    if (shouldSkipImageProcessing(objectResponse, allowedContentTypes)) {
+      return callback(null, response);
+    }
+
+    const isAnimatedGif =
+      'image/gif' === objectResponse.ContentType &&
+      animated(await streamToBuffer(objectResponse.Body));
+
+    if (isAnimatedGif) {
       return callback(null, response);
     }
 
-    let contentType = null;
     const objectBody = await streamToBuffer(objectResponse.Body);
     const image = sharp(objectBody);
-    const params = new URLSearchParams(request.querystring);
+    const preserveOriginalFormat = formatSetting === 'original';
 
-    if ('image/gif' === objectResponse.ContentType) {
-      image.png();
-      contentType = [{ key: 'Content-Type', value: 'image/png' }];
-    }
+    let contentType = null;
 
-    if (request.headers['accept'] && request.headers['accept'][0].value.match('image/webp')) {
-      image.webp({
-        quality: Math.round(Math.min(Math.max(parseInt(params.get('quality'), 10) || 82, 0), 100)),
-      });
-      contentType = [{ key: 'Content-Type', value: 'image/webp' }];
+    if (!preserveOriginalFormat) {
+      contentType = await processImageFormat(image, objectResponse, request, params, formatSetting);
     }
 
     if (params.has('width') || params.has('height')) {
-      image.resize({
-        width: parseInt(params.get('width'), 10) || null,
-        height: parseInt(params.get('height'), 10) || null,
-        fit: params.has('cropped') ? sharp.fit.cover : sharp.fit.inside,
-        withoutEnlargement: true,
-      });
+      applyResize(image, params);
     }
 
     const buffer = await image.toBuffer();
     const responseBody = buffer.toString('base64');
 
-    if (1330000 < Buffer.byteLength(responseBody)) {
+    if (isResponseTooLarge(responseBody)) {
       return callback(null, response);
     }
 
@@ -87,7 +74,90 @@ exports.handler = async (event, context, callback) => {
   }
 };
 
-// Helper function to convert a stream to a buffer
+function shouldSkipProcessing(request, response) {
+  return (
+    '200' !== response.status ||
+    !request.origin ||
+    !request.origin.s3 ||
+    !request.origin.s3.domainName
+  );
+}
+
+function extractBucketDetails(request) {
+  const match = request.origin.s3.domainName.match(/([^.]*)\.s3(\.[^.]*)?\.amazonaws\.com/i);
+
+  if (!match || !match[1] || 'string' !== typeof match[1]) {
+    return null;
+  }
+
+  return match[1];
+}
+
+function fetchOriginalImage(bucket, key) {
+  const getObjectCommand = new GetObjectCommand({ Bucket: bucket, Key: key });
+  return s3Client.send(getObjectCommand);
+}
+
+function shouldSkipImageProcessing(objectResponse, allowedContentTypes) {
+  return !objectResponse.ContentType || !allowedContentTypes.includes(objectResponse.ContentType);
+}
+
+function processImageFormat(image, objectResponse, request, params, formatSetting) {
+  let contentType = null;
+
+  if (formatSetting && formatSetting !== 'auto') {
+    return applyExplicitFormat(image, formatSetting);
+  }
+
+  if ('image/gif' === objectResponse.ContentType) {
+    image.png();
+    contentType = [{ key: 'Content-Type', value: 'image/png' }];
+  }
+
+  if (request.headers['accept'] && request.headers['accept'][0].value.match('image/webp')) {
+    const quality = calculateQuality(params);
+    image.webp({ quality });
+    contentType = [{ key: 'Content-Type', value: 'image/webp' }];
+  }
+
+  return contentType;
+}
+
+function applyExplicitFormat(image, formatSetting) {
+  switch (formatSetting.toLowerCase()) {
+    case 'webp':
+      image.webp();
+      return [{ key: 'Content-Type', value: 'image/webp' }];
+    case 'png':
+      image.png();
+      return [{ key: 'Content-Type', value: 'image/png' }];
+    case 'jpeg':
+    case 'jpg':
+      image.jpeg();
+      return [{ key: 'Content-Type', value: 'image/jpeg' }];
+    default:
+      return null;
+  }
+}
+
+function calculateQuality(params) {
+  const rawQuality = parseInt(params.get('quality'), 10) || 82;
+  return Math.round(Math.min(Math.max(rawQuality, 0), 100));
+}
+
+function applyResize(image, params) {
+  image.resize({
+    width: parseInt(params.get('width'), 10) || null,
+    height: parseInt(params.get('height'), 10) || null,
+    fit: params.has('cropped') ? sharp.fit.cover : sharp.fit.inside,
+    withoutEnlargement: true,
+  });
+}
+
+function isResponseTooLarge(responseBody) {
+  return 1330000 < Buffer.byteLength(responseBody);
+}
+
 async function streamToBuffer(stream) {
   const chunks = [];
 
diff --git a/tests/image-processing-integration.test.js b/tests/image-processing-integration.test.js
@@ -283,4 +283,81 @@ describe('Image Processing Integration', () => {
     expect(callback.mock.calls[0][1]).toBe(originalResponse);
     expect(callback.mock.calls[0][1].bodyEncoding).toBeUndefined();
   });
+
+  test('should preserve original GIF format when format=original is specified', async () => {
+    const event = createCloudFrontEvent({
+      uri: '/test-image.gif',
+      querystring: 'format=original',
+    });
+
+    const callback = jest.fn();
+    await handler(event, {}, callback);
+
+    expect(callback).toHaveBeenCalledTimes(1);
+    expect(callback).toHaveBeenCalledWith(null, expect.any(Object));
+
+    const response = callback.mock.calls[0][1];
+
+    expect(response.status).toBe('200');
+    expect(response.bodyEncoding).toBe('base64');
+
+    expect(response.headers['content-type']).toBeDefined();
+
+    const responseBuffer = Buffer.from(response.body, 'base64');
+    const metadata = await sharp(responseBuffer).metadata();
+
+    expect(metadata.format).toBe('gif');
+  });
+
+  test('should preserve original JPEG format when format=original is specified, even with WebP Accept header', async () => {
+    const event = createCloudFrontEvent({
+      uri: '/test-image.jpg',
+      querystring: 'format=original',
+      headers: {
+        accept: [{ key: 'Accept', value: 'image/webp,image/*' }],
+      },
+    });
+
+    const callback = jest.fn();
+    await handler(event, {}, callback);
+
+    expect(callback).toHaveBeenCalledTimes(1);
+    expect(callback).toHaveBeenCalledWith(null, expect.any(Object));
+
+    const response = callback.mock.calls[0][1];
+
+    expect(response.status).toBe('200');
+    expect(response.bodyEncoding).toBe('base64');
+
+    expect(response.headers['content-type']).toBeDefined();
+    expect(response.headers['content-type'][0].value).toBe('image/jpeg');
+
+    const responseBuffer = Buffer.from(response.body, 'base64');
+    const metadata = await sharp(responseBuffer).metadata();
+
+    expect(metadata.format).toBe('jpeg');
+  });
+
+  test('should force conversion to specific format when explicitly requested', async () => {
+    const event = createCloudFrontEvent({
+      uri: '/test-image.jpg',
+      querystring: 'format=webp',
+    });
+
+    const callback = jest.fn();
+    await handler(event, {}, callback);
+
+    expect(callback).toHaveBeenCalledTimes(1);
+
+    const response = callback.mock.calls[0][1];
+
+    expect(response.headers['content-type']).toEqual([
+      { key: 'Content-Type', value: 'image/webp' },
+    ]);
+
+    const responseBuffer = Buffer.from(response.body, 'base64');
+    const metadata = await sharp(responseBuffer).metadata();
+
+    expect(metadata.format).toBe('webp');
+  });
 });
