poll

Documentation

Index

• func Poll(ctx context.Context, cfg Config, fetch Fetcher) (string, error)
• func PollV2(ctx context.Context, cfg Config, fetch FetcherV2) (string, error)
• func WithOnProgress(ctx context.Context, fn OnProgress) context.Context
• func WithOnProgressV2(ctx context.Context, fn OnProgressV2) context.Context
• type Config
• type FetchResult
• type Fetcher
• type FetcherV2
• type OnProgress
• type OnProgressV2
  • func OnProgressV2FromContext(ctx context.Context) OnProgressV2
• type ProgressInfo
• type TaskStatus
  • func MapStatus(raw string) TaskStatus
  • func (s TaskStatus) Done() bool
  • func (s TaskStatus) String() string

Functions

func Poll

func Poll(ctx context.Context, cfg Config, fetch Fetcher) (string, error)

Poll calls fetch repeatedly until it returns done or an error. It calls fetch immediately on the first iteration (no initial wait).

func PollV2

func PollV2(ctx context.Context, cfg Config, fetch FetcherV2) (string, error)

PollV2 is like Poll but accepts a FetcherV2 that returns extended progress info.

func WithOnProgress

func WithOnProgress(ctx context.Context, fn OnProgress) context.Context

WithOnProgress attaches a progress callback to the context. When Poll is called without Config.OnProgress, it falls back to this.

func WithOnProgressV2

func WithOnProgressV2(ctx context.Context, fn OnProgressV2) context.Context

WithOnProgressV2 attaches an extended progress callback to the context.

Types

type Config

type Config struct {
	Interval    time.Duration // base polling interval
	MaxAttempts int           // 0 means unlimited
	Backoff     float64       // multiplier per attempt; 1.0 = fixed interval
	MaxInterval time.Duration // upper bound for backoff growth
	OnProgress  OnProgress    // optional progress callback
}

Config controls polling behavior.

type FetchResult

type FetchResult struct {
	Result     string  // final output (set when Done=true)
	Done       bool    // whether the task has completed
	Percent    float64 // 0~1, upstream-reported progress (0 if unavailable)
	PreviewURL string  // intermediate preview URL (e.g. video first frame)
}

FetchResult carries extended information from a poll fetch.

type Fetcher

type Fetcher func(ctx context.Context) (result string, done bool, err error)

Fetcher checks whether an async task has completed. It returns the result string when done is true.

type FetcherV2

type FetcherV2 func(ctx context.Context) (FetchResult, error)

FetcherV2 checks whether an async task has completed with extended info.

type OnProgress

type OnProgress func(attempt int, elapsed time.Duration)

OnProgress is called after each poll attempt (optional).

type OnProgressV2

type OnProgressV2 func(ProgressInfo)

OnProgressV2 is the extended progress callback.

func OnProgressV2FromContext

func OnProgressV2FromContext(ctx context.Context) OnProgressV2

OnProgressV2FromContext extracts the extended progress callback from context.

type ProgressInfo

type ProgressInfo struct {
	Attempt    int
	Elapsed    time.Duration
	Percent    float64
	PreviewURL string
}

ProgressInfo carries extended progress data for OnProgressV2 callbacks.

type TaskStatus

type TaskStatus int

TaskStatus represents the normalized status of an async task.

const (
	StatusPending   TaskStatus = iota // queued, not yet started
	StatusRunning                     // in progress
	StatusSuccess                     // completed successfully
	StatusFailed                      // completed with error
	StatusCancelled                   // cancelled by user or system
)

func MapStatus

func MapStatus(raw string) TaskStatus

MapStatus maps a raw status string from any engine API to a normalized TaskStatus. The mapping is case-insensitive and covers common variations across providers.

func (TaskStatus) Done

func (s TaskStatus) Done() bool

Done returns true if the status is terminal (success, failed, or cancelled).

func (TaskStatus) String

func (s TaskStatus) String() string

String returns a human-readable status name.