remove child related types, cleanup version

Author: ktoso

Sources/DistributedActors/Cluster/HandshakeStateMachine.swift

@@ -17,14 +17,19 @@ import NIO
 // ==== ----------------------------------------------------------------------------------------------------------------
 // MARK: Protocol version
 
-/// Wire Protocol version of this Swift Distributed Actors build.
-public let DistributedActorsProtocolVersion: ClusterSystem.Version = .init(reserved: 0, major: 1, minor: 0, patch: 0)
+extension ClusterSystem {
+    /// Wire protocol version of this `ClusterSystem`.
+    ///
+    /// This version does not have to match the project version, i.e. a library version `1.5.0` may still be using the protocol version `1.0.0`,
+    /// as this version number is more about the _wire_ compatibility of the underlying protocol, rather than the library capabilities
+    public static let protocolVersion: ClusterSystem.Version = ClusterSystem.Version(reserved: 0, major: 1, minor: 0, patch: 0)
+}
 
 // ==== ----------------------------------------------------------------------------------------------------------------
 // MARK: Constants for Cluster
 
 /// Magic 2 byte value for use as initial bytes in connections (before handshake).
-/// Reads as: `5AC7 == SACT == S Act == Swift/Swift Distributed Actors Act == Swift/Swift Distributed Actors`
+/// Reads as: `5AC7 == SACT == S Act == Swift/ (Distributed) Actors
 internal let HandshakeMagicBytes: UInt16 = 0x5AC7
 
 // ==== ----------------------------------------------------------------------------------------------------------------

Sources/DistributedActors/Cluster/Reception/_OperationLogClusterReceptionistBehavior.swift

@@ -17,9 +17,6 @@ import Logging
 // ==== ----------------------------------------------------------------------------------------------------------------
 // MARK: Cluster (OpLog) Receptionist
 
-/// ClusterReceptionist namespace
-public enum ClusterReceptionist {}
-
 public final class _OperationLogClusterReceptionist {
     typealias Message = Receptionist.Message
     typealias ReceptionistRef = _ActorRef<Message>

Sources/DistributedActors/ClusterSystemSettings.swift

@@ -40,7 +40,7 @@ public struct ClusterSystemSettings {
 
     public var receptionist: ReceptionistSettings = .default
 
-    public var transports: [_InternalActorTransport] = []
+    internal var transports: [_InternalActorTransport] = []
     public var serialization: Serialization.Settings = .default
 
     // ==== ------------------------------------------------------------------------------------------------------------
@@ -124,6 +124,7 @@ public struct ClusterSystemSettings {
     )
 
     /// Defines the Time-To-Live of an association, i.e. when it shall be completely dropped from the tombstones list.
+    ///
     /// An association ("unique connection identifier between two nodes") is kept as tombstone when severing a connection between nodes,
     /// in order to avoid accidental re-connections to given node. Once a node has been downed, removed, and disassociated, it MUST NOT be
     /// communicated with again. Tombstones are used to ensure this, even if the downed ("zombie") node, attempts to reconnect.
@@ -141,7 +142,7 @@ public struct ClusterSystemSettings {
     }
 
     /// FOR TESTING ONLY: Exposed for testing handshake negotiation while joining nodes of different versions.
-    internal var _protocolVersion: ClusterSystem.Version = DistributedActorsProtocolVersion
+    internal var _protocolVersion: ClusterSystem.Version = ClusterSystem.protocolVersion
 
     // ==== ------------------------------------------------------------------------------------------------------------
     // MARK: Cluster.Membership Gossip

Sources/DistributedActors/DistributedActors.docc/Clustering.md

@@ -268,3 +268,24 @@ distributed actor Boss: LifecycleWatch {
     }
 }
 ```
+
+## Customizing Remote Calls
+
+Remote calls are at the heart of what makes distributed actors actually distributed.
+
+A call made on a remote distributed actor reference, will cross network boundaries, and therefore may way due to 
+network issues, message loss, serialization errors, or other reasons such as the recipient node crashing as it 
+processes the message. Even replies to remote calls could sometimes fail being delivered, so you might need to 
+design your distributed actors with idempotency (the resilience of a method being called more than once, e.g. due to a retry) in mind.
+
+By default, to avoid "hanging" a remote caller forever on a suspended remote call as the recipient node fails to reply to it,
+for example because it (or the network itself), are currently unresponsive, remote calls have a default timeout configured,
+and if no reply is received within this duration, the call will fail with a ``RemoteCallError``.
+
+You can configure the default timeout used by the cluster system during its initialization:
+
+```swift
+ClusterSystem() { settings in 
+    settings.
+}
+```

Sources/DistributedActors/Plugins/ClusterSystemSettings+Plugins.swift

@@ -60,17 +60,6 @@ public struct PluginsSettings {
         }
     }
 
-//    /// Stops all plugins in the *reversed* order as they were added.
-//    internal func stopAll(_ transport: ActorClusterTransport) async {
-//        // Shut down in reversed order so plugins with the fewest dependencies are stopped first!
-//        for plugin in self.plugins.reversed() {
-//            do {
-//                try await plugin.stop(transport)
-//            } catch {
-//                fatalError("Failed to stop plugin \(plugin.key)! Error: \(error)")
-//            }
-//        }
-//    }
 }
 
 extension PluginsSettings {

Sources/DistributedActors/SystemMessages.swift

@@ -64,7 +64,7 @@ public enum _SystemMessage: Equatable {
 
     /// Child actor has terminated. This system message by itself does not necessarily cause a DeathPact and termination of the parent.
     /// If the message carries an `escalated` failure, the failure should apply to the parent as well, potentially tearing it down as well.
-    case childTerminated(ref: _AddressableActorRef, TerminationCircumstances)
+    case childTerminated(ref: _AddressableActorRef, _TerminationCircumstances)
 
     /// Node has terminated, and all actors of this node shall be considered as terminated.
     /// This system message does _not_ have a direct counter part as `Signal`, and instead results in the sending of multiple
@@ -92,8 +92,9 @@ public enum _SystemMessage: Equatable {
     case tombstone
 }
 
+// TODO: Child actors are being removed
 /// The circumstances under which a child actor has terminated.
-public enum TerminationCircumstances {
+public enum _TerminationCircumstances {
     /// The actor stopped naturally, by becoming `.stop`
     case stopped
     /// The actor has failed during message processing.

Sources/DistributedActors/Version.swift

@@ -13,7 +13,8 @@
 //===----------------------------------------------------------------------===//
 
 extension ClusterSystem {
-    /// Version of the cluster system, as advertised to other nodes while joining the cluster.
+    /// Version advertised to other nodes while joining the cluster.
+    /// 
     /// Can be used to determine wire of feature compatibility of nodes joining a cluster.
     public struct Version: Equatable, CustomStringConvertible {
         /// Exact semantics of the reserved field remain to be defined.