Skip to content

Commit 8b6ec16

Browse files
authored
docs: fix broken tag on the docs site and update changelogs (#1338)
1 parent 5ab619b commit 8b6ec16

2 files changed

Lines changed: 21 additions & 18 deletions

File tree

changelogs/unreleased.md

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,3 +3,9 @@
33
## 🔧 Fixes
44

55
- **Cluster membership events follow routing table convergence** ([#1331](https://github.com/Tochemey/goakt/issues/1331)). `NodeLeft` and `NodeJoined` are now published once the cluster's routing table has converged on the membership change, using the member set olric announces with each convergence, instead of waiting for the single rebalance epoch started for the change. A departure whose epoch was superseded by a later routing table push used to surface only through the 30s fallback timer, and a join in the same situation could go unreported until the next join. A node that joins and departs, or departs and restarts, before the table converges is announced in the order the converged member set implies. A member that departs, restarts at the same address and departs again is announced each time, where the second departure was previously lost. A join whose convergence never comes is announced after the same 30s bound as a departure, and that wait is cancelled as soon as the event is announced or the actor system stops.
6+
7+
- **Actors and grains carry their role constraint through relocation and remote activation** ([#1334](https://github.com/Tochemey/goakt/issues/1334)). The required role was dropped from every wire path that recreates an actor or grain on another node: `SpawnOn` did not forward the actor's `WithRole` in the remote spawn request, and neither the grain's cluster record nor the remote activation request carried `WithActivationRole`, so a relocated or remotely activated grain also lost the constraint for all later relocations. All of these paths now transport the role, and relocation honors it for grains the way it already did for actors: each eager grain activated with `WithActivationRole` is reassigned to the least-loaded surviving node advertising its role (the leader qualifies like any peer), and when no surviving node does, the grain is reported in `RelocationFailed` instead of being reactivated on an ineligible node. Lazy grains remain unconstrained during relocation because their handoff only releases a directory entry; the role is re-applied when the grain is next activated.
8+
9+
## 📦 Dependencies
10+
11+
- Updated Go to v1.26.6 (`go.mod` and the build Dockerfile).

docs/actor/relocation.mdx

Lines changed: 15 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,18 @@
11
---
22
title: Relocation
33
description: Automatic actor migration when nodes leave the cluster.
4-
sidebarTitle: "Relocation"
4+
sidebarTitle: 'Relocation'
55
---
66

77
**Relocation** is the automatic migration of actors and grains from a node that has left the cluster to the remaining
88
live nodes. Whether a node shuts down **gracefully** or **crashes**, its relocatable actors and grains are recreated on
99
other nodes so the cluster remains available.
1010

1111
<Note>
12-
Relocation works for both graceful and abrupt departures. On a graceful shutdown the departing node replicates a
13-
`PeerState` snapshot to its oldest peers. On a crash (`kill -9`, OOM, network partition) that snapshot never gets
14-
written, so the leader instead reconstructs the departed node's relocation set from the replicated cluster registry.
15-
Actors spawned with `WithRelocationDisabled` are still lost with the node either way.
12+
Relocation works for both graceful and abrupt departures. On a graceful shutdown the departing node replicates a `PeerState` snapshot to
13+
its oldest peers. On a crash (`kill -9`, OOM, network partition) that snapshot never gets written, so the leader instead reconstructs the
14+
departed node's relocation set from the replicated cluster registry. Actors spawned with `WithRelocationDisabled` are still lost with the
15+
node either way.
1616
</Note>
1717

1818
## When relocation happens
@@ -113,9 +113,8 @@ Item failures are isolated: a failing actor, grain, or peer never aborts the res
113113
self-heals when the grain is next addressed.
114114

115115
<Warning>
116-
The relocation handoff uses a batched wire request. During a rolling upgrade, run homogeneous GoAkt versions before
117-
triggering topology changes: an older node cannot process the batched request, and its share is then reassigned to
118-
another peer or reported as failed.
116+
The relocation handoff uses a batched wire request. During a rolling upgrade, run homogeneous GoAkt versions before triggering topology
117+
changes: an older node cannot process the batched request, and its share is then reassigned to another peer or reported as failed.
119118
</Warning>
120119

121120
## Relocation events
@@ -269,9 +268,8 @@ Set `WithReplicaCount(3)` to also tolerate two concurrent node losses, at the co
269268
registry update.
270269

271270
<Warning>
272-
With `WithReplicaCount(1)` there are no backups: the partitions owned by a crashed node are lost with it, and
273-
registry-derived recovery silently misses the affected records. The actor system logs a warning at startup when
274-
clustering runs with a replica count of 1.
271+
With `WithReplicaCount(1)` there are no backups: the partitions owned by a crashed node are lost with it, and registry-derived recovery
272+
silently misses the affected records. The actor system logs a warning at startup when clustering runs with a replica count of 1.
275273
</Warning>
276274

277275
Cases that remain open at any replica count: losing all owners of a partition at once loses its records; a write
@@ -328,9 +326,7 @@ identity, err := actor.GrainOf[*MyGrain](ctx, system, "my-grain", actor.WithGrai
328326
Use this for grains that must stay warm without an external trigger (for example those driving timers, streams, or
329327
background work) that must resume immediately after the host departs.
330328

331-
<Note>
332-
`WithGrainEagerRelocation` and `WithGrainDisableRelocation` are mutually exclusive; configuring both fails validation.
333-
</Note>
329+
<Note>`WithGrainEagerRelocation` and `WithGrainDisableRelocation` are mutually exclusive; configuring both fails validation.</Note>
334330

335331
### Disable relocation system-wide
336332

@@ -392,12 +388,13 @@ Masking is bounded, not unbounded. Each node opens a short handoff window when i
392388

393389
- **ErrActorNotFound**: the actor could not be resolved on any surviving node.
394390
- **ErrRelocationInProgress**: the target is still being relocated; retry shortly.
395-
</Note>
391+
392+
</Note>
396393

397394
<Warning>
398-
Identity-based routing (`SendAsync` / `SendSync` and their `ReceiveContext` wrappers) re-resolves the target on each
399-
send, so both observe the relocation. Holding a stale remote `*PID` obtained before the departure and calling `Tell` /
400-
`Ask` on it directly bypasses re-resolution and can still surface a connection error, so resolve by name during churn.
395+
Identity-based routing (`SendAsync` / `SendSync` and their `ReceiveContext` wrappers) re-resolves the target on each send, so both observe
396+
the relocation. Holding a stale remote `*PID` obtained before the departure and calling `Tell` / `Ask` on it directly bypasses
397+
re-resolution and can still surface a connection error, so resolve by name during churn.
401398
</Warning>
402399

403400
## Check relocatability

0 commit comments

Comments
 (0)