diff --git a/docs/developer/plugins.md b/docs/developer/plugins.md index 2a42b6f..ebff3bc 100644 --- a/docs/developer/plugins.md +++ b/docs/developer/plugins.md @@ -163,6 +163,29 @@ A deprecated entry stays in its catalog and keeps receiving releases until its catalog removes it, so installs and upgrades keep working during the deprecation period. +### What users see + +`plugin install`, `plugin install` with no arguments (restore), and +`plugin upgrade` print a notice to stderr for a deprecated plugin. +`plugin upgrade` prints it whether the plugin was upgraded or was already up +to date. For the entry above, a user whose registry doesn't have the +replacement's catalog sees: + +```text +warning: ipam is deprecated: ipam moved to the Milo catalog. + To switch to the replacement: + datumctl plugin index add milo-os milo-os/cli-plugins + datumctl plugin install milo-os/ipam +``` + +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. + +To move, run `datumctl plugin install /`. The plugin is then +recorded as installed from the new catalog, so `plugin upgrade` uses that +catalog and the notice stops. + --- ## plugins.json schema diff --git a/internal/cmd/plugin/deprecation_cmd_test.go b/internal/cmd/plugin/deprecation_cmd_test.go new file mode 100644 index 0000000..f0be2b8 --- /dev/null +++ b/internal/cmd/plugin/deprecation_cmd_test.go @@ -0,0 +1,223 @@ +package plugin + +import ( + "bytes" + "os" + "runtime" + "strings" + "testing" + + metav1 "k8s.io/apimachinery/pkg/apis/meta/v1" + + "go.datum.net/datumctl/internal/pluginstore" +) + +func deprecatedPlugin(name, version string) pluginstore.Plugin { + p := testPlugin(name, version, name) + p.Spec.Deprecated = &pluginstore.Deprecation{ + Message: "use the new one", + Replacement: &pluginstore.PluginReplacement{ + Catalog: "milo-os/cli-plugins", + Name: name, + }, + } + return p +} + +func TestUpgrade_deprecatedUpToDatePrintsNotice(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")) + + out, err := execPluginCmd(t, dir, upgradeCmd(nil), "ipam") + if err != nil { + t.Fatalf("unexpected error: %v\n%s", err, out) + } + for _, want := range []string{"ipam is already up to date", "warning: ipam is deprecated: use the new one"} { + if !strings.Contains(out, want) { + t.Fatalf("want %q in output:\n%s", want, out) + } + } +} + +func TestUpgrade_movedPluginNoNotice(t *testing.T) { + dir := t.TempDir() + if err := pluginstore.SaveRegistry(dir, &pluginstore.Registry{Catalogs: []pluginstore.Catalog{ + {Name: "milo-os", Source: "milo-os/cli-plugins", Type: pluginstore.CatalogTypeCustom}, + }}); err != nil { + t.Fatal(err) + } + seedManifest(t, dir, map[string]*pluginstore.InstalledPlugin{"ipam": installedEntry("milo-os", "v0.1.0")}) + seedFreshCache(t, dir, "milo-os", testPlugin("ipam", "v0.1.0", "IPAM")) + seedFreshCache(t, dir, pluginstore.OfficialCatalogName, deprecatedPlugin("ipam", "v0.1.0")) + + out, err := execPluginCmd(t, dir, upgradeCmd(nil), "ipam") + if err != nil { + t.Fatalf("unexpected error: %v\n%s", err, out) + } + if !strings.Contains(out, "ipam is already up to date") || strings.Contains(out, "deprecated") { + t.Fatalf("want up-to-date report and no notice, got:\n%s", out) + } +} + +func TestUpgrade_nonDeprecatedNoNotice(t *testing.T) { + dir := t.TempDir() + seedManifest(t, dir, map[string]*pluginstore.InstalledPlugin{"dns": installedEntry("datum", "v1.0.0")}) + seedFreshCache(t, dir, pluginstore.OfficialCatalogName, testPlugin("dns", "v1.0.0", "DNS")) + + out, err := execPluginCmd(t, dir, upgradeCmd(nil), "dns") + if err != nil { + t.Fatalf("unexpected error: %v\n%s", err, out) + } + if strings.Contains(out, "deprecated") { + t.Fatalf("want no notice, got:\n%s", out) + } +} + +func TestUpgradeAll_failedUpgradeNoNotice(t *testing.T) { + dir := t.TempDir() + seedManifest(t, dir, map[string]*pluginstore.InstalledPlugin{ + "ipam": installedEntry("datum", "v0.1.0"), + "dns": installedEntry("datum", "v1.0.0"), + }) + // ipam is deprecated and has a newer version with no platforms, so its + // upgrade fails. + seedFreshCache(t, dir, pluginstore.OfficialCatalogName, + deprecatedPlugin("ipam", "v0.2.0"), deprecatedPlugin("dns", "v1.0.0")) + + out, err := execPluginCmd(t, dir, upgradeCmd(nil), "--all") + if err == nil { + t.Fatalf("want error for failed ipam upgrade, got none:\n%s", out) + } + if strings.Contains(out, "warning: ipam is deprecated") { + t.Fatalf("failed upgrade must not print a notice:\n%s", out) + } + if !strings.Contains(out, "warning: dns is deprecated") { + t.Fatalf("successful plugin should print its notice:\n%s", out) + } +} + +func TestInstallFromCatalog_deprecatedPrintsNotice(t *testing.T) { + if runtime.GOOS == "windows" { + t.Skip("test builds a unix binary helper; skip on windows") + } + pluginBin := buildHelperBinary(t, ` +package main + +import ( + "fmt" + "os" +) + +func main() { + for _, a := range os.Args[1:] { + if a == "--plugin-manifest" { + fmt.Println(`+"`"+`{"name":"alpha","version":"v0.2.0","description":"Alpha","api_version":1}`+"`"+`) + return + } + } +} +`) + binData, err := os.ReadFile(pluginBin) + if err != nil { + t.Fatal(err) + } + archiveBytes := makeTarGz(t, "alpha", binData) + url := serveArchive(t, archiveBytes) + + alpha := pluginstore.Plugin{ + ObjectMeta: metav1.ObjectMeta{Name: "alpha"}, + Spec: pluginstore.PluginSpec{ + ShortDescription: "Alpha", + Version: "v0.2.0", + Platforms: []pluginstore.Platform{{URI: url + "/alpha.tar.gz", SHA256: sha256HexOf(archiveBytes)}}, + Deprecated: &pluginstore.Deprecation{Message: "use beta"}, + }, + } + dir := t.TempDir() + seedFreshCache(t, dir, pluginstore.OfficialCatalogName, alpha) + + t.Setenv("DATUMCTL_PLUGINS_DIR", dir) + var stdout, stderr bytes.Buffer + cmd := installCmd(nil) + cmd.SetOut(&stdout) + cmd.SetErr(&stderr) + cmd.SetIn(strings.NewReader("")) + cmd.SetArgs([]string{"datum/alpha"}) + if err := cmd.Execute(); err != nil { + t.Fatalf("unexpected error: %v\n%s%s", err, stdout.String(), stderr.String()) + } + if !strings.Contains(stdout.String(), "Installed alpha") { + t.Fatalf("want install report on stdout:\n%s", stdout.String()) + } + const notice = "warning: alpha is deprecated: use beta" + if !strings.Contains(stderr.String(), notice) || strings.Contains(stdout.String(), "deprecated") { + t.Fatalf("notice must be on stderr only; stdout:\n%s\nstderr:\n%s", stdout.String(), stderr.String()) + } + m, err := pluginstore.Load(dir) + if err != nil || m.Plugins["alpha"] == nil { + t.Fatalf("record not saved: %v", err) + } +} + +func TestInstallRestore_deprecatedPrintsNotice(t *testing.T) { + if runtime.GOOS == "windows" { + t.Skip("test builds a unix binary helper; skip on windows") + } + build := func(name string) pluginstore.Plugin { + bin := buildHelperBinary(t, ` +package main + +import ( + "fmt" + "os" +) + +func main() { + for _, a := range os.Args[1:] { + if a == "--plugin-manifest" { + fmt.Println(`+"`"+`{"name":"`+name+`","version":"v0.2.0","description":"x","api_version":1}`+"`"+`) + return + } + } +} +`) + data, err := os.ReadFile(bin) + if err != nil { + t.Fatal(err) + } + archive := makeTarGz(t, name, data) + url := serveArchive(t, archive) + return pluginstore.Plugin{ + ObjectMeta: metav1.ObjectMeta{Name: name}, + Spec: pluginstore.PluginSpec{ + ShortDescription: name, + Version: "v0.2.0", + Platforms: []pluginstore.Platform{{URI: url + "/" + name + ".tar.gz", SHA256: sha256HexOf(archive)}}, + }, + } + } + alpha := build("alpha") + alpha.Spec.Deprecated = &pluginstore.Deprecation{Message: "use gamma"} + beta := build("beta") + + dir := t.TempDir() + seedManifest(t, dir, map[string]*pluginstore.InstalledPlugin{ + "alpha": installedEntry("datum", "v0.2.0"), + "beta": installedEntry("datum", "v0.2.0"), + }) + seedFreshCache(t, dir, pluginstore.OfficialCatalogName, alpha, beta) + + out, err := execPluginCmd(t, dir, installCmd(nil)) + if err != nil { + t.Fatalf("unexpected error: %v\n%s", err, out) + } + for _, want := range []string{"Installed alpha", "Installed beta", "warning: alpha is deprecated: use gamma"} { + if !strings.Contains(out, want) { + t.Fatalf("want %q in output:\n%s", want, out) + } + } + if strings.Contains(out, "beta is deprecated") { + t.Fatalf("beta must get no notice:\n%s", out) + } +} diff --git a/internal/cmd/plugin/install.go b/internal/cmd/plugin/install.go index b39f30d..f612beb 100644 --- a/internal/cmd/plugin/install.go +++ b/internal/cmd/plugin/install.go @@ -238,7 +238,13 @@ func installFromCatalog(cmd *cobra.Command, pluginsDir string, reg *pluginstore. // Record the catalog's canonical name (cat.Name), so "default/" // is stored as "datum". idxEntry.Catalog = cat.Name - return saveAndReport(cmd, pluginsDir, name, idxEntry, binaryPath) + if err := saveAndReport(cmd, pluginsDir, name, idxEntry, binaryPath); err != nil { + return err + } + if p := pluginstore.FindInIndex(idx, name); p != nil { + writeDeprecationNotice(cmd.ErrOrStderr(), reg, name, p.Spec.Deprecated) + } + return nil } // installBareName resolves a bare plugin name across all catalogs (default @@ -350,6 +356,9 @@ func installAllFromManifest(cmd *cobra.Command, pluginsDir, currentVersion strin newEntry.Catalog = catalogName manifest.Plugins[name] = newEntry fmt.Fprintf(cmd.OutOrStdout(), "Installed %s %s from %s\n", name, newEntry.Version, catalogName) + if p := pluginstore.FindInIndex(idx, name); p != nil { + writeDeprecationNotice(cmd.ErrOrStderr(), reg, name, p.Spec.Deprecated) + } } if saveErr := pluginstore.Save(pluginsDir, manifest); saveErr != nil { diff --git a/internal/cmd/plugin/upgrade.go b/internal/cmd/plugin/upgrade.go index 49ddfc0..1f955ca 100644 --- a/internal/cmd/plugin/upgrade.go +++ b/internal/cmd/plugin/upgrade.go @@ -93,6 +93,7 @@ func upgradeOne(cmd *cobra.Command, pluginsDir string, manifest *pluginstore.Man return customerrors.NewUserError(fmt.Sprintf("upgrade plugin %s: %v", name, err)) } reportUpgrade(cmd, name, from, to, upgraded) + u.writeNotice(name, entry) return nil } @@ -127,6 +128,7 @@ func upgradeAll(cmd *cobra.Command, pluginsDir string, manifest *pluginstore.Man continue } reportUpgrade(cmd, name, from, to, upgraded) + u.writeNotice(name, entry) } if len(errs) > 0 { @@ -152,6 +154,7 @@ type upgrader struct { cmd *cobra.Command pluginsDir string manifest *pluginstore.Manifest + reg *pluginstore.Registry currentVersion string getIndex func(catalogName string) (*pluginstore.CachedIndex, error) } @@ -166,11 +169,33 @@ func newUpgrader(cmd *cobra.Command, pluginsDir string, manifest *pluginstore.Ma cmd: cmd, pluginsDir: pluginsDir, manifest: manifest, + reg: reg, currentVersion: currentVersion, getIndex: catalogIndexLoader(cmd, pluginsDir, reg), }, nil } +// writeNotice prints the deprecation notice, if any, for a plugin that was +// just processed without error. Direct GitHub installs have no catalog entry +// and get none. The catalog is the one the plugin is recorded as installed +// from, so a plugin that moved to another catalog stops getting a notice. +func (u *upgrader) writeNotice(name string, entry *pluginstore.InstalledPlugin) { + if entry.Catalog == "" && strings.Contains(entry.Source, "/") { + return + } + catalogName := pluginstore.CanonicalCatalogName(entry.Catalog) + if catalogName == "" { + catalogName = pluginstore.OfficialCatalogName + } + idx, err := u.getIndex(catalogName) + if err != nil { + return + } + if p := pluginstore.FindInIndex(idx, name); p != nil { + writeDeprecationNotice(u.cmd.ErrOrStderr(), u.reg, name, p.Spec.Deprecated) + } +} + // upgrade brings one installed plugin to the latest version offered by the // source it was installed from and records the result in plugins.json. It // returns the latest version and whether a new version was installed; when the