Merge pull request #215 from VictorAvelar/feature/idempotency-key-sup…

…port

.devcontainer/devcontainer.json

@@ -47,7 +47,7 @@
             ""
           ],
           "formatting.gofumpt": true,
-          "ui.completion.usePlaceholders": true,
+          "ui.completion.usePlaceholders": false,
           "ui.diagnostic.staticcheck": true,
           "ui.semanticTokens": true
         },

.github/labeler.yml

@@ -1,5 +1,5 @@
 tests:
-  - any: ["mollie/*_tests.go", "mollie/connect/*_tests.go"]
+  - any: ["mollie/*_test.go", "mollie/connect/*_test.go", "mollie/tools/*_test.go"]
 
 documentation:
   - docs/*
@@ -11,7 +11,7 @@ gh-actions:
   - .github/**/*.yml
 
 core:
-  - any: ["mollie/*.go", "!mollie/*_tests.go"]
+  - any: ["mollie/*.go", "!mollie/*_tests.go", "!mollie/tools/*"]
 
 modules:
   - go.*  
@@ -24,3 +24,6 @@ config:
 
 meta-files:
   - any: ["Makefile", "README.md", "LICENSE", "SECURITY.md"]
+
+tools:
+  - any: ["mollie/tools/*.go"]

Makefile

@@ -53,3 +53,9 @@ clean:
 update-docs:
 	@godocdown ./mollie > docs/README.md 
 .PHONY: update-docs 
+
+sub-pkg-docs:
+	@godocdown ./mollie/connect > docs/connect/README.md
+	@godocdown ./mollie/tools > docs/tools/README.md
+	@godocdown ./mollie/tools/idempotency > docs/tools/idempotency/README.md
+.PHONY: sub-pkg-docs

docs/README.md

@@ -21,12 +21,13 @@ the name of the resource you want to interact with.
 
 ```go
 const (
- BaseURL            string = "https://api.mollie.com/"
- AuthHeader         string = "Authorization"
- TokenType          string = "Bearer"
- APITokenEnv        string = "MOLLIE_API_TOKEN"
- OrgTokenEnv        string = "MOLLIE_ORG_TOKEN"
- RequestContentType string = "application/json"
+ BaseURL              string = "https://api.mollie.com/"
+ AuthHeader           string = "Authorization"
+ TokenType            string = "Bearer"
+ APITokenEnv          string = "MOLLIE_API_TOKEN"
+ OrgTokenEnv          string = "MOLLIE_ORG_TOKEN"
+ RequestContentType   string = "application/json"
+ IdempotencyKeyHeader string = "Idempotency-Key"
 )
 ```
 
@@ -471,6 +472,15 @@ NewAPIRequest is a wrapper around the http.NewRequest function.
 It will setup the authentication headers/parameters according to the client
 config.
 
+#### func (*Client) SetIdempotencyKeyGenerator
+
+```go
+func (c *Client) SetIdempotencyKeyGenerator(kg idempotency.KeyGenerator)
+```
+
+SetIdempotencyKeyGenerator allows you to pass your own idempotency key
+generator.
+
 #### func (*Client) WithAuthenticationValue
 
 ```go
@@ -507,12 +517,13 @@ Config contains information that helps during the setup of a new Mollie client.
 #### func  NewConfig
 
 ```go
