types

package
v0.8.7 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 3, 2026 License: MIT Imports: 6 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	KB = 1 << 10
	MB = 1 << 20
	GB = 1 << 30
)
View Source 
const (
	IncompleteSuffix = ".surge"

	MinChunk     = 2 * MB
	AlignSize    = 4 * KB
	WorkerBuffer = 512 * KB

	WorkerBatchSize     = 1 * MB
	WorkerBatchInterval = 200 * time.Millisecond

	PerDownloadMax = 32
	DialHedgeCount = 4

	DefaultMaxIdleConns          = 100
	DefaultIdleConnTimeout       = 90 * time.Second
	DefaultTLSHandshakeTimeout   = 10 * time.Second
	DefaultResponseHeaderTimeout = 15 * time.Second
	DefaultExpectContinueTimeout = 1 * time.Second
	DialTimeout                  = 10 * time.Second
	KeepAliveDuration            = 30 * time.Second
	ProbeTimeout                 = 30 * time.Second

	PoolMaxIdleConns        = 512
	PoolMaxIdleConnsPerHost = 128
	PoolMaxConnsPerHost     = 512

	MaxTaskRetries = 3
	RetryBaseDelay = 200 * time.Millisecond

	HealthCheckInterval = 1 * time.Second
	SlowWorkerThreshold = 0.30
	SlowWorkerGrace     = 5 * time.Second
	StallTimeout        = 3 * time.Second
	SpeedEMAAlpha       = 0.3

	ProgressChannelBuffer = 100
)
View Source 
const DefaultUserAgent = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36"

Variables

View Source 
var (
	ErrPaused             = errors.New("download paused")
	ErrNotFound           = errors.New("download not found")
	ErrCompleted          = errors.New("download already completed")
	ErrPausing            = errors.New("download is still pausing, try again in a moment")
	ErrEngineNotInit      = errors.New("engine not initialized")
	ErrPoolNotInit        = errors.New("worker pool not initialized")
	ErrIDExists           = errors.New("download id already exists")
	ErrURLRequired        = errors.New("URL is required")
	ErrDestRequired       = errors.New("destination path is required")
	ErrServiceUnavailable = errors.New("service unavailable")
	ErrQueuedUpdate       = errors.New("cannot update URL for a queued download, please cancel or wait for it to start")
	ErrActiveUpdate       = errors.New("download is currently active, please pause it before updating the URL")
	ErrMaxRedirects       = errors.New("stopped after 10 redirects")
)

Common errors

Functions

This section is empty.

Types

type CancelResult added in v0.7.8 

type CancelResult struct {
	Found     bool
	Filename  string
	DestPath  string
	Completed bool
	WasQueued bool
}

CancelResult carries enough metadata for callers to emit lifecycle events without creating an import cycle back to the worker pool.

type ChunkStatus 

type ChunkStatus int

ChunkStatus represents the status of a visualization chunk 

const (
	ChunkPending     ChunkStatus = 0 // 00
	ChunkDownloading ChunkStatus = 1 // 01
	ChunkCompleted   ChunkStatus = 2 // 10 (Bit 2 set)
)

type DownloadConfig 

type DownloadConfig struct {
	URL        string
	OutputPath string
	DestPath   string
	ID         string
	Filename   string
	IsResume   bool
	ProgressCh chan<- any
	State      *ProgressState
	SavedState *DownloadState
	Runtime    *RuntimeConfig
	Mirrors    []string
	Headers    map[string]string

	IsExplicitCategory bool
	TotalSize          int64
	SupportsRange      bool
}

type DownloadEntry 

type DownloadEntry struct {
	ID          string   `json:"id"`
	URLHash     string   `json:"url_hash"`
	URL         string   `json:"url"`
	DestPath    string   `json:"dest_path"`
	Filename    string   `json:"filename"`
	Status      string   `json:"status"`
	TotalSize   int64    `json:"total_size"`
	Downloaded  int64    `json:"downloaded"`
	CompletedAt int64    `json:"completed_at"`
	TimeTaken   int64    `json:"time_taken"`
	AvgSpeed    float64  `json:"avg_speed"`
	Mirrors     []string `json:"mirrors,omitempty"`
}

DownloadEntry is the durable record used for history and lifecycle recovery.

type DownloadState 

type DownloadState struct {
	ID         string   `json:"id"`
	URLHash    string   `json:"url_hash"`
	URL        string   `json:"url"`
	DestPath   string   `json:"dest_path"`
	TotalSize  int64    `json:"total_size"`
	Downloaded int64    `json:"downloaded"`
	Tasks      []Task   `json:"tasks"`
	Filename   string   `json:"filename"`
	CreatedAt  int64    `json:"created_at"`
	PausedAt   int64    `json:"paused_at"`
	Elapsed    int64    `json:"elapsed"`
	Mirrors    []string `json:"mirrors,omitempty"`

	ChunkBitmap     []byte `json:"chunk_bitmap,omitempty"`
	ActualChunkSize int64  `json:"actual_chunk_size,omitempty"`

	FileHash string `json:"file_hash,omitempty"`
}

