repository initial source and CI

Author: gofri

.github/workflows/lint.yaml

@@ -0,0 +1,24 @@
+name: Lint
+on:
+  push:
+    tags:
+      - v*
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/setup-go@c4a742cab115ed795e34d4513e2cf7d472deb55f # v3
+        with:
+          go-version: 1.19
+      - uses: actions/checkout@93ea575cb5d8a053eaa0ac8fa3b40d7e05a33cc8 # v3
+      - name: Lint
+        uses: golangci/golangci-lint-action@08e2f20817b15149a52b5b3ebe7de50aff2ba8c5 # v3.4.0
+        with:
+          version: v1.50.1
+          args: --timeout=3m

.github/workflows/test.yaml

@@ -0,0 +1,27 @@
+name: Test
+on:
+  push:
+    tags:
+      - v*
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+
+jobs:
+  build_and_test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/setup-go@c4a742cab115ed795e34d4513e2cf7d472deb55f # v3
+        with:
+          go-version: 1.19
+      - uses: actions/checkout@93ea575cb5d8a053eaa0ac8fa3b40d7e05a33cc8 # v3
+      - name: Verify dependencies
+        run: go mod verify
+      - name: Build
+        run: go build -v ./...
+      - name: Vet
+        run: go vet -v ./...
+      - name: Test
+        run: go test -v -count=1 -shuffle=on -timeout=30m -race ./...

README.md

@@ -1,2 +1,45 @@
 # go-github-ratelimit
