shorebird/packages/artifact_proxy

Artifact Proxy

This is a tool for proxying Flutter artifacts from a derived Flutter engine revision back to the base Flutter engine revision. This is useful for when you need to modify some of the Flutter artifacts but not all of them.

This is a development tool which maps requests to configurable artifact origins. By default, Flutter artifacts are redirected to the public Flutter storage origin and Shorebird-specific artifacts are redirected to the local open mirror root at http://localhost:8080/artifacts.

Usage

Uses config.dart to configure recognized artifact URL patterns. Runtime origins are configured with environment variables:

• SHOREBIRD_ARTIFACT_BASE_URL: root for open Shorebird manifests and artifacts, defaulting to http://localhost:8080/artifacts
• ARTIFACT_PROXY_FLUTTER_BASE_URL: root for upstream Flutter artifacts, defaulting to https://storage.googleapis.com

# Run locally with hot-reload enabled.
PORT=8081 DEV=true dart --enable-vm-service run bin/server.dart

And then in a separate terminal:

FLUTTER_STORAGE_BASE_URL=http://localhost:8081 flutter precache -a

You should use a separate checkout of Flutter when running this, so you don't poison the cache of your main Flutter checkout.

Updating config.dart

If you run into 404s when fetching artifacts, ensure that the expected manifest exists at:

$SHOREBIRD_ARTIFACT_BASE_URL/shorebird/$engineRevision/artifacts_manifest.yaml

If it does, you may need to update the artifact list in config.dart and, if the artifact is one we're providing, add it in ../../../scripts/write_artifact_manifest.py.

To do so, point Flutter at this proxy with FLUTTER_STORAGE_BASE_URL, run a Shorebird/Flutter command that downloads the missing artifact, then add the observed URL pattern to packages/artifact_proxy/lib/config.dart.

If you changed Flutter tool code while debugging, remove the flutter_tools snapshot:

cd bin/cache/flutter/bin/cache
rm flutter_tools.s*

• Run a Shorebird command (shorebird run works well).
• For each artifact that 404s, add a line to packages/artifact_proxy/lib/config.dart, following the conventions for capturing engine revisions and escaping relevant characters.

Generating an artifacts_manifest.yaml

To generate a new artifacts_manifest.yaml for a specific Flutter engine revision, use the workspace helper:

../../../scripts/write_artifact_manifest.py \
  --flutter-engine-revision <flutter_engine_revision> \
  --output artifacts_manifest.yaml

--flutter-engine-revision is the upstream Flutter engine revision used for unchanged artifacts. Upload the generated file under the custom Shorebird engine revision path shown below.

Then upload the artifacts_manifest.yaml to:

$SHOREBIRD_ARTIFACT_BASE_URL/shorebird/<shorebird_engine_revision>/artifacts_manifest.yaml

The GitHub CI engine artifacts include a mirror/ subtree for the override files listed by this manifest. Copy the contents of that subtree to $SHOREBIRD_ARTIFACT_BASE_URL alongside the manifest and patch-*.zip artifacts.