DownloadState is the persisted snapshot used to resume a download.

type DownloadStatus 

type DownloadStatus struct {
	ID          string  `json:"id"`
	URL         string  `json:"url"`
	Filename    string  `json:"filename"`
	DestPath    string  `json:"dest_path,omitempty"`
	TotalSize   int64   `json:"total_size"`
	Downloaded  int64   `json:"downloaded"`
	Progress    float64 `json:"progress"`
	Speed       float64 `json:"speed"`
	Status      string  `json:"status"`
	Error       string  `json:"error,omitempty"`
	ETA         int64   `json:"eta"`
	Connections int     `json:"connections"`
	AddedAt     int64   `json:"added_at"`
	TimeTaken   int64   `json:"time_taken"`
	AvgSpeed    float64 `json:"avg_speed"`
}

DownloadStatus is the transient view returned to the TUI and API clients.

type MasterList 

type MasterList struct {
	Downloads []DownloadEntry `json:"downloads"`
}

MasterList holds all tracked downloads.

type MirrorStatus 

type MirrorStatus struct {
	URL    string
	Active bool
	Error  bool
}

type ProgressState 

type ProgressState struct {
	ID            string
	Downloaded    atomic.Int64
	TotalSize     int64
	DestPath      string // Initial destination path
	Filename      string // Initial filename
	URL           string // Source URL
	StartTime     time.Time
	ActiveWorkers atomic.Int32
	Done          atomic.Bool
	Error         atomic.Pointer[error]
	Paused        atomic.Bool
	Pausing       atomic.Bool // Intermediate state: Pause requested but workers not yet exited

	VerifiedProgress  atomic.Int64  // Verified bytes written to disk (for UI progress)
	SessionStartBytes int64         // SessionStartBytes tracks how many bytes were already downloaded when the current session started
	SavedElapsed      time.Duration // Time spent in previous sessions

	Mirrors []MirrorStatus

	ChunkBitmap     []byte
	ChunkProgress   []int64
	ActualChunkSize int64
	BitmapWidth     int
	// contains filtered or unexported fields
}

func NewProgressState 

func NewProgressState(id string, totalSize int64) *ProgressState

func (*ProgressState) FinalizePauseSession 

func (ps *ProgressState) FinalizePauseSession(downloaded int64) time.Duration

FinalizePauseSession finalizes the current session for a pause transition. It keeps timing/data frozen while paused and returns total elapsed after finalize.

func (*ProgressState) FinalizeSession 

func (ps *ProgressState) FinalizeSession(downloaded int64) (time.Duration, time.Duration)

FinalizeSession closes the current session and accumulates its elapsed time into total elapsed. It returns (sessionElapsed, totalElapsedAfterFinalize).

func (*ProgressState) GetBitmap 

func (ps *ProgressState) GetBitmap() ([]byte, int, int64, int64, []int64)

GetBitmap returns a copy of the bitmap and metadata

func (*ProgressState) GetBitmapSnapshot 

func (ps *ProgressState) GetBitmapSnapshot(includeProgress bool) ([]byte, int, int64, int64, []int64)

GetBitmapSnapshot returns a copy of bitmap metadata and optionally chunk progress.

func (*ProgressState) GetChunkState 

func (ps *ProgressState) GetChunkState(index int) ChunkStatus

GetChunkState gets the 2-bit state for a specific chunk index (thread-safe)

func (*ProgressState) GetDestPath 

func (ps *ProgressState) GetDestPath() string

func (*ProgressState) GetError 

func (ps *ProgressState) GetError() error

func (*ProgressState) GetFilename 

func (ps *ProgressState) GetFilename() string

func (*ProgressState) GetMirrors 

func (ps *ProgressState) GetMirrors() []MirrorStatus

func (*ProgressState) GetProgress 

func (ps *ProgressState) GetProgress() (downloaded int64, total int64, totalElapsed time.Duration, sessionElapsed time.Duration, connections int32, sessionStartBytes int64)

func (*ProgressState) GetSavedElapsed 

func (ps *ProgressState) GetSavedElapsed() time.Duration

func (*ProgressState) GetURL 

func (ps *ProgressState) GetURL() string

func (*ProgressState) InitBitmap 

func (ps *ProgressState) InitBitmap(totalSize int64, chunkSize int64)

InitBitmap initializes the chunk bitmap

func (*ProgressState) IsPaused 

func (ps *ProgressState) IsPaused() bool

func (*ProgressState) IsPausing 

func (ps *ProgressState) IsPausing() bool

func (*ProgressState) Pause 

func (ps *ProgressState) Pause()

func (*ProgressState) RecalculateProgress 

