Support pull interval flag for catalog show. (#257)

Author: cmrigney

cmd/docker-mcp/commands/catalog_next.go

@@ -93,22 +93,18 @@ func showCatalogNextCommand() *cobra.Command {
 			if !supported {
 				return fmt.Errorf("unsupported format: %s", format)
 			}
-			supportedPullOptions := slices.Contains(catalognext.SupportedPullOptions(), pullOption)
-			if !supportedPullOptions {
-				return fmt.Errorf("unsupported pull option: %s", pullOption)
-			}
 			dao, err := db.New()
 			if err != nil {
 				return err
 			}
 			ociService := oci.NewService()
-			return catalognext.Show(cmd.Context(), dao, ociService, args[0], workingset.OutputFormat(format), catalognext.PullOption(pullOption))
+			return catalognext.Show(cmd.Context(), dao, ociService, args[0], workingset.OutputFormat(format), pullOption)
 		},
 	}
 
 	flags := cmd.Flags()
 	flags.StringVar(&format, "format", string(workingset.OutputFormatHumanReadable), fmt.Sprintf("Supported: %s.", strings.Join(workingset.SupportedFormats(), ", ")))
-	flags.StringVar(&pullOption, "pull", string(catalognext.PullOptionNever), fmt.Sprintf("Supported: %s.", strings.Join(catalognext.SupportedPullOptions(), ", ")))
+	flags.StringVar(&pullOption, "pull", string(catalognext.PullOptionNever), fmt.Sprintf("Supported: %s, or duration (e.g. '1h', '1d'). Duration represents time since last update.", strings.Join(catalognext.SupportedPullOptions(), ", ")))
 	return cmd
 }
 

pkg/catalog_next/catalog.go

