keep old links working for renamed default branches

If 'master' or 'main' fail to resolve, try again with 'HEAD' after a delay

this keeps old links to renamed default branches working for the big master->main migration

Author: minrk

binderhub/builder.py

@@ -2,6 +2,7 @@
 Handlers for working with version control services (i.e. GitHub) for builds.
 """
 
+import asyncio
 import hashlib
 import json
 import re
@@ -303,16 +304,43 @@ async def get(self, provider_prefix, _unescaped_spec):
                     'GitHub recently changed default branches from "master" to "main".'
                 )
 
-                if provider.unresolved_ref == "master":
-                    error_message.append('Did you mean the "main" branch?')
-                elif provider.unresolved_ref == "main":
-                    error_message.append('Did you mean the "master" branch?')
+                if provider.unresolved_ref in {"master", "main"}:
+                    error_message.append(
+                        "Tip: HEAD will always resolve to a repo's default branch."
+                    )
+
+                    # keep old links working for default branch names
+                    # by substituting 'master' or 'main' with 'HEAD'
+                    pre_ref_spec, _ = spec.rsplit("/", 1)
+                    spec = f"{pre_ref_spec}/HEAD"
+                    unresolved_ref = provider.unresolved_ref
+                    try:
+                        provider = self.get_provider(provider_prefix, spec=spec)
+                        ref = await provider.get_resolved_ref()
+                    except Exception as e:
+                        # if this fails, leave ref as None, which will fail below
+                        self.log.error(f"Error redirecting {key} to HEAD: {e}")
+                    else:
+                        # delayed redirect for deleted default branches
+                        await self.emit(
+                            {
+                                "phase": "waiting",
+                                "message": (
+                                    " ".join(error_message) + "\n"
+                                    f"Trying again with HEAD instead of {unresolved_ref}. Please update your links.\n"
+                                ),
+                            }
+                        )
+                        # artificial delay for what should be broken links
+                        await asyncio.sleep(10)
 
             else:
                 error_message.append("Is your repo public?")
 
-            await self.fail(" ".join(error_message))
-            return
+            if ref is None:
+                # ref can become non-None if redirected to HEAD
+                await self.fail(" ".join(error_message))
+                return
 
         self.ref_url = await provider.get_resolved_ref_url()
         resolved_spec = await provider.get_resolved_spec()

binderhub/repoproviders.py

@@ -38,8 +38,8 @@ def tokenize_spec(spec):
     spec_parts = spec.split("/", 2)  # allow ref to contain "/"
     if len(spec_parts) != 3:
         msg = f'Spec is not of the form "user/repo/ref", provided: "{spec}".'
-        if len(spec_parts) == 2 and spec_parts[-1] not in ("main", "master"):
-            msg += f' Did you mean "{spec}/main"?'
+        if len(spec_parts) == 2 and spec_parts[-1] not in {"main", "master", "HEAD"}:
+            msg += f' Did you mean "{spec}/HEAD"?'
         raise ValueError(msg)
 
     return spec_parts
@@ -564,7 +564,7 @@ class GitLabRepoProvider(RepoProvider):
     <url-escaped-namespace>/<unresolved_ref>
 
     eg:
-    group%2Fproject%2Frepo/master
+    group%2Fproject%2Frepo/main
     """
 
     name = Unicode("GitLab")
@@ -956,10 +956,9 @@ class GistRepoProvider(GitHubRepoProvider):
 
     The ref is optional, valid values are
         - a full sha1 of a ref in the history
-        - master
-        - HEAD for the default branch
+        - HEAD for the latest ref (also allow 'master', 'main' as aliases for HEAD)
 
-    If master or no ref is specified the latest revision will be used.
+    If HEAD or no ref is specified the latest revision will be used.
     """
 
     name = Unicode("Gist")
@@ -1020,7 +1019,7 @@ async def get_resolved_ref(self):
             )
 
         all_versions = [e["version"] for e in ref_info["history"]]
-        if self.unresolved_ref in {"", "HEAD", "master"}:
+        if self.unresolved_ref in {"", "HEAD", "master", "main"}:
             self.resolved_ref = all_versions[0]
         else:
             if self.unresolved_ref not in all_versions:

binderhub/tests/test_build.py

@@ -41,6 +41,8 @@
         # gh/ GitHub repo provider
         "gh/binderhub-ci-repos/cached-minimal-dockerfile/HEAD",
         "gh/binderhub-ci-repos/cached-minimal-dockerfile/596b52f10efb0c9befc0c4ae850cc5175297d71c",
+        # test redirect master->HEAD
+        "gh/binderhub-ci-repos/cached-minimal-dockerfile/master",
         # gl/ GitLab repo provider
         "gl/binderhub-ci-repos%2Fcached-minimal-dockerfile/HEAD",
         "gl/binderhub-ci-repos%2Fcached-minimal-dockerfile/596b52f10efb0c9befc0c4ae850cc5175297d71c",

binderhub/tests/test_repoproviders.py

@@ -360,14 +360,14 @@ def test_long_spec(self):
         assert len(spec_parts) == 3
 
     def test_spec_with_no_suggestion(self):
-        spec = "short/master"
+        spec = "short/HEAD"
         error = "^((?!Did you mean).)*$"  # negative match
         with self.assertRaisesRegex(ValueError, error):
             user, repo, unresolved_ref = tokenize_spec(spec)
 
     def test_spec_with_suggestion(self):
         spec = "short/suggestion"
-        error = f'Did you mean "{spec}/main"?'
+        error = f'Did you mean "{spec}/HEAD"?'
         with self.assertRaisesRegex(ValueError, error):
             user, repo, unresolved_ref = tokenize_spec(spec)