buildinfo.go

package buildinfo

import (
	"encoding/json"
	"runtime"
	"runtime/debug"
	"sync"
)

// Info contains build metadata for a Go binary.
//
// String fields default to DevVersion (Version) or Unknown (Commit, BuildTime,
// Branch) when neither -ldflags nor runtime/debug data populate them, so callers
// can render them safely without nil checks. Because those defaults are
// indistinguishable from real values by inspection alone, Source records which
// input actually won and HasCommit / HasVersion report whether a field holds
// real data.
type Info struct {
	// Version is the semver string for this build, or DevVersion when nothing
	// supplied one. Check Source to find out which.
	Version string `json:"version"`

	// Source records which input produced Version. See Source.
	Source Source `json:"source"`

	// Commit is the VCS commit hash, or Unknown.
	Commit string `json:"commit"`

	// BuildTime is the build timestamp in RFC3339 format, or Unknown.
	BuildTime string `json:"build_time"`

	// Branch is the VCS branch name, or Unknown. Go records no branch, so this
	// is populated only via -ldflags.
	Branch string `json:"branch"`

	// GoVersion is the toolchain version that produced the binary.
	GoVersion string `json:"go_version"`

	// GOOS is the target operating system.
	GOOS string `json:"goos"`

	// GOARCH is the target architecture.
	GOARCH string `json:"goarch"`

	// Modified reports an uncommitted working tree at build time. Meaningful
	// only alongside a real commit — see HasCommit.
	Modified bool `json:"modified"`

	// Modules lists dependency modules, with any replace directives resolved
	// to their targets.
	Modules []Module `json:"modules,omitempty"`
}

// HasCommit reports whether Commit holds a real hash rather than the Unknown
// sentinel.
//
// Needed because Modified is only meaningful alongside a commit: rendering
// "unknown (dirty)" asserts a dirty checkout for a build that carries no VCS
// record at all. Prefer this over comparing against Unknown yourself — the
// sentinel is this package's business, not its callers'.
func (i Info) HasCommit() bool {
	return i.Commit != "" && i.Commit != Unknown
}

// HasVersion reports whether Version came from a real input (an -ldflags stamp
// or a resolved module version) rather than falling back to DevVersion.
//
// Equivalent to Source != SourceUnknown, and offered because that is the check
// most callers actually want when deciding whether to display a version at all.
func (i Info) HasVersion() bool {
	return i.Source != SourceUnknown
}

// Module describes a single dependency module entry from runtime/debug.
type Module struct {
	Path    string `json:"path"`
	Version string `json:"version"`
	Sum     string `json:"sum,omitempty"`
}

// develVersion is the placeholder runtime/debug reports for Main.Version when a
// binary is built from a local source tree rather than resolved through the
// module proxy (`go build` / `go test` / `go run`). It is not a real version, so
// it must never be surfaced to callers.
const develVersion = "(devel)"

// Sentinel values used when an input supplied nothing. Exported so callers can
// compare against them instead of hardcoding the literals — a duplicated
// sentinel in a consumer breaks silently if this package ever changes one.
const (
	// DevVersion is Info.Version when no -ldflags stamp and no module version
	// were available, i.e. a plain local build.
	DevVersion = "dev"

	// Unknown is the fallback for Commit, BuildTime, and Branch.
	Unknown = "unknown"
)

// Source identifies which input produced Info.Version.
//
// Exists because the version string alone cannot answer the most common
// question a user asks about a build: "why does it say dev?" A binary reports
// DevVersion both when it was built locally and when a release pipeline forgot
// to pass its ldflags, and those need different responses. Surfacing the source
// makes the difference self-diagnosing rather than a support conversation.
type Source string

const (
	// SourceLdflags means Version was stamped at build time via
	// -X github.com/ubgo/buildinfo.Version=... — the release path.
	SourceLdflags Source = "ldflags"

	// SourceModule means Version came from the module version the Go toolchain
	// recorded in BuildInfo.Main.Version, i.e. the binary was installed with
	// `go install <pkg>@<version>`.
	SourceModule Source = "module"

	// SourceUnknown means neither input applied and Version is DevVersion: a
	// plain `go build`, `go run`, or `go test` binary with no release
	// provenance.
	SourceUnknown Source = "unknown"
)

