Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
44 changes: 42 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -519,6 +519,45 @@ summarised below. Two things become required with it:

Neither is needed when the database already holds DDEV hostnames.

### Which side the database holds — `--holds`

A committed production-canonical file describes the sites, not the database
in front of you. A worktree's data comes from somewhere: a pristine production
dump holds each site's `canonical`, `ddev hostshift copy-db` from a parent whose
pull search-replaced to `.ddev.site` holds each site's `base`, and a staging
pull holds its staging alias. Mapped from the wrong side, the app is handed a
hostname its data does not name, and one that checks the Host redirects every
page to the one it does — a copy-db worktree of a production-canonical repo
301s to the parent.

So say which side, and keep the one file:

```
ddev hostshift init --holds base # copy-db, or any search-replaced pull
ddev hostshift init --holds alias # a staging pull
ddev hostshift init --holds canonical # a production dump; the default
```

`base` and `canonical` are the fields of that name; `alias` is the one alias a
site declares besides its base, and refuses a site with none or several rather
than guess. The variant does not move — it is always derived from `base` — so
the preview URL is the same whichever side the data is on.

The side is recorded as `HOSTSHIFT_HOLDS` in `.ddev/.env`, the way a chosen
slug is, so `check`, the post-start hook and a later bare `init` resolve the
same map; `--holds canonical` goes back and records nothing. `copy-db` says so
when it has just put the bases into a worktree mapped on its canonicals.

Off the canonical side the proxy gets a flat `--from`/`--to` map — the held
origin of each site against its variant — rather than reading the mounted file,
because the published image predates the flag. A flat map carries no aliases,
so a URL in the copy naming one of the site's other origins passes through
unrewritten, as it did before the repo committed the file. `--holds base`
without a `hostshift.yaml` is accepted and changes nothing: the map is the
parent's DDEV hostnames already. The binary takes the same flag
(`hostshift map --holds base --pairs`), and there it keeps the other origins as
aliases.

## Reference

```
Expand All @@ -542,8 +581,9 @@ ddev hostshift env print what init would write, without writing
ddev hostshift wp-cli emit wp-cli.local.yml on stdout
```

`--slug NAME` overrides the slug derived from the git branch. `--dry-run` shows
what `init` would write without writing it.
`--slug NAME` overrides the slug derived from the git branch. `--holds SIDE`
says which of `hostshift.yaml`'s origins the database holds (above). `--dry-run`
shows what `init` would write without writing it.

Flags worth knowing:

Expand Down
5 changes: 5 additions & 0 deletions cmd/hostshift/main.go
Original file line number Diff line number Diff line change
Expand Up @@ -201,6 +201,7 @@ type common struct {
file string
slug, upstream string
from, to repeatable
holds string
anyVariant bool
}

Expand All @@ -212,6 +213,9 @@ func (c *common) register(fs *flag.FlagSet) {
fs.Var(&c.from, "from", "canonical origin, repeatable, index-aligned with --to")
fs.Var(&c.to, "to", "variant origin, repeatable, index-aligned with --from")
fs.Var(pairFlag{&c.from, &c.to}, "map", "canonical=variant, repeatable")
fs.StringVar(&c.holds, "holds", "",
"which of each hostshift.yaml site's origins the database holds:\n"+
"canonical (the default), base, or alias (its one alias besides base)")
}

func (c *common) load() (*config.Resolved, error) {
Expand All @@ -221,6 +225,7 @@ func (c *common) load() (*config.Resolved, error) {
From: c.from,
To: c.to,
File: c.file,
Holds: c.holds,
VariantOptional: c.anyVariant,
})
}
Expand Down
53 changes: 53 additions & 0 deletions cmd/hostshift/map_json_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -99,6 +99,59 @@ func TestMapFileOverridesTheProjects(t *testing.T) {
}
}

