Add routingMode option to GetDurableObjectOptions

MellowYarker · MellowYarker · commit 3289720f2fb5 · 2025-11-14T11:11:16.000-05:00
diff --git a/src/workerd/api/actor.c++ b/src/workerd/api/actor.c++
@@ -53,11 +53,11 @@ kj::Own<WorkerInterface> GlobalActorOutgoingFactory::newSingleUseClient(
       KJ_SWITCH_ONEOF(channelIdOrFactory) {
         KJ_CASE_ONEOF(channelId, uint) {
           actorChannel = context.getGlobalActorChannel(channelId, id->getInner(),
-              kj::mv(locationHint), mode, enableReplicaRouting, tracing.span);
+              kj::mv(locationHint), mode, enableReplicaRouting, kj::mv(routingMode), tracing.span);
         }
         KJ_CASE_ONEOF(factory, kj::Own<DurableObjectNamespace::ActorChannelFactory>) {
-          actorChannel = factory->getGlobalActor(
-              id->getInner(), kj::mv(locationHint), mode, enableReplicaRouting, tracing.span);
+          actorChannel = factory->getGlobalActor(id->getInner(), kj::mv(locationHint), mode,
+              enableReplicaRouting, kj::mv(routingMode), tracing.span);
         }
       }
     }
@@ -146,24 +146,31 @@ jsg::Ref<DurableObject> DurableObjectNamespace::getImpl(jsg::Lock& js,
     jsg::Optional<GetDurableObjectOptions> options) {
   JSG_REQUIRE(idFactory->matchesJurisdiction(id->getInner()), TypeError,
       "get called on jurisdictional subnamespace with an ID from a different jurisdiction");
+  KJ_IF_SOME(o, options) {
+    KJ_IF_SOME(routingMode, o.routingMode) {
+      JSG_REQUIRE(routingMode == "primary-only", RangeError, "unknown routingMode: ", routingMode);
+    }
+  }
 
   auto& context = IoContext::current();
-  kj::Maybe<kj::String> locationHint = kj::none;
+  kj::Maybe<kj::String> locationHint;
+  kj::Maybe<kj::String> routingMode;
   KJ_IF_SOME(o, options) {
     locationHint = kj::mv(o.locationHint);
+    routingMode = kj::mv(o.routingMode);
   }
 
   bool enableReplicaRouting = FeatureFlags::get(js).getReplicaRouting();
 
   kj::Own<Fetcher::OutgoingFactory> outgoingFactory;
   KJ_SWITCH_ONEOF(channel) {
     KJ_CASE_ONEOF(channelId, uint) {
-      outgoingFactory = kj::heap<GlobalActorOutgoingFactory>(
-          channelId, id.addRef(), kj::mv(locationHint), mode, enableReplicaRouting);
+      outgoingFactory = kj::heap<GlobalActorOutgoingFactory>(channelId, id.addRef(),
+          kj::mv(locationHint), mode, enableReplicaRouting, kj::mv(routingMode));
     }
     KJ_CASE_ONEOF(channelFactory, IoOwn<ActorChannelFactory>) {
       outgoingFactory = kj::heap<GlobalActorOutgoingFactory>(kj::addRef(*channelFactory),
-          id.addRef(), kj::mv(locationHint), mode, enableReplicaRouting);
+          id.addRef(), kj::mv(locationHint), mode, enableReplicaRouting, kj::mv(routingMode));
     }
   }
 
diff --git a/src/workerd/api/actor.h b/src/workerd/api/actor.h
@@ -156,6 +156,7 @@ class DurableObjectNamespace: public jsg::Object {
         kj::Maybe<kj::String> locationHint,
         ActorGetMode mode,
         bool enableReplicaRouting,
+        kj::Maybe<kj::String> routingMode,
         SpanParent parentSpan) = 0;
   };
 
