Debian Codegraph @

provider.go

raw
1 package tfaddr
2
3 import (
4 "fmt"
5 "strings"
6
7 svchost "github.com/hashicorp/terraform-svchost"
8 "golang.org/x/net/idna"
9 )
10
11 // Provider encapsulates a single provider type. In the future this will be
12 // extended to include additional fields including Namespace and SourceHost
13 type Provider struct {
14 Type string
15 Namespace string
16 Hostname svchost.Hostname
17 }
18
19 // DefaultProviderRegistryHost is the hostname used for provider addresses that do
20 // not have an explicit hostname.
21 const DefaultProviderRegistryHost = svchost.Hostname("registry.terraform.io")
22
23 // BuiltInProviderHost is the pseudo-hostname used for the "built-in" provider
24 // namespace. Built-in provider addresses must also have their namespace set
25 // to BuiltInProviderNamespace in order to be considered as built-in.
26 const BuiltInProviderHost = svchost.Hostname("terraform.io")
27
28 // BuiltInProviderNamespace is the provider namespace used for "built-in"
29 // providers. Built-in provider addresses must also have their hostname
30 // set to BuiltInProviderHost in order to be considered as built-in.
31 //
32 // The this namespace is literally named "builtin", in the hope that users
33 // who see FQNs containing this will be able to infer the way in which they are
34 // special, even if they haven't encountered the concept formally yet.
35 const BuiltInProviderNamespace = "builtin"
36
37 // UnknownProviderNamespace is the special string used to indicate
38 // unknown namespace, e.g. in "aws". This is equivalent to
39 // LegacyProviderNamespace for <0.12 style address. This namespace
40 // would never be produced by Terraform itself explicitly, it is
41 // only an internal placeholder.
42 const UnknownProviderNamespace = "?"
43
44 // LegacyProviderNamespace is the special string used in the Namespace field
45 // of type Provider to mark a legacy provider address. This special namespace
46 // value would normally be invalid, and can be used only when the hostname is
47 // DefaultProviderRegistryHost because that host owns the mapping from legacy name to
48 // FQN. This may be produced by Terraform 0.13.
49 const LegacyProviderNamespace = "-"
50
51 // String returns an FQN string, indended for use in machine-readable output.
52 func (pt Provider) String() string {
53 if pt.IsZero() {
54 panic("called String on zero-value addrs.Provider")
55 }
56 return pt.Hostname.ForDisplay() + "/" + pt.Namespace + "/" + pt.Type
57 }
58
59 // ForDisplay returns a user-friendly FQN string, simplified for readability. If
60 // the provider is using the default hostname, the hostname is omitted.
61 func (pt Provider) ForDisplay() string {
62 if pt.IsZero() {
63 panic("called ForDisplay on zero-value addrs.Provider")
64 }
65
66 if pt.Hostname == DefaultProviderRegistryHost {
67 return pt.Namespace + "/" + pt.Type
68 }
69 return pt.Hostname.ForDisplay() + "/" + pt.Namespace + "/" + pt.Type
70 }
71
72 // NewProvider constructs a provider address from its parts, and normalizes
73 // the namespace and type parts to lowercase using unicode case folding rules
74 // so that resulting addrs.Provider values can be compared using standard
75 // Go equality rules (==).
76 //
77 // The hostname is given as a svchost.Hostname, which is required by the
78 // contract of that type to have already been normalized for equality testing.
79 //
80 // This function will panic if the given namespace or type name are not valid.
81 // When accepting namespace or type values from outside the program, use
82 // ParseProviderPart first to check that the given value is valid.
83 func NewProvider(hostname svchost.Hostname, namespace, typeName string) Provider {
84 if namespace == LegacyProviderNamespace {
85 // Legacy provider addresses must always be created via struct
86 panic("attempt to create legacy provider address using NewProvider; use Provider{} instead")
87 }
88 if namespace == UnknownProviderNamespace {
89 // Provider addresses with unknown namespace must always
90 // be created via struct
91 panic("attempt to create provider address with unknown namespace using NewProvider; use Provider{} instead")
92 }
93 if namespace == "" {
94 // This case is already handled by MustParseProviderPart() below,
95 // but we catch it early to provide more helpful message.
96 panic("attempt to create provider address with empty namespace")
97 }
98
99 return Provider{
100 Type: MustParseProviderPart(typeName),
101 Namespace: MustParseProviderPart(namespace),
102 Hostname: hostname,
103 }
104 }
105
106 // LegacyString returns the provider type, which is frequently used
107 // interchangeably with provider name. This function can and should be removed
108 // when provider type is fully integrated. As a safeguard for future
109 // refactoring, this function panics if the Provider is not a legacy provider.
110 func (pt Provider) LegacyString() string {
111 if pt.IsZero() {
112 panic("called LegacyString on zero-value addrs.Provider")
113 }
114 if pt.Namespace != LegacyProviderNamespace && pt.Namespace != BuiltInProviderNamespace {
115 panic(pt.String() + " cannot be represented as a legacy string")
116 }
117 return pt.Type
118 }
119
120 // IsZero returns true if the receiver is the zero value of addrs.Provider.
121 //
122 // The zero value is not a valid addrs.Provider and calling other methods on
123 // such a value is likely to either panic or otherwise misbehave.
124 func (pt Provider) IsZero() bool {
125 return pt == Provider{}
126 }
127
128 // HasKnownNamespace returns true if the provider namespace is known
129 // (also if it is legacy namespace)
130 func (pt Provider) HasKnownNamespace() bool {
131 return pt.Namespace != UnknownProviderNamespace
132 }
133
134 // IsBuiltIn returns true if the receiver is the address of a "built-in"
135 // provider. That is, a provider under terraform.io/builtin/ which is
136 // included as part of the Terraform binary itself rather than one to be
137 // installed from elsewhere.
138 //
139 // These are ignored by the provider installer because they are assumed to
140 // already be available without any further installation.
141 func (pt Provider) IsBuiltIn() bool {
142 return pt.Hostname == BuiltInProviderHost && pt.Namespace == BuiltInProviderNamespace
143 }
144
145 // LessThan returns true if the receiver should sort before the other given
146 // address in an ordered list of provider addresses.
147 //
148 // This ordering is an arbitrary one just to allow deterministic results from
149 // functions that would otherwise have no natural ordering. It's subject
150 // to change in future.
151 func (pt Provider) LessThan(other Provider) bool {
152 switch {
153 case pt.Hostname != other.Hostname:
154 return pt.Hostname < other.Hostname
155 case pt.Namespace != other.Namespace:
156 return pt.Namespace < other.Namespace
157 default:
158 return pt.Type < other.Type
159 }
160 }
161
162 // IsLegacy returns true if the provider is a legacy-style provider
163 func (pt Provider) IsLegacy() bool {
164 if pt.IsZero() {
165 panic("called IsLegacy() on zero-value addrs.Provider")
166 }
167
168 return pt.Hostname == DefaultProviderRegistryHost && pt.Namespace == LegacyProviderNamespace
169
170 }
171
172 // Equals returns true if the receiver and other provider have the same attributes.
173 func (pt Provider) Equals(other Provider) bool {
174 return pt == other
175 }
176
177 // ParseProviderSource parses the source attribute and returns a provider.
178 // This is intended primarily to parse the FQN-like strings returned by
179 // terraform-config-inspect.
180 //
181 // The following are valid source string formats:
182 // name
183 // namespace/name
184 // hostname/namespace/name
185 //
186 // "name"-only format is parsed as -/name (i.e. legacy namespace)
187 // requiring further identification of the namespace via Registry API
188 func ParseProviderSource(str string) (Provider, error) {
189 var ret Provider
190 parts, err := parseSourceStringParts(str)
191 if err != nil {
192 return ret, err
193 }
194
195 name := parts[len(parts)-1]
196 ret.Type = name
197 ret.Hostname = DefaultProviderRegistryHost
198
199 if len(parts) == 1 {
200 return Provider{
201 Hostname: DefaultProviderRegistryHost,
202 Namespace: UnknownProviderNamespace,
203 Type: name,
204 }, nil
205 }
206
207 if len(parts) >= 2 {
208 // the namespace is always the second-to-last part
209 givenNamespace := parts[len(parts)-2]
210 if givenNamespace == LegacyProviderNamespace {
211 // For now we're tolerating legacy provider addresses until we've
212 // finished updating the rest of the codebase to no longer use them,
213 // or else we'd get errors round-tripping through legacy subsystems.
214 ret.Namespace = LegacyProviderNamespace
215 } else {
216 namespace, err := ParseProviderPart(givenNamespace)
217 if err != nil {
218 return Provider{}, &ParserError{
219 Summary: "Invalid provider namespace",
220 Detail: fmt.Sprintf(`Invalid provider namespace %q in source %q: %s"`, namespace, str, err),
221 }
222 }
223 ret.Namespace = namespace
224 }
225 }
226
227 // Final Case: 3 parts
228 if len(parts) == 3 {
229 // the namespace is always the first part in a three-part source string
230 hn, err := svchost.ForComparison(parts[0])
231 if err != nil {
232 return Provider{}, &ParserError{
233 Summary: "Invalid provider source hostname",
234 Detail: fmt.Sprintf(`Invalid provider source hostname namespace %q in source %q: %s"`, hn, str, err),
235 }
236 }
237 ret.Hostname = hn
238 }
239
240 if ret.Namespace == LegacyProviderNamespace && ret.Hostname != DefaultProviderRegistryHost {
241 // Legacy provider addresses must always be on the default registry
242 // host, because the default registry host decides what actual FQN
243 // each one maps to.
244 return Provider{}, &ParserError{
245 Summary: "Invalid provider namespace",
246 Detail: "The legacy provider namespace \"-\" can be used only with hostname " + DefaultProviderRegistryHost.ForDisplay() + ".",
247 }
248 }
249
250 // Due to how plugin executables are named and provider git repositories
251 // are conventionally named, it's a reasonable and
252 // apparently-somewhat-common user error to incorrectly use the
253 // "terraform-provider-" prefix in a provider source address. There is
254 // no good reason for a provider to have the prefix "terraform-" anyway,
255 // so we've made that invalid from the start both so we can give feedback
256 // to provider developers about the terraform- prefix being redundant
257 // and give specialized feedback to folks who incorrectly use the full
258 // terraform-provider- prefix to help them self-correct.
259 const redundantPrefix = "terraform-"
260 const userErrorPrefix = "terraform-provider-"
261 if strings.HasPrefix(ret.Type, redundantPrefix) {
262 if strings.HasPrefix(ret.Type, userErrorPrefix) {
263 // Likely user error. We only return this specialized error if
264 // whatever is after the prefix would otherwise be a
265 // syntactically-valid provider type, so we don't end up advising
266 // the user to try something that would be invalid for another
267 // reason anyway.
268 // (This is mainly just for robustness, because the validation
269 // we already did above should've rejected most/all ways for
270 // the suggestedType to end up invalid here.)
271 suggestedType := ret.Type[len(userErrorPrefix):]
272 if _, err := ParseProviderPart(suggestedType); err == nil {
273 suggestedAddr := ret
274 suggestedAddr.Type = suggestedType
275 return Provider{}, &ParserError{
276 Summary: "Invalid provider type",
277 Detail: fmt.Sprintf("Provider source %q has a type with the prefix %q, which isn't valid. Although that prefix is often used in the names of version control repositories for Terraform providers, provider source strings should not include it.\n\nDid you mean %q?", ret.ForDisplay(), userErrorPrefix, suggestedAddr.ForDisplay()),
278 }
279 }
280 }
281 // Otherwise, probably instead an incorrectly-named provider, perhaps
282 // arising from a similar instinct to what causes there to be
283 // thousands of Python packages on PyPI with "python-"-prefixed
284 // names.
285 return Provider{}, &ParserError{
286 Summary: "Invalid provider type",
287 Detail: fmt.Sprintf("Provider source %q has a type with the prefix %q, which isn't allowed because it would be redundant to name a Terraform provider with that prefix. If you are the author of this provider, rename it to not include the prefix.", ret, redundantPrefix),
288 }
289 }
290
291 return ret, nil
292 }
293
294 // MustParseProviderSource is a wrapper around ParseProviderSource that panics if
295 // it returns an error.
296 func MustParseProviderSource(raw string) (Provider) {
297 p, err := ParseProviderSource(raw)
298 if err != nil {
299 panic(err)
300 }
301 return p
302 }
303
304 // ValidateProviderAddress returns error if the given address is not FQN,
305 // that is if it is missing any of the three components from
306 // hostname/namespace/name.
307 func ValidateProviderAddress(raw string) error {
308 parts, err := parseSourceStringParts(raw)
309 if err != nil {
310 return err
311 }
312
313 if len(parts) != 3 {
314 return &ParserError{
315 Summary: "Invalid provider address format",
316 Detail: `Expected FQN in the format "hostname/namespace/name"`,
317 }
318 }
319
320 p, err := ParseProviderSource(raw)
321 if err != nil {
322 return err
323 }
324
325 if !p.HasKnownNamespace() {
326 return &ParserError{
327 Summary: "Unknown provider namespace",
328 Detail: `Expected FQN in the format "hostname/namespace/name"`,
329 }
330 }
331
332 if !p.IsLegacy() {
333 return &ParserError{
334 Summary: "Invalid legacy provider namespace",
335 Detail: `Expected FQN in the format "hostname/namespace/name"`,
336 }
337 }
338
339 return nil
340 }
341
342 func parseSourceStringParts(str string) ([]string, error) {
343 // split the source string into individual components
344 parts := strings.Split(str, "/")
345 if len(parts) == 0 || len(parts) > 3 {
346 return nil, &ParserError{
347 Summary: "Invalid provider source string",
348 Detail: `The "source" attribute must be in the format "[hostname/][namespace/]name"`,
349 }
350 }
351
352 // check for an invalid empty string in any part
353 for i := range parts {
354 if parts[i] == "" {
355 return nil, &ParserError{
356 Summary: "Invalid provider source string",
357 Detail: `The "source" attribute must be in the format "[hostname/][namespace/]name"`,
358 }
359 }
360 }
361
362 // check the 'name' portion, which is always the last part
363 givenName := parts[len(parts)-1]
364 name, err := ParseProviderPart(givenName)
365 if err != nil {
366 return nil, &ParserError{
367 Summary: "Invalid provider type",
368 Detail: fmt.Sprintf(`Invalid provider type %q in source %q: %s"`, givenName, str, err),
369 }
370 }
371 parts[len(parts)-1] = name
372
373 return parts, nil
374 }
375
376 // ParseProviderPart processes an addrs.Provider namespace or type string
377 // provided by an end-user, producing a normalized version if possible or
378 // an error if the string contains invalid characters.
379 //
380 // A provider part is processed in the same way as an individual label in a DNS
381 // domain name: it is transformed to lowercase per the usual DNS case mapping
382 // and normalization rules and may contain only letters, digits, and dashes.
383 // Additionally, dashes may not appear at the start or end of the string.
384 //
385 // These restrictions are intended to allow these names to appear in fussy
386 // contexts such as directory/file names on case-insensitive filesystems,
387 // repository names on GitHub, etc. We're using the DNS rules in particular,
388 // rather than some similar rules defined locally, because the hostname part
389 // of an addrs.Provider is already a hostname and it's ideal to use exactly
390 // the same case folding and normalization rules for all of the parts.
391 //
392 // In practice a provider type string conventionally does not contain dashes
393 // either. Such names are permitted, but providers with such type names will be
394 // hard to use because their resource type names will not be able to contain
395 // the provider type name and thus each resource will need an explicit provider
396 // address specified. (A real-world example of such a provider is the
397 // "google-beta" variant of the GCP provider, which has resource types that
398 // start with the "google_" prefix instead.)
399 //
400 // It's valid to pass the result of this function as the argument to a
401 // subsequent call, in which case the result will be identical.
402 func ParseProviderPart(given string) (string, error) {
403 if len(given) == 0 {
404 return "", fmt.Errorf("must have at least one character")
405 }
406
407 // We're going to process the given name using the same "IDNA" library we
408 // use for the hostname portion, since it already implements the case
409 // folding rules we want.
410 //
411 // The idna library doesn't expose individual label parsing directly, but
412 // once we've verified it doesn't contain any dots we can just treat it
413 // like a top-level domain for this library's purposes.
414 if strings.ContainsRune(given, '.') {
415 return "", fmt.Errorf("dots are not allowed")
416 }
417
418 // We don't allow names containing multiple consecutive dashes, just as
419 // a matter of preference: they look weird, confusing, or incorrect.
420 // This also, as a side-effect, prevents the use of the "punycode"
421 // indicator prefix "xn--" that would cause the IDNA library to interpret
422 // the given name as punycode, because that would be weird and unexpected.
423 if strings.Contains(given, "--") {
424 return "", fmt.Errorf("cannot use multiple consecutive dashes")
425 }
426
427 result, err := idna.Lookup.ToUnicode(given)
428 if err != nil {
429 return "", fmt.Errorf("must contain only letters, digits, and dashes, and may not use leading or trailing dashes")
430 }
431
432 return result, nil
433 }
434
435 // MustParseProviderPart is a wrapper around ParseProviderPart that panics if
436 // it returns an error.
437 func MustParseProviderPart(given string) string {
438 result, err := ParseProviderPart(given)
439 if err != nil {
440 panic(err.Error())
441 }
442 return result
443 }