Create primaryStub and deprecate 'primary' field.

[jtolio]

The 'primary' field name is confusing, as it is easy to read code like

if (!this.ctx.storage.primary)

and assume it's a boolean, not a stub. you might think the above is a test to make sure we're not the primary, but because the primary stub is set only on replicas, it's the opposite!

if (!this.ctx.primaryStub)

is easier to read and understand that this is an 'if' checking if we're the primary.

This change also moves the registration location to be outside of .ctx.storage.

Once #6649 is merged, this PR should be retargeted to main.

[jtolio]

This PR was unfortunately moved from #6605

[ask-bonk]

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

This PR adds ctx.primaryStub as a clearer alternative to ctx.storage.primary on DurableObjectState, and adds a @deprecated tag to the old property.

One minor issue:

1. (Medium) The deprecation message on DurableObjectStorage.primary says "Use primaryStub instead" but primaryStub lives on a different object (DurableObjectState, i.e. ctx.primaryStub). A user reading ctx.storage.primary and seeing this deprecation might look for ctx.storage.primaryStub, which doesn't exist. The message should clarify the new location.

[ask-bonk]

I've posted a review on PR #6652 with one medium-severity finding:

The deprecation message on DurableObjectStorage.primary says "Use primaryStub instead" but primaryStub lives on DurableObjectState (ctx.primaryStub), not on DurableObjectStorage. Users seeing the deprecation on ctx.storage.primary would naturally look for ctx.storage.primaryStub, which doesn't exist. I suggested changing the message to "Use ctx.primaryStub instead" across the three affected files (types/src/cloudflare.ts and both generated snapshots).

The rest of the implementation looks correct — the JSG_LAZY_READONLY_INSTANCE_PROPERTY usage is appropriate since the underlying maybePrimary never changes after construction, the delegation through storage->getPrimary() is safe, and the compat flag gating is consistent.

github run

[codecov-commenter]

Codecov Report

❌ Patch coverage is 0% with 6 lines in your changes missing coverage. Please review.
✅ Project coverage is 66.42%. Comparing base (2684b54) to head (0864429).

Files with missing lines	Patch %	Lines
src/workerd/api/actor-state.c++	0.00%	6 Missing ⚠️

Additional details and impacted files

@@                          Coverage Diff                           @@
##           jolio/move-config-read-replication    #6652      +/-   ##
======================================================================
- Coverage                               66.44%   66.42%   -0.02%     
======================================================================
  Files                                     405      405              
  Lines                                  116106   116112       +6     
  Branches                                19433    19434       +1     
======================================================================
- Hits                                    77148    77131      -17     
- Misses                                  27377    27401      +24     
+ Partials                                11581    11580       -1     

☔ 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.

[codspeed-hq]

Merging this PR will not alter performance

✅ 72 untouched benchmarks
⏩ 129 skipped benchmarks¹

---

_{Comparing jolio/add-ctx-primaryStub (56a2896) with main (4028835)²}

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. ↩

2. No successful run was found on jolio/move-config-read-replication (2684b54) during the generation of this report, so main (4028835) was used instead as the comparison base. There might be some changes unrelated to this pull request in this report. ↩

[justin-mp]

I think this PR is fine, but you should invert the PR ordering so that this one is a parent of #6649 since being able to use getPrimary would help you significantly clean up #6649 .

It's probably worth dropping a TODO(cleanup) in the DurableObjectState::getPrimary implementation noting that we probably want getPrimary in that class rather than in DurableObjectStorage. (If you have any ideas on how we might move the implementation of getPrimary out of DurableObjectStorage once we've removed the primary API, please put them in the TODO.)

[justin-mp]

For my own education, why do we document this here? If someone doesn't have the experimental flag set, would they see this?

[jtolio]

so two things I have discovered:

• annotations added to this file do not do anything unless the field getting documented is actually visible somewhere, so, for the purposes of non-experimental annotations, this is a no-op.
• we actually do generate typescript annotations and docstrings for experimental-only flag fields, but they are in an experimental output folder (types/generated-snapshot/experimental).

i don't honestly know what we do with stuff in types/generated-snapshot/experimental. i assume customers don't see it, but if it was not used at all would it be in here? anyway, at the advice of the Bonk bot earlier in the thread it seemed harmless enough to add.

[jasnell]

Typically, by convention, we try to keep the naming aligned.. e.g. primaryStub -> getPrimaryStub. Since the getPrimary method here is being added, is there a reason not to align the names?

[jtolio]

good point, will fix, if i can figure out how to reopen this PR

[jtolio]

fixed in the new pr

[jtolio]

Cool, Github! That's exactly what I wanted to have happen.

Merged. jtolio merged 0 commits into jolio/move-config-read-replication from jolio/add-ctx-primaryStub

[jtolio]

Moved to #6663