// --holds picks which declared origin of each site is the canonical side: the
// same file maps a production dump, a copy of the main checkout's database and
// a staging pull, and the variant stays where it is.
func TestMapHolds(t *testing.T) {
dir := t.TempDir()
writeFile(t, dir, "hostshift.yaml", prodYAML)
pairs := func(holds string) (int, string, string) {
return run(t, "", cmdMap, "-C", dir, "--slug", "wt-a", "--pairs", "--holds", holds)
}

for holds, want := range map[string]string{
"canonical": "https://www.example.com=https://wt-a--acme.ddev.site\nhttps://shop.example.com=https://wt-a--shop.acme.ddev.site\n",
"base": "https://acme.ddev.site=https://wt-a--acme.ddev.site\nhttps://shop.acme.ddev.site=https://wt-a--shop.acme.ddev.site\n",
} {
if code, out, errOut := pairs(holds); code != exitOK || out != want {
t.Errorf("--holds %s: exit %d: %q %s", holds, code, out, errOut)
}
}

// The origin it replaces stays in the map as an alias, so a production URL
// left in a copied database still rewrites to the variant.
_, out, _ := run(t, "", cmdMap, "-C", dir, "--json", "--holds", "base")
s := decodeMap(t, out).Sites[0]
if s.Canonical != "https://acme.ddev.site" || s.Base != "https://acme.ddev.site" ||
strings.Join(s.Aliases, " ") != "https://www.example.com https://acme.staging.example.net" {
t.Errorf("--holds base: %+v", s)
}

// An alias only where a site declares exactly one: the shop declares none.
if code, _, errOut := pairs("alias"); code != exitConfig || !strings.Contains(errOut, `site "shop": --holds alias, but it declares no alias`) {
t.Errorf("alias, none: exit %d: %s", code, errOut)
}
two := strings.Replace(prodYAML, "aliases: [https://acme.staging.example.net]", "aliases: [https://acme.staging.example.net, https://acme.test.example.net]", 1)
staged := two + " aliases: [https://shop.staging.example.net]\n"
writeFile(t, dir, "hostshift.yaml", staged)
if code, _, errOut := pairs("alias"); code != exitConfig || !strings.Contains(errOut, "ambiguous") {
t.Errorf("alias, two: exit %d: %s", code, errOut)
}
writeFile(t, dir, "hostshift.yaml", prodYAML+" aliases: [https://shop.staging.example.net]\n")
want := "https://acme.staging.example.net=https://wt-a--acme.ddev.site\nhttps://shop.staging.example.net=https://wt-a--shop.acme.ddev.site\n"
if code, out, errOut := pairs("alias"); code != exitOK || out != want {
t.Errorf("--holds alias: exit %d: %q %s", code, out, errOut)
}

// No file, no aliases to hold; and a side that is not one is refused.
if code, _, errOut := run(t, "", cmdMap, "--slug", "wt-a", "--from", "https://a.ddev.site", "--holds", "alias"); code != exitConfig || !strings.Contains(errOut, "declares no aliases") {
t.Errorf("flags: exit %d: %s", code, errOut)
}
if code, _, errOut := pairs("staging"); code != exitConfig || !strings.Contains(errOut, "canonical, base or alias") {
t.Errorf("bad side: exit %d: %s", code, errOut)
}
}

// The layer says which of the three the map came from.
func TestMapJSONLayer(t *testing.T) {
dir := t.TempDir()
Expand Down
96 changes: 90 additions & 6 deletions ddev/commands/host/hostshift
Original file line number Diff line number Diff line change
Expand Up @@ -57,7 +57,9 @@ usage: ddev hostshift <command> [flags]

--slug NAME name this worktree's hostnames; recorded, and it sticks
--slug-from-branch forget a recorded slug and follow the branch again
--dry-run, -n say what would happen, write nothing
--holds SIDE which of hostshift.yaml's origins the database holds:
canonical (the default), base or alias; recorded
--dry-run, -n say what would happen, write nothing
--no-restart init: write the file and stop, for a pre-start hook
--force copy-db: overwrite a database that has tables
--quiet, -q say nothing when there is nothing to check
Expand All @@ -76,6 +78,7 @@ fi
slug=""
slug_explicit=""
forget_slug=""
holds=""
branch=""
dry_run=""
no_restart=""
Expand All @@ -97,6 +100,11 @@ while [ $# -gt 0 ]; do
# recording it — so without this the only way to return to branch-derived
# naming is to hand-edit .ddev/.env.
--slug-from-branch) forget_slug=1; shift ;;
# Both spellings, for the reason --slug gives above.
--holds) holds="${2:?--holds needs a value}"; shift 2 ;;
--holds=*) holds="${1#*=}"
[ -n "$holds" ] || { echo "--holds needs a value" >&2; exit 2; }
shift ;;
--dry-run|-n) dry_run=1; shift ;;
--no-restart) no_restart=1; shift ;;
--quiet|-q) quiet=1; shift ;;
Expand Down Expand Up @@ -308,6 +316,41 @@ case "$slug" in
exit 2 ;;
esac

