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