Split ReplicationChannel into ServerChannel and ClientChannel

For clarity. While doing so, I noticed that we register an extra client
channel. While the server requires two channels, the client only needs
one.

Author: Shatur

CHANGELOG.md

@@ -26,6 +26,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Component removals and insertions for an entity are now buffered and applied as bundles to avoid triggering observers without all components being inserted or removed. This also significantly improves performance by avoiding extra archetype moves and lookups.
 - The `Replicated` component is no longer automatically inserted into non-replicated entities spawned from replicated components.
 - Replace `ServerEntityMap::get_by_*` and `ServerEntityMap::remove_by_*` with an entry-based API. Use `ServerEntityMap::server_entry` or `ServerEntityMap::client_entry` instead.
+- Split `ReplicationChannel` into `ServerChannel` and `ClientChannel` for clarity.
+- Don't register an additional unreliable client channel for replication. While the server requires two channels, the client only needs one.
 - Print error instead of panic on mapping overwrite in `ServerEntityMap`.
 
 ### Removed

src/client.rs

@@ -12,7 +12,7 @@ use postcard::experimental::max_size::MaxSize;
 use crate::shared::{
     backend::{
         ClientState,
-        replicon_channels::{ReplicationChannel, RepliconChannels},
+        replicon_channels::{ClientChannel, RepliconChannels, ServerChannel},
         replicon_client::RepliconClient,
     },
     entity_serde, postcard_utils,
@@ -87,10 +87,10 @@ impl Plugin for ClientPlugin {
 
 /// Receives and applies replication messages from the server.
 ///
-/// Update messages are sent over the [`ReplicationChannel::Updates`] and are applied first to ensure valid state
+/// Update messages are sent over the [`ServerChannel::Updates`] and are applied first to ensure valid state
 /// for component mutations.
 ///
-/// Mutate messages are sent over [`ReplicationChannel::Mutations`], which means they may appear
+/// Mutate messages are sent over [`ServerChannel::Mutations`], which means they may appear
 /// ahead-of or behind update messages from the same server tick. A mutation will only be applied if its
 /// update tick has already appeared in an update message, otherwise it will be buffered while waiting.
 /// Since component mutations can arrive in any order, they will only be applied if they correspond to a more
@@ -180,7 +180,7 @@ fn apply_replication(
     client: &mut RepliconClient,
     buffered_mutations: &mut BufferedMutations,
 ) -> Result<()> {
-    for mut message in client.receive(ReplicationChannel::Updates) {
+    for mut message in client.receive(ServerChannel::Updates) {
         apply_update_message(world, params, &mut message)?;
     }
 
@@ -191,14 +191,14 @@ fn apply_replication(
     // (unless user requested history via marker).
     let update_tick = *world.resource::<ServerUpdateTick>();
     let acks_size =
-        MutateIndex::POSTCARD_MAX_SIZE * client.received_count(ReplicationChannel::Mutations);
+        MutateIndex::POSTCARD_MAX_SIZE * client.received_count(ServerChannel::Mutations);
     if acks_size != 0 {
         let mut acks = Vec::with_capacity(acks_size);
-        for message in client.receive(ReplicationChannel::Mutations) {
+        for message in client.receive(ServerChannel::Mutations) {
             let mutate_index = buffer_mutate_message(params, buffered_mutations, message)?;
             postcard_utils::to_extend_mut(&mutate_index, &mut acks)?;
         }
-        client.send(ReplicationChannel::Updates, acks);
+        client.send(ClientChannel::MutationAcks, acks);
     }
 
     apply_mutate_messages(world, params, buffered_mutations, update_tick)

src/lib.rs

@@ -102,7 +102,7 @@ It can be disabled by setting [`ServerPlugin::replicate_after_connect`] to `fals
 some components on connected clients are only present after replication starts.
 See the required components for [`ReplicatedClient`].
 
-For implementation details see [`ReplicationChannel`](shared::backend::replicon_channels::ReplicationChannel).
+For implementation details see [`ServerChannel`](shared::backend::replicon_channels::ServerChannel).
 
 ### Tick rate
 
@@ -589,7 +589,7 @@ You can control marker priority or enable processing of old values using [`AppMa
 ### Ticks information
 
 This requires an understanding of how replication works. See the documentation on
-[`ReplicationChannel`](shared::backend::replicon_channels::ReplicationChannel) and [this section](#eventual-consistency) for more details.
+[`ServerChannel`](shared::backend::replicon_channels::ServerChannel) and [this section](#eventual-consistency) for more details.
 
 To get information about confirmed ticks for individual entities, we provide
 [`ConfirmHistory`](client::confirm_history::ConfirmHistory) along with the [`EntityReplicated`](client::confirm_history::ConfirmHistory)

src/server.rs

@@ -25,7 +25,7 @@ use crate::shared::{
     backend::{
         ServerState,
         connected_client::ConnectedClient,
-        replicon_channels::{ReplicationChannel, RepliconChannels},
+        replicon_channels::{ClientChannel, RepliconChannels},
         replicon_server::RepliconServer,
     },
     event::server_event::BufferedServerEvents,
@@ -223,7 +223,7 @@ fn receive_acks(
     mut clients: Query<&mut ClientTicks>,
     mut entity_buffer: ResMut<EntityBuffer>,
 ) {
-    for (client_entity, mut message) in server.receive(ReplicationChannel::Updates) {
+    for (client_entity, mut message) in server.receive(ClientChannel::MutationAcks) {
         while message.has_remaining() {
             match postcard_utils::from_buf(&mut message) {
                 Ok(mutate_index) => {

src/server/replication_messages/mutations.rs

@@ -5,7 +5,7 @@ use postcard::experimental::{max_size::MaxSize, serialized_size};
 
 use super::{change_ranges::ChangeRanges, serialized_data::SerializedData};
 use crate::shared::{
-    backend::{replicon_channels::ReplicationChannel, replicon_server::RepliconServer},
+    backend::{replicon_channels::ServerChannel, replicon_server::RepliconServer},
     postcard_utils,
     replication::{
         client_ticks::{ClientTicks, EntityBuffer},
@@ -147,7 +147,7 @@ impl Mutations {
     /// independently on the client.
     /// Message splits only happen per-entity to avoid weird behavior from partial entity mutations.
     ///
-    /// Sent over the [`ReplicationChannel::Mutations`] channel. If the message gets lost, we try to resend it manually,
+    /// Sent over the [`ServerChannel::Mutations`] channel. If the message gets lost, we try to resend it manually,
     /// using the last up-to-date mutations to avoid re-sending old values.
     pub(crate) fn send(
         &mut self,
@@ -231,7 +231,7 @@ impl Mutations {
 
             debug_assert_eq!(message.len(), message_size);
 
-            server.send(client_entity, ReplicationChannel::Mutations, message);
+            server.send(client_entity, ServerChannel::Mutations, message);
         }
 
         Ok(self.messages.len())

src/server/replication_messages/updates.rs

@@ -6,7 +6,7 @@ use postcard::experimental::serialized_size;
 use super::{change_ranges::ChangeRanges, mutations::Mutations, serialized_data::SerializedData};
 use crate::server::client_visibility::Visibility;
 use crate::shared::{
-    backend::{replicon_channels::ReplicationChannel, replicon_server::RepliconServer},
+    backend::{replicon_channels::ServerChannel, replicon_server::RepliconServer},
     postcard_utils,
     replication::update_message_flags::UpdateMessageFlags,
 };
@@ -180,7 +180,7 @@ impl Updates {
     /// Contains tick, mappings, insertions, removals, and despawns that
     /// happened in this tick.
     ///
-    /// Sent over [`ReplicationChannel::Updates`] channel.
+    /// Sent over [`ServerChannel::Updates`] channel.
     ///
     /// Some data is optional, and their presence is encoded in the [`UpdateMessageFlags`] bitset.
     ///
@@ -285,7 +285,7 @@ impl Updates {
 
         debug_assert_eq!(message.len(), message_size);
 
-        server.send(client_entity, ReplicationChannel::Updates, message);
+        server.send(client_entity, ServerChannel::Updates, message);
 
         Ok(())
     }

src/shared/backend/connected_client.rs

@@ -32,7 +32,7 @@ pub struct ConnectedClient {
     /// splitting into multiple packets.
     ///
     /// Used to manually split mutations over packet-size messages to allow applying them partially.
-    /// For more details on replication see [`ReplicationChannel`](super::replicon_channels::ReplicationChannel).
+    /// For more details on replication see [`ServerChannel`](super::replicon_channels::ServerChannel).
     ///
     /// <div class="warning">
     ///

src/shared/backend/replicon_channels.rs

@@ -7,8 +7,7 @@ use log::debug;
 /// [`ServerPlugin::finish`](crate::server::ServerPlugin).
 ///
 /// Channel IDs are represented by [`usize`], but backends may limit the number of channels.
-///
-/// The first two channels are used for replication. For more details, see [`ReplicationChannel`].
+/// See [`ServerChannel`] and [`ClientChannel`] for channels that are always reserved.
 ///
 /// Other channels are used for events, with one channel per event. For more details, see
 /// [`RemoteEventRegistry`](crate::shared::event::remote_event_registry::RemoteEventRegistry).
@@ -30,13 +29,10 @@ impl Default for RepliconChannels {
     fn default() -> Self {
         Self {
             server: vec![
-                ReplicationChannel::Updates.into(),
-                ReplicationChannel::Mutations.into(),
-            ],
-            client: vec![
-                ReplicationChannel::Updates.into(),
-                ReplicationChannel::Mutations.into(),
+                ServerChannel::Updates.into(),
+                ServerChannel::Mutations.into(),
             ],
+            client: vec![ClientChannel::MutationAcks.into()],
         }
     }
 }
@@ -71,7 +67,14 @@ impl RepliconChannels {
     }
 }
 
-/// ID of a server replication channel.
+/// Constant ID of a channel for sending data from server to client.
+///
+/// These channels are always reserved, though additional channels may be required
+/// for remote server events. Use [`RepliconChannels`] to retrieve all channels required for Replicon.
+///
+/// See also [`ClientChannel`].
+///
+/// # Replication channels
 ///
 /// To synchronize the state, we send only changes using Bevy's change detection.
 ///
@@ -108,28 +111,57 @@ impl RepliconChannels {
 ///
 /// See also [`RepliconChannels`], [`Channel`] and [corresponding section](../index.html#eventual-consistency)
 /// from the quick start guide.
-pub enum ReplicationChannel {
+pub enum ServerChannel {
     /// For sending messages with entity mappings, inserts, removals and despawns.
     ///
     /// This is an ordered reliable channel.
     Updates,
     /// For sending messages with component mutations.
     ///
     /// This is an unreliable channel.
+    ///
+    /// See also [`ClientChannel::MutationAcks`].
     Mutations,
 }
 
-impl From<ReplicationChannel> for Channel {
-    fn from(value: ReplicationChannel) -> Self {
+impl From<ServerChannel> for Channel {
+    fn from(value: ServerChannel) -> Self {
+        match value {
+            ServerChannel::Updates => Channel::Ordered,
+            ServerChannel::Mutations => Channel::Unreliable,
+        }
+    }
+}
+
+impl From<ServerChannel> for usize {
+    fn from(value: ServerChannel) -> Self {
+        value as usize
+    }
+}
+
+/// Constant ID of a channel for sending data from client to server.
+///
+/// These channels are always reserved, though additional channels may be required
+/// for remote client events. Use [`RepliconChannels`] to retrieve all channels required for Replicon.
+///
+/// See also [`ServerChannel`].
+pub enum ClientChannel {
+    /// For sending acks to acknowledge mutation messages received from [`ServerChannel::Mutations`].
+    ///
+    /// This is an ordered reliable channel.
+    MutationAcks,
+}
+
+impl From<ClientChannel> for Channel {
+    fn from(value: ClientChannel) -> Self {
         match value {
-            ReplicationChannel::Updates => Channel::Ordered,
-            ReplicationChannel::Mutations => Channel::Unreliable,
+            ClientChannel::MutationAcks => Channel::Ordered,
         }
     }
 }
 
-impl From<ReplicationChannel> for usize {
-    fn from(value: ReplicationChannel) -> Self {
+impl From<ClientChannel> for usize {
+    fn from(value: ClientChannel) -> Self {
         value as usize
     }
 }

src/shared/event/server_event.rs

@@ -148,7 +148,7 @@ pub trait ServerEventAppExt {
     /// has not yet received.
     ///
     /// For more details about replication see the documentation on
-    /// [`ReplicationChannel`](crate::shared::backend::replicon_channels::ReplicationChannel).
+    /// [`ServerChannel`](crate::shared::backend::replicon_channels::ServerChannel).
     ///
     /// However, if you know your event doesn't rely on that, you can mark it
     /// as independent to always emit it immediately. For example, a chat

tests/client_event.rs

@@ -30,7 +30,7 @@ fn channels() {
 
     let event_registry = app.world().resource::<RemoteEventRegistry>();
     assert_eq!(event_registry.client_channel::<NonRemoteEvent>(), None);
-    assert_eq!(event_registry.client_channel::<TestEvent>(), Some(2));
+    assert_eq!(event_registry.client_channel::<TestEvent>(), Some(1));
 }
 
 #[test]

tests/connection.rs

@@ -4,7 +4,7 @@ use bevy_replicon::{
     server::server_tick::ServerTick,
     shared::backend::{
         connected_client::{ConnectedClient, NetworkId, NetworkIdMap},
-        replicon_channels::ReplicationChannel,
+        replicon_channels::{ClientChannel, ServerChannel},
     },
     test_app::ServerTestAppExt,
 };
@@ -21,7 +21,7 @@ fn client_to_server() {
     const MESSAGES: &[&[u8]] = &[&[0], &[1]];
     let mut client = client_app.world_mut().resource_mut::<RepliconClient>();
     for &message in MESSAGES {
-        client.send(ReplicationChannel::Updates, message);
+        client.send(ClientChannel::MutationAcks, message);
     }
 
     let mut server = server_app.world_mut().resource_mut::<RepliconServer>();
@@ -30,7 +30,7 @@ fn client_to_server() {
     }
 
     let messages: Vec<_> = server
-        .receive(ReplicationChannel::Updates)
+        .receive(ServerChannel::Updates)
         .map(|(_, message)| message)
         .collect();
     assert_eq!(messages, MESSAGES);
@@ -48,15 +48,15 @@ fn server_to_client() {
     const MESSAGES: &[&[u8]] = &[&[0], &[1]];
     let mut server = server_app.world_mut().resource_mut::<RepliconServer>();
     for &message in MESSAGES {
-        server.send(Entity::PLACEHOLDER, ReplicationChannel::Updates, message);
+        server.send(Entity::PLACEHOLDER, ServerChannel::Updates, message);
     }
 
     let mut client = client_app.world_mut().resource_mut::<RepliconClient>();
     for (_, channel_id, message) in server.drain_sent() {
         client.insert_received(channel_id, message);
     }
 
-    let messages: Vec<_> = client.receive(ReplicationChannel::Updates).collect();
+    let messages: Vec<_> = client.receive(ServerChannel::Updates).collect();
     assert_eq!(messages, MESSAGES);
 }
 
@@ -102,8 +102,8 @@ fn client_cleanup_on_disconnect() {
     app.world_mut().run_schedule(StateTransition);
 
     let mut client = app.world_mut().resource_mut::<RepliconClient>();
-    client.send(ReplicationChannel::Updates, Vec::new());
-    client.insert_received(ReplicationChannel::Updates, Vec::new());
+    client.send(ServerChannel::Updates, Vec::new());
+    client.insert_received(ServerChannel::Updates, Vec::new());
 
     app.world_mut()
         .resource_mut::<NextState<ClientState>>()
@@ -113,7 +113,7 @@ fn client_cleanup_on_disconnect() {
 
     let mut client = app.world_mut().resource_mut::<RepliconClient>();
     assert_eq!(client.drain_sent().count(), 0);
-    assert_eq!(client.receive(ReplicationChannel::Updates).count(), 0);
+    assert_eq!(client.receive(ServerChannel::Updates).count(), 0);
 }
 
 #[test]
@@ -130,8 +130,8 @@ fn server_cleanup_on_stop() {
     app.world_mut().run_schedule(StateTransition);
 
     let mut server = app.world_mut().resource_mut::<RepliconServer>();
-    server.send(Entity::PLACEHOLDER, ReplicationChannel::Updates, Vec::new());
-    server.insert_received(Entity::PLACEHOLDER, ReplicationChannel::Updates, Vec::new());
+    server.send(Entity::PLACEHOLDER, ServerChannel::Updates, Vec::new());
+    server.insert_received(Entity::PLACEHOLDER, ServerChannel::Updates, Vec::new());
 
     app.world_mut()
         .resource_mut::<NextState<ServerState>>()
@@ -141,7 +141,7 @@ fn server_cleanup_on_stop() {
 
     let mut server = app.world_mut().resource_mut::<RepliconServer>();
     assert_eq!(server.drain_sent().count(), 0);
-    assert_eq!(server.receive(ReplicationChannel::Updates).count(), 0);
+    assert_eq!(server.receive(ServerChannel::Updates).count(), 0);
     assert_eq!(app.world().resource::<ServerTick>().get(), 0);
 }