DownloadTask.java

package cn.reactnative.modules.update;

import android.content.Context;
import android.os.Handler;
import android.os.Looper;
import android.util.Log;
import com.facebook.react.bridge.Arguments;
import com.facebook.react.bridge.WritableMap;
import java.io.File;
import java.io.FileOutputStream;
import java.io.IOException;
import java.io.InputStream;
import java.nio.charset.StandardCharsets;
import java.security.DigestOutputStream;
import java.security.MessageDigest;
import java.util.ArrayList;
import java.util.Enumeration;
import java.util.zip.ZipEntry;
import okhttp3.Call;
import okhttp3.OkHttpClient;
import okhttp3.Request;
import okhttp3.Response;
import okhttp3.ResponseBody;
import okio.BufferedSink;
import okio.BufferedSource;
import okio.Okio;
import org.json.JSONObject;

class DownloadTask implements Runnable {
    // Bundle delta entry inside a patch archive, stored encoded.
    private static final String BUNDLE_DELTA_ENTRY =
        Texts.BUNDLE_DELTA_ENTRY;

    // Resume sidecars are a few hundred bytes of JSON.
    private static final long MAX_SIDECAR_BYTES = 64 * 1024;
    // When the server does not report Content-Length we cannot key progress
    // events on percentage change, so throttle by bytes to avoid flooding the
    // bridge (e.g. a 20MB chunked download would otherwise emit ~5000 events).
    private static final long PROGRESS_BYTES_THRESHOLD = 256 * 1024;
    // Explicit timeouts: the default client has no call timeout, so a
    // slow-dripping connection could occupy the single-threaded download
    // executor indefinitely and starve queued tasks. The call timeout is a
    // generous upper bound sized for large full-package downloads.
    private static final OkHttpClient HTTP_CLIENT = HttpClients.base().newBuilder()
            .connectTimeout(15, java.util.concurrent.TimeUnit.SECONDS)
            .readTimeout(30, java.util.concurrent.TimeUnit.SECONDS)
            .writeTimeout(30, java.util.concurrent.TimeUnit.SECONDS)
            .callTimeout(10, java.util.concurrent.TimeUnit.MINUTES)
            .build();

    // Two-phase install (cpp/patch_core/install_record.h): all unpack/patch
    // work happens in <hash>.staging; the final <hash> directory only ever
    // appears through an atomic rename after the completion record was
    // written, so a crash or failure can never leave a half-installed
    // directory that looks like a version.
    private File stagingDirectory() {
        return InstallRecord.stagingDirectoryFor(params.unzipDirectory);
    }

    // SHA-256 of the downloaded archive, recorded in the install record.
    private String artifactSha256 = "";
    // The archive digest computed while its bytes streamed to disk (a resumed
    // transfer first hashes the prefix already on disk); null when this task
    // did not stream the whole file itself and it must be hashed from disk.
    private String streamedArchiveSha256;
    // Digest of the bundle computed while a full package was extracted;
    // null when the bundle was produced some other way (patch tasks).
    private String stagedBundleSha256;

    /** What a staged patch archive declared, as the native core consumes it. */
    private static final class PatchArchiveContents {
        final String[] entryNames;
        // The raw __diff.json bytes (UTF-8): parsed only by the native core
        // (cpp/patch_core/patch_manifest.h), never here.
        final byte[] manifestJson;

        PatchArchiveContents(ArrayList<String> entryNames, byte[] manifestJson) {
            this.entryNames = entryNames.toArray(new String[0]);
            this.manifestJson = manifestJson;
        }
    }

    private final Context context;
    private final DownloadTaskParams params;
    private final Handler mainHandler = new Handler(Looper.getMainLooper());
    private final BundledResourceCopier bundledResourceCopier;
    private String hash;
    // Set once downloadFile() returns: failures after this point in a patch
    // task are patch-application failures, not download failures.
    private boolean downloadPhaseCompleted = false;

    DownloadTask(Context context, DownloadTaskParams params) {
        this.context = context.getApplicationContext();
        this.params = params;
        this.bundledResourceCopier = new BundledResourceCopier(this.context);
    }

    private void postProgress(final long received, final long total) {
        // Cross-platform progress contract: unknown length is reported as
        // total=0, never a raw -1 (OkHttp's contentLength for chunked/gzip).
        final long normalizedTotal = total > 0 ? total : 0;
        mainHandler.post(() -> {
            WritableMap progress = Arguments.createMap();
            progress.putDouble("received", received);
            progress.putDouble("total", normalizedTotal);
            progress.putString("hash", hash);
            UpdateEventEmitter.sendEvent("RCTPushyDownloadProgress", progress);
        });
    }

