latest

package module
v0.0.0-...-c5c4c8b Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Feb 2, 2017 License: MIT Imports: 16 Imported by: 0

README

go-latest

GitHub release Wercker MIT License Go Documentation

go-latest is a package to check a provided version is latest or not from various sources.

Once you distribute your tool by golang and user start to use it, it's difficult to tell users that new version is released and encourage them to use new one. go-latest enables you to do that by just preparing simple source. For sources, currently you can use tags on Github, HTML meta tag (HTML scraping) and JSON response.

See more details in document at https://godoc.org/github.com/tcnksm/go-latest.

Install

To install, use go get:

$ go get -d github.com/tcnksm/go-latest

Usage

For sources to check, currently you can use tags on Github, HTML meta tag (HTML scraping) and JSON response.

Github Tag

To check 0.1.0 is the latest in tags on GitHub.

githubTag := &latest.GithubTag{
    Owner: "username",
    Repository: "reponame",
}

res, _ := latest.Check(githubTag, "0.1.0")
if res.Outdated {
    fmt.Printf("0.1.0 is not latest, you should upgrade to %s", res.Current)
}

go-latest uses Semantic Versioning to compare versions. If tagging name strategy on GitHub is different from it, you need to fix it with FixVersionStrFunc. For example, if you add v charactor in the begining of version string like v0.1.0, you need to transform it to 0.1.0, you can use DeleteFrontV() function like below,

githubTag := &latest.GithubTag{
    Owner:             "username",
    Repository:        "reponame",
    FixVersionStrFunc: latest.DeleteFrontV(),
}

You can define your own FixVersionStrFunc. See more on https://godoc.org/github.com/tcnksm/go-latest

HTML meta tag

You can use simple HTTP+HTML meta tag for a checking source.

For example, if you have a tool named reduce-worker and want to check 0.1.0 is latest or not, prepare HTML page which includes following meta tag,

<meta name="go-latest" content="reduce-worker 0.1.1 New version include security update">

And make request,

html := &latest.HTMLMeta{
    URL: "http://example.com/info",
    Name: "reduce-worker",
}

res, _ := latest.Check(html, "0.1.0")
if res.Outdated {
    fmt.Printf("0.1.0 is not latest, %s, upgrade to %s", res.Meta.Message, res.Current)
}

To know about HTML meta tag specification, see HTML Meta tag.

You can prepare your own HTML page and its scraping function. See more details in document at https://godoc.org/github.com/tcnksm/go-latest.

JSON

You can also use a JSON response.

If you want to check 0.1.0 is latest or not, prepare an API server which returns a following response,

{
    "version":"1.2.3",
    "message":"New version include security update, you should update soon",
    "url":"http://example.com/info"
}

And make request,

json := &latest.JSON{
    URL: "http://example.com/json",
}

res, _ := latest.Check(json, "0.1.0")
if res.Outdated {
    fmt.Printf("0.1.0 is not latest, %s, upgrade to %s", res.Meta.Message, res.Current)
}

You can use your own json schema by defining JSONReceive interface. See more details in document at https://godoc.org/github.com/tcnksm/go-latest.

Version comparing

To compare version, we use hashicorp/go-version. go-version follows Semantic Versioning. So to use go-latest you need to follow SemVer format.

For user who doesn't use SemVer format, go-latest has function to transform it into SemVer format.

