feat: add max-age option to provisioners list command

rafrdz · rafrdz · commit 95713c5b1af5 · 2025-08-15T19:49:46.000Z
diff --git a/cli/provisioners.go b/cli/provisioners.go
@@ -2,6 +2,7 @@ package cli
 
 import (
 	"fmt"
+	"time"
 
 	"golang.org/x/xerrors"
 
@@ -43,6 +44,7 @@ func (r *RootCmd) provisionerList() *serpent.Command {
 		limit   int64
 		offline bool
 		status  []string
+		maxAge  time.Duration
 	)
 
 	cmd := &serpent.Command{
@@ -65,6 +67,7 @@ func (r *RootCmd) provisionerList() *serpent.Command {
 				Limit:   int(limit),
 				Offline: offline,
 				Status:  slice.StringEnums[codersdk.ProvisionerDaemonStatus](status),
+				MaxAge:  maxAge,
 			})
 			if err != nil {
 				return xerrors.Errorf("list provisioner daemons: %w", err)
@@ -104,10 +107,11 @@ func (r *RootCmd) provisionerList() *serpent.Command {
 			Value:         serpent.Int64Of(&limit),
 		},
 		{
-			Flag:        "show-offline",
-			Env:         "CODER_PROVISIONER_SHOW_OFFLINE",
-			Description: "Show offline provisioners.",
-			Value:       serpent.BoolOf(&offline),
+			Flag:          "show-offline",
+			FlagShorthand: "f",
+			Env:           "CODER_PROVISIONER_SHOW_OFFLINE",
+			Description:   "Show offline provisioners.",
+			Value:         serpent.BoolOf(&offline),
 		},
 		{
 			Flag:          "status",
@@ -116,6 +120,13 @@ func (r *RootCmd) provisionerList() *serpent.Command {
 			Description:   "Filter by provisioner status.",
 			Value:         serpent.EnumArrayOf(&status, slice.ToStrings(codersdk.ProvisionerDaemonStatusEnums())...),
 		},
+		{
+			Flag:          "max-age",
+			FlagShorthand: "m",
+			Env:           "CODER_PROVISIONER_LIST_MAX_AGE",
+			Description:   "Filter provisioners by maximum age.",
+			Value:         serpent.DurationOf(&maxAge),
+		},
 	}...)
 
 	orgContext.AttachOptions(cmd)
diff --git a/cli/provisioners_test.go b/cli/provisioners_test.go
@@ -249,6 +249,23 @@ func TestProvisioners_Golden(t *testing.T) {
 		clitest.TestGoldenFile(t, t.Name(), got.Bytes(), replace)
 	})
 
+	t.Run("list provisioner daemons by max age", func(t *testing.T) {
+		t.Parallel()
+
+		var got bytes.Buffer
+		inv, root := clitest.New(t,
+			"provisioners",
+			"list",
+			"--max-age=1h",
+		)
+		inv.Stdout = &got
+		clitest.SetupConfig(t, templateAdminClient, root)
+		err := inv.Run()
+		require.NoError(t, err)
+
+		clitest.TestGoldenFile(t, t.Name(), got.Bytes(), replace)
+	})
+
 	// Test jobs list with template admin as members are currently
 	// unable to access provisioner jobs. In the future (with RBAC
 	// changes), we may allow them to view _their_ jobs.
diff --git a/cli/testdata/TestProvisioners_Golden/list_provisioner_daemons_by_max_age.golden b/cli/testdata/TestProvisioners_Golden/list_provisioner_daemons_by_max_age.golden
@@ -0,0 +1,4 @@
+CREATED AT            LAST SEEN AT          KEY NAME  NAME                 VERSION       STATUS  TAGS                                    
+====[timestamp]=====  ====[timestamp]=====  built-in  default-provisioner  v0.0.0-devel  idle    map[owner: scope:organization]          
+====[timestamp]=====  ====[timestamp]=====  built-in  provisioner-1        v0.0.0        busy    map[foo:bar owner: scope:organization]  
+====[timestamp]=====  ====[timestamp]=====  built-in  provisioner-3        v0.0.0        idle    map[owner: scope:organization]          
diff --git a/cli/testdata/coder_provisioner_list_--help.golden b/cli/testdata/coder_provisioner_list_--help.golden
@@ -17,10 +17,13 @@ OPTIONS:
   -l, --limit int, $CODER_PROVISIONER_LIST_LIMIT (default: 50)
           Limit the number of provisioners returned.
 