    // Sidecar next to the archive recording what a partial download belongs
    // to (url + validators + total). An archive without a matching sidecar is
    // untrusted and restarted from zero; the pair is deleted together with
    // the archive once it is consumed or classified as poisoned.
    private static File resumeSidecarFile(File archive) {
        return new File(archive.getPath() + ".resume");
    }

    static void deleteResumeSidecar(File archive) {
        File sidecar = resumeSidecarFile(archive);
        if (sidecar.exists() && !sidecar.delete() && BuildConfig.DEBUG) {
            Log.w(Texts.LOG_TAG, "Failed to delete resume sidecar " + sidecar);
        }
    }

    // The sidecar's text, "" when there is none or it cannot be one (larger
    // than a sidecar ever is, unreadable): ResumePlan treats both as "no
    // trusted partial".
    private static String readSidecarText(File sidecar) {
        if (!sidecar.isFile()) {
            return "";
        }
        try {
            return UpdateFileUtils.readSmallUtf8(sidecar, MAX_SIDECAR_BYTES);
        } catch (Throwable e) {
            return "";
        }
    }

    private static void writeSidecarText(File sidecar, String text) {
        try {
            UpdateFileUtils.ensureParentDirectory(sidecar);
            try (java.io.FileOutputStream out = new java.io.FileOutputStream(sidecar)) {
                out.write(text.getBytes(StandardCharsets.UTF_8));
            }
        } catch (Throwable e) {
            // Non-fatal: without a sidecar the next attempt starts from zero.
            Log.w(Texts.LOG_TAG, "Failed to persist resume sidecar: " + e);
        }
    }

    // A ResumePlan result; null from the native core means memory ran out.
    private static JSONObject resumeDecision(String json) throws IOException {
        if (json == null) {
            throw new IOException("resume plan failed");
        }
        try {
            return new JSONObject(json);
        } catch (org.json.JSONException e) {
            throw new IOException("resume plan failed", e);
        }
    }

    private void downloadFile() throws IOException {
        this.hash = params.hash;
        streamedArchiveSha256 = null;
        String url = params.url;
        File writePath = params.targetFile;
        File sidecar = resumeSidecarFile(writePath);
        UpdateFileUtils.ensureParentDirectory(writePath);

        // Cross-launch resume (NATIVE_CHECKUPDATE_DESIGN §11.4): a brick gets
        // a few hundred milliseconds per launch plus a bounded crash-rescue
        // window, so every partial byte must survive process death and count.
        // What to request is the shared core's decision (ResumePlan).
        String sidecarText = readSidecarText(sidecar);
        JSONObject plan = resumeDecision(ResumePlan.planRequest(
            sidecarText, url, writePath.isFile() ? writePath.length() : 0));
        String action = plan.optString("action");
        if ("complete".equals(action)) {
            // Fully received in a previous attempt (the process died
            // between download end and unzip): nothing left to transfer.
            long total = plan.optLong("total");
            downloadPhaseCompleted = true;
            postProgress(total, total);
            return;
        }
        long resumeOffset = 0;
        JSONObject headers = null;
        if ("resume".equals(action)) {
            resumeOffset = plan.optLong("offset");
            headers = plan.optJSONObject("headers");
        } else {
            discardPartial(writePath);
            sidecarText = "";
        }

        if (!transferArchive(url, writePath, sidecar, sidecarText, resumeOffset, headers)) {
            // The partial no longer matches what the server serves (a stale
            // 416, an untrusted range response): drop it and retry once from
            // zero.
            discardPartial(writePath);
            if (!transferArchive(url, writePath, sidecar, "", 0, null)) {
                throw new IOException("Server rejected the download range for " + url);
            }
        }
        downloadPhaseCompleted = true;
    }

    /** Drops a partial download and its sidecar; throws when the bytes stay. */
    private static void discardPartial(File archive) throws IOException {
        if (archive.exists() && !archive.delete()) {
            throw new IOException("Failed to replace existing file: " + archive);
        }
        deleteResumeSidecar(archive);
    }

