plugin-test: check Auth is used when list-all uses Github API

Many plugins were having this problem where they rely on accessing
GitHub's API for listing versions from some repo releases. But not
setting an Authorization token for `curl`, causes the test to fail.

We now detect that if the plugin `list-all` looks like accessing
`api.github.com` and if so, we also try to guess if the Authroization
header will be set. If not, we fail the test and head the plugin author
to some documentation on how to add it.

Hope this reduces the number of failures due to GitHub API rate
limiting on travis.

docs/creating-plugins.md

@@ -140,6 +140,27 @@ os:
   - osx
 ```
 
+## GitHub API Rate Limiting
+
+If your plugin's `list-all` depends on accessing the GitHub API, make sure you provide
+an Authorization token when accessing it, otherwise your tests might fail due to rate limiting.
+
+To do so, create a [new personal token](https://github.com/settings/tokens/new) with only `public_repo` access.
+
+Then on your travis.ci build settings add a *secure* environment variable for it
+named something like `GITHUB_API_TOKEN`. And *DO NOT* EVER publish your token in your code.
+
+Finally, add something like the following to `bin/list-all`
+
+```shell
+cmd="curl -s"
+if [ -n "$GITHUB_API_TOKEN" ]; then
+ cmd="$cmd -H 'Authorization: token $GITHUB_API_TOKEN'"
+fi
+
+cmd="$cmd $releases_path"
+```
+
 ## Submitting plugins to the official plugins repository
 
 `asdf` can easily install plugins by specifying the plugin repository url, e.g. `plugin-add my-plugin https://github.com/user/asdf-my-plugin.git`.

lib/commands/plugin-test.sh

@@ -36,6 +36,31 @@ plugin_test_command() {
         fi
 
 
+        local plugin_path
+        plugin_path=$(get_plugin_path "$plugin_name")
+        local list_all="$plugin_path/bin/list-all"
+        if grep api.github.com "$list_all" >/dev/null; then
+            if ! grep Authorization "$list_all" >/dev/null; then
+                echo
+                echo "Looks like ${plugin_name}/bin/list-all relies on GitHub releases"
+                echo "but it does not properly sets an Authorization header to prevent"
+                echo "GitHub API rate limiting."
+                echo
+                echo "See https://github.com/asdf-vm/asdf/blob/master/docs/creating-plugins.md#github-api-rate-limiting"
+
+                fail_test "$plugin_name/bin/list-all does not set GitHub Authorization token"
+            fi
+
+            # test for most common token names we have on plugins
+            if [ -z "$OAUTH_TOKEN" ] || [ -z "$GITHUB_API_TOKEN" ] ; then
+                echo "$plugin_name/bin/list-all is using GitHub API, just be sure you provide an API Authorization token"
+                echo "via your travis settings. This is the current rate_limit:"
+                echo
+                curl -s https://api.github.com/rate_limit
+                echo
+            fi
+        fi
+
         local versions
         # shellcheck disable=SC2046
         if ! read -r -a versions <<< $(asdf list-all "$plugin_name"); then