@sigx/lynx-updates 0.6.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 Andreas Ekdahl
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,162 @@
+# @sigx/lynx-updates
+
+Over-the-air (OTA) bundle updates for sigx-lynx. Ship JS-only releases to
+installed apps without a store round-trip — with pluggable backends, every
+update mode from fully-automatic to fully-manual, and crash-driven rollback.
+
+```bash
+pnpm add @sigx/lynx-updates
+sigx prebuild   # links the native module + bakes the runtime fingerprint
+```
+
+## Quick start
+
+```tsx
+// src/main.tsx
+import { defineApp } from '@sigx/lynx';
+import { Updates } from '@sigx/lynx-updates';
+import App from './App';
+
+Updates.configure({
+    provider: { url: 'https://cdn.example.com/myapp/production/manifest.json' },
+    mode: 'silent',                    // download now, apply on next launch
+    checkOn: ['launch', 'foreground'],
+});
+
+defineApp(<App />).mount(null);
+```
+
+Publish an update:
+
+```bash
+sigx build                       # produces dist/main.lynx.bundle
+sigx updates:publish             # writes updates-dist/production/{manifest.json, updates/<id>/...}
+# upload updates-dist/production/ to any static host — done.
+```
+
+## Update modes
+
+| Mode | Behavior |
+|---|---|
+| `'silent'` (default) | Auto check + download; the update applies on the next cold launch. |
+| `'immediate'` | Auto check + download, then applies immediately via an in-place reload. |
+| `'manual'` | Nothing automatic — drive `checkForUpdate()` / `download()` / `apply()` yourself. |
+
+**Mandatory updates** (`mandatory: true` in the manifest, `--mandatory` on
+publish) override every mode: `state.mandatory` becomes true (block the UI —
+see `<UpdateGate>` in `@sigx/lynx-updates-ui`), and the update downloads and
+applies automatically. Opt out with `honorMandatory: false`.
+
+## Runtime-version compatibility
+
+An OTA bundle can only run on a native binary that has the native modules it
+expects. `sigx prebuild` computes a **runtime fingerprint** from the linked
+native modules' source content, the Lynx SDK version and the scaffold
+revision, and bakes it into the binary. `sigx updates:publish` stamps the
+same fingerprint into the manifest, and the client refuses mismatches:
+
+- Add/remove/update a native module package → new fingerprint → published
+  updates no longer match → ship a store release. The check surfaces this as
+  `{ type: 'incompatible' }` / the `incompatibleUpdate` event.
+- JS-only changes (any lockstep release that doesn't touch native code) keep
+  the fingerprint stable — published updates stay valid.
+- Prefer manual control? Pin it: `updates: { runtimeVersion: '1.0.0' }` in
+  `signalx.config.ts` (Expo-style — you own the compatibility guarantee).
+
+After a store update, all downloaded OTA updates are dropped automatically
+(the binary's fingerprint/versionCode no longer match the recorded state).
+
+## Rollback safety
+
+Updates commit in two phases. A downloaded update is *pending* until the app
+signals a healthy boot via `markReady()` — called automatically just after
+`configure()` (set `autoMarkReady: false` to gate on your own signal, e.g.
+first screen rendered). If the app crashes before `markReady()` on
+`rollback.maxFailedLaunches` consecutive launches (default 2), the native
+side deletes the update and reverts to the previous bundle. Detect it:
+
+```ts
+const { didRollBack } = await Updates.getCurrentlyRunning();
+```
+
+## API
+
+```ts
+Updates.configure(config)         // sync, idempotent — call before defineApp()
+Updates.checkForUpdate()          // → { type: 'update-available' | 'up-to-date' | 'incompatible', ... }
+Updates.download(manifest?)       // download + verify + stage for next launch
+Updates.apply()                   // apply staged update NOW (in-place reload; only rejects)
+Updates.markReady()               // health signal — commits the pending update
+Updates.getCurrentlyRunning()     // { updateId, isEmbedded, isFirstLaunchAfterUpdate, didRollBack, ... }
+Updates.clearUpdates()            // back to the baked bundle on next launch
+Updates.getState() / Updates.addListener(fn) / Updates.isAvailable()
+useUpdates()                      // Computed<UpdatesState> for components
+```
+
+State machine: `idle → checking → up-to-date | available | incompatible`,
+`available → downloading → ready → applying`; failures land in `error` and
+every transition fires a typed `UpdatesEvent`.
+
+## Custom backends
+
+The static-manifest provider is ~150 lines over `fetch`. Anything else —
+auth, signed manifests, staged rollout services, the Expo Updates protocol —
+implements `UpdateProvider` in its own package, no core changes:
+
+```ts
+import type { UpdateProvider } from '@sigx/lynx-updates';
+
+const myBackend: UpdateProvider = {
+    name: 'my-backend',
+    async checkForUpdate(ctx) {
+        // ctx: { platform, runtimeVersion, currentUpdateId, embeddedVersion, channel }
+        const res = await fetch(`https://updates.example.com/check`, { ... });
+        // normalize your protocol's answer to an UpdateManifest
+        return { type: 'update-available', manifest };
+    },
+    async resolveDownload(manifest) {
+        return { url: manifest.bundleUrl, sha256: manifest.sha256, headers: { Authorization: '…' } };
+    },
+};
+
+Updates.configure({ provider: myBackend });
+```
+
+The byte transfer always happens natively (streamed to disk with incremental
+SHA-256 verification) — providers only decide *what* to download.
+
+## Static manifest format
+
+`sigx updates:publish` maintains this document; serve it from any static host:
+
+```json
+{
+    "schemaVersion": 1,
+    "updates": [{
+        "id": "a1b2c3d4e5f60718",
+        "version": "1.4.2",
+        "channel": "production",
+        "platforms": ["android"],
+        "runtimeVersion": "fp1-3aa01b2c44de9921",
+        "bundleUrl": "updates/a1b2c3d4e5f60718/main.lynx.bundle",
+        "sha256": "<64-hex>",
+        "mandatory": false,
+        "createdAt": "2026-06-12T10:00:00Z",
+        "metadata": { "releaseNotes": "Bug fixes." }
+    }]
+}
+```
+
+One URL serves every channel/runtime version: old binaries keep matching
+their entries while new binaries pick up new ones. `bundleUrl` may be
+relative (resolved against the manifest URL).
+
+## Notes
+
+- **Dev builds**: when running from a dev server URL, OTA is inert (the dev
+  server owns the bundle). Baked-bundle debug runs DO consult the update
+  store, so rollback can be exercised locally.
+- **Web**: no-ops gracefully — every API degrades like the other native
+  modules.
+- Prebuilt UI (update prompt, blocking gate, progress, restart banner):
+  [`@sigx/lynx-updates-ui`](../lynx-updates-ui/README.md).

package/android/com/sigx/updates/UpdateDownloader.kt

@@ -0,0 +1,154 @@
+package com.sigx.updates
+
+import android.content.Context
+import android.util.Log
+import java.io.File
+import java.io.FileOutputStream
+import java.net.HttpURLConnection
+import java.net.URL
+import java.security.MessageDigest
+import java.util.concurrent.atomic.AtomicBoolean
+import org.json.JSONObject
+
+/**
+ * Streaming bundle downloader: bytes go straight to `tmp/<id>.partial` with
+ * an incremental SHA-256, then atomically move into `updates/<id>/` once the
+ * hash matches. Single-flight — concurrent calls beyond the first fail fast.
+ */
+object UpdateDownloader {
+
+    private const val TAG = "SigxUpdates"
+    private const val CONNECT_TIMEOUT_MS = 15_000
+    private const val READ_TIMEOUT_MS = 30_000
+    private const val PROGRESS_INTERVAL_MS = 150L
+
+    private val inFlight = AtomicBoolean(false)
+
+    /**
+     * @return null on success, or an error message. `code` semantics ride in
+     *         the message prefix; the module maps them to bridge errors.
+     */
+    fun download(
+        context: Context,
+        url: String,
+        expectedSha256: String,
+        updateId: String,
+        headers: Map<String, String>,
+        manifestJson: String,
+    ): String? {
+        // Already on disk and intact → success without a byte transferred.
+        if (UpdateStore.bundleFile(context, updateId).exists() &&
+            UpdateStore.verifySha256(context, updateId)
+        ) {
+            return null
+        }
+
+        if (!inFlight.compareAndSet(false, true)) {
+            return "E_DOWNLOAD_IN_PROGRESS: another download is running"
+        }
+        try {
+            return downloadLocked(context, url, expectedSha256, updateId, headers, manifestJson)
+        } finally {
+            inFlight.set(false)
+        }
+    }
+
+    private fun downloadLocked(
+        context: Context,
+        url: String,
+        expectedSha256: String,
+        updateId: String,
+        headers: Map<String, String>,
+        manifestJson: String,
+    ): String? {
+        val tmpDir = UpdateStore.tmpDir(context)
+        tmpDir.mkdirs()
+        val partial = File(tmpDir, "$updateId.partial")
+
+        var connection: HttpURLConnection? = null
+        try {
+            connection = URL(url).openConnection() as HttpURLConnection
+            connection.connectTimeout = CONNECT_TIMEOUT_MS
+            connection.readTimeout = READ_TIMEOUT_MS
+            connection.instanceFollowRedirects = true
+            for ((key, value) in headers) {
+                connection.setRequestProperty(key, value)
+            }
+
+            val status = connection.responseCode
+            if (status !in 200..299) {
+                return "Download failed: HTTP $status"
+            }
+
+            val totalBytes = connection.contentLengthLong.takeIf { it >= 0 }
+            val digest = MessageDigest.getInstance("SHA-256")
+            var receivedBytes = 0L
+            var lastProgressAt = 0L
+
+            connection.inputStream.use { input ->
+                FileOutputStream(partial).use { out ->
+                    val buffer = ByteArray(64 * 1024)
+                    while (true) {
+                        val read = input.read(buffer)
+                        if (read < 0) break
+                        out.write(buffer, 0, read)
+                        digest.update(buffer, 0, read)
+                        receivedBytes += read
+                        val now = System.currentTimeMillis()
+                        if (now - lastProgressAt >= PROGRESS_INTERVAL_MS) {
+                            lastProgressAt = now
+                            UpdatesEventBus.emitProgress(receivedBytes, totalBytes)
+                        }
+                    }
+                    out.fd.sync()
+                }
+            }
+            UpdatesEventBus.emitProgress(receivedBytes, totalBytes ?: receivedBytes)
+
+            val actual = digest.digest().joinToString("") { "%02x".format(it) }
+            if (!actual.equals(expectedSha256, ignoreCase = true)) {
+                partial.delete()
+                return "E_HASH_MISMATCH: expected $expectedSha256, got $actual"
+            }
+
+            // Atomic-ish promote: write metadata first, bundle rename last.
+            val dir = UpdateStore.updateDir(context, updateId)
+            dir.deleteRecursively()
+            dir.mkdirs()
+            val meta = try {
+                JSONObject(manifestJson)
+            } catch (e: Exception) {
+                JSONObject()
+            }
+            meta.put("sha256", expectedSha256.lowercase())
+            meta.put("sizeBytes", receivedBytes)
+            meta.put("sourceUrl", url)
+            meta.put("downloadedAt", System.currentTimeMillis())
+            // Atomic + fsynced: a truncated update.json would fail
+            // verifySha256() on next launch and roll back a perfectly good
+            // bundle as "corrupt".
+            val metaFile = UpdateStore.updateJsonFile(context, updateId)
+            val metaTmp = File(dir, "update.json.tmp")
+            FileOutputStream(metaTmp).use { out ->
+                out.write(meta.toString().toByteArray(Charsets.UTF_8))
+                out.fd.sync()
+            }
+            if (!metaTmp.renameTo(metaFile)) {
+                metaFile.delete()
+                metaTmp.renameTo(metaFile)
+            }
+            val bundle = UpdateStore.bundleFile(context, updateId)
+            if (!partial.renameTo(bundle)) {
+                partial.copyTo(bundle, overwrite = true)
+                partial.delete()
+            }
+            Log.i(TAG, "Downloaded update $updateId ($receivedBytes bytes)")
+            return null
+        } catch (e: Exception) {
+            partial.delete()
+            return "Download failed: ${e.message}"
+        } finally {
+            connection?.disconnect()
+        }
+    }
+}