[draft] start scaffolding ContainerEntrypoint

src/cloudflare/internal/workers.d.ts

@@ -19,6 +19,13 @@ export class WorkflowEntrypoint {
   env: unknown;
 }
 
+export class ContainerEntrypoint {
+  constructor(ctx: unknown, env: unknown);
+
+  ctx: unknown;
+  env: unknown;
+}
+
 export class RpcStub {
   constructor(server: object);
 }

src/cloudflare/workers.ts

@@ -10,6 +10,16 @@ import innerEnv from 'cloudflare-internal:env';
 
 export const WorkerEntrypoint = entrypoints.WorkerEntrypoint;
 export const DurableObject = entrypoints.DurableObject;
+
+// Add ping method to ContainerEntrypoint prototype
+const ContainerEntrypointBase = entrypoints.ContainerEntrypoint;
+class ContainerEntrypointWithMethods extends ContainerEntrypointBase {
+  ping(): string {
+    return 'pong';
+  }
+}
+export const ContainerEntrypoint = ContainerEntrypointWithMethods;
+
 export const RpcStub = entrypoints.RpcStub;
 export const RpcPromise = entrypoints.RpcPromise;
 export const RpcProperty = entrypoints.RpcProperty;

src/workerd/api/BUILD.bazel

@@ -377,6 +377,12 @@ wd_test(
     data = ["actor-alarms-test.js"],
 )
 
