Add a mode to the Rust SDK with additional logging to a file (#4566)

# Description of Changes

In the Rust client SDK, with this PR, doing
`.with_debug_to_file("path.txt")` on the connection builder will result
in the SDK logging additional verbose info to `path.txt`.

# API and ABI breaking changes

Adds a new user-facing-ish API to the Rust client SDK.

# Expected complexity level and risk

2? Some possibility of deadlock due to adding a new mutex, but this is
explicitly not for production use.

# Testing

- [x] Ran `chat-console-rs` locally with this enabled and got some debug
logs out of it.

Author: gefjon

crates/codegen/src/rust.rs

@@ -1308,7 +1308,7 @@ impl __sdk::InModule for Reducer {{
 }
 
 fn print_db_update_defn(module: &ModuleDef, visibility: CodegenVisibility, out: &mut Indenter) {
-    writeln!(out, "#[derive(Default)]");
+    writeln!(out, "#[derive(Default, Debug)]");
     writeln!(out, "#[allow(non_snake_case)]");
     writeln!(out, "#[doc(hidden)]");
     out.delimited_block(
@@ -1616,6 +1616,7 @@ fn print_const_db_context_types(out: &mut Indenter) {
         out,
         "
 #[doc(hidden)]
+#[derive(Debug)]
 pub struct RemoteModule;
 
 impl __sdk::InModule for RemoteModule {{

crates/codegen/tests/snapshots/codegen__codegen_rust.snap

@@ -1230,7 +1230,7 @@ _ => unreachable!(),
 }
 }
 
-#[derive(Default)]
+#[derive(Default, Debug)]
 #[allow(non_snake_case)]
 #[doc(hidden)]
 pub struct DbUpdate {
@@ -1346,6 +1346,7 @@ impl<'r> __sdk::AppliedDiff<'r> for AppliedDiff<'r> {
 
 
 #[doc(hidden)]
+#[derive(Debug)]
 pub struct RemoteModule;
 
 impl __sdk::InModule for RemoteModule {

sdks/rust/src/client_cache.rs

@@ -3,14 +3,17 @@
 //! This module is internal, and may incompatibly change without warning.
 
 use crate::callbacks::CallbackId;
-use crate::db_connection::{PendingMutation, SharedCell};
+use crate::db_connection::{debug_log, PendingMutation, SharedCell};
 use crate::spacetime_module::{InModule, SpacetimeModule, TableUpdate, WithBsatn};
 use anymap::{any::Any, Map};
 use bytes::Bytes;
 use core::any::type_name;
 use core::hash::Hash;
 use futures_channel::mpsc;
 use spacetimedb_data_structures::map::{hash_map::Entry, HashCollectionExt, HashMap};
+use std::fmt::Debug;
+use std::fs::File;
+use std::io::Write;
 use std::marker::PhantomData;
 use std::sync::Arc;
 
@@ -35,6 +38,9 @@ pub struct TableCache<Row> {
     /// Entries are added to this map during [`crate::DbConnectionBuilder::build`],
     /// via a `register_table` function autogenerated for each table.
     pub(crate) unique_indices: HashMap<&'static str, Box<dyn UniqueIndexDyn<Row = Row>>>,
+
+    /// Clone of the [`crate::db_connection::DbContextImpl::extra_logging`].
+    extra_logging: Option<SharedCell<File>>,
 }
 
 /// Stores an entry of the typed row value together with its ref count in the table cache.
@@ -59,11 +65,12 @@ pub(crate) struct RowEntry<Row> {
 }
 
 // Can't derive this because the `Row` generic messes us up.
-impl<Row> Default for TableCache<Row> {
-    fn default() -> Self {
+impl<Row> TableCache<Row> {
+    fn new(extra_logging: Option<SharedCell<File>>) -> Self {
         Self {
             entries: Default::default(),
             unique_indices: Default::default(),
+            extra_logging,
         }
     }
 }
@@ -185,7 +192,13 @@ impl<'r, Row> TableAppliedDiff<'r, Row> {
     }
 }
 
-impl<Row: Clone + Send + Sync + 'static> TableCache<Row> {
+impl<Row> TableCache<Row> {
+    fn debug_log(&self, body: impl FnOnce(&mut File) -> std::result::Result<(), std::io::Error>) {
+        debug_log(&self.extra_logging, body);
+    }
+}
+
+impl<Row: Clone + Debug + Send + Sync + 'static> TableCache<Row> {
     fn handle_delete<'r>(
         &mut self,
         inserts: &mut RowEventMap<'_, Row>,
@@ -195,8 +208,16 @@ impl<Row: Clone + Send + Sync + 'static> TableCache<Row> {
         // Extract the entry and decrement the `ref_count`.
         // Only create a delete event if `ref_count = 0`.
         let Entry::Occupied(mut entry) = self.entries.entry(delete.bsatn.clone()) else {
+            self.debug_log(|file| {
+                writeln!(file, "`handle_delete` for table with row type {}: a delete update should correspond to an existing row in the table cache, but the row {delete:?} was not present", std::any::type_name::<Row>())?;
+                writeln!(file, "table contents:")?;
+                for (bsatn, RowEntry { row, ref_count }) in self.entries.iter() {
+                    writeln!(file, "\t{bsatn:?}\n\t\t{row:?}\n\t\tref_count {ref_count}")?;
+                }
+                Ok(())
+            });
             // We're guaranteed to never hit this as long as we apply inserts before deletes.
-            unreachable!("a delete update should correspond to an existing row in the table cache");
+            unreachable!("a delete update should correspond to an existing row in the table cache, but the row {delete:?} was not present");
         };
         let ref_count = &mut entry.get_mut().ref_count;
         *ref_count -= 1;
@@ -320,19 +341,21 @@ pub struct ClientCache<M: SpacetimeModule + ?Sized> {
     /// The strings are table names, since we may have multiple tables with the same row type.
     tables: Map<dyn Any + Send + Sync>,
 
+    /// Clone of the [`crate::db_connection::DbContextImpl::extra_logging`].
+    extra_logging: Option<SharedCell<File>>,
+
     _module: PhantomData<M>,
 }
 
-impl<M: SpacetimeModule> Default for ClientCache<M> {
-    fn default() -> Self {
+impl<M: SpacetimeModule> ClientCache<M> {
+    pub(crate) fn new(extra_logging: Option<SharedCell<File>>) -> Self {
         Self {
             tables: Map::new(),
+            extra_logging,
             _module: PhantomData,
         }
     }
-}
 
-impl<M: SpacetimeModule> ClientCache<M> {
     /// Get a handle on the [`TableCache`] which stores rows of type `Row` for the table `table_name`.
     pub(crate) fn get_table<Row: InModule<Module = M> + Send + Sync + 'static>(
         &self,
@@ -353,12 +376,12 @@ impl<M: SpacetimeModule> ClientCache<M> {
             .entry::<HashMap<&'static str, TableCache<Row>>>()
             .or_insert_with(Default::default)
             .entry(table_name)
-            .or_default()
+            .or_insert_with(|| TableCache::new(self.extra_logging.clone()))
     }
 
     /// Apply all the mutations in `diff`
     /// to the [`TableCache`] which stores rows of type `Row` for the table `table_name`.
-    pub fn apply_diff_to_table<'r, Row: InModule<Module = M> + Clone + Send + Sync + 'static>(
+    pub fn apply_diff_to_table<'r, Row: InModule<Module = M> + Clone + Debug + Send + Sync + 'static>(
         &mut self,
         table_name: &'static str,
         diff: &'r TableUpdate<Row>,
@@ -530,7 +553,7 @@ pub struct UniqueConstraintHandle<Row: InModule, Col> {
 }
 
 impl<
-        Row: Clone + InModule + Send + Sync + 'static,
+        Row: Clone + Debug + InModule + Send + Sync + 'static,
         Col: std::any::Any + Eq + std::hash::Hash + Clone + Send + Sync + std::fmt::Debug + 'static,
     > UniqueConstraintHandle<Row, Col>
 {