feat: add polling fallback for stale asset downloads #7926

luke-mino-altherr · 2026-01-09T22:28:29Z

nit: you could make the a generic and inject the zDownloadFileResult in the getTask function to future proof this a bit

That's what the caveat at the top is for.
I don't like to make single use things generic. Reusable things, those should be generic.

-Original file line number
+Diff line change
@@ Expand Up @@
     ## Testing Guidelines
+    See @docs/testing/*.md for detailed patterns.
     - Frameworks:
       - Vitest (unit/component, happy-dom)
       - Playwright (E2E)
@@ Expand Down @@

-Original file line number
+Diff line change
@@ -0,0 +1,138 @@
+    ---
+    globs:
+      - '**/*.test.ts'
+      - '**/*.spec.ts'
+    ---
+    # Vitest Patterns
+    ## Setup
+    Use `createTestingPinia` from `@pinia/testing`, not `createPinia`:
+    ```typescript
+    import { createTestingPinia } from '@pinia/testing'
+    import { setActivePinia } from 'pinia'
+    import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+    describe('MyStore', () => {
+      beforeEach(() => {
+        setActivePinia(createTestingPinia({ stubActions: false }))
+        vi.useFakeTimers()
+        vi.resetAllMocks()
+      })
+      afterEach(() => {
+        vi.useRealTimers()
+      })
+    })
+    ```
+    **Why `stubActions: false`?** By default, testing pinia stubs all actions. Set to `false` when testing actual store behavior.
+    ## Mock Patterns
+    ### Reset all mocks at once
+    ```typescript
+    beforeEach(() => {
+      vi.resetAllMocks()  // Not individual mock.mockReset() calls
+    })
+    ```
+    ### Module mocks with vi.mock()
+    ```typescript
+    vi.mock('@/scripts/api', () => ({
+      api: {
+        addEventListener: vi.fn(),
+        fetchData: vi.fn()
+      }
+    }))
+    vi.mock('@/services/myService', () => ({
+      myService: {
+        doThing: vi.fn()
+      }
+    }))
+    ```
+    ### Configure mocks in tests
+    ```typescript
+    import { api } from '@/scripts/api'
+    import { myService } from '@/services/myService'
+    it('handles success', () => {
+      vi.mocked(myService.doThing).mockResolvedValue({ data: 'test' })
+      // ... test code
+    })
+    ```
+    ## Testing Event Listeners
+    When a store registers event listeners at module load time:
+    ```typescript
+    function getEventHandler() {
+      const call = vi.mocked(api.addEventListener).mock.calls.find(
+        ([event]) => event === 'my_event'
+      )
+      return call?.[1] as (e: CustomEvent<MyEventType>) => void
+    }
+    function dispatch(data: MyEventType) {
+      const handler = getEventHandler()
+      handler(new CustomEvent('my_event', { detail: data }))
+    }
+    it('handles events', () => {
+      const store = useMyStore()
+      dispatch({ field: 'value' })
+      expect(store.items).toHaveLength(1)
+    })
+    ```
+    ## Testing with Fake Timers
+    For stores with intervals, timeouts, or polling:
+    ```typescript
+    beforeEach(() => {
+      vi.useFakeTimers()
+    })
+    afterEach(() => {
+      vi.useRealTimers()
+    })
+    it('polls after delay', async () => {
+      const store = useMyStore()
+      store.startPolling()
+      await vi.advanceTimersByTimeAsync(30000)
+      expect(mockService.fetch).toHaveBeenCalled()
+    })
+    ```
+    ## Assertion Style
+    Prefer `.toHaveLength()` over `.length.toBe()`:
+    ```typescript
+    // Good
+    expect(store.items).toHaveLength(1)
+    // Avoid
+    expect(store.items.length).toBe(1)
+    ```
+    Use `.toMatchObject()` for partial matching:
+    ```typescript
+    expect(store.completedItems[0]).toMatchObject({
+      id: 'task-123',
+      status: 'done'
+    })
+    ```