# Which side of hostshift.yaml the database holds, recorded like a chosen slug.
#
# The file declares each site once — canonical, base, aliases — and which of
# those a database holds depends on where *that copy* came from, not on the
# site: a pristine production dump holds the canonicals, `copy-db` from a
# search-replaced parent holds the bases, a staging pull holds the aliases. With
# the file mounted, the proxy maps the canonicals and nothing else, so a copy of
# the parent's database 301'd every page to the parent's hostname — an app that
# checks the Host it is handed against the hostname its data names redirects.
#
# Recorded in .ddev/.env, for the reason HOSTSHIFT_SLUG_CHOSEN is: `check`, the
# post-start hook and a later bare `init` must resolve the same side the
# database was deployed with, or they call a correct deployment stale and
# "fix" it back onto the wrong side. `--holds canonical` is the way back, and
# records nothing because it is the default.
if [ -z "$holds" ] && [ "$cmd" != "copy-db" ]; then
holds="$(sed -n '/^HOSTSHIFT_HOLDS=/{s///p;q;}' .ddev/.env 2>/dev/null | tr -d '\r' || true)"
fi
case "${holds:-canonical}" in
canonical|base|alias) ;;
*) echo "hostshift: --holds $holds: say canonical, base or alias" >&2; exit 2 ;;
esac
[ "$holds" = canonical ] && holds=""
# Without a hostshift.yaml the map already is the base side — the parent's DDEV
# hostnames, which is what the database holds after `copy-db` — so `base` is
# accepted as a no-op, and a caller that knows only where its data came from can
# say so without first asking whether the repo has the file. The other two name
# origins only the file declares.
if [ ! -f hostshift.yaml ] && [ -n "$holds" ] && [ "$holds" != base ] && [ "$cmd" != "copy-db" ]; then
echo "hostshift: --holds $holds needs a hostshift.yaml to say which hostnames those" >&2
echo " are, and this checkout has none. Without one the map is the parent's" >&2
echo " DDEV hostnames, which is --holds base." >&2
exit 2
fi

