feat: Enforce singleton instance per file

- SafeBox.create(...) now returns the same instance for a given fileName
- Deprecated close() and closeWhenIdle() with no-op bodies
- Removed SafeBoxBlobFileRegistry as it's no longer needed

Author: harrytmthy

safebox/src/androidTest/java/com/harrytmthy/safebox/SafeBoxTest.kt

@@ -20,24 +20,16 @@ import android.content.Context
 import android.content.SharedPreferences
 import androidx.test.core.app.ApplicationProvider
 import androidx.test.ext.junit.runners.AndroidJUnit4
-import com.harrytmthy.safebox.SafeBox.Companion.DEFAULT_KEY_ALIAS
-import com.harrytmthy.safebox.SafeBox.Companion.DEFAULT_VALUE_KEYSTORE_ALIAS
-import com.harrytmthy.safebox.state.SafeBoxState
 import com.harrytmthy.safebox.state.SafeBoxStateListener
 import kotlinx.coroutines.CoroutineDispatcher
 import kotlinx.coroutines.Dispatchers
 import kotlinx.coroutines.ExperimentalCoroutinesApi
 import kotlinx.coroutines.test.UnconfinedTestDispatcher
 import org.junit.After
 import org.junit.runner.RunWith
-import java.io.File
-import java.security.KeyStore
-import java.util.concurrent.CopyOnWriteArrayList
-import java.util.concurrent.atomic.AtomicBoolean
 import kotlin.test.Test
 import kotlin.test.assertContentEquals
 import kotlin.test.assertEquals
-import kotlin.test.assertFalse
 import kotlin.test.assertNull
 import kotlin.test.assertTrue
 
@@ -56,15 +48,6 @@ class SafeBoxTest {
         safeBox.edit()
             .clear()
             .commit()
-        safeBox.close()
-
-        KeyStore.getInstance("AndroidKeyStore").apply {
-            load(null)
-            deleteEntry(DEFAULT_VALUE_KEYSTORE_ALIAS)
-        }
-
-        File(context.noBackupFilesDir, "$fileName.bin").delete()
-        File(context.noBackupFilesDir, "$DEFAULT_KEY_ALIAS.bin").delete()
     }
 
     @Test
@@ -179,68 +162,6 @@ class SafeBoxTest {
         assertContentEquals(expectedValueChanges, changedValues)
     }
 
