feat(s3-deployment): add some convenient methods to CacheControl (#25477)

This PR adds following convenient methods to `CacheControl`.

| method | directive | RFC |
|-|-|-|
| `CacheControl.noStore()` | `no-store` | [RFC9111](https://www.rfc-editor.org/rfc/rfc9111.html), Section 5.2.2.4 |
| `CacheControl.mustUnderstand()` | `must-understand` | RFC9111, Section 5.2.2.3 |
| `CacheControl.immutable()` | `immutable` | [RFC8246](https://www.rfc-editor.org/rfc/rfc8246.html) |
| `CacheControl.staleWhileRevalidate(duration)` | `stale-while-revalidate=<duration>` | [RFC5861](https://www.rfc-editor.org/rfc/rfc5861.html) |
| `CacheControl.staleIfError(duration)` | `stale-if-error=<duration>` | RFC5861 |

For more information about these Cache-Control directives,
see https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control

----

*By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license*

Author: Tietew

packages/aws-cdk-lib/aws-s3-deployment/README.md

@@ -157,14 +157,19 @@ declare const destinationBucket: s3.Bucket;
 new s3deploy.BucketDeployment(this, 'BucketDeployment', {
   sources: [s3deploy.Source.asset('./website', { exclude: ['index.html'] })],
   destinationBucket,
-  cacheControl: [s3deploy.CacheControl.fromString('max-age=31536000,public,immutable')],
+  cacheControl: [
+    s3deploy.CacheControl.maxAge(Duration.days(365)),
+    s3deploy.CacheControl.immutable(),
+  ],
   prune: false,
 });
 
 new s3deploy.BucketDeployment(this, 'HTMLBucketDeployment', {
   sources: [s3deploy.Source.asset('./website', { exclude: ['*', '!index.html'] })],
   destinationBucket,
-  cacheControl: [s3deploy.CacheControl.fromString('max-age=0,no-cache,no-store,must-revalidate')],
+  cacheControl: [
+    s3deploy.CacheControl.maxAge(Duration.seconds(0)),
+  ],
   prune: false,
 });
 ```

packages/aws-cdk-lib/aws-s3-deployment/lib/bucket-deployment.ts

@@ -631,6 +631,16 @@ export class CacheControl {
    */
   public static noTransform() { return new CacheControl('no-transform'); }
 
+  /**
+   * Sets 'no-store'.
+   */
+  public static noStore() { return new CacheControl('no-store'); }
+
+  /**
+   * Sets 'must-understand'.
+   */
+  public static mustUnderstand() { return new CacheControl('must-understand'); }
+
   /**
    * Sets 'public'.
    */
@@ -641,6 +651,11 @@ export class CacheControl {
    */
   public static setPrivate() { return new CacheControl('private'); }
 
+  /**
+   * Sets 'immutable'.
+   */
+  public static immutable() { return new CacheControl('immutable'); }
+
   /**
    * Sets 'proxy-revalidate'.
    */
@@ -656,6 +671,16 @@ export class CacheControl {
    */
   public static sMaxAge(t: cdk.Duration) { return new CacheControl(`s-maxage=${t.toSeconds()}`); }
 
+  /**
+   * Sets 'stale-while-revalidate=<duration-in-seconds>'.
+   */
+  public static staleWhileRevalidate(t: cdk.Duration) { return new CacheControl(`stale-while-revalidate=${t.toSeconds()}`); }
+
+  /**
+   * Sets 'stale-if-error=<duration-in-seconds>'.
+   */
+  public static staleIfError(t: cdk.Duration) { return new CacheControl(`stale-if-error=${t.toSeconds()}`); }
+
   /**
    * Constructs a custom cache control key from the literal value.
    */

packages/aws-cdk-lib/aws-s3-deployment/test/bucket-deployment.test.ts

@@ -514,11 +514,16 @@ test('cache control type has correct values', () => {
   expect(s3deploy.CacheControl.mustRevalidate().value).toEqual('must-revalidate');
   expect(s3deploy.CacheControl.noCache().value).toEqual('no-cache');
   expect(s3deploy.CacheControl.noTransform().value).toEqual('no-transform');
+  expect(s3deploy.CacheControl.noStore().value).toEqual('no-store');
+  expect(s3deploy.CacheControl.mustUnderstand().value).toEqual('must-understand');
   expect(s3deploy.CacheControl.setPublic().value).toEqual('public');
   expect(s3deploy.CacheControl.setPrivate().value).toEqual('private');
+  expect(s3deploy.CacheControl.immutable().value).toEqual('immutable');
   expect(s3deploy.CacheControl.proxyRevalidate().value).toEqual('proxy-revalidate');
   expect(s3deploy.CacheControl.maxAge(cdk.Duration.minutes(1)).value).toEqual('max-age=60');
   expect(s3deploy.CacheControl.sMaxAge(cdk.Duration.minutes(1)).value).toEqual('s-maxage=60');
+  expect(s3deploy.CacheControl.staleWhileRevalidate(cdk.Duration.minutes(1)).value).toEqual('stale-while-revalidate=60');
+  expect(s3deploy.CacheControl.staleIfError(cdk.Duration.minutes(1)).value).toEqual('stale-if-error=60');
   expect(s3deploy.CacheControl.fromString('only-if-cached').value).toEqual('only-if-cached');
 });