@bravemobile/react-native-code-push 13.0.0 → 13.1.0-beta.0

package/cli/utils/binaryPatch.test.ts

@@ -0,0 +1,234 @@
+import { spawnSync } from "child_process";
+import crypto from "crypto";
+import fs from "fs";
+import os from "os";
+import path from "path";
+import { afterAll, beforeAll, describe, expect, it } from "@jest/globals";
+import { applyPatch, generatePatch, resolveBinaryPatchTool } from "./binaryPatch.js";
+
+/**
+ * Locks the binary patch codec contract: which bytes a patch restores, and which
+ * kinds of broken input the appliers do and do not catch.
+ *
+ * Everything here runs against real binaries and real bytes - hdiffz/hpatchz and a
+ * host build of the native applier - because the whole point is to prove that the
+ * committed patch format really is what every applier understands.
+ */
+
+/** Building the applier from source takes a while on a cold machine. */
+const BUILD_APPLIER_TIMEOUT_MS = 5 * 60 * 1000;
+
+function findRepoRoot(): string {
+    let dir = process.cwd();
+    for (;;) {
+        if (fs.existsSync(path.join(dir, "scripts", "binary-patch", "build-hdiffpatch.sh"))) {
+            return dir;
+        }
+        const parent = path.dirname(dir);
+        if (parent === dir) {
+            throw new Error(`cannot locate the repository root from ${process.cwd()}`);
+        }
+        dir = parent;
+    }
+}
+
+const repoRoot = findRepoRoot();
+const fixtureDir = path.join(repoRoot, "cli", "fixtures", "binary-patch");
+const baseFixture = path.join(fixtureDir, "base.bundle");
+const targetFixture = path.join(fixtureDir, "target.bundle");
+const patchFixture = path.join(fixtureDir, "update.patch");
+/**
+ * One shared tree builds the applier for both platforms: iOS pulls it in through the
+ * podspec at the repository root, Android through externalNativeBuild.
+ */
+const applierDir = path.join(repoRoot, "cpp", "binarypatch");
+
+let workDir: string;
+
+function sha256(filePath: string): string {
+    return crypto.createHash("sha256").update(fs.readFileSync(filePath)).digest("hex");
+}
+
+function workPath(name: string): string {
+    return path.join(workDir, name);
+}
+
+/** Writes a copy of `sourcePath` with `mutate` applied to its bytes. */
+function writeMutatedCopy(sourcePath: string, name: string, mutate: (bytes: Buffer) => Buffer): string {
+    const destination = workPath(name);
+    fs.writeFileSync(destination, mutate(fs.readFileSync(sourcePath)));
+    return destination;
+}
+
+function cCompiler(): string {
+    return process.env.CC || "cc";
+}
+
+function hasCCompiler(): boolean {
+    return spawnSync(cCompiler(), ["--version"], { stdio: "ignore" }).status === 0;
+}
+
+beforeAll(() => {
+    // hdiffz/hpatchz are provisioned for the whole run by the jest global setup.
+    workDir = fs.mkdtempSync(path.join(os.tmpdir(), "codepush-binary-patch-"));
+});
+
+afterAll(() => {
+    fs.rmSync(workDir, { recursive: true, force: true });
+});
+
+describe("generatePatch/applyPatch", () => {
+    it("restores the target bytes from a freshly generated patch", () => {
+        const generatedPatch = workPath("generated.patch");
+        const restored = workPath("restored-from-generated.bundle");
+
+        generatePatch(baseFixture, targetFixture, generatedPatch);
+        applyPatch(baseFixture, generatedPatch, restored);
+
+        expect(fs.statSync(generatedPatch).size).toBeGreaterThan(0);
+        expect(sha256(restored)).toBe(sha256(targetFixture));
+    });
+
+    it("restores the target bytes from the committed patch fixture", () => {
+        const restored = workPath("restored-from-fixture.bundle");
+
+        applyPatch(baseFixture, patchFixture, restored);
+
+        expect(sha256(restored)).toBe(sha256(targetFixture));
+    });
+
+    it("reports a missing patch tool with a message that says how to get it", () => {
+        const previous = process.env.HDIFFPATCH_TOOLS_DIR;
+        process.env.HDIFFPATCH_TOOLS_DIR = workPath("no-such-dir");
+        try {
+            expect(() => resolveBinaryPatchTool("hdiffz")).toThrow(/build-hdiffpatch\.sh/);
+        } finally {
+            if (previous === undefined) {
+                delete process.env.HDIFFPATCH_TOOLS_DIR;
+            } else {
+                process.env.HDIFFPATCH_TOOLS_DIR = previous;
+            }
+        }
+    });
+});
+
+describe("applyPatch failure modes", () => {
+    it("fails on a patch with a corrupted header", () => {
+        const corrupted = writeMutatedCopy(patchFixture, "corrupt-header.patch", (bytes) => {
+            // Byte 0 is inside the patch type string, which the header parser reads first.
+            bytes[0] ^= 0xff;
+            return bytes;
+        });
+
+        expect(() => applyPatch(baseFixture, corrupted, workPath("out-corrupt-header.bundle"))).toThrow(/hpatchz/);
+    });
+
+    it("fails on a truncated patch", () => {
+        const truncated = writeMutatedCopy(patchFixture, "truncated.patch", (bytes) =>
+            bytes.subarray(0, Math.floor(bytes.length / 2)),
+        );
+
+        expect(() => applyPatch(baseFixture, truncated, workPath("out-truncated.bundle"))).toThrow(/hpatchz/);
+    });
+});
+
+/**
+ * A compressed diff carries no checksum of the base data, and the zstd streams
+ * inside it are written without content checksums, so an applier cannot tell every
+ * kind of wrong input apart from a legitimate one. These tests pin that down: the
+ * apply step may report success, but it never produces the target bytes. Callers
+ * must therefore verify the base and target hashes themselves rather than treating
+ * a successful apply as proof of a correct result.
+ */
+describe("errors the codec cannot detect", () => {
+    it("never produces the target bytes when a byte inside the compressed diff data is corrupted", () => {
+        const corrupted = writeMutatedCopy(patchFixture, "corrupt-body.patch", (bytes) => {
+            bytes[Math.floor(bytes.length / 2)] ^= 0xff;
+            return bytes;
+        });
+        const restored = workPath("out-corrupt-body.bundle");
+
+        // Whether the corruption is reported depends on where it lands: a flipped bit
+        // inside a zstd literals block decodes to different bytes without any error,
+        // while one that invalidates a block header does fail. Either way the result
+        // is not the target, which is all the caller can rely on.
+        let restoredHash: string | null = null;
+        try {
+            applyPatch(baseFixture, corrupted, restored);
+            restoredHash = sha256(restored);
+        } catch {
+            restoredHash = null;
+        }
+
+        expect(restoredHash).not.toBe(sha256(targetFixture));
+    });
+
+    it("applies but produces wrong bytes when the base has the expected size and different content", () => {
+        const wrongBase = writeMutatedCopy(baseFixture, "wrong-base.bundle", (bytes) => {
+            bytes[1000] ^= 0xff;
+            return bytes;
+        });
+        const restored = workPath("out-wrong-base.bundle");
+
+        applyPatch(wrongBase, patchFixture, restored);
+
+        expect(fs.statSync(wrongBase).size).toBe(fs.statSync(baseFixture).size);
+        expect(sha256(restored)).not.toBe(sha256(targetFixture));
+    });
+});
+
+/**
+ * The native appliers on Android and iOS are built from the vendored sources, so a
+ * host build of the same sources is what proves they agree with hdiffz/hpatchz.
+ */
+const describeNativeApplier = hasCCompiler() ? describe : describe.skip;
+
+describeNativeApplier("host build of the native applier", () => {
+    let hostApplier: string;
+
+    const runHostApplier = (oldPath: string, patch: string, outPath: string): number | null => {
+        const result = spawnSync(hostApplier, [oldPath, patch, outPath], { encoding: "utf8" });
+        return result.status;
+    };
+
+    beforeAll(() => {
+        hostApplier = workPath("apply_patch_host");
+        const script = path.join(applierDir, "host", "build.sh");
+        const result = spawnSync(script, [hostApplier], { encoding: "utf8", timeout: BUILD_APPLIER_TIMEOUT_MS });
+        if (result.status !== 0) {
+            throw new Error(`${script} failed:\n${result.stdout ?? ""}${result.stderr ?? ""}`);
+        }
+    }, BUILD_APPLIER_TIMEOUT_MS);
+
+    it("restores the same target bytes as the CLI applier", () => {
+        const restored = workPath("out-host.bundle");
+
+        expect(runHostApplier(baseFixture, patchFixture, restored)).toBe(0);
+        expect(sha256(restored)).toBe(sha256(targetFixture));
+    });
+
+    it("reports a corrupted patch header as exit code 3", () => {
+        const corrupted = writeMutatedCopy(patchFixture, "host-corrupt-header.patch", (bytes) => {
+            bytes[0] ^= 0xff;
+            return bytes;
+        });
+
+        expect(runHostApplier(baseFixture, corrupted, workPath("out-host-corrupt-header.bundle"))).toBe(3);
+    });
+
+    it("reports a base of unexpected size as exit code 5", () => {
+        const shortBase = writeMutatedCopy(baseFixture, "host-short-base.bundle", (bytes) =>
+            bytes.subarray(0, bytes.length - 16),
+        );
+
+        expect(runHostApplier(shortBase, patchFixture, workPath("out-host-short-base.bundle"))).toBe(5);
+    });
+
+    it("reports a truncated patch as exit code 6", () => {
+        const truncated = writeMutatedCopy(patchFixture, "host-truncated.patch", (bytes) =>
+            bytes.subarray(0, Math.floor(bytes.length / 2)),
+        );
+
+        expect(runHostApplier(baseFixture, truncated, workPath("out-host-truncated.bundle"))).toBe(6);
+    });
+});

