Wire up DO-attached container API.

No methods are implemented yet, but if a container capability is passed in when creating an actor, then `ctx.container` will be populated.

Author: kentonv

src/workerd/api/actor-state.c++

@@ -825,10 +825,13 @@ kj::OneOf<jsg::Ref<DurableObjectId>, kj::StringPtr> ActorState::getId() {
   KJ_UNREACHABLE;
 }
 
-DurableObjectState::DurableObjectState(
-    Worker::Actor::Id actorId, kj::Maybe<jsg::Ref<DurableObjectStorage>> storage)
+DurableObjectState::DurableObjectState(Worker::Actor::Id actorId,
+    kj::Maybe<jsg::Ref<DurableObjectStorage>> storage,
+    kj::Maybe<rpc::Container::Client> container)
     : id(kj::mv(actorId)),
-      storage(kj::mv(storage)) {}
+      storage(kj::mv(storage)),
+      container(container.map(
+          [&](rpc::Container::Client& cap) { return jsg::alloc<Container>(kj::mv(cap)); })) {}
 
 void DurableObjectState::waitUntil(kj::Promise<void> promise) {
   IoContext::current().addWaitUntil(kj::mv(promise));

src/workerd/api/actor-state.h

@@ -8,6 +8,7 @@
 // See actor.h for APIs used by other Workers to talk to Actors.
 
 #include <workerd/api/actor.h>
+#include <workerd/api/container.h>
 #include <workerd/io/actor-cache.h>
 #include <workerd/io/actor-id.h>
 #include <workerd/io/compatibility-date.capnp.h>
@@ -462,7 +463,9 @@ class WebSocketRequestResponsePair: public jsg::Object {
 // The type passed as the first parameter to durable object class's constructor.
 class DurableObjectState: public jsg::Object {
  public:
-  DurableObjectState(Worker::Actor::Id actorId, kj::Maybe<jsg::Ref<DurableObjectStorage>> storage);
+  DurableObjectState(Worker::Actor::Id actorId,
+      kj::Maybe<jsg::Ref<DurableObjectStorage>> storage,
+      kj::Maybe<rpc::Container::Client> container);
 
   void waitUntil(kj::Promise<void> promise);
 
@@ -472,6 +475,10 @@ class DurableObjectState: public jsg::Object {
     return storage.map([&](jsg::Ref<DurableObjectStorage>& p) { return p.addRef(); });
   }
 
+  jsg::Optional<jsg::Ref<Container>> getContainer() {
+    return container.map([](jsg::Ref<Container>& c) { return c.addRef(); });
+  }
+
   jsg::Promise<jsg::JsRef<jsg::JsValue>> blockConcurrencyWhile(
       jsg::Lock& js, jsg::Function<jsg::Promise<jsg::JsRef<jsg::JsValue>>()> callback);
 
@@ -536,6 +543,7 @@ class DurableObjectState: public jsg::Object {
     JSG_METHOD(waitUntil);
     JSG_READONLY_INSTANCE_PROPERTY(id, getId);
     JSG_READONLY_INSTANCE_PROPERTY(storage, getStorage);
+    JSG_READONLY_INSTANCE_PROPERTY(container, getContainer);
     JSG_METHOD(blockConcurrencyWhile);
     JSG_METHOD(acceptWebSocket);
     JSG_METHOD(getWebSockets);
@@ -574,6 +582,7 @@ class DurableObjectState: public jsg::Object {
  private:
   Worker::Actor::Id id;
   kj::Maybe<jsg::Ref<DurableObjectStorage>> storage;
+  kj::Maybe<jsg::Ref<Container>> container;
 
   // Limits for Hibernatable WebSocket tags.
 

src/workerd/api/container.c++

@@ -0,0 +1,14 @@
+// Copyright (c) 2025 Cloudflare, Inc.
+// Licensed under the Apache 2.0 license found in the LICENSE file or at:
+//     https://opensource.org/licenses/Apache-2.0
+
+#include "container.h"
+
+#include <workerd/io/io-context.h>
+
+namespace workerd::api {
+
+Container::Container(rpc::Container::Client rpcClient)
+    : rpcClient(IoContext::current().addObject(kj::heap(kj::mv(rpcClient)))) {}
+
+}  // namespace workerd::api

src/workerd/api/container.h

@@ -0,0 +1,30 @@
+// Copyright (c) 2025 Cloudflare, Inc.
+// Licensed under the Apache 2.0 license found in the LICENSE file or at:
+//     https://opensource.org/licenses/Apache-2.0
+
+#pragma once
+// APIs that an Actor (Durable Object) uses to access its own state.
+//
+// See actor.h for APIs used by other Workers to talk to Actors.
+
+#include <workerd/io/container.capnp.h>
+#include <workerd/io/io-own.h>
+#include <workerd/jsg/jsg.h>
+
+namespace workerd::api {
+
+class Container: public jsg::Object {
+ public:
+  Container(rpc::Container::Client rpcClient);
+
+  JSG_RESOURCE_TYPE(Container) {
+    // TODO(now): Implement the API.
+  }
+
+ private:
+  IoOwn<rpc::Container::Client> rpcClient;
+};
+
+#define EW_CONTAINER_ISOLATE_TYPES api::Container
+
+}  // namespace workerd::api

src/workerd/io/BUILD.bazel

@@ -98,6 +98,7 @@ wd_cc_library(
         ":actor-id",
         ":actor-storage_capnp",
         ":cdp_capnp",
+        ":container_capnp",
         ":frankenvalue",
         ":io-gate",
         ":io-helpers",

src/workerd/io/worker.c++

@@ -3184,6 +3184,8 @@ struct Worker::Actor::Impl {
   kj::Maybe<jsg::JsRef<jsg::JsValue>> transient;
   kj::Maybe<kj::Own<ActorCacheInterface>> actorCache;
 
+  kj::Maybe<rpc::Container::Client> container;
+
   struct NoClass {};
   struct Initializing {};
 
@@ -3344,10 +3346,12 @@ struct Worker::Actor::Impl {
       kj::Own<ActorObserver> metricsParam,
       kj::Maybe<kj::Own<HibernationManager>> manager,
       kj::Maybe<uint16_t>& hibernationEventType,
+      kj::Maybe<rpc::Container::Client> container,
       kj::PromiseFulfillerPair<void> paf = kj::newPromiseAndFulfiller<void>())
       : actorId(kj::mv(actorId)),
         makeStorage(kj::mv(makeStorage)),
         metrics(kj::mv(metricsParam)),
+        container(kj::mv(container)),
         hooks(loopback->addRef(), timerChannel, *metrics),
         inputGate(hooks),
         outputGate(hooks),
@@ -3404,12 +3408,13 @@ Worker::Actor::Actor(const Worker& worker,
     TimerChannel& timerChannel,
     kj::Own<ActorObserver> metrics,
     kj::Maybe<kj::Own<HibernationManager>> manager,
-    kj::Maybe<uint16_t> hibernationEventType)
+    kj::Maybe<uint16_t> hibernationEventType,
+    kj::Maybe<rpc::Container::Client> container)
     : worker(kj::atomicAddRef(worker)),
       tracker(tracker.map([](RequestTracker& tracker) { return tracker.addRef(); })) {
   impl = kj::heap<Impl>(*this, lock, kj::mv(actorId), hasTransient, kj::mv(makeActorCache),
       kj::mv(makeStorage), kj::mv(loopback), timerChannel, kj::mv(metrics), kj::mv(manager),
-      hibernationEventType);
+      hibernationEventType, kj::mv(container));
 
   KJ_IF_SOME(c, className) {
     KJ_IF_SOME(cls, lock.getWorker().impl->actorClasses.find(c)) {
@@ -3432,7 +3437,8 @@ void Worker::Actor::ensureConstructed(IoContext& context) {
       KJ_IF_SOME(c, impl->actorCache) {
         storage = impl->makeStorage(lock, worker->getIsolate().getApi(), *c);
       }
-      auto handler = info.cls(lock, jsg::alloc<api::DurableObjectState>(cloneId(), kj::mv(storage)),
+      auto handler = info.cls(lock,
+          jsg::alloc<api::DurableObjectState>(cloneId(), kj::mv(storage), kj::mv(impl->container)),
           KJ_ASSERT_NONNULL(lock.getWorker().impl->env).addRef(js));
 
       // HACK: We set handler.env to undefined because we already passed the real env into the

src/workerd/io/worker.h

@@ -8,6 +8,7 @@
 #include <workerd/io/actor-cache.h>  // because we can't forward-declare ActorCache::SharedLru.
 #include <workerd/io/actor-id.h>
 #include <workerd/io/compatibility-date.capnp.h>
+#include <workerd/io/container.capnp.h>
 #include <workerd/io/frankenvalue.h>
 #include <workerd/io/io-channels.h>
 #include <workerd/io/limit-enforcer.h>
@@ -762,7 +763,8 @@ class Worker::Actor final: public kj::Refcounted {
       TimerChannel& timerChannel,
       kj::Own<ActorObserver> metrics,
       kj::Maybe<kj::Own<HibernationManager>> manager,
-      kj::Maybe<uint16_t> hibernationEventType);
+      kj::Maybe<uint16_t> hibernationEventType,
+      kj::Maybe<rpc::Container::Client> container = kj::none);
 
   ~Actor() noexcept(false);
 

src/workerd/server/workerd-api.c++

@@ -10,6 +10,7 @@
 #include <workerd/api/actor.h>
 #include <workerd/api/analytics-engine.h>
 #include <workerd/api/cache.h>
+#include <workerd/api/container.h>
 #include <workerd/api/crypto/impl.h>
 #include <workerd/api/encoding.h>
 #include <workerd/api/events.h>
@@ -84,6 +85,7 @@ JSG_DECLARE_ISOLATE_TYPE(JsgWorkerdIsolate,
     EW_BASICS_ISOLATE_TYPES,
     EW_BLOB_ISOLATE_TYPES,
     EW_CACHE_ISOLATE_TYPES,
+    EW_CONTAINER_ISOLATE_TYPES,
     EW_CRYPTO_ISOLATE_TYPES,
     EW_ENCODING_ISOLATE_TYPES,
     EW_EVENTS_ISOLATE_TYPES,