Added pkg/app/version.go and examples, changelog, and go.mod

CHANGELOG.md

@@ -0,0 +1,19 @@
+# Wharf core library changelog
+
+This project tries to follow [SemVer 2.0.0](https://semver.org/).
+
+<!--
+	When composing new changes to this list, try to follow convention.
+
+	The WIP release shall be updated just before adding the Git tag.
+	From (WIP) to (YYYY-MM-DD), ex: (2021-02-09) for 9th of Febuary, 2021
+
+	A good source on conventions can be found here:
+	https://changelog.md/
+-->
+
+## v1.0.0 (WIP)
+
+- Added `pkg/app` with newly added `app.Version` struct together with an example
+  of how to use with [gin-gonic/gin](https://github.com/gin-gonic/gin).
+	Use this for versioning your built APIs and command-line programs. (#2)

go.mod

@@ -0,0 +1,8 @@
+module github.com/iver-wharf/wharf-core
+
+go 1.16
+
+require (
+	github.com/gin-gonic/gin v1.7.1
+	gopkg.in/yaml.v2 v2.4.0
+)

go.sum

@@ -0,0 +1,55 @@
+github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
+github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/gin-contrib/sse v0.1.0 h1:Y/yl/+YNO8GZSjAhjMsSuLt29uWRFHdHYUb5lYOV9qE=
+github.com/gin-contrib/sse v0.1.0/go.mod h1:RHrZQHXnP2xjPF+u1gW/2HnVO7nvIa9PG3Gm+fLHvGI=
+github.com/gin-gonic/gin v1.7.1 h1:qC89GU3p8TvKWMAVhEpmpB2CIb1hnqt2UdKZaP93mS8=
+github.com/gin-gonic/gin v1.7.1/go.mod h1:jD2toBW3GZUr5UMcdrwQA10I7RuaFOl/SGeDjXkfUtY=
+github.com/go-playground/assert/v2 v2.0.1 h1:MsBgLAaY856+nPRTKrp3/OZK38U/wa0CcBYNjji3q3A=
+github.com/go-playground/assert/v2 v2.0.1/go.mod h1:VDjEfimB/XKnb+ZQfWdccd7VUvScMdVu0Titje2rxJ4=
+github.com/go-playground/locales v0.13.0 h1:HyWk6mgj5qFqCT5fjGBuRArbVDfE4hi8+e8ceBS/t7Q=
+github.com/go-playground/locales v0.13.0/go.mod h1:taPMhCMXrRLJO55olJkUXHZBHCxTMfnGwq/HNwmWNS8=
+github.com/go-playground/universal-translator v0.17.0 h1:icxd5fm+REJzpZx7ZfpaD876Lmtgy7VtROAbHHXk8no=
+github.com/go-playground/universal-translator v0.17.0/go.mod h1:UkSxE5sNxxRwHyU+Scu5vgOQjsIJAF8j9muTVoKLVtA=
+github.com/go-playground/validator/v10 v10.4.1 h1:pH2c5ADXtd66mxoE0Zm9SUhxE20r7aM3F26W0hOn+GE=
+github.com/go-playground/validator/v10 v10.4.1/go.mod h1:nlOn6nFhuKACm19sB/8EGNn9GlaMV7XkbRSipzJ0Ii4=
+github.com/golang/protobuf v1.3.3 h1:gyjaxf+svBWX08ZjK86iN9geUJF0H6gp2IRKX6Nf6/I=
+github.com/golang/protobuf v1.3.3/go.mod h1:vzj43D7+SQXF/4pzW/hwtAqwc6iTitCiVSaWz5lYuqw=
+github.com/google/gofuzz v1.0.0/go.mod h1:dBl0BpW6vV/+mYPU4Po3pmUjxk6FQPldtuIdl/M65Eg=
+github.com/json-iterator/go v1.1.9 h1:9yzud/Ht36ygwatGx56VwCZtlI/2AD15T1X2sjSuGns=
+github.com/json-iterator/go v1.1.9/go.mod h1:KdQUCv79m/52Kvf8AW2vK1V8akMuk1QjK/uOdHXbAo4=
+github.com/leodido/go-urn v1.2.0 h1:hpXL4XnriNwQ/ABnpepYM/1vCLWNDfUNts8dX3xTG6Y=
+github.com/leodido/go-urn v1.2.0/go.mod h1:+8+nEpDfqqsY+g338gtMEUOtuK+4dEMhiQEgxpxOKII=
+github.com/mattn/go-isatty v0.0.12 h1:wuysRhFDzyxgEmMf5xjvJ2M9dZoWAXNNr5LSBS7uHXY=
+github.com/mattn/go-isatty v0.0.12/go.mod h1:cbi8OIDigv2wuxKPP5vlRcQ1OAZbq2CE4Kysco4FUpU=
+github.com/modern-go/concurrent v0.0.0-20180228061459-e0a39a4cb421 h1:ZqeYNhU3OHLH3mGKHDcjJRFFRrJa6eAM5H+CtDdOsPc=
+github.com/modern-go/concurrent v0.0.0-20180228061459-e0a39a4cb421/go.mod h1:6dJC0mAP4ikYIbvyc7fijjWJddQyLn8Ig3JB5CqoB9Q=
+github.com/modern-go/reflect2 v0.0.0-20180701023420-4b7aa43c6742 h1:Esafd1046DLDQ0W1YjYsBW+p8U2u7vzgW2SQVmlNazg=
+github.com/modern-go/reflect2 v0.0.0-20180701023420-4b7aa43c6742/go.mod h1:bx2lNnkwVCuqBIxFjflWJWanXIb3RllmbCylyMrvgv0=
+github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
+github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
+github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
+github.com/stretchr/testify v1.3.0/go.mod h1:M5WIy9Dh21IEIfnGCwXGc5bZfKNJtfHm1UVUgZn+9EI=
+github.com/stretchr/testify v1.4.0 h1:2E4SXV/wtOkTonXsotYi4li6zVWxYlZuYNCXe9XRJyk=
+github.com/stretchr/testify v1.4.0/go.mod h1:j7eGeouHqKxXV5pUuKE4zz7dFj8WfuZ+81PSLYec5m4=
+github.com/ugorji/go v1.1.7 h1:/68gy2h+1mWMrwZFeD1kQialdSzAb432dtpeJ42ovdo=
+github.com/ugorji/go v1.1.7/go.mod h1:kZn38zHttfInRq0xu/PH0az30d+z6vm202qpg1oXVMw=
+github.com/ugorji/go/codec v1.1.7 h1:2SvQaVZ1ouYrrKKwoSk2pzd4A9evlKJb9oTL+OaLUSs=
+github.com/ugorji/go/codec v1.1.7/go.mod h1:Ax+UKWsSmolVDwsd+7N3ZtXu+yMGCf907BLYF3GoBXY=
+golang.org/x/crypto v0.0.0-20190308221718-c2843e01d9a2/go.mod h1:djNgcEr1/C05ACkg1iLfiJU5Ep61QUkGW8qpdssI0+w=
+golang.org/x/crypto v0.0.0-20200622213623-75b288015ac9 h1:psW17arqaxU48Z5kZ0CQnkZWQJsqcURM6tKiBApRjXI=
+golang.org/x/crypto v0.0.0-20200622213623-75b288015ac9/go.mod h1:LzIPMQfyMNhhGPhUkYOs5KpL4U8rLKemX1yGLhDgUto=
+golang.org/x/net v0.0.0-20190404232315-eb5bcb51f2a3/go.mod h1:t9HGtf8HONx5eT2rtn7q6eTqICYqUVnKs3thJo3Qplg=
+golang.org/x/sys v0.0.0-20190215142949-d0b11bdaac8a/go.mod h1:STP8DvDyc/dI5b8T5hshtkjS+E42TnysNCUPdjciGhY=
+golang.org/x/sys v0.0.0-20190412213103-97732733099d/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
+golang.org/x/sys v0.0.0-20200116001909-b77594299b42 h1:vEOn+mP2zCOVzKckCZy6YsCtDblrpj/w7B9nxGNELpg=
+golang.org/x/sys v0.0.0-20200116001909-b77594299b42/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
+golang.org/x/text v0.3.0/go.mod h1:NqM8EUOU14njkJ3fqMW+pc6Ldnwhi/IjpwHt7yyuwOQ=
+golang.org/x/text v0.3.2/go.mod h1:bEr9sfX3Q8Zfm5fL9x+3itogRgK3+ptLWKqgva+5dAk=
+golang.org/x/tools v0.0.0-20180917221912-90fa682c2a6e/go.mod h1:n7NCudcB/nEzxVGmLbDWY5pfWTLqBcC2KZ6jyYvM4mQ=
+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405 h1:yhCVgyC4o1eVCa2tZl7eS0r+SDo693bJlVdllGtEeKM=
+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
+gopkg.in/yaml.v2 v2.2.2/go.mod h1:hI93XBmqTisBFMUTm0b8Fm+jr3Dg1NNxqwp+5A1VGuI=
+gopkg.in/yaml.v2 v2.2.8/go.mod h1:hI93XBmqTisBFMUTm0b8Fm+jr3Dg1NNxqwp+5A1VGuI=
+gopkg.in/yaml.v2 v2.4.0 h1:D8xgwECY7CYvx+Y2n4sBz93Jn9JRvxdiyyo8CTfuKaY=
+gopkg.in/yaml.v2 v2.4.0/go.mod h1:RDklbk79AGWmwhnvt/jBztapEOGDOx6ZbXqjP6csGnQ=

pkg/app/doc.go

@@ -0,0 +1,3 @@
+// Package app contains utility types and functions regarding metadata about the
+// application itself, such as versioning.
+package app

pkg/app/example_version_gin_endpoint_test.go

@@ -0,0 +1,59 @@
+package app_test
+
+import (
+	_ "embed"
+	"fmt"
+	"net/http"
+	"os"
+
+	"github.com/gin-gonic/gin"
+	"github.com/iver-wharf/wharf-core/pkg/app"
+)
+
+// The version.yaml file should be populated by a CI pipeline build step just
+// before building the binary for this application.
+//
+// For example, assuming you have BUILD_VERSION, BUILD_GIT_COMMIT, and BUILD_REF
+// environment variables set before running the following script:
+//
+// 		#!/bin/sh
+//
+// 		cat <<EOF > version.yaml
+// 		version: ${BUILD_VERSION}
+// 		buildGitCommit: ${BUILD_GIT_COMMIT}
+// 		buildDate: $(date '+%FT%T%:z')
+// 		buildRef: ${BUILD_REF}
+// 		EOF
+
+// go:embed version.yaml
+var versionFile []byte
+
+// AppVersion is the type holding metadata about this application's version.
+var AppVersion app.Version
+
+// getVersionHandler godoc
+// @summary Returns the version of this API
+// @tags meta
+// @success 200 {object} app.Version
+// @router /version [get]
+func getVersionHandler(c *gin.Context) {
+	c.JSON(http.StatusOK, AppVersion)
+}
+
+func ExampleVersion_ginEndpoint() {
+	if err := app.UnmarshalVersionYAML(versionFile, &AppVersion); err != nil {
+		fmt.Println("Failed to read embedded version.yaml file:", err)
+		os.Exit(1)
+	}
+
+	// If you use swaggo then you can set the API version like so:
+	//
+	// 		docs.SwaggerInfo.Version = AppVersion.Version
+	//
+	// More info: https://github.com/swaggo/swag#how-to-use-it-with-gin
+
+	r := gin.Default()
+	r.GET("/version", getVersionHandler)
+
+	_ = r.Run()
+}

pkg/app/example_version_unmarshal_test.go

@@ -0,0 +1,32 @@
+package app_test
+
+import (
+	"fmt"
+
+	"github.com/iver-wharf/wharf-core/pkg/app"
+)
+
+func ExampleUnmarshalVersionYAML() {
+	var body = []byte(`
+version: v1.0.0
+buildGitCommit: 10aaf36a71ffe4f021b3d85341f684931f333040
+buildDate: 2021-05-20T14:27:11+01:00
+buildRef: 123
+`)
+
+	var version app.Version
+	if err := app.UnmarshalVersionYAML(body, &version); err != nil {
+		fmt.Println("Unexpected error:", err)
+	}
+
+	fmt.Println("Version:         ", version.Version)
+	fmt.Println("Build Git commit:", version.BuildGitCommit)
+	fmt.Println("Build date:      ", version.BuildDate)
+	fmt.Println("Build reference: ", version.BuildRef)
+
+	// Output:
+	// Version:          v1.0.0
+	// Build Git commit: 10aaf36a71ffe4f021b3d85341f684931f333040
+	// Build date:       2021-05-20 14:27:11 +0100 +0100
+	// Build reference:  123
+}

pkg/app/version.go

@@ -0,0 +1,36 @@
+package app
+
+import (
+	"time"
+
+	"gopkg.in/yaml.v2"
+)
+
+// Version holds common version fields used in the different Wharf components
+// to distinguish it from other versions. This metadata can be commonly viewed
+// through the build application via an endpoint or commandline flag.
+type Version struct {
+	// Version is the version of this API build. A SemVer2.0.0 formatted version
+	// prefixed with a single "v" is expected, but not enforced.
+	//
+	// For local development versions a value of "local dev", "local docker",
+	// or something alike is recommended.
+	Version string `json:"version" yaml:"version" example:"v1.0.0"`
+
+	// BuildGitCommit is the Git commit that this version of the API was
+	// built from.
+	BuildGitCommit string `json:"buildGitCommit" yaml:"buildGitCommit" example:"10aaf36a71ffe4f021b3d85341f684931f333040"`
+
+	// BuildDate is the date on which this version of the API was built.
+	BuildDate time.Time `json:"buildDate" yaml:"buildDate" format:"date-time"`
+
+	// BuildRef is the Wharf build ID/reference from which this version of
+	// the API was build in.
+	BuildRef uint `json:"buildRef" yaml:"buildRef"`
+}
+
+// UnmarshalVersionYAML reads a YAML formatted file body and returns the
+// parsed Version.
+func UnmarshalVersionYAML(in []byte, version *Version) error {
+	return yaml.Unmarshal(in, &version)
+}