feat: implement version picking and version listing for schedulers (#106)

dottorblaster · web-flow · commit 7c2f52fa5969 · 2026-05-05T18:39:06.000+02:00
* feat: implement version picking and version listing for schedulers

* docs: regenerate manpages
diff --git a/cmd/schedctl/root.go b/cmd/schedctl/root.go
@@ -43,6 +43,7 @@ func NewRootCmd() *cli.Command {
 			NewStopCmd(),
 			NewStatusCmd(),
 			NewDoctorCmd(),
+			NewVersionsCmd(),
 		},
 	}
 }
diff --git a/cmd/schedctl/root_test.go b/cmd/schedctl/root_test.go
@@ -42,7 +42,7 @@ func TestNewRootCmd(t *testing.T) {
 func TestRootCmdHasSubcommands(t *testing.T) {
 	rootCmd := cmd.NewRootCmd()
 
-	expected := []string{"run", "ps", "stop", "list", "doctor", "status"}
+	expected := []string{"run", "ps", "stop", "list", "doctor", "status", "versions"}
 	for _, name := range expected {
 		assert.NotNil(t, findSubcommand(rootCmd, name), "Root command should have %s subcommand", name)
 	}
@@ -51,7 +51,7 @@ func TestRootCmdHasSubcommands(t *testing.T) {
 func TestRootCmdSubcommandCount(t *testing.T) {
 	rootCmd := cmd.NewRootCmd()
 
-	assert.Equal(t, 6, len(rootCmd.Commands), "Root command should declare exactly 5 subcommands")
+	assert.Equal(t, 7, len(rootCmd.Commands), "Root command should declare exactly 7 subcommands")
 }
 
 func TestRootCmdHasDriverPersistentFlag(t *testing.T) {
diff --git a/cmd/schedctl/run.go b/cmd/schedctl/run.go
@@ -24,6 +24,7 @@ Arguments after -- are passed to the scheduler container.
 
 Examples:
   schedctl run scx_rusty
+  schedctl run scx_rusty --version v1.0.0
   schedctl run scx_rusty -- --verbose
   schedctl run --attach scx_rusty -- --mode=performance --interval=100`,
 		Flags: []cli.Flag{
@@ -34,6 +35,12 @@ Examples:
 				Local:    true,
 				Category: categoryProcess,
 			},
+			&cli.StringFlag{
+				Name:     "version",
+				Usage:    "scheduler version (image tag) to run, e.g. v1.0.0",
+				Local:    true,
+				Category: categoryProcess,
+			},
 		},
 		Action: runAction,
 	}
@@ -49,8 +56,9 @@ func runAction(_ context.Context, cmd *cli.Command) error {
 	containerArgs := args[1:]
 	driver := cmd.String("driver")
 	attach := cmd.Bool("attach")
+	version := cmd.String("version")
 
-	result, err := schedulers.GetScheduler(schedulerID)
+	result, err := schedulers.GetScheduler(schedulerID, version)
 	if err != nil {
 		return err
 	}
diff --git a/cmd/schedctl/run_test.go b/cmd/schedctl/run_test.go
@@ -32,6 +32,18 @@ func TestRunCmdHasAttachFlag(t *testing.T) {
 	assert.True(t, boolFlag.Local, "attach flag should be local to the run command")
 }
 
+func TestRunCmdHasVersionFlag(t *testing.T) {
+	runCmd := cmd.NewRunCmd()
+
+	versionFlag := lookupFlag(runCmd.Flags, "version")
+	assert.NotNil(t, versionFlag, "run command should have 'version' flag")
+
+	stringFlag, ok := versionFlag.(*cli.StringFlag)
+	assert.True(t, ok, "version flag should be a StringFlag")
+	assert.Equal(t, "", stringFlag.Value, "version flag should default to empty string")
+	assert.True(t, stringFlag.Local, "version flag should be local to the run command")
+}
+
 func TestRunCmdAttachFlagIsCategorized(t *testing.T) {
 	runCmd := cmd.NewRunCmd()
 
diff --git a/cmd/schedctl/versions.go b/cmd/schedctl/versions.go
@@ -0,0 +1,48 @@
+package cmd
+
+import (
+	"context"
+	"fmt"
+	"sort"
+
+	"github.com/urfave/cli/v3"
+
+	"schedctl/internal/output"
+	"schedctl/internal/schedulers"
+)
+
+func NewVersionsCmd() *cli.Command {
+	return &cli.Command{
+		Name:      "versions",
+		Usage:     "list available versions for a scheduler",
+		ArgsUsage: "SCHEDULER",
+		Description: `Query the container registry for all available versions (tags)
+of the given scheduler.
+
+Examples:
+  schedctl versions scx_rusty
+  schedctl versions ghcr.io/myorg/custom-scheduler`,
+		Action: versionsAction,
+	}
+}
+
+func versionsAction(_ context.Context, cmd *cli.Command) error {
+	args := cmd.Args().Slice()
+	if len(args) == 0 {
+		return fmt.Errorf("exactly one scheduler ID required")
+	}
+
+	schedulerID := args[0]
+
+	versions, err := schedulers.ListVersions(schedulerID)
+	if err != nil {
+		return err
+	}
+
+	sort.Strings(versions)
+	for _, v := range versions {
+		_, _ = output.Out("%s\n", v)
+	}
+
+	return nil
+}
diff --git a/cmd/schedctl/versions_test.go b/cmd/schedctl/versions_test.go
@@ -0,0 +1,31 @@
+package cmd_test
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+
+	cmd "schedctl/cmd/schedctl"
+)
+
+func TestNewVersionsCmd(t *testing.T) {
+	versionsCmd := cmd.NewVersionsCmd()
+
+	assert.NotNil(t, versionsCmd)
+	assert.Equal(t, "versions", versionsCmd.Name)
+	assert.Equal(t, "list available versions for a scheduler", versionsCmd.Usage)
+	assert.Equal(t, "SCHEDULER", versionsCmd.ArgsUsage)
+	assert.NotEmpty(t, versionsCmd.Description)
+}
+
+func TestVersionsCmdHasNoLocalFlags(t *testing.T) {
+	versionsCmd := cmd.NewVersionsCmd()
+
+	assert.Empty(t, versionsCmd.Flags, "versions command should have no local flags")
+}
+
+func TestVersionsCmdRegisteredOnRoot(t *testing.T) {
+	rootCmd := cmd.NewRootCmd()
+
+	assert.NotNil(t, findSubcommand(rootCmd, "versions"), "versions subcommand must be registered on the root command")
+}
diff --git a/dist/man/schedctl-run.1 b/dist/man/schedctl-run.1
@@ -11,6 +11,7 @@ schedctl-run
 .EX
 [--attach|-a]
 [--driver|-d]=[value]
+[--version]=[value]
 .EE
 
 
@@ -23,6 +24,7 @@ Arguments after -- are passed to the scheduler container.
 .PP
 Examples:
   schedctl run scx_rusty
+  schedctl run scx_rusty --version v1.0.0
   schedctl run scx_rusty -- --verbose
   schedctl run --attach scx_rusty -- --mode=performance --interval=100
 
@@ -39,3 +41,6 @@ schedctl run SCHEDULER [-- ARGS...]
 
 .PP
 \fB--driver, -d\fP="": container runtime to use: containerd, podman (default: "podman")
+
+.PP
+\fB--version\fP="": scheduler version (image tag) to run, e.g. v1.0.0
diff --git a/dist/man/schedctl-versions.1 b/dist/man/schedctl-versions.1
@@ -0,0 +1,34 @@
+.nh
+.TH schedctl-versions 1
+
+.SH NAME
+schedctl-versions \- list available versions for a scheduler
+
+
+.SH SYNOPSIS
+schedctl-versions
+
+.EX
+[--driver|-d]=[value]
+.EE
+
+
+.SH DESCRIPTION
+Query the container registry for all available versions (tags)
+of the given scheduler.
+
+.PP
+Examples:
+  schedctl versions scx_rusty
+  schedctl versions ghcr.io/myorg/custom-scheduler
+
+.PP
+\fBUsage\fP:
+
+.EX
+schedctl versions SCHEDULER
+.EE
+
+
+.SH GLOBAL OPTIONS
+\fB--driver, -d\fP="": container runtime to use: containerd, podman (default: "podman")
diff --git a/dist/man/schedctl.1 b/dist/man/schedctl.1
@@ -38,6 +38,9 @@ Run a specific scheduler
 .PP
 \fB--attach, -a\fP: attach to the current process instead of detaching
 
+.PP
+\fB--version\fP="": scheduler version (image tag) to run, e.g. v1.0.0
+
 .SH ps
 list running schedulers
 
@@ -55,3 +58,6 @@ check host readiness for sched_ext schedulers
 
 .PP
 \fB--output, -o\fP="": output format: text, json (default: "text")
+
+.SH versions
+list available versions for a scheduler
diff --git a/go.mod b/go.mod
@@ -6,6 +6,7 @@ require (
 	github.com/anatol/vmtest v0.0.0-20230711210602-87511df0d4bc
 	github.com/containerd/containerd/v2 v2.2.0
 	github.com/containers/podman/v5 v5.8.2
+	github.com/google/go-containerregistry v0.20.7
 	github.com/stretchr/testify v1.11.1
 	github.com/tmc/scp v0.0.0-20170824174625-f7b48647feef
 	github.com/urfave/cli-docs/v3 v3.1.0
@@ -86,6 +87,7 @@ require (
 	github.com/cyberphone/json-canonicalization v0.0.0-20241213102144-19d51d7fe467 // indirect
 	github.com/cyphar/filepath-securejoin v0.5.2 // indirect
 	github.com/disiqueira/gotree/v3 v3.0.2 // indirect
+	github.com/docker/cli v29.0.3+incompatible // indirect
 	github.com/docker/distribution v2.8.3+incompatible // indirect
 	github.com/docker/docker v28.5.2+incompatible // indirect
 	github.com/docker/docker-credential-helpers v0.9.4 // indirect
@@ -95,7 +97,6 @@ require (
 	github.com/go-jose/go-jose/v4 v4.1.4 // indirect
 	github.com/godbus/dbus/v5 v5.1.1-0.20241109141217-c266b19b28e9 // indirect
 	github.com/golang/protobuf v1.5.4 // indirect
-	github.com/google/go-containerregistry v0.20.7 // indirect
 	github.com/google/go-intervals v0.0.2 // indirect
 	github.com/gorilla/mux v1.8.1 // indirect
 	github.com/gorilla/schema v1.4.1 // indirect
@@ -111,6 +112,7 @@ require (
 	github.com/mattn/go-sqlite3 v1.14.32 // indirect
 	github.com/miekg/pkcs11 v1.1.1 // indirect
 	github.com/mistifyio/go-zfs/v3 v3.1.0 // indirect
+	github.com/mitchellh/go-homedir v1.1.0 // indirect
 	github.com/moby/docker-image-spec v1.3.1 // indirect
 	github.com/moby/sys/capability v0.4.0 // indirect
 	github.com/moby/term v0.5.2 // indirect
diff --git a/go.sum b/go.sum
@@ -209,6 +209,8 @@ github.com/miekg/pkcs11 v1.1.1 h1:Ugu9pdy6vAYku5DEpVWVFPYnzV+bxB+iRdbuFSu7TvU=
 github.com/miekg/pkcs11 v1.1.1/go.mod h1:XsNlhZGX73bx86s2hdc/FuaLm2CPZJemRLMA+WTFxgs=
 github.com/mistifyio/go-zfs/v3 v3.1.0 h1:FZaylcg0hjUp27i23VcJJQiuBeAZjrC8lPqCGM1CopY=
 github.com/mistifyio/go-zfs/v3 v3.1.0/go.mod h1:CzVgeB0RvF2EGzQnytKVvVSDwmKJXxkOTUGbNrTja/k=
+github.com/mitchellh/go-homedir v1.1.0 h1:lukF9ziXFxDFPkA1vsr5zpc1XuPDn/wFntq5mG+4E0Y=
+github.com/mitchellh/go-homedir v1.1.0/go.mod h1:SfyaCUpYCn1Vlf4IUYiD9fPX4A5wJrkLzIz1N1q0pr0=
 github.com/moby/docker-image-spec v1.3.1 h1:jMKff3w6PgbfSa69GfNg+zN/XLhfXJGnEx3Nl2EsFP0=
 github.com/moby/docker-image-spec v1.3.1/go.mod h1:eKmb5VW8vQEh/BAr2yvVNvuiJuY6UIocYsFu/DxxRpo=
 github.com/moby/locker v1.0.1 h1:fOXqR41zeveg4fFODix+1Ch4mj/gT0NE1XJbp/epuBg=
diff --git a/internal/schedulers/export_test.go b/internal/schedulers/export_test.go
@@ -0,0 +1,3 @@
+package schedulers
+
+func ImageRepo(image string) string { return imageRepo(image) }
diff --git a/internal/schedulers/schedulers.go b/internal/schedulers/schedulers.go
@@ -7,6 +7,8 @@ import (
 	"net/http"
 	"strings"
 
+	"github.com/google/go-containerregistry/pkg/crane"
+
 	"schedctl/internal/output"
 )
 
@@ -94,20 +96,35 @@ func ensureImageTag(image string) string {
 	return image
 }
 
-func GetScheduler(id string) (SchedulerImage, error) {
+func imageRepo(image string) string {
+	if idx := strings.Index(image, "@"); idx != -1 {
+		return image[:idx]
+	}
+
+	parts := strings.Split(image, "/")
+	last := parts[len(parts)-1]
+
+	if idx := strings.Index(last, ":"); idx != -1 {
+		parts[len(parts)-1] = last[:idx]
+	}
+
+	return strings.Join(parts, "/")
+}
+
+func GetScheduler(id, version string) (SchedulerImage, error) {
 	var result SchedulerImage
 
 	manifest := List()
 	for key, entry := range manifest {
 		if key == id {
-			result.ImageURI = ensureImageTag(entry.ImageURI)
+			result.ImageURI = resolveImageVersion(entry.ImageURI, version)
 			result.Source = SourceManifest
 			return result, nil
 		}
 	}
 
 	if isContainerImage(id) {
-		result.ImageURI = ensureImageTag(id)
+		result.ImageURI = resolveImageVersion(id, version)
 		result.Source = SourceDirect
 		return result, nil
 	}
@@ -116,3 +133,28 @@ func GetScheduler(id string) (SchedulerImage, error) {
 		"scheduler not found in manifest and input does not appear to be a valid container image URI",
 	)
 }
+
+func resolveImageVersion(image, version string) string {
+	if version != "" {
+		return imageRepo(image) + ":" + version
+	}
+
+	return ensureImageTag(image)
+}
+
+func ListVersions(id string) ([]string, error) {
+	manifest := List()
+	for key, entry := range manifest {
+		if key == id {
+			return crane.ListTags(imageRepo(entry.ImageURI))
+		}
+	}
+
+	if isContainerImage(id) {
+		return crane.ListTags(imageRepo(id))
+	}
+
+	return nil, errors.New(
+		"scheduler not found in manifest and input does not appear to be a valid container image URI",
+	)
+}
diff --git a/internal/schedulers/schedulers_test.go b/internal/schedulers/schedulers_test.go

Original file line number	Diff line number	Diff line change
`@@ -43,6 +43,7 @@ func NewRootCmd() *cli.Command {`
`43`	`43`	`NewStopCmd(),`
`44`	`44`	`NewStatusCmd(),`
`45`	`45`	`NewDoctorCmd(),`
	`46`	`+ NewVersionsCmd(),`
`46`	`47`	`},`
`47`	`48`	`}`
`48`	`49`	`}`
Original file line number	Diff line number	Diff line change
`@@ -42,7 +42,7 @@ func TestNewRootCmd(t *testing.T) {`
`42`	`42`	`func TestRootCmdHasSubcommands(t *testing.T) {`
`43`	`43`	`rootCmd := cmd.NewRootCmd()`
`44`	`44`
`45`		`- expected := []string{"run", "ps", "stop", "list", "doctor", "status"}`
	`45`	`+ expected := []string{"run", "ps", "stop", "list", "doctor", "status", "versions"}`
`46`	`46`	`for _, name := range expected {`
`47`	`47`	`assert.NotNil(t, findSubcommand(rootCmd, name), "Root command should have %s subcommand", name)`
`48`	`48`	`}`
`@@ -51,7 +51,7 @@ func TestRootCmdHasSubcommands(t *testing.T) {`
`51`	`51`	`func TestRootCmdSubcommandCount(t *testing.T) {`
`52`	`52`	`rootCmd := cmd.NewRootCmd()`
`53`	`53`
`54`		`- assert.Equal(t, 6, len(rootCmd.Commands), "Root command should declare exactly 5 subcommands")`
	`54`	`+ assert.Equal(t, 7, len(rootCmd.Commands), "Root command should declare exactly 7 subcommands")`
`55`	`55`	`}`
`56`	`56`
`57`	`57`	`func TestRootCmdHasDriverPersistentFlag(t *testing.T) {`