Implement phase 3 SDK enhancements

Author: alxgsv

CHANGELOG.md

@@ -11,6 +11,7 @@ BREAKING CHANGES:
 * Remove `file.OrderBySizeAsc` and `file.OrderBySizeDesc` constants (not supported in v0.7)
 * Remove `APIv05` and `APIv06` constants
 * Minimum Go version is now 1.25
+* Throttled requests no longer retry by default — automatic retries are now opt-in via `ucare.Config.Retry`
 
 FEATURES:
 
@@ -19,12 +20,18 @@ FEATURES:
 * Add `metadata` package with file metadata CRUD operations
 * Add `group.Delete()` for deleting group metadata without deleting files
 * Add webhook event constants for `file.stored`, `file.deleted`, `file.info_updated`, and deprecated `file.infected`
+* Add `ucare.Config.Retry` and `RetryConfig` for configurable throttling retries
+* Add `upload.Service.Upload()` for automatic direct-vs-multipart upload selection
+* Export structured API error types: `APIError`, `AuthError`, `ThrottleError`, `ValidationError`, and `ForbiddenError`
 
 IMPROVEMENTS:
 
 * Add `UserAgent` field to `ucare.Config` for custom agent identification
 * Replace `http.NewRequest` + `WithContext` with `http.NewRequestWithContext`
 * Throttle retry loops now respect context cancellation
+* REST throttling retries now honor `Retry-After` with configurable fail-fast limits and fallback exponential backoff
+* Upload throttling retries now use configurable exponential backoff capping
+* Error values now expose HTTP status details for caller inspection
 * Replace `ioutil` usage with `io` equivalents
 * Replace `go-env` dependency with `os.Getenv`
 * Update `stretchr/testify` to v1.10.0

internal/config/config.go

@@ -19,8 +19,6 @@ const (
 
 	AcceptHeaderFormat = "application/vnd.uploadcare-%s+json"
 
-	MaxThrottleRetries = 3
-
 	UCTimeLayout = "2006-01-02T15:04:05"
 )
 

ucare/client.go

@@ -40,6 +40,9 @@ type Config struct {
 	// UserAgent is appended to the default User-Agent string.
 	// Use this to identify your application (e.g. "my-app/1.0.0").
 	UserAgent string
+	// Retry controls automatic retry of throttled (HTTP 429) requests.
+	// When nil (the default), throttled requests fail immediately.
+	Retry *RetryConfig
 }
 
 // ReqEncoder exists to encode data into the prepared request.

ucare/error.go

@@ -5,7 +5,7 @@ import (
 	"fmt"
 )
 
