Debian Codegraph @

module.go

raw
1 package tfaddr
2
3 import (
4 "fmt"
5 "path"
6 "regexp"
7 "strings"
8
9 svchost "github.com/hashicorp/terraform-svchost"
10 )
11
12 // Module is representing a module listed in a Terraform module
13 // registry.
14 type Module struct {
15 // Package is the registry package that the target module belongs to.
16 // The module installer must translate this into a ModuleSourceRemote
17 // using the registry API and then take that underlying address's
18 // Package in order to find the actual package location.
19 Package ModulePackage
20
21 // If Subdir is non-empty then it represents a sub-directory within the
22 // remote package that the registry address eventually resolves to.
23 // This will ultimately become the suffix of the Subdir of the
24 // ModuleSourceRemote that the registry address translates to.
25 //
26 // Subdir uses a normalized forward-slash-based path syntax within the
27 // virtual filesystem represented by the final package. It will never
28 // include `../` or `./` sequences.
29 Subdir string
30 }
31
32 // DefaultModuleRegistryHost is the hostname used for registry-based module
33 // source addresses that do not have an explicit hostname.
34 const DefaultModuleRegistryHost = svchost.Hostname("registry.terraform.io")
35
36 var moduleRegistryNamePattern = regexp.MustCompile("^[0-9A-Za-z](?:[0-9A-Za-z-_]{0,62}[0-9A-Za-z])?$")
37 var moduleRegistryTargetSystemPattern = regexp.MustCompile("^[0-9a-z]{1,64}$")
38
39 // ParseModuleSource only accepts module registry addresses, and
40 // will reject any other address type.
41 func ParseModuleSource(raw string) (Module, error) {
42 var err error
43
44 var subDir string
45 raw, subDir = splitPackageSubdir(raw)
46 if strings.HasPrefix(subDir, "../") {
47 return Module{}, fmt.Errorf("subdirectory path %q leads outside of the module package", subDir)
48 }
49
50 parts := strings.Split(raw, "/")
51 // A valid registry address has either three or four parts, because the
52 // leading hostname part is optional.
53 if len(parts) != 3 && len(parts) != 4 {
54 return Module{}, fmt.Errorf("a module registry source address must have either three or four slash-separated components")
55 }
56
57 host := DefaultModuleRegistryHost
58 if len(parts) == 4 {
59 host, err = svchost.ForComparison(parts[0])
60 if err != nil {
61 // The svchost library doesn't produce very good error messages to
62 // return to an end-user, so we'll use some custom ones here.
63 switch {
64 case strings.Contains(parts[0], "--"):
65 // Looks like possibly punycode, which we don't allow here
66 // to ensure that source addresses are written readably.
67 return Module{}, fmt.Errorf("invalid module registry hostname %q; internationalized domain names must be given as direct unicode characters, not in punycode", parts[0])
68 default:
69 return Module{}, fmt.Errorf("invalid module registry hostname %q", parts[0])
70 }
71 }
72 if !strings.Contains(host.String(), ".") {
73 return Module{}, fmt.Errorf("invalid module registry hostname: must contain at least one dot")
74 }
75 // Discard the hostname prefix now that we've processed it
76 parts = parts[1:]
77 }
78
79 ret := Module{
80 Package: ModulePackage{
81 Host: host,
82 },
83
84 Subdir: subDir,
85 }
86
87 if host == svchost.Hostname("github.com") || host == svchost.Hostname("bitbucket.org") {
88 return ret, fmt.Errorf("can't use %q as a module registry host, because it's reserved for installing directly from version control repositories", host)
89 }
90
91 if ret.Package.Namespace, err = parseModuleRegistryName(parts[0]); err != nil {
92 if strings.Contains(parts[0], ".") {
93 // Seems like the user omitted one of the latter components in
94 // an address with an explicit hostname.
95 return ret, fmt.Errorf("source address must have three more components after the hostname: the namespace, the name, and the target system")
96 }
97 return ret, fmt.Errorf("invalid namespace %q: %s", parts[0], err)
98 }
99 if ret.Package.Name, err = parseModuleRegistryName(parts[1]); err != nil {
100 return ret, fmt.Errorf("invalid module name %q: %s", parts[1], err)
101 }
102 if ret.Package.TargetSystem, err = parseModuleRegistryTargetSystem(parts[2]); err != nil {
103 if strings.Contains(parts[2], "?") {
104 // The user was trying to include a query string, probably?
105 return ret, fmt.Errorf("module registry addresses may not include a query string portion")
106 }
107 return ret, fmt.Errorf("invalid target system %q: %s", parts[2], err)
108 }
109
110 return ret, nil
111 }
112
113 // MustParseModuleSource is a wrapper around ParseModuleSource that panics if
114 // it returns an error.
115 func MustParseModuleSource(raw string) (Module) {
116 mod, err := ParseModuleSource(raw)
117 if err != nil {
118 panic(err)
119 }
120 return mod
121 }
122
123 // parseModuleRegistryName validates and normalizes a string in either the
124 // "namespace" or "name" position of a module registry source address.
125 func parseModuleRegistryName(given string) (string, error) {
126 // Similar to the names in provider source addresses, we defined these
127 // to be compatible with what filesystems and typical remote systems
128 // like GitHub allow in names. Unfortunately we didn't end up defining
129 // these exactly equivalently: provider names can only use dashes as
130 // punctuation, whereas module names can use underscores. So here we're
131 // using some regular expressions from the original module source
132 // implementation, rather than using the IDNA rules as we do in
133 // ParseProviderPart.
134
135 if !moduleRegistryNamePattern.MatchString(given) {
136 return "", fmt.Errorf("must be between one and 64 characters, including ASCII letters, digits, dashes, and underscores, where dashes and underscores may not be the prefix or suffix")
137 }
138
139 // We also skip normalizing the name to lowercase, because we historically
140 // didn't do that and so existing module registries might be doing
141 // case-sensitive matching.
142 return given, nil
143 }
144
145 // parseModuleRegistryTargetSystem validates and normalizes a string in the
146 // "target system" position of a module registry source address. This is
147 // what we historically called "provider" but never actually enforced as
148 // being a provider address, and now _cannot_ be a provider address because
149 // provider addresses have three slash-separated components of their own.
150 func parseModuleRegistryTargetSystem(given string) (string, error) {
151 // Similar to the names in provider source addresses, we defined these
152 // to be compatible with what filesystems and typical remote systems
153 // like GitHub allow in names. Unfortunately we didn't end up defining
154 // these exactly equivalently: provider names can't use dashes or
155 // underscores. So here we're using some regular expressions from the
156 // original module source implementation, rather than using the IDNA rules
157 // as we do in ParseProviderPart.
158
159 if !moduleRegistryTargetSystemPattern.MatchString(given) {
160 return "", fmt.Errorf("must be between one and 64 ASCII letters or digits")
161 }
162
163 // We also skip normalizing the name to lowercase, because we historically
164 // didn't do that and so existing module registries might be doing
165 // case-sensitive matching.
166 return given, nil
167 }
168
169 // String returns a full representation of the address, including any
170 // additional components that are typically implied by omission in
171 // user-written addresses.
172 //
173 // We typically use this longer representation in error message, in case
174 // the inclusion of normally-omitted components is helpful in debugging
175 // unexpected behavior.
176 func (s Module) String() string {
177 if s.Subdir != "" {
178 return s.Package.String() + "//" + s.Subdir
179 }
180 return s.Package.String()
181 }
182
183 // ForDisplay is similar to String but instead returns a representation of
184 // the idiomatic way to write the address in configuration, omitting
185 // components that are commonly just implied in addresses written by
186 // users.
187 //
188 // We typically use this shorter representation in informational messages,
189 // such as the note that we're about to start downloading a package.
190 func (s Module) ForDisplay() string {
191 if s.Subdir != "" {
192 return s.Package.ForDisplay() + "//" + s.Subdir
193 }
194 return s.Package.ForDisplay()
195 }
196
197 // splitPackageSubdir detects whether the given address string has a
198 // subdirectory portion, and if so returns a non-empty subDir string
199 // along with the trimmed package address.
200 //
201 // If the given string doesn't have a subdirectory portion then it'll
202 // just be returned verbatim in packageAddr, with an empty subDir value.
203 func splitPackageSubdir(given string) (packageAddr, subDir string) {
204 packageAddr, subDir = sourceDirSubdir(given)
205 if subDir != "" {
206 subDir = path.Clean(subDir)
207 }
208 return packageAddr, subDir
209 }
210
211 // sourceDirSubdir takes a source URL and returns a tuple of the URL without
212 // the subdir and the subdir.
213 //
214 // ex:
215 // dom.com/path/?q=p => dom.com/path/?q=p, ""
216 // proto://dom.com/path//*?q=p => proto://dom.com/path?q=p, "*"
217 // proto://dom.com/path//path2?q=p => proto://dom.com/path?q=p, "path2"
218 func sourceDirSubdir(src string) (string, string) {
219 // URL might contains another url in query parameters
220 stop := len(src)
221 if idx := strings.Index(src, "?"); idx > -1 {
222 stop = idx
223 }
224
225 // Calculate an offset to avoid accidentally marking the scheme
226 // as the dir.
227 var offset int
228 if idx := strings.Index(src[:stop], "://"); idx > -1 {
229 offset = idx + 3
230 }
231
232 // First see if we even have an explicit subdir
233 idx := strings.Index(src[offset:stop], "//")
234 if idx == -1 {
235 return src, ""
236 }
237
238 idx += offset
239 subdir := src[idx+2:]
240 src = src[:idx]
241
242 // Next, check if we have query parameters and push them onto the
243 // URL.
244 if idx = strings.Index(subdir, "?"); idx > -1 {
245 query := subdir[idx:]
246 subdir = subdir[:idx]
247 src += query
248 }
249
250 return src, subdir
251 }