+  -m, --max-age duration, $CODER_PROVISIONER_LIST_MAX_AGE
+          Filter provisioners by maximum age.
+
   -o, --output table|json (default: table)
           Output format.
 
-      --show-offline bool, $CODER_PROVISIONER_SHOW_OFFLINE
+  -f, --show-offline bool, $CODER_PROVISIONER_SHOW_OFFLINE
           Show offline provisioners.
 
   -s, --status [offline|idle|busy], $CODER_PROVISIONER_LIST_STATUS
diff --git a/coderd/database/querier_test.go b/coderd/database/querier_test.go
@@ -635,6 +635,73 @@ func TestGetProvisionerDaemonsWithStatusByOrganization(t *testing.T) {
 			})
 		}
 	})
+
+	t.Run("FilterByMaxAge", func(t *testing.T) {
+		t.Parallel()
+		db, _ := dbtestutil.NewDB(t)
+		org := dbgen.Organization(t, db, database.Organization{})
+
+		dbgen.ProvisionerDaemon(t, db, database.ProvisionerDaemon{
+			Name:           "foo-daemon",
+			OrganizationID: org.ID,
+			CreatedAt:      dbtime.Now().Add(-(45 * time.Minute)),
+			LastSeenAt: sql.NullTime{
+				Valid: true,
+				Time:  dbtime.Now().Add(-(45 * time.Minute)),
+			},
+		})
+
+		dbgen.ProvisionerDaemon(t, db, database.ProvisionerDaemon{
+			Name:           "bar-daemon",
+			OrganizationID: org.ID,
+			CreatedAt:      dbtime.Now().Add(-(25 * time.Minute)),
+			LastSeenAt: sql.NullTime{
+				Valid: true,
+				Time:  dbtime.Now().Add(-(25 * time.Minute)),
+			},
+		})
+
+		type testCase struct {
+			name        string
+			maxAge      sql.NullInt64
+			expectedNum int
+		}
+
+		tests := []testCase{
+			{
+				name:        "Max age 1 hour",
+				maxAge:      sql.NullInt64{Int64: time.Hour.Milliseconds(), Valid: true},
+				expectedNum: 2,
+			},
+			{
+				name:        "Max age 30 minutes",
+				maxAge:      sql.NullInt64{Int64: (30 * time.Minute).Milliseconds(), Valid: true},
+				expectedNum: 1,
+			},
+			{
+				name:        "Max age 15 minutes",
+				maxAge:      sql.NullInt64{Int64: (15 * time.Minute).Milliseconds(), Valid: true},
+				expectedNum: 0,
+			},
+			{
+				name:        "No max age",
+				maxAge:      sql.NullInt64{Valid: false},
+				expectedNum: 2,
+			},
+		}
+		for _, tc := range tests {
+			//nolint:tparallel,paralleltest
+			t.Run(tc.name, func(t *testing.T) {
+				daemons, err := db.GetProvisionerDaemonsWithStatusByOrganization(context.Background(), database.GetProvisionerDaemonsWithStatusByOrganizationParams{
+					OrganizationID:  org.ID,
+					StaleIntervalMS: 60 * time.Minute.Milliseconds(),
+					MaxAgeMs:        tc.maxAge,
+				})
+				require.NoError(t, err)
+				require.Len(t, daemons, tc.expectedNum)
+			})
+		}
+	})
 }
 
 func TestGetWorkspaceAgentUsageStats(t *testing.T) {
diff --git a/coderd/database/queries.sql.go b/coderd/database/queries.sql.go
diff --git a/coderd/database/queries/provisionerdaemons.sql b/coderd/database/queries/provisionerdaemons.sql
@@ -110,10 +110,16 @@ WHERE
 	pd.organization_id = @organization_id::uuid
 	AND (COALESCE(array_length(@ids::uuid[], 1), 0) = 0 OR pd.id = ANY(@ids::uuid[]))
 	AND (@tags::tagset = 'null'::tagset OR provisioner_tagset_contains(pd.tags::tagset, @tags::tagset))
+	-- Filter by max age if provided
 	AND (
-		-- Include daemons that have been seen recently
+		sqlc.narg('max_age_ms')::bigint IS NULL
+		OR pd.last_seen_at IS NULL 
+		OR pd.last_seen_at >= (NOW() - (sqlc.narg('max_age_ms')::bigint || ' ms')::interval)
+	)
+	AND (
+		-- Always include online daemons
 		(pd.last_seen_at IS NOT NULL AND pd.last_seen_at >= (NOW() - (@stale_interval_ms::bigint || ' ms')::interval))
-		-- Include offline daemons only when offline param is set OR 'offline' is in the list of statuses
+		-- Include offline daemons if offline param is true or 'offline' status is requested
 		OR (
 			(pd.last_seen_at IS NULL OR pd.last_seen_at < (NOW() - (@stale_interval_ms::bigint || ' ms')::interval))
 			AND (
@@ -122,15 +128,17 @@ WHERE
 			)
 		)
 	)
-	-- Filter daemons by their current status if statuses are provided
 	AND (
+		-- Filter daemons by any statuses if provided
 		COALESCE(array_length(@statuses::provisioner_daemon_status[], 1), 0) = 0
+		OR (current_job.id IS NOT NULL AND 'busy'::provisioner_daemon_status = ANY(@statuses::provisioner_daemon_status[]))
+		OR (current_job.id IS NULL AND 'idle'::provisioner_daemon_status = ANY(@statuses::provisioner_daemon_status[]))
 		OR (
-		    (current_job.id IS NOT NULL AND 'busy'::provisioner_daemon_status = ANY(@statuses::provisioner_daemon_status[]))
-		    OR (current_job.id IS NULL AND 'idle'::provisioner_daemon_status = ANY(@statuses::provisioner_daemon_status[]))
+		    'offline'::provisioner_daemon_status = ANY(@statuses::provisioner_daemon_status[])
+		    AND (pd.last_seen_at IS NULL OR pd.last_seen_at < (NOW() - (@stale_interval_ms::bigint || ' ms')::interval))
 		)
 		OR (
-		    (COALESCE(sqlc.narg('offline')::bool, false) = true OR 'offline'::provisioner_daemon_status = ANY(@statuses::provisioner_daemon_status[]))
+		    COALESCE(sqlc.narg('offline')::bool, false) = true
 		    AND (pd.last_seen_at IS NULL OR pd.last_seen_at < (NOW() - (@stale_interval_ms::bigint || ' ms')::interval))
 		)
 	)
diff --git a/coderd/httpapi/queryparams.go b/coderd/httpapi/queryparams.go
@@ -293,6 +293,23 @@ func (p *QueryParamParser) ProvisionerDaemonStatuses(vals url.Values, def []code
 	})
 }
 