    /**
     * One HTTP transfer, appending from resumeOffset when the server honours
     * the range. Returns false only when the partial must be discarded and the
     * download retried from zero (ResumePlan's "restart"); throws on every
     * other failure.
     */
    private boolean transferArchive(
        String url, File writePath, File sidecar, String sidecarText, long resumeOffset,
        JSONObject resumeHeaders
    ) throws IOException {
        Request.Builder builder = new Request.Builder().url(url);
        if (resumeHeaders != null) {
            // Range, Accept-Encoding: identity and If-Range (ResumePlan).
            // Fresh downloads send none of them and keep OkHttp's
            // transparent gzip, which decompresses and strips the headers.
            java.util.Iterator<String> names = resumeHeaders.keys();
            while (names.hasNext()) {
                String name = names.next();
                builder.header(name, resumeHeaders.optString(name));
            }
        }

        Call call = HttpClients.withDeadline(HTTP_CLIENT, params.deadlineNanos)
            .newCall(builder.build());
        // Registered so an orchestrated phase timeout can cancel it
        // (CODE_AUDIT 2.12); cleared once the transfer is over.
        params.attachCall(call);
        try (Response response = call.execute()) {
            HttpClients.rejectProtocolDowngrade(url, response);
            ResponseBody body = response.body();
            long contentLength = body == null ? -1 : body.contentLength();
            // The Content-Encoding header is visible only when the server
            // encoded the body itself (OkHttp strips it when it transparently
            // decompresses its own gzip).
            JSONObject decision = resumeDecision(ResumePlan.classifyResponse(
                response.code(),
                resumeOffset,
                response.header("Content-Range"),
                response.header("Content-Encoding"),
                contentLength,
                sidecarText,
                url,
                writePath.isFile() ? writePath.length() : 0));
            String action = decision.optString("action");
            if ("complete".equals(action)) {
                // The partial is actually the complete file.
                long total = decision.optLong("total");
                postProgress(total, total);
                return true;
            }
            if ("restart".equals(action)) {
                return false;
            }
            if (!"write".equals(action)) {
                // The partial and its sidecar stay: that is the resume state.
                throw new IOException("Server error: " + response.code() + " " + response.message());
            }
            if (body == null) {
                throw new IOException("Empty response body for " + url);
            }

            boolean append = decision.optBoolean("append");
            long baseOffset = decision.optLong("base");
            long totalAll = decision.optLong("total");
            boolean encodedBody = decision.optBoolean("encoded");
            if (totalAll > ArchiveLimits.MAX_ARCHIVE_BYTES) {
                throw new IOException("archive too large: " + totalAll + " bytes");
            }
            ArchiveLimits.ensureFreeSpace(
                writePath, totalAll > 0 ? totalAll - baseOffset : 0);
            if (!append) {
                // Destroy the old bytes before the sidecar can vouch for
                // them with the new validators (a crash between the two
                // writes must never leave a sidecar describing stale bytes).
                discardPartial(writePath);
            }
            String etag = response.header("ETag");
            String lastModified = response.header("Last-Modified");
            if (decision.optBoolean("persistSidecar")) {
                // Persist before streaming so a mid-stream crash can resume.
                writeSidecarText(sidecar,
                    ResumePlan.sidecar(url, etag, lastModified, sidecarText, totalAll));
            } else {
                // No resume across an encoded transfer.
                deleteResumeSidecar(writePath);
            }

            long bytesRead;
            long received = 0;
            int currentPercentage = 0;
            long lastPostedBytes = baseOffset;
            // Unknown length: the response-time check could only reserve the
            // margin, so the disk is probed before any write that would run
            // past the bytes reserved so far (the shared probe plan,
            // ArchiveLimits.planFreeSpaceProbe) — no write can ever eat into
            // the margin. A throw keeps the partial for a later attempt.
            long freeSpaceReservedUntil = 0;

            // The archive digest is computed as the bytes reach the file, so
            // the install does not re-read the whole archive afterwards.
            MessageDigest digest = UpdateFileUtils.newSha256();
            if (append) {
                UpdateFileUtils.updateDigest(digest, writePath);
            }
            try (
                BufferedSource source = body.source();
                BufferedSink sink = Okio.buffer(Okio.sink(new DigestOutputStream(
                    new FileOutputStream(writePath, append), digest)))
            ) {
                while ((bytesRead = source.read(sink.buffer(), UpdateFileUtils.BUFFER_SIZE)) != -1) {
                    // A known length was reserved up front: no per-chunk plan
                    // (and no JNI round trip on this hot loop).
                    long[] probe = totalAll > 0 ? null : ArchiveLimits.planFreeSpaceProbe(
                        totalAll, received, bytesRead, freeSpaceReservedUntil);
                    received += bytesRead;
                    if (probe != null) {
                        freeSpaceReservedUntil = probe[1];
                    }
                    if (probe != null && probe[0] > 0) {
                        try {
                            ArchiveLimits.ensureFreeSpace(writePath, probe[0]);
                        } catch (IOException e) {
                            // The chunk is still only buffered; closing the
                            // sink would flush it onto the disk that just
                            // failed the probe.
                            sink.buffer().clear();
                            throw e;
                        }
                    }
                    // Write whole segments only: a 64KB read no longer costs
                    // a write() syscall per partially filled segment.
                    sink.emitCompleteSegments();

                    long overall = baseOffset + received;
                    if (overall > ArchiveLimits.MAX_ARCHIVE_BYTES) {
                        // Unknown/chunked length backstop.
                        throw new IOException(
                            "archive too large: exceeded " + ArchiveLimits.MAX_ARCHIVE_BYTES);
                    }
                    if (totalAll > 0) {
                        int percentage = (int) (overall * 100.0 / totalAll + 0.5);
                        if (percentage > currentPercentage) {
                            currentPercentage = percentage;
                            lastPostedBytes = overall;
                            postProgress(overall, totalAll);
                        }
                    } else if (overall - lastPostedBytes >= PROGRESS_BYTES_THRESHOLD) {
                        lastPostedBytes = overall;
                        postProgress(overall, totalAll);
                    }
                }
                sink.flush();
            }

            if (contentLength >= 0 && received != contentLength) {
                throw new IOException("Unexpected eof while reading downloaded package");
            }
            if (totalAll > 0 && writePath.length() != totalAll) {
                throw new IOException("Download incomplete: expected " + totalAll
                    + " bytes, got " + writePath.length());
            }
            if (!encodedBody) {
                // Refresh with the final size: a length unknown up front
                // (chunked) left the sidecar without a total, so a process
                // dying between download end and unzip would otherwise
                // download the whole archive again.
                writeSidecarText(sidecar, ResumePlan.sidecar(
                    url, etag, lastModified, sidecarText, writePath.length()));
            }
            streamedArchiveSha256 = UpdateFileUtils.toHex(digest.digest());
            // Final progress event, skipped when the loop already posted this
            // exact value (known length reaching 100% posts it in-loop).
            if (baseOffset + received != lastPostedBytes) {
                postProgress(baseOffset + received, totalAll);
            }
        } finally {
            params.attachCall(null);
        }
        return true;
    }

