Make raw error private

Author: simolus3

crates/core/src/checkpoint.rs

@@ -27,7 +27,7 @@ fn powersync_validate_checkpoint_impl(
 ) -> Result<String, PowerSyncError> {
     let data = args[0].text();
     let checkpoint: Checkpoint =
-        serde_json::from_str(data).map_err(PowerSyncError::json_argument_error)?;
+        serde_json::from_str(data).map_err(PowerSyncError::as_argument_error)?;
     let db = ctx.db_handle();
     let buckets: Vec<OwnedBucketChecksum> = checkpoint
         .buckets

crates/core/src/diff.rs

@@ -23,10 +23,8 @@ fn powersync_diff_impl(
 }
 
 pub fn diff_objects(data_old: &str, data_new: &str) -> Result<String, PowerSyncError> {
-    let v_new: json::Value =
-        json::from_str(data_new).map_err(PowerSyncError::json_argument_error)?;
-    let v_old: json::Value =
-        json::from_str(data_old).map_err(PowerSyncError::json_argument_error)?;
+    let v_new: json::Value = json::from_str(data_new).map_err(PowerSyncError::as_argument_error)?;
+    let v_old: json::Value = json::from_str(data_old).map_err(PowerSyncError::as_argument_error)?;
 
     if let (json::Value::Object(mut left), json::Value::Object(mut right)) = (v_new, v_old) {
         // Remove all null values

crates/core/src/error.rs

@@ -13,7 +13,8 @@ use crate::bson::BsonError;
 
 /// A [RawPowerSyncError], but boxed.
 ///
-/// We allocate errors in boxes to avoid large [Result] types returning these.
+/// We allocate errors in boxes to avoid large [Result] types (given the large size of the
+/// [RawPowerSyncError] enum type).
 pub struct PowerSyncError {
     inner: Box<RawPowerSyncError>,
 }
@@ -35,10 +36,14 @@ impl PowerSyncError {
         .into()
     }
 
-    pub fn json_argument_error(cause: serde_json::Error) -> Self {
+    /// Converts something that can be a [PowerSyncErrorCause] into an argument error.
+    ///
+    /// This can be used to represent e.g. JSON parsing errors as argument errors, e.g. with
+    /// ` serde_json::from_str(payload.text()).map_err(PowerSyncError::as_argument_error)`.
+    pub fn as_argument_error(cause: impl Into<PowerSyncErrorCause>) -> Self {
         RawPowerSyncError::ArgumentError {
             desc: "".into(),
-            cause: PowerSyncErrorCause::Json(cause),
+            cause: cause.into(),
         }
         .into()
     }
@@ -54,17 +59,35 @@ impl PowerSyncError {
         RawPowerSyncError::StateError { desc }.into()
     }
 
+    pub fn sync_protocol_error(desc: &'static str, cause: impl Into<PowerSyncErrorCause>) -> Self {
+        RawPowerSyncError::SyncProtocolError {
+            desc,
+            cause: cause.into(),
+        }
+        .into()
+    }
+
+    /// A generic internal error.
+    ///
+    /// This should only be used rarely since this error provides no further details.
     pub fn unknown_internal() -> Self {
         Self::internal(PowerSyncErrorCause::Unknown)
     }
 
+    /// A generic internal error with an associated cause.
     pub fn internal(cause: impl Into<PowerSyncErrorCause>) -> Self {
         RawPowerSyncError::Internal {
             cause: cause.into(),
         }
         .into()
     }
 
+    pub fn missing_client_id() -> Self {
+        RawPowerSyncError::MissingClientId.into()
+    }
+
+    /// Applies this error to a function result context, setting the error code and a descriptive
+    /// text.
     pub fn apply_to_ctx(self, description: &str, ctx: *mut context) {
         let mut desc = self.description(ctx.db_handle());
         desc.insert_str(0, description);
@@ -91,7 +114,7 @@ impl PowerSyncError {
 
         match self.inner.as_ref() {
             Sqlite { code, .. } => *code,
-            InvalidBucketPriority | ArgumentError { .. } | StateError { .. } => ResultCode::MISUSE,
+            ArgumentError { .. } | StateError { .. } => ResultCode::MISUSE,
             MissingClientId | SyncProtocolError { .. } => ResultCode::ABORT,
             LocalDataError { .. } => ResultCode::CORRUPT,
             Internal { .. } => ResultCode::INTERNAL,
@@ -125,7 +148,7 @@ impl From<ResultCode> for PowerSyncError {
 
 /// A structured enumeration of possible errors that can occur in the core extension.
 #[derive(Error, Debug)]
-pub enum RawPowerSyncError {
+enum RawPowerSyncError {
     /// An internal call to SQLite made by the core extension has failed. We store the original
     /// result code and an optional context describing what the core extension was trying to do when
     /// the error occurred.
@@ -158,19 +181,18 @@ pub enum RawPowerSyncError {
     /// (e.g. a checkpoint diff before we've ever received a checkpoint).
     ///
     /// This interrupts a sync iteration as we cannot reasonably continue afterwards (the client and
-    /// server are necessarily in different states).
+    /// server are necessarily in diverged states).
     #[error("Sync protocol error: {desc}. {cause}")]
     SyncProtocolError {
         desc: &'static str,
         cause: PowerSyncErrorCause,
     },
     /// There's invalid local data in the database (like malformed JSON in the oplog table).
-    #[error("invalid local data")]
+    #[error("invalid local data: {cause}")]
     LocalDataError { cause: PowerSyncErrorCause },
     #[error("No client_id found in ps_kv")]
     MissingClientId,
-    #[error("Invalid bucket priority value")]
-    InvalidBucketPriority,
+    /// A catch-all for remaining internal errors that are very unlikely to happen.
     #[error("Internal PowerSync error. {cause}")]
     Internal { cause: PowerSyncErrorCause },
 }

crates/core/src/kv.rs

@@ -9,7 +9,7 @@ use sqlite_nostd::{Connection, Context};
 
 use crate::create_sqlite_optional_text_fn;
 use crate::create_sqlite_text_fn;
-use crate::error::{PowerSyncError, RawPowerSyncError};
+use crate::error::PowerSyncError;
 use crate::sync::BucketPriority;
 
 fn powersync_client_id_impl(
@@ -29,7 +29,7 @@ pub fn client_id(db: *mut sqlite::sqlite3) -> Result<String, PowerSyncError> {
         let client_id = statement.column_text(0)?;
         Ok(client_id.to_string())
     } else {
-        Err(RawPowerSyncError::MissingClientId.into())
+        Err(PowerSyncError::missing_client_id())
     }
 }
 

crates/core/src/operations.rs

@@ -18,7 +18,7 @@ pub fn insert_operation(db: *mut sqlite::sqlite3, data: &str) -> Result<(), Powe
     }
 
     let batch: BucketBatch =
-        serde_json::from_str(data).map_err(PowerSyncError::json_argument_error)?;
+        serde_json::from_str(data).map_err(PowerSyncError::as_argument_error)?;
     let adapter = StorageAdapter::new(db)?;
 
     for line in &batch.buckets {

crates/core/src/schema/management.rs

@@ -133,7 +133,7 @@ SELECT name, internal_name, local_only FROM powersync_tables WHERE name NOT IN (
 fn update_indexes(db: *mut sqlite::sqlite3, schema: &str) -> Result<(), PowerSyncError> {
     let mut statements: Vec<String> = alloc::vec![];
     let schema =
-        serde_json::from_str::<Schema>(schema).map_err(PowerSyncError::json_argument_error)?;
+        serde_json::from_str::<Schema>(schema).map_err(PowerSyncError::as_argument_error)?;
     let mut expected_index_names: Vec<String> = vec![];
 
     {

crates/core/src/sync/bucket_priority.rs

@@ -1,6 +1,6 @@
 use serde::{de::Visitor, Deserialize, Serialize};
 
-use crate::error::{PowerSyncError, RawPowerSyncError};
+use crate::error::PowerSyncError;
 
 #[repr(transparent)]
 #[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
@@ -26,7 +26,9 @@ impl TryFrom<i32> for BucketPriority {
 
     fn try_from(value: i32) -> Result<Self, Self::Error> {
         if value < BucketPriority::HIGHEST.number || value == Self::SENTINEL.number {
-            return Err(RawPowerSyncError::InvalidBucketPriority.into());
+            return Err(PowerSyncError::argument_error(
+                "Invalid bucket priority value",
+            ));
         }
 
         return Ok(BucketPriority { number: value });

crates/core/src/sync/interface.rs

@@ -151,7 +151,7 @@ pub fn register(db: *mut sqlite::sqlite3, state: Arc<DatabaseState>) -> Result<(
                 "start" => SyncControlRequest::StartSyncStream({
                     if payload.value_type() == ColumnType::Text {
                         serde_json::from_str(payload.text())
-                            .map_err(PowerSyncError::json_argument_error)?
+                            .map_err(PowerSyncError::as_argument_error)?
                     } else {
                         StartSyncStream::default()
                     }

crates/core/src/sync/streaming_sync.rs

@@ -17,7 +17,7 @@ use futures_lite::FutureExt;
 
 use crate::{
     bson,
-    error::{PowerSyncError, RawPowerSyncError},
+    error::PowerSyncError,
     kv::client_id,
     state::DatabaseState,
     sync::{checkpoint::OwnedBucketChecksum, interface::StartSyncStream},
@@ -249,18 +249,10 @@ impl StreamingSyncIteration {
                         .update(|s| s.disconnect(), &mut event.instructions);
                     break;
                 }
-                SyncEvent::TextLine { data } => serde_json::from_str(data).map_err(|e| {
-                    PowerSyncError::from(RawPowerSyncError::SyncProtocolError {
-                        desc: "invalid text line",
-                        cause: e.into(),
-                    })
-                })?,
-                SyncEvent::BinaryLine { data } => bson::from_bytes(data).map_err(|e| {
-                    PowerSyncError::from(RawPowerSyncError::SyncProtocolError {
-                        desc: "invalid binary line",
-                        cause: e.into(),
-                    })
-                })?,
+                SyncEvent::TextLine { data } => serde_json::from_str(data)
+                    .map_err(|e| PowerSyncError::sync_protocol_error("invalid text line", e))?,
+                SyncEvent::BinaryLine { data } => bson::from_bytes(data)
+                    .map_err(|e| PowerSyncError::sync_protocol_error("invalid binary line", e))?,
                 SyncEvent::UploadFinished => {
                     if let Some(checkpoint) = validated_but_not_applied.take() {
                         let result = self.adapter.sync_local(

crates/core/src/sync_local.rs

@@ -20,7 +20,7 @@ pub fn sync_local<V: Value>(
     data: &V,
 ) -> Result<i64, PowerSyncError> {
     let mut operation: SyncOperation<'_> =
-        SyncOperation::from_args(state, db, data).map_err(PowerSyncError::json_argument_error)?;
+        SyncOperation::from_args(state, db, data).map_err(PowerSyncError::as_argument_error)?;
     operation.apply()
 }