feat: add cron scheduling mode for image update checks (#1460)

* feat: add cron scheduling mode for image update checks Adds a cron scheduling mode alongside the existing fixed-interval dropdown in Settings > Automation > Image update checks. Users can now set a 5-field cron expression (e.g. "0 3 * * 1") for precise time-of-day scheduling of registry polls. - Backend: ImageUpdateService gains mode/cronExpression fields and cron-based nextDelayMs() using the existing cron-parser dependency. PUT /api/image-updates/interval extended with transactional writes and server-authoritative cron validation matching the Scheduled Operations contract. Nicknames like @daily are supported. - Frontend: UpdatesSection gains a SegmentedControl toggle and cron text input with cronstrue-powered live description. The frontend does advisory validation only; backend 400s are surfaced inline. SettingsPrimaryButton used for explicit "Save schedule" action. - No cron jitter (the user chose a specific time). Interval mode keeps existing ±10% jitter. - Tests: 15 new backend tests covering valid cron, invalid cron, 6-field rejection, nickname support, backward compat, runtime fallback, and transactional writes. - Docs: auto-update-policies.mdx, alerts-notifications.mdx, and openapi.yaml updated with new scheduling mode. * fix: add mode and cronExpression to UpdatesSection test fixtures The existing tests failed because the mock status object was missing the new required fields (mode, cronExpression) added with cron scheduling support. Without them, status.mode was undefined, causing uiMode to never match 'interval' and the Select combobox to not render. * fix: prevent SegmentedControl from stretching full-width in SettingsField The flex-col container defaults items to align-self: stretch, making the Interval/Cron toggle bar span the full card width. Add self-start so it sizes to its content.
2026-08-07 17:34:23 +00:00 · 2026-06-25 19:47:57 -04:00
parent 3bf677af6c
commit 7320a86579
12 changed files with 558 additions and 34 deletions
@@ -143,6 +143,8 @@ describe('CadenceStrip', () => {
      nextCheckAt: Date.now() + 110 * 60 * 1000,
      manualCooldownMinutes: 2,
      manualCooldownRemainingMs: 0,
+      mode: 'interval' as const,
+      cronExpression: null,
    };
    render(<CadenceStrip cadence={cadence} />);
    expect(screen.getByText(/Last checked 10m ago/)).toBeInTheDocument();
@@ -158,6 +160,8 @@ describe('CadenceStrip', () => {
      nextCheckAt: null,
      manualCooldownMinutes: 2,
      manualCooldownRemainingMs: 0,
+      mode: 'interval' as const,
+      cronExpression: null,
    };
    render(<CadenceStrip cadence={cadence} />);
    expect(screen.getByText(/Last checked never/)).toBeInTheDocument();
@@ -173,6 +177,8 @@ describe('CadenceStrip', () => {
      nextCheckAt: Date.now() + 7_200_000,
      manualCooldownMinutes: 2,
      manualCooldownRemainingMs: 3000,
+      mode: 'interval' as const,
+      cronExpression: null,
    };
    render(<CadenceStrip cadence={cadence} />);
    expect(screen.getByText(/Recheck available in 3s/)).toBeInTheDocument();
@@ -1,5 +1,6 @@
 import { useState, useEffect, useCallback } from 'react';
 import { Skeleton } from '@/components/ui/skeleton';
+import { Input } from '@/components/ui/input';
 import {
    Select,
    SelectContent,
@@ -7,16 +8,21 @@ import {
    SelectTrigger,
    SelectValue,
 } from '@/components/ui/select';
+import { SegmentedControl } from '@/components/ui/segmented-control';
+import { SettingsPrimaryButton } from './SettingsActions';
 import { apiFetch } from '@/lib/api';
 import { toast } from '@/components/ui/toast-store';
 import { useNodes } from '@/context/NodeContext';
 import { useAuth } from '@/context/AuthContext';
 import { formatTimeAgo, formatTimeUntil } from '@/lib/relativeTime';
+import { getCronDescription, getCronFieldError } from '@/lib/scheduling';
 import { SettingsSection } from './SettingsSection';
 import { SettingsField } from './SettingsField';
 import { useMastheadStats } from './MastheadStatsContext';
 import type { ImageUpdateStatus } from '@/types/imageUpdates';

+type ImageCheckMode = 'interval' | 'cron';
+
 const INTERVAL_PRESETS: { minutes: number; label: string }[] = [
    { minutes: 15, label: '15 minutes' },
    { minutes: 30, label: '30 minutes' },
@@ -44,6 +50,15 @@ export function UpdatesSection() {
    const [isLoading, setIsLoading] = useState(false);
    const [isSaving, setIsSaving] = useState(false);

+    // uiMode drives which control is visible. It is initialized from status.mode
+    // on first fetch and synced back only after successful PUTs, so the user can
+    // switch to Cron locally without persisting, and stay on Cron after a 400.
+    const [uiMode, setUiMode] = useState<ImageCheckMode>('interval');
+    // Draft cron text for the input; the saved expression lives in status.cronExpression.
+    const [draftCron, setDraftCron] = useState('');
+    // Inline error from a failed cron save (backend 400 message).
+    const [saveError, setSaveError] = useState<string | null>(null);
+
    const intervalMinutes = status?.intervalMinutes ?? null;

    useMastheadStats(
@@ -60,7 +75,13 @@ export function UpdatesSection() {
                const res = await apiFetch('/image-updates/status');
                if (!res.ok) throw new Error('Failed to load image-update status');
                const data = await res.json() as ImageUpdateStatus;
-                if (!cancelled) setStatus(data);
+                if (!cancelled) {
+                    setStatus(data);
+                    setUiMode(data.mode);
+                    if (data.mode === 'cron' && data.cronExpression) {
+                        setDraftCron(data.cronExpression);
+                    }
+                }
            } catch (e) {
                console.error('Failed to fetch image-update status', e);
                if (!cancelled) toast.error((e as Error)?.message || 'Failed to load image-update status.');
@@ -72,14 +93,20 @@ export function UpdatesSection() {
        return () => { cancelled = true; };
    }, [activeNode?.id]);

+    // ── Interval change (immediate save) ──────────────────────────────────
+
    const handleIntervalChange = useCallback(async (value: string) => {
        const minutes = Number(value);
        if (!Number.isInteger(minutes)) return;
        setIsSaving(true);
        try {
+            const body: Record<string, unknown> = { minutes };
+            // When in interval mode, always send mode: 'interval' to clear any
+            // stale cron config on the server.
+            body.mode = 'interval';
            const res = await apiFetch('/image-updates/interval', {
                method: 'PUT',
-                body: JSON.stringify({ minutes }),
+                body: JSON.stringify(body),
            });
            if (!res.ok) {
                const err = await res.json().catch(() => ({}));
@@ -87,6 +114,8 @@ export function UpdatesSection() {
            }
            const data = await res.json() as ImageUpdateStatus;
            setStatus(data);
+            setUiMode('interval');
+            setSaveError(null);
            toast.success(`Sencho now checks for image updates every ${formatIntervalLabel(data.intervalMinutes)}.`);
        } catch (e) {
            toast.error((e as Error)?.message || 'Failed to update interval.');
@@ -95,6 +124,78 @@ export function UpdatesSection() {
        }
    }, []);

+    // ── Mode toggle ───────────────────────────────────────────────────────
+
+    const handleModeChange = useCallback((next: ImageCheckMode) => {
+        setSaveError(null);
+        if (next === 'interval') {
+            // Switching to Interval: immediately persist.
+            setIsSaving(true);
+            const minutes = intervalMinutes ?? 120;
+            apiFetch('/image-updates/interval', {
+                method: 'PUT',
+                body: JSON.stringify({ minutes, mode: 'interval' }),
+            })
+                .then(async res => {
+                    if (!res.ok) throw new Error('Failed to switch to interval mode');
+                    const data = await res.json() as ImageUpdateStatus;
+                    setStatus(data);
+                    setUiMode('interval');
+                })
+                .catch(e => {
+                    toast.error((e as Error)?.message || 'Failed to switch to interval mode.');
+                    // Keep uiMode on 'cron' on failure; do not optimistically switch.
+                })
+                .finally(() => setIsSaving(false));
+        } else {
+            // Switching to Cron: local UI only. Draft input appears.
+            setUiMode('cron');
+            if (!draftCron && status?.cronExpression) {
+                setDraftCron(status.cronExpression);
+            }
+        }
+    }, [intervalMinutes, status?.cronExpression, draftCron]);
+
+    // ── Cron save ─────────────────────────────────────────────────────────
+
+    const cronTrimmed = draftCron.trim();
+    const cronFieldError = getCronFieldError(draftCron);
+    const cronDescription = cronTrimmed.length > 0 ? getCronDescription(draftCron) : '';
+    const hasDescriptionError = cronTrimmed.length > 0 && cronDescription === 'Invalid expression';
+    const canSaveCron = cronTrimmed.length > 0 && !cronFieldError && !hasDescriptionError && !isSaving;
+
+    const handleSaveCron = useCallback(async () => {
+        if (!canSaveCron || intervalMinutes == null) return;
+        setIsSaving(true);
+        setSaveError(null);
+        try {
+            const res = await apiFetch('/image-updates/interval', {
+                method: 'PUT',
+                body: JSON.stringify({
+                    minutes: intervalMinutes,
+                    mode: 'cron',
+                    cron: cronTrimmed,
+                }),
+            });
+            if (!res.ok) {
+                const err = await res.json().catch(() => ({}));
+                const msg = err?.error || 'Failed to save cron schedule';
+                setSaveError(msg);
+                // Keep uiMode='cron', keep draft. status.mode stays unchanged.
+                return;
+            }
+            const data = await res.json() as ImageUpdateStatus;
+            setStatus(data);
+            setUiMode('cron');
+            setDraftCron(data.cronExpression ?? '');
+            toast.success('Image update checks now run on a cron schedule.');
+        } catch (e) {
+            setSaveError((e as Error)?.message || 'Failed to save cron schedule.');
+        } finally {
+            setIsSaving(false);
+        }
+    }, [canSaveCron, intervalMinutes, cronTrimmed]);
+
    if (isLoading && !status) return <SectionSkeleton />;

    // A value set via the API (any integer 15-1440) may not be a preset; surface
@@ -115,25 +216,64 @@ export function UpdatesSection() {
            <SettingsSection title="Registry checks" kicker="node-scoped">
                <SettingsField
                    label="Check registries for image updates every"
-                    helper="Sencho checks registries on this interval to detect available image updates and raise notifications. Scheduled auto-update tasks apply updates on their own schedule; this only controls how often Sencho looks. Each node checks on its own interval."
+                    helper="Sencho checks registries to detect available image updates and raise notifications. Choose a fixed interval, or set a cron expression for precise scheduling. Cron expressions run in the node's local timezone. Each node checks on its own schedule."
                >
-                    <div className="flex flex-col gap-2">
-                        <Select
-                            value={intervalMinutes != null ? String(intervalMinutes) : undefined}
-                            onValueChange={handleIntervalChange}
-                            disabled={readOnly || isSaving || intervalMinutes == null}
-                        >
-                            <SelectTrigger className="w-44" aria-label="Image update check interval">
-                                <SelectValue placeholder="Select interval" />
-                            </SelectTrigger>
-                            <SelectContent>
-                                {options.map(opt => (
-                                    <SelectItem key={opt.minutes} value={String(opt.minutes)}>
-                                        {opt.label}
-                                    </SelectItem>
-                                ))}
-                            </SelectContent>
-                        </Select>
+                    <div className="flex flex-col gap-3">
+                        <SegmentedControl<ImageCheckMode>
+                            value={uiMode}
+                            onChange={handleModeChange}
+                            ariaLabel="Image check scheduling mode"
+                            className="self-start"
+                            options={[
+                                { value: 'interval', label: 'Interval' },
+                                { value: 'cron', label: 'Cron' },
+                            ]}
+                        />
+
+                        {uiMode === 'interval' ? (
+                            <Select
+                                value={intervalMinutes != null ? String(intervalMinutes) : undefined}
+                                onValueChange={handleIntervalChange}
+                                disabled={readOnly || isSaving || intervalMinutes == null}
+                            >
+                                <SelectTrigger className="w-44" aria-label="Image update check interval">
+                                    <SelectValue placeholder="Select interval" />
+                                </SelectTrigger>
+                                <SelectContent>
+                                    {options.map(opt => (
+                                        <SelectItem key={opt.minutes} value={String(opt.minutes)}>
+                                            {opt.label}
+                                        </SelectItem>
+                                    ))}
+                                </SelectContent>
+                            </Select>
+                        ) : (
+                            <div className="flex flex-col gap-2">
+                                <div className="flex items-center gap-2">
+                                    <Input
+                                        className="font-mono w-44"
+                                        placeholder="0 3 * * 1"
+                                        value={draftCron}
+                                        onChange={e => { setDraftCron(e.target.value); setSaveError(null); }}
+                                        disabled={readOnly || isSaving}
+                                    />
+                                    <SettingsPrimaryButton
+                                        disabled={!canSaveCron}
+                                        onClick={handleSaveCron}
+                                    >
+                                        Save schedule
+                                    </SettingsPrimaryButton>
+                                </div>
+                                {saveError
+                                    ? <p className="text-xs text-destructive">{saveError}</p>
+                                    : cronFieldError
+                                        ? <p className="text-xs text-destructive">{cronFieldError}</p>
+                                        : cronDescription
+                                            ? <p className="text-xs text-stat-subtitle">{cronDescription}</p>
+                                            : null}
+                            </div>
+                        )}
+
                        <p className="font-mono text-[11px] text-stat-subtitle/90">
                            Last checked {lastChecked} · Next check {nextCheck}
                        </p>
@@ -30,6 +30,8 @@ const STATUS = {
    nextCheckAt: Date.now() + 115 * 60 * 1000,
    manualCooldownMinutes: 2,
    manualCooldownRemainingMs: 0,
+    mode: 'interval' as const,
+    cronExpression: null,
 };

 beforeEach(() => {
@@ -18,4 +18,8 @@ export interface ImageUpdateStatus {
    nextCheckAt: number | null;
    manualCooldownMinutes: number;
    manualCooldownRemainingMs: number;
+    /** Active scheduling mode. */
+    mode: 'interval' | 'cron';
+    /** 5-field cron expression when mode is 'cron', null otherwise. */
+    cronExpression: string | null;
 }