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
37 changes: 37 additions & 0 deletions docs/developer/plugins.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
37 changes: 37 additions & 0 deletions internal/pluginstore/catalog.go
Original file line number Diff line number Diff line change
Expand Up @@ -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()
}
150 changes: 150 additions & 0 deletions internal/pluginstore/deprecation_test.go
Original file line number Diff line number Diff line change
@@ -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")
}
}
26 changes: 26 additions & 0 deletions internal/pluginstore/manifest.go
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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
}
8 changes: 8 additions & 0 deletions internal/pluginstore/validate.go
Original file line number Diff line number Diff line change
Expand Up @@ -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))
}
Expand Down
Loading