package/cli/utils/binaryPatch.ts

@@ -0,0 +1,103 @@
+/**
+ * Binary patch codec for CodePush updates.
+ *
+ * A binary patch update carries only the difference between the bundle that is
+ * already inside the app binary and the bundle a release wants to run, instead of
+ * the whole bundle. Patches are produced by HDiffPatch's `hdiffz` and applied on
+ * device by the native appliers; `hpatchz` is the reference applier used here so a
+ * patch can be verified right after it is produced.
+ *
+ * The tool options below are part of the format contract, not tuning knobs:
+ *   -m-6            the base bundle is held in memory while patching, which is what
+ *                   the native appliers do, and match score 6 suits bytecode
+ *   -c-zstd-21-24   zstd is the only decompressor the native appliers link
+ *   -f              overwrite the output file if it already exists
+ * Changing them produces patches the native appliers cannot read.
+ *
+ * A patch contains no checksum of the base data, and its zstd streams carry no
+ * content checksums, so a successful apply is not proof of a correct result: a base
+ * of the right size but the wrong content, or a corrupted patch body, can both apply
+ * "successfully" and yield wrong bytes. Callers must verify the base and target
+ * hashes themselves.
+ */
+
+import { spawnSync } from "child_process";
+import fs from "fs";
+import path from "path";
+
+/**
+ * Identifies the patch format so a client can refuse a patch it cannot apply.
+ * Bump the format version whenever the tool options above change.
+ */
+export const BINARY_PATCH_ALGORITHM = 'hdiffpatch-m-zstd';
+export const BINARY_PATCH_FORMAT_VERSION = 1;
+
+export type BinaryPatchTool = 'hdiffz' | 'hpatchz';
+
+const HDIFFZ_OPTIONS = ['-f', '-m-6', '-c-zstd-21-24'];
+const HPATCHZ_OPTIONS = ['-f', '-m'];
+
+const TOOLS_DIR_ENV_NAME = 'HDIFFPATCH_TOOLS_DIR';
+const TOOLS_DIR_NAME = '.hdiffpatch-tools';
+const BUILD_SCRIPT_PATH = 'scripts/binary-patch/build-hdiffpatch.sh';
+
+/**
+ * Finds the hdiffz/hpatchz executable, looking at `HDIFFPATCH_TOOLS_DIR` first and
+ * then at a `.hdiffpatch-tools` directory in the working directory or any directory
+ * above it. The tools are built from source rather than installed as a package
+ * dependency, so the error explains how to get them.
+ */
+export function resolveBinaryPatchTool(tool: BinaryPatchTool): string {
+    const configuredDir = process.env[TOOLS_DIR_ENV_NAME];
+    if (configuredDir) {
+        const configured = path.join(configuredDir, tool);
+        if (fs.existsSync(configured)) {
+            return configured;
+        }
+        throw new Error(
+            `${TOOLS_DIR_ENV_NAME} is set to '${configuredDir}' but it does not contain '${tool}'. ` +
+                `Build the tools with '${BUILD_SCRIPT_PATH}'.`,
+        );
+    }
+
+    let directory = path.resolve(process.cwd());
+    for (;;) {
+        const candidate = path.join(directory, TOOLS_DIR_NAME, tool);
+        if (fs.existsSync(candidate)) {
+            return candidate;
+        }
+        const parent = path.dirname(directory);
+        if (parent === directory) {
+            break;
+        }
+        directory = parent;
+    }
+
+    throw new Error(
+        `'${tool}' not found in any '${TOOLS_DIR_NAME}' directory at or above '${process.cwd()}'. ` +
+            `Build it with '${BUILD_SCRIPT_PATH}', or set ${TOOLS_DIR_ENV_NAME} to a directory that contains it.`,
+    );
+}
+
+/** Writes the patch that turns the bundle at `basePath` into the one at `targetPath`. */
+export function generatePatch(basePath: string, targetPath: string, patchPath: string): void {
+    runTool('hdiffz', [...HDIFFZ_OPTIONS, basePath, targetPath, patchPath]);
+}
+
+/** Writes the bundle that `patchPath` produces from the bundle at `basePath`. */
+export function applyPatch(basePath: string, patchPath: string, outputPath: string): void {
+    runTool('hpatchz', [...HPATCHZ_OPTIONS, basePath, patchPath, outputPath]);
+}
+
+function runTool(tool: BinaryPatchTool, args: string[]): void {
+    const executable = resolveBinaryPatchTool(tool);
+    const result = spawnSync(executable, args, { encoding: 'utf8' });
+
+    if (result.error) {
+        throw new Error(`failed to run ${tool}: ${result.error.message}`);
+    }
+    if (result.status !== 0) {
+        const reason = result.status === null ? `signal ${result.signal}` : `exit code ${result.status}`;
+        throw new Error(`${tool} failed with ${reason}\n${result.stdout ?? ''}${result.stderr ?? ''}`);
+    }
+}

