Make get_default_canonical_id public

src/main/java/com/google/devtools/build/lib/bazel/repository/starlark/StarlarkBaseExternalContext.java

@@ -605,7 +605,10 @@ private StructImpl completeDownload(PendingDownload pendingDownload)
           Downloads a file to the output path for the provided url and returns a struct \
           containing <code>success</code>, a flag which is <code>true</code> if the \
           download completed successfully, and if successful, a hash of the file \
-          with the fields <code>sha256</code> and <code>integrity</code>.
+          with the fields <code>sha256</code> and <code>integrity</code>. \
+          When <code>sha256</code> or <code>integrity</code> is user specified, setting an explicit \
+          <code>canonical_id</code> is highly recommended. e.g. \
+          <a href='/rules/lib/repo/cache#get_default_canonical_id'><code>get_default_canonical_id</code></a>
           """,
       useStarlarkThread = true,
       parameters = {
@@ -804,7 +807,10 @@ public Object download(
           Downloads a file to the output path for the provided url, extracts it, and returns a \
           struct containing <code>success</code>, a flag which is <code>true</code> if the \
           download completed successfully, and if successful, a hash of the file with the \
-          fields <code>sha256</code> and <code>integrity</code>.
+          fields <code>sha256</code> and <code>integrity</code>. \
+          When <code>sha256</code> or <code>integrity</code> is user specified, setting an explicit \
+          <code>canonical_id</code> is highly recommended. e.g. \
+          <a href='/rules/lib/repo/cache#get_default_canonical_id'><code>get_default_canonical_id</code></a>
           """,
       useStarlarkThread = true,
       parameters = {

src/test/shell/bazel/external_integration_test.sh

@@ -3003,6 +3003,50 @@ EOF
   test -h "$execroot/external/ext" || fail "Expected symlink to external repo."
 }
 
+function test_default_canonical_id_enabled() {
+    cat > repo.bzl <<EOF
+load("@bazel_tools//tools/build_defs/repo:cache.bzl", "get_default_canonical_id")
+
+def _impl(rctx):
+  print("canonical_id", repr(get_default_canonical_id(rctx, ["url-1", "url-2"])))
+  rctx.file("BUILD", "")
+
+dummy_repository = repository_rule(_impl)
+EOF
+  touch BUILD
+  cat > WORKSPACE <<EOF
+load('//:repo.bzl', 'dummy_repository')
+dummy_repository(name = 'foo')
+EOF
+
+  # NOTE: Test environment modifies defaults, so --repo_env must be explicitly set
+  bazel query @foo//:all --repo_env=BAZEL_HTTP_RULES_URLS_AS_DEFAULT_CANONICAL_ID=1 \
+    2>$TEST_log || fail 'Expected fetch to succeed'
+  expect_log "canonical_id \"url-1 url-2\""
+}
+
+function test_default_canonical_id_disabled() {
+    cat > repo.bzl <<EOF
+load("@bazel_tools//tools/build_defs/repo:cache.bzl", "get_default_canonical_id")
+
+def _impl(rctx):
+  print("canonical_id", repr(get_default_canonical_id(rctx, ["url-1", "url-2"])))
+  rctx.file("BUILD", "")
+
+dummy_repository = repository_rule(_impl)
+EOF
+  touch BUILD
+  cat > WORKSPACE <<EOF
+load('//:repo.bzl', 'dummy_repository')
+dummy_repository(name = 'foo')
+EOF
+
+  # NOTE: Test environment modifies defaults, so --repo_env must be explicitly set
+  bazel query @foo//:all --repo_env=BAZEL_HTTP_RULES_URLS_AS_DEFAULT_CANONICAL_ID=0 \
+    2>$TEST_log || fail 'Expected fetch to succeed'
+  expect_log "canonical_id \"\""
+}
+
 function test_environ_incrementally() {
   # Set up workspace with a repository rule to examine env vars.  Assert that undeclared
   # env vars don't trigger reevaluations.

tools/build_defs/repo/BUILD

@@ -40,6 +40,7 @@ genrule(
 )
 
 REPO_BZL_FILES = [
+    "cache",
     "git",
     "http",
     "local",

tools/build_defs/repo/cache.bzl

@@ -20,7 +20,7 @@
 
 """Returns the default canonical id to use for downloads."""
 
-visibility("private")
+visibility("public")
 
 DEFAULT_CANONICAL_ID_ENV = "BAZEL_HTTP_RULES_URLS_AS_DEFAULT_CANONICAL_ID"
 
@@ -37,7 +37,28 @@ machines without the file in the cache. This behavior can be disabled with
 """.format(env = DEFAULT_CANONICAL_ID_ENV)
 
 def get_default_canonical_id(repository_ctx, urls):
-    """Returns the default canonical id to use for downloads."""
+    """Returns the default canonical id to use for downloads.
+
+    Returns `""` (empty string) when Bazel is run with
+    `--repo_env=BAZEL_HTTP_RULES_URLS_AS_DEFAULT_CANONICAL_ID=0`.
+
+    e.g.
+    ```python
+    load("@bazel_tools//tools/build_defs/repo:cache.bzl", "get_default_canonical_id")
+    # ...
+        repository_ctx.download_and_extract(
+            url = urls,
+            integrity = integrity
+            canonical_id = get_default_canonical_id(repository_ctx, urls),
+        ),
+    ```
+
+    Args:
+      repository_ctx: The repository context of the repository rule calling this utility
+        function.
+      urls: A list of URLs matching what is passed to `repository_ctx.download` and
+        `repository_ctx.download_and_extract`.
+    """
     if repository_ctx.os.environ.get(DEFAULT_CANONICAL_ID_ENV) == "0":
         return ""