chromium/src
0
Fork 0
Code Activity

Updater: Remove FP from v4 protocol documentation.

Browse Source 
Bug: 353249967
Change-Id: Ib32098fd4712ded3cec017dfb3160289c291af08
Reviewed-on: https://chromium-review.googlesource.com/c/chromium/src/+/6300769
Auto-Submit: Joshua Pawlicki <waffles@chromium.org>
Reviewed-by: Sorin Jianu <sorin@chromium.org>
Commit-Queue: Sorin Jianu <sorin@chromium.org>
Cr-Commit-Position: refs/heads/main@{#1425479}
This commit is contained in:
Joshua Pawlicki
2025-02-26 16:54:57 -08:00
committed by Chromium LUCI CQ
parent e6e1282a1e
commit 0075e4c935
1 changed files with 43 additions and 62 deletions

105
docs/updater/protocol_4.md

@ -132,16 +132,8 @@ A differential update achieves better compression by relying on information
A version number is usually insufficient to identify the binaries the client
already has, since they may vary by architecture, platform, or other variables
while retaining the same official version number. Therefore, the server sends a
more precise label with each package. Once an update payload is installed, the
"package fingerprint" that is associated with this payload is then sent back in
subsequent update checks.
The package fingerprint sent by the server must identify the payload that will
eventually be installed by the client as a result of processing the server's
response. This will usually be derived from a checksum of the package payload,
which will be different from the payload the client initially downloads if the
downloaded payload is compressed, differential, or otherwise transformed.
while retaining the same official version number. Therefore, the client sends
hashes of the binaries it has cached.
### Pipelines
A pipeline represents a series of operations to obtain and process a payload in
@ -159,6 +151,15 @@ pipeline is successful, or all pipelines have failed. This increases the
probability that a pipeline will be applied, even if all differential pipelines
fail.
Some pipeline operations have a `hash_in` member, describing the hash of the
file that the operation will operate on. If a file with a matching hash is
already cached, clients may skip the preceding operations. Similarly, clients
may skip operations preceding and including any operation that has a
`hash_out` member if they already have a file matching `hash_out` cached.
Since the contents of the cache may change as a client attempts and falls back
between pipelines, the server cannot always predict what operations a client
may skip.
### Extensions & Forward Compatibility
The protocol is extensible via the addition of new object members. Clients must
tolerate the existence of members they do not handle. Unofficial or
@ -388,12 +389,9 @@ following members:
unknown, or that the concept of enabling/disabling does not exist. "0"
indicates that the application is disabled. "1" indicates that the app is
enabled. Default: "-1".
* `fp`: A `fingerprint` object representing the currently installed
[package fingerprint](#differential-updates) of the application.
* `cached_fingerprints`: A list of `fingerprint` objects, one for each
currently cached [package fingerprint](#differential-updates)
of the application. This list may be empty if the local cache is empty or
does not exist.
* `cache`: A list of `hash` objects, identifying files that the client has
available to use for the purposes of differential updates. This list may
be empty, for example if the local cache is empty or does not exist.
* `iid`: Installation ID is an opaque token that identifies an installation
flow. The installation ID is a unique identifier embedded into a
metainstaller for the application. It can be used to correlate the first
@ -438,11 +436,8 @@ following members:
* `updatecheck`: An `updatecheck` object. This member may be omitted if the
client will not honor an update response.
#### `fingerprint` Objects (Update Check Request)
A `fingerprint` object contains a string representing the
[package fingerprint](#differential-updates) for this update.
* `fingerprint`: The package fingerprint for this package given as a string,
or "" if the fingerprint is unknown. Default: "".
#### `hash` Objects (Update Check Request)
* `sha256`: A SHA-256 hash, rendered in lowercase base16.
#### `ping` Objects (Update Check Request)
* `ad`: The date that the previous active report took place on, or "-1" if
@ -669,14 +664,18 @@ the following members:
The following members are only present if the `status` is "ok":
* `nextversion`: The expected version of the product, if any pipeline is
able to complete all operations successfully.
* `nextfp`: A `fingerprint` object representing the package fingerprint
associated with the all `pipeline` objects.
* `pipeline`: A list of `pipeline` objects.
#### `pipeline` Objects (Update Check Response)
A pipeline object describes a pipeline process that may be applied in order to
update the current binary. A pipeline is represented as a series of operations.
A pipeline object has the following members:
* `pipeline_id`: A string describing the pipeline strategy. This string is
echoed back to the server in `event` objects to help the server attribute
events to a particular pipeline. Pipeline IDs are not necessarily globally
unique; for example, a server might use an ID of "h1 -> h2 via zucchini" to
identify a pipeline that updates an application from h1 to h2, using a
zucchini patch, and reuse that ID across many update check responses.
* `operation`: A list of `operation` objects.
#### `operation` Objects (Update Check Response)
@ -691,8 +690,8 @@ the following members:
For `type == "download"`: Download a payload.
* `size`: The size in bytes of the payload requested for download.
* `outhash_sha256`: The SHA256 hash of the payload downloaded, encoded as a
lowercase hexadecimal string.
* `hash_out`: A `hash` object containing the expected hash of the downloaded
bytes.
* `url`: The ordered list of url objects from which this payload may be
obtained. Clients must attempt to download from each URL of the appropriate
type in the specified order, falling back to the next URL if a TCP or HTTP
@ -708,19 +707,17 @@ For `type == "decompress_lzma"`: Decompress a file produced by the previous
For `type == "zucc"`: Apply a differential Zucchini patch produced by a
previous operation to a cached payload. The patch is generated using
[Zucchini](https://chromium.googlesource.com/chromium/src.git/+/main/components/zucchini/README.md).
* `previousfp`: A `fingerprint` object representing the package fingerprint of
the package that must be used as the input for this patch operation.
* `previous`: A `hash` object representing the file to apply this patch to.
For `type == "puff"`: Apply a differential Puffin patch produced by a previous
operation to a payload stored in the cache. The patch is generated using
[Puffin](https://chromium.googlesource.com/chromium/src.git/+/main/third_party/puffin/README.md).
* `previousfp`: A `fingerprint` object representing the package fingerprint of
the package that must be used as the input for this patch operation.
* `previous`: A `hash` object representing the file to apply this patch to.
For `type == "crx3"`: Decompress a CRX3 package produced by the previous
operation and install it.
* `inhash_sha256`: The SHA256 hash of the payload produced by the previous
operation, encoded as a lowercase hexadecimal string.
* `hash_in`: A `hash` object containing the expected hash of the CRX3 to be
installed.
* `path`: The path to a payload or directory, relative to the root of the CRX
archive. This may be left blank in cases where execution after install is
not necessary.
@ -728,10 +725,9 @@ For `type == "crx3"`: Decompress a CRX3 package produced by the previous
passed to the identified binary to execute.
For `type == "run"`: Execute a binary located at a given path.
* `path`: The path to the executable relative to the install directory
(or in an update with the associated `nextfp`, provided by the parent object
`pipeline`, if this response does not contain an update for this
application) given as a string.
* `path`: The path to the executable relative to the directory that the
application is currently installed into. If the application was updated
earlier in this pipeline, this path is relative to the new installation.
* `arguments`: The command line arguments to be passed to the executable,
formatted as a single string.
@ -806,13 +802,13 @@ attmpted as part of this update session. All events have the following members:
* 2: An install session.
* 3: An update session.
* 4: An uninstall session.
* 14: A download operation.
* 60: A decompress_lzma operation.
* 61: A zucchini patch application operation.
* 62: A puffin patch application operation.
* 63: A crx3 package installation operation.
* 14: A `download` operation.
* 60: A `decompress_lzma` operation.
* 61: A `zucchini` patch application operation.
* 62: A `puffin` patch application operation.
* 63: A `crx3` package installation operation.
* 41: An app command completion event.
* 42: A run operation.
* 42: A `run` operation.
* `eventresult`: The outcome of the operation. Default: 0. Known values:
* 0: error
* 1: success
@ -840,17 +836,11 @@ attmpted as part of this update session. All events have the following members:
Depending on the event type, additional members may be present:
For `eventtype == 2` events:
* `nextfp`: A `fingerprint` object representing the
[package fingerprint](#differential-updates) that the client was attempting
to update to, regardless of whether that update was successful.
* `nextversion`: The application version that the client was attempting to
update to, regardless of whether the update was successful.
For `eventtype == 3` events:
* All the members of `eventtype == 2` events.
* `previousfp`: A `fingerprint` object representing the
[package fingerprint](#differential-updates) of the application, prior to
the update, regardless of whether that update was successful.
* `previousversion`: The application version the client had prior to the
update, regardless of whether that update was successful.
@ -868,23 +858,14 @@ For `eventtype == 14` events:
* "direct": The Chromium network stack.
* `expected_bytes`: The number of bytes expected to be downloaded. Default:
0.
* `pipeline_id`: The `pipeline_id` set in the request for this operation's
pipeline.
* `url`: The URL from which the download was attempted.
For `eventtype == 60` events:
* All the members of `eventtype == 3` events, including those inherited from
`eventtype == 2` events.
For `eventtype == 61` events:
* All the members of `eventtype == 3` events, including those inherited from
`eventtype == 2` events.
For `eventtype == 62` events:
* All the members of `eventtype == 3` events, including those inherited from
`eventtype == 2` events.
For `eventtype == 63` events:
* All the members of `eventtype == 3` events, including those inherited from
`eventtype == 2` events.
For `eventtype` == 60, 61, 62, or 63 events:
* All the members of `eventtype == 3` events.
* `pipeline_id`: The `pipeline_id` set in the request for this operation's
pipeline.
For `eventtype == 41` events:
* `appcommandid`: The id of the app command for which the ping is being sent.