    private void copyBundledAssetToFile(String assetName, File destination) throws IOException {
        try (InputStream in = context.getAssets().open(assetName)) {
            UpdateFileUtils.copyInputStreamToFile(in, destination);
        }
    }

    private PatchArchiveContents extractPatchArchive(File archiveFile, File unzipDirectory)
        throws IOException {
        UpdateFileUtils.removeDirectory(unzipDirectory);
        UpdateFileUtils.ensureDirectory(unzipDirectory);

        ArrayList<String> entryNames = new ArrayList<String>();
        byte[] manifestJson = new byte[0];
        try (SafeZipFile zipFile = new SafeZipFile(archiveFile)) {
            ensureArchiveWithinLimits(archiveFile, zipFile, unzipDirectory);
            Enumeration<? extends ZipEntry> entries = zipFile.entries();
            while (entries.hasMoreElements()) {
                ZipEntry entry = entries.nextElement();
                String name = entry.getName();
                entryNames.add(name);

                if (name.equals("__diff.json")) {
                    if (entry.getSize() > ArchiveLimits.MAX_MANIFEST_BYTES) {
                        throw new IOException("delta manifest too large: " + entry.getSize());
                    }
                    manifestJson = UpdateFileUtils.readBytes(
                        zipFile.getInputStream(entry), ArchiveLimits.MAX_MANIFEST_BYTES);
                    continue;
                }

                zipFile.unzipToPath(entry, unzipDirectory);
            }
        }
        return new PatchArchiveContents(entryNames, manifestJson);
    }

    /**
     * Shared first half of the two patch tasks: download the archive and
     * unpack it into the staging directory. The native applyArchiveDelta
     * validates what it declared.
     */
    private PatchArchiveContents stagePatchArchive() throws IOException {
        downloadFile();
        artifactSha256 = archiveSha256();
        return extractPatchArchive(params.targetFile, stagingDirectory());
    }

