Port akka-core#31859: Improve StopShards coordinator command

[pjfanning]

Part of #2730

See #2782

Ports akka/akka-core#31859 — improves the StopShards coordinator command with proper guards, correctness fixes, and serialization support.

ShardCoordinator changes

• Guard: rememberEntities — logs error and ignores StopShards (incompatible combination)
• Guard: no known regions / shutting down — logs warning and ignores instead of silently misbehaving
• Immediate ack for already-stopped shards — sends ShardStopped immediately rather than hanging
• Skip already-rebalancing shards — avoids double-stopping; they'll ack when rebalance completes
• Timeout mechanism — StopShardTimeout cleans up waiting actors after handOffTimeout elapses

Serialization

Added protobuf serialization for StopShards so the command can be sent across nodes (e.g., from a ShardRegion proxy to the coordinator):

• Added StopShards message to ClusterShardingMessages.proto
• Updated generated ClusterShardingMessages.java
• Added "ST" manifest + stopShardsToProto/stopShardsFromBinary to ClusterShardingMessageSerializer

Tests

• StopShardsSpec — 2-node cluster test verifying full stop flow including ShardStopped acks and entity termination
• ClusterShardingMessageSerializerSpec — serialization roundtrip for StopShards

Usage

// Send from any node (via ShardRegion proxy or directly to coordinator)
shardRegion ! ShardCoordinator.Internal.StopShards(Set("shard-1", "shard-2"))
// Receive one ShardStopped per shard once stopped
expectMsgType[ShardStopped]

[Copilot]

Pull request overview

Ports Akka improvements to the Cluster Sharding StopShards coordinator command, making it safer/correcter under various coordinator states and enabling cross-node usage via protobuf serialization.

Changes:

• Harden ShardCoordinator handling of StopShards (guards, correct region targeting, immediate acks, timeout cleanup).
• Add protobuf schema + serializer support for StopShards ("ST" manifest).
• Add/extend tests covering StopShards serialization and a 2-node stop flow.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
cluster-sharding/src/test/scala/org/apache/pekko/cluster/sharding/protobuf/ClusterShardingMessageSerializerSpec.scala	Adds a serialization roundtrip test for StopShards.
cluster-sharding/src/test/scala/org/apache/pekko/cluster/sharding/StopShardsSpec.scala	New 2-node cluster spec exercising StopShards and ShardStopped acks.
cluster-sharding/src/main/scala/org/apache/pekko/cluster/sharding/protobuf/ClusterShardingMessageSerializer.scala	Adds "ST" manifest and protobuf (de)serialization for StopShards.
cluster-sharding/src/main/scala/org/apache/pekko/cluster/sharding/ShardCoordinator.scala	Implements guarded, region-aware StopShards execution plus timeout cleanup.
cluster-sharding/src/main/protobuf/ClusterShardingMessages.proto	Adds protobuf message definition for StopShards.
cluster-sharding/src/main/java/org/apache/pekko/cluster/sharding/protobuf/msg/ClusterShardingMessages.java	Regenerated protobuf Java output including StopShards.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[He-Pin]

lgtm