@shipvo/capacitor 0.0.3 → 0.0.4

package/android/build.gradle

@@ -14,5 +14,7 @@ android {
 
 dependencies {
     implementation project(':capacitor-android')
+    // bzip2 for the BSDIFF40 patch step; the same version packages/runtime uses.
+    implementation 'org.apache.commons:commons-compress:1.21'
     testImplementation "junit:junit:4.13.2"
 }

package/android/src/main/java/dev/shipvo/capacitor/BundleStore.java

@@ -57,6 +57,18 @@ public final class BundleStore {
         for (int n; (n = in.read(buf)) > 0; ) out.write(buf, 0, n);
     }
 
+    /**
+     * Builds `name` from the stored `baseName` and a patch. Writes the file only when the patch, the
+     * rebuilt size and the rebuilt hash all check out; otherwise the caller downloads the full bundle.
+     */
+    public PatchStep.Outcome patch(String baseName, byte[] patch, String patchSha256, String name, long newSize, String newSha256, long maxMemory) {
+        byte[] base = null;
+        try { if (file(baseName).length() <= maxMemory) base = read(baseName); } catch (IOException | OutOfMemoryError e) { base = null; }
+        PatchStep.Outcome o = PatchStep.run(base, patch, patchSha256, newSize, newSha256, maxMemory);
+        if (o.bytes == null) return o;
+        try { write(name, o.bytes); return o; } catch (IOException e) { return new PatchStep.Outcome("full", null, e.getMessage()); }
+    }
+
     public void remove(String name) throws IOException { file(name).delete(); }
 
     public List<String> list() {

package/android/src/main/java/dev/shipvo/capacitor/Patch.java

@@ -0,0 +1,55 @@
+package dev.shipvo.capacitor;
+
+import java.io.ByteArrayInputStream;
+import java.io.IOException;
+import java.io.InputStream;
+import java.nio.charset.StandardCharsets;
+import org.apache.commons.compress.compressors.bzip2.BZip2CompressorInputStream;
+
+/** bspatch for the BSDIFF40 format (bsdiff 4.x): header, then bzip2 control, diff and extra blocks. Copied in small form from packages/runtime. */
+final class Patch {
+    private Patch() {}
+
+    private static long offtin(byte[] b, int o) {
+        long y = b[o + 7] & 0x7F;
+        for (int i = 6; i >= 0; i--) y = (y << 8) | (b[o + i] & 0xFF);
+        return (b[o + 7] & 0x80) != 0 ? -y : y;
+    }
+
+    private static void readFully(InputStream in, byte[] buf, int off, int len) throws IOException {
+        int n = 0;
+        while (n < len) {
+            int r = in.read(buf, off + n, len - n);
+            if (r <= 0) throw new IOException("patch truncated");
+            n += r;
+        }
+    }
+
+    static byte[] apply(byte[] old, byte[] patch) throws IOException {
+        if (patch.length < 32 || !"BSDIFF40".equals(new String(patch, 0, 8, StandardCharsets.US_ASCII))) throw new IOException("not a BSDIFF40 patch");
+        long ctrlLen = offtin(patch, 8), diffLen = offtin(patch, 16), newSize = offtin(patch, 24);
+        if (ctrlLen < 0 || diffLen < 0 || newSize < 0 || newSize > (64L << 20) || 32 + ctrlLen + diffLen > patch.length) throw new IOException("bad patch header");
+        int extraStart = (int) (32 + ctrlLen + diffLen);
+        byte[] out = new byte[(int) newSize];
+        try (InputStream ctrl = new BZip2CompressorInputStream(new ByteArrayInputStream(patch, 32, (int) ctrlLen));
+             InputStream diff = new BZip2CompressorInputStream(new ByteArrayInputStream(patch, 32 + (int) ctrlLen, (int) diffLen));
+             InputStream extra = new BZip2CompressorInputStream(new ByteArrayInputStream(patch, extraStart, patch.length - extraStart))) {
+            long oldPos = 0, newPos = 0;
+            byte[] c = new byte[24];
+            while (newPos < newSize) {
+                readFully(ctrl, c, 0, 24);
+                long x = offtin(c, 0), y = offtin(c, 8), z = offtin(c, 16);
+                if (x < 0 || y < 0 || newPos + x + y > newSize) throw new IOException("corrupt patch control");
+                readFully(diff, out, (int) newPos, (int) x);
+                for (int i = 0; i < x; i++) {
+                    long op = oldPos + i;
+                    if (op >= 0 && op < old.length) out[(int) newPos + i] += old[(int) op];
+                }
+                newPos += x; oldPos += x;
+                readFully(extra, out, (int) newPos, (int) y);
+                newPos += y; oldPos += z;
+            }
+        }
+        return out;
+    }
+}

package/android/src/main/java/dev/shipvo/capacitor/PatchStep.java

@@ -0,0 +1,35 @@
+package dev.shipvo.capacitor;
+
+/**
+ * Rule 9 on Android: apply a patch to the stored base bundle, check it, and say whether the
+ * caller may use the result. Anything else means "download the full bundle".
+ */
+public final class PatchStep {
+    private PatchStep() {}
+
+    /** Share of the app's heap limit that base + patch + output may use together. */
+    public static final double BUDGET_FRACTION = 0.4;
+    public static final String OUT_OF_MEMORY = "out_of_memory";
+    public static final String OVER_BUDGET = "over_memory_budget";
+
+    /** `bytes` is the rebuilt bundle when `via` is "patch"; otherwise `patchError` says why the full bundle is needed. */
+    public static final class Outcome {
+        public final String via; public final byte[] bytes; public final String patchError;
+        Outcome(String via, byte[] bytes, String patchError) { this.via = via; this.bytes = bytes; this.patchError = patchError; }
+    }
+
+    public static boolean fits(long base, long patch, long out, long maxMemory) {
+        return base + patch + out <= (long) (maxMemory * BUDGET_FRACTION);
+    }
+
+    public static Outcome run(byte[] base, byte[] patch, String patchSha256, long newSize, String newSha256, long maxMemory) {
+        if (base == null || !fits(base.length, patch.length, newSize, maxMemory)) return new Outcome("full", null, OVER_BUDGET);
+        try {
+            if (!BundleStore.sha256Hex(patch).equalsIgnoreCase(patchSha256)) throw new IllegalStateException("patch hash mismatch");
+            byte[] out = Patch.apply(base, patch);
+            if (out.length != newSize || !BundleStore.sha256Hex(out).equalsIgnoreCase(newSha256)) throw new IllegalStateException("patched bundle hash mismatch");
+            return new Outcome("patch", out, null);
+        } catch (OutOfMemoryError e) { return new Outcome("full", null, OUT_OF_MEMORY); }
+        catch (Exception e) { return new Outcome("full", null, String.valueOf(e.getMessage())); }
+    }
+}

package/android/src/main/java/dev/shipvo/capacitor/ShipvoPlugin.java

@@ -57,6 +57,20 @@ public class ShipvoPlugin extends Plugin {
         } catch (Exception e) { call.reject(e.getMessage()); }
     }
 
+    /** Rule 9: build `name` from the stored `base` and a patch. Resolves `via` "patch", or "full" with `patchError`. */
+    @PluginMethod
+    public void filePatch(PluginCall call) {
+        try {
+            byte[] patch = Base64.decode(call.getString("patch", ""), Base64.NO_WRAP);
+            PatchStep.Outcome o = store().patch(call.getString("base"), patch, call.getString("patchSha256"), call.getString("name"),
+                call.getLong("size", -1L), call.getString("sha256"), Runtime.getRuntime().maxMemory());
+            JSObject r = new JSObject();
+            r.put("via", o.via);
+            if (o.patchError != null) r.put("patchError", o.patchError);
+            call.resolve(r);
+        } catch (Exception e) { call.reject(e.getMessage()); }
+    }
+
     @PluginMethod
     public void fileRead(PluginCall call) {
         try {

package/dist/engine.js

@@ -170,28 +170,57 @@ export class ShipvoCapacitor {
             return { status: "none", release: p.release };
         const t1 = this.now();
         let bytes;
-        try {
-            const url = new URL(p.core.url, this.c.baseUrl.replace(/\/?$/, "/")).toString();
-            const r = await f(url);
-            if (!r.ok)
-                throw new Error(`HTTP ${r.status}`);
-            bytes = new Uint8Array(await r.arrayBuffer());
+        // Rule 9: a patch only when its from_sha256 is the hash of the bundle this device runs (the current release).
+        let via = "full";
+        let patchError;
+        let patchedBytes = 0;
+        const baseSha = s.current ? s.hashes[String(s.current)] : undefined;
+        const chosen = baseSha && this.c.files.patch ? p.core.patches?.find((x) => x.from_sha256 === baseSha) : undefined;
+        if (chosen && this.c.files.patch) {
+            try {
+                const r = await f(new URL(chosen.url, this.c.baseUrl.replace(/\/?$/, "/")).toString());
+                if (!r.ok)
+                    throw new Error(`patch HTTP ${r.status}`);
+                const patch = new Uint8Array(await r.arrayBuffer());
+                if (patch.byteLength !== chosen.size)
+                    throw new Error("patch size mismatch");
+                const o = await this.c.files.patch({ base: bundleName(s.current), patch, patchSha256: chosen.sha256, name: bundleName(p.release), size: p.core.size, sha256: p.core.sha256 });
+                via = o.via;
+                patchError = o.patchError;
+                if (o.via === "patch")
+                    patchedBytes = patch.byteLength;
+            }
+            catch (e) {
+                patchError = String(e?.message ?? e);
+            }
         }
-        catch (e) {
-            this.push(s, "download_failed");
-            await this.save();
-            return { status: "error", release: p.release, error: String(e?.message ?? e) };
+        if (via === "patch") {
+            bytes = new Uint8Array(0);
         }
+        else
+            try {
+                const url = new URL(p.core.url, this.c.baseUrl.replace(/\/?$/, "/")).toString();
+                const r = await f(url);
+                if (!r.ok)
+                    throw new Error(`HTTP ${r.status}`);
+                bytes = new Uint8Array(await r.arrayBuffer());
+            }
+            catch (e) {
+                this.push(s, "download_failed");
+                await this.save();
+                return { status: "error", release: p.release, error: String(e?.message ?? e) };
+            }
         const t2 = this.now();
-        // Size and sha-256 against the signed pointer.
-        if (bytes.byteLength !== p.core.size || (await sha256Hex(bytes)) !== p.core.sha256) {
+        // Size and sha-256 against the signed pointer. A patched bundle was already checked natively.
+        if (via === "full" && (bytes.byteLength !== p.core.size || (await sha256Hex(bytes)) !== p.core.sha256)) {
             this.block(s, p.release);
             return this.reject(s, "verify_failed", "bundle size or sha-256 does not match", p.release);
         }
         const t3 = this.now();
         // Stage: write the file, then point `pending` at it. A replaced pending release is dropped.
         const old = s.pending;
-        await this.c.files.write(bundleName(p.release), bytes);
+        if (via === "full")
+            await this.c.files.write(bundleName(p.release), bytes);
         s.hashes[String(p.release)] = p.core.sha256;
         s.pending = p.release;
         s.pendingBoots = 0;
@@ -200,7 +229,7 @@ export class ShipvoCapacitor {
         await this.save();
         if (apply)
             await this.reload();
-        return { status: "staged", release: p.release, bytes: bytes.byteLength, downloadMs: t2 - t1, verifyMs: t3 - t2, issuedAt: p.issued_at };
+        return { status: "staged", release: p.release, bytes: via === "patch" ? patchedBytes : bytes.byteLength, via, ...(patchError ? { patchError } : {}), downloadMs: t2 - t1, verifyMs: t3 - t2, issuedAt: p.issued_at };
     }
     push(s, e) { if (!s.events.includes(e) || !e.startsWith("pointer_rejected"))
         s.events.push(e); }

package/dist/index.d.ts

@@ -4,4 +4,4 @@ export type { ShipvoConfig } from "./engine.js";
 export { MemoryStore, MemoryFiles } from "./memory.js";
 export { verifyEd25519, sha256Hex, semverLess } from "./verify.js";
 export { NativeStore, NativeFiles, bootAndServe, bootAndSwitch } from "./native.js";
-export type { ShipvoNativePlugin } from "./native.js";
+export type { ShipvoNativePlugin, ShipvoPatchPlugin } from "./native.js";

package/dist/native.d.ts

@@ -37,6 +37,20 @@ export interface ShipvoNativePlugin {
         serving?: string;
     }>;
 }
+/** Build a stored bundle from another stored bundle and a BSDIFF40 patch. Native checks the patch hash, the rebuilt size and hash, and the memory budget. */
+export interface ShipvoPatchPlugin {
+    filePatch(o: {
+        base: string;
+        name: string;
+        patch: string;
+        patchSha256: string;
+        size: number;
+        sha256: string;
+    }): Promise<{
+        via: "patch" | "full";
+        patchError?: string;
+    }>;
+}
 /** `KeyValueStore` backed by the native plugin (SharedPreferences on Android). */
 export declare class NativeStore implements KeyValueStore {
     private n;
@@ -47,7 +61,9 @@ export declare class NativeStore implements KeyValueStore {
 /** `BundleFiles` backed by the native plugin (the app-private files directory on Android). */
 export declare class NativeFiles implements BundleFiles {
     private n;
-    constructor(n: ShipvoNativePlugin);
+    /** Set only when the plugin has `filePatch`, so the core tries a patch only where one can be applied. */
+    patch?: BundleFiles["patch"];
+    constructor(n: ShipvoNativePlugin & Partial<ShipvoPatchPlugin>);
     write(name: string, bytes: Uint8Array): Promise<void>;
     read(name: string): Promise<Uint8Array<ArrayBuffer>>;
     remove(name: string): Promise<void>;

package/dist/native.js

@@ -13,8 +13,12 @@ export class NativeStore {
 /** `BundleFiles` backed by the native plugin (the app-private files directory on Android). */
 export class NativeFiles {
     n;
+    /** Set only when the plugin has `filePatch`, so the core tries a patch only where one can be applied. */
+    patch;
     constructor(n) {
         this.n = n;
+        if (n.filePatch)
+            this.patch = (o) => n.filePatch({ base: o.base, name: o.name, patch: toB64(o.patch), patchSha256: o.patchSha256, size: o.size, sha256: o.sha256 });
     }
     async write(name, bytes) { await this.n.fileWrite({ name, data: toB64(bytes) }); }
     async read(name) { return fromB64((await this.n.fileRead({ name })).data); }

package/dist/types.d.ts

@@ -21,6 +21,9 @@ export type CheckResult = {
     verifyMs?: number;
     issuedAt?: string;
     error?: string;
+    /** How the bundle arrived: a patch against the current bundle, or the full file. `patchError` says why a patch was not used. */
+    via?: "patch" | "full";
+    patchError?: string;
     reason?: "hermes_bytecode_mismatch" | "native_module_missing" | "native_module_version";
 };
 export type HealthyResult = {
@@ -52,6 +55,21 @@ export interface KeyValueStore {
 export interface BundleFiles {
     write(name: string, bytes: Uint8Array): Promise<void>;
     remove(name: string): Promise<void>;
+    /**
+     * Optional. Build `name` from the stored `base` file and a patch (rule 9). Native checks the patch hash,
+     * then the rebuilt size and hash, and writes `name` only on success; otherwise it reports `via: "full"`.
+     */
+    patch?(o: {
+        base: string;
+        patch: Uint8Array;
+        patchSha256: string;
+        name: string;
+        size: number;
+        sha256: string;
+    }): Promise<{
+        via: "patch" | "full";
+        patchError?: string;
+    }>;
     /** Remove every file. Used when a new shell is installed. */
     clear(): Promise<void>;
 }

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@shipvo/capacitor",
-  "version": "0.0.3",
+  "version": "0.0.4",
   "type": "module",
   "license": "Apache-2.0",
   "description": "Signed over-the-air updates for Capacitor web bundles: the same release decisions and trust model as the Shipvo React Native runtime.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "dependencies": {
-    "@shipvo/schema": "^0.0.7"
+    "@shipvo/schema": "^0.0.8"
   },
   "devDependencies": {
     "@types/node": "^22.8.0",