expo-updates 0.14.6 → 0.15.0

package/CHANGELOG.md

@@ -10,19 +10,39 @@
 
 ### 💡 Others
 
-## 0.14.6 — 2022-09-26
+## 0.15.0 — 2022-10-25
 
-_This version does not introduce any user-facing changes._
+### 🛠 Breaking changes
+
+- [plugin] Upgrade minimum runtime requirement to Node 14 (LTS). ([#18204](https://github.com/expo/expo/pull/18204) by [@EvanBacon](https://github.com/EvanBacon))
+- Bumped iOS deployment target to 13.0 and deprecated support for iOS 12. ([#18873](https://github.com/expo/expo/pull/18873) by [@tsapeta](https://github.com/tsapeta))
+
+### 🎉 New features
 
-## 0.14.5 — 2022-08-22
+- [iOS] New logger and log reader for unifying logging support in expo-updates. ([#18284](https://github.com/expo/expo/pull/18284) by [@douglowder](https://github.com/douglowder))
+- [Android] New logger and log reader for unifying logging support in expo-updates. ([#18318](https://github.com/expo/expo/pull/18318) by [@douglowder](https://github.com/douglowder))
+- Add JS methods to read and clear client logs. ([#18390](https://github.com/expo/expo/pull/18390) by [@douglowder](https://github.com/douglowder))
+- Add Logger support for writing logs to a file; add Logger and associated classes to Android. ([#18513](https://github.com/expo/expo/pull/18513) by [@douglowder](https://github.com/douglowder))
+- Make extra header processing code consistent between manifests and assets. ([#18564](https://github.com/expo/expo/pull/18564) by [@wschurman](https://github.com/wschurman))
+- Type `UpdateCheckResult` and `UpdateFetchResult` to reflect when `manifest` is defined or not. ([#18577](https://github.com/expo/expo/pull/18577) by [@SimenB](https://github.com/SimenB))
 
 ### 🐛 Bug fixes
 
-- Fixed *with-node.sh* doesn't keep quotes when passing arguments to Node.js and caused build errors when there are spaces in target name. ([#18741](https://github.com/expo/expo/pull/18741) by [@kudo](https://github.com/kudo))
+- Fix small race condition in recovery code on Android where in very rare scenarios, a bundle could be downloaded twice. ([#18377](https://github.com/expo/expo/pull/18377) by [@esamelson](https://github.com/esamelson))
+- Fixed _with-node.sh_ doesn't keep quotes when passing arguments to Node.js and caused build errors when there are spaces in target name. ([#18741](https://github.com/expo/expo/pull/18741) by [@kudo](https://github.com/kudo))
 
-## 0.14.4 — 2022-08-12
+### 💡 Others
 
-_This version does not introduce any user-facing changes._
+- [plugin] Migrate import from @expo/config-plugins to expo/config-plugins and @expo/config-types to expo/config. ([#18855](https://github.com/expo/expo/pull/18855) by [@brentvatne](https://github.com/brentvatne))
+- Update doc block link for manifests. ([#18981](https://github.com/expo/expo/pull/18981) by [@EvanBacon](https://github.com/EvanBacon))
+- Drop `@expo/config-plugins` dependency in favor of peer dependency on `expo`. ([#18595](https://github.com/expo/expo/pull/18595) by [@EvanBacon](https://github.com/EvanBacon))
+- Log various errors with the new Updates logger; add E2E tests for the logger. ([#18810](https://github.com/expo/expo/pull/18810) by [@douglowder](https://github.com/douglowder))
+- [iOS] Flag to enable native debugging of updates. ([#19292](https://github.com/expo/expo/pull/19292) by [@douglowder](https://github.com/douglowder))
+- [Android] Flag to enable native debugging of updates. ([#19441](https://github.com/expo/expo/pull/19441) by [@douglowder](https://github.com/douglowder))
+
+### ⚠️ Notices
+
+- Added support for React Native 0.70.x. ([#19261](https://github.com/expo/expo/pull/19261) by [@kudo](https://github.com/kudo))
 
 ## 0.14.3 — 2022-07-25
 

package/android/build.gradle

@@ -4,7 +4,19 @@ apply plugin: 'kotlin-kapt'
 apply plugin: 'maven-publish'
 
 group = 'host.exp.exponent'
-version = '0.14.6'
+version = '0.15.0'
+
+def ex_updates_native_debug_env = System.getenv("EX_UPDATES_NATIVE_DEBUG") ?: "0"
+def ex_updates_native_debug = ex_updates_native_debug_env == "1" ? "true" : "false"
+
+// For native updates debugging, override these properties
+if (findProject(":app")) {
+  def appProjectExt = project(":app").ext
+  if (appProjectExt.has("react") && ex_updates_native_debug) {
+    appProjectExt.react.bundleInDebug = true
+    appProjectExt.react.devDisabledInDebug = true
+  }
+}
 
 apply from: "../scripts/create-manifest-android.gradle"
 
@@ -77,9 +89,10 @@ android {
     minSdkVersion safeExtGet("minSdkVersion", 21)
     targetSdkVersion safeExtGet("targetSdkVersion", 31)
     versionCode 31
-    versionName '0.14.6'
+    versionName '0.15.0'
     consumerProguardFiles("proguard-rules.pro")
     testInstrumentationRunner "androidx.test.runner.AndroidJUnitRunner"
+    buildConfigField("boolean", "EX_UPDATES_NATIVE_DEBUG", ex_updates_native_debug)
     // uncomment below to export the database schema when making changes
     /* javaCompileOptions {
       annotationProcessorOptions {

package/android/proguard-rules.pro

@@ -3,5 +3,5 @@
 }
 
 -keepclassmembers class com.facebook.react.devsupport.DisabledDevSupportManager {
-  private final com.facebook.react.bridge.DefaultNativeModuleCallExceptionHandler mDefaultNativeModuleCallExceptionHandler;
+  private final com.facebook.react.bridge.DefaultJSExceptionHandler mDefaultJSExceptionHandler;
 }

package/android/src/main/java/expo/modules/updates/UpdatesConfiguration.kt

@@ -6,6 +6,17 @@ import android.net.Uri
 import android.util.Log
 import expo.modules.updates.codesigning.CodeSigningConfiguration
 
+/**
+ * Holds global, immutable configuration values for updates, as well as doing some rudimentary
+ * validation.
+ *
+ * In most apps, these configuration values are baked into the build, and this class functions as a
+ * utility for reading and memoizing the values.
+ *
+ * In development clients (including Expo Go) where this configuration is intended to be dynamic at
+ * runtime and updates from multiple scopes can potentially be opened, multiple instances of this
+ * class may be created over the lifetime of the app, but only one should be active at a time.
+ */
 class UpdatesConfiguration private constructor (
   val isEnabled: Boolean,
   val expectsSignedManifest: Boolean,

package/android/src/main/java/expo/modules/updates/UpdatesController.kt

@@ -30,12 +30,34 @@ import expo.modules.updates.loader.LoaderTask
 import expo.modules.updates.loader.LoaderTask.BackgroundUpdateStatus
 import expo.modules.updates.loader.LoaderTask.LoaderTaskCallback
 import expo.modules.updates.loader.RemoteLoader
+import expo.modules.updates.logging.UpdatesErrorCode
+import expo.modules.updates.logging.UpdatesLogReader
+import expo.modules.updates.logging.UpdatesLogger
 import expo.modules.updates.manifest.UpdateManifest
 import expo.modules.updates.selectionpolicy.SelectionPolicy
 import expo.modules.updates.selectionpolicy.SelectionPolicyFactory
 import java.io.File
 import java.lang.ref.WeakReference
 
+/**
+ * Main entry point to expo-updates in normal release builds (development clients, including Expo
+ * Go, use a different entry point). Singleton that keeps track of updates state, holds references
+ * to instances of other updates classes, and is the central hub for all updates-related tasks.
+ *
+ * The `start` method in this class should be invoked early in the application lifecycle, via
+ * [UpdatesPackage]. It delegates to an instance of [LoaderTask] to start the process of loading and
+ * launching an update, then responds appropriately depending on the callbacks that are invoked.
+ *
+ * This class also provides getter methods to access information about the updates state, which are
+ * used by the exported [UpdatesModule] through [UpdatesService]. Such information includes
+ * references to: the database, the [UpdatesConfiguration] object, the path on disk to the updates
+ * directory, any currently active [LoaderTask], the current [SelectionPolicy], the error recovery
+ * handler, and the current launched update. This class is intended to be the source of truth for
+ * these objects, so other classes shouldn't retain any of them indefinitely.
+ *
+ * This class also optionally holds a reference to the app's [ReactNativeHost], which allows
+ * expo-updates to reload JS and send events through the bridge.
+ */
 class UpdatesController private constructor(
   context: Context,
   var updatesConfiguration: UpdatesConfiguration
@@ -62,6 +84,15 @@ class UpdatesController private constructor(
     }
   }
 
+  private fun purgeUpdatesLogsOlderThanOneDay(context: Context) {
+    UpdatesLogReader(context).purgeLogEntries {
+      if (it != null) {
+        Log.e(TAG, "UpdatesLogReader: error in purgeLogEntries", it)
+      }
+    }
+  }
+
+  private val logger = UpdatesLogger(context)
   private var isStarted = false
   private var loaderTask: LoaderTask? = null
   private var remoteLoadStatus = ErrorRecoveryDelegate.RemoteLoadStatus.IDLE
@@ -71,7 +102,7 @@ class UpdatesController private constructor(
     UpdatesUtils.getRuntimeVersion(updatesConfiguration)
   )
   val fileDownloader: FileDownloader = FileDownloader(context)
-  private val errorRecovery: ErrorRecovery = ErrorRecovery()
+  private val errorRecovery: ErrorRecovery = ErrorRecovery(context)
 
   private fun setRemoteLoadStatus(status: ErrorRecoveryDelegate.RemoteLoadStatus) {
     remoteLoadStatus = status
@@ -143,6 +174,10 @@ class UpdatesController private constructor(
   val isUsingEmbeddedAssets: Boolean
     get() = launcher?.isUsingEmbeddedAssets ?: false
 
+  /**
+   * Any process that calls this *must* manually release the lock by calling `releaseDatabase()` in
+   * every possible case (success, error) as soon as it is finished.
+   */
   fun getDatabase(): UpdatesDatabase = databaseHolder.database
 
   fun releaseDatabase() {
@@ -214,6 +249,8 @@ class UpdatesController private constructor(
       return
     }
 
+    purgeUpdatesLogsOlderThanOneDay(context)
+
     initializeDatabaseHandler()
     initializeErrorRecovery(context)
 
@@ -229,6 +266,7 @@ class UpdatesController private constructor(
       selectionPolicy,
       object : LoaderTaskCallback {
         override fun onFailure(e: Exception) {
+          logger.error("UpdatesController loaderTask onFailure: ${e.localizedMessage}", UpdatesErrorCode.None)
           launcher = NoDatabaseLauncher(context, updatesConfiguration, e)
           isEmergencyLaunch = true
           notifyController()
@@ -260,6 +298,7 @@ class UpdatesController private constructor(
               if (exception == null) {
                 throw AssertionError("Background update with error status must have a nonnull exception object")
               }
+              logger.error("UpdatesController onBackgroundUpdateFinished: Error: ${exception.localizedMessage}", UpdatesErrorCode.Unknown, exception)
               remoteLoadStatus = ErrorRecoveryDelegate.RemoteLoadStatus.IDLE
               val params = Arguments.createMap()
               params.putString("message", exception.message)
@@ -270,12 +309,14 @@ class UpdatesController private constructor(
                 throw AssertionError("Background update with error status must have a nonnull update object")
               }
               remoteLoadStatus = ErrorRecoveryDelegate.RemoteLoadStatus.NEW_UPDATE_LOADED
+              logger.info("UpdatesController onBackgroundUpdateFinished: Update available", UpdatesErrorCode.None)
               val params = Arguments.createMap()
               params.putString("manifestString", update.manifest.toString())
               UpdatesUtils.sendEventToReactNative(reactNativeHost, UPDATE_AVAILABLE_EVENT, params)
             }
             BackgroundUpdateStatus.NO_UPDATE_AVAILABLE -> {
               remoteLoadStatus = ErrorRecoveryDelegate.RemoteLoadStatus.IDLE
+              logger.error("UpdatesController onBackgroundUpdateFinished: No update available", UpdatesErrorCode.NoUpdatesAvailable)
               UpdatesUtils.sendEventToReactNative(
                 reactNativeHost,
                 UPDATE_NO_UPDATE_AVAILABLE_EVENT,
@@ -310,6 +351,7 @@ class UpdatesController private constructor(
         val remoteLoader = RemoteLoader(context, updatesConfiguration, database, fileDownloader, updatesDirectory, launchedUpdate)
         remoteLoader.start(object : Loader.LoaderCallback {
           override fun onFailure(e: Exception) {
+            logger.error("UpdatesController loadRemoteUpdate onFailure: ${e.localizedMessage}", UpdatesErrorCode.UpdateFailedToLoad, launchedUpdate?.loggingId, null)
             setRemoteLoadStatus(ErrorRecoveryDelegate.RemoteLoadStatus.IDLE)
             releaseDatabase()
           }

package/android/src/main/java/expo/modules/updates/UpdatesDevLauncherController.kt

@@ -17,17 +17,25 @@ import expo.modules.updatesinterface.UpdatesInterface.UpdateCallback
 import org.json.JSONObject
 import java.util.*
 
-// this unused import must stay because of versioning
-/* ktlint-disable no-unused-imports */
-
-/* ktlint-enable no-unused-imports */
-
+/**
+ * Main entry point to expo-updates in development builds with expo-dev-client. Singleton that still
+ * makes use of [UpdatesController] for keeping track of updates state, but provides capabilities
+ * that are not usually exposed but that expo-dev-client needs (launching and downloading a specific
+ * update by URL, allowing dynamic configuration, introspecting the database).
+ *
+ * Implements the external UpdatesInterface from the expo-updates-interface package. This allows
+ * expo-dev-client to compile without needing expo-updates to be installed.
+ */
 class UpdatesDevLauncherController : UpdatesInterface {
   private var mTempConfiguration: UpdatesConfiguration? = null
   override fun reset() {
     UpdatesController.instance.setLauncher(null)
   }
 
+  /**
+   * Fetch an update using a dynamically generated configuration object (including a potentially
+   * different update URL than the one embedded in the build).
+   */
   override fun fetchUpdateWithConfiguration(
     configuration: HashMap<String, Any>,
     context: Context,
@@ -99,6 +107,10 @@ class UpdatesDevLauncherController : UpdatesInterface {
 
     // ensure that we launch the update we want, even if it isn't the latest one
     val currentSelectionPolicy = controller.selectionPolicy
+    // Calling `setNextSelectionPolicy` allows the Updates module's `reloadAsync` method to reload
+    // with a different (newer) update if one is downloaded, e.g. using `fetchUpdateAsync`. If we
+    // set the default selection policy here instead, the update we are launching here would keep
+    // being launched by `reloadAsync` even if a newer one is downloaded.
     controller.setNextSelectionPolicy(
       SelectionPolicy(
         LauncherSelectionPolicySingleUpdate(update.id),

package/android/src/main/java/expo/modules/updates/UpdatesInterface.kt

@@ -13,6 +13,10 @@ import java.io.File
 import expo.modules.updates.UpdatesConfiguration
 /* ktlint-enable no-unused-imports */
 
+/**
+ * Interface implemented by the [UpdatesService] internal module and used by [UpdatesModule] to
+ * search for the correct internal module in the registry.
+ */
 interface UpdatesInterface {
   val configuration: UpdatesConfiguration
   val selectionPolicy: SelectionPolicy

package/android/src/main/java/expo/modules/updates/UpdatesModule.kt

@@ -17,12 +17,26 @@ import expo.modules.updates.loader.FileDownloader.ManifestDownloadCallback
 import expo.modules.updates.loader.Loader
 import expo.modules.updates.loader.RemoteLoader
 import expo.modules.updates.manifest.UpdateManifest
+import expo.modules.updates.logging.UpdatesErrorCode
+import expo.modules.updates.logging.UpdatesLogEntry
+import expo.modules.updates.logging.UpdatesLogReader
+import expo.modules.updates.logging.UpdatesLogger
+import java.util.Date
 
 // these unused imports must stay because of versioning
 /* ktlint-disable no-unused-imports */
 import expo.modules.updates.UpdatesConfiguration
 /* ktlint-enable no-unused-imports */
 
+/**
+ * Exported module which provides to the JS runtime information about the currently running update
+ * and updates state, along with methods to check for and download new updates, reload with the
+ * newest downloaded update applied, and read/clear native log entries.
+ *
+ * Communicates with the updates hub ([UpdatesController] in most apps, [ExpoUpdatesAppLoader] in
+ * Expo Go and legacy standalone apps) via [UpdatesService], an internal module which is overridden
+ * by [UpdatesBinding], a scoped module, in Expo Go.
+ */
 class UpdatesModule(
   context: Context,
   private val moduleRegistryDelegate: ModuleRegistryDelegate = ModuleRegistryDelegate()
@@ -40,6 +54,7 @@ class UpdatesModule(
   }
 
   override fun getConstants(): Map<String, Any> {
+    UpdatesLogger(context).info("UpdatesModule: getConstants called", UpdatesErrorCode.None)
     val constants = mutableMapOf<String, Any>()
     try {
       val updatesServiceLocal: UpdatesInterface? = updatesService
@@ -246,6 +261,55 @@ class UpdatesModule(
     }
   }
 
+  @ExpoMethod
+  fun readLogEntriesAsync(maxAge: Long, promise: Promise) {
+    AsyncTask.execute {
+      val reader = UpdatesLogReader(context)
+      val date = Date()
+      val epoch = Date(date.time - maxAge)
+      val results = reader.getLogEntries(epoch)
+        .mapNotNull { UpdatesLogEntry.create(it) }
+        .map { entry ->
+          Bundle().apply {
+            putLong("timestamp", entry.timestamp)
+            putString("message", entry.message)
+            putString("code", entry.code)
+            putString("level", entry.level)
+            if (entry.updateId != null) {
+              putString("updateId", entry.updateId)
+            }
+            if (entry.assetId != null) {
+              putString("assetId", entry.assetId)
+            }
+            if (entry.stacktrace != null) {
+              putStringArray("stacktrace", entry.stacktrace.toTypedArray())
+            }
+          }
+        }
+      promise.resolve(results)
+    }
+  }
+
+  @ExpoMethod
+  fun clearLogEntriesAsync(promise: Promise) {
+    AsyncTask.execute {
+      val reader = UpdatesLogReader(context)
+      reader.purgeLogEntries(
+        olderThan = Date()
+      ) { error ->
+        if (error != null) {
+          promise.reject(
+            "ERR_UPDATES_READ_LOGS",
+            "There was an error when clearing the expo-updates log file",
+            error
+          )
+        } else {
+          promise.resolve(null)
+        }
+      }
+    }
+  }
+
   companion object {
     private const val NAME = "ExpoUpdates"
 

package/android/src/main/java/expo/modules/updates/UpdatesPackage.kt

@@ -15,6 +15,10 @@ import expo.modules.core.interfaces.ReactNativeHostHandler
 import expo.modules.updates.UpdatesController
 /* ktlint-enable no-unused-imports */
 
+/**
+ * Defines the internal and exported modules for expo-updates, as well as the auto-setup behavior in
+ * applicable environments.
+ */
 class UpdatesPackage : Package {
   override fun createInternalModules(context: Context): List<InternalModule> {
     return listOf(UpdatesService(context) as InternalModule)
@@ -25,19 +29,20 @@ class UpdatesPackage : Package {
   }
 
   override fun createReactNativeHostHandlers(context: Context): List<ReactNativeHostHandler> {
+    val useNativeDebug = BuildConfig.EX_UPDATES_NATIVE_DEBUG
     val handler: ReactNativeHostHandler = object : ReactNativeHostHandler {
       private var mShouldAutoSetup: Boolean? = null
 
       override fun getJSBundleFile(useDeveloperSupport: Boolean): String? {
-        return if (shouldAutoSetup(context) && !useDeveloperSupport) UpdatesController.instance.launchAssetFile else null
+        return if (shouldAutoSetup(context) && (useNativeDebug || !useDeveloperSupport)) UpdatesController.instance.launchAssetFile else null
       }
 
       override fun getBundleAssetName(useDeveloperSupport: Boolean): String? {
-        return if (shouldAutoSetup(context) && !useDeveloperSupport) UpdatesController.instance.bundleAssetName else null
+        return if (shouldAutoSetup(context) && (useNativeDebug || !useDeveloperSupport)) UpdatesController.instance.bundleAssetName else null
       }
 
       override fun onWillCreateReactInstanceManager(useDeveloperSupport: Boolean) {
-        if (shouldAutoSetup(context) && !useDeveloperSupport) {
+        if (shouldAutoSetup(context) && (useNativeDebug || !useDeveloperSupport)) {
           UpdatesController.initialize(context)
         }
       }
@@ -45,7 +50,7 @@ class UpdatesPackage : Package {
       override fun onDidCreateReactInstanceManager(reactInstanceManager: ReactInstanceManager, useDeveloperSupport: Boolean) {
         // WHEN_VERSIONING_REMOVE_FROM_HERE
         // This code path breaks versioning and is not necessary for Expo Go.
-        if (shouldAutoSetup(context) && !useDeveloperSupport) {
+        if (shouldAutoSetup(context) && (useNativeDebug || !useDeveloperSupport)) {
           UpdatesController.instance.onDidCreateReactInstanceManager(reactInstanceManager)
         }
         // WHEN_VERSIONING_REMOVE_TO_HERE

package/android/src/main/java/expo/modules/updates/UpdatesService.kt

@@ -7,6 +7,7 @@ import expo.modules.updates.db.entity.AssetEntity
 import expo.modules.updates.db.entity.UpdateEntity
 import expo.modules.updates.launcher.Launcher.LauncherCallback
 import expo.modules.updates.loader.FileDownloader
+import expo.modules.updates.manifest.EmbeddedManifest
 import expo.modules.updates.selectionpolicy.SelectionPolicy
 import java.io.File
 
@@ -14,10 +15,16 @@ import java.io.File
 /* ktlint-disable no-unused-imports */
 import expo.modules.updates.UpdatesConfiguration
 import expo.modules.updates.UpdatesController
-import expo.modules.updates.manifest.EmbeddedManifest
-
 /* ktlint-enable no-unused-imports */
 
+/**
+ * Internal module whose purpose is to connect [UpdatesModule] with the central updates entry point.
+ * In most apps, this is [UpdatesController].
+ *
+ * In other cases, this module can be overridden at runtime to redirect [UpdatesModule] to a
+ * different entry point. This is the case in Expo Go, where this module is overridden by
+ * [UpdatesBinding] in order to get data from [ExpoUpdatesAppLoader].
+ */
 open class UpdatesService(protected var context: Context) : InternalModule, UpdatesInterface {
   override fun getExportedInterfaces(): List<Class<*>> {
     return listOf(UpdatesInterface::class.java as Class<*>)

package/android/src/main/java/expo/modules/updates/UpdatesUtils.kt

@@ -29,6 +29,9 @@ import java.text.SimpleDateFormat
 import java.util.*
 import kotlin.experimental.and
 
+/**
+ * Miscellaneous helper functions that are used by multiple classes in the library.
+ */
 object UpdatesUtils {
   private val TAG = UpdatesUtils::class.java.simpleName
 

package/android/src/main/java/expo/modules/updates/db/DatabaseHolder.kt

@@ -2,6 +2,17 @@ package expo.modules.updates.db
 
 import android.util.Log
 
+/**
+ * Wrapper class that provides a rudimentary locking mechanism for the database. This allows us to
+ * control what high-level operations involving the database can occur simultaneously. Most classes
+ * should access [UpdatesDatabase] through this class.
+ *
+ * Any process that calls `getDatabase` *must* manually release the lock by calling
+ * `releaseDatabase` in every possible case (success, error) as soon as it is finished.
+ *
+ * On iOS we use GCD queues as a more sophisticated way of achieving the same thing; we may also
+ * eventually want to migrate to a coroutine- or [Handler]-based system in lieu of this class.
+ */
 class DatabaseHolder(private val mDatabase: UpdatesDatabase) {
   private var isInUse = false
 

package/android/src/main/java/expo/modules/updates/db/Reaper.kt

@@ -8,6 +8,12 @@ import expo.modules.updates.manifest.ManifestMetadata
 import expo.modules.updates.selectionpolicy.SelectionPolicy
 import java.io.File
 
+/**
+ * Safely clears old, unused assets and updates from the filesystem and database.
+ *
+ * Should be run in a background process when no other updates-related events are occurring (e.g.
+ * update download).
+ */
 object Reaper {
   private val TAG = Reaper::class.java.simpleName
 

package/android/src/main/java/expo/modules/updates/db/UpdatesDatabase.kt

@@ -16,6 +16,31 @@ import expo.modules.updates.db.entity.UpdateAssetEntity
 import expo.modules.updates.db.entity.UpdateEntity
 import java.util.*
 
+/**
+ * SQLite database that keeps track of updates currently loaded/loading to disk, including the
+ * update manifest and metadata, status, and the individual assets (including bundles/bytecode) that
+ * comprise the update. (Assets themselves are stored on the device's file system, and a relative
+ * path is kept in SQLite.)
+ *
+ * SQLite allows a many-to-many relationship between updates and assets, which means we can keep
+ * only one copy of each asset on disk at a time while also being able to clear unused assets with
+ * relative ease (see [Reaper]).
+ *
+ * We use the Android Room library here, which provides a friendly abstraction over SQLite. The
+ * database schema is autogenerated from the `Entity` classes, and `DAO` classes provide access to
+ * the actual data.
+ *
+ * Occasionally it's necessary to add migrations when the data structures for updates or assets must
+ * change. Extra care must be taken here, since these migrations will happen on users' devices for
+ * apps we do not control. See
+ * https://github.com/expo/expo/blob/main/packages/expo-updates/guides/migrations.md for step by
+ * step instructions.
+ *
+ * [DatabaseHolder] provides a rudimentary locking mechanism, and most other classes access the
+ * database through this class. This allows control over what high-level operations involving the
+ * database can occur simultaneously - e.g. we don't want to be trying to download a new update at
+ * the same time the [Reaper] is running.
+ */
 @Database(
   entities = [UpdateEntity::class, UpdateAssetEntity::class, AssetEntity::class, JSONDataEntity::class],
   exportSchema = false,

package/android/src/main/java/expo/modules/updates/db/dao/AssetDao.kt

@@ -6,6 +6,9 @@ import expo.modules.updates.db.entity.UpdateAssetEntity
 import expo.modules.updates.db.entity.UpdateEntity
 import java.util.*
 
+/**
+ * Utility class for accessing and modifying data in SQLite relating to assets.
+ */
 @Dao
 abstract class AssetDao {
   /**

package/android/src/main/java/expo/modules/updates/db/dao/JSONDataDao.kt

@@ -7,6 +7,9 @@ import androidx.room.Transaction
 import expo.modules.updates.db.entity.JSONDataEntity
 import java.util.*
 
+/**
+ * Utility class for accessing and modifying data in the `json_data` SQLite table.
+ */
 @Dao
 abstract class JSONDataDao {
   /**

package/android/src/main/java/expo/modules/updates/db/dao/UpdateDao.kt

@@ -6,6 +6,9 @@ import expo.modules.updates.db.entity.UpdateEntity
 import expo.modules.updates.db.enums.UpdateStatus
 import java.util.*
 
+/**
+ * Utility class for accessing and modifying data in SQLite relating to updates.
+ */
 @Dao
 abstract class UpdateDao {
   /**

package/android/src/main/java/expo/modules/updates/db/entity/AssetEntity.kt

@@ -6,6 +6,14 @@ import expo.modules.updates.db.enums.HashType
 import org.json.JSONObject
 import java.util.*
 
+/**
+ * Data class that represents a (potential) row in the `assets` table in SQLite. The table schema is
+ * autogenerated from this file.
+ *
+ * The `id` field here only has meaning within an individual SQLite instance, as a foreign key;
+ * unlike [UpdateEntity.id], it does *not* uniquely identify an asset across multiple installations
+ * of an app. [AssetEntity.hash] should be used in most places where a unique identifier is needed.
+ */
 @Entity(tableName = "assets", indices = [Index(value = ["key"], unique = true)])
 class AssetEntity(@field:ColumnInfo(name = "key") var key: String?, var type: String?) {
   @PrimaryKey(autoGenerate = true) // 0 is treated as unset while inserting the entity into the db

package/android/src/main/java/expo/modules/updates/db/entity/JSONDataEntity.kt

@@ -6,6 +6,16 @@ import androidx.room.Index
 import androidx.room.PrimaryKey
 import java.util.*
 
+/**
+ * Data class representing a (potential) row of arbitrary JSON data to be stored in the `json_data`
+ * table in SQLite. The table schema is autogenerated from this file.
+ *
+ * Used to store per-scope data that should be persisted and overridden via key, such as items in
+ * [ManifestMetadata].
+ *
+ * The `scopeKey` field is only relevant in environments such as Expo Go in which updates from
+ * multiple scopes can be launched.
+ */
 @Entity(tableName = "json_data", indices = [Index(value = ["scope_key"])])
 class JSONDataEntity(
   var key: String,

package/android/src/main/java/expo/modules/updates/db/entity/UpdateAssetEntity.kt

@@ -6,6 +6,13 @@ import androidx.room.ForeignKey
 import androidx.room.Index
 import java.util.*
 
+/**
+ * Data class that represents a (potential) row in the `updates_assets` table, the schema for which
+ * is autogenerated from this file.
+ *
+ * This entity exists only within the database framework, to represent the many-to-many relation
+ * between updates and assets. It should not be used by any other outside classes.
+ */
 @Entity(
   tableName = "updates_assets",
   primaryKeys = ["update_id", "asset_id"],

package/android/src/main/java/expo/modules/updates/db/entity/UpdateEntity.kt

@@ -5,6 +5,18 @@ import expo.modules.updates.db.enums.UpdateStatus
 import org.json.JSONObject
 import java.util.*
 
+/**
+ * Data class that represents a (potential) row in the `updates` table in SQLite. The table schema
+ * is autogenerated from this file.
+ *
+ * expo-updates treats most fields (other than `status`, `keep`, `lastAccessed`, and the launch
+ * counts) as effectively immutable once in the database. This means an update server should never
+ * host two manifests with the same `id` that differ in any other field, as expo-updates will not
+ * take the difference into account.
+ *
+ * The `scopeKey` field is only relevant in environments such as Expo Go in which updates from
+ * multiple scopes can be launched.
+ */
 @Entity(
   tableName = "updates",
   foreignKeys = [
@@ -36,6 +48,11 @@ class UpdateEntity(
 
   var keep = false
 
+  val loggingId: String
+    get() {
+      return id.toString().lowercase()
+    }
+
   @ColumnInfo(name = "last_accessed")
   var lastAccessed: Date = Date()