    private void doFullPatch() throws IOException {
        downloadFile();

        File work = stagingDirectory();
        UpdateFileUtils.removeDirectory(work);
        UpdateFileUtils.ensureDirectory(work);
        artifactSha256 = archiveSha256();

        // The bundle's digest (for the install record) is taken from the
        // bytes as they are extracted, instead of re-reading the bundle right
        // after. Any entry resolving to the bundle path counts; the last write
        // wins on disk and in the digest alike.
        File bundleTarget = InstallRecord.bundleFile(work).getCanonicalFile();
        stagedBundleSha256 = null;
        try (SafeZipFile zipFile = new SafeZipFile(params.targetFile)) {
            ensureArchiveWithinLimits(params.targetFile, zipFile, work);
            Enumeration<? extends ZipEntry> entries = zipFile.entries();
            while (entries.hasMoreElements()) {
                ZipEntry entry = entries.nextElement();
                if (!entry.isDirectory()
                    && new File(work, entry.getName()).getCanonicalFile().equals(bundleTarget)) {
                    MessageDigest digest = UpdateFileUtils.newSha256();
                    zipFile.unzipToPath(entry, work, digest);
                    stagedBundleSha256 = UpdateFileUtils.toHex(digest.digest());
                } else {
                    zipFile.unzipToPath(entry, work);
                }
            }
        }

        deleteConsumedArchive();
    }

    private String archiveSha256() throws IOException {
        return streamedArchiveSha256 != null
            ? streamedArchiveSha256 : UpdateFileUtils.sha256Hex(params.targetFile);
    }

    /**
     * Last step of a successful patch task: the completion record (with the
     * final bundle's digest) goes into the staging directory, which is then
     * renamed over the version directory in one atomic step.
     */
    private void promoteStaging() throws IOException {
        File work = stagingDirectory();
        if (targetsRunningVersion()) {
            // The process switched to this very version while the task ran
            // (a restartApp racing the download): never rename over the
            // live directory. Its verified install stands; staging goes.
            ensureNotReinstallingRunningVersion();
            UpdateFileUtils.removeDirectory(work);
            return;
        }
        InstallRecord.seal(work, params.hash, artifactSha256, stagedBundleSha256);
        if (params.unzipDirectory.exists()) {
            UpdateFileUtils.removeDirectory(params.unzipDirectory);
        }
        InstallRecord.promote(work, params.unzipDirectory);
    }

    /**
     * Resource caps before extraction (cpp/patch_core/archive_limits.h): the
     * archive itself, the central directory's declared contents, and the
     * free space the expansion needs. Failing here is a PATCH_FAILED (the
     * bytes arrived; they cannot be applied).
     */
    private static void ensureArchiveWithinLimits(
        File archiveFile, SafeZipFile zipFile, File unzipDirectory
    ) throws IOException {
        long archiveBytes = archiveFile.length();
        if (archiveBytes > ArchiveLimits.MAX_ARCHIVE_BYTES) {
            throw new IOException("archive too large: " + archiveBytes + " bytes");
        }
        ArchiveLimits.ensureFreeSpace(unzipDirectory, zipFile.inspect(archiveBytes));
    }

    // The archive and its resume sidecar live and die together: once the
    // archive is consumed (or classified as poisoned) the sidecar must not
    // survive to vouch for a file that no longer exists or cannot be trusted.
    private void deleteConsumedArchive() {
        if (params.targetFile.exists()) {
            params.targetFile.delete();
        }
        deleteResumeSidecar(params.targetFile);
    }

    private void doPatchFromApk() throws IOException {
        PatchArchiveContents contents = stagePatchArchive();
        File work = stagingDirectory();

        File originBundleFile = new File(work, ".origin.bundle");
        copyBundledAssetToFile("index.android.bundle", originBundleFile);
        CopyGroupResult[] copies;
        try {
            // The APK's resources are zip entries, not files: the core
            // rebuilds the bundle and hands the manifest copies back.
            copies = applyArchiveDelta(
                DownloadTaskParams.TASK_TYPE_PATCH_FROM_APK,
                contents.entryNames,
                contents.manifestJson,
                work.getAbsolutePath(),
                work.getAbsolutePath(),
                originBundleFile.getAbsolutePath(),
                new File(work, BUNDLE_DELTA_ENTRY).getAbsolutePath(),
                InstallRecord.bundleFile(work).getAbsolutePath(),
                true
            );
        } finally {
            originBundleFile.delete();
        }

        bundledResourceCopier.copyFromResource(work, copies);
        deleteConsumedArchive();
    }