@@ -195,13 +196,22 @@ class DurableObjectNamespace: public jsg::Object {
 
   struct GetDurableObjectOptions {
     jsg::Optional<kj::String> locationHint;
+    // `routingMode` may be be of interest to applications using Durable Objects replicas. It can be
+    // one of the following options:
+    //    - none: the default, indicates we will pick for the application.
+    //    - "primary-only": guarantees we route directly to the primary (skip any replicas.)
+    jsg::Optional<kj::String> routingMode;
 
-    JSG_STRUCT(locationHint);
+    JSG_STRUCT(locationHint, routingMode);
 
-    JSG_STRUCT_TS_DEFINE(type DurableObjectLocationHint = "wnam" | "enam" | "sam" | "weur" | "eeur" | "apac" | "oc" | "afr" | "me");
     // Possible values from https://developers.cloudflare.com/workers/runtime-apis/durable-objects/#providing-a-location-hint
+    JSG_STRUCT_TS_DEFINE(
+      type DurableObjectLocationHint = "wnam" | "enam" | "sam" | "weur" | "eeur" | "apac" | "oc" | "afr" | "me";
+      type DurableObjectRoutingMode = "primary-only");
+
     JSG_STRUCT_TS_OVERRIDE({
       locationHint?: DurableObjectLocationHint;
+      routingMode?: DurableObjectRoutingMode;
     });
   };
 
@@ -270,12 +280,14 @@ class GlobalActorOutgoingFactory final: public Fetcher::OutgoingFactory {
       jsg::Ref<DurableObjectId> id,
       kj::Maybe<kj::String> locationHint,
       ActorGetMode mode,
-      bool enableReplicaRouting)
+      bool enableReplicaRouting,
+      kj::Maybe<kj::String> routingMode)
       : channelIdOrFactory(kj::mv(channelIdOrFactory)),
         id(kj::mv(id)),
         locationHint(kj::mv(locationHint)),
         mode(mode),
-        enableReplicaRouting(enableReplicaRouting) {}
+        enableReplicaRouting(enableReplicaRouting),
+        routingMode(kj::mv(routingMode)) {}
 
   kj::Own<WorkerInterface> newSingleUseClient(kj::Maybe<kj::String> cfStr) override;
 
@@ -285,6 +297,7 @@ class GlobalActorOutgoingFactory final: public Fetcher::OutgoingFactory {
   kj::Maybe<kj::String> locationHint;
   ActorGetMode mode;
   bool enableReplicaRouting;
+  kj::Maybe<kj::String> routingMode;
   kj::Maybe<kj::Own<IoChannelFactory::ActorChannel>> actorChannel;
 };
 
diff --git a/src/workerd/io/io-channels.h b/src/workerd/io/io-channels.h
@@ -208,6 +208,7 @@ class IoChannelFactory {
       kj::Maybe<kj::String> locationHint,
       ActorGetMode mode,
       bool enableReplicaRouting,
+      kj::Maybe<kj::String> routingMode,
       SpanParent parentSpan) = 0;
 
   // Get an actor stub from the given namespace for the actor with the given name.
diff --git a/src/workerd/io/io-context.h b/src/workerd/io/io-context.h
@@ -894,9 +894,10 @@ class IoContext final: public kj::Refcounted, private kj::TaskSet::ErrorHandler
       kj::Maybe<kj::String> locationHint,
       ActorGetMode mode,
       bool enableReplicaRouting,