-    @Test
-    fun closeWhenIdle_shouldWaitUntilWritesAreDoneBeforeClosing() {
-        val observedStates = CopyOnWriteArrayList<SafeBoxState>()
-        val closed = AtomicBoolean(false)
-        safeBox = createSafeBox(
-            ioDispatcher = Dispatchers.IO,
-            stateListener = SafeBoxStateListener { state ->
-                observedStates.add(state)
-                closed.set(state == SafeBoxState.CLOSED)
-            },
-        )
-        repeat(5) {
-            safeBox.edit()
-                .putString("key", "value")
-                .apply()
-        }
-        safeBox.closeWhenIdle()
-        repeat(5) {
-            safeBox.edit()
-                .putString("key", "value")
-                .apply()
-        }
-        while (!closed.get()) {
-            Thread.sleep(3)
-        }
-        val expectedOnSlowInit = listOf(
-            SafeBoxState.STARTING,
-            SafeBoxState.WRITING,
-            SafeBoxState.IDLE,
-            SafeBoxState.CLOSED,
-        )
-        val expectedOnFastInit = listOf(
-            SafeBoxState.STARTING,
-            SafeBoxState.IDLE, // finished STARTING before launching any write operation
-            SafeBoxState.WRITING,
-            SafeBoxState.IDLE,
-            SafeBoxState.CLOSED,
-        )
-        assertTrue(observedStates == expectedOnSlowInit || observedStates == expectedOnFastInit)
-    }
-
-    @Test
-    fun putString_shouldDoNothingAfterClosing() {
-        val hasEmissionAfterClose = AtomicBoolean(false)
-        val closed = AtomicBoolean(false)
-        safeBox = createSafeBox(
-            stateListener = SafeBoxStateListener { state ->
-                if (closed.get()) {
-                    hasEmissionAfterClose.set(true)
-                }
-                closed.set(state == SafeBoxState.CLOSED)
-            },
-        )
-
-        safeBox.closeWhenIdle()
-        safeBox.edit()
-            .putString("key", "value")
-            .commit()
-
-        assertFalse(hasEmissionAfterClose.get())
-    }
-
     private fun createSafeBox(
         ioDispatcher: CoroutineDispatcher = UnconfinedTestDispatcher(),
         stateListener: SafeBoxStateListener? = null,

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

@@ -32,7 +32,6 @@ import com.harrytmthy.safebox.extensions.safeBoxScope
 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.SafeBoxStateListener
 import com.harrytmthy.safebox.state.SafeBoxStateManager
 import com.harrytmthy.safebox.storage.Bytes
@@ -199,27 +198,25 @@ public class SafeBox private constructor(
     }
 
     /**
+     * **Deprecated:** SafeBox no longer supports instance closing.
+     *
      * Immediately closes the underlying file channel and releases resources.
-     * Also unregisters the file from [SafeBoxBlobFileRegistry], allowing a new SafeBox
-     * instance to be created with the same filename.
      *
      * ⚠️ Once closed, this instance becomes *permanently unusable*. Any further access will fail.
      *
      * ⚠️ Only use this method when you're certain that no writes are in progress.
      *
      * Closing during an active write can result in data corruption or incomplete persistence.
      */
+    @Deprecated(message = "This method is now a no-op, as SafeBox is always active and reusable.")
     public fun close() {
-        SafeBoxBlobFileRegistry.unregister(blobStore.getFileName())
-        blobStore.close()
-        keyCipherProvider.destroyKey()
-        valueCipherProvider.destroyKey()
+        // no-op
     }
 
     /**
+     * **Deprecated:** SafeBox no longer supports instance closing.
+     *
      * Closes the underlying file channel only after all pending writes have completed.
-     * Also unregisters the file from [SafeBoxBlobFileRegistry], allowing a new SafeBox
-     * instance to be created with the same filename.
      *
      * ⚠️ Once closed, this instance becomes *permanently unusable*. Any further access will fail.
      *
@@ -228,8 +225,9 @@ public class SafeBox private constructor(
      * Internally, this launches a coroutine on [safeBoxScope] to wait until the SafeBox
      * becomes idle before releasing resources.
      */
+    @Deprecated(message = "This method is now a no-op, as SafeBox is always active and reusable.")
     public fun closeWhenIdle() {
-        stateManager.closeWhenIdle(::close)
+        // no-op
     }
 
     override fun getAll(): Map<String, Any?> {
@@ -376,6 +374,9 @@ public class SafeBox private constructor(
         @VisibleForTesting
         internal const val DEFAULT_VALUE_KEYSTORE_ALIAS = "SafeBoxValue"
 
+        @VisibleForTesting
+        internal val instances = ConcurrentHashMap<String, SafeBox>()
+
         /**
          * Creates a [SafeBox] instance with secure defaults:
          * - Keys are deterministically encrypted using [ChaCha20CipherProvider].
@@ -411,7 +412,10 @@ public class SafeBox private constructor(
             ioDispatcher: CoroutineDispatcher = Dispatchers.IO,
             stateListener: SafeBoxStateListener? = null,
         ): SafeBox {
-            SafeBoxBlobFileRegistry.register(fileName)
+            instances[fileName]?.let { safeBox ->
+                stateListener?.let(safeBox.stateManager::setStateListener)
+                return safeBox
+            }
             val aesGcmCipherProvider = AesGcmCipherProvider.create(
                 alias = valueKeyStoreAlias,
                 aad = additionalAuthenticatedData,
@@ -428,6 +432,7 @@ public class SafeBox private constructor(
             val stateManager = SafeBoxStateManager(fileName, stateListener, ioDispatcher)
             val blobStore = SafeBoxBlobStore.create(context, fileName)
             return SafeBox(blobStore, keyCipherProvider, valueCipherProvider, stateManager)
+                .also { instances[fileName] = it }
         }
 
         /**
@@ -461,10 +466,14 @@ public class SafeBox private constructor(
             ioDispatcher: CoroutineDispatcher = Dispatchers.IO,
             stateListener: SafeBoxStateListener? = null,
         ): SafeBox {
-            SafeBoxBlobFileRegistry.register(fileName)
+            instances[fileName]?.let { safeBox ->
+                stateListener?.let(safeBox.stateManager::setStateListener)
+                return safeBox
+            }
             val stateManager = SafeBoxStateManager(fileName, stateListener, ioDispatcher)
             val blobStore = SafeBoxBlobStore.create(context, fileName)
             return SafeBox(blobStore, keyCipherProvider, valueCipherProvider, stateManager)
+                .also { instances[fileName] = it }
         }
     }
 }

safebox/src/main/java/com/harrytmthy/safebox/registry/SafeBoxBlobFileRegistry.kt

@@ -49,7 +49,7 @@ import java.util.concurrent.atomic.AtomicReference
  */
 internal class SafeBoxStateManager(
     private val fileName: String,
-    private val stateListener: SafeBoxStateListener?,
+    private var stateListener: SafeBoxStateListener?,
     private val ioDispatcher: CoroutineDispatcher,
 ) {
 
@@ -61,6 +61,10 @@ internal class SafeBoxStateManager(
 
     private val closed = AtomicBoolean(false)
 
+    fun setStateListener(stateListener: SafeBoxStateListener?) {
+        this.stateListener = stateListener
+    }
+
     inline fun launchWithStartingState(crossinline block: suspend () -> Unit) {
         updateState(STARTING)
         safeBoxScope.launch(ioDispatcher) {