feat(ios): apply binary patch updates - #155

…lier

HDiffPatch takes the decompressor as a plugin. Upstream ships a demo header
implementing a dozen codecs, which would pull in headers for codecs the applier never
sees, so this is a standalone hpatch_TDecompress implementation for zstd - the only
codec CodePush patches are compressed with. The window it accepts is capped at the
2^24 the generation options use, so a corrupted frame header asking for a wider
window is rejected before anything is allocated.

apply_patch_host is the reference applier built from those sources for the development
machine. It loads the base bundle and the patch into memory and writes the restored
bundle sequentially, which is the memory contract the Android and iOS appliers follow,
and it maps each failure to its own exit code so a caller can tell a corrupt patch
from a mismatched base.

Adds the CLI side of the codec - generatePatch and applyPatch spawn hdiffz and hpatchz
with the fixed options that define the patch format - together with a test suite that
pins the format down against real bytes and real binaries.

The fixtures are committed and can be regenerated deterministically by
scripts/binary-patch/generate-fixtures.mjs, so the tests verify the patch bytes that
ship rather than bytes produced on the fly. hdiffz and hpatchz are built from upstream
sources by scripts/binary-patch/build-hdiffpatch.sh, which the suite runs on demand
when the tools are missing.

Two properties are pinned down because callers have to handle them: a patch carries no
checksum of the base data, and its zstd streams carry no content checksums. Applying a
patch to a different base of the same size, or applying a patch whose body is
corrupted, can therefore report success and still produce the wrong bytes. Verifying
the base and target hashes stays the caller's responsibility.

The applier sources ship in the npm package so both platforms can build them, minus
the host harness, which only exists to run this suite.

An absolute --output-path produced an absolute bundle directory, which the
'./' prefix turned into a path below the current working directory.

`bundle` and `release` accept --binary-bundle-path, the JS bundle of the
target binary. With it, `release` publishes two artifacts per platform: the
full bundle named after its packageHash, and `<packageHash>-patch.zip`, which
carries the target bundle only as a patch against the binary's bundle plus a
`codepush-binary-patch.json` manifest. Every other file is copied unchanged,
so applying the patch and dropping the two patch-only files reproduces the
full contents byte for byte - and therefore the same packageHash.

The Hermes compilation is aligned with the base bundle through
`-base-bytecode` when the app's own compiler advertises the flag, which is
what keeps the patch small. A compiler without the flag only warns; a
compilation that fails with it fails the release, since the base is then
wrong.

Both archive sizes and the saving are printed before anything is uploaded,
and the full bundle is uploaded before the patch. A failed upload of either
leaves the release history untouched. Carrying the patch URL in the release
history is deliberately not part of this change.

The release action read `options.bundleName`, but commander stores the
`-j, --js-bundle-name` flag as `options.jsBundleName`, so a custom JS bundle
name never reached `release()` and the platform default was always used.

Optionality is now expressed in the types instead of asserted away, so "not
given" cannot pass for a name again.

The suites that generate real patches each built the tools in their own
`beforeAll`, so a suite without that hook - the release flow suite - failed on
a machine with no `.hdiffpatch-tools` yet, and two workers could run the same
build at the same time.

A jest global setup builds them once before any worker starts, which also
removes the duplicated helper from the two suites that had one.

A patch is only worth publishing when it is smaller than the archive it
replaces, and the CLI runs unattended in CI, so what happens otherwise is
decided up front instead of being left to whoever reads the summary.

`skip`, the default, warns, records the skip in the summary and releases the
full bundle alone. `fail` stops the release before either artifact is
uploaded, so the release history stays untouched. Equal sizes count as
oversized: a patch that saves nothing still costs a client an extra download
and an apply step.

The Babel config of this repository has no JSX transform - an app bundling
the library transforms it with the React Native preset - so a test cannot
load src/CodePush.js. Compile that one file with TypeScript instead, which
turns the JSX of the decorator into React.createElement calls and leaves the
rest of the module to the same downlevelling Babel would have applied.

A release published with --binary-bundle-path uploads a patch archive whose
URL was logged and then dropped. Record it in the release history entry of
that release, and carry it from the fetched history through the update check
to the metadata the native module is handed when it downloads the update.

A release without a patch says nothing about one: the field is absent from
the history entry and from the update, so a release history written before
binary patches existed keeps behaving exactly as it did.

A release published with a binary patch offers two archives of the same
update: the full one, and a patch of the JS bundle against the bundle
inside the app binary. Download the patch when the release has one, apply
it to the binary's bundle and put the restored bundle where the archive
left a patch, which leaves contents identical to the full archive - and
therefore the folder hash check that follows unchanged.

Nothing about a patch is trusted. The manifest is checked before anything
is read, the paths it points at have to stay inside the archive, the base
bundle is hashed before the patch is applied and the restored bundle is
hashed afterwards, and the restored bytes only reach the update contents
once both hashes match. A patch carries no checksum of what it produces,
so those two hashes are the only thing standing between a corrupted patch
and a broken app.

