add comment & test (#309)

crates/db/src/kv/cursor.rs

@@ -128,6 +128,8 @@ impl<'tx, T: Table> DbCursorRW<'tx, T> for Cursor<'tx, RW, T> {
             .map_err(|e| Error::Write(e.into()))
     }
 
+    /// Appends the data to the end of the table. Consequently, the append operation
+    /// will fail if the inserted key is less than the last table key
     fn append(&mut self, key: T::Key, value: T::Value) -> Result<(), Error> {
         self.inner
             .put(key.encode().as_ref(), value.compress().as_ref(), WriteFlags::APPEND)

crates/db/src/kv/mod.rs

@@ -140,11 +140,12 @@ mod tests {
     use super::{test_utils, Env, EnvKind};
     use reth_interfaces::{
         db::{
+            self,
             models::ShardedKey,
             tables::{
                 AccountHistory, CanonicalHeaders, Headers, PlainAccountState, PlainStorageState,
             },
-            Database, DbCursorRO, DbDupCursorRO, DbTx, DbTxMut,
+            Database, DbCursorRO, DbCursorRW, DbDupCursorRO, DbTx, DbTxMut,
         },
         provider::{ProviderImpl, StateProviderFactory},
     };
@@ -236,6 +237,27 @@ mod tests {
         assert_eq!(cursor.prev(), Ok(Some((missing_key - 2, H256::zero()))));
     }
 
+    #[test]
+    fn db_cursor_append_failure() {
+        let db: Arc<Env<WriteMap>> = test_utils::create_test_db(EnvKind::RW);
+
+        // PUT
+        let tx = db.tx_mut().expect(ERROR_INIT_TX);
+        vec![0, 1, 3, 4, 5]
+            .into_iter()
+            .try_for_each(|key| tx.put::<CanonicalHeaders>(key, H256::zero()))
+            .expect(ERROR_PUT);
+        tx.commit().expect(ERROR_COMMIT);
+
+        // APPEND
+        let key_to_insert = 2;
+        let tx = db.tx_mut().expect(ERROR_INIT_TX);
+        let mut cursor = tx.cursor_mut::<CanonicalHeaders>().unwrap();
+        cursor.seek_exact(1).unwrap();
+        assert_eq!(cursor.append(key_to_insert, H256::zero()), Err(db::Error::Write(4294936878)));
+        assert_eq!(cursor.current(), Ok(Some((5, H256::zero())))); // the end of table
+    }
+
     #[test]
     fn db_closure_put_get() {
         let path = TempDir::new().expect(test_utils::ERROR_TEMPDIR).into_path();