Fix ordering: apply x-partykit-room header before ensureInitialized

The first pass of PR #381 ran #ensureInitialized() BEFORE applying the
x-partykit-room header fallback. For DOs with ctx.id.name undefined and
no __ps_name storage record, that meant onStart() ran against an unset
#_name and threw if it read this.name.

Restore the 0.5.0 ordering: pre-populate #_name from the header before
ensureInitialized runs, so onStart() sees the correct name regardless
of which source provided it. The resolvability throw is now a final
check after ensureInitialized.

Resolution priority is now: ctx.id.name > x-partykit-room header >
legacy __ps_name storage. Storage only wins when neither of the other
two supplies the name.

Adds HeaderOnlyOnStartServer + a regression test covering the
newUniqueId + x-partykit-room + onStart-reads-name path.

Made-with: Cursor

Author: threepointone

packages/partyserver/src/index.ts

@@ -389,24 +389,24 @@ export class Server<
         this.#_props = JSON.parse(props);
       }
 
-      // Name resolution in `#ensureInitialized()` consults
-      // `ctx.id.name`, then a legacy storage record, so by the time it
-      // returns `this.name` is populated for any properly-addressed
-      // DO or any DO bootstrapped via the legacy `__ps_name` storage
-      // record (e.g. Cloudflare Agents facets). The only remaining
-      // case is a caller that bypasses both — then we fall back to
-      // the `x-partykit-room` request header.
+      // Name resolution priority: ctx.id.name > x-partykit-room header
+      // > legacy __ps_name storage record. Pre-populate from the header
+      // BEFORE `#ensureInitialized()` so that `onStart()` sees the name
+      // regardless of how it was supplied. `#ensureInitialized()` will
+      // fall back to reading storage when neither ctx.id.name nor the
+      // header has provided one.
+      if (!this.ctx.id.name && !this.#_name) {
+        const room = request.headers.get("x-partykit-room");
+        if (room) this.#_name = room;
+      }
+
       await this.#ensureInitialized();
 
       if (!this.ctx.id.name && !this.#_name) {
-        const room = request.headers.get("x-partykit-room");
-        if (!room) {
-          throw new Error(`Cannot determine the name for ${this.#ParentClass.name}: this.ctx.id.name is undefined, no legacy __ps_name storage record is present, and no x-partykit-room header was supplied. Likely causes:
+        throw new Error(`Cannot determine the name for ${this.#ParentClass.name}: this.ctx.id.name is undefined, no legacy __ps_name storage record is present, and no x-partykit-room header was supplied. Likely causes:
   1. The stub was built via idFromString()/newUniqueId(). PartyServer requires name-based addressing (idFromName/getByName).
   2. The workerd/wrangler runtime is too old to expose ctx.id.name — update to a recent wrangler release.
   3. You called stub.fetch() directly without going through routePartykitRequest()/getServerByName(). Prefer those, or set the x-partykit-room header.`);
-        }
-        this.#_name = room;
       }
 
       const url = new URL(request.url);

packages/partyserver/src/tests/index.test.ts

@@ -699,6 +699,29 @@ describe("this.name in the constructor", () => {
   });
 });
 
+describe("x-partykit-room header applied before onStart", () => {
+  it("populates this.name from header before onStart runs", async () => {
+    // Regression guard: for DOs with `ctx.id.name === undefined` where
+    // the caller supplies the name via `x-partykit-room`, the header
+    // must be applied BEFORE `#ensureInitialized()` runs `onStart()`.
+    // Otherwise an onStart that reads `this.name` would throw.
+    const id = env.HeaderOnlyOnStartServer.newUniqueId();
+    const stub = env.HeaderOnlyOnStartServer.get(id);
+    const res = await stub.fetch(
+      new Request("http://example.com/", {
+        headers: { "x-partykit-room": "header-onstart-test" }
+      })
+    );
+    expect(res.status).toBe(200);
+    const data = (await res.json()) as {
+      name: string;
+      onStartName: string | null;
+    };
+    expect(data.name).toBe("header-onstart-test");
+    expect(data.onStartName).toBe("header-onstart-test");
+  });
+});
+
 describe("Framework bootstrap fallback (Agents facets etc.)", () => {
   it("hydrates this.name from __ps_name storage when ctx.id.name is undefined", async () => {
     // Regression guard for Cloudflare Agents facets. Facets are spawned

packages/partyserver/src/tests/worker.ts

@@ -15,6 +15,7 @@ export type Env = {
   AlarmServer: DurableObjectNamespace<AlarmServer>;
   AlarmNameServer: DurableObjectNamespace<AlarmNameServer>;
   NoNameServer: DurableObjectNamespace<NoNameServer>;
+  HeaderOnlyOnStartServer: DurableObjectNamespace<HeaderOnlyOnStartServer>;
   FacetLikeBootstrapServer: DurableObjectNamespace<FacetLikeBootstrapServer>;
   NameInConstructorServer: DurableObjectNamespace<NameInConstructorServer>;
   Mixed: DurableObjectNamespace<Mixed>;
@@ -257,6 +258,29 @@ export class NoNameServer extends Server {
   }
 }
 
+/**
+ * Regression guard: DO with `ctx.id.name === undefined` (because it was
+ * addressed via `newUniqueId()`) whose `onStart()` reads `this.name`.
+ * When the caller supplies the name via the `x-partykit-room` header,
+ * `Server.fetch()` must apply the header BEFORE running `onStart()`, so
+ * `this.name` is readable during `onStart()`.
+ */
+export class HeaderOnlyOnStartServer extends Server {
+  onStartName: string | null = null;
+
+  async onStart() {
+    // Throws if `this.name` isn't resolvable here.
+    this.onStartName = this.name;
+  }
+
+  onRequest(): Response {
+    return Response.json({
+      name: this.name,
+      onStartName: this.onStartName
+    });
+  }
+}
+
 /**
  * Simulates a framework-level bootstrap pattern (e.g. Cloudflare Agents
  * facets) where the DO is NOT addressed via `idFromName()` — so

packages/partyserver/src/tests/wrangler.jsonc

@@ -87,6 +87,10 @@
         "name": "PropsServer",
         "class_name": "PropsServer"
       },
+      {
+        "name": "HeaderOnlyOnStartServer",
+        "class_name": "HeaderOnlyOnStartServer"
+      },
       {
         "name": "FacetLikeBootstrapServer",
         "class_name": "FacetLikeBootstrapServer"
@@ -120,6 +124,7 @@
         "UriServer",
         "UriServerInMemory",
         "PropsServer",
+        "HeaderOnlyOnStartServer",
         "FacetLikeBootstrapServer",
         "NameInConstructorServer"
       ]