feat(registry): Add SafeBoxBlobFileRegistry to enforce single instance per file (#11)

Author: harrytmthy

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

@@ -53,6 +53,7 @@ class SafeBoxTest {
         safeBox.edit()
             .clear()
             .commit()
+        safeBox.close()
 
         KeyStore.getInstance("AndroidKeyStore").apply {
             load(null)

safebox/src/androidTest/java/com/harrytmthy/safebox/migration/SafeBoxMigrationHelperTest.kt

@@ -64,6 +64,7 @@ class SafeBoxMigrationHelperTest {
         esp.edit()
             .clear()
             .commit()
+        safeBox.close()
         context.deleteSharedPreferences(fileEsp)
         context.deleteFile("$fileSafeBox.bin")
     }

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

@@ -198,4 +198,9 @@ class SafeBoxBlobStoreTest {
         assertContentEquals(secondValue, result[key])
         assertTrue(blobStore.entryMetas.containsKey(key))
     }
+
+    @Test
+    fun getFileName_shouldReturnFileName() {
+        assertEquals(fileName, blobStore.getFileName())
+    }
 }

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

@@ -32,6 +32,7 @@ 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.storage.Bytes
 import com.harrytmthy.safebox.storage.SafeBoxBlobStore
 import com.harrytmthy.safebox.strategy.ValueFallbackStrategy
@@ -150,12 +151,17 @@ public class SafeBox private constructor(
     }
 
     /**
-     * Releases resources and closes the underlying file channel.
+     * 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.
      *
-     * Call this when SafeBox is no longer in use to ensure file handles are cleaned up.
-     * Failing to do so may result in resource leaks or file corruption.
+     * ⚠️ 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.
      */
     public fun close() {
+        SafeBoxBlobFileRegistry.unregister(blobStore.getFileName())
         blobStore.close()
     }
 
@@ -329,9 +335,11 @@ public class SafeBox private constructor(
          * @param ioDispatcher The dispatcher used for I/O operations (default: [Dispatchers.IO])
          *
          * @return A fully configured [SafeBox] instance
+         * @throws IllegalStateException if the file is already registered.
          */
         @JvmOverloads
         @JvmStatic
+        @Throws(IllegalStateException::class)
         public fun create(
             context: Context,
             fileName: String,
@@ -340,6 +348,7 @@ public class SafeBox private constructor(
             additionalAuthenticatedData: ByteArray = fileName.toByteArray(),
             ioDispatcher: CoroutineDispatcher = Dispatchers.IO,
         ): SafeBox {
+            SafeBoxBlobFileRegistry.register(fileName)
             val aesGcmCipherProvider = AesGcmCipherProvider.create(
                 alias = valueKeyStoreAlias,
                 aad = additionalAuthenticatedData,
@@ -353,7 +362,8 @@ public class SafeBox private constructor(
             )
             val keyCipherProvider = ChaCha20CipherProvider(keyProvider, deterministic = true)
             val valueCipherProvider = ChaCha20CipherProvider(keyProvider, deterministic = false)
-            return create(context, fileName, keyCipherProvider, valueCipherProvider, ioDispatcher)
+            val blobStore = SafeBoxBlobStore.create(context, fileName, ioDispatcher)
+            return SafeBox(blobStore, keyCipherProvider, valueCipherProvider, ioDispatcher)
         }
 
         /**
@@ -373,16 +383,19 @@ public class SafeBox private constructor(
          * @param ioDispatcher The dispatcher used for I/O operations (default: [Dispatchers.IO])
          *
          * @return A [SafeBox] instance with the provided [CipherProvider]
+         * @throws IllegalStateException if the file is already registered.
          */
         @JvmOverloads
         @JvmStatic
+        @Throws(IllegalStateException::class)
         public fun create(
             context: Context,
             fileName: String,
             keyCipherProvider: CipherProvider,
             valueCipherProvider: CipherProvider,
             ioDispatcher: CoroutineDispatcher = Dispatchers.IO,
         ): SafeBox {
+            SafeBoxBlobFileRegistry.register(fileName)
             val blobStore = SafeBoxBlobStore.create(context, fileName, ioDispatcher)
             return SafeBox(blobStore, keyCipherProvider, valueCipherProvider, ioDispatcher)
         }

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

@@ -0,0 +1,59 @@
+/*
+ * 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.registry
+
+import com.harrytmthy.safebox.SafeBox
+import java.util.Collections
+import java.util.concurrent.ConcurrentHashMap
+
+/**
+ * An internal registry that tracks active SafeBox blob files.
+ *
+ * Prevents multiple [SafeBox] instances from accessing the same file simultaneously.
+ * This ensures thread safety and prevents corruption due to concurrent `FileChannel` access.
+ *
+ * This registry is internal-only and not intended for external observation.
+ * Please use [SafeBoxStateObserver] to listen for state changes.
+ */
+internal object SafeBoxBlobFileRegistry {
+
+    private val registry: MutableSet<String> = Collections.newSetFromMap(ConcurrentHashMap())
+
+    /**
+     * Registers the given file name as currently in use.
+     *
+     * @param fileName The file name associated with a SafeBox instance.
+     * @throws IllegalStateException if the file is already registered.
+     */
+    @Throws(IllegalStateException::class)
+    fun register(fileName: String) {
+        if (registry.contains(fileName)) {
+            error("SafeBox with file name '$fileName' is already in use. Please close it first.")
+        }
+        registry.add(fileName)
+    }
+
+    /**
+     * Unregisters the given file name, allowing the creation of a new SafeBox instances with
+     * an existing file name.
+     *
+     * @param fileName The file name to unregister.
+     */
+    fun unregister(fileName: String) {
+        registry.remove(fileName)
+    }
+}

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

@@ -45,9 +45,11 @@ import java.util.concurrent.atomic.AtomicReference
  */
 internal class SafeBoxBlobStore private constructor(
     ioDispatcher: CoroutineDispatcher,
-    private val channel: FileChannel,
+    private val file: File,
 ) {
 
+    private val channel = RandomAccessFile(file, "rw").channel
+
     private val buffer = channel.map(FileChannel.MapMode.READ_WRITE, 0, BUFFER_CAPACITY.toLong())
 
     private val entries = HashMap<Bytes, ByteArray>()
@@ -167,7 +169,7 @@ internal class SafeBoxBlobStore private constructor(
      *
      * @return a set of [Bytes] keys that were removed, used for notifying listeners.
      */
-    suspend fun deleteAll(): Set<Bytes> =
+    internal suspend fun deleteAll(): Set<Bytes> =
         writeMutex.withLock {
             buffer.position(0)
             buffer.put(ByteArray(nextWritePosition))
@@ -178,6 +180,16 @@ internal class SafeBoxBlobStore private constructor(
             keys
         }
 
+    /**
+     * Returns the name of the backing file, excluding its extension.
+     *
+     * This is used by the internal registry to uniquely identify open SafeBox instances
+     * and prevent concurrent access to the same file.
+     *
+     * @return The file name without extension.
+     */
+    internal fun getFileName(): String = file.nameWithoutExtension
+
     /**
      * Closes the underlying file channel and releases associated resources.
      * Must be called when SafeBoxBlobStore is no longer in use to prevent memory leaks.
@@ -284,8 +296,7 @@ internal class SafeBoxBlobStore private constructor(
             if (!file.exists()) {
                 file.createNewFile()
             }
-            val raf = RandomAccessFile(file, "rw")
-            return SafeBoxBlobStore(ioDispatcher, raf.channel)
+            return SafeBoxBlobStore(ioDispatcher, file)
         }
     }
 }

safebox/src/main/java/com/harrytmthy/safebox/storage/SafeBoxBlobStore.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.registry
+
+import kotlin.test.Test
+import kotlin.test.assertFailsWith
+
+class SafeBoxBlobFileRegistryTest {
+
+    @Test
+    fun `register and unregister should succeed`() {
+        val fileName = "test_file"
+
+        SafeBoxBlobFileRegistry.register(fileName)
+        SafeBoxBlobFileRegistry.unregister(fileName)
+        SafeBoxBlobFileRegistry.register(fileName)
+    }
+
+    @Test
+    fun `register twice should throw IllegalStateException`() {
+        val fileName = "duplicate_file"
+
+        SafeBoxBlobFileRegistry.register(fileName)
+
+        assertFailsWith<IllegalStateException> { SafeBoxBlobFileRegistry.register(fileName) }
+    }
+
+    @Test
+    fun `unregister non-registered file should succeed`() {
+        val fileName = "nonexistent_file"
+
+        SafeBoxBlobFileRegistry.unregister(fileName)
+    }
+}