# What this project answers to. `hostshift hosts` reads the DDEV config with
# its config.*.yaml override merging — parsing that here would be the place the
# careful parts get lost.
Expand Down Expand Up @@ -673,6 +716,15 @@ if [ "$cmd" = "copy-db" ]; then
echo " or re-run the copy once $from is up, which replaces it outright." >&2
fi
exit 1; }
# Not "nothing else to do" when a hostshift.yaml is here. The file's canonical
# side is usually production, and the copy holds $from's DDEV hostnames — its
# bases — so a map left on the canonicals 301s every page to the parent.
if [ -f hostshift.yaml ] && ! grep -q '^HOSTSHIFT_HOLDS=base$' .ddev/.env 2>/dev/null; then
echo "hostshift: copied. It holds $from's hostnames — hostshift.yaml's" >&2
echo " \`base:\` side — so map that side:" >&2
echo " ddev hostshift init --holds base" >&2
exit 0
fi
echo "hostshift: copied. It still holds $from's hostnames, which is what" >&2
echo " hostshift maps — nothing else to do." >&2
exit 0
Expand All @@ -683,6 +735,37 @@ fi
# other environments, or production ones the database was never search-replaced
# away from. Passing --from would override it.
map_args=()
# ...which is exactly what --holds wants, and the only way to ask for it.
#
# The proxy image is :latest and older than this flag, and the compose file's
# rule is that nothing may ask it for a flag it does not have. --from/--to has
# worked since the first release, so the side is resolved here, on the host, and
# handed over as the flat map the no-file path already uses: the held origin of
# each site against its variant. `flat` routes everything below that keys on
# "is there a hostshift.yaml?" for the *proxy's* sake onto that path.
#
# The cost is the aliases. A flat list cannot carry them, so a URL in the copy
# naming one of the site's other origins — production, say, in a copy-db of a
# search-replaced database — passes through unrewritten, exactly as it did
# before the repo committed its hostshift.yaml.
flat=""
if [ -f hostshift.yaml ] && [ -n "$holds" ] && [ "$cmd" != "copy-db" ]; then
if ! held="$(hostshift map --slug "$slug" --holds "$holds" --pairs 2>&1)"; then
case "$held" in
*"flag provided but not defined: -holds"*)
echo "hostshift: --holds needs the hostshift CLI v0.4.0 or later on PATH." >&2
echo " https://github.com/generoi/hostshift/releases" >&2 ;;
*) printf '%s\n' "$held" >&2 ;;
esac
exit 2
fi
while IFS='=' read -r c v; do
[ -n "$c" ] || continue
map_args+=(--from "$c" --to "$v")
done <<<"$held"
[ "${#map_args[@]}" -gt 0 ] || { echo "hostshift: --holds $holds resolved no sites" >&2; exit 2; }
flat=1
fi
# The parent declares canonical hostnames this worktree cannot see.
#
# `hostshift hosts -C <dir>` reads the parent's *DDEV* config and nothing else,
Expand Down Expand Up @@ -1216,9 +1299,9 @@ done <<<"$hosts"
# So it is resolved here, on the host, where the parent checkout is readable, and
# handed over. Only when there is no hostshift.yaml: that file *is* mounted, it
# carries aliases a canonical=variant list cannot express, and the container
# reads it correctly.
# reads it correctly — for the canonical side. Any other side is flat too.
hsmap=""
if [ ! -f hostshift.yaml ]; then
if [ ! -f hostshift.yaml ] || [ -n "$flat" ]; then
# Repeated --from/--to, not `--map c=v,c=v`. Comma-separated --map is a flag
# form this branch added, and the image is :latest: the published binary splits
# the whole string on its first `=`, so a two-site map came out as one site
Expand Down Expand Up @@ -1368,7 +1451,8 @@ fi
# slug when run as printed, which in the case that motivates --slug at all is
# back onto the colliding name the collision warning told you to move off.
env_out="#ddev-silent-no-warn${slug_explicit:+
HOSTSHIFT_SLUG_CHOSEN=$slug}
HOSTSHIFT_SLUG_CHOSEN=$slug}${holds:+
HOSTSHIFT_HOLDS=$holds}
HOSTSHIFT_ARGS=$args
HOSTSHIFT_VARIANTS=$variants
HOSTSHIFT_WEB_HOSTS=$web"
Expand Down Expand Up @@ -1422,7 +1506,7 @@ if [ "$cmd" = "check" ]; then
# variable of the developer's own sharing the prefix — and the compose file
# reads HOSTSHIFT_* names, so that is how someone arrives at one.
deployed="$(grep -e '^HOSTSHIFT_ARGS=' -e '^HOSTSHIFT_VARIANTS=' -e '^HOSTSHIFT_WEB_HOSTS=' \
-e '^HOSTSHIFT_SLUG_CHOSEN=' -e '^#ddev-silent-no-warn' .ddev/.env | tr -d '\r' || true)"
-e '^HOSTSHIFT_SLUG_CHOSEN=' -e '^HOSTSHIFT_HOLDS=' -e '^#ddev-silent-no-warn' .ddev/.env | tr -d '\r' || true)"
if [ "$deployed" != "$env_out" ]; then
echo "hostshift: .ddev/.env is out of date. It says" >&2
printf '%s\n' "${deployed:- nothing}" >&2
Expand Down Expand Up @@ -2902,7 +2986,7 @@ trap 'rm -f "$tmp"' EXIT
# it meant it.
cp -p .ddev/.env "$tmp"
{ grep -v -e '^HOSTSHIFT_ARGS=' -e '^HOSTSHIFT_VARIANTS=' -e '^HOSTSHIFT_WEB_HOSTS=' \
-e '^HOSTSHIFT_SLUG_CHOSEN=' -e '^#ddev-silent-no-warn' .ddev/.env || true
-e '^HOSTSHIFT_SLUG_CHOSEN=' -e '^HOSTSHIFT_HOLDS=' -e '^#ddev-silent-no-warn' .ddev/.env || true
printf '%s\n' "$env_out"; } > "$tmp"
mv "$tmp" .ddev/.env

Expand Down
Loading
Loading