// Valid reports whether s is a known source. Guards against a zero-value or
// hand-constructed Info being treated as if it carried real provenance.
func (s Source) Valid() bool {
	switch s {
	case SourceLdflags, SourceModule, SourceUnknown:
		return true
	}
	return false
}

// String implements fmt.Stringer.
func (s Source) String() string { return string(s) }

var (
	cached Info
	once   sync.Once

	// readBuildInfo is the seam for tests to inject a synthetic *debug.BuildInfo.
	readBuildInfo = debug.ReadBuildInfo
)

// Get returns the populated Info struct, cached after the first call.
//
// Population precedence (highest first):
//
//  1. -ldflags overrides set at build time.
//  2. runtime/debug.ReadBuildInfo data — the module version recorded in
//     Main.Version, plus VCS data (vcs.revision, vcs.time, vcs.modified).
//  3. Sentinel defaults (DevVersion for Version, Unknown for Commit /
//     BuildTime / Branch).
//
// Info.Source reports which of those produced Version, so a caller never has to
// infer provenance from the string itself.
func Get() Info {
	once.Do(load)
	return cached
}

// Map returns Info as a flat string-only map for legacy or string-typed
// consumers (e.g. simple key-value renderers).
//
// Modified and Modules are omitted: the former is not a string and the latter is
// unbounded, which would swamp a log line or a metric label set.
func Map() map[string]string {
	i := Get()
	return map[string]string{
		"version":    i.Version,
		"source":     string(i.Source),
		"commit":     i.Commit,
		"build_time": i.BuildTime,
		"branch":     i.Branch,
		"go_version": i.GoVersion,
		"goos":       i.GOOS,
		"goarch":     i.GOARCH,
	}
}

// JSON returns the Info marshalled as JSON bytes.
func (i Info) JSON() ([]byte, error) {
	return json.Marshal(i)
}

func load() {
	info := Info{
		GoVersion: runtime.Version(),
		GOOS:      runtime.GOOS,
		GOARCH:    runtime.GOARCH,
	}

	if bi, ok := readBuildInfo(); ok {
		// Main.Version carries the module version the binary was resolved at,
		// e.g. "v1.2.3" after `go install example.com/cmd/app@v1.2.3`. The Go
		// toolchain records it with no build flags, which makes it the only
		// automatic version source for users who install via `go install`
		// rather than downloading a CI-stamped release artifact.
		//
		// Locally built binaries report the develVersion placeholder instead;
		// treat that as absent so the sentinel default applies.
		if bi.Main.Version != "" && bi.Main.Version != develVersion {
			info.Version = bi.Main.Version
			info.Source = SourceModule
		}

		for _, s := range bi.Settings {
			switch s.Key {
			case "vcs.revision":
				info.Commit = s.Value
			case "vcs.time":
				info.BuildTime = s.Value
			case "vcs.modified":
				info.Modified = s.Value == "true"
			}
		}
		info.Modules = collectModules(bi)
	}

	// Source is assigned in the same statement as Version everywhere it is set,
	// so the two cannot drift out of agreement as this function grows.
	if Version != "" {
		info.Version = Version
		info.Source = SourceLdflags
	}
	if Commit != "" {
		info.Commit = Commit
	}
	if BuildTime != "" {
		info.BuildTime = BuildTime
	}
	if Branch != "" {
		info.Branch = Branch
	}

	if info.Version == "" {
		info.Version = DevVersion
		info.Source = SourceUnknown
	}
	if info.Commit == "" {
		info.Commit = Unknown
	}
	if info.BuildTime == "" {
		info.BuildTime = Unknown
	}
	if info.Branch == "" {
		info.Branch = Unknown
	}

	cached = info
}

func collectModules(bi *debug.BuildInfo) []Module {
	mods := make([]Module, 0, len(bi.Deps))
	for _, d := range bi.Deps {
		for d.Replace != nil {
			d = d.Replace
		}
		mods = append(mods, Module{
			Path:    d.Path,
			Version: d.Version,
			Sum:     d.Sum,
		})
	}
	return mods
}