Skip to content

Let plugins make references that survive across incarnations and nodes - #1246

Open
akbashev wants to merge 1 commit into
apple:mainfrom
akbashev:plugin-actor-references
Open

akbashev wants to merge 1 commit into
apple:mainfrom
akbashev:plugin-actor-references

Conversation

@akbashev

@akbashev akbashev commented Oct 2, 2026 •

Copy link
Copy Markdown
Contributor

Some actors are run by a plugin, like the cluster singleton or a virtual actor. The plugin can stop such an actor and start it again, possibly on another node. Each time, the actor gets a new ActorID.

So holding an ActorID isn't enough: once the plugin restarts the actor, calls to the old ID fail. Callers need a reference that the plugin always routes to the actor that's running now.

The singleton plugin builds such references with interceptCalls, but:

  • interceptCalls is internal, so plugins outside DistributedCluster can't use it;
  • the routing lives only on the node that made the reference, so a reference sent to another node stops being routed there.

What changed

All additive. Existing behaviour is unchanged.

  • RemoteCallInterceptor and interceptCalls(to:metadata:interceptor:) are public. interceptCalls no longer ignores its metadata.
  • forwardCall(to: ActorID, …) / forwardCallVoid deliver a call to an actor by ID, locally or remotely.
  • ClusterSystemSettings.propagateMetadata(\.key) opts a metadata key into travelling with IDs. It also fixes custom metadata being dropped by ActorID.init(from:).
  • ActorLifecyclePlugin.interceptor(for:) (default nil) lets a plugin intercept IDs it recognises when they're decoded on another node.

Result

cluster-virtual-actors' getActor returns such a reference. A reference kept on another node keeps working after the actor is deactivated: the next call starts the actor again and reaches it. If the actor can't be started, for example because no node hosts virtual actors, the call fails with that error.

Open questions

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant