@rovq/react-native 0.1.0 → 0.2.0

package/README.md

@@ -68,10 +68,54 @@ useEffect(() => {
 }, []);
 ```
 
-To ask the user before downloading, use `checkForUpdate`, `downloadUpdate({ onProgress })`, `installUpdate`, and `restartApp`. Failures throw `RovqError` with a stable `code`.
+For full control, use `checkForUpdate`, `downloadUpdate({ onProgress })`, `installUpdate`, and `restartApp`. They throw `RovqError` with a stable `code`.
+
+## Updating in the foreground or the background
+
+Wrap your app in `RovqUpdateGate`, and choose how updates arrive:
+
+```tsx
+import { RovqUpdateGate } from '@rovq/react-native';
+
+export default function Root() {
+  return (
+    <RovqUpdateGate mode="auto" variant="bar">
+      <App />
+    </RovqUpdateGate>
+  );
+}
+```
+
+| `mode`           | What the user sees                                                                |
+| ---------------- | --------------------------------------------------------------------------------- |
+| `background`     | Nothing. The update downloads while they use the app, and loads on the next start |
+| `foreground`     | A progress screen, then the app restarts on the new version at once               |
+| `auto` (default) | Foreground for a release published with `--mandatory`, background otherwise       |
+
+`variant` is `bar` or `percent`. The gate shows your app while it checks, so a slow server never holds it up, and it confirms the running release with `notifyApplicationReady` for you. Pass `title`, `color`, and `backgroundColor`, or draw your own screen with `renderProgress={(state) => ...}`.
+
+To build your own interface, use the hook and the progress component:
+
+```tsx
+import { RovqUpdateProgress, useRovqUpdate } from '@rovq/react-native';
+
+const { phase, progress, update, error, check } = useRovqUpdate({ mode: 'background' });
+// phase: idle, checking, upToDate, downloading, installing, ready, restarting, or error
+{
+  progress !== null && <RovqUpdateProgress progress={progress} variant="percent" />;
+}
+```
+
+A failure never throws. It ends in the `error` phase, and the app keeps running what it has.
+
+"Background" means while the app is open. When the user leaves the app, the system can pause the download, and it continues from where it stopped the next time the app runs.
 
 Publish updates with [`@rovq/cli`](https://www.npmjs.com/package/@rovq/cli).
 
+## Downloading only what changed
+
+A release published by `@rovq/cli` 0.2 lists its files, and the SDK downloads only those it does not already have. Files from the release before, and assets inside the app itself, are checked against the signed hash and reused. A change to one screen downloads only the bundle, however many images and sounds the app has.
+
 ## License
 
 MIT

package/android/src/main/java/com/rovq/engine/ManifestVerifier.kt

@@ -2,14 +2,14 @@ package com.rovq.engine
 
 import com.google.crypto.tink.subtle.Ed25519Verify
 import java.security.GeneralSecurityException
+import org.json.JSONArray
 import org.json.JSONException
 import org.json.JSONObject
 
 private const val PUBLIC_KEY_SIZE = 32
 private const val SIGNATURE_SIZE = 64
-private const val MANIFEST_VERSION = 1
 private const val PLATFORM = "ANDROID"
-private val MANIFEST_FIELDS = setOf(
+private val STREAM_FIELDS = setOf(
     "version",
     "releaseId",
     "deploymentKey",
@@ -18,19 +18,30 @@ private val MANIFEST_FIELDS = setOf(
     "binaryVersion",
     "sequence",
     "mandatory",
-    "package",
 )
+
+// Version 1 names one ZIP package. Version 2 lists files. See docs/file-packages.md.
+private val ZIP_MANIFEST_FIELDS = STREAM_FIELDS + "package"
+private val FILES_MANIFEST_FIELDS = STREAM_FIELDS + "files"
 private val PACKAGE_FIELDS = setOf("hash", "size")
+private val FILE_FIELDS = setOf("path", "hash", "size")
 private val UUID_PATTERN = Regex("^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$")
 private val HASH_PATTERN = Regex("^[0-9a-f]{64}$")
 
+/** One file of a release made of files, from a verified manifest. */
+data class ManifestFile(val path: String, val hash: String, val size: Long)
+
 /** Facts from a manifest whose signature has been verified. Nothing else should be trusted. */
 data class VerifiedManifest(
     val releaseId: String,
     val sequence: Long,
     val mandatory: Boolean,
+    /** The ZIP package's hash. Empty for a release made of files. */
     val packageHash: String,
+    /** The ZIP package's size, or all files together. */
     val packageSize: Long,
+    /** Set for a release made of files, sorted by path. Null for a ZIP package. */
+    val files: List<ManifestFile>? = null,
 )
 
 /**
@@ -112,8 +123,9 @@ class ManifestVerifier(
 
     private fun parseAndCheck(manifest: String): VerifiedManifest {
         val root = parseObject(manifest)
-        requireOnlyFields(root, MANIFEST_FIELDS)
-        if (longField(root, "version") != MANIFEST_VERSION.toLong()) invalid("Unknown manifest version")
+        val version = longField(root, "version")
+        if (version != 1L && version != 2L) invalid("Unknown manifest version")
+        requireOnlyFields(root, if (version == 1L) ZIP_MANIFEST_FIELDS else FILES_MANIFEST_FIELDS)
 
         val releaseId = stringField(root, "releaseId")
         // Later used as a folder name, so it must be exactly a UUID.
@@ -125,6 +137,16 @@ class ManifestVerifier(
         val mandatory = root.opt("mandatory") as? Boolean ?: invalid("mandatory must be a boolean")
         stringField(root, "binaryVersion")
 
+        // A valid signature for another deployment, platform or runtime must not install here.
+        requireMatch("deploymentKey", stringField(root, "deploymentKey"), deploymentKey)
+        requireMatch("platform", stringField(root, "platform"), PLATFORM)
+        requireMatch("runtimeVersion", stringField(root, "runtimeVersion"), runtimeVersion)
+
+        if (version == 2L) {
+            val files = fileList(root.opt("files"))
+            return VerifiedManifest(releaseId, sequence, mandatory, "", files.sumOf { it.size }, files)
+        }
+
         val packageInfo = root.opt("package") as? JSONObject ?: invalid("package must be an object")
         requireOnlyFields(packageInfo, PACKAGE_FIELDS)
         val hash = stringField(packageInfo, "hash")
@@ -132,14 +154,49 @@ class ManifestVerifier(
         val size = longField(packageInfo, "size")
         if (size <= 0) invalid("package size must be positive")
 
-        // A valid signature for another deployment, platform or runtime must not install here.
-        requireMatch("deploymentKey", stringField(root, "deploymentKey"), deploymentKey)
-        requireMatch("platform", stringField(root, "platform"), PLATFORM)
-        requireMatch("runtimeVersion", stringField(root, "runtimeVersion"), runtimeVersion)
-
         return VerifiedManifest(releaseId, sequence, mandatory, hash, size)
     }
 
+    /**
+     * The same rules as a ZIP package, because each path is written to disk the same way.
+     * Sorted by UTF-16 code units, as JavaScript and Kotlin both sort, so one set of files has
+     * one signed form.
+     */
+    private fun fileList(value: Any?): List<ManifestFile> {
+        val list = value as? JSONArray ?: invalid("files must be an array")
+        if (list.length() == 0 || list.length() > PackageRules.MAX_ENTRIES) {
+            invalid("A package must have from 1 to ${PackageRules.MAX_ENTRIES} files")
+        }
+        val files = ArrayList<ManifestFile>(list.length())
+        val seen = HashSet<String>()
+        var total = 0L
+        for (index in 0 until list.length()) {
+            val entry = list.opt(index) as? JSONObject ?: invalid("Each file must be an object")
+            requireOnlyFields(entry, FILE_FIELDS)
+            val path = stringField(entry, "path")
+            PackageRules.findPathProblem(path)?.let { invalid("The file $path $it") }
+            val previous = files.lastOrNull()
+            if (previous != null && previous.path >= path) {
+                invalid("The files must be sorted by path, each path once")
+            }
+            if (!seen.add(PackageRules.pathIdentity(path))) {
+                invalid("The file $path differs from another only by letter case")
+            }
+            val hash = stringField(entry, "hash")
+            if (!HASH_PATTERN.matches(hash)) invalid("The file $path has a malformed hash")
+            val size = longField(entry, "size")
+            // Bounded before adding, so the total cannot overflow.
+            if (size < 0 || size > PackageRules.MAX_TOTAL_SIZE) invalid("The file $path has an invalid size")
+            total += size
+            if (total > PackageRules.MAX_TOTAL_SIZE) invalid("The files are larger than the allowed total")
+            files += ManifestFile(path, hash, size)
+        }
+        val bundle = files.firstOrNull { it.path == PackageRules.BUNDLE_FILE_NAME }
+            ?: invalid("The bundle file is missing")
+        if (bundle.size == 0L) invalid("The bundle file is empty")
+        return files
+    }
+
     private fun parseObject(text: String): JSONObject = try {
         JSONObject(text)
     } catch (error: JSONException) {

package/android/src/main/java/com/rovq/engine/PackageDownloader.kt

@@ -29,16 +29,21 @@ class PackageDownloader(
      * deletes it. It counts as good only once the whole file matches the signed hash, so a partial
      * or wrong file can never be mistaken for a good one.
      *
+     * @param hash the signed SHA-256 of the whole file.
+     * @param size the signed size of the whole file.
+     * @param extraSpace room needed beyond the file itself, such as for extracting it.
      * @param onProgress receives bytes received so far and the total.
      */
     fun download(
         url: String,
-        manifest: VerifiedManifest,
+        hash: String,
+        size: Long,
         target: File,
+        extraSpace: Long = 0,
         onProgress: (received: Long, total: Long) -> Unit = { _, _ -> },
     ) {
         try {
-            downloadToFile(url, manifest, target, onProgress)
+            downloadToFile(url, Expected(hash, size), target, extraSpace, onProgress)
         } catch (error: RovqException) {
             if (error.code != RovqErrorCode.DOWNLOAD_FAILED) target.delete()
             throw error
@@ -48,10 +53,17 @@ class PackageDownloader(
         }
     }
 
+    /** The signed facts a download must end up matching. */
+    private data class Expected(val hash: String, val size: Long)
+
+    /** Room left in a folder. Replaced in tests. */
+    internal fun freeSpaceIn(folder: File): Long = freeSpace(folder)
+
     private fun downloadToFile(
         url: String,
-        manifest: VerifiedManifest,
+        expected: Expected,
         target: File,
+        extraSpace: Long,
         onProgress: (Long, Long) -> Unit,
     ) {
         val parsed = try {
@@ -64,11 +76,15 @@ class PackageDownloader(
         }
 
         val digest = MessageDigest.getInstance("SHA-256")
-        val existing = readExisting(target, manifest, digest)
-        checkFreeSpace(target, manifest, existing)
+        val existing = readExisting(target, expected, digest)
+        checkFreeSpace(target, expected.size - existing + extraSpace)
         var received = existing
-        if (existing == manifest.packageSize) {
-            verifyHash(digest, manifest)
+        if (existing == expected.size) {
+            // An empty file has nothing to download, but must still exist.
+            if (!target.isFile && !target.createNewFile()) {
+                throw RovqException(RovqErrorCode.STORAGE_FAILED, "Could not create the file")
+            }
+            verifyHash(digest, expected)
             return
         }
 
@@ -119,7 +135,7 @@ class PackageDownloader(
                         if (count < 0) break
                         received += count
                         // Stops at once, so a wrong server cannot fill the disk.
-                        if (received > manifest.packageSize) {
+                        if (received > expected.size) {
                             throw RovqException(
                                 RovqErrorCode.SIZE_MISMATCH,
                                 "Download is larger than the signed size",
@@ -131,7 +147,7 @@ class PackageDownloader(
                         } catch (error: IOException) {
                             throw RovqException(RovqErrorCode.STORAGE_FAILED, "Could not write the file", error)
                         }
-                        onProgress(received, manifest.packageSize)
+                        onProgress(received, expected.size)
                     }
                 }
                 // Forces the bytes to disk, so power loss cannot leave a file that looks complete.
@@ -143,16 +159,16 @@ class PackageDownloader(
 
         // A lost connection can look like a normal end of file, so a short download counts
         // as a network failure, which is worth retrying.
-        if (received < manifest.packageSize) {
+        if (received < expected.size) {
             throw RovqException(RovqErrorCode.DOWNLOAD_FAILED, "The download ended early")
         }
-        verifyHash(digest, manifest)
+        verifyHash(digest, expected)
     }
 
     /** @return how many bytes are already there, after adding them to [digest]. */
-    private fun readExisting(target: File, manifest: VerifiedManifest, digest: MessageDigest): Long {
+    private fun readExisting(target: File, expected: Expected, digest: MessageDigest): Long {
         if (!target.isFile) return 0
-        if (target.length() > manifest.packageSize) {
+        if (target.length() > expected.size) {
             target.delete()
             return 0
         }
@@ -167,21 +183,16 @@ class PackageDownloader(
         return target.length()
     }
 
-    /**
-     * Extracting needs room too, and its size is unknown until then, so this asks for the package
-     * twice. A package can still expand further, and extraction reports that if it happens.
-     */
-    private fun checkFreeSpace(target: File, manifest: VerifiedManifest, existing: Long) {
-        val needed = manifest.packageSize - existing + manifest.packageSize
+    private fun checkFreeSpace(target: File, needed: Long) {
         val folder = target.parentFile ?: target
         if (freeSpace(folder) < needed) {
             throw RovqException(RovqErrorCode.STORAGE_FAILED, "Not enough free space for this update")
         }
     }
 
-    private fun verifyHash(digest: MessageDigest, manifest: VerifiedManifest) {
+    private fun verifyHash(digest: MessageDigest, expected: Expected) {
         val hash = digest.digest().joinToString("") { "%02x".format(it) }
-        if (hash != manifest.packageHash) {
+        if (hash != expected.hash) {
             throw RovqException(RovqErrorCode.HASH_MISMATCH, "Download does not match the signed hash")
         }
     }

package/android/src/main/java/com/rovq/engine/RovqEngine.kt

@@ -104,6 +104,8 @@ class RovqEngine(
     private val rootDir: File,
     private val config: EngineConfig,
     private val service: UpdateService = HttpUpdateService(config.apiUrl, config.allowInsecureUrls),
+    /** The app's own assets, which a release made of files reuses instead of downloading. */
+    builtInFiles: BuiltInFiles? = null,
     private val clock: () -> Long = System::currentTimeMillis,
 ) {
     private val store: EngineStateStore
@@ -126,6 +128,7 @@ class RovqEngine(
             rootDir,
             verifier,
             PackageDownloader(config.allowInsecureUrls),
+            builtInFiles,
         )
         state = loadState()
         verifier.revokedPublicKeys = state.revokedPublicKeys
@@ -396,7 +399,11 @@ class RovqEngine(
             state.highestSequence
         }
         return try {
-            val manifest = installer.install(offered, highestSequence, onProgress).manifest
+            val deviceId = synchronized(this) { state.deviceId }
+            val links = FileLinks { releaseId, hashes ->
+                service.fileLinks(config.deploymentKey, deviceId, releaseId, hashes)
+            }
+            val manifest = installer.install(offered, highestSequence, links, onProgress).manifest
             synchronized(this) {
                 save(
                     state.copy(