+wd_test(
+    src = "container-entrypoint-test.wd-test",
+    args = ["--experimental"],
+    data = ["container-entrypoint-test.js"],
+)
+
 wd_test(
     src = "tail-worker-test.wd-test",
     args = [

src/workerd/api/container-entrypoint-test.js

@@ -0,0 +1,27 @@
+// Copyright (c) 2017-2025 Cloudflare, Inc.
+// Licensed under the Apache 2.0 license found in the LICENSE file or at:
+//     https://opensource.org/licenses/Apache-2.0
+
+import { ContainerEntrypoint } from 'cloudflare:workers';
+import assert from 'node:assert';
+
+// Example ContainerEntrypoint that extends the base class
+export class MyContainer extends ContainerEntrypoint {
+  async customMethod() {
+    return 'custom response';
+  }
+}
+
+// Test that ContainerEntrypoint can be instantiated and ping method works
+export const testPingMethod = {
+  async test(ctrl, env, ctx) {
+    // Get a stub to MyContainer
+    const id = env.MY_CONTAINER.idFromName('test-container');
+    const stub = env.MY_CONTAINER.get(id);
+
+  // Call the built-in ping method
+    const pingResult = await stub.ping();
+    assert.strictEqual(pingResult, 'pong', 'ping() should return "pong"');
+  },
+};
+

src/workerd/api/container-entrypoint-test.wd-test

@@ -0,0 +1,27 @@
+using Workerd = import "/workerd/workerd.capnp";
+
+const config :Workerd.Config = (
+  services = [
+    (name = "main", worker = .mainWorker),
+    (name = "TEST_TMPDIR", disk = (writable = true)),
+  ],
+);
+
+const mainWorker :Workerd.Worker = (
+  compatibilityDate = "2025-01-01",
+  compatibilityFlags = ["experimental", "nodejs_compat"],
+
+  modules = [
+    (name = "worker", esModule = embed "container-entrypoint-test.js"),
+  ],
+
+  durableObjectNamespaces = [
+    (className = "MyContainer", uniqueKey = "container-test-unique-key-123"),
+  ],
+
+  durableObjectStorage = (localDisk = "TEST_TMPDIR"),
+
+  bindings = [
+    (name = "MY_CONTAINER", durableObjectNamespace = "MyContainer"),
+  ],
+);

src/workerd/api/workers-module.c++

@@ -52,6 +52,18 @@ jsg::Ref<WorkflowEntrypoint> WorkflowEntrypoint::constructor(
   return js.alloc<WorkflowEntrypoint>();
 }
 
+jsg::Ref<ContainerEntrypoint> ContainerEntrypoint::constructor(
+    const v8::FunctionCallbackInfo<v8::Value>& args,
+    jsg::Ref<DurableObjectState> ctx,
+    jsg::JsObject env) {
+  jsg::Lock& js = jsg::Lock::from(args.GetIsolate());
+
+  jsg::JsObject self(args.This());
+  self.set(js, "ctx", jsg::JsValue(args[0]));
+  self.set(js, "env", jsg::JsValue(args[1]));
+  return js.alloc<ContainerEntrypoint>();
+}
+
 void EntrypointsModule::waitUntil(kj::Promise<void> promise) {
   // No need to check if IoContext::hasCurrent since current() will throw
   // if there is no active request.

src/workerd/api/workers-module.h

@@ -70,6 +70,27 @@ class WorkflowEntrypoint: public jsg::Object {
   JSG_RESOURCE_TYPE(WorkflowEntrypoint) {}
 };
 
+// Base class for Containers
+//
+// When the worker's top-level module exports a class that extends this class, it means that it
+// is a Container entrypoint, similar to Durable Objects but with container-specific functionality.
+//
+//     import { ContainerEntrypoint } from "cloudflare:workers";
+//     export class MyContainer extends ContainerEntrypoint {
+//       // ping() is provided by the base class
+//     }
+//
+// `env` and `ctx` are automatically available as `this.env` and `this.ctx`, without the need to
+// define a constructor.
+class ContainerEntrypoint: public jsg::Object {
+ public:
+  static jsg::Ref<ContainerEntrypoint> constructor(const v8::FunctionCallbackInfo<v8::Value>& args,
+      jsg::Ref<DurableObjectState> ctx,
+      jsg::JsObject env);
+
+  JSG_RESOURCE_TYPE(ContainerEntrypoint) {}
+};
+
 // The "cloudflare:workers" module, which exposes the WorkerEntrypoint, WorkflowEntrypoint and DurableObject types
 // for extending.
 class EntrypointsModule: public jsg::Object {
@@ -82,6 +103,7 @@ class EntrypointsModule: public jsg::Object {
   JSG_RESOURCE_TYPE(EntrypointsModule) {
     JSG_NESTED_TYPE(WorkerEntrypoint);
     JSG_NESTED_TYPE(WorkflowEntrypoint);
+    JSG_NESTED_TYPE(ContainerEntrypoint);
     JSG_NESTED_TYPE_NAMED(DurableObjectBase, DurableObject);
     JSG_NESTED_TYPE_NAMED(JsRpcPromise, RpcPromise);
     JSG_NESTED_TYPE_NAMED(JsRpcProperty, RpcProperty);
@@ -94,7 +116,7 @@ class EntrypointsModule: public jsg::Object {
 };
 
 #define EW_WORKERS_MODULE_ISOLATE_TYPES                                                            \
-  api::WorkerEntrypoint, api::WorkflowEntrypoint, api::DurableObjectBase, api::EntrypointsModule
+  api::WorkerEntrypoint, api::WorkflowEntrypoint, api::ContainerEntrypoint, api::DurableObjectBase, api::EntrypointsModule
 
 template <class Registry>
 void registerWorkersModule(Registry& registry, CompatibilityFlags::Reader flags) {

src/workerd/io/worker.c++

@@ -1866,6 +1866,13 @@ void Worker::processEntrypointClass(jsg::Lock& js,
               .missingSuperclass = false,
             });
         return;
+      } else if (handle == entrypointClasses.containerEntrypoint) {
+        impl->actorClasses.insert(kj::mv(handlerName),
+            ActorClassInfo{
+              .cls = kj::mv(cls),
+              .missingSuperclass = false,
+            });
+        return;
       } else if (handle == entrypointClasses.workerEntrypoint) {
         impl->statelessClasses.insert(kj::mv(handlerName), kj::mv(cls));
         return;

src/workerd/io/worker.h

@@ -76,6 +76,9 @@ struct EntrypointClasses {
   // Class constructor for DurableObject (aka api::DurableObjectBase).
   jsg::JsObject durableObject;
 
+  // Class constructor for ContainerEntrypoint
+  jsg::JsObject containerEntrypoint;
+
   // Class constructor for WorkflowEntrypoint
   jsg::JsObject workflowEntrypoint;
 };

src/workerd/server/tests/container-client/BUILD.bazel

@@ -7,3 +7,11 @@ wd_test(
     data = ["test.js"],
     tags = ["off-by-default"],
 )
+
+wd_test(
+    size = "enormous",
+    src = "test-entrypoint.wd-test",
+    args = ["--experimental"],
+    data = ["test-entrypoint.js"],
+    tags = ["off-by-default"],
+)