    private void doPatchFromPpk() throws IOException {
        PatchArchiveContents contents = stagePatchArchive();
        File work = stagingDirectory();
        applyArchiveDelta(
            DownloadTaskParams.TASK_TYPE_PATCH_FROM_PPK,
            contents.entryNames,
            contents.manifestJson,
            params.originDirectory.getAbsolutePath(),
            work.getAbsolutePath(),
            InstallRecord.bundleFile(params.originDirectory).getAbsolutePath(),
            new File(work, BUNDLE_DELTA_ENTRY).getAbsolutePath(),
            InstallRecord.bundleFile(work).getAbsolutePath(),
            false
        );
        deleteConsumedArchive();
    }

    // Dot-named, so the selection under the versions root never picks it.
    static final String TRASH_DIR_NAME = ".trash";

    private void doCleanUp() {
        final File trash = new File(params.unzipDirectory, TRASH_DIR_NAME);
        // Phase 1, under the version-files lock: only renames doomed entries
        // into the trash, so activation is never blocked behind a recursive
        // delete of several version directories.
        UpdateContext.getInstance(context).runCleanupWithLatestState(keepNames ->
            cleanupOldEntries(
                params.unzipDirectory.getAbsolutePath(),
                keepNames,
                params.maxAgeDays,
                trash.getAbsolutePath()
            ));
        // Phase 2, lock released: nothing in the trash is reachable as a
        // version any more. Also purges leftovers of an interrupted run.
        // Best effort: phase 1 already succeeded, and a leftover the native
        // delete cannot remove must not fail every later cleanup task.
        if (trash.isDirectory()) {
            try {
                cleanupOldEntries(trash.getAbsolutePath(), new String[0], 0, null);
            } catch (RuntimeException e) {
                Log.w(Texts.LOG_TAG, "Failed to purge cleanup trash", e);
            }
        }
    }

    private void cleanUpAfterFailure(int taskType) {
        switch (taskType) {
            case DownloadTaskParams.TASK_TYPE_PATCH_FULL:
            case DownloadTaskParams.TASK_TYPE_PATCH_FROM_APK:
            case DownloadTaskParams.TASK_TYPE_PATCH_FROM_PPK:
                // Only the staging directory is ours to drop: the final
                // version directory is never touched by a failed install.
                try {
                    UpdateFileUtils.removeDirectory(stagingDirectory());
                } catch (IOException ioException) {
                    Log.e(Texts.LOG_TAG, "Failed to clean staging directory", ioException);
                }
                if (downloadPhaseCompleted) {
                    // Fully received but failed to unzip/patch: the archive is
                    // poisoned, and resuming it would fail the same way on
                    // every future attempt. A download-phase failure keeps the
                    // partial + sidecar instead — that is the resume state.
                    deleteConsumedArchive();
                }
                break;
            case DownloadTaskParams.TASK_TYPE_PLAIN_DOWNLOAD:
                deleteConsumedArchive();
                break;
            default:
                break;
        }
    }

    private boolean isPatchTask(int taskType) {
        return taskType == DownloadTaskParams.TASK_TYPE_PATCH_FULL
            || taskType == DownloadTaskParams.TASK_TYPE_PATCH_FROM_APK
            || taskType == DownloadTaskParams.TASK_TYPE_PATCH_FROM_PPK;
    }

    private boolean hasCompletedDeltaDirectory() {
        return params.unzipDirectory != null
            && params.hash != null
            && InstallRecord.isInstalled(params.unzipDirectory, params.hash);
    }

    // True when this task targets the version the process is running from.
    private boolean targetsRunningVersion() {
        String running = UpdateContext.runningVersion();
        return running != null && params.hash != null && running.equals(params.hash);
    }

    /**
     * The running version's directory is never replaced in place
     * (CODE_AUDIT 2.10): images and fonts are read from it on demand, and an
     * install from before completion records existed has no marker, so a
     * re-download of the same hash would wipe the live directory. A running
     * version whose record verifies against the bundle on disk needs no
     * install and passes; anything else is refused as a file-operation
     * failure rather than overwritten.
     */
    private void ensureNotReinstallingRunningVersion() throws IOException {
        try {
            InstallRecord.verifyInstalled(params.unzipDirectory, params.hash, false);
        } catch (IOException e) {
            throw new FileOperationException("Running version " + params.hash
                + " cannot be reinstalled in place: " + e.getMessage());
        }
    }