Any failure along that path downloads the full archive instead, and does
so exactly once: the fallback download is not allowed to take the patch
path, so it has no patch failure of its own to fall back from and needs no
counter or stored state to say so. Each failure is logged with the reason
it fell back, which is what a rollout is judged from.

The applier itself is the shared C code the host build compiles too,
reached from CMake where it lives rather than copied in.

The android client now installs an update from its patch archive and falls
back to the full one, so say so where patch bundles are documented, and
record what that adds to a consumer's android build: the NDK and CMake,
which compile the applier.

The note about installing updates against the binary's bundle being
something android cannot do is no longer true, so it now explains why the
update check still does not carry the binary's hash.

Three ways an update could go wrong on the patch path, found by testing the
download and install steps together instead of apart:

An archive wraps its files in a single directory, and a manifest's paths are
relative to that directory, so the manifest was looked for one level above
where it is. Every patch update would have fallen back to the full archive.

A patch URL that answers with something other than an archive - an error page
served with a 200, say - took the branch that treats a download as a bare JS
bundle and moves it into the package folder under the update's hash, with no
patch applied and no hash ever checked, and then reported success so nothing
fell back. The patch path now refuses anything that is not an archive.

Applying a patch is the one path that holds a whole bundle in memory, and an
OutOfMemoryError there escaped the fallback, the native module's error
handling and the download task, leaving the promise unsettled - the worst
answer to the failure the fallback exists for. It is now absorbed like any
other patch failure, and the bundle is read into a buffer sized from the
asset instead of one that grows into a second copy of itself.

The download and install steps are now covered together, over a real socket
with real archives, with only the applier's two seams stubbed.

An update published with a binary patch offers two archives of the same
contents, and iOS now installs from the smaller one: the patch archive is
downloaded first, the JS bundle it carries only a patch of is rebuilt against
the bundle inside the app binary, and what is left is byte for byte what the
full archive would have delivered - so the folder hash check that follows the
install is unchanged and stays the last line of defence.

Nothing about a patch archive is trusted. Its manifest is read before anything
is applied and refused when it is not the format this client can apply, when
its paths reach outside the archive, or when it promises a bundle larger than
a bundle can be. Neither the diff format nor the zstd streams inside it carry
a checksum of the data they produce, so the base bundle is hashed before the
patch is applied and the restored bundle afterwards, and the restored bytes
only reach the update contents once both checks have passed.

Every failure downloads the full archive instead, exactly once and with
nothing stored to count it: the full archive is fetched by a call that cannot
take the patch path, so it has no failure of its own to fall back from. A
patch URL that answers with something other than an archive is one of those
failures rather than a bare JS bundle to move into place, which would install
bytes no hash was ever checked against.

The applier is the C code the other platform and the host build compile as
well, referenced where it lives rather than copied here, and the pod builds
it - which is what keeps the appliers of the platforms from drifting apart.

The iOS client installs an update from its patch archive too, so the paragraph
about what a released patch means for a client is no longer about one platform,
and the pod section says what that adds to a consumer's iOS build: nothing.
CocoaPods compiles the applier along with the rest of the pod, where Android
needs the NDK and CMake for the same sources.

Both NSData objects have their last ARC use before the C call that reads their
bytes for the whole of its run, so ARC was free to release them - unmapping the
base bundle out from under the applier. Give both locals a precise lifetime.

HDiffPatch is pinned to v5.1.3 but its zstd dependency was cloned from the
fork's default branch, so any upstream push silently changed the generator and
could break a build that had been green. Fetch the pinned commit instead, and
record it next to the zstd entry in the third party notices.

`hdiffz` is the one prerequisite a binary patch release has that npm install
does not provide, and the error a missing tool raises names
`scripts/binary-patch/build-hdiffpatch.sh` - a path the published package did
not carry. Add the script to `files`, and document the one-time build, what it
needs, where it installs, and the `HDIFFPATCH_TOOLS_DIR` override in both
release guides.

Requirements lists what an app has to have in place, and by its own
wording that bullet asked for nothing: the Android Gradle Plugin installs
the NDK and CMake versions it is missing. The binary patch section of the
CLI README still says the library builds native code and what that needs,
which is where the note belongs.

A manifest is untrusted input, and the size it names is what the restore
reserves before reading a byte of the patch. The old 512 MiB ceiling was
far above anything a release can produce: a large Hermes bundle stays
under 50 MB. A manifest that does exceed the bound costs nothing beyond
the full archive being downloaded instead, so 128 MiB leaves ample room
while cutting what a bad manifest can ask for.

The Android applier moves to the same value in the same change; the two
bounds are one contract and have to answer an oversized manifest alike.

…y-patch-cli-artifacts

…-patch-metadata

…h-android-apply

# Conflicts:
#	cli/README.ko.md
#	cli/README.md

…-patch-ios-apply