podman

1
// Copyright 2018 The Go Authors. All rights reserved.
2
// Use of this source code is governed by a BSD-style
3
// license that can be found in the LICENSE file.
4

5
// Pseudo-versions
6
//
7
// Code authors are expected to tag the revisions they want users to use,
8
// including prereleases. However, not all authors tag versions at all,
9
// and not all commits a user might want to try will have tags.
10
// A pseudo-version is a version with a special form that allows us to
11
// address an untagged commit and order that version with respect to
12
// other versions we might encounter.
13
//
14
// A pseudo-version takes one of the general forms:
15
//
16
//	(1) vX.0.0-yyyymmddhhmmss-abcdef123456
17
//	(2) vX.Y.(Z+1)-0.yyyymmddhhmmss-abcdef123456
18
//	(3) vX.Y.(Z+1)-0.yyyymmddhhmmss-abcdef123456+incompatible
19
//	(4) vX.Y.Z-pre.0.yyyymmddhhmmss-abcdef123456
20
//	(5) vX.Y.Z-pre.0.yyyymmddhhmmss-abcdef123456+incompatible
21
//
22
// If there is no recently tagged version with the right major version vX,
23
// then form (1) is used, creating a space of pseudo-versions at the bottom
24
// of the vX version range, less than any tagged version, including the unlikely v0.0.0.
25
//
26
// If the most recent tagged version before the target commit is vX.Y.Z or vX.Y.Z+incompatible,
27
// then the pseudo-version uses form (2) or (3), making it a prerelease for the next
28
// possible semantic version after vX.Y.Z. The leading 0 segment in the prerelease string
29
// ensures that the pseudo-version compares less than possible future explicit prereleases
30
// like vX.Y.(Z+1)-rc1 or vX.Y.(Z+1)-1.
31
//
32
// If the most recent tagged version before the target commit is vX.Y.Z-pre or vX.Y.Z-pre+incompatible,
33
// then the pseudo-version uses form (4) or (5), making it a slightly later prerelease.
34

35
package module
36

37
import (
38
	"errors"
39
	"fmt"
40
	"strings"
41
	"time"
42

43
	"golang.org/x/mod/internal/lazyregexp"
44
	"golang.org/x/mod/semver"
45
)
46

47
var pseudoVersionRE = lazyregexp.New(`^v[0-9]+\.(0\.0-|\d+\.\d+-([^+]*\.)?0\.)\d{14}-[A-Za-z0-9]+(\+[0-9A-Za-z-]+(\.[0-9A-Za-z-]+)*)?$`)
48

49
const PseudoVersionTimestampFormat = "20060102150405"
50

51
// PseudoVersion returns a pseudo-version for the given major version ("v1")
52
// preexisting older tagged version ("" or "v1.2.3" or "v1.2.3-pre"), revision time,
53
// and revision identifier (usually a 12-byte commit hash prefix).
54
func PseudoVersion(major, older string, t time.Time, rev string) string {
55
	if major == "" {
56
		major = "v0"
57
	}
58
	segment := fmt.Sprintf("%s-%s", t.UTC().Format(PseudoVersionTimestampFormat), rev)
59
	build := semver.Build(older)
60
	older = semver.Canonical(older)
61
	if older == "" {
62
		return major + ".0.0-" + segment // form (1)
63
	}
64
	if semver.Prerelease(older) != "" {
65
		return older + ".0." + segment + build // form (4), (5)
66
	}
67

68
	// Form (2), (3).
69
	// Extract patch from vMAJOR.MINOR.PATCH
70
	i := strings.LastIndex(older, ".") + 1
71
	v, patch := older[:i], older[i:]
72

73
	// Reassemble.
74
	return v + incDecimal(patch) + "-0." + segment + build
75
}
76

77
// ZeroPseudoVersion returns a pseudo-version with a zero timestamp and
78
// revision, which may be used as a placeholder.
79
func ZeroPseudoVersion(major string) string {
80
	return PseudoVersion(major, "", time.Time{}, "000000000000")
81
}
82

83
// incDecimal returns the decimal string incremented by 1.
84
func incDecimal(decimal string) string {
85
	// Scan right to left turning 9s to 0s until you find a digit to increment.
86
	digits := []byte(decimal)
87
	i := len(digits) - 1
88
	for ; i >= 0 && digits[i] == '9'; i-- {
89
		digits[i] = '0'
90
	}
91
	if i >= 0 {
92
		digits[i]++
93
	} else {
94
		// digits is all zeros
95
		digits[0] = '1'
96
		digits = append(digits, '0')
97
	}
98
	return string(digits)
99
}
100

101
// decDecimal returns the decimal string decremented by 1, or the empty string
102
// if the decimal is all zeroes.
103
func decDecimal(decimal string) string {
104
	// Scan right to left turning 0s to 9s until you find a digit to decrement.
105
	digits := []byte(decimal)
106
	i := len(digits) - 1
107
	for ; i >= 0 && digits[i] == '0'; i-- {
108
		digits[i] = '9'
109
	}
110
	if i < 0 {
111
		// decimal is all zeros
112
		return ""
113
	}
114
	if i == 0 && digits[i] == '1' && len(digits) > 1 {
115
		digits = digits[1:]
116
	} else {
117
		digits[i]--
118
	}
119
	return string(digits)
120
}
121

122
// IsPseudoVersion reports whether v is a pseudo-version.
123
func IsPseudoVersion(v string) bool {
124
	return strings.Count(v, "-") >= 2 && semver.IsValid(v) && pseudoVersionRE.MatchString(v)
125
}
126