-A GoLang HTTP RoundTripper that handles GitHub API secondary rate limits
+
+[![Go Report Card](https://goreportcard.com/badge/github.com/gofri/go-github-ratelimit)](https://goreportcard.com/report/github.com/gofri/go-github-ratelimit)
+
+Package go-github-ratelimit provides a http.RoundTripper implementation that handles [secondary rate limit](https://docs.github.com/en/rest/overview/resources-in-the-rest-api?apiVersion=2022-11-28#secondary-rate-limits) for the GitHub API.  
+The RoundTripper waits for the secondary rate limit to finish in a blocking mode and then issues/retries requests.
+
+go-github-ratelimit can be used with any HTTP client communicating with GitHub API.    
+It is meant to complement [go-github](https://github.com/google/go-github), but there is no association between this repository and the go-github repository or Google.  
+  
+## Installation
+```go get github.com/gofri/go-github-ratelimit```
+
+## Usage Example (with go-github and [oauth2](golang.org/x/oauth2))
+```go
+import "github.com/google/go-github/github"
+import "golang.org/x/oauth2"
+import "github.com/gofri/go-github-ratelimit/github_ratelimit"
+
+func main() {
+	ctx := context.Background()
+	ts := oauth2.StaticTokenSource(
+		&oauth2.Token{AccessToken: "Your Personal Access Token"},
+	)
+	tc := oauth2.NewClient(ctx, ts)
+	rateLimiter := github_ratelimit.NewRateLimitWaiterClient(tc.Transport)
+	client := github.NewClient(rateLimiter)
+
+	// now use the client as you please
+}
+```
+
+## Options
+The RoundTripper accepts a set of optional options:
+- Single Sleep Limit: limit the sleep time for a single rate limit.
+- Total Sleep Limit: limit the accumulated sleep time for all rate limits.
+  
+The RoundTripper accepts a set of optional callbacks:
+- On Limit Detected: callback for when a rate limit that requires sleeping is detected.
+- On Single Limit Exceeded: callback for when a rate limit that exceeds the single sleep limit is detected.
+- On Total Limit Exceeded: callback for when a rate limit that exceeds the total sleep limit is detected.
+
+## License
+This package is distributed under the MIT license found in the LICENSE file.  
+Contribution and feedback is welcome.

github_ratelimit/callback.go

@@ -0,0 +1,35 @@
+package github_ratelimit
+
+import (
+	"context"
+	"net/http"
+	"time"
+)
+
+// CallbackContext is passed to all callbacks.
+// Fields might be nillable, depending on the specific callback and field.
+type CallbackContext struct {
+	UserContext    *context.Context
+	RoundTripper   *SecondaryRateLimitWaiter
+	SleepUntil     *time.Time
+	TotalSleepTime *time.Duration
+	Request        *http.Request
+	Response       *http.Response
+}
+
+// OnLimitDetected is a callback to be called when a new rate limit is detected (before the sleep)
+// The totalSleepTime includes the sleep time for the upcoming sleep
+// Note: called while holding the lock.
+type OnLimitDetected func(*CallbackContext)
+
+// OnSingleLimitPassed is a callback to be called when a rate limit is exceeding the limit for a single sleep.
+// The sleepUntil represents the end of sleep time if the limit was not exceeded.
+// The totalSleepTime does not include the sleep (that is not going to happen).
+// Note: called while holding the lock.
+type OnSingleLimitExceeded func(*CallbackContext)
+
+// OnTotalLimitExceeded is a callback to be called when a rate limit is exceeding the limit for the total sleep.
+// The sleepUntil represents the end of sleep time if the limit was not exceeded.
+// The totalSleepTime does not include the sleep (that is not going to happen).
+// Note: called while holding the lock.
+type OnTotalLimitExceeded func(*CallbackContext)

github_ratelimit/github_ratelimit_test/ratelimit_injecter.go

@@ -0,0 +1,108 @@
+package github_ratelimit_test
+
+import (
+	"fmt"
+	"io"
+	"net/http"
+	"strings"
+	"sync"
+	"time"
+)
+
+type SecondaryRateLimitInjecter struct {
+	base          http.RoundTripper
+	options       *SecondaryRateLimitInjecterOptions
+	blockUntil    time.Time
+	lock          sync.Mutex
+	AbuseAttempts int
+}
+
+const (
+	RateLimitInjecterEvery    = "SECONDARY_RATE_LIMIT_INJECTER_EVERY"
+	RateLimitInjecterDuration = "SECONDARY_RATE_LIMIT_INJECTER_DURATION"
+)
+
+type SecondaryRateLimitInjecterOptions struct {
+	Every time.Duration
+	Sleep time.Duration
+}
+
+func NewRateLimitInjecter(base http.RoundTripper, options *SecondaryRateLimitInjecterOptions) (http.RoundTripper, error) {
+	if options.IsNoop() {
+		return base, nil
+	}
+	if err := options.Validate(); err != nil {
+		return nil, err
+	}
+
+	injecter := &SecondaryRateLimitInjecter{
+		base:    base,
+		options: options,
+	}
+	return injecter, nil
+}
+
+func (t *SecondaryRateLimitInjecter) RoundTrip(request *http.Request) (*http.Response, error) {
+	resp, err := t.base.RoundTrip(request)
+	if err != nil {
+		return resp, err
+	}
+
+	t.lock.Lock()
+	defer t.lock.Unlock()
+
+	// initialize on first use
+	now := time.Now()
+	if t.blockUntil.IsZero() {
+		t.blockUntil = now
+	}
+
+	// on-going rate limit
+	if t.blockUntil.After(now) {
+		t.AbuseAttempts++
+		return t.toRetryResponse(resp), nil
+	}
+
+	nextStart := t.NextSleepStart()
+
+	// start a rate limit period
+	if !now.Before(nextStart) {
+		t.blockUntil = nextStart.Add(t.options.Sleep)
+		return t.toRetryResponse(resp), nil
+	}
+
+	return resp, nil
+}
+
+func (r *SecondaryRateLimitInjecterOptions) IsNoop() bool {
+	return r.Every == 0 || r.Sleep == 0
+}
+
+func (r *SecondaryRateLimitInjecterOptions) Validate() error {
+	if r.Every < 0 {
+		return fmt.Errorf("injecter expects a positive trigger interval")
+	}
+	if r.Sleep < 0 {
+		return fmt.Errorf("injecter expects a positive sleep interval")
+	}
+	return nil
+}
+func (r *SecondaryRateLimitInjecter) CurrentSleepEnd() time.Time {
+	return r.blockUntil
+}
+
+func (r *SecondaryRateLimitInjecter) NextSleepStart() time.Time {
+	return r.blockUntil.Add(r.options.Every)
+}
+
+func (t *SecondaryRateLimitInjecter) toRetryResponse(resp *http.Response) *http.Response {
+	resp.StatusCode = http.StatusForbidden
+	timeUntil := time.Until(t.blockUntil)
+	if timeUntil.Nanoseconds()%int64(time.Second) > 0 {
+		timeUntil += time.Second
+	}
+	resp.Header.Set("Retry-After", fmt.Sprintf("%v", int(timeUntil.Seconds())))
+	doc_url := "https://docs.github.com/en/rest/guides/best-practices-for-integrators?apiVersion=2022-11-28#secondary-rate-limits"
+	resp.Body = io.NopCloser(strings.NewReader(`{"documentation_url":"` + doc_url + `"}`))
+	return resp
+}

github_ratelimit/options.go

@@ -0,0 +1,49 @@
+package github_ratelimit
+
+import (
+	"context"
+	"time"
+)
+
+type Option func(*SecondaryRateLimitWaiter)
+
+// WithLimitDetectedCallback adds a callback to be called when a new active rate limit is detected.
+func WithLimitDetectedCallback(callback OnLimitDetected) Option {
+	return func(t *SecondaryRateLimitWaiter) {
+		t.onLimitDetected = callback
+	}
+}
+
+// WithSingleSleepLimit adds a limit to the duration allowed to wait for a single sleep (rate limit).
+// The callback parameter is nillable.
+func WithSingleSleepLimit(limit time.Duration, callback OnSingleLimitExceeded) Option {
+	return func(t *SecondaryRateLimitWaiter) {
+		t.singleSleepLimit = &limit
+		t.onSingleLimitExceeded = callback
+	}
+}
+
+// WithTotalSleepLimit adds a limit to the accumulated duration allowed to wait for all sleeps (one or more rate limits).
+// The callback parameter is nillable.
+func WithTotalSleepLimit(limit time.Duration, callback OnTotalLimitExceeded) Option {
+	return func(t *SecondaryRateLimitWaiter) {
+		t.totalSleepLimit = &limit
+		t.onTotalLimitExceeded = callback
+	}
+}
+
+// WithUserContext sets the user context to be passed to callbacks.
+func WithUserContext(ctx context.Context) Option {
+	return func(t *SecondaryRateLimitWaiter) {
+		t.userContext = &ctx
+	}
+}
+
+func applyOptions(w *SecondaryRateLimitWaiter, opts ...Option) {
+	for _, o := range opts {
+		if o == nil {
+			continue
+		}
+		o(w)
+	}
+}