app

Documentation

Overview

Package app contains utility types and functions regarding metadata about the application itself, such as versioning.

Index

• func UnmarshalVersionYAML(in []byte, version *Version) error
• type Version

Examples

• UnmarshalVersionYAML
• Version (GinEndpoint)

Functions

func UnmarshalVersionYAML

func UnmarshalVersionYAML(in []byte, version *Version) error

UnmarshalVersionYAML reads a YAML formatted file body and returns the parsed Version.

Example

package main

import (
	"fmt"

	"github.com/iver-wharf/wharf-core/pkg/app"
)

func main() {
	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

Types

type Version

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"`
}

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.

Example (GinEndpoint)

package main

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 main() {
	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()
}