127
// IsZeroPseudoVersion returns whether v is a pseudo-version with a zero base,
128
// timestamp, and revision, as returned by [ZeroPseudoVersion].
129
func IsZeroPseudoVersion(v string) bool {
130
	return v == ZeroPseudoVersion(semver.Major(v))
131
}
132

133
// PseudoVersionTime returns the time stamp of the pseudo-version v.
134
// It returns an error if v is not a pseudo-version or if the time stamp
135
// embedded in the pseudo-version is not a valid time.
136
func PseudoVersionTime(v string) (time.Time, error) {
137
	_, timestamp, _, _, err := parsePseudoVersion(v)
138
	if err != nil {
139
		return time.Time{}, err
140
	}
141
	t, err := time.Parse("20060102150405", timestamp)
142
	if err != nil {
143
		return time.Time{}, &InvalidVersionError{
144
			Version: v,
145
			Pseudo:  true,
146
			Err:     fmt.Errorf("malformed time %q", timestamp),
147
		}
148
	}
149
	return t, nil
150
}
151

152
// PseudoVersionRev returns the revision identifier of the pseudo-version v.
153
// It returns an error if v is not a pseudo-version.
154
func PseudoVersionRev(v string) (rev string, err error) {
155
	_, _, rev, _, err = parsePseudoVersion(v)
156
	return
157
}
158

159
// PseudoVersionBase returns the canonical parent version, if any, upon which
160
// the pseudo-version v is based.
161
//
162
// If v has no parent version (that is, if it is "vX.0.0-[…]"),
163
// PseudoVersionBase returns the empty string and a nil error.
164
func PseudoVersionBase(v string) (string, error) {
165
	base, _, _, build, err := parsePseudoVersion(v)
166
	if err != nil {
167
		return "", err
168
	}
169

170
	switch pre := semver.Prerelease(base); pre {
171
	case "":
172
		// vX.0.0-yyyymmddhhmmss-abcdef123456 → ""
173
		if build != "" {
174
			// Pseudo-versions of the form vX.0.0-yyyymmddhhmmss-abcdef123456+incompatible
175
			// are nonsensical: the "vX.0.0-" prefix implies that there is no parent tag,
176
			// but the "+incompatible" suffix implies that the major version of
177
			// the parent tag is not compatible with the module's import path.
178
			//
179
			// There are a few such entries in the index generated by proxy.golang.org,
180
			// but we believe those entries were generated by the proxy itself.
181
			return "", &InvalidVersionError{
182
				Version: v,
183
				Pseudo:  true,
184
				Err:     fmt.Errorf("lacks base version, but has build metadata %q", build),
185
			}
186
		}
187
		return "", nil
188

189
	case "-0":
190
		// vX.Y.(Z+1)-0.yyyymmddhhmmss-abcdef123456 → vX.Y.Z
191
		// vX.Y.(Z+1)-0.yyyymmddhhmmss-abcdef123456+incompatible → vX.Y.Z+incompatible
192
		base = strings.TrimSuffix(base, pre)
193
		i := strings.LastIndexByte(base, '.')
194
		if i < 0 {
195
			panic("base from parsePseudoVersion missing patch number: " + base)
196
		}
197
		patch := decDecimal(base[i+1:])
198
		if patch == "" {
199
			// vX.0.0-0 is invalid, but has been observed in the wild in the index
200
			// generated by requests to proxy.golang.org.
201
			//
202
			// NOTE(bcmills): I cannot find a historical bug that accounts for
203
			// pseudo-versions of this form, nor have I seen such versions in any
204
			// actual go.mod files. If we find actual examples of this form and a
205
			// reasonable theory of how they came into existence, it seems fine to
206
			// treat them as equivalent to vX.0.0 (especially since the invalid
207
			// pseudo-versions have lower precedence than the real ones). For now, we
208
			// reject them.
209
			return "", &InvalidVersionError{
210
				Version: v,
211
				Pseudo:  true,
212
				Err:     fmt.Errorf("version before %s would have negative patch number", base),
213
			}
214
		}
215
		return base[:i+1] + patch + build, nil
216

217
	default:
218
		// vX.Y.Z-pre.0.yyyymmddhhmmss-abcdef123456 → vX.Y.Z-pre
219
		// vX.Y.Z-pre.0.yyyymmddhhmmss-abcdef123456+incompatible → vX.Y.Z-pre+incompatible
220
		if !strings.HasSuffix(base, ".0") {
221
			panic(`base from parsePseudoVersion missing ".0" before date: ` + base)
222
		}
223
		return strings.TrimSuffix(base, ".0") + build, nil
224
	}
225
}
226

227
var errPseudoSyntax = errors.New("syntax error")
228

229
func parsePseudoVersion(v string) (base, timestamp, rev, build string, err error) {
230
	if !IsPseudoVersion(v) {
231
		return "", "", "", "", &InvalidVersionError{
232
			Version: v,
233
			Pseudo:  true,
234
			Err:     errPseudoSyntax,
235
		}
236
	}
237
	build = semver.Build(v)
238
	v = strings.TrimSuffix(v, build)
239
	j := strings.LastIndex(v, "-")
240
	v, rev = v[:j], v[j+1:]
241
	i := strings.LastIndex(v, "-")
242
	if j := strings.LastIndex(v, "."); j > i {
243
		base = v[:j] // "vX.Y.Z-pre.0" or "vX.Y.(Z+1)-0"
244
		timestamp = v[j+1:]
245
	} else {
246
		base = v[:i] // "vX.0.0"
247
		timestamp = v[i+1:]
248
	}
249
	return base, timestamp, rev, build, nil
250
}
251