feat: add rate limit for request paypal api

Author: SpectatorNan

client.go

@@ -10,8 +10,12 @@ import (
 	"net/http"
 	"net/http/httputil"
 	"time"
+
+	"github.com/plutov/paypal/v4/limiter"
 )
 
+var ErrRateLimited = errors.New("rate limited")
+
 // NewClient returns new Client struct
 // APIBase is a base API URL, for testing you can use paypal.APIBaseSandBox
 func NewClient(clientID string, secret string, APIBase string) (*Client, error) {
@@ -76,6 +80,15 @@ func (c *Client) SetReturnRepresentation() {
 	c.returnRepresentation = true
 }
 
+// SetLimiter configures an optional rate limiter used by SendWithAuth.
+// key is used as the rate limit bucket key; if empty, a default is used.
+func (c *Client) SetLimiter(l limiter.RateLimiter, key string) {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+	c.rateLimiter = l
+	c.rateLimiterKey = key
+}
+
 // Send makes a request to the API, the response body will be
 // unmarshalled into v, or if v is an io.Writer, the response will
 // be written to it without decoding
@@ -166,7 +179,34 @@ func (c *Client) SendWithAuth(req *http.Request, v interface{}) error {
 	// Note: Here we do not want to `defer c.Unlock()` because we need `c.Send(...)`
 	// to happen outside of the locked section.
 
-	if c.Token == nil || (!c.tokenExpiresAt.IsZero() && time.Until(c.tokenExpiresAt) < RequestNewTokenBeforeExpiresIn) {
+	// determine if a token request is needed under the lock
+	needToken := c.Token == nil || (!c.tokenExpiresAt.IsZero() && time.Until(c.tokenExpiresAt) < RequestNewTokenBeforeExpiresIn)
+
+	// optional rate limiting
+	if c.rateLimiter != nil {
+		key := c.rateLimiterKey
+		if key == "" {
+			key = "paypal:client"
+		}
+		ctx := req.Context()
+		permits := 1
+		if needToken {
+			permits = 2 // one for token request, one for the main API call
+		}
+		for i := 0; i < permits; i++ {
+			dec, err := c.rateLimiter.Allow(ctx, key)
+			if err != nil {
+				c.mu.Unlock()
+				return err
+			}
+			if !dec.Allowed {
+				c.mu.Unlock()
+				return ErrRateLimited
+			}
+		}
+	}
+
+	if needToken {
 		// c.Token will be updated in GetAccessToken call
 		if _, err := c.GetAccessToken(req.Context()); err != nil {
 			// c.Unlock()

client_limiter_test.go

@@ -0,0 +1,132 @@
+package paypal
+
+import (
+	"context"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"sync/atomic"
+	"testing"
+	"time"
+
+	"github.com/plutov/paypal/v4/limiter"
+	"github.com/stretchr/testify/assert"
+)
+
+type okResp struct {
+	OK bool `json:"ok"`
+}
+
+func newTestServer() (*httptest.Server, *int32, *int32) {
+	tokenHits := new(int32)
+	apiHits := new(int32)
+	mux := http.NewServeMux()
+	mux.HandleFunc("/v1/oauth2/token", func(w http.ResponseWriter, r *http.Request) {
+		atomic.AddInt32(tokenHits, 1)
+		w.Header().Set("Content-Type", "application/json")
+		_ = json.NewEncoder(w).Encode(map[string]any{
+			"access_token": "test-token",
+			"token_type":   "Bearer",
+			"expires_in":   3600,
+		})
+	})
+	mux.HandleFunc("/api", func(w http.ResponseWriter, r *http.Request) {
+		atomic.AddInt32(apiHits, 1)
+		if r.Header.Get("Authorization") == "" {
+			w.WriteHeader(http.StatusUnauthorized)
+			return
+		}
+		w.Header().Set("Content-Type", "application/json")
+		_ = json.NewEncoder(w).Encode(okResp{OK: true})
+	})
+	return httptest.NewServer(mux), tokenHits, apiHits
+}
+
+func newClientForServer(t *testing.T, s *httptest.Server) *Client {
+	t.Helper()
+	c, err := NewClient("id", "secret", s.URL)
+	if err != nil {
+		t.Fatalf("new client: %v", err)
+	}
+	c.SetHTTPClient(s.Client())
+	return c
+}
+
+func TestClientLimiter_BlocksWhenInsufficientPermitsForTokenAndRequest(t *testing.T) {
+	s, tokenHits, apiHits := newTestServer()
+	defer s.Close()
+	c := newClientForServer(t, s)
+
+	// limiter allows only 1 request, but we need 2 (token + api)
+	lim := limiter.NewFixedWindowLimiter(limiter.NewMemoryStorage(), limiter.FixedWindowConfig{Window: time.Minute, Limit: 1})
+	c.SetLimiter(lim, "test-key")
+
+	req, _ := c.NewRequest(context.Background(), http.MethodGet, s.URL+"/api", nil)
+	var out okResp
+	err := c.SendWithAuth(req, &out)
+	assert.Error(t, err)
+	assert.Equal(t, ErrRateLimited, err)
+	// should have short-circuited before hitting network
+	assert.Equal(t, int32(0), atomic.LoadInt32(tokenHits))
+	assert.Equal(t, int32(0), atomic.LoadInt32(apiHits))
+}
+
+func TestClientLimiter_AllowsWithSufficientPermitsForTokenAndRequest(t *testing.T) {
+	s, tokenHits, apiHits := newTestServer()
+	defer s.Close()
+	c := newClientForServer(t, s)
+
+	// need 2 permits and we have 2
+	lim := limiter.NewFixedWindowLimiter(limiter.NewMemoryStorage(), limiter.FixedWindowConfig{Window: time.Minute, Limit: 2})
+	c.SetLimiter(lim, "test-key")
+
+	req, _ := c.NewRequest(context.Background(), http.MethodGet, s.URL+"/api", nil)
+	var out okResp
+	err := c.SendWithAuth(req, &out)
+	assert.NoError(t, err)
+	assert.True(t, out.OK)
+	assert.Equal(t, int32(1), atomic.LoadInt32(tokenHits))
+	assert.Equal(t, int32(1), atomic.LoadInt32(apiHits))
+}
+
+func TestClientLimiter_ConsumesOnePermitWhenTokenAlreadySet(t *testing.T) {
+	s, tokenHits, apiHits := newTestServer()
+	defer s.Close()
+	c := newClientForServer(t, s)
+
+	// set token so we don't need refresh
+	c.SetAccessToken("preset")
+	// allow only 1 permit
+	lim := limiter.NewFixedWindowLimiter(limiter.NewMemoryStorage(), limiter.FixedWindowConfig{Window: time.Minute, Limit: 1})
+	c.SetLimiter(lim, "test-key")
+
+	req, _ := c.NewRequest(context.Background(), http.MethodGet, s.URL+"/api", nil)
+	var out okResp
+	err := c.SendWithAuth(req, &out)
+	assert.NoError(t, err)
+	assert.True(t, out.OK)
+	assert.Equal(t, int32(0), atomic.LoadInt32(*&tokenHits))
+	assert.Equal(t, int32(1), atomic.LoadInt32(apiHits))
+}
+
+func TestClientLimiter_TokenSoonToExpire_ConsumesTwoPermits(t *testing.T) {
+	s, tokenHits, apiHits := newTestServer()
+	defer s.Close()
+	c := newClientForServer(t, s)
+
+	// pre-existing token but expiring soon (< 60s)
+	c.Token = &TokenResponse{Token: "old"}
+	c.tokenExpiresAt = time.Now().Add(5 * time.Second)
+
+	// need 2 permits; provide exactly 2
+	lim := limiter.NewFixedWindowLimiter(limiter.NewMemoryStorage(), limiter.FixedWindowConfig{Window: time.Minute, Limit: 2})
+	c.SetLimiter(lim, "test-key")
+
+	req, _ := c.NewRequest(context.Background(), http.MethodGet, s.URL+"/api", nil)
+	var out okResp
+	err := c.SendWithAuth(req, &out)
+	assert.NoError(t, err)
+	assert.True(t, out.OK)
+	assert.Equal(t, int32(1), atomic.LoadInt32(tokenHits))
+	assert.Equal(t, int32(1), atomic.LoadInt32(apiHits))
+}

types.go

@@ -8,6 +8,9 @@ import (
 	"strings"
 	"sync"
 	"time"
+
+	// add limiter support
+	"github.com/plutov/paypal/v4/limiter"
 )
 
 const (
@@ -646,6 +649,10 @@ type (
 		Token                *TokenResponse
 		tokenExpiresAt       time.Time
 		returnRepresentation bool
+
+		// optional rate limiter; if set, SendWithAuth will check it before making requests
+		rateLimiter    limiter.RateLimiter
+		rateLimiterKey string
 	}
 
 	// CreditCard struct
@@ -1594,7 +1601,7 @@ func (t JSONTime) MarshalJSON() ([]byte, error) {
 	return []byte(stamp), nil
 }
 
-// UnmarshalJSON for JSONTime, timezone offset is missing a colon ':"
+// UnmarshalJSON for JSONTime, timezone offset is missing a colon ':'
 func (t *JSONTime) UnmarshalJSON(b []byte) error {
 	s := strings.Trim(string(b), `"`)
 	nt, err := time.Parse("2006-01-02T15:04:05Z0700", s)