package/cpp/binarypatch/binarypatch_zstd_decompressor.c

@@ -0,0 +1,187 @@
+#include "binarypatch_zstd_decompressor.h"
+
+#include <stdlib.h>
+#include <string.h>
+
+#include "zstd.h"
+
+/*
+ * Largest window a decompression session will accept, pinned to the window that the
+ * `-c-zstd-21-24` generation options use: no patch this project produces declares a
+ * window above 2^24. Keeping the bound at the generation limit means a corrupted
+ * frame header that asks for a wider window is rejected before anything is
+ * allocated, instead of being answered with an allocation that large - and applying
+ * a patch keeps several decompression sessions open at once, so the bound applies
+ * several times over. Changing the generation options is a patch format version
+ * change, and this bound moves with them.
+ */
+#define BINARYPATCH_ZSTD_WINDOW_LOG_MAX 24
+
+/*
+ * One decompression session. The input and output buffers are allocated in the
+ * same block as the struct (`buffers` is their start) to keep the number of
+ * allocations per patch session down.
+ */
+typedef struct {
+    const hpatch_TStreamInput* codeStream;
+    hpatch_StreamPos_t         codeReadPos;
+    hpatch_StreamPos_t         codeEnd;
+
+    ZSTD_DStream*              dstream;
+    ZSTD_inBuffer              in;
+    size_t                     inCapacity;
+    ZSTD_outBuffer             out;
+    size_t                     outReadPos; /* bytes of `out` already handed to the caller */
+
+    hpatch_dec_error_t         decError;
+    unsigned char              buffers[1]; /* [inCapacity bytes][out.size bytes] */
+} binarypatch_zstd_session;
+
+static hpatch_BOOL _zstd_fail(binarypatch_zstd_session* self) {
+    if (self->decError == hpatch_dec_ok) {
+        self->decError = hpatch_dec_error;
+    }
+    return hpatch_FALSE;
+}
+
+static hpatch_BOOL _zstd_is_can_open(const char* compressType) {
+    return (0 == strcmp(compressType, BINARYPATCH_ZSTD_COMPRESS_TYPE)) ? hpatch_TRUE : hpatch_FALSE;
+}
+
+static hpatch_decompressHandle _zstd_open(struct hpatch_TDecompress* decompressPlugin,
+                                          hpatch_StreamPos_t dataSize,
+                                          const struct hpatch_TStreamInput* codeStream,
+                                          hpatch_StreamPos_t code_begin,
+                                          hpatch_StreamPos_t code_end) {
+    const size_t inCapacity = ZSTD_DStreamInSize();
+    const size_t outCapacity = ZSTD_DStreamOutSize();
+    binarypatch_zstd_session* self;
+
+    /* The uncompressed size is tracked by the caller's patch stream, not here. */
+    (void)dataSize;
+
+    self = (binarypatch_zstd_session*)malloc(sizeof(binarypatch_zstd_session) + inCapacity + outCapacity);
+    if (!self) {
+        _hpatch_update_decError(decompressPlugin, hpatch_dec_mem_error);
+        return 0;
+    }
+    memset(self, 0, sizeof(binarypatch_zstd_session));
+    self->codeStream = codeStream;
+    self->codeReadPos = code_begin;
+    self->codeEnd = code_end;
+    self->in.src = self->buffers;
+    self->in.size = 0;
+    self->in.pos = 0; /* pos == size: the input buffer starts empty and is refilled on demand */
+    self->inCapacity = inCapacity;
+    self->out.dst = self->buffers + inCapacity;
+    self->out.size = outCapacity;
+    self->out.pos = 0;
+    self->outReadPos = 0;
+
+    self->dstream = ZSTD_createDStream();
+    if (!self->dstream) {
+        free(self);
+        _hpatch_update_decError(decompressPlugin, hpatch_dec_open_error);
+        return 0;
+    }
+    /*
+     * The window bound is applied here rather than left at zstd's default, and a
+     * session that cannot take it is refused: without the bound a corrupted frame
+     * header could ask for a much larger window than any patch legitimately needs.
+     */
+    if (ZSTD_isError(ZSTD_initDStream(self->dstream)) ||
+        ZSTD_isError(ZSTD_DCtx_setParameter(self->dstream, ZSTD_d_windowLogMax,
+                                            BINARYPATCH_ZSTD_WINDOW_LOG_MAX))) {
+        ZSTD_freeDStream(self->dstream);
+        free(self);
+        _hpatch_update_decError(decompressPlugin, hpatch_dec_open_error);
+        return 0;
+    }
+    return self;
+}
+
+static hpatch_BOOL _zstd_close(struct hpatch_TDecompress* decompressPlugin,
+                               hpatch_decompressHandle decompressHandle) {
+    binarypatch_zstd_session* self = (binarypatch_zstd_session*)decompressHandle;
+    hpatch_BOOL result = hpatch_TRUE;
+    if (!self) {
+        return hpatch_TRUE;
+    }
+    /* Report the session's failure through the plugin so the caller can read it. */
+    if (self->decError != hpatch_dec_ok) {
+        _hpatch_update_decError(decompressPlugin, self->decError);
+    }
+    if (0 != ZSTD_freeDStream(self->dstream)) {
+        result = hpatch_FALSE;
+        _hpatch_update_decError(decompressPlugin, hpatch_dec_close_error);
+    }
+    free(self);
+    return result;
+}
+
+/*
+ * Must fill the whole `[out_part_data, out_part_data_end)` range; anything less is
+ * an error by the `hpatch_TDecompress` contract.
+ */
+static hpatch_BOOL _zstd_decompress_part(hpatch_decompressHandle decompressHandle,
+                                         unsigned char* out_part_data,
+                                         unsigned char* out_part_data_end) {
+    binarypatch_zstd_session* self = (binarypatch_zstd_session*)decompressHandle;
+
+    while (out_part_data < out_part_data_end) {
+        size_t ready = self->out.pos - self->outReadPos;
+        size_t ret;
+
+        if (ready > 0) {
+            const size_t wanted = (size_t)(out_part_data_end - out_part_data);
+            if (ready > wanted) {
+                ready = wanted;
+            }
+            memcpy(out_part_data, (const unsigned char*)self->out.dst + self->outReadPos, ready);
+            out_part_data += ready;
+            self->outReadPos += ready;
+            continue;
+        }
+
+        if (self->in.pos == self->in.size) {
+            const hpatch_StreamPos_t remaining = self->codeEnd - self->codeReadPos;
+            unsigned char* inBuf = (unsigned char*)self->in.src;
+            size_t toRead = self->inCapacity;
+            if (remaining < (hpatch_StreamPos_t)toRead) {
+                toRead = (size_t)remaining;
+            }
+            self->in.pos = 0;
+            self->in.size = toRead;
+            if (toRead > 0) {
+                if (!self->codeStream->read(self->codeStream, self->codeReadPos, inBuf, inBuf + toRead)) {
+                    return _zstd_fail(self);
+                }
+                self->codeReadPos += toRead;
+            }
+        }
+
+        self->out.pos = 0;
+        self->outReadPos = 0;
+        ret = ZSTD_decompressStream(self->dstream, &self->out, &self->in);
+        if (ZSTD_isError(ret)) {
+            return _zstd_fail(self);
+        }
+        /*
+         * No progress with no input left means the compressed stream ended before
+         * the patch asked for its last byte - a truncated or corrupt patch.
+         */
+        if (self->out.pos == 0) {
+            return _zstd_fail(self);
+        }
+    }
+    return hpatch_TRUE;
+}
+
+void binarypatch_zstd_decompressor_init(hpatch_TDecompress* out_decompressor) {
+    memset(out_decompressor, 0, sizeof(hpatch_TDecompress));
+    out_decompressor->is_can_open = _zstd_is_can_open;
+    out_decompressor->open = _zstd_open;
+    out_decompressor->close = _zstd_close;
+    out_decompressor->decompress_part = _zstd_decompress_part;
+    /* reset_code stays NULL: it is only needed for vcdiff style patches. */
+}

