Helper Functions & building Blocks (#30)

Author: Dean Karn

.github/workflows/go.yml

@@ -29,11 +29,8 @@ jobs:
           restore-keys: |
             ${{ runner.os }}-v1-go-
 
-      - name: Checkout code
-        uses: actions/checkout@v3
-
       - name: Test
-        run: go test ./...
+        run: go test -race -cover ./...
 
   golangci:
     name: lint

CHANGELOG.md

@@ -6,6 +6,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [5.17.0] - 2023-05-08
+### Added
+- bytesext.Bytes alias to int64 for better code clarity.
+- errorext.DoRetryable(...) building block for automating retryable errors.
+- sqlext.DoTransaction(...) building block for abstracting away transactions.
+- httpext.DoRetryableResponse(...) & httpext.DoRetryable(...) building blocks for automating retryable http requests.
+- httpext.DecodeResponse(...) building block for decoding http responses.
+- httpext.ErrRetryableStatusCode error for retryable http status code detection and handling.
+- errorsext.ErrMaxAttemptsReached error for retryable retryable logic & reuse.
+
 ## [5.16.0] - 2023-04-16
 ### Added
 - sliceext.Reverse(...)
@@ -27,7 +37,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 - Added `timext.NanoTime` for fast low level monotonic time with nanosecond precision.
 
-[Unreleased]: https://github.com/go-playground/pkg/compare/v5.16.0...HEAD
+[Unreleased]: https://github.com/go-playground/pkg/compare/v5.17.0...HEAD
+[5.17.0]: https://github.com/go-playground/pkg/compare/v5.16.0...v5.17.0
 [5.16.0]: https://github.com/go-playground/pkg/compare/v5.15.2...v5.16.0
 [5.15.2]: https://github.com/go-playground/pkg/compare/v5.15.1...v5.15.2
 [5.15.1]: https://github.com/go-playground/pkg/compare/v5.15.0...v5.15.1

README.md

@@ -1,7 +1,7 @@
 # pkg
 
-![Project status](https://img.shields.io/badge/version-5.16.0-green.svg)
-[![Build Status](https://travis-ci.org/go-playground/pkg.svg?branch=master)](https://travis-ci.org/go-playground/pkg)
+![Project status](https://img.shields.io/badge/version-5.17.0-green.svg)
+[![Lint & Test](https://github.com/go-playground/pkg/actions/workflows/go.yml/badge.svg)](https://github.com/go-playground/pkg/actions/workflows/go.yml)
 [![Coverage Status](https://coveralls.io/repos/github/go-playground/pkg/badge.svg?branch=master)](https://coveralls.io/github/go-playground/pkg?branch=master)
 [![GoDoc](https://godoc.org/github.com/go-playground/pkg?status.svg)](https://pkg.go.dev/mod/github.com/go-playground/pkg/v5)
 ![License](https://img.shields.io/dub/l/vibe-d.svg)

bytes/size.go

@@ -1,5 +1,8 @@
 package bytesext
 
+// Bytes is a type alias to int64 in order to better express the desired data type.
+type Bytes = int64
+
 // Common byte unit sizes
 const (
 	BYTE = 1

database/sql/transaction.go

@@ -0,0 +1,28 @@
+//go:build go1.18
+// +build go1.18
+
+package sqlext
+
+import (
+	"context"
+	"database/sql"
+	resultext "github.com/go-playground/pkg/v5/values/result"
+)
+
+// DoTransaction is a helper function that abstracts some complexities of dealing with a transaction and rolling it back.
+func DoTransaction[T any](ctx context.Context, opts *sql.TxOptions, conn *sql.DB, fn func(context.Context, *sql.Tx) resultext.Result[T, error]) resultext.Result[T, error] {
+	tx, err := conn.BeginTx(ctx, opts)
+	if err != nil {
+		return resultext.Err[T, error](err)
+	}
+	result := fn(ctx, tx)
+	if result.IsErr() {
+		_ = tx.Rollback()
+		return result
+	}
+	err = tx.Commit()
+	if err != nil {
+		return resultext.Err[T, error](err)
+	}
+	return result
+}

errors/do.go

@@ -0,0 +1,40 @@
+//go:build go1.18
+// +build go1.18
+
+package errorsext
+
+import (
+	"context"
+	optionext "github.com/go-playground/pkg/v5/values/option"
+	resultext "github.com/go-playground/pkg/v5/values/result"
+)
+
+// RetryableFn is a function that can be retried.
+type RetryableFn[T, E any] func(ctx context.Context) resultext.Result[T, E]
+
+// IsRetryableFn is called to determine if the error is retryable and optionally returns the reason for logging and metrics.
+type IsRetryableFn[E any] func(err E) (reason string, isRetryable bool)
+
+// OnRetryFn is called after IsRetryableFn returns true and before the retry is attempted.
+//
+// this allows for interception, short-circuiting and adding of backoff strategies.
+type OnRetryFn[E any] func(ctx context.Context, originalErr E, reason string, attempt int) optionext.Option[E]
+
+// DoRetryable will execute the provided functions code and automatically retry using the provided retry function.
+func DoRetryable[T, E any](ctx context.Context, isRetryFn IsRetryableFn[E], onRetryFn OnRetryFn[E], fn RetryableFn[T, E]) resultext.Result[T, E] {
+	var attempt int
+	for {
+		result := fn(ctx)
+		if result.IsErr() {
+			err := result.Err()
+			if reason, isRetryable := isRetryFn(err); isRetryable {
+				if opt := onRetryFn(ctx, err, reason, attempt); opt.IsSome() {
+					return resultext.Err[T, E](opt.Unwrap())
+				}
+				attempt++
+				continue
+			}
+		}
+		return result
+	}
+}

errors/retryable.go

@@ -6,6 +6,12 @@ import (
 	"syscall"
 )
 
+var (
+	// ErrMaxAttemptsReached is a placeholder error to use when some retryable even has reached its maximum number of
+	// attempts.
+	ErrMaxAttemptsReached = errors.New("max attempts reached")
+)
+
 // IsRetryableHTTP returns if the provided error is considered retryable HTTP error. It also returns the
 // type, in string form, for optional logging and metrics use.
 func IsRetryableHTTP(err error) (retryType string, isRetryable bool) {

net/http/helpers.go

@@ -8,6 +8,7 @@ import (
 	"mime"
 	"net"
 	"net/http"
+	"net/url"
 	"path/filepath"
 	"strings"
 
@@ -102,11 +103,9 @@ func ClientIP(r *http.Request) (clientIP string) {
 	return
 }
 
-//
 // JSONStream uses json.Encoder to stream the JSON reponse body.
 //
 // This differs from the JSON helper which unmarshalls into memory first allowing the capture of JSON encoding errors.
-//
 func JSONStream(w http.ResponseWriter, status int, i interface{}) error {
 	w.Header().Set(ContentType, ApplicationJSON)
 	w.WriteHeader(status)
@@ -218,10 +217,17 @@ func DecodeMultipartForm(r *http.Request, qp QueryParamsOption, maxMemory int64,
 // NOTE: when includeQueryParams=true query params will be parsed and included eg. route /user?test=true 'test'
 // is added to parsed JSON and replaces any values that may have been present
 func DecodeJSON(r *http.Request, qp QueryParamsOption, maxMemory int64, v interface{}) (err error) {
-	var body io.Reader = r.Body
-	if encoding := r.Header.Get(ContentEncoding); encoding == Gzip {
+	var values url.Values
+	if qp == QueryParams {
+		values = r.URL.Query()
+	}
+	return decodeJSON(r.Header, r.Body, qp, values, maxMemory, v)
+}
+
+func decodeJSON(headers http.Header, body io.Reader, qp QueryParamsOption, values url.Values, maxMemory int64, v interface{}) (err error) {
+	if encoding := headers.Get(ContentEncoding); encoding == Gzip {
 		var gzr *gzip.Reader
-		gzr, err = gzip.NewReader(r.Body)
+		gzr, err = gzip.NewReader(body)
 		if err != nil {
 			return
 		}
@@ -232,7 +238,7 @@ func DecodeJSON(r *http.Request, qp QueryParamsOption, maxMemory int64, v interf
 	}
 	err = json.NewDecoder(ioext.LimitReader(body, maxMemory)).Decode(v)
 	if qp == QueryParams && err == nil {
-		err = DecodeQueryParams(r, v)
+		err = decodeQueryParams(values, v)
 	}
 	return
 }
@@ -245,10 +251,17 @@ func DecodeJSON(r *http.Request, qp QueryParamsOption, maxMemory int64, v interf
 // NOTE: when includeQueryParams=true query params will be parsed and included eg. route /user?test=true 'test'
 // is added to parsed XML and replaces any values that may have been present
 func DecodeXML(r *http.Request, qp QueryParamsOption, maxMemory int64, v interface{}) (err error) {
-	var body io.Reader = r.Body
-	if encoding := r.Header.Get(ContentEncoding); encoding == Gzip {
+	var values url.Values
+	if qp == QueryParams {
+		values = r.URL.Query()
+	}
+	return decodeXML(r.Header, r.Body, qp, values, maxMemory, v)
+}
+
+func decodeXML(headers http.Header, body io.Reader, qp QueryParamsOption, values url.Values, maxMemory int64, v interface{}) (err error) {
+	if encoding := headers.Get(ContentEncoding); encoding == Gzip {
 		var gzr *gzip.Reader
-		gzr, err = gzip.NewReader(r.Body)
+		gzr, err = gzip.NewReader(body)
 		if err != nil {
 			return
 		}
@@ -259,14 +272,18 @@ func DecodeXML(r *http.Request, qp QueryParamsOption, maxMemory int64, v interfa
 	}
 	err = xml.NewDecoder(ioext.LimitReader(body, maxMemory)).Decode(v)
 	if qp == QueryParams && err == nil {
-		err = DecodeQueryParams(r, v)
+		err = decodeQueryParams(values, v)
 	}
 	return
 }
 
 // DecodeQueryParams takes the URL Query params flag.
 func DecodeQueryParams(r *http.Request, v interface{}) (err error) {
-	err = DefaultFormDecoder.Decode(v, r.URL.Query())
+	return decodeQueryParams(r.URL.Query(), v)
+}
+
+func decodeQueryParams(values url.Values, v interface{}) (err error) {
+	err = DefaultFormDecoder.Decode(v, values)
 	return
 }
 
@@ -275,7 +292,7 @@ const (
 	nakedApplicationXML  string = "application/xml"
 )
 
-// Decode takes the request and attempts to discover it's content type via
+// Decode takes the request and attempts to discover its content type via
 // the http headers and then decode the request body into the provided struct.
 // Example if header was "application/json" would decode using
 // json.NewDecoder(ioext.LimitReader(r.Body, maxMemory)).Decode(v).

net/http/helpers_go1.18.go

@@ -0,0 +1,32 @@
+//go:build go1.18
+// +build go1.18
+
+package httpext
+
+import (
+	"errors"
+	bytesext "github.com/go-playground/pkg/v5/bytes"
+	"net/http"
+	"strings"
+)
+
+// DecodeResponse takes the response and attempts to discover its content type via
+// the http headers and then decode the request body into the provided type.
+//
+// Example if header was "application/json" would decode using
+// json.NewDecoder(ioext.LimitReader(r.Body, maxMemory)).Decode(v).
+func DecodeResponse[T any](r *http.Response, maxMemory bytesext.Bytes) (result T, err error) {
+	typ := r.Header.Get(ContentType)
+	if idx := strings.Index(typ, ";"); idx != -1 {
+		typ = typ[:idx]
+	}
+	switch typ {
+	case nakedApplicationJSON:
+		err = decodeJSON(r.Header, r.Body, NoQueryParams, nil, maxMemory, &result)
+	case nakedApplicationXML:
+		err = decodeXML(r.Header, r.Body, NoQueryParams, nil, maxMemory, &result)
+	default:
+		err = errors.New("unsupported content type")
+	}
+	return
+}

net/http/helpers_test_go1.18.go

@@ -0,0 +1,62 @@
+//go:build go1.18
+// +build go1.18
+
+package httpext
+
+import (
+	. "github.com/go-playground/assert/v2"
+	bytesext "github.com/go-playground/pkg/v5/bytes"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+)
+
+func TestDecodeResponse(t *testing.T) {
+
+	type result struct {
+		ID int `json:"id" xml:"id"`
+	}
+
+	tests := []struct {
+		name     string
+		handler  http.HandlerFunc
+		expected result
+	}{
+		{
+			name: "Test JSON",
+			handler: func(w http.ResponseWriter, r *http.Request) {
+				Equal(t, JSON(w, http.StatusOK, result{ID: 3}), nil)
+			},
+			expected: result{ID: 3},
+		},
+		{
+			name: "Test XML",
+			handler: func(w http.ResponseWriter, r *http.Request) {
+				Equal(t, XML(w, http.StatusOK, result{ID: 5}), nil)
+			},
+			expected: result{ID: 5},
+		},
+	}
+
+	for _, tc := range tests {
+		tc := tc
+		t.Run(tc.name, func(t *testing.T) {
+			mux := http.NewServeMux()
+			mux.HandleFunc("/", tc.handler)
+
+			server := httptest.NewServer(mux)
+			defer server.Close()
+
+			req, err := http.NewRequest(http.MethodGet, server.URL, nil)
+			Equal(t, err, nil)
+
+			resp, err := http.DefaultClient.Do(req)
+			Equal(t, err, nil)
+			Equal(t, resp.StatusCode, http.StatusOK)
+
+			res, err := DecodeResponse[result](resp, bytesext.MiB)
+			Equal(t, err, nil)
+			Equal(t, tc.expected.ID, res.ID)
+		})
+	}
+}