-Original file line number
+Diff line change
@@ Expand Up @@
         bytesDownloaded: 0,
         progress: 0,
         status: 'created',
+        lastUpdate: Date.now(),
         ...overrides
       }
     }
@@ Expand Down @@

-Original file line number
+Diff line change
@@ Expand Up @@
         bytesDownloaded: 0,
         progress: 0,
         status: 'created',
+        lastUpdate: Date.now(),
         ...overrides
       }
     }
@@ Expand Down @@

-Original file line number
+Diff line change
@@ -0,0 +1,70 @@
+    /**
+     * Task Service for polling background task status.
+     *
+     * CAVEAT: The `payload` and `result` schemas below are specific to
+     * `task:download_file` tasks. Other task types may have different
+     * payload/result structures. We are not generalizing this until
+     * additional use cases arise.
+     */
+    import { z } from 'zod'
+    import { fromZodError } from 'zod-validation-error'
+    import { api } from '@/scripts/api'
+    const TASKS_ENDPOINT = '/tasks'
+    const zTaskStatus = z.enum(['created', 'running', 'completed', 'failed'])
+    const zDownloadFileResult = z.object({
+      success: z.boolean(),
+      file_path: z.string().optional(),
+      bytes_downloaded: z.number().optional(),
+      content_type: z.string().optional(),
+      hash: z.string().optional(),
+      filename: z.string().optional(),
+      asset_id: z.string().optional(),
+      metadata: z.record(z.unknown()).optional(),
+      error: z.string().optional()
+    })
+    const zTaskResponse = z.object({
+      id: z.string().uuid(),
+      idempotency_key: z.string(),
+      task_name: z.string(),
+      payload: z.record(z.unknown()),
+      status: zTaskStatus,
+      result: zDownloadFileResult.optional(),
+      error_message: z.string().optional(),
+      create_time: z.string().datetime(),
+      update_time: z.string().datetime(),
+      started_at: z.string().datetime().optional(),
+      completed_at: z.string().datetime().optional()
+    })
+    export type TaskResponse = z.infer<typeof zTaskResponse>
+    function createTaskService() {
+      async function getTask(taskId: string): Promise<TaskResponse> {
+        const res = await api.fetchApi(`${TASKS_ENDPOINT}/${taskId}`)
+        if (!res.ok) {
+          if (res.status === 404) {
+            throw new Error(`Task not found: ${taskId}`)
+          }
+          throw new Error(`Failed to get task ${taskId}: ${res.status}`)
+        }
+        const data = await res.json()
+        const result = zTaskResponse.safeParse(data)
+        if (!result.success) {
+          throw new Error(fromZodError(result.error).message)
+        }
+        return result.data
+      }
+      return { getTask }
+    }
+    export const taskService = createTaskService()

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: add polling fallback for stale asset downloads #7926

Uh oh!

Diff view

Diff view

There are no files selected for viewing

luke-mino-altherr Jan 9, 2026

Uh oh!

DrJKL Jan 9, 2026

Uh oh!

DrJKL Jan 9, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

-Original file line number
+Diff line change
@@ Expand Up @@
     const zAssetDownloadWsMessage = z.object({
       task_id: z.string(),
-      asset_id: z.string(),
       asset_name: z.string(),
       bytes_total: z.number(),
       bytes_downloaded: z.number(),
       progress: z.number(),
       status: z.enum(['created', 'running', 'completed', 'failed']),
+      asset_id: z.string().optional(),
       error: z.string().optional()
     })
@@ Expand Down @@

feat: add polling fallback for stale asset downloads #7926

Uh oh!

feat: add polling fallback for stale asset downloads #7926

Uh oh!

Uh oh!

Diff view

Diff view

There are no files selected for viewing

luke-mino-altherr Jan 9, 2026

Choose a reason for hiding this comment

Uh oh!

DrJKL Jan 9, 2026

Choose a reason for hiding this comment

Uh oh!

DrJKL Jan 9, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!