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
17 changes: 16 additions & 1 deletion docs/developer/plugins.md
Original file line number Diff line number Diff line change
Expand Up @@ -89,7 +89,8 @@ datumctl plugin remove compute
catalog, or in the catalog named by `--index`. It upgrades plugins that are
behind the catalog, leaves up-to-date ones alone, and skips a plugin whose name
is already installed from another catalog or from GitHub rather than replace
it. A plugin that fails is reported at the end without stopping the rest.
it. It also skips deprecated plugins that aren't installed. A plugin that
fails is reported at the end without stopping the rest.
With a third-party catalog it first lists the plugins it would install and asks
to confirm; pass `--yes` to skip the prompt. Without a terminal and without
`--yes`, it exits with an error rather than install anything.
Expand Down Expand Up @@ -182,6 +183,20 @@ If the replacement's catalog is already registered, the notice shows only the
`plugin install` line. Installs and upgrades still proceed. Plugins installed
directly from GitHub have no catalog entry and get no notice.

When both a deprecated plugin and a replacement with the same name are
available, a bare-name install such as `datumctl plugin install ipam` picks the
replacement instead of reporting that the name exists in multiple catalogs. If
other catalogs also have a plugin with that name, the collision error lists
only those and the replacement. A replacement with a new name isn't picked
this way; install it with `datumctl plugin install <catalog>/<new-name>`.
When the install proceeds from the replacement, it first prints
`note: <name> in <catalog> is deprecated; installing its replacement from <catalog>`
to stderr, once per deprecated match it dropped.

`plugin install --all-available` skips a deprecated plugin that isn't
installed and prints `Skipped <name>: deprecated`. It still upgrades a
deprecated plugin that is already installed and prints the notice.