+      kj::Maybe<kj::String> routingMode,
       SpanParent parentSpan) {
-    return getIoChannelFactory().getGlobalActor(
-        channel, id, kj::mv(locationHint), mode, enableReplicaRouting, kj::mv(parentSpan));
+    return getIoChannelFactory().getGlobalActor(channel, id, kj::mv(locationHint), mode,
+        enableReplicaRouting, kj::mv(routingMode), kj::mv(parentSpan));
   }
   kj::Own<IoChannelFactory::ActorChannel> getColoLocalActorChannel(
       uint channel, kj::StringPtr id, SpanParent parentSpan) {
diff --git a/src/workerd/server/server.c++ b/src/workerd/server/server.c++
@@ -3276,10 +3276,12 @@ class Server::WorkerService final: public Service,
       kj::Maybe<kj::String> locationHint,
       ActorGetMode mode,
       bool enableReplicaRouting,
+      kj::Maybe<kj::String> routingMode,
       SpanParent parentSpan) override {
     JSG_REQUIRE(mode == ActorGetMode::GET_OR_CREATE, Error,
         "workerd only supports GET_OR_CREATE mode for getting actor stubs");
     JSG_REQUIRE(!enableReplicaRouting, Error, "workerd does not support replica routing.");
+    JSG_REQUIRE(routingMode == kj::none, Error, "workerd does not support replica routing.");
     auto& channels =
         KJ_REQUIRE_NONNULL(ioChannels.tryGet<LinkedIoChannels>(), "link() has not been called");
 
diff --git a/src/workerd/tests/test-fixture.c++ b/src/workerd/tests/test-fixture.c++
@@ -104,6 +104,7 @@ struct DummyIoChannelFactory final: public IoChannelFactory {
       kj::Maybe<kj::String> locationHint,
       ActorGetMode mode,
       bool enableReplicaRouting,
+      kj::Maybe<kj::String> routingMode,
       SpanParent parentSpan) override {
     KJ_FAIL_REQUIRE("no actor channels");
   }
diff --git a/types/generated-snapshot/experimental/index.d.ts b/types/generated-snapshot/experimental/index.d.ts
@@ -641,8 +641,10 @@ type DurableObjectLocationHint =
   | "oc"
   | "afr"
   | "me";
+type DurableObjectRoutingMode = "primary-only";
 interface DurableObjectNamespaceGetDurableObjectOptions {
   locationHint?: DurableObjectLocationHint;
+  routingMode?: DurableObjectRoutingMode;
 }
 interface DurableObjectClass<
   _T extends Rpc.DurableObjectBranded | undefined = undefined,
diff --git a/types/generated-snapshot/experimental/index.ts b/types/generated-snapshot/experimental/index.ts
@@ -646,8 +646,10 @@ export type DurableObjectLocationHint =
   | "oc"
   | "afr"
   | "me";
+export type DurableObjectRoutingMode = "primary-only";
 export interface DurableObjectNamespaceGetDurableObjectOptions {
   locationHint?: DurableObjectLocationHint;
+  routingMode?: DurableObjectRoutingMode;
 }
 export interface DurableObjectClass<
   _T extends Rpc.DurableObjectBranded | undefined = undefined,
diff --git a/types/generated-snapshot/latest/index.d.ts b/types/generated-snapshot/latest/index.d.ts
@@ -619,8 +619,10 @@ type DurableObjectLocationHint =
   | "oc"
   | "afr"
   | "me";
+type DurableObjectRoutingMode = "primary-only";
 interface DurableObjectNamespaceGetDurableObjectOptions {
   locationHint?: DurableObjectLocationHint;
+  routingMode?: DurableObjectRoutingMode;
 }
 interface DurableObjectClass<
   _T extends Rpc.DurableObjectBranded | undefined = undefined,
diff --git a/types/generated-snapshot/latest/index.ts b/types/generated-snapshot/latest/index.ts
@@ -624,8 +624,10 @@ export type DurableObjectLocationHint =
   | "oc"
   | "afr"
   | "me";
+export type DurableObjectRoutingMode = "primary-only";
 export interface DurableObjectNamespaceGetDurableObjectOptions {
   locationHint?: DurableObjectLocationHint;
+  routingMode?: DurableObjectRoutingMode;
 }
 export interface DurableObjectClass<
   _T extends Rpc.DurableObjectBranded | undefined = undefined,

Original file line number	Diff line number	Diff line change
`@@ -104,6 +104,7 @@ struct DummyIoChannelFactory final: public IoChannelFactory {`
`104`	`104`	`kj::Maybe<kj::String> locationHint,`
`105`	`105`	`ActorGetMode mode,`
`106`	`106`	`bool enableReplicaRouting,`
	`107`	`+ kj::Maybe<kj::String> routingMode,`
`107`	`108`	`SpanParent parentSpan) override {`
`108`	`109`	`KJ_FAIL_REQUIRE("no actor channels");`
`109`	`110`	`}`