Blob Storage Integration — Sync Status State Machine

The blob storage exporter's UI status is derived from five DB fields on BlobStorageIntegration. No explicit status column exists — the status is computed at read time by deriveSyncStatus.ts.

DB fields (the state vector)

Derived states (precedence top-to-bottom)

disabled    ← enabled = false (set by user save, or by the worker after a
              final-attempt customer-config/credential failure)
error       ← lastError != null
running     ← runStartedAt != null AND age < 2h
queued      ← nextSyncAt <= now
idle        ← lastSyncAt = null (never exported)
up_to_date  ← fallthrough

Transition diagram

                      ┌──────────────────────────────────────────┐
                      │           User saves (web)               │
                      │  runStartedAt = null                     │
                      │  if errored+enabled: nextSyncAt = now    │
                      │  if mode changed: lastSyncAt = null,     │
                      │                   nextSyncAt = now       │
                      └────────────────┬─────────────────────────┘
                                       │
    ┌──────────┐                       ▼
    │ disabled │◄──── enabled = false (any state)
    └──────────┘
         │ user enables
         ▼
    ┌──────────┐   nextSyncAt = null, lastSyncAt = null
    │   idle   │◄──── freshly created, never synced
    └──────────┘
         │ save sets nextSyncAt = now (on mode change or save while errored)
         ▼
    ┌──────────┐   nextSyncAt <= now
    │  queued  │◄──── scheduler finds row (lastSyncAt=null OR nextSyncAt<=now)
    └──────────┘      and enqueues a BullMQ job (no DB write)
         │
         │ worker picks up job, sets runStartedAt = new Date()
         ▼
    ┌──────────┐
    │ running  │   runStartedAt set, age < 2h
    └──────────┘
        ╱    ╲
  success    failure
      ╱        ╲
     ▼          ▼
┌───────────┐  ┌───────┐
│ up_to_date│  │ error │
└───────────┘  └───────┘
                   │ final-attempt customer-fault → enabled = false
                   ▼
              ┌──────────┐
              │ disabled │
              └──────────┘

Transition detail

Safety valve

If a worker crashes without clearing runStartedAt, the 2h TTL in deriveSyncStatus lets the status fall through to whatever the underlying fields indicate (typically queued, since the scheduler will re-enqueue on the next tick). No explicit cleanup is needed.

Run Now (manual trigger)

Run Now only enqueues a BullMQ job with a unique manual- jobId. It does not write any DB state. The worker then follows the normal running → success/failure path. The UI shows the current status (error/up_to_date/queued) until the worker picks up the job and sets runStartedAt.

Key files

UI Owner Map

Surface: Project Settings → Integrations → Blob Storage — export configuration form plus sync status display.

Entry point: web/src/pages/project/[projectId]/settings/integrations/blobstorage.tsx owns the lifecycle: the tRPC get query (with status-driven refetch interval), the sync-status badge, and page layout. It mounts the two feature components below.

Structure (components/):

External consumers: none — the components are only mounted by the settings page above.

State ownership — draft-lifetime model: server state lives in the tRPC query (page). Form state is a disposable draft scoped to one entity identity: the container mounts BlobStorageIntegrationForm keyed on projectId + config existence, only after the query and project have resolved. Initial values flow in once via defaultValues; edits flow out only via onSubmit. There is no reset path at all — no reactive values, no resetOptions, no reset useEffect. Identity changes (project switch, create, delete) remount the form; same-entity refetches (5s status poll, post-save invalidation) keep the key stable and therefore can never wipe or leak a draft. Consequence, by design: clean fields do not live-update from background refetches while the form is mounted. Field-group components receive the typed control prop and subscribe to individual fields with useWatch; there is no local Zustand store and no feature useEffect.

Performance boundaries: a keystroke or select change rerenders only the field-group component watching that field. The form layer reads no field values and holds no async state; mutation pending-state lives in the container.