-// API response errors
+// Sentinel errors for specific conditions
 var (
 	ErrInvalidAuthCreds = errors.New("Incorrect authentication credentials")
 	ErrAuthForbidden    = errors.New("Simple authentication over HTTP is " +
@@ -18,43 +18,50 @@ var (
 		"files smaller than 100MB")
 )
 
-type respErr struct {
-	Details string `json:"detail"`
+// APIError represents a generic API error response.
+// Callers can use errors.As to check for this type as a catch-all
+// for any non-specific API error.
+type APIError struct {
+	StatusCode int    `json:"-"`
+	Detail     string `json:"detail"`
 }
 
-// Error implements error interface
-func (e respErr) Error() string {
-	return e.Details
+func (e APIError) Error() string {
+	return fmt.Sprintf("uploadcare: HTTP %d: %s", e.StatusCode, e.Detail)
 }
 
-type authErr struct{ respErr }
+// AuthError represents an authentication failure (HTTP 401).
+type AuthError struct{ APIError }
 
-type throttleErr struct {
+func (e AuthError) Error() string {
+	return fmt.Sprintf("uploadcare: authentication failed: %s", e.Detail)
+}
+
+// ThrottleError represents a throttled request (HTTP 429).
+type ThrottleError struct {
 	RetryAfter int
 }
 
-func (e throttleErr) Error() string {
+func (e ThrottleError) Error() string {
 	if e.RetryAfter == 0 {
-		return "Request was throttled."
+		return "uploadcare: request throttled"
 	}
 	return fmt.Sprintf(
-		"Request was throttled. Expected available in %d second",
+		"uploadcare: request throttled, retry after %d seconds",
 		e.RetryAfter,
 	)
 }
 
-type reqValidationErr struct{ respErr }
+// ValidationError represents a request validation failure (HTTP 400).
+type ValidationError struct{ APIError }
 
-func (e reqValidationErr) Error() string {
-	return fmt.Sprintf("Request parameters validation error: %s", e.Details)
+func (e ValidationError) Error() string {
+	return fmt.Sprintf("uploadcare: validation error: %s", e.Detail)
 }
 
-type reqForbiddenErr struct{ respErr }
-
-type unexpectedStatusErr struct {
-	StatusCode int
-}
+// ForbiddenError represents a forbidden request (HTTP 403).
+type ForbiddenError struct{ APIError }
 
-func (e unexpectedStatusErr) Error() string {
-	return fmt.Sprintf("unexpected HTTP status: %d", e.StatusCode)
+func (e ForbiddenError) Error() string {
+	return fmt.Sprintf("uploadcare: forbidden: %s", e.Detail)
 }

ucare/error_test.go

@@ -0,0 +1,94 @@
+package ucare
+
+import (
+	"errors"
+	"testing"
+
+	assert "github.com/stretchr/testify/require"
+)
+
+func TestAPIError_Error(t *testing.T) {
+	t.Parallel()
+	err := APIError{StatusCode: 404, Detail: "not found"}
+	assert.Equal(t, "uploadcare: HTTP 404: not found", err.Error())
+}
+
+func TestAuthError_Error(t *testing.T) {
+	t.Parallel()
+	err := AuthError{APIError{StatusCode: 401, Detail: "invalid token"}}
+	assert.Equal(t, "uploadcare: authentication failed: invalid token", err.Error())
+}
+
+func TestThrottleError_Error(t *testing.T) {
+	t.Parallel()
+	err := ThrottleError{RetryAfter: 5}
+	assert.Equal(t, "uploadcare: request throttled, retry after 5 seconds", err.Error())
+}
+
+func TestThrottleError_Error_ZeroRetryAfter(t *testing.T) {
+	t.Parallel()
+	err := ThrottleError{}
+	assert.Equal(t, "uploadcare: request throttled", err.Error())
+}
+
+func TestValidationError_Error(t *testing.T) {
+	t.Parallel()
+	err := ValidationError{APIError{StatusCode: 400, Detail: "bad field"}}
+	assert.Equal(t, "uploadcare: validation error: bad field", err.Error())
+}
+
+func TestForbiddenError_Error(t *testing.T) {
+	t.Parallel()
+	err := ForbiddenError{APIError{StatusCode: 403, Detail: "denied"}}
+	assert.Equal(t, "uploadcare: forbidden: denied", err.Error())
+}
+
+func TestErrorsAs_APIError(t *testing.T) {
+	t.Parallel()
+	var target APIError
+	err := error(APIError{StatusCode: 409, Detail: "conflict"})
+	assert.True(t, errors.As(err, &target))
+	assert.Equal(t, 409, target.StatusCode)
+}
+
+func TestErrorsAs_AuthError(t *testing.T) {
+	t.Parallel()
+	var target AuthError
+	err := error(AuthError{APIError{StatusCode: 401, Detail: "bad creds"}})
+	assert.True(t, errors.As(err, &target))
+	assert.Equal(t, 401, target.StatusCode)
+}
+
+func TestErrorsAs_ThrottleError(t *testing.T) {
+	t.Parallel()
+	var target ThrottleError
+	err := error(ThrottleError{RetryAfter: 10})
+	assert.True(t, errors.As(err, &target))
+	assert.Equal(t, 10, target.RetryAfter)
+}
+
+func TestErrorsAs_AuthError_DoesNotMatchAPIError(t *testing.T) {
+	t.Parallel()
+	var target APIError
+	err := error(AuthError{APIError{StatusCode: 401, Detail: "bad creds"}})
+	// AuthError embeds APIError as a value, not a pointer.
+	// errors.As does not unwrap embedded value types, so this does NOT match.
+	// Callers should check specific types first, then APIError as fallback.
+	assert.False(t, errors.As(err, &target))
+}
+
+func TestErrorsAs_ValidationError(t *testing.T) {
+	t.Parallel()
+	var target ValidationError
+	err := error(ValidationError{APIError{StatusCode: 400, Detail: "bad input"}})
+	assert.True(t, errors.As(err, &target))
+	assert.Equal(t, 400, target.StatusCode)
+}
+
+func TestErrorsAs_ForbiddenError(t *testing.T) {
+	t.Parallel()
+	var target ForbiddenError
+	err := error(ForbiddenError{APIError{StatusCode: 403, Detail: "no"}})
+	assert.True(t, errors.As(err, &target))
+	assert.Equal(t, 403, target.StatusCode)
+}

ucare/restapi.go

@@ -22,7 +22,8 @@ type restAPIClient struct {
 	acceptHeader  string
 	setAuthHeader restAPIAuthFunc
 
-	conn *http.Client
+	conn  *http.Client
+	retry *RetryConfig
 }
 
 func newRESTAPIClient(creds APICreds, conf *Config) Client {
@@ -32,7 +33,8 @@ func newRESTAPIClient(creds APICreds, conf *Config) Client {
 
 		setAuthHeader: simpleRESTAPIAuth,
 
-		conn: conf.HTTPClient,
+		conn:  conf.HTTPClient,
+		retry: conf.Retry,
 	}
 
 	if conf.SignBasedAuthentication {
@@ -131,43 +133,59 @@ func (c *restAPIClient) handleResponse(
 
 	switch resp.StatusCode {
 	case 400, 404:
-		var err respErr
-		if e := json.NewDecoder(resp.Body).Decode(&err); e != nil {
+		var apiErr APIError
+		if e := json.NewDecoder(resp.Body).Decode(&apiErr); e != nil {
 			return false, e
 		}
-		return false, err
+		apiErr.StatusCode = resp.StatusCode
+		return false, apiErr
 	case 401:
-		var err authErr
-		if e := json.NewDecoder(resp.Body).Decode(&err); e != nil {
+		var authErr AuthError
+		if e := json.NewDecoder(resp.Body).Decode(&authErr); e != nil {
 			return false, e
 		}
-		return false, err
+		authErr.StatusCode = 401
+		return false, authErr
+	case 403:
+		var forbiddenErr ForbiddenError
+		if e := json.NewDecoder(resp.Body).Decode(&forbiddenErr); e != nil {
+			return false, e
+		}
+		forbiddenErr.StatusCode = 403
+		return false, forbiddenErr
 	case 406:
 		return false, ErrInvalidVersion
 	case 429:
 		retryAfter, err := strconv.Atoi(
 			resp.Header.Get("Retry-After"),
 		)
 		if err != nil {
-			return false, fmt.Errorf("invalid Retry-After: %w", err)
+			retryAfter = 0
 		}
-
-		if tries > config.MaxThrottleRetries {
-			return false, throttleErr{retryAfter}
+		if c.retry == nil || tries > c.retry.MaxRetries {
+			return false, ThrottleError{RetryAfter: retryAfter}
+		}
+		if c.retry.MaxWaitSeconds > 0 &&
+			retryAfter > c.retry.MaxWaitSeconds {
+			return false, ThrottleError{RetryAfter: retryAfter}
+		}
+		wait := retryAfter
+		if wait <= 0 {
+			wait = expBackoff(tries)
 		}
-
 		select {
 		case <-req.Context().Done():
 			return false, req.Context().Err()
-		case <-time.After(time.Duration(retryAfter) * time.Second):
+		case <-time.After(time.Duration(wait) * time.Second):
 		}
 		return true, nil
 	default:
 		if resp.StatusCode >= 400 {
-			var apiErr respErr
-			if e := json.NewDecoder(resp.Body).Decode(&apiErr); e != nil || apiErr.Details == "" {
-				return false, unexpectedStatusErr{StatusCode: resp.StatusCode}
+			var apiErr APIError
+			if e := json.NewDecoder(resp.Body).Decode(&apiErr); e != nil || apiErr.Detail == "" {
+				apiErr.Detail = http.StatusText(resp.StatusCode)
 			}
+			apiErr.StatusCode = resp.StatusCode
 			return false, apiErr
 		}
 	}