-func NewConfig(t bool, auth string) *Config
+func NewConfig(t, reqIdem bool, auth string) *Config
 ```
 
 NewConfig builds a Mollie configuration object, it takes t to indicate if our
-client is meant to create requests for testing and auth to indicate the
-authentication method we want to use.
+client is meant to create requests for testing, reqIdem to enable the request
+idempotency beta feature, and auth to indicate the authentication method we want
+to use.
 
 #### type CreateShipmentRequest
 

docs/connect/README.md

@@ -0,0 +1,14 @@
+# connect
+
+--
+    import "github.com/VictorAvelar/mollie-api-go/v3/mollie/connect"
+
+## Usage
+
+#### func  OauthEndpoint
+
+```go
+func OauthEndpoint() *oauth2.Endpoint
+```
+
+OauthEndpoint is Mollies's OAuth 2.0 endpoint.

docs/tools/README.md

@@ -0,0 +1,9 @@
+# tools
+
+--
+    import "github.com/VictorAvelar/mollie-api-go/v3/mollie/tools"
+
+package tools provides some common tools required by mollie's features in order
+to maximize the library utility.
+
+## Usage

docs/tools/idempotency/README.md

@@ -0,0 +1,61 @@
+# idempotency
+
+--
+    import "github.com/VictorAvelar/mollie-api-go/v3/mollie/tools/idempotency"
+
+package idempotency contains the services in charge of generating a unique keys
+to be passed in POST requests to ensure operation uniqueness.
+
+See: <https://docs.mollie.com/overview/api-idempotency>
+
+The std generator uses google's uuid library to return a new uuid as unique
+idempotency key.
+
+You can build your own generator and pass it to the library by implementing the
+KeyGenerator interface.
+
+## Usage
+
+```go
+const (
+ TestKeyExpected = "test_ikg_key"
+)
+```
+
+#### type KeyGenerator
+
+```go
+type KeyGenerator interface {
+ // Generate encapsulates the logic to return a string representation of
+ // a unique idempotency key.
+ Generate() string
+}
+```
+
+KeyGenerator describes the service in charge of generating a unique idempotency
+key to be passed in POST requests to ensure operation uniqueness.
+
+See: <https://docs.mollie.com/overview/api-idempotency>
+
+#### func  NewNopGenerator
+
+```go
+func NewNopGenerator(exp string) KeyGenerator
+```
+
+NewNopGenerator returns a dummy implementation of the IdempotencyKeyGenerator
+interface.
+
+Good for testing or when a predictable result is required.
+
+If exp is an empty string, then TestKeyExpected is used as default value for the
+NOpGenerator.
+
+#### func  NewStdGenerator
+
+```go
+func NewStdGenerator() KeyGenerator
+```
+
+NewStdGenerator returns an standard and common way of generating idempotency
+unique keys.

go.mod

@@ -11,6 +11,7 @@ require (
 require (
 	github.com/davecgh/go-spew v1.1.1 // indirect
 	github.com/golang/protobuf v1.5.2 // indirect
+	github.com/google/uuid v1.3.0 // indirect
 	github.com/kr/pretty v0.1.0 // indirect
 	github.com/pmezard/go-difflib v1.0.0 // indirect
 	golang.org/x/net v0.3.0 // indirect

go.sum

@@ -12,6 +12,8 @@ github.com/google/go-cmp v0.5.8 h1:e6P7q2lk1O+qJJb4BtCQXlK8vWEO8V1ZeuEdJNOqZyg=
 github.com/google/go-cmp v0.5.8/go.mod h1:17dUlkBOakJ0+DkrSSNjCkIjxS6bF9zb3elmeNGIjoY=
 github.com/google/go-querystring v1.1.0 h1:AnCroh3fv4ZBgVIf1Iwtovgjaw/GiKJo8M8yD/fhyJ8=
 github.com/google/go-querystring v1.1.0/go.mod h1:Kcdr2DB4koayq7X8pmAG4sNG59So17icRSOU623lUBU=
+github.com/google/uuid v1.3.0 h1:t6JiXgmwXMjEs8VusXIJk2BXHsn+wx8BZdTaoZ5fu7I=
+github.com/google/uuid v1.3.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
 github.com/kr/pretty v0.1.0 h1:L/CwN0zerZDmRFUapSPitk6f+Q3+0za1rQkzVuMiMFI=
 github.com/kr/pretty v0.1.0/go.mod h1:dAy3ld7l9f0ibDNOQOHHMYYIIbhfbHSm3C4ZsoJORNo=
 github.com/kr/pty v1.1.1/go.mod h1:pFQYn66WHrOpPYNljwOMqo10TkYh1fy3cYio2l3bCsQ=

mollie/config.go

@@ -2,16 +2,19 @@ package mollie
 
 // Config contains information that helps during the setup of a new Mollie client.
 type Config struct {
-	testing bool
-	auth    string
+	testing        bool
+	auth           string
+	reqIdempotency bool
 }
 
 // NewConfig builds a Mollie configuration object,
-// it takes t to indicate if our client is meant to create requests for testing
+// it takes t to indicate if our client is meant to create requests for testing,
+// reqIdem to enable the request idempotency beta feature,
 // and auth to indicate the authentication method we want to use.
-func NewConfig(t bool, auth string) *Config {
+func NewConfig(t, reqIdem bool, auth string) *Config {
 	return &Config{
-		testing: t,
-		auth:    auth,
+		testing:        t,
+		auth:           auth,
+		reqIdempotency: reqIdem,
 	}
 }

mollie/config_test.go

@@ -1,6 +1,7 @@
 package mollie
 
 import (
+	"fmt"
 	"testing"
 
 	"github.com/stretchr/testify/assert"
@@ -9,6 +10,7 @@ import (
 func TestNewConfig(t *testing.T) {
 	type args struct {
 		t    bool
+		ikg  bool
 		auth string
 	}
 	tests := []struct {
@@ -63,8 +65,13 @@ func TestNewConfig(t *testing.T) {
 	}
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
-			got := NewConfig(tt.args.t, tt.args.auth)
+			got := NewConfig(tt.args.t, tt.args.ikg, tt.args.auth)
 			assert.Equal(t, got, tt.want)
 		})
 	}
 }
+
+func ExampleNewConfig() {
+	fmt.Println(NewConfig(true, true, APITokenEnv))
+	// Output: &{true MOLLIE_API_TOKEN true}
+}

mollie/mollie.go

@@ -14,17 +14,19 @@ import (
 	"runtime"
 	"strings"
 
+	"github.com/VictorAvelar/mollie-api-go/v3/mollie/tools/idempotency"
 	"github.com/google/go-querystring/query"
 )
 
 // Constants holding values for client initialization and request instantiation.
 const (
-	BaseURL            string = "https://api.mollie.com/"
-	AuthHeader         string = "Authorization"
-	TokenType          string = "Bearer"
-	APITokenEnv        string = "MOLLIE_API_TOKEN"
-	OrgTokenEnv        string = "MOLLIE_ORG_TOKEN"
-	RequestContentType string = "application/json"
+	BaseURL              string = "https://api.mollie.com/"
+	AuthHeader           string = "Authorization"
+	TokenType            string = "Bearer"
+	APITokenEnv          string = "MOLLIE_API_TOKEN"
+	OrgTokenEnv          string = "MOLLIE_ORG_TOKEN"
+	RequestContentType   string = "application/json"
+	IdempotencyKeyHeader string = "Idempotency-Key"
 )
 
 var (
@@ -41,6 +43,8 @@ type Client struct {
 	client         *http.Client
 	common         service // Reuse a single struct instead of allocating one for each service on the heap.
 	config         *Config
+	// Tools
+	idempotencyKeyProvider idempotency.KeyGenerator
 	// Services
 	Payments       *PaymentsService
 	Chargebacks    *ChargebacksService
@@ -148,6 +152,12 @@ func (c *Client) HasAccessToken() bool {
 	return accessTokenExpr.Match([]byte(c.authentication))
 }
 
+// SetIdempotencyKeyGenerator allows you to pass your own idempotency
+// key generator.
+func (c *Client) SetIdempotencyKeyGenerator(kg idempotency.KeyGenerator) {
+	c.idempotencyKeyProvider = kg
+}
+
 // NewAPIRequest is a wrapper around the http.NewRequest function.
 //
 // It will setup the authentication headers/parameters according to the client config.
@@ -193,6 +203,10 @@ func (c *Client) NewAPIRequest(ctx context.Context, method string, uri string, b
 	req.Header.Set("Accept", RequestContentType)
 	req.Header.Set("User-Agent", c.userAgent)
 
+	if c.config.reqIdempotency && c.idempotencyKeyProvider != nil && req.Method == http.MethodPost {
+		req.Header.Set(IdempotencyKeyHeader, c.idempotencyKeyProvider.Generate())
+	}
+
 	return
 }
 
@@ -236,13 +250,18 @@ func NewClient(baseClient *http.Client, conf *Config) (mollie *Client, err error
 	uri, _ := url.Parse(BaseURL)
 
 	mollie = &Client{
-		BaseURL: uri,
-		client:  baseClient,
-		config:  conf,
+		BaseURL:                uri,
+		client:                 baseClient,
+		config:                 conf,
+		idempotencyKeyProvider: nil,
 	}
 
 	mollie.common.client = mollie
 
+	if mollie.config.reqIdempotency {
+		mollie.common.client.idempotencyKeyProvider = idempotency.NewStdGenerator()
+	}
+
 	// services for resources
 	mollie.Payments = (*PaymentsService)(&mollie.common)
 	mollie.Chargebacks = (*ChargebacksService)(&mollie.common)