+func (p *QueryParamParser) Duration(vals url.Values, def time.Duration, queryParam string) time.Duration {
+	v, err := parseQueryParam(p, vals, func(v string) (time.Duration, error) {
+		d, err := time.ParseDuration(v)
+		if err != nil {
+			return 0, err
+		}
+		return d, nil
+	}, def, queryParam)
+	if err != nil {
+		p.Errors = append(p.Errors, codersdk.ValidationError{
+			Field:  queryParam,
+			Detail: fmt.Sprintf("Query param %q must be a valid duration (e.g., '24h', '30m', '1h30m'): %s", queryParam, err.Error()),
+		})
+	}
+	return v
+}
+
 // ValidEnum represents an enum that can be parsed and validated.
 type ValidEnum interface {
 	// Add more types as needed (avoid importing large dependency trees).
diff --git a/coderd/provisionerdaemons.go b/coderd/provisionerdaemons.go
@@ -48,6 +48,7 @@ func (api *API) provisionerDaemons(rw http.ResponseWriter, r *http.Request) {
 	tags := p.JSONStringMap(qp, database.StringMap{}, "tags")
 	includeOffline := p.NullableBoolean(qp, sql.NullBool{}, "offline")
 	statuses := p.ProvisionerDaemonStatuses(qp, []codersdk.ProvisionerDaemonStatus{}, "status")
+	maxAge := p.Duration(qp, 0, "max_age")
 	p.ErrorExcessParams(qp)
 	if len(p.Errors) > 0 {
 		httpapi.Write(ctx, rw, http.StatusBadRequest, codersdk.Response{
@@ -67,6 +68,7 @@ func (api *API) provisionerDaemons(rw http.ResponseWriter, r *http.Request) {
 			Limit:           sql.NullInt32{Int32: limit, Valid: limit > 0},
 			Offline:         includeOffline,
 			Statuses:        dbStatuses,
+			MaxAgeMs:        sql.NullInt64{Int64: maxAge.Milliseconds(), Valid: maxAge > 0},
 			IDs:             ids,
 			Tags:            tags,
 		},
diff --git a/codersdk/organizations.go b/codersdk/organizations.go
@@ -347,6 +347,7 @@ type OrganizationProvisionerDaemonsOptions struct {
 	Limit   int
 	Offline bool
 	Status  []ProvisionerDaemonStatus
+	MaxAge  time.Duration
 	IDs     []uuid.UUID
 	Tags    map[string]string
 }
@@ -363,6 +364,9 @@ func (c *Client) OrganizationProvisionerDaemons(ctx context.Context, organizatio
 		if len(opts.Status) > 0 {
 			qp.Add("status", joinSlice(opts.Status))
 		}
+		if opts.MaxAge > 0 {
+			qp.Add("max_age", opts.MaxAge.String())
+		}
 		if len(opts.IDs) > 0 {
 			qp.Add("ids", joinSliceStringer(opts.IDs))
 		}
diff --git a/docs/reference/cli/provisioner_list.md b/docs/reference/cli/provisioner_list.md
diff --git a/enterprise/cli/testdata/coder_provisioner_list_--help.golden b/enterprise/cli/testdata/coder_provisioner_list_--help.golden
@@ -17,10 +17,13 @@ OPTIONS:
   -l, --limit int, $CODER_PROVISIONER_LIST_LIMIT (default: 50)
           Limit the number of provisioners returned.
 
+  -m, --max-age duration, $CODER_PROVISIONER_LIST_MAX_AGE
+          Filter provisioners by maximum age.
+
   -o, --output table|json (default: table)
           Output format.
 
-      --show-offline bool, $CODER_PROVISIONER_SHOW_OFFLINE
+  -f, --show-offline bool, $CODER_PROVISIONER_SHOW_OFFLINE
           Show offline provisioners.
 
   -s, --status [offline|idle|busy], $CODER_PROVISIONER_LIST_STATUS
diff --git a/site/src/api/typesGenerated.ts b/site/src/api/typesGenerated.ts

Original file line number	Diff line number	Diff line change
`@@ -347,6 +347,7 @@ type OrganizationProvisionerDaemonsOptions struct {`
`347`	`347`	`Limit int`
`348`	`348`	`Offline bool`
`349`	`349`	`Status []ProvisionerDaemonStatus`
	`350`	`+ MaxAge time.Duration`
`350`	`351`	`IDs []uuid.UUID`
`351`	`352`	`Tags map[string]string`
`352`	`353`	`}`
`@@ -363,6 +364,9 @@ func (c *Client) OrganizationProvisionerDaemons(ctx context.Context, organizatio`
`363`	`364`	`if len(opts.Status) > 0 {`
`364`	`365`	`qp.Add("status", joinSlice(opts.Status))`
`365`	`366`	`}`
	`367`	`+ if opts.MaxAge > 0 {`
	`368`	`+ qp.Add("max_age", opts.MaxAge.String())`
	`369`	`+ }`
`366`	`370`	`if len(opts.IDs) > 0 {`
`367`	`371`	`qp.Add("ids", joinSliceStringer(opts.IDs))`
`368`	`372`	`}`