@@ -147,6 +147,9 @@ const (
 	PullOptionMissing = "missing"
 	PullOptionNever   = "never"
 	PullOptionAlways  = "always"
+
+	// Special value for duration-based pull options. Don't add as supported pull option below.
+	PullOptionDuration = "duration"
 )
 
 func SupportedPullOptions() []string {

pkg/catalog_next/show.go

@@ -7,7 +7,9 @@ import (
 	"errors"
 	"fmt"
 	"os"
+	"slices"
 	"strings"
+	"time"
 
 	"github.com/goccy/go-yaml"
 	"github.com/google/go-containerregistry/pkg/name"
@@ -17,7 +19,12 @@ import (
 	"github.com/docker/mcp-gateway/pkg/workingset"
 )
 
-func Show(ctx context.Context, dao db.DAO, ociService oci.Service, refStr string, format workingset.OutputFormat, pullOption PullOption) error {
+func Show(ctx context.Context, dao db.DAO, ociService oci.Service, refStr string, format workingset.OutputFormat, pullOptionParam string) error {
+	pullOption, pullInterval, err := parsePullOption(pullOptionParam)
+	if err != nil {
+		return err
+	}
+
 	ref, err := name.ParseReference(refStr)
 	if err != nil {
 		return fmt.Errorf("failed to parse oci-reference %s: %w", refStr, err)
@@ -37,19 +44,37 @@ func Show(ctx context.Context, dao db.DAO, ociService oci.Service, refStr string
 	}
 
 	dbCatalog, err := dao.GetCatalog(ctx, refStr)
-	if err != nil && errors.Is(err, sql.ErrNoRows) && pullOption == PullOptionMissing {
-		fmt.Fprintf(os.Stderr, "Pulling catalog %s...\n", refStr)
-		dbCatalog, err = pullCatalog(ctx, dao, ociService, refStr)
+	if err != nil && errors.Is(err, sql.ErrNoRows) && (pullOption == PullOptionMissing || pullOption == PullOptionDuration) {
+		fmt.Fprintf(os.Stderr, "Pulling catalog %s (missing)...\n", refStr)
+		_, err = pullCatalog(ctx, dao, ociService, refStr)
 		if err != nil {
 			return fmt.Errorf("failed to pull missing catalog %s: %w", refStr, err)
 		}
+		// Reload the catalog after pulling
+		dbCatalog, err = dao.GetCatalog(ctx, refStr)
+		if err != nil {
+			return fmt.Errorf("failed to get catalog %s: %w", refStr, err)
+		}
 	} else if err != nil {
 		if errors.Is(err, sql.ErrNoRows) {
 			return fmt.Errorf("catalog %s not found", refStr)
 		}
 		return fmt.Errorf("failed to get catalog: %w", err)
 	}
 
+	if pullOption == PullOptionDuration && dbCatalog.LastUpdated != nil && time.Since(*dbCatalog.LastUpdated) > pullInterval {
+		fmt.Fprintf(os.Stderr, "Pulling catalog %s... (last update was %s ago)\n", refStr, time.Since(*dbCatalog.LastUpdated).Round(time.Second))
+		_, err := pullCatalog(ctx, dao, ociService, refStr)
+		if err != nil {
+			return fmt.Errorf("failed to pull catalog %s: %w", refStr, err)
+		}
+		// Reload the catalog
+		dbCatalog, err = dao.GetCatalog(ctx, refStr)
+		if err != nil {
+			return fmt.Errorf("failed to get catalog %s: %w", refStr, err)
+		}
+	}
+
 	catalog := NewFromDb(dbCatalog)
 
 	var data []byte
@@ -86,3 +111,29 @@ func printHumanReadable(catalog CatalogWithDigest) string {
 	servers = strings.TrimSuffix(servers, "\n")
 	return fmt.Sprintf("Reference: %s\nTitle: %s\nSource: %s\nServers:\n%s", catalog.Ref, catalog.Title, catalog.Source, servers)
 }
+
+func parsePullOption(pullOptionParam string) (PullOption, time.Duration, error) {
+	if pullOptionParam == "" {
+		return PullOptionNever, 0, nil
+	}
+
+	var pullOption PullOption
+	var pullInterval time.Duration
+	isPullOption := slices.Contains(SupportedPullOptions(), pullOptionParam)
+	if isPullOption {
+		pullOption = PullOption(pullOptionParam)
+	} else {
+		// Maybe duration
+		duration, err := time.ParseDuration(pullOptionParam)
+		if err != nil {
+			return PullOptionNever, 0, fmt.Errorf("failed to parse pull option %s: should be %s, or duration (e.g. '1h', '1d')", pullOptionParam, strings.Join(SupportedPullOptions(), ", "))
+		}
+		if duration < 0 {
+			return PullOptionNever, 0, fmt.Errorf("duration %s must be positive", duration)
+		}
+		pullOption = PullOptionDuration
+		pullInterval = duration
+	}
+
+	return pullOption, pullInterval, nil
+}

pkg/catalog_next/show_test.go

@@ -208,3 +208,13 @@ func TestShowInvalidReferenceWithDigest(t *testing.T) {
 	require.Error(t, err)
 	assert.Contains(t, err.Error(), "reference test/invalid-reference@sha256:4bcff63911fcb4448bd4fdacec207030997caf25e9bea4045fa6c8c44de311d1 must be a valid OCI reference without a digest")
 }
+
+// TODO(cody): Add tests for pull once we have proper mocks in place
+func TestInvalidPullOption(t *testing.T) {
+	dao := setupTestDB(t)
+	ctx := t.Context()
+
+	err := Show(ctx, dao, getMockOciService(), "test/catalog:latest", workingset.OutputFormatJSON, "invalid")
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "failed to parse pull option invalid: should be missing, never, always, or duration (e.g. '1h', '1d')")
+}

pkg/db/catalog.go

@@ -6,6 +6,7 @@ import (
 	"encoding/json"
 	"errors"
 	"fmt"
+	"time"
 )
 
 type CatalogDAO interface {
@@ -18,11 +19,12 @@ type CatalogDAO interface {
 type ToolList []string
 
 type Catalog struct {
-	Ref     string          `db:"ref"`
-	Digest  string          `db:"digest"`
-	Title   string          `db:"title"`
-	Source  string          `db:"source"`
-	Servers []CatalogServer `db:"-"`
+	Ref         string          `db:"ref"`
+	Digest      string          `db:"digest"`
+	Title       string          `db:"title"`
+	Source      string          `db:"source"`
+	LastUpdated *time.Time      `db:"last_updated"`
+	Servers     []CatalogServer `db:"-"`
 }
 
 type CatalogServer struct {
@@ -53,7 +55,7 @@ func (tools *ToolList) Scan(value any) error {
 }
 
 func (d *dao) GetCatalog(ctx context.Context, ref string) (*Catalog, error) {
-	const query = `SELECT ref, digest, title, source FROM catalog WHERE ref = $1`
+	const query = `SELECT ref, digest, title, source, last_updated FROM catalog WHERE ref = $1`
 
 	var catalog Catalog
 	err := d.db.GetContext(ctx, &catalog, query, ref)
@@ -88,7 +90,7 @@ func (d *dao) UpsertCatalog(ctx context.Context, catalog Catalog) error {
 		return err
 	}
 
-	const insertQuery = `INSERT INTO catalog (ref, digest, title, source) VALUES ($1, $2, $3, $4)`
+	const insertQuery = `INSERT INTO catalog (ref, digest, title, source, last_updated) VALUES ($1, $2, $3, $4, current_timestamp)`
 
 	_, err = tx.ExecContext(ctx, insertQuery, catalog.Ref, catalog.Digest, catalog.Title, catalog.Source)
 	if err != nil {
@@ -133,7 +135,7 @@ func (d *dao) ListCatalogs(ctx context.Context) ([]Catalog, error) {
 		ServerJSON string `db:"server_json"`
 	}
 
-	const query = `SELECT c.ref, c.digest, c.title, c.source,
+	const query = `SELECT c.ref, c.digest, c.title, c.source, c.last_updated,
 	COALESCE(
 		json_group_array(json_object('id', s.id, 'server_type', s.server_type, 'tools', json(s.tools), 'source', s.source, 'image', s.image, 'snapshot', json(s.snapshot))),
 		'[]'

pkg/db/catalog_test.go

@@ -3,6 +3,7 @@ package db
 import (
 	"database/sql"
 	"testing"
+	"time"
 
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
@@ -40,6 +41,8 @@ func TestCreateCatalogAndGetCatalog(t *testing.T) {
 	assert.Equal(t, catalog.Source, retrieved.Source)
 	assert.Len(t, retrieved.Servers, 1)
 	assert.Equal(t, "registry", retrieved.Servers[0].ServerType)
+	assert.NotNil(t, retrieved.LastUpdated)
+	assert.WithinDuration(t, time.Now().UTC(), *retrieved.LastUpdated, 60*time.Second)
 }
 
 func TestCreateCatalogWithEmptyServers(t *testing.T) {
@@ -272,6 +275,11 @@ func TestListCatalogsWithServersAndSnapshots(t *testing.T) {
 	require.NoError(t, err)
 	assert.Len(t, retrieved, 2)
 
+	assert.NotNil(t, retrieved[0].LastUpdated)
+	assert.NotNil(t, retrieved[1].LastUpdated)
+	assert.WithinDuration(t, time.Now().UTC(), *retrieved[0].LastUpdated, 60*time.Second)
+	assert.WithinDuration(t, time.Now().UTC(), *retrieved[1].LastUpdated, 60*time.Second)
+
 	// Find catalog 1 and verify
 	var cat1 *Catalog
 	for i := range retrieved {

pkg/db/migrations/003_add_catalog_last_update.up.sql

@@ -0,0 +1,2 @@
+alter table catalog add column last_updated DATETIME;
+update catalog set last_updated = current_timestamp;