diff --git a/README.md b/README.md index 5bc27cc..5d8a8f5 100644 --- a/README.md +++ b/README.md @@ -334,6 +334,56 @@ In a worktree, run `ddev hostshift check` rather than the bare one. The bare command resolves *this* checkout's hostnames — not the ones the database holds — and reports that map as valid. +### Reading the map from a program + +`hostshift map --json` prints the resolved sites, and says which layer they +came from — `file`, `ddev` or `flags` — and where: + +```console +$ git show origin/master:hostshift.yaml | hostshift map --json --file - +{ + "layer": "file", + "source": "stdin", + "sites": [ + { + "name": "main", + "canonical": "https://www.example.com", + "base": "https://acme.ddev.site", + "aliases": [ + "https://acme.ddev.site", + "https://acme.staging.example.net" + ] + }, + { + "name": "shop", + "canonical": "https://shop.example.com", + "base": "https://shop.acme.ddev.site", + "aliases": [ + "https://shop.acme.ddev.site" + ] + } + ] +} +``` + +It needs no `--slug`. Without one there is no variant to derive, so `variant` +is left out and the sites are a listing rather than a validated map; every +origin in it has still been parsed as one, so each is a bare `http` or `https` +scheme and host. Pass `--slug` and each site carries its variant, and the map +is checked exactly as `check` checks it. `aliases` is what rewrites to the +variant besides the canonical, so it includes `base`. `base` is the origin the +variant derives from — the canonical where the file declares none, absent for +a `--map` pair, which derives nothing. + +`--file` reads a hostshift.yaml other than the checkout's, and `--file -` +reads it from stdin, which is the form above: a program that has to trust the +map from one commit can hand hostshift that commit's file without writing it +into a working tree a branch can change. A named file that does not exist is +an error, not a fall-back to the DDEV layer. Every subcommand that resolves a +map takes it; `rewrite` refuses `-`, since its stdin is the body. + +`hostshift hosts --json` prints the same hostnames as `hosts`, as one array. + ## The database — required, and hostshift does not choose it **DDEV gives a new worktree an empty database of its own**, so the first thing diff --git a/cmd/hostshift/main.go b/cmd/hostshift/main.go index f5f9aa8..7576e8d 100644 --- a/cmd/hostshift/main.go +++ b/cmd/hostshift/main.go @@ -21,6 +21,7 @@ import ( "net/url" "os" "os/signal" + "runtime/debug" "sort" "strings" "syscall" @@ -61,6 +62,7 @@ no knowledge of any CMS. That work is opinionated and belongs to whatever knows the stack — for DDEV, the add-on, as "ddev hostshift". -C dir project directory (default ".") + --file path the hostshift.yaml to read instead of the project's; - is stdin --slug derive each variant by prefixing the leftmost label of its canonical host --upstream upstream base URL, e.g. http://web:80 @@ -72,6 +74,15 @@ the stack — for DDEV, the add-on, as "ddev hostshift". // and no build would have failed. var version = "dev" +// `go install …@v0.3.0`, the README's other install path, sets no -X flag but +// does record the module version, so a caller checking for a minimum version +// gets a real answer rather than "dev". +func init() { + if bi, ok := debug.ReadBuildInfo(); ok && version == "dev" && strings.HasPrefix(bi.Main.Version, "v") { + version = bi.Main.Version + } +} + // exit codes, per PLAN §5.8 const ( exitOK = 0 @@ -187,12 +198,15 @@ func (p pairFlag) Set(v string) error { // common holds the flags every map-using subcommand shares. type common struct { dir string + file string slug, upstream string from, to repeatable + anyVariant bool } func (c *common) register(fs *flag.FlagSet) { fs.StringVar(&c.dir, "C", ".", "project directory") + fs.StringVar(&c.file, "file", "", "hostshift.yaml to read instead of the project's; - reads it from stdin") fs.StringVar(&c.slug, "slug", "", "worktree slug used to derive variant hosts") fs.StringVar(&c.upstream, "upstream", "", "upstream base URL, e.g. http://web:80") fs.Var(&c.from, "from", "canonical origin, repeatable, index-aligned with --to") @@ -202,10 +216,12 @@ func (c *common) register(fs *flag.FlagSet) { func (c *common) load() (*config.Resolved, error) { return config.Load(c.dir, config.Flags{ - Upstream: c.upstream, - Slug: c.slug, - From: c.from, - To: c.to, + Upstream: c.upstream, + Slug: c.slug, + From: c.from, + To: c.to, + File: c.file, + VariantOptional: c.anyVariant, }) } @@ -250,6 +266,9 @@ func cmdRewrite(args []string) (int, error) { if err != nil { return exitConfig, err } + if c.file == "-" { + return exitConfig, errors.New("--file -: stdin is the body this command rewrites; name the file instead") + } res, err := c.load() if err != nil { return exitConfig, err @@ -556,6 +575,7 @@ func cmdProxy(args []string) (int, error) { func cmdHosts(args []string) (int, error) { fs := flag.NewFlagSet("hosts", flag.ContinueOnError) dir := fs.String("C", ".", "project directory") + asJSON := fs.Bool("json", false, "emit the hostnames as a JSON array") if describe(fs, args, "print the hostnames a project declares, one per line") { return exitOK, nil } @@ -579,6 +599,12 @@ func cmdHosts(args []string) (int, error) { return exitConfig, fmt.Errorf("%s declares %q, which is not a hostname: %w", ddev.Path(*dir), h, err) } } + if *asJSON { + if err := json.NewEncoder(os.Stdout).Encode(proj.Hosts); err != nil { + return exitRuntime, err + } + return exitOK, nil + } for _, h := range proj.Hosts { fmt.Println(h) } @@ -644,6 +670,9 @@ func cmdMap(args []string) (int, error) { if err := fs.Parse(args); err != nil { return exitConfig, nil } + // A listing of the sites needs no slug: without one each site is printed + // with no variant, and the map is not validated as one. + c.anyVariant = *asJSON res, err := c.load() if err != nil { return exitConfig, err @@ -703,16 +732,27 @@ func cmdMap(args []string) (int, error) { type site struct { Name string `json:"name"` Canonical string `json:"canonical"` + Base string `json:"base,omitempty"` Aliases []string `json:"aliases,omitempty"` - Variant string `json:"variant"` + Variant string `json:"variant,omitempty"` + } + out := struct { + Layer string `json:"layer"` + Source string `json:"source"` + Sites []site `json:"sites"` + }{Layer: res.Layer, Source: res.Source, Sites: make([]site, 0, len(res.Map.Sites))} + str := func(o origin.Origin) string { + if o.Host == "" { + return "" + } + return o.String() } - out := make([]site, 0, len(res.Map.Sites)) for _, s := range res.Map.Sites { - e := site{Name: s.Name, Canonical: s.Canonical.String(), Variant: s.Variant.String()} + e := site{Name: s.Name, Canonical: s.Canonical.String(), Base: str(s.Base), Variant: str(s.Variant)} for _, a := range s.Aliases { e.Aliases = append(e.Aliases, a.String()) } - out = append(out, e) + out.Sites = append(out.Sites, e) } enc := json.NewEncoder(os.Stdout) enc.SetIndent("", " ") diff --git a/cmd/hostshift/map_json_test.go b/cmd/hostshift/map_json_test.go new file mode 100644 index 0000000..6e64d0f --- /dev/null +++ b/cmd/hostshift/map_json_test.go @@ -0,0 +1,122 @@ +package main + +import ( + "encoding/json" + "strings" + "testing" +) + +const prodYAML = `version: 1 +sites: + - name: main + canonical: https://www.example.com + base: https://acme.ddev.site + aliases: [https://acme.staging.example.net] + - name: shop + canonical: https://shop.example.com + base: https://shop.acme.ddev.site +` + +type mapJSON struct { + Layer, Source string + Sites []struct { + Name, Canonical, Base, Variant string + Aliases []string + } +} + +func decodeMap(t *testing.T, out string) mapJSON { + t.Helper() + var m mapJSON + if err := json.Unmarshal([]byte(out), &m); err != nil { + t.Fatalf("%v:\n%s", err, out) + } + return m +} + +// `map --json` lists the sites without a slug, so a caller can read a +// hostshift.yaml's canonicals and bases without deciding a variant; with one, +// each site carries its variant too. +func TestMapJSONListsSitesWithoutASlug(t *testing.T) { + dir := t.TempDir() + writeFile(t, dir, "hostshift.yaml", prodYAML) + + code, out, errOut := run(t, "", cmdMap, "-C", dir, "--json") + if code != exitOK { + t.Fatalf("exit %d: %s", code, errOut) + } + m := decodeMap(t, out) + if m.Layer != "file" || !strings.HasSuffix(m.Source, "hostshift.yaml") || len(m.Sites) != 2 { + t.Fatalf("%+v", m) + } + s := m.Sites[0] + if s.Name != "main" || s.Canonical != "https://www.example.com" || s.Base != "https://acme.ddev.site" || + s.Variant != "" || len(s.Aliases) != 2 { + t.Errorf("site 1: %+v", s) + } + if strings.Contains(out, `"variant"`) { + t.Errorf("a variant without a slug:\n%s", out) + } + + _, out, _ = run(t, "", cmdMap, "-C", dir, "--json", "--slug", "wt-a") + if v := decodeMap(t, out).Sites[1].Variant; v != "https://wt-a--shop.acme.ddev.site" { + t.Errorf("variant = %q", v) + } + + // Without --json a missing slug is still an error. + if code, _, errOut := run(t, "", cmdMap, "-C", dir); code != exitConfig || !strings.Contains(errOut, "no variant") { + t.Errorf("exit %d: %s", code, errOut) + } +} + +// --file reads a hostshift.yaml other than the project's, and - reads it from +// stdin: the project's own copy is not consulted. +func TestMapFileOverridesTheProjects(t *testing.T) { + dir := t.TempDir() + writeFile(t, dir, "hostshift.yaml", strings.ReplaceAll(prodYAML, "www.example.com", "www.example.org")) + writeFile(t, dir, "other.yaml", prodYAML) + + _, out, _ := run(t, prodYAML, cmdMap, "-C", dir, "--json", "--file", "-") + if m := decodeMap(t, out); m.Source != "stdin" || m.Sites[0].Canonical != "https://www.example.com" { + t.Errorf("stdin: %+v", m) + } + _, out, _ = run(t, "", cmdMap, "-C", dir, "--json", "--file", dir+"/other.yaml") + if m := decodeMap(t, out); m.Source != dir+"/other.yaml" || m.Sites[0].Canonical != "https://www.example.com" { + t.Errorf("file: %+v", m) + } + // A named file that is not there is an error, not a fall-back. + if code, _, _ := run(t, "", cmdMap, "-C", dir, "--json", "--file", dir+"/missing.yaml"); code != exitConfig { + t.Errorf("missing file: exit %d", code) + } + // Only plain origins: a path is refused, as everywhere else. + bad := strings.Replace(prodYAML, "https://shop.example.com", "https://shop.example.com/x", 1) + if code, _, errOut := run(t, bad, cmdMap, "--json", "--file", "-"); code != exitConfig || !strings.Contains(errOut, "no path") { + t.Errorf("path: exit %d: %s", code, errOut) + } + // rewrite reads its body from stdin, so it cannot take the file there too. + if code, _, _ := run(t, "x", cmdRewrite, "--file", "-"); code != exitConfig { + t.Errorf("rewrite --file -: exit %d", code) + } +} + +// The layer says which of the three the map came from. +func TestMapJSONLayer(t *testing.T) { + dir := t.TempDir() + writeFile(t, dir, ".ddev/config.yaml", "name: acme\n") + _, out, _ := run(t, "", cmdMap, "-C", dir, "--json") + if m := decodeMap(t, out); m.Layer != "ddev" || m.Sites[0].Base != "https://acme.ddev.site" { + t.Errorf("ddev: %+v", m) + } + _, out, _ = run(t, "", cmdMap, "-C", dir, "--json", "--map", "https://a.example=https://b.example") + if m := decodeMap(t, out); m.Layer != "flags" || m.Sites[0].Base != "" { + t.Errorf("flags: %+v", m) + } +} + +func TestHostsJSON(t *testing.T) { + dir := t.TempDir() + writeFile(t, dir, ".ddev/config.yaml", "name: site\nadditional_hostnames:\n - blog\n") + if _, out, _ := run(t, "", cmdHosts, "-C", dir, "--json"); out != `["site.ddev.site","blog.ddev.site"]`+"\n" { + t.Errorf("out = %q", out) + } +} diff --git a/internal/config/config.go b/internal/config/config.go index bd70690..faa7907 100644 --- a/internal/config/config.go +++ b/internal/config/config.go @@ -56,6 +56,14 @@ type Flags struct { Slug string // From/To are an explicit index-aligned map that replaces the files entirely. From, To []string + // File is the hostshift.yaml to read instead of /hostshift.yaml, "-" + // for stdin. Unlike the default it must exist: naming a file that is not + // there falling back to the DDEV layer would be a silent change of map. + File string + // VariantOptional resolves the sites even when there is no slug to derive + // a variant from; those sites keep a zero Variant and the Map is then a + // listing that was never validated as a map, for `map --json` only. + VariantOptional bool } // Resolved is everything the proxy needs. @@ -63,6 +71,7 @@ type Resolved struct { Map *origin.Map Upstream string Source string // where the map came from, for diagnostics + Layer string // which layer that was: "file", "ddev" or "flags" // Uncovered lists hostnames DDEV registers for this project that the map // does not mention, so they have no variant and cannot be reached here — a @@ -132,7 +141,7 @@ func resolve(dir string, f Flags) (*Resolved, error) { if err != nil { return nil, err } - res := &Resolved{Map: m, Upstream: f.Upstream, Source: "--from/--to"} + res := &Resolved{Map: m, Upstream: f.Upstream, Source: "--from/--to", Layer: "flags"} // Best-effort: outside a DDEV project there is nothing to compare the // map against, and that is not an error — `hostshift` runs anywhere. if proj, err := ddev.Load(dir); err == nil { @@ -145,6 +154,7 @@ func resolve(dir string, f Flags) (*Resolved, error) { sites []origin.Site up = f.Upstream source string + layer string pattern = DefaultVariantPattern ) @@ -163,11 +173,11 @@ func resolve(dir string, f Flags) (*Resolved, error) { return nil, err } - switch hf, path, err := loadFile(dir); { + switch hf, path, err := loadFile(dir, f.File); { case err != nil: return nil, err case hf != nil: - source = path + source, layer = path, "file" if hf.Variant.Pattern != "" { pattern = hf.Variant.Pattern } @@ -183,17 +193,27 @@ func resolve(dir string, f Flags) (*Resolved, error) { if proj == nil { return nil, fmt.Errorf("no map: found neither hostshift.yaml nor .ddev/config.yaml in %s, and no --from/--to given", dir) } - source = ddev.Path(dir) + " (DDEV defaults)" + source, layer = ddev.Path(dir)+" (DDEV defaults)", "ddev" if sites, err = sitesFromHosts(proj.Hosts, pattern, f.Slug); err != nil { return nil, err } } - m, err2 := origin.NewMap(sites) - if err = err2; err != nil { - return nil, err + var m *origin.Map + for _, s := range sites { + if s.Variant.Host == "" { + if !f.VariantOptional { + return nil, fmt.Errorf("site %q: no variant — pass --slug, or declare `variant:` on the site", s.Name) + } + m = &origin.Map{Sites: sites} + } + } + if m == nil { + if m, err = origin.NewMap(sites); err != nil { + return nil, err + } } - res := &Resolved{Map: m, Upstream: up, Source: source} + res := &Resolved{Map: m, Upstream: up, Source: source, Layer: layer} // A hostshift.yaml *replaces* the DDEV layer rather than merging with it: // an explicit map is a statement about which hosts this project serves, and @@ -322,7 +342,7 @@ func mapFromFlags(f Flags) (*origin.Map, error) { if err != nil { return nil, err } - sites = append(sites, origin.Site{Name: name, Canonical: c, Variant: v}) + sites = append(sites, origin.Site{Name: name, Canonical: c, Base: c, Variant: v}) } return origin.NewMap(sites) } @@ -344,11 +364,23 @@ func mapFromFlags(f Flags) (*origin.Map, error) { return origin.NewMap(sites) } -func loadFile(dir string) (*File, string, error) { +func loadFile(dir, file string) (*File, string, error) { path := filepath.Join(dir, "hostshift.yaml") - b, err := os.ReadFile(path) - if os.IsNotExist(err) { - return nil, "", nil + var ( + b []byte + err error + ) + switch file { + case "": + if b, err = os.ReadFile(path); os.IsNotExist(err) { + return nil, "", nil + } + case "-": + path = "stdin" + b, err = io.ReadAll(os.Stdin) + default: + path = file + b, err = os.ReadFile(path) } if err != nil { return nil, "", err @@ -415,13 +447,19 @@ func sitesFromFile(f *File, pattern, slug string) ([]origin.Site, error) { if err != nil { return nil, err } - sites = append(sites, origin.Site{Name: name, Canonical: canonical, Aliases: aliases, Variant: variant}) + base := canonical + if s.Base != "" { + base, _ = origin.Parse(s.Base) // parsed above, as an alias + } + sites = append(sites, origin.Site{Name: name, Canonical: canonical, Base: base, Aliases: aliases, Variant: variant}) } return sites, nil } // deriveVariant applies the pattern to the leftmost label of base. An explicit -// variant: on the site wins; base falls back to canonical when absent. +// variant: on the site wins; base falls back to canonical when absent. With no +// slug it returns the zero Origin, which resolve refuses unless the caller asked +// for a listing (Flags.VariantOptional). func deriveVariant(explicit, base, canonical, pattern, slug, name string) (origin.Origin, error) { if explicit != "" { return origin.Parse(explicit) @@ -435,7 +473,7 @@ func deriveVariant(explicit, base, canonical, pattern, slug, name string) (origi return origin.Origin{}, fmt.Errorf("site %q: %w", name, err) } if slug == "" { - return origin.Origin{}, fmt.Errorf("site %q: no variant — pass --slug, or declare `variant:` on the site", name) + return origin.Origin{}, nil } host, err := applyPattern(pattern, slug, o.Host) if err != nil { @@ -566,7 +604,7 @@ func sitesFromHosts(hosts []string, pattern, slug string) ([]origin.Site, error) if err != nil { return nil, err } - sites = append(sites, origin.Site{Name: name, Canonical: c, Variant: v}) + sites = append(sites, origin.Site{Name: name, Canonical: c, Base: c, Variant: v}) } return sites, nil } diff --git a/internal/origin/hostmap.go b/internal/origin/hostmap.go index 60c690a..660b3ca 100644 --- a/internal/origin/hostmap.go +++ b/internal/origin/hostmap.go @@ -17,8 +17,12 @@ import ( type Site struct { Name string Canonical Origin - Aliases []Origin - Variant Origin + // Base is the origin the variant derives from: hostshift.yaml's `base:`, + // else the canonical; zero for a --map pair, which derives nothing. It is + // already in Aliases when it differs from Canonical; this is for reporting. + Base Origin + Aliases []Origin + Variant Origin } // CanonicalSet is every origin that rewrites to this site's variant.