To move, run `datumctl plugin install <catalog>/<name>`. The plugin is then
recorded as installed from the new catalog, so `plugin upgrade` uses that
catalog and the notice stops.
Expand Down
44 changes: 41 additions & 3 deletions internal/cmd/plugin/catalog_resolve.go
Original file line number Diff line number Diff line change
Expand Up @@ -102,8 +102,9 @@ func catalogIndexLoader(cmd *cobra.Command, pluginsDir string, reg *pluginstore.

// resolveBareName finds every catalog that contains a plugin with the given
// name. The default catalog is checked first. A catalog that cannot be reached
// is skipped with a warning rather than failing the whole resolution.
func resolveBareName(cmd *cobra.Command, pluginsDir string, reg *pluginstore.Registry, name string) []catalogMatch {
// is skipped with a warning rather than failing the whole resolution. It also
// returns the deprecated matches dropped because their replacement is present.
func resolveBareName(cmd *cobra.Command, pluginsDir string, reg *pluginstore.Registry, name string) ([]catalogMatch, []supersededMatch) {
var matches []catalogMatch
active := reg.Active()
for i := range active {
Expand All @@ -117,7 +118,44 @@ func resolveBareName(cmd *cobra.Command, pluginsDir string, reg *pluginstore.Reg
matches = append(matches, catalogMatch{catalog: cat, plugin: p})
}
}
return matches
return dropSupersededMatches(matches)
}

// supersededMatch is a deprecated match dropped because replacement, another
// match, supersedes it.
type supersededMatch struct {
deprecated catalogMatch
replacement catalogMatch
}

// dropSupersededMatches removes a match whose plugin is deprecated when
// another match is its replacement: same catalog source and name. Order is
// preserved. When every match would be dropped (deprecated entries naming
// each other), the matches are returned unchanged and nothing is dropped. The
// dropped matches are returned with the match that replaces each.
func dropSupersededMatches(matches []catalogMatch) (kept []catalogMatch, dropped []supersededMatch) {
for i, m := range matches {
if d := m.plugin.Spec.Deprecated; d != nil && d.Replacement != nil {
var replacement *catalogMatch
for j, other := range matches {
if i != j &&
pluginstore.SameCatalogSource(d.Replacement.Catalog, other.catalog.Source) &&
other.plugin.Name == d.Replacement.PluginName(m.plugin.Name) {
replacement = &matches[j]
break
}
}
if replacement != nil {
dropped = append(dropped, supersededMatch{deprecated: m, replacement: *replacement})
continue
}
}
kept = append(kept, m)
}
if len(kept) == 0 {
return matches, nil
}
return kept, dropped
}

// collisionError renders the "available from multiple catalogs" message that
Expand Down
53 changes: 53 additions & 0 deletions internal/cmd/plugin/deprecation_cmd_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@ import (
"strings"
"testing"

"github.com/spf13/cobra"
metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"

"go.datum.net/datumctl/internal/pluginstore"
Expand Down Expand Up @@ -221,3 +222,55 @@ func main() {
t.Fatalf("beta must get no notice:\n%s", out)
}
}

// execPluginCmdSplit runs cmd with separate stdout and stderr buffers.
func execPluginCmdSplit(t *testing.T, pluginsDir string, cmd *cobra.Command, args ...string) (stdout, stderr string, err error) {
t.Helper()
t.Setenv("DATUMCTL_PLUGINS_DIR", pluginsDir)
var outBuf, errBuf bytes.Buffer
cmd.SetOut(&outBuf)
cmd.SetErr(&errBuf)
cmd.SetIn(strings.NewReader(""))
cmd.SetArgs(args)
err = cmd.Execute()
return outBuf.String(), errBuf.String(), err
}

func TestInstallAllAvailable_deprecatedUpToDatePrintsNoticeOnStderr(t *testing.T) {
dir := t.TempDir()
seedManifest(t, dir, map[string]*pluginstore.InstalledPlugin{"ipam": installedEntry("datum", "v0.1.0")})
seedFreshCache(t, dir, pluginstore.OfficialCatalogName, deprecatedPlugin("ipam", "v0.1.0"))

stdout, stderr, err := execPluginCmdSplit(t, dir, installCmd(nil), "--all-available")
if err != nil {
t.Fatalf("unexpected error: %v\n%s", err, stderr)
}
if !strings.Contains(stdout, "ipam v0.1.0 is up to date") {
t.Fatalf("want up-to-date line on stdout:\n%s", stdout)
}
if strings.Contains(stdout, "deprecated") {
t.Fatalf("notice must not be on stdout:\n%s", stdout)
}
if !strings.Contains(stderr, "warning: ipam is deprecated: use the new one") {
t.Fatalf("want notice on stderr:\n%s", stderr)
}
}

func TestInstallBareName_noteWhenReplacementSupersedes(t *testing.T) {
dir := t.TempDir()
if err := pluginstore.SaveRegistry(dir, &pluginstore.Registry{Catalogs: []pluginstore.Catalog{
{Name: "acme-milo", Source: "https://github.com/milo-os/cli-plugins", Type: pluginstore.CatalogTypeCustom},
}}); err != nil {
t.Fatal(err)
}
seedFreshCache(t, dir, pluginstore.OfficialCatalogName, deprecatedPlugin("ipam", "v0.1.0"))
// The replacement has no platform builds, so the install fails after the
// note is printed, before any download.
seedFreshCache(t, dir, "acme-milo", testPlugin("ipam", "v1.0.0", "IPAM"))

_, stderr, _ := execPluginCmdSplit(t, dir, installCmd(nil), "ipam")
want := "note: ipam in datum is deprecated; installing its replacement from acme-milo\n"
if strings.Count(stderr, want) != 1 {
t.Fatalf("want exactly one %q in stderr:\n%s", want, stderr)
}
}
6 changes: 5 additions & 1 deletion internal/cmd/plugin/install.go
Original file line number Diff line number Diff line change
Expand Up @@ -251,11 +251,15 @@ func installFromCatalog(cmd *cobra.Command, pluginsDir string, reg *pluginstore.
// first) and installs the unique match, or surfaces the options on a collision.
// version pins a specific release, or "" installs the recommended version.
func installBareName(cmd *cobra.Command, pluginsDir string, reg *pluginstore.Registry, name, version, currentVersion string) error {
matches := resolveBareName(cmd, pluginsDir, reg, name)
matches, dropped := resolveBareName(cmd, pluginsDir, reg, name)
switch len(matches) {
case 0:
return customerrors.NewUserError(fmt.Sprintf("plugin %q not found in any registered catalog; run 'datumctl plugin search %s' to look for it", name, name))
case 1:
for _, d := range dropped {
fmt.Fprintf(cmd.ErrOrStderr(), "note: %s in %s is deprecated; installing its replacement from %s\n",
name, d.deprecated.catalog.Name, d.replacement.catalog.Name)
}
return installFromCatalog(cmd, pluginsDir, reg, matches[0].catalog.Name, name, version, currentVersion)
default:
return customerrors.NewUserError(collisionError(name, matches).Error())
Expand Down
17 changes: 16 additions & 1 deletion internal/cmd/plugin/install_all_available.go
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,8 @@ type catalogInstallPlan struct {
// upToDate lists plugins already installed from this catalog at its version.
upToDate []string
// skipped lists plugins installed from another catalog or from GitHub,
// which --all-available leaves alone rather than replace.
// which --all-available leaves alone rather than replace, and deprecated
// plugins that are not installed.
skipped []skippedPlugin
}

Expand All @@ -37,6 +38,10 @@ func planCatalogInstall(catalogName string, idx *pluginstore.CachedIndex, manife
p := &idx.Plugins[i]
entry := manifest.Plugins[p.Name]
if entry == nil {
if p.Spec.Deprecated != nil {
plan.skipped = append(plan.skipped, skippedPlugin{name: p.Name, reason: "deprecated"})
continue
}
plan.install = append(plan.install, p.Name)
continue
}
Expand Down Expand Up @@ -101,6 +106,7 @@ func installAllAvailable(cmd *cobra.Command, pluginsDir, catalogName, currentVer
}
for _, name := range plan.upToDate {
fmt.Fprintf(out, "%s %s is up to date\n", name, manifest.Plugins[name].Version)
warnIfDeprecated(cmd, reg, idx, name)
}
for _, s := range plan.skipped {
fmt.Fprintf(out, "Skipped %s: %s\n", s.name, s.reason)
Expand Down Expand Up @@ -134,6 +140,7 @@ func installAllAvailable(cmd *cobra.Command, pluginsDir, catalogName, currentVer
manifest.Plugins[name] = entry
installed++
fmt.Fprintf(out, "Installed %s %s from %s [%s]\n", name, entry.Version, cat.Name, installBadge(cat.Name))
warnIfDeprecated(cmd, reg, idx, name)
}

if installed > 0 {
Expand All @@ -147,6 +154,14 @@ func installAllAvailable(cmd *cobra.Command, pluginsDir, catalogName, currentVer
return nil
}

// warnIfDeprecated prints the deprecation notice for name to stderr when its
// entry in idx is deprecated.
func warnIfDeprecated(cmd *cobra.Command, reg *pluginstore.Registry, idx *pluginstore.CachedIndex, name string) {
if p := pluginstore.FindInIndex(idx, name); p != nil {
writeDeprecationNotice(cmd.ErrOrStderr(), reg, name, p.Spec.Deprecated)
}
}

// confirmThirdPartyInstallAll lists the plugins a third-party --all-available
// would install and reads a y/N answer from stdin. answered is false when no
// one responds (EOF, non-interactive), so the caller can tell that apart from
Expand Down
56 changes: 56 additions & 0 deletions internal/cmd/plugin/install_all_available_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -290,3 +290,59 @@ func TestInstall_yesNeedsAllAvailable(t *testing.T) {
t.Fatalf("error = %v, want the --yes/--all-available error", err)
}
}

func deprecatedIpam(version string) pluginstore.Plugin {
p := testPlugin("ipam", version, "IPAM")
p.Spec.Deprecated = &pluginstore.Deprecation{
Message: "ipam moved.",
Replacement: &pluginstore.PluginReplacement{Catalog: "milo-os/cli-plugins"},
}
return p
}

func TestPlanCatalogInstall_skipsDeprecatedNotInstalled(t *testing.T) {
t.Parallel()
idx := &pluginstore.CachedIndex{Plugins: []pluginstore.Plugin{
deprecatedIpam("v0.1.0"),
testPlugin("dns", "v1.0.0", "DNS"),
}}
got := planCatalogInstall("datum", idx, &pluginstore.Manifest{})
if want := []string{"dns"}; !reflect.DeepEqual(got.install, want) {
t.Errorf("install = %v, want %v", got.install, want)
}
if want := []skippedPlugin{{name: "ipam", reason: "deprecated"}}; !reflect.DeepEqual(got.skipped, want) {
t.Errorf("skipped = %+v, want %+v", got.skipped, want)
}
}

func TestPlanCatalogInstall_upgradesDeprecatedInstalled(t *testing.T) {
t.Parallel()
idx := &pluginstore.CachedIndex{Plugins: []pluginstore.Plugin{deprecatedIpam("v0.2.0")}}
manifest := &pluginstore.Manifest{Plugins: map[string]*pluginstore.InstalledPlugin{
"ipam": {Source: "ipam", Catalog: "datum", Version: "v0.1.0"},
}}
got := planCatalogInstall("datum", idx, manifest)
if want := []string{"ipam"}; !reflect.DeepEqual(got.install, want) {
t.Errorf("install = %v, want %v", got.install, want)
}
}

func TestInstallAllAvailable_skipsDeprecatedNotInstalled(t *testing.T) {
pluginsDir := t.TempDir()
seedFreshCache(t, pluginsDir, "datum", deprecatedIpam("v0.1.0"))

out, err := execPluginCmd(t, pluginsDir, installCmd(nil), "--all-available")
if err != nil {
t.Fatalf("install --all-available failed: %v\n%s", err, out)
}
if !strings.Contains(out, "Skipped ipam: deprecated") {
t.Fatalf("expected skip line, got:\n%s", out)
}
m, err := pluginstore.Load(pluginsDir)
if err != nil {
t.Fatal(err)
}
if _, ok := m.Plugins["ipam"]; ok {
t.Fatalf("ipam must not be installed: %+v", m.Plugins)
}
}
95 changes: 92 additions & 3 deletions internal/cmd/plugin/install_catalog_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -102,7 +102,7 @@ func TestResolveBareName_uniqueAndCollision(t *testing.T) {
cmd.SetErr(&errOut)

// Collision: deploy is in datum and acme; the official datum catalog is first.
matches := resolveBareName(cmd, pluginsDir, reg, "deploy")
matches, _ := resolveBareName(cmd, pluginsDir, reg, "deploy")
if len(matches) != 2 {
t.Fatalf("expected 2 matches for deploy, got %d", len(matches))
}
Expand All @@ -119,13 +119,13 @@ func TestResolveBareName_uniqueAndCollision(t *testing.T) {
}

// Unique: solo is only in beta.
solo := resolveBareName(cmd, pluginsDir, reg, "solo")
solo, _ := resolveBareName(cmd, pluginsDir, reg, "solo")
if len(solo) != 1 || solo[0].catalog.Name != "beta" {
t.Fatalf("expected unique beta match for solo, got %+v", solo)
}

// Missing: nothing matches.
if got := resolveBareName(cmd, pluginsDir, reg, "ghost"); len(got) != 0 {
if got, _ := resolveBareName(cmd, pluginsDir, reg, "ghost"); len(got) != 0 {
t.Fatalf("expected no matches for ghost, got %+v", got)
}
}
Expand Down Expand Up @@ -176,3 +176,92 @@ func TestSearch_unknownIndexErrors(t *testing.T) {
t.Fatal("expected error for unknown --index")
}
}

func resolveWithCatalogs(t *testing.T, name string, extra []pluginstore.Catalog, seed map[string]pluginstore.Plugin) []catalogMatch {
t.Helper()
pluginsDir := t.TempDir()
if err := pluginstore.SaveRegistry(pluginsDir, &pluginstore.Registry{Catalogs: extra}); err != nil {
t.Fatal(err)
}
for cat, p := range seed {
seedFreshCache(t, pluginsDir, cat, p)
}
reg, err := pluginstore.LoadRegistry(pluginsDir)
if err != nil {
t.Fatal(err)
}
cmd := &cobra.Command{}
cmd.SetContext(context.Background())
cmd.SetErr(&bytes.Buffer{})
matches, _ := resolveBareName(cmd, pluginsDir, reg, name)
return matches
}

func TestResolveBareName_prefersReplacement(t *testing.T) {
got := resolveWithCatalogs(t, "ipam",
[]pluginstore.Catalog{{Name: "acme-milo", Source: "https://github.com/milo-os/cli-plugins", Type: pluginstore.CatalogTypeCustom}},
map[string]pluginstore.Plugin{
"datum": deprecatedPlugin("ipam", "v0.1.0"),
"acme-milo": testPlugin("ipam", "v1.0.0", "IPAM"),
})
if len(got) != 1 || got[0].catalog.Name != "acme-milo" {
t.Fatalf("want one match from acme-milo, got %+v", got)
}
}

func TestResolveBareName_deprecatedWithoutReplacementPresent(t *testing.T) {
got := resolveWithCatalogs(t, "ipam",
[]pluginstore.Catalog{{Name: "other", Source: "https://github.com/other/repo", Type: pluginstore.CatalogTypeCustom}},
map[string]pluginstore.Plugin{
"datum": deprecatedPlugin("ipam", "v0.1.0"),
"other": testPlugin("ipam", "v1.0.0", "IPAM"),
})
if len(got) != 2 {
t.Fatalf("want 2 matches, got %+v", got)
}
}

func TestResolveBareName_thirdCatalogStillCollides(t *testing.T) {
got := resolveWithCatalogs(t, "ipam",
[]pluginstore.Catalog{
{Name: "acme-milo", Source: "https://github.com/milo-os/cli-plugins", Type: pluginstore.CatalogTypeCustom},
{Name: "other", Source: "https://github.com/other/repo", Type: pluginstore.CatalogTypeCustom},
},
map[string]pluginstore.Plugin{
"datum": deprecatedPlugin("ipam", "v0.1.0"),
"acme-milo": testPlugin("ipam", "v1.0.0", "IPAM"),
"other": testPlugin("ipam", "v2.0.0", "IPAM"),
})
if len(got) != 2 || got[0].catalog.Name != "acme-milo" || got[1].catalog.Name != "other" {
t.Fatalf("want acme-milo and other, got %+v", got)
}
}

func TestResolveBareName_mutuallyDeprecatedKeepsAll(t *testing.T) {
a := deprecatedPlugin("ipam", "v0.1.0") // replacement: milo-os/cli-plugins
b := deprecatedPlugin("ipam", "v0.2.0")
b.Spec.Deprecated.Replacement.Catalog = "datum-cloud/datumctl-plugins"
got := resolveWithCatalogs(t, "ipam",
[]pluginstore.Catalog{{Name: "acme-milo", Source: "https://github.com/milo-os/cli-plugins", Type: pluginstore.CatalogTypeCustom}},
map[string]pluginstore.Plugin{"datum": a, "acme-milo": b})
if len(got) != 2 {
t.Fatalf("want both matches, got %+v", got)
}
}

func TestDropSupersededMatches_reportsDropped(t *testing.T) {
dep := catalogMatch{catalog: pluginstore.Catalog{Name: "datum", Source: "datum"}, plugin: func() *pluginstore.Plugin { p := deprecatedPlugin("ipam", "v0.1.0"); return &p }()}
repl := catalogMatch{catalog: pluginstore.Catalog{Name: "acme-milo", Source: "https://github.com/milo-os/cli-plugins"}, plugin: func() *pluginstore.Plugin { p := testPlugin("ipam", "v1.0.0", "IPAM"); return &p }()}
kept, dropped := dropSupersededMatches([]catalogMatch{dep, repl})
if len(kept) != 1 || kept[0].catalog.Name != "acme-milo" {
t.Fatalf("kept = %+v", kept)
}
if len(dropped) != 1 || dropped[0].deprecated.catalog.Name != "datum" || dropped[0].replacement.catalog.Name != "acme-milo" {
t.Fatalf("dropped = %+v", dropped)
}
// Mutually deprecated: nothing dropped.
kept, dropped = dropSupersededMatches([]catalogMatch{dep})
if len(kept) != 1 || len(dropped) != 0 {
t.Fatalf("kept=%+v dropped=%+v", kept, dropped)
}
}
Loading