containers: add custom labels support to container start options

src/workerd/api/container.c++

@@ -56,6 +56,24 @@ void Container::start(jsg::Lock& js, jsg::Optional<StartupOptions> maybeOptions)
     }
   }
 
+  KJ_IF_SOME(labels, options.labels) {
+    auto list = req.initLabels(labels.fields.size());
+    for (auto i: kj::indices(labels.fields)) {
+      auto& field = labels.fields[i];
+      JSG_REQUIRE(field.name.size() > 0, Error, "Label names cannot be empty");
+      for (auto c: field.name) {
+        JSG_REQUIRE(static_cast<kj::byte>(c) >= 0x20, Error,
+            "Label names cannot contain control characters (index ", i, ")");
+      }
+      for (auto c: field.value) {
+        JSG_REQUIRE(static_cast<kj::byte>(c) >= 0x20, Error,
+            "Label values cannot contain control characters (index ", i, ")");
+      }
+      list[i].setName(field.name);
+      list[i].setValue(field.value);
+    }
+  }
+
   req.setCompatibilityFlags(flags);
 
   IoContext::current().addTask(req.sendIgnoringResult());

src/workerd/api/container.h

@@ -29,23 +29,26 @@ class Container: public jsg::Object {
     bool enableInternet = false;
     jsg::Optional<jsg::Dict<kj::String>> env;
     jsg::Optional<int64_t> hardTimeout;
+    jsg::Optional<jsg::Dict<kj::String>> labels;
 
     // TODO(containers): Allow intercepting stdin/stdout/stderr by specifying streams here.
 
-    JSG_STRUCT(entrypoint, enableInternet, env, hardTimeout);
+    JSG_STRUCT(entrypoint, enableInternet, env, hardTimeout, labels);
     JSG_STRUCT_TS_OVERRIDE_DYNAMIC(CompatibilityFlags::Reader flags) {
       if (flags.getWorkerdExperimental()) {
         JSG_TS_OVERRIDE(ContainerStartupOptions {
           entrypoint?: string[];
           enableInternet: boolean;
           env?: Record<string, string>;
           hardTimeout?: number | bigint;
+          labels?: Record<string, string>;
         });
       } else {
         JSG_TS_OVERRIDE(ContainerStartupOptions {
           entrypoint?: string[];
           enableInternet: boolean;
           env?: Record<string, string>;
+          labels?: Record<string, string>;
         });
       }
     }

src/workerd/io/container.capnp

@@ -44,6 +44,14 @@ interface Container @0x9aaceefc06523bca {
 
     compatibilityFlags @4 :CompatibilityFlags;
     # Compatibility flags for this worker
+
+    labels @5 :List(Label);
+    # Optional key-value metadata labels for metrics/observability.
+  }
+
+  struct Label {
+    name @0 :Text;
+    value @1 :Text;
   }
 
   monitor @2 () -> (exitCode: Int32);

src/workerd/server/container-client.c++

@@ -790,6 +790,16 @@ kj::Promise<void> ContainerClient::createContainer(
     jsonEnv.set(envSize + i, defaultEnv[i]);
   }
 
+  // Pass user-supplied labels as Docker object labels, visible via `docker inspect`.
+  if (params.hasLabels()) {
+    auto lbls = params.getLabels();
+    auto labelsObj = jsonRoot.initLabels().initObject(lbls.size());
+    for (auto i: kj::zeroTo(lbls.size())) {
+      labelsObj[i].setName(lbls[i].getName());
+      labelsObj[i].initValue().setString(lbls[i].getValue());
+    }
+  }
+
   auto hostConfig = jsonRoot.initHostConfig();
   // We need to set a restart policy to avoid having ambiguous states
   // where the container we're managing is stuck at "exited" state.

src/workerd/server/tests/container-client/test.js

@@ -311,6 +311,58 @@ export class DurableObjectExample extends DurableObject {
     await monitor;
   }
 
+  async testLabels() {
+    const container = this.ctx.container;
+    if (container.running) {
+      let monitor = container.monitor().catch((_err) => {});
+      await container.destroy();
+      await monitor;
+    }
+
+    assert.strictEqual(container.running, false);
+
+    container.start({
+      enableInternet: true,
+      labels: { team: 'workers', environment: 'testing' },
+    });
+
+    const monitor = container.monitor().catch((_err) => {});
+    await this.waitUntilContainerIsHealthy();
+
+    assert.strictEqual(container.running, true);
+
+    await container.destroy();
+    await monitor;
+    assert.strictEqual(container.running, false);
+  }
+
+  async testLabelValidation() {
+    const container = this.ctx.container;
+    if (container.running) {
+      let monitor = container.monitor().catch((_err) => {});
+      await container.destroy();
+      await monitor;
+    }
+
+    assert.strictEqual(container.running, false);
+
+    // Empty label name
+    assert.throws(() => container.start({ labels: { '': 'value' } }), {
+      message: /Label names cannot be empty/,
+    });
+
+    // Label name with control character
+    assert.throws(
+      () => container.start({ labels: { 'bad\x01name': 'value' } }),
+      { message: /Label names cannot contain control characters \(index 0\)/ }
+    );
+
+    // Label value with control character
+    assert.throws(() => container.start({ labels: { name: 'bad\x01value' } }), {
+      message: /Label values cannot contain control characters \(index 0\)/,
+    });
+  }
+
   async testPidNamespace() {
     const container = this.ctx.container;
     if (container.running) {
@@ -899,6 +951,28 @@ export const testSetInactivityTimeout = {
   },
 };
 
+// Test that custom labels are passed through to the container
+export const testLabels = {
+  async test(_ctrl, env) {
+    const id = env.MY_CONTAINER.idFromName(
+      getRandomDurableObjectName('testLabels')
+    );
+    const stub = env.MY_CONTAINER.get(id);
+    await stub.testLabels();
+  },
+};
+
+// Test that invalid labels are rejected with clear error messages
+export const testLabelValidation = {
+  async test(_ctrl, env) {
+    const id = env.MY_CONTAINER.idFromName(
+      getRandomDurableObjectName('testLabelValidation')
+    );
+    const stub = env.MY_CONTAINER.get(id);
+    await stub.testLabelValidation();
+  },
+};
+
 // Test PID namespace isolation behavior
 // When containers_pid_namespace is ENABLED, the container has its own isolated PID namespace.
 // We verify this by checking that PID 1 in the container's namespace is the container's

types/generated-snapshot/experimental/index.d.ts

@@ -3894,6 +3894,7 @@ interface ContainerStartupOptions {
   enableInternet: boolean;
   env?: Record<string, string>;
   hardTimeout?: number | bigint;
+  labels?: Record<string, string>;
 }
 /**
  * The **`FileSystemHandle`** interface of the File System API is an object which represents a file or directory entry.

types/generated-snapshot/experimental/index.ts

@@ -3900,6 +3900,7 @@ export interface ContainerStartupOptions {
   enableInternet: boolean;
   env?: Record<string, string>;
   hardTimeout?: number | bigint;
+  labels?: Record<string, string>;
 }
 /**
  * The **`FileSystemHandle`** interface of the File System API is an object which represents a file or directory entry.

types/generated-snapshot/latest/index.d.ts

@@ -3772,6 +3772,7 @@ interface ContainerStartupOptions {
   enableInternet: boolean;
   env?: Record<string, string>;
   hardTimeout?: number | bigint;
+  labels?: Record<string, string>;
 }
 /**
  * The **`MessagePort`** interface of the Channel Messaging API represents one of the two ports of a MessageChannel, allowing messages to be sent from one port and listening out for them arriving at the other.

types/generated-snapshot/latest/index.ts

@@ -3778,6 +3778,7 @@ export interface ContainerStartupOptions {
   enableInternet: boolean;
   env?: Record<string, string>;
   hardTimeout?: number | bigint;
+  labels?: Record<string, string>;
 }
 /**
  * The **`MessagePort`** interface of the Channel Messaging API represents one of the two ports of a MessageChannel, allowing messages to be sent from one port and listening out for them arriving at the other.