[api] Rename to --obey-ratelimit

commands/api.go

@@ -74,7 +74,10 @@ var cmdApi = &Command{
 		resource as indicated in the "Link" response header. For GraphQL queries,
 		this utilizes 'pageInfo' that must be present in the query; see EXAMPLES.
 
-		Note that multiple JSON documents will be output as a result.
+		Note that multiple JSON documents will be output as a result. If the API
+		rate limit has been reached, the final document that is output will be the
+		HTTP 403 notice, and the process will exit with a non-zero status. One way
+		this can be avoided is by enabling '--obey-ratelimit'.
 
 	--color[=<WHEN>]
 		Enable colored output even if stdout is not a terminal. <WHEN> can be one
@@ -87,14 +90,10 @@ var cmdApi = &Command{
 		requests as well. Just make sure to not use '--cache' for any GraphQL
 		mutations.
 
-	--rate-limit
-		If the next '--paginate' request would exceed the rate limit allocation
-		as specified by the server, then print a message to standard error and
-		sleep until the time given in the rate limit reset header.
-
-		Without this flag, '--paginate' will continue to issue requests without
-		regard to the number of remaining rate limit slots, potentially
-		resulting in only partial pagination results.
+	--obey-ratelimit
+		After exceeding the API rate limit, pause the process until the reset time
+		of the current rate limit window and retry the request. Note that this may
+		cause the process to hang for a long time (maximum of 1 hour).
 
 	<ENDPOINT>
 		The GitHub API endpoint to send the HTTP request to (default: "/").
@@ -238,15 +237,14 @@ func apiCommand(_ *Command, args *Args) {
 		body = params
 	}
 
-	rateLimitWait := args.Flag.Bool("--rate-limit")
-
 	gh := github.NewClient(host)
 
 	out := ui.Stdout
 	colorize := colorizeOutput(args.Flag.HasReceived("--color"), args.Flag.Value("--color"))
 	parseJSON := args.Flag.Bool("--flat")
 	includeHeaders := args.Flag.Bool("--include")
 	paginate := args.Flag.Bool("--paginate")
+	rateLimitWait := args.Flag.Bool("--obey-ratelimit")
 
 	args.NoForward()
 

features/api.feature

@@ -435,9 +435,34 @@ Feature: hub api
         json [{}]
       }
       """
-    When I successfully run `hub api --rate-limit --paginate hello`
+    When I successfully run `hub api --obey-ratelimit --paginate hello`
     Then the stderr should contain "API rate limit exceeded; pausing until "
 
+  Scenario: Succumb to rate limit with pagination
+    Given the GitHub API server:
+      """
+      get('/hello') {
+        page = (params[:page] || 1).to_i
+        response.headers['X-Ratelimit-Remaining'] = '0'
+        response.headers['X-Ratelimit-Reset'] = Time.now.utc.to_i.to_s
+        if page == 2
+          status 403
+          json :message => "API rate limit exceeded"
+        else
+          response.headers['Link'] = %(</hello?page=#{page+1}>; rel="next")
+          json [{page:page}]
+        end
+      }
+      """
+    When I run `hub api --paginate -t hello`
+    Then the exit status should be 22
+    And the stderr should not contain "API rate limit exceeded"
+    And the stdout should contain exactly:
+      """
+      .[0].page	1
+      .message	API rate limit exceeded\n
+      """
+
   Scenario: Honor rate limit for 403s
     Given the GitHub API server:
       """
@@ -452,7 +477,7 @@ Feature: hub api
         json [{}]
       }
       """
-    When I successfully run `hub api --rate-limit hello`
+    When I successfully run `hub api --obey-ratelimit hello`
     Then the stderr should contain "API rate limit exceeded; pausing until "
 
   Scenario: 403 unrelated to rate limit
@@ -463,6 +488,6 @@ Feature: hub api
         status 403
       }
       """
-    When I run `hub api --rate-limit hello`
+    When I run `hub api --obey-ratelimit hello`
     Then the exit status should be 22
     Then the stderr should not contain "API rate limit exceeded"