func (ps *ProgressState) RecalculateProgress(remainingTasks []Task)

RecalculateProgress reconstructs ChunkProgress from remaining tasks (for resume)

func (*ProgressState) RestoreBitmap 

func (ps *ProgressState) RestoreBitmap(bitmap []byte, actualChunkSize int64)

RestoreBitmap restores the chunk bitmap from saved state

func (*ProgressState) Resume 

func (ps *ProgressState) Resume()

func (*ProgressState) SessionReset added in v0.8.3 

func (ps *ProgressState) SessionReset()

SessionReset wipes the current progress and session state, allowing for a fresh start (e.g. fallback).

func (*ProgressState) SetCancelFunc 

func (ps *ProgressState) SetCancelFunc(cancel context.CancelFunc)

func (*ProgressState) SetChunkProgress 

func (ps *ProgressState) SetChunkProgress(progress []int64)

SetChunkProgress updates chunk progress array from external sources (e.g. remote events).

func (*ProgressState) SetChunkState 

func (ps *ProgressState) SetChunkState(index int, status ChunkStatus)

SetChunkState sets the 2-bit state for a specific chunk index (thread-safe)

func (*ProgressState) SetDestPath 

func (ps *ProgressState) SetDestPath(path string)

func (*ProgressState) SetError 

func (ps *ProgressState) SetError(err error)

func (*ProgressState) SetFilename 

func (ps *ProgressState) SetFilename(filename string)

func (*ProgressState) SetMirrors 

func (ps *ProgressState) SetMirrors(mirrors []MirrorStatus)

func (*ProgressState) SetPausing 

func (ps *ProgressState) SetPausing(pausing bool)

func (*ProgressState) SetSavedElapsed 

func (ps *ProgressState) SetSavedElapsed(d time.Duration)

func (*ProgressState) SetTotalSize 

func (ps *ProgressState) SetTotalSize(size int64)

func (*ProgressState) SetURL 

func (ps *ProgressState) SetURL(url string)

func (*ProgressState) SyncSessionStart 

func (ps *ProgressState) SyncSessionStart()

func (*ProgressState) UpdateChunkStatus 

func (ps *ProgressState) UpdateChunkStatus(offset, length int64, status ChunkStatus)

UpdateChunkStatus updates the bitmap based on byte range

type RuntimeConfig 

type RuntimeConfig struct {
	MaxConnectionsPerDownload int
	UserAgent                 string
	ProxyURL                  string
	CustomDNS                 string
	SequentialDownload        bool
	MinChunkSize              int64

	WorkerBufferSize      int
	MaxTaskRetries        int
	DialHedgeCount        int
	SlowWorkerThreshold   float64
	SlowWorkerGracePeriod time.Duration
	StallTimeout          time.Duration
	SpeedEmaAlpha         float64
}

RuntimeConfig carries network and downloader tuning knobs. Fields used by the downloader getters fall into two groups: zero means "use package default" for capacity-style settings such as connections, chunk size, buffer size, and retries; zero is preserved for opt-out settings where disabling a behavior is meaningful.

func DefaultRuntimeConfig added in v0.8.7 

func DefaultRuntimeConfig() *RuntimeConfig

DefaultRuntimeConfig returns a fully-populated runtime config for callers that want engine defaults rather than relying on zero-value semantics.

func (*RuntimeConfig) GetDialHedgeCount added in v0.8.2 

func (r *RuntimeConfig) GetDialHedgeCount() int

func (*RuntimeConfig) GetMaxConnectionsPerDownload added in v0.8.7 

func (r *RuntimeConfig) GetMaxConnectionsPerDownload() int

func (*RuntimeConfig) GetMaxTaskRetries 

func (r *RuntimeConfig) GetMaxTaskRetries() int

func (*RuntimeConfig) GetMinChunkSize 

func (r *RuntimeConfig) GetMinChunkSize() int64

func (*RuntimeConfig) GetSlowWorkerGracePeriod 

func (r *RuntimeConfig) GetSlowWorkerGracePeriod() time.Duration

func (*RuntimeConfig) GetSlowWorkerThreshold 

func (r *RuntimeConfig) GetSlowWorkerThreshold() float64

func (*RuntimeConfig) GetSpeedEmaAlpha 

func (r *RuntimeConfig) GetSpeedEmaAlpha() float64

func (*RuntimeConfig) GetStallTimeout 

func (r *RuntimeConfig) GetStallTimeout() time.Duration

func (*RuntimeConfig) GetUserAgent 

func (r *RuntimeConfig) GetUserAgent() string

func (*RuntimeConfig) GetWorkerBufferSize 

func (r *RuntimeConfig) GetWorkerBufferSize() int

type Task 

type Task struct {
	Offset          int64         `json:"offset"`
	Length          int64         `json:"length"`
	SharedMaxOffset *atomic.Int64 `json:"-"`
}

Task represents a byte range to download.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.