feat(storage): Add instance-bound SafeBoxStateListener support to SafeBoxBlobStore (#13)

Author: harrytmthy

safebox/src/androidTest/java/com/harrytmthy/safebox/storage/SafeBoxBlobStoreTest.kt

@@ -20,12 +20,15 @@ import android.content.Context
 import androidx.test.core.app.ApplicationProvider
 import androidx.test.ext.junit.runners.AndroidJUnit4
 import com.harrytmthy.safebox.extensions.toBytes
+import com.harrytmthy.safebox.state.SafeBoxState
+import com.harrytmthy.safebox.state.SafeBoxStateListener
 import kotlinx.coroutines.ExperimentalCoroutinesApi
 import kotlinx.coroutines.test.UnconfinedTestDispatcher
 import kotlinx.coroutines.test.runTest
 import org.junit.After
 import org.junit.runner.RunWith
 import java.io.File
+import java.util.concurrent.CopyOnWriteArrayList
 import kotlin.test.Test
 import kotlin.test.assertContentEquals
 import kotlin.test.assertEquals
@@ -40,12 +43,22 @@ class SafeBoxBlobStoreTest {
 
     private val fileName: String = "safebox_blob_test"
 
-    private val blobStore = SafeBoxBlobStore.create(context, fileName, UnconfinedTestDispatcher())
+    private val observedStates = CopyOnWriteArrayList<SafeBoxState>()
+
+    private val stateListener = SafeBoxStateListener(observedStates::add)
+
+    private val blobStore = SafeBoxBlobStore.create(
+        context,
+        fileName,
+        UnconfinedTestDispatcher(),
+        stateListener,
+    )
 
     @After
     fun teardown() {
         blobStore.close()
         File(context.noBackupFilesDir, "$fileName.bin").delete()
+        observedStates.clear()
     }
 
     @Test
@@ -203,4 +216,21 @@ class SafeBoxBlobStoreTest {
     fun getFileName_shouldReturnFileName() {
         assertEquals(fileName, blobStore.getFileName())
     }
+
+    @Test
+    fun write_shouldEmitWritingAndIdleStates() = runTest {
+        val key = "alpha".toByteArray().toBytes()
+        val value = "123".toByteArray()
+
+        blobStore.write(key, value)
+
+        assertEquals(listOf(SafeBoxState.WRITING, SafeBoxState.IDLE), observedStates)
+    }
+
+    @Test
+    fun close_shouldEmitClosedState() {
+        blobStore.close()
+
+        assertEquals(SafeBoxState.CLOSED, observedStates.last())
+    }
 }

safebox/src/main/java/com/harrytmthy/safebox/SafeBox.kt

@@ -33,6 +33,8 @@ import com.harrytmthy.safebox.extensions.toBytes
 import com.harrytmthy.safebox.extensions.toEncodedByteArray
 import com.harrytmthy.safebox.keystore.SecureRandomKeyProvider
 import com.harrytmthy.safebox.registry.SafeBoxBlobFileRegistry
+import com.harrytmthy.safebox.state.SafeBoxState
+import com.harrytmthy.safebox.state.SafeBoxStateListener
 import com.harrytmthy.safebox.storage.Bytes
 import com.harrytmthy.safebox.storage.SafeBoxBlobStore
 import com.harrytmthy.safebox.strategy.ValueFallbackStrategy
@@ -333,6 +335,7 @@ public class SafeBox private constructor(
          * @param valueKeyStoreAlias The Android Keystore alias used for AES-GCM key generation
          * @param additionalAuthenticatedData Optional AAD bound to the AES-GCM (default: fileName)
          * @param ioDispatcher The dispatcher used for I/O operations (default: [Dispatchers.IO])
+         * @param stateListener The listener to observe instance-bound state transitions
          *
          * @return A fully configured [SafeBox] instance
          * @throws IllegalStateException if the file is already registered.
@@ -347,8 +350,10 @@ public class SafeBox private constructor(
             valueKeyStoreAlias: String = DEFAULT_VALUE_KEYSTORE_ALIAS,
             additionalAuthenticatedData: ByteArray = fileName.toByteArray(),
             ioDispatcher: CoroutineDispatcher = Dispatchers.IO,
+            stateListener: SafeBoxStateListener? = null,
         ): SafeBox {
             SafeBoxBlobFileRegistry.register(fileName)
+            stateListener?.onStateChanged(SafeBoxState.IDLE)
             val aesGcmCipherProvider = AesGcmCipherProvider.create(
                 alias = valueKeyStoreAlias,
                 aad = additionalAuthenticatedData,
@@ -362,7 +367,7 @@ public class SafeBox private constructor(
             )
             val keyCipherProvider = ChaCha20CipherProvider(keyProvider, deterministic = true)
             val valueCipherProvider = ChaCha20CipherProvider(keyProvider, deterministic = false)
-            val blobStore = SafeBoxBlobStore.create(context, fileName, ioDispatcher)
+            val blobStore = SafeBoxBlobStore.create(context, fileName, ioDispatcher, stateListener)
             return SafeBox(blobStore, keyCipherProvider, valueCipherProvider, ioDispatcher)
         }
 
@@ -381,6 +386,7 @@ public class SafeBox private constructor(
          * @param keyCipherProvider Cipher used for encrypting and decrypting keys
          * @param valueCipherProvider Cipher used for encrypting and decrypting values
          * @param ioDispatcher The dispatcher used for I/O operations (default: [Dispatchers.IO])
+         * @param stateListener The listener to observe instance-bound state transitions
          *
          * @return A [SafeBox] instance with the provided [CipherProvider]
          * @throws IllegalStateException if the file is already registered.
@@ -394,9 +400,10 @@ public class SafeBox private constructor(
             keyCipherProvider: CipherProvider,
             valueCipherProvider: CipherProvider,
             ioDispatcher: CoroutineDispatcher = Dispatchers.IO,
+            stateListener: SafeBoxStateListener? = null,
         ): SafeBox {
             SafeBoxBlobFileRegistry.register(fileName)
-            val blobStore = SafeBoxBlobStore.create(context, fileName, ioDispatcher)
+            val blobStore = SafeBoxBlobStore.create(context, fileName, ioDispatcher, stateListener)
             return SafeBox(blobStore, keyCipherProvider, valueCipherProvider, ioDispatcher)
         }
     }

safebox/src/main/java/com/harrytmthy/safebox/state/SafeBoxState.kt

@@ -0,0 +1,48 @@
+/*
+ * Copyright 2025 Harry Timothy Tumalewa
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.harrytmthy.safebox.state
+
+import com.harrytmthy.safebox.SafeBox
+
+/**
+ * Represents the current lifecycle state of a [SafeBox] instance.
+ *
+ * These states are exposed through [SafeBoxStateListener] and help consumers track
+ * SafeBox activity, especially during asynchronous operations.
+ *
+ * @see SafeBoxStateListener
+ */
+public enum class SafeBoxState {
+
+    /**
+     * Indicates that SafeBox is idle and not currently writing to disk.
+     * This is the default resting state.
+     */
+    IDLE,
+
+    /**
+     * Indicates that SafeBox is performing a write operation.
+     * Avoid closing or deleting the SafeBox during this time.
+     */
+    WRITING,
+
+    /**
+     * Indicates that SafeBox has been closed and is no longer usable.
+     * Once closed, a SafeBox instance cannot be reused.
+     */
+    CLOSED,
+}

safebox/src/main/java/com/harrytmthy/safebox/state/SafeBoxStateListener.kt

@@ -0,0 +1,35 @@
+/*
+ * Copyright 2025 Harry Timothy Tumalewa
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.harrytmthy.safebox.state
+
+/**
+ * A listener interface for observing [SafeBoxState] changes tied to a specific SafeBox file.
+ *
+ * This is typically used in non-singleton SafeBox use cases (e.g. ViewModel-scoped),
+ * where consumers need to track if the instance is writing, idle, or closed.
+ *
+ * @see SafeBoxState
+ */
+public fun interface SafeBoxStateListener {
+
+    /**
+     * Called whenever there is a state update.
+     *
+     * @param state The latest state of the SafeBox instance.
+     */
+    fun onStateChanged(state: SafeBoxState)
+}

safebox/src/main/java/com/harrytmthy/safebox/storage/SafeBoxBlobStore.kt

@@ -21,6 +21,8 @@ import android.util.Log
 import androidx.annotation.VisibleForTesting
 import com.harrytmthy.safebox.extensions.safeBoxScope
 import com.harrytmthy.safebox.extensions.toBytes
+import com.harrytmthy.safebox.state.SafeBoxState
+import com.harrytmthy.safebox.state.SafeBoxStateListener
 import com.harrytmthy.safebox.strategy.ValueFallbackStrategy
 import com.harrytmthy.safebox.strategy.ValueFallbackStrategy.ERROR
 import com.harrytmthy.safebox.strategy.ValueFallbackStrategy.WARN
@@ -46,6 +48,7 @@ import java.util.concurrent.atomic.AtomicReference
 internal class SafeBoxBlobStore private constructor(
     ioDispatcher: CoroutineDispatcher,
     private val file: File,
+    private val stateListener: SafeBoxStateListener?,
 ) {
 
     private val channel = RandomAccessFile(file, "rw").channel
@@ -121,7 +124,7 @@ internal class SafeBoxBlobStore private constructor(
      * @throws IllegalStateException if the blob file does not have enough remaining capacity.
      */
     internal suspend fun write(encryptedKey: Bytes, encryptedValue: ByteArray) {
-        writeMutex.withLock {
+        writeMutex.withLockAndStateUpdates {
             if (!entryMetas.contains(encryptedKey)) {
                 writeAtOffset(encryptedKey, encryptedValue)
             } else {
@@ -139,7 +142,7 @@ internal class SafeBoxBlobStore private constructor(
      * @param encryptedKeys Vararg array of keys to delete.
      */
     internal suspend fun delete(vararg encryptedKeys: Bytes) {
-        writeMutex.withLock {
+        writeMutex.withLockAndStateUpdates {
             val metas = entryMetas.values.toList()
             for (encryptedKey in encryptedKeys) {
                 val currentIndex = entryMetas.keys.indexOf(encryptedKey)
@@ -170,7 +173,7 @@ internal class SafeBoxBlobStore private constructor(
      * @return a set of [Bytes] keys that were removed, used for notifying listeners.
      */
     internal suspend fun deleteAll(): Set<Bytes> =
-        writeMutex.withLock {
+        writeMutex.withLockAndStateUpdates {
             buffer.position(0)
             buffer.put(ByteArray(nextWritePosition))
             buffer.force()
@@ -196,6 +199,7 @@ internal class SafeBoxBlobStore private constructor(
      */
     internal fun close() {
         channel.close()
+        stateListener?.onStateChanged(SafeBoxState.CLOSED)
     }
 
     private fun writeAtOffset(
@@ -280,6 +284,20 @@ internal class SafeBoxBlobStore private constructor(
         }
     }
 
+    /**
+     * Wraps the given [action] with mutex locking and emits SafeBox state transitions.
+     *
+     * This ensures that any critical write operation is surrounded by `WRITING` and `IDLE` events,
+     * which helps external listeners track write progress.
+     */
+    private suspend inline fun <T> Mutex.withLockAndStateUpdates(crossinline action: () -> T): T =
+        withLock {
+            stateListener?.onStateChanged(SafeBoxState.WRITING)
+            val result = action()
+            stateListener?.onStateChanged(SafeBoxState.IDLE)
+            result
+        }
+
     @VisibleForTesting
     internal data class EntryMeta(val offset: Int, val size: Int)
 
@@ -291,12 +309,13 @@ internal class SafeBoxBlobStore private constructor(
             context: Context,
             fileName: String,
             ioDispatcher: CoroutineDispatcher,
+            stateListener: SafeBoxStateListener?,
         ): SafeBoxBlobStore {
             val file = File(context.noBackupFilesDir, "$fileName.bin")
             if (!file.exists()) {
                 file.createNewFile()
             }
-            return SafeBoxBlobStore(ioDispatcher, file)
+            return SafeBoxBlobStore(ioDispatcher, file, stateListener)
         }
     }
 }