Fetch Service sessions¶

Experimental

The integration with the Fetch Service is an experimental feature and therefore subject to change.

Craft Application uses Fetch Service to validate all dependencies that are downloaded during an artifact build. These dependencies are either software included in the artifact itself, or software that the build tool or build system needs.

Fetch Service operates in sessions, which run in one of two modes: managed or external.

Managed sessions¶

When the --enable-fetch-service option is passed to the pack command, Craft Application will open a Fetch Service session before starting the build, and close it after the build is finished. In this scenario, the Fetch Service must be available on the host so that Craft Application can talk to it.

A Fetch Service session must have a working policy, which is either permissive or strict. With a permissive policy, Fetch Service inspects but doesn’t filter any traffic. With a strict policy, it filters traffic according to a configuration in Craft Application. The policy is selected by adding it to the Fetch Service flag, with --enable-fetch-service=<policy>.

When Craft Application closes the session, it creates the final session report with the description of the items that were downloaded during artifact build. This is provided as a JSON file with the same name as the artifact itself, in the same directory.

External sessions¶

Alternatively, Craft Application can be configured to use a pre-existing Fetch Service session for builds and tests. In this mode of operation, Craft Application configures all traffic filtering for the session, but you are responsible for opening and closing the session itself, and otherwise managing Fetch Service.

In order to make use of this mode, users must create a Fetch Service session and configure the following environment variables before invoking the pack or test command:

Variable	Description
`http_proxy`, `https_proxy`	Must point to the full session url, including scheme, server and port.
`CRAFT_PROXY_CERT`	Must point to the Fetch Service’s CA certificate. This file must be locally accessible by Craft Application.
`CRAFT_USE_EXTERNAL_FETCH_SERVICE`	Must be `1` to use the session while building the artifact.
`CRAFT_TEST_FETCH_SERVICE_SESSIONS`	Can optionally point to a different session for test execution.

If CRAFT_USE_EXTERNAL_FETCH_SERVICE is set when running the test command, Craft Application will copy the certificate specified by CRAFT_PROXY_CERT, if set, to each spread runner and configure its package managers, snapd, and LXD to use the proxy.

Since the test command builds the artifact if necessary, the session will see traffic from both the build and the tests. In order to isolate the traffic from the tests, set CRAFT_TEST_FETCH_SERVICE_SESSIONS to point to a different session for test execution.

Because Craft Application has no control over the Fetch Service session in this mode, it can’t create a session report.