    @Override
    public void run() {
        int taskType = params.type;
        final boolean runningVersion = isPatchTask(taskType) && targetsRunningVersion();
        final boolean alreadyCompleted = isPatchTask(taskType)
            && hasCompletedDeltaDirectory();
        try {
            if (params.isCancelled()) {
                throw new IOException("download task cancelled before it started");
            }
            if (runningVersion) {
                ensureNotReinstallingRunningVersion();
                Log.i(Texts.LOG_TAG, "download task: version " + params.hash
                    + " is running in this process and already installed");
            } else if (alreadyCompleted) {
                Log.i(Texts.LOG_TAG,
                    "download task: version " + params.hash + " already completed");
            } else {
                switch (taskType) {
                    case DownloadTaskParams.TASK_TYPE_PATCH_FULL:
                        doFullPatch();
                        promoteStaging();
                        break;
                    case DownloadTaskParams.TASK_TYPE_PATCH_FROM_APK:
                        doPatchFromApk();
                        promoteStaging();
                        break;
                    case DownloadTaskParams.TASK_TYPE_PATCH_FROM_PPK:
                        doPatchFromPpk();
                        promoteStaging();
                        break;
                    case DownloadTaskParams.TASK_TYPE_CLEANUP:
                        doCleanUp();
                        break;
                    case DownloadTaskParams.TASK_TYPE_PLAIN_DOWNLOAD:
                        downloadFile();
                        break;
                    default:
                        break;
                }
            }
        } catch (Throwable error) {
            Log.e(Texts.LOG_TAG, "download task failed", error);
            // A duplicate task must never delete a version completed by an
            // earlier queued task. The marker + bundle pair is the ownership
            // handoff: once present, this failure did not create that install.
            if (!hasCompletedDeltaDirectory()) {
                cleanUpAfterFailure(taskType);
            }

            if (params.listener != null) {
                // A patch task that failed after its artifact was fully
                // downloaded (unzip / hdiff / resource copy, incl. copiesCrc
                // verification) is a patch failure, not a download failure —
                // the module maps the exception type to PATCH_FAILED.
                Throwable classified = error;
                if (downloadPhaseCompleted
                    && isPatchTask(taskType)
                    && !(error instanceof PatchFailedException)
                    && !(error instanceof FileOperationException)) {
                    classified = new PatchFailedException(
                        String.valueOf(error.getMessage()), error);
                }
                params.listener.onDownloadFailed(classified);
            }
            return;
        }

        if (taskType == DownloadTaskParams.TASK_TYPE_PLAIN_DOWNLOAD) {
            // A plain download's file is final at completion — a surviving
            // sidecar would make a later download of the same URL return
            // these bytes without ever asking the server again.
            deleteResumeSidecar(params.targetFile);
        }

        // The task itself succeeded. Run the completion callback outside the
        // try/catch above so an exception thrown by the callback (e.g. a
        // PackageInstaller failure during APK staging) is not mistaken for
        // a download failure that deletes the successfully downloaded file and
        // settles the promise a second time.
        if (params.listener != null) {
            try {
                params.listener.onDownloadCompleted(params);
            } catch (Throwable error) {
                Log.e(Texts.LOG_TAG, "download completion callback failed", error);
                params.listener.onDownloadFailed(error);
            }
        }
    }

    // The native half of a patch install (cpp/patch_core/archive_patch_core.h
    // ApplyArchivePatch): checks the archive's entries, parses and validates
    // manifestJson (__diff.json), rebuilds the bundle and, unless
    // hostCopiesResources, performs the copies, deletes and merge. Returns
    // the copies the caller still owes (empty unless hostCopiesResources).
    private static native CopyGroupResult[] applyArchiveDelta(
        int patchType,
        String[] entryNames,
        byte[] manifestJson,
        String sourceRoot,
        String targetRoot,
        String originBundlePath,
        String bundlePatchPath,
        String bundleOutputPath,
        boolean hostCopiesResources
    );

    // trashDir non-empty: move the selected entries there instead of
    // deleting them (see doCleanUp).
    private static native void cleanupOldEntries(
        String rootDir,
        String[] keepNames,
        int maxAgeDays,
        String trashDir
    );
}