Address small nits and update tests.

Author: cconstable

contrib/external-storage-s3/README.md

@@ -2,7 +2,7 @@
 
 > ⚠️ **This package is experimental and may be subject to change.** ⚠️
 
-`@temporalio/external-storage-s3` stores and retrieves Temporal payloads in Amazon S3 via the [External Storage](../../README.md) feature.
+`@temporalio/external-storage-s3` stores and retrieves Temporal payloads in Amazon S3 via the [External Storage](https://docs.temporal.io/external-storage) feature.
 
 This package has no AWS dependency: it defines the driver and the `S3StorageDriverClient` interface, and you supply the S3 client. Use the companion [`@temporalio/external-storage-s3-aws-sdk`](../external-storage-s3-aws-sdk) package for an [`@aws-sdk/client-s3`](https://www.npmjs.com/package/@aws-sdk/client-s3)-backed client, or implement the interface yourself.
 

contrib/external-storage-s3/src/__tests__/test-driver.ts

@@ -71,15 +71,12 @@ test('key is content-addressed and segmented by the store context', async (t) =>
   const [claim] = await driver.store(workflowContext, [payload]);
   assert(claim?.claimData.key);
 
-  // Content-addressed: the digest segment is the SHA-256 of the serialized payload
-  // bytes, and the store context fields form the preceding path segments in order.
   const digest = sha256Hex(payloadBytes(payload));
   t.is(claim.claimData.key, `v0/ns/my-ns/wt/MyWorkflow/wi/wf-1/ri/run-1/d/sha256/${digest}`);
   t.is(claim.claimData.hashValue, digest);
   t.is(claim.claimData.hashAlgorithm, 'sha256');
   t.is(claim.claimData.bucket, 'b');
 
-  // Different content under the same context changes only the trailing digest segment.
   const [other] = await driver.store(workflowContext, [makePayload('"world"')]);
   assert(other?.claimData.key);
   t.not(other.claimData.key, claim.claimData.key);
@@ -120,6 +117,15 @@ test('a target with no identity falls back to a bare digest key', async (t) => {
   t.regex(claim.claimData.key, /^v0\/d\/sha256\/[0-9a-f]{64}$/);
 });
 
+test('missing context segments are encoded as the literal "null"', async (t) => {
+  const driver = new S3StorageDriver({ client: new FakeS3Client(), bucket: 'b' });
+
+  const [claim] = await driver.store({ target: { kind: 'workflow', namespace: 'my-ns' } }, [makePayload('"x"')]);
+  assert(claim?.claimData.key);
+
+  t.true(claim.claimData.key.startsWith('v0/ns/my-ns/wt/null/wi/null/ri/null/d/sha256/'));
+});
+
 test('identical payloads in the same scope deduplicate to one upload', async (t) => {
   const client = new FakeS3Client();
   const driver = new S3StorageDriver({ client, bucket: 'b' });

contrib/external-storage-s3/src/driver.ts

@@ -15,11 +15,17 @@ const PayloadProto = proto.temporal.api.common.v1.Payload;
 
 const DRIVER_TYPE = 'aws.s3driver';
 const DEFAULT_MAX_PAYLOAD_SIZE = 50 * 1024 * 1024;
+/** Key segment written when a context value is empty or absent. */
+const NULL_SEGMENT = 'null';
 
 /** Picks the destination bucket for a given payload. Enables dynamic per-payload routing. */
 export type BucketSelector = (context: StorageDriverStoreContext, payload: Payload) => string;
 
-/** @experimental */
+/**
+ * Configuration for an {@link S3StorageDriver}.
+ *
+ * @experimental
+ */
 export interface S3StorageDriverOptions {
   /**
    * An {@link S3StorageDriverClient} that performs the underlying requests,
@@ -47,7 +53,7 @@ export interface S3StorageDriverOptions {
  * literal `null`.
  */
 function encodeKeySegment(value: string | undefined): string {
-  if (!value) return 'null';
+  if (!value) return NULL_SEGMENT;
   return encodeURIComponent(value).replace(/~/g, '%7E');
 }
 
@@ -124,13 +130,13 @@ export class S3StorageDriver implements StorageDriver {
   private readonly maxPayloadSize: number;
 
   constructor(options: S3StorageDriverOptions) {
-    const { client, bucket, driverName, maxPayloadSize = DEFAULT_MAX_PAYLOAD_SIZE } = options;
+    const { client, bucket, driverName = DRIVER_TYPE, maxPayloadSize = DEFAULT_MAX_PAYLOAD_SIZE } = options;
     if (!Number.isFinite(maxPayloadSize) || maxPayloadSize <= 0) {
       throw new ValueError(`maxPayloadSize must be a positive finite number, got ${String(maxPayloadSize)}`);
     }
     this.client = client;
     this.bucket = typeof bucket === 'string' ? () => bucket : bucket;
-    this.name = driverName || DRIVER_TYPE;
+    this.name = driverName;
     this.maxPayloadSize = maxPayloadSize;
   }