package/cpp/binarypatch/binarypatch_zstd_decompressor.h

@@ -0,0 +1,47 @@
+/*
+ * zstd decompressor for HDiffPatch.
+ *
+ * HDiffPatch's patch functions take the decompressor as a plugin, so every codec
+ * the appliers must understand has to be supplied through `hpatch_TDecompress`.
+ * CodePush patches are always produced with `hdiffz -f -m-6 -c-zstd-21-24`, so
+ * zstd is the only codec implemented here; upstream ships a demo header covering
+ * a dozen codecs, but pulling that in would drag along headers for codecs the
+ * appliers never see.
+ *
+ * `hpatch_TDecompress` carries a mutable `decError` field, so each patch session
+ * must own its instance. Callers therefore declare the struct themselves and
+ * initialize it through `binarypatch_zstd_decompressor_init()`.
+ *
+ * This file and the vendored sources next to it sit outside the platform
+ * directories because both platforms compile them: iOS through the podspec at the
+ * repository root, Android through externalNativeBuild. One shared copy is what
+ * keeps the two appliers from drifting apart.
+ */
+
+#ifndef BINARYPATCH_ZSTD_DECOMPRESSOR_H
+#define BINARYPATCH_ZSTD_DECOMPRESSOR_H
+
+#include "libHDiffPatch/HPatch/patch_types.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/*
+ * The `compressType` string that `hdiffz -c-zstd-...` writes into the patch
+ * header, and the only value this decompressor accepts.
+ */
+#define BINARYPATCH_ZSTD_COMPRESS_TYPE "zstd"
+
+/*
+ * Fills `out_decompressor` with the zstd plugin implementation. The struct is
+ * fully overwritten, so it needs no prior initialization, and it holds no state
+ * that must be released.
+ */
+void binarypatch_zstd_decompressor_init(hpatch_TDecompress* out_decompressor);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* BINARYPATCH_ZSTD_DECOMPRESSOR_H */

