containers: add custom labels support to container start options

[martinezjandrew]

Customers want to attach custom labels to containers so that they can filter based on them in GraphQL.

Originally, labels were supported at the deployments API level but not through the DO binding. The StartupOptions struct accepted a labels field from JS, but container.c++:start() never forwarded it to the capnpStartParams. Labels were silently dropped before the runtime/launcher could receive them.

This PR aims to resolve this by:

• adding a Label struct and labels field to StartParams in container.capnp
• Forwarding labels from the JS dict to the capnp list in container.capnp
• Encoding labels into Docker's ContainerCreateRequest JSON for local development.
  • You can view the labels with docker inspect

[github-actions]

All contributors have signed the CLA ✍️ ✅
_{Posted by the CLA Assistant Lite bot.}

[ask-bonk]

I'm Bonk, and I've done a quick review of your PR.

This PR adds custom label forwarding from the JS container API through to the capnp StartParams and Docker ContainerCreateRequest. The capnp schema change is additive and wire-compatible.

Findings (ranked by severity):

1. [MEDIUM] No input validation on label names or values — The env dict validates against = and \0 characters, but labels passes names/values through with no validation at all. Since labels flow to Docker and GraphQL, consider adding basic bounds checks (e.g., label count limit, key/value length limits, reject empty keys). At minimum, empty label names should be rejected.

2. [LOW] C++ test duplicates production encoding logic — The label→Docker JSON encoding in both test cases is copy-pasted from container-client.c++ rather than exercised through createContainer(). If the production code is refactored, these tests would pass with stale logic.

---

This review was generated by an AI assistant and may contain inaccuracies. Please verify any suggestions before applying them.

[ask-bonk]

Review posted on PR #6352. Two findings:

1. [MEDIUM] No input validation on label names/values — The existing env dict validates against = and \0 characters, but labels passes through with zero validation. Since labels flow to Docker and GraphQL, at minimum empty label names should be rejected. Posted an inline suggestion with a concrete fix.

2. [LOW] C++ test duplicates production encoding logic — The test cases copy-paste the label→Docker JSON encoding from container-client.c++ rather than exercising the production code path. If the production code is refactored, these tests would still pass with stale logic.

The capnp schema change is additive (labels @5 with new Label struct) and wire-compatible. The TS type overrides are correctly placed in both experimental and non-experimental branches.

github run

[github-actions]

The generated output of @cloudflare/workers-types matches the snapshot in types/generated-snapshot 🎉

[martinezjandrew]

I have read the CLA Document and I hereby sign the CLA

[martinezjandrew]

recheck

[codspeed-hq]

Merging this PR will not alter performance

✅ 70 untouched benchmarks
⏩ 129 skipped benchmarks¹

---

_{Comparing amartinez/container-labels (ebb0c02) with main (8deb8db)}

Footnotes

1. 129 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports. ↩

[codecov-commenter]

Codecov Report

❌ Patch coverage is 0% with 25 lines in your changes missing coverage. Please review.
✅ Project coverage is 70.70%. Comparing base (8deb8db) to head (ebb0c02).

Files with missing lines	Patch %	Lines
src/workerd/api/container.c++	0.00%	17 Missing ⚠️
src/workerd/server/container-client.c++	0.00%	8 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #6352      +/-   ##
==========================================
- Coverage   70.71%   70.70%   -0.02%     
==========================================
  Files         420      420              
  Lines      113702   113727      +25     
  Branches    18731    18740       +9     
==========================================
+ Hits        80410    80414       +4     
- Misses      22061    22084      +23     
+ Partials    11231    11229       -2     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[petebacondarwin]

Approved the typings changes on behalf of Wrangler team.