Contribution

  1. Fork (https://github.com/tcnksm/go-latest/fork)
  2. Create a feature branch
  3. Commit your changes
  4. Rebase your local changes against the master branch
  5. Run test suite with the go test ./... command and confirm that it passes
  6. Run gofmt -s
  7. Create new Pull Request

Author

Taichi Nakashima

Documentation

Overview

go-latest is pacakge to check a provided version is latest from various sources.

http://github.com/tcnksm/go-latest

package main

import (
    "github.com/tcnksm/go-latest"
)

githubTag := &latest.GithubTag{
    Owner: "tcnksm",
    Repository: "ghr"
}

res, _ := latest.Check("0.1.0",githubTag)
if res.Outdated {
    fmt.Printf("version 0.1.0 is out of date, you can upgrade to %s", res.Current)
}

Index

Constants

View Source
const EnvGoLatestDisable = "GOLATEST_DISABLE"

EnvGoLatestDisable is environmental variable to disable go-latest execution.

View Source
const MetaTagName = "go-latest"

MetaTagName is common HTML meta tag name which is defined on https://github.com/tcnksm/go-latest/blob/master/doc/html_meta.md

Variables

This section is empty.

Functions

This section is empty.

Types

type CheckResponse

type CheckResponse struct {
	// Current is current latest version on source.
	Current string

	// Outdate is true when target version is less than Curernt on source.
	Outdated bool

	// Latest is true when target version is equal to Current on source.
	Latest bool

	// New is true when target version is greater than Current on source.
	New bool

	// Malformed store versions or tags which can not be parsed as
	// Semantic versioning (not compared with target).
	Malformeds []string

	// Meta is meta information from source.
	Meta *Meta
}

CheckResponse is a response for a Check request.

func Check

func Check(s Source, target string) (*CheckResponse, error)

Check fetches last version information from its source and compares with target and return result (CheckResponse).

type FetchResponse

type FetchResponse struct {
	Versions   []*version.Version
	Malformeds []string
	Meta       *Meta
}

FetchResponse the commom response of Fetch request.

type FixVersionStrFunc

type FixVersionStrFunc func(string) string

FixVersionStrFunc is function to fix version string so that it can be interpreted as Semantic Versiongin by http://godoc.org/github.com/hashicorp/go-version

func DeleteFrontV

func DeleteFrontV() FixVersionStrFunc

DeleteFrontV delete first `v` charactor on version string. For example version name `v0.1.1` becomes `0.1.1`

type GithubTag

type GithubTag struct {
	// Owner and Repository are GitHub owner name and its repository name.
	// e.g., If you want to check https://github.com/tcnksm/ghr version
	// Repository is `ghr`, and Owner is `tcnksm`.
	Owner      string
	Repository string

	// FixVersionStrFunc is function to fix version string (in this case tag
	// name string) on GitHub so that it can be interpreted as Semantic Versioning
	// by hashicorp/go-version. By default, it does nothing.
	FixVersionStrFunc FixVersionStrFunc

	// TagFilterFunc is function to filter tags from GitHub. Some project includes
	// tags you don't want to use for version comparing. It can be used to exclude
	// such tags. By default, it does nothing.
	TagFilterFunc TagFilterFunc

	// URL & Token is used for GitHub Enterprise
	URL   string
	Token string
}

GithubTag is used to fetch version(tag) information from Github.

func (*GithubTag) Fetch

func (g *GithubTag) Fetch() (*FetchResponse, error)

func (*GithubTag) Validate

func (g *GithubTag) Validate() error

type HTML

type HTML struct {
	// URL is HTML page URL which include version information.
	URL string

	// Scrap is used to scrap a single HTML page and extract version information.
	// See more about HTMLScrap interface.
	// By default, it does nothing, just return HTML contents.
	Scrap HTMLScrap
}

HTML is used to fetch version information from a single HTML page.

func (*HTML) Fetch

func (h *HTML) Fetch() (*FetchResponse, error)

func (*HTML) Validate

func (h *HTML) Validate() error

type HTMLMeta

type HTMLMeta struct {
	// URL is HTML page URL which include version information.
	URL string

	// Name is tool name which you want to check. This name must be
	// written in HTML meta tag content field. HTMLMeta use this to
	// extract version information.
	Name string
}

HTMLMeta is used to fetch a single HTML page and extract version information from specific meta tag. See meta tag specification that HTMLMeta tries to extract on https://github.com/tcnksm/go-latest/blob/master/doc/html_meta.md

func (*HTMLMeta) Fetch

func (hm *HTMLMeta) Fetch() (*FetchResponse, error)

func (*HTMLMeta) Validate

func (hm *HTMLMeta) Validate() error

type HTMLScrap

type HTMLScrap interface {
	// Exec is called from Fetch after fetching a HTMl page from source.
	// It must return version information as string list format.
	Exec(r io.Reader) ([]string, *Meta, error)
}

HTMLScrap is used to scrap a single HTML page and extract version information.

type JSON

type JSON struct {
	// URL is URL which return json response with version information.
	URL string

	// Response is used to decode json as Struct and extract version information.
	// See JSONResponse interface. By Default, it is used defaultJSONResponse.
	Response JSONResponse
}

JSON is used to get version information as json format from remote host.

func (*JSON) Fetch

func (j *JSON) Fetch() (*FetchResponse, error)

func (*JSON) Validate

func (j *JSON) Validate() error

type JSONResponse

type JSONResponse interface {
	// VersionInfo is called from Fetch to extract version info.
	// It must return Semantic Version format version string list.
	VersionInfo() ([]string, error)

	// MetaInfo is called from Fetch to extract meta info.
	MetaInfo() (*Meta, error)
}

JSONResponse is used to decode json as Struct and extract information.

type Meta

type Meta struct {
	Message string
	URL     string
}

Meta is meta information from Fetch request.

type Source

type Source interface {
	// Validate is called before Fetch in Check.
	// Source may need to have various information like URL or product name,
	// so it is used for check each variables are correctly set.
	// If it is failed, Fetch() will not executed.
	Validate() error

	// Fetch is called in Check to fetch information from remote sources.
	// After fetching, it will convert it into common expression (FetchResponse)
	Fetch() (*FetchResponse, error)
}

Source is the interface that every version information source must implement.

type TagFilterFunc

type TagFilterFunc func(string) bool

TagFilterFunc is fucntion to filter unexpected tags from GitHub. Check a given tag as string (before FixVersionStr) and return bool. If it's expected, return true. If not return false.

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL