From 90d42ce903e9a5b0697e02b883da14aea730fd80 Mon Sep 17 00:00:00 2001 From: Michael Costello Date: Tue, 17 Nov 2026 12:21:06 -0500 Subject: [PATCH] feat: Let catalog entries declare a deprecation Removing a plugin from a catalog breaks upgrade for everyone who installed it, and nothing tells them where the plugin went. Catalog entries can now carry an optional spec.deprecated block with a message and a replacement plugin in another catalog. The replacement names a catalog source rather than a catalog name, because users pick their own names when they add a catalog. SameCatalogSource resolves two sources and compares them, so later changes can recognize a replacement catalog the user already added. GitHub sources match by owner and repository, ignoring case and branch, since GitHub treats those as one repository. plugin index validate reports a deprecation with no message or no replacement catalog. The field is additive, and datumctl parses catalogs without rejecting unknown fields, so older releases keep installing and upgrading deprecated plugins. Resolves: #367 Co-Authored-By: Claude Opus 5.5 --- docs/developer/plugins.md | 37 ++++++ internal/pluginstore/catalog.go | 37 ++++++ internal/pluginstore/deprecation_test.go | 150 +++++++++++++++++++++++ internal/pluginstore/manifest.go | 26 ++++ internal/pluginstore/validate.go | 8 ++ 5 files changed, 258 insertions(+) create mode 100644 internal/pluginstore/deprecation_test.go diff --git a/docs/developer/plugins.md b/docs/developer/plugins.md index 97db775..2a42b6f 100644 --- a/docs/developer/plugins.md +++ b/docs/developer/plugins.md @@ -128,6 +128,43 @@ machine. --- +## Deprecating a catalog plugin + +A plugin can move from one catalog to another, for example when a plugin +built for the Milo platform moves from the Datum Cloud catalog to +`milo-os/cli-plugins`. Removing the old entry right away would break +`plugin upgrade` for everyone who installed from it, so the old entry first +marks itself deprecated and names its replacement: + +```yaml +spec: + # ...version, platforms, and other fields as before + deprecated: + message: ipam moved to the Milo catalog. + replacement: + catalog: milo-os/cli-plugins # a catalog source, as `plugin index add` takes + name: ipam # optional; defaults to this plugin's name +``` + +- `replacement.catalog` is a catalog source, not a catalog name. Users choose + their own names when they add a catalog, so datumctl recognizes the + replacement's catalog by resolving both sources and comparing them. For + example, `milo-os/cli-plugins`, `github.com/milo-os/cli-plugins`, and + `https://raw.githubusercontent.com/milo-os/cli-plugins/main/index.yaml` are + the same catalog. GitHub sources match by owner and repository regardless of + case or branch. +- `plugin index validate` reports a `deprecated` block that has no `message` + or no `replacement.catalog`. +- The field is additive. datumctl parses catalogs without rejecting unknown + fields, so releases that predate deprecation support keep installing and + upgrading a deprecated plugin as usual. + +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. + +--- + ## plugins.json schema `plugins.json` records every managed install. It is the source of truth for diff --git a/internal/pluginstore/catalog.go b/internal/pluginstore/catalog.go index 872370a..a490cea 100644 --- a/internal/pluginstore/catalog.go +++ b/internal/pluginstore/catalog.go @@ -477,3 +477,40 @@ func SourceGitHubOwnerRepo(source string) (ownerRepo string, ok bool) { } return "", false } + +// SameCatalogSource reports whether two catalog source strings resolve to the +// same catalog. When both resolve to GitHub, they match if their owner/repo +// strings are equal ignoring case; the branch is ignored. Otherwise local +// sources match by LocalPath and other remote sources by FetchURL (scheme and +// host compared case-insensitively). A source ResolveCatalogSource rejects +// never matches anything, including an identical invalid source. +func SameCatalogSource(a, b string) bool { + ra, err := ResolveCatalogSource(a) + if err != nil { + return false + } + rb, err := ResolveCatalogSource(b) + if err != nil { + return false + } + if ga, ok := SourceGitHubOwnerRepo(a); ok { + if gb, ok := SourceGitHubOwnerRepo(b); ok { + return strings.EqualFold(ga, gb) + } + } + if ra.IsLocal || rb.IsLocal { + return ra.IsLocal && rb.IsLocal && ra.LocalPath == rb.LocalPath + } + return normalizeFetchURL(ra.FetchURL) == normalizeFetchURL(rb.FetchURL) +} + +// normalizeFetchURL lowercases the scheme and host of a URL. +func normalizeFetchURL(raw string) string { + u, err := url.Parse(raw) + if err != nil { + return raw + } + u.Scheme = strings.ToLower(u.Scheme) + u.Host = strings.ToLower(u.Host) + return u.String() +} diff --git a/internal/pluginstore/deprecation_test.go b/internal/pluginstore/deprecation_test.go new file mode 100644 index 0000000..5ba2bd1 --- /dev/null +++ b/internal/pluginstore/deprecation_test.go @@ -0,0 +1,150 @@ +package pluginstore + +import ( + "os" + "path/filepath" + "strings" + "testing" + + metav1 "k8s.io/apimachinery/pkg/apis/meta/v1" + "sigs.k8s.io/yaml" +) + +const deprecatedCatalogYAML = `apiVersion: datumctl.dev/v1alpha1 +kind: PluginList +items: + - apiVersion: datumctl.dev/v1alpha1 + kind: Plugin + metadata: + name: ipam + spec: + shortDescription: IPAM + version: v1.0.0 + deprecated: + message: "moved" + replacement: + catalog: milo-os/cli-plugins + name: ipam + platforms: [] +` + +func TestParseCatalog_deprecatedBlock(t *testing.T) { + var list PluginList + if err := yaml.Unmarshal([]byte(deprecatedCatalogYAML), &list); err != nil { + t.Fatal(err) + } + check := func(t *testing.T, items []Plugin) { + t.Helper() + if len(items) != 1 { + t.Fatalf("items = %d, want 1", len(items)) + } + d := items[0].Spec.Deprecated + if d == nil || d.Message != "moved" || d.Replacement == nil || + d.Replacement.Catalog != "milo-os/cli-plugins" || d.Replacement.Name != "ipam" { + t.Fatalf("deprecated = %+v", d) + } + } + check(t, list.Items) + + dir := t.TempDir() + if err := SaveCatalogIndex(dir, "acme", &CachedIndex{Plugins: list.Items}); err != nil { + t.Fatal(err) + } + got, err := LoadCatalogIndex(dir, "acme") + if err != nil { + t.Fatal(err) + } + check(t, got.Plugins) +} + +func TestParseCatalog_noDeprecatedBlock(t *testing.T) { + var list PluginList + raw := "items:\n - metadata:\n name: ipam\n spec:\n version: v1.0.0\n" + if err := yaml.Unmarshal([]byte(raw), &list); err != nil { + t.Fatal(err) + } + if list.Items[0].Spec.Deprecated != nil { + t.Fatalf("Deprecated = %+v, want nil", list.Items[0].Spec.Deprecated) + } +} + +func TestPluginReplacement_PluginName(t *testing.T) { + if got := (&PluginReplacement{}).PluginName("ipam"); got != "ipam" { + t.Errorf("got %q", got) + } + if got := (&PluginReplacement{Name: "ipam2"}).PluginName("ipam"); got != "ipam2" { + t.Errorf("got %q", got) + } +} + +func TestSameCatalogSource(t *testing.T) { + cases := []struct { + a, b string + want bool + }{ + {"milo-os/cli-plugins", "github.com/milo-os/cli-plugins", true}, + {"milo-os/cli-plugins", "https://raw.githubusercontent.com/milo-os/cli-plugins/main/index.yaml", true}, + {"milo-os/cli-plugins", "https://RAW.GITHUBUSERCONTENT.COM/milo-os/cli-plugins/main/index.yaml", true}, + {"milo-os/cli-plugins", "datum-cloud/datumctl-plugins", false}, + {"http://x", "milo-os/cli-plugins", false}, + {"milo-os/cli-plugins", "http://x", false}, + {"http://x", "http://x", false}, + {"milo-os/cli-plugins", "https://raw.githubusercontent.com/milo-os/cli-plugins/master/index.yaml", true}, + {"milo-os/cli-plugins", "Milo-OS/CLI-Plugins", true}, + {"https://example.com/cat/index.yaml", "https://EXAMPLE.com/cat/index.yaml", true}, + {"milo-os/cli-plugins", "milo-os/other-plugins", false}, + } + for _, c := range cases { + if got := SameCatalogSource(c.a, c.b); got != c.want { + t.Errorf("SameCatalogSource(%q, %q) = %v, want %v", c.a, c.b, got, c.want) + } + } +} + +func TestLintCatalog_deprecated(t *testing.T) { + item := func(d *Deprecation) *PluginList { + return &PluginList{Items: []Plugin{{ + ObjectMeta: metav1.ObjectMeta{Name: "ipam"}, + Spec: PluginSpec{ + Version: "v1.0.0", + Platforms: []Platform{{ + URI: "https://example.com/a.tar.gz", SHA256: "abc", + }}, + Deprecated: d, + }, + }}} + } + problems := strings.Join(LintCatalog(item(&Deprecation{})), "\n") + for _, want := range []string{"ipam: deprecated has no message", "ipam: deprecated has no replacement.catalog"} { + if !strings.Contains(problems, want) { + t.Errorf("missing problem %q in %q", want, problems) + } + } + full := &Deprecation{Message: "moved", Replacement: &PluginReplacement{Catalog: "milo-os/cli-plugins"}} + if p := LintCatalog(item(full)); len(p) != 0 { + t.Errorf("full block: problems = %v", p) + } + if p := LintCatalog(item(nil)); len(p) != 0 { + t.Errorf("no block: problems = %v", p) + } +} + +func TestPluginReplacement_PluginName_nil(t *testing.T) { + var r *PluginReplacement + if got := r.PluginName("ipam"); got != "ipam" { + t.Errorf("got %q", got) + } +} + +func TestSameCatalogSource_local(t *testing.T) { + dir := t.TempDir() + if err := os.WriteFile(filepath.Join(dir, "index.yaml"), []byte("items: []\n"), 0o600); err != nil { + t.Fatal(err) + } + if !SameCatalogSource(dir, dir+"/index.yaml") { + t.Error("directory and its index.yaml should match") + } + if SameCatalogSource(dir, "milo-os/cli-plugins") { + t.Error("local path must not match a remote source") + } +} diff --git a/internal/pluginstore/manifest.go b/internal/pluginstore/manifest.go index 54fa6bb..84416f1 100644 --- a/internal/pluginstore/manifest.go +++ b/internal/pluginstore/manifest.go @@ -22,6 +22,10 @@ type PluginSpec struct { Homepage string `json:"homepage,omitempty"` Version string `json:"version"` Platforms []Platform `json:"platforms"` + + // Deprecated marks the plugin as deprecated. Optional and additive: older + // datumctl releases ignore it. + Deprecated *Deprecation `json:"deprecated,omitempty"` } // Platform describes a downloadable archive for one OS/arch combination. @@ -86,3 +90,25 @@ func (l *PluginList) HeaderFor() CatalogHeader { Homepage: l.Homepage, } } + +// Deprecation marks a plugin as deprecated and optionally names a replacement. +type Deprecation struct { + Message string `json:"message,omitempty"` + Replacement *PluginReplacement `json:"replacement,omitempty"` +} + +// PluginReplacement names the plugin that supersedes a deprecated one. +type PluginReplacement struct { + // Catalog is a catalog source, as `plugin index add` takes. + Catalog string `json:"catalog"` + // Name defaults to the deprecated plugin's name. + Name string `json:"name,omitempty"` +} + +// PluginName returns r.Name, or fallback when r is nil or r.Name is empty. +func (r *PluginReplacement) PluginName(fallback string) string { + if r == nil || r.Name == "" { + return fallback + } + return r.Name +} diff --git a/internal/pluginstore/validate.go b/internal/pluginstore/validate.go index eb4150d..d8796e9 100644 --- a/internal/pluginstore/validate.go +++ b/internal/pluginstore/validate.go @@ -56,6 +56,14 @@ func LintCatalog(list *PluginList) []string { if p.Spec.Version == "" { problems = append(problems, fmt.Sprintf("%s: missing spec.version", label)) } + if d := p.Spec.Deprecated; d != nil { + if d.Message == "" { + problems = append(problems, fmt.Sprintf("%s: deprecated has no message", label)) + } + if d.Replacement == nil || d.Replacement.Catalog == "" { + problems = append(problems, fmt.Sprintf("%s: deprecated has no replacement.catalog", label)) + } + } if len(p.Spec.Platforms) == 0 { problems = append(problems, fmt.Sprintf("%s: no platforms declared", label)) }