package/cpp/binarypatch/vendor/HDiffPatch/libHDiffPatch/HPatch/checksum_plugin.h

@@ -0,0 +1,52 @@
+//checksum_plugin.h
+//  checksum plugin type
+/*
+ The MIT License (MIT)
+ Copyright (c) 2018-2019 HouSisong
+ 
+ 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 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.
+ */
+#ifndef HPatch_checksum_plugin_h
+#define HPatch_checksum_plugin_h
+#include "patch_types.h"
+#ifdef __cplusplus
+extern "C" {
+#endif
+    
+    typedef void*  hpatch_checksumHandle;
+    typedef struct hpatch_TChecksum{
+        //return type tag; strlen(result)<=hpatch_kMaxPluginTypeLength; (Note:result lifetime)
+        const char*   (*checksumType)(void); //ascii cstring,cannot contain '&'
+        hpatch_size_t (*checksumByteSize)(void); //0<result<=hpatch_kStreamCacheSize
+        hpatch_checksumHandle (*open)(struct hpatch_TChecksum* plugin);
+        void                 (*close)(struct hpatch_TChecksum* plugin,hpatch_checksumHandle handle);
+        void                 (*begin)(hpatch_checksumHandle handle); //must support reset
+        void                (*append)(hpatch_checksumHandle handle,
+                                      const unsigned char* part_data,const unsigned char* part_data_end);
+        void                   (*end)(hpatch_checksumHandle handle,
+                                      unsigned char* checksum,unsigned char* checksum_end);
+    } hpatch_TChecksum;
+    
+#ifdef __cplusplus
+}
+#endif
+#endif