tree: 1e303830fc8af85ef36da591f6a9799cb186d13f [path history] [tgz]
  1. appindex_unittest.py
  2. nebraska.py
  3. nebraska_unittest.py
  4. README.md
  5. request_unittest.py
  6. response_unittest.py
  7. run_unittests
  8. sample.json
  9. unittest_common.py
nebraska/README.md

Nebraska

Nebraska is a mock Omaha server built to facilitate testing of new DLCs (DownLoadable Content) as well as update and install mechanisms in Chrome OS. It is designed to be a lightweight, simple, and dependency-free standalone server that can run on a host machine or DUT. Its single purpose is to respond to update and install requests with Omaha-like responses based on some provided metadata. All other related functions (i.e. generating payloads, transferring files to a DUT, and serving the payloads themselves) must be handled elsewhere.

System Requirements

The entire server is implemented in nebraska.py and Nebraska does not depend on anything outside of the Python standard libraries, so this file on its own should be sufficient to run the server on any device with Python 2.7.10 or newer.

WARNING: External dependencies should never be added to Nebraska!

Payload Metadata

Nebraska handles requests based on the contents of install and update payload directories. These directories should be populated with JSON files describing the payloads you wish to make available. On receiving a request, Nebraska searches the install or update payload directory as appropriate and formulates a response based on metadata describing a matching payload if it can find one. Nebraska expects at least one of these directories to be specified on startup.

Metadata Format

The information in these files should be output by paygen when generating a payload, and should have the following key-value pairs. See sample.json for an example.

appid: The appid of the app provided by the payload.
name: Payload file name.
target_version: App target version.
is_delta: True iff the payload is a delta update.
source_version: The source version if the payload is a delta update.
size: Total size of the payload.
metadata_signature: Metadata signature.
metadata_size: Metadata size.
sha256_hex: SHA256 of the payload.

Payload URLs

Nebraska does not serve the payload itself. It only provides payload metadata formatted in an Omaha-like response along with a URL where the payload can be found. The base of this URL can be given at startup.

The URL can be the URL of some other server that serves payloads, or can be a file URL that points to a directory on the DUT containing update and install payloads. When responding to a request, Nebraska constructs the URL it uses in its response by appending “update” or “install” onto the end of the given base URL depending on whether the request is for an update or install. The complete URL for a payload can be constructed by concatenating the URL given in by Nebraska with the name of the payload, which is also given in the response from Nebraska. Giving a file URL in place of server URL is possible due to the fact that update engine relies on libcurl to handle the payload transfer, which is able to handle local files in the same way it handles remote URLs.

Known Issues

Lazy Version Checking

We only check the first two version components when doing version comparisons. This is partially due to the way the final version component is constructed in development builds vs. production builds.

Detecting Update/Install

In order to signal that a DLC should be installed rather than updated, update engine includes a request for the platform app without a request for an update. This allows Omaha to differentiate between an update operation where Chrome OS and all DLCs will be updated to a strictly greater version, and an install operation where one or more DLCs of the same version as the platform app will be installed. We currently decide whether a request is for an update or install based on whether exactly one other app (which we assume to be the platform app) the request list does not have an associated update request.