Speed up downloads by combining multiple network connections in parallel
TypeScript bandwidth-aggregationcross-platformdesktop-appdownloaderdownloadmanagerlinuxmacosmulticonnectionparallel-downloadswindows
export type NetworkInterfaceKind = 'wifi' | 'usb' | 'ethernet' | 'bridge' | 'other'
export type IpFamily = 4 | 6
export interface NetworkAddress {
address: string
family: IpFamily
netmask?: string
/** Used by the existing IPv4 same-subnet warning. */
subnet?: string
}
export type ThemeSource = 'light' | 'dark'
export interface NetworkInterfaceInfo {
/** Stable identifier for this interface (currently the OS device name, e.g. "en0"). */
id: string
device: string
displayName: string
addresses: NetworkAddress[]
kind: NetworkInterfaceKind
mac?: string
}
interface ProbeResultBase {
requestedUrl: string
/** URL after following redirects — this is what the download should actually fetch. */
finalUrl: string
supportsRanges: boolean
/** null when the server did not report a size. */
totalBytes: number | null
suggestedFileName: string
contentType: string | null
/** Strong validators, used to detect if the remote content changes between pause and resume. */
etag: string | null
lastModified: string | null
}
export interface HttpProbeResult extends ProbeResultBase {
kind: 'http'
}
export interface TorrentProbeResult extends ProbeResultBase {
kind: 'torrent'
torrent: TorrentInfo
}
export interface NzbProbeResult extends ProbeResultBase {
kind: 'nzb'
nzb: NzbInfo
}
export type ProbeResult = HttpProbeResult | TorrentProbeResult | NzbProbeResult
/** How the check of a magnet link is going, while it's still going: `noPeersYet` once its first
* search came back empty and it's looking a little longer. */
export interface MagnetCheckStatus {
/** The link as it was given to probeUrl. */
link: string
noPeersYet: boolean
}
export interface TorrentInfo {
infoHash: string
pieceLength: number
/** Where each file will be written, relative to the destination folder, already checked to be
* safe (see main/download/torrent/paths.ts). */
files: { path: string; length: number }[]
/** Trackers listed in the torrent's metadata. */
trackers?: string[]
/** Whether the torrent is marked private (BEP 27). */
isPrivate?: boolean
}
export interface TorrentTrackersResult {
defaultTrackers: string[]
customTrackers: string[]
isPrivate: boolean
}
/** What an NZB holds: Usenet articles, grouped into the files they make up once decoded. */
export interface NzbInfo {
/** Identifies the NZB among those probed lately (see main/download/nzb/nzbFile.ts). */
hash: string
/** Each file as it will be saved in the download's folder, and what its articles add up to:
* a little more than the file itself, since yEnc encodes it with some overhead. */
files: { name: string; bytes: number; segments: number }[]
}
/** One of a torrent download's files, for listing them while it runs. */
export interface TorrentFileEntry {
/** As TorrentInfo's: relative to the destination folder, the torrent's own folder first. */
path: string
length: number
/** Chosen to be downloaded. */
chosen: boolean
}
/** `queued`: waiting for one of the downloads running at once to end (see
* AppSettings.downloadsAtOnce). */
export type DownloadStatus =
'queued' | 'downloading' | 'paused' | 'completed' | 'error' | 'cancelled'
/** An HTTP stream's state. `pending` means it is waiting for work: it holds no block, either because
* none is free for it right now or because it hasn't started. `downloading` always means it is
* fetching one (`currentBlockIndex` says which). A stream that fails for good leaves the list;
* what went wrong is its network's to report (see DownloadNetwork). */
export type HttpStreamStatus =
'pending' | 'downloading' | 'retrying' | 'paused' | 'completed' | 'cancelled'
/** One connection to the server, through one network. Streams come and go as the download
* runs; what a network has done is kept on its DownloadNetwork. */
export interface HttpStreamState {
id: number
/** The network it runs on: a DownloadNetwork's id. */
interfaceId: string
rangeStart: number
/** null means an open-ended range (download to end of file). */
rangeEnd: number | null
/** New bytes it has delivered. */
bytesDownloaded: number
speedBytesPerSec: number
status: HttpStreamStatus
/** The block this stream is fetching. Unset whenever it holds none (idle, retrying, paused, done). */
currentBlockIndex?: number
/** True while this stream is racing another stream for `currentBlockIndex`, because that one
* was too slow — see main/download/scheduler.ts. Whichever finishes first wins. */
hedge?: boolean
/** True while this stream is fetching the back part of `currentBlockIndex`, split off from what
* another stream had left of it — see main/download/scheduler.ts. Each fetches its own part. */
split?: boolean
}
/** A live BitTorrent peer connection. A peer does not own a piece: it may contribute blocks to
* several pieces, and several peers may contribute to one piece. */
export interface TorrentPeerState {
/** Unique in the download, in the order its peers connected: "Peer #(id + 1)". */
id: number
interfaceId: string
status: 'connected' | 'receiving'
/** The client it runs, as its peer id names it ("qBittorrent 4.6.2"); null when unknown. */
client: string | null
bytesDownloaded: number
speedBytesPerSec: number
bytesUploaded: number
uploadSpeedBytesPerSec: number
}
export type HttpBlockStatus = 'pending' | 'downloading' | 'completed'
/** `skipped`: a piece that none of the files chosen for this torrent needs. */
export type TorrentPieceStatus = HttpBlockStatus | 'skipped'
interface WorkUnitState {
index: number
rangeStart: number
rangeEnd: number | null
/** The network currently leasing this block (or the last one to touch it). Only meaningful
* as "who is working on it now" — for who actually *delivered* the bytes, read
* `bytesByInterface`, since a block can be started on one network and finished on another
* after a retry or a pause/resume. */
interfaceId?: string
bytesDownloaded: number
/** Bytes of this block delivered by each network, keyed by interface id. Summing to
* `bytesDownloaded`, this is what the block grid colors by, so a block split across
* networks is attributed to all of them instead of only the one that happened to finish it. */
bytesByInterface: Record<string, number>
}
export interface HttpBlockState extends WorkUnitState {
kind: 'http'
status: HttpBlockStatus
}
export interface TorrentPieceState extends WorkUnitState {
kind: 'torrent'
status: TorrentPieceStatus
/** Bytes received in this run but not yet hash-verified. This is live activity, not durable
* progress, and may fall back to zero after a failed verification. */
provisionalBytes: number
}
/** `missing`: the news server no longer has the article, or sent it damaged. What the article
* held is left as zeros in its file, for a par2 repair to restore. */
export type NzbSegmentStatus = HttpBlockStatus | 'missing'
/** One Usenet article of an NZB download. Its range is in the NZB's own byte count, the articles
* as posted, one after the other: the files' real sizes are only known once they come in. */
export interface NzbSegmentState extends WorkUnitState {
kind: 'nzb'
status: NzbSegmentStatus
}
export type DownloadUnitState = HttpBlockState | TorrentPieceState | NzbSegmentState
/** What a Saved Messages attachment is, as the media browser groups it. */
export type TelegramMediaType =
'photo' | 'video' | 'audio' | 'voice' | 'document' | 'animation' | 'sticker'
/** One media attachment in Saved Messages. */
export interface TelegramMediaItem {
/** The message's id in Saved Messages: what a download of it is started by. */
messageId: number
type: TelegramMediaType
fileName: string
mimeType: string
/** 0 for photos: Telegram doesn't reveal a photo's byte size ahead of its download. */
totalBytes: number
width?: number
height?: number
/** Unix seconds the message was sent. */
date: number
/** Inline JPEG thumbnail as a data URL, when the message carries one small enough to embed. */
thumbnail?: string
}
/** One page of Saved Messages media, oldest entry last, for the browser's paging. */
export interface TelegramMediaPage {
items: TelegramMediaItem[]
/** The oldest message id seen; the next page asks for older ones than it. Unset when exhausted. */
nextOffsetId?: number
exhausted: boolean
}
/** The user's own Telegram API credentials (my.telegram.org) and phone, as the login form
* sends them. */
export interface TelegramCredentials {
apiId: number
apiHash: string
phone: string
}
/** Where Telegram sign-in stands, as the login dialog shows it. Credentials are the user's own
* api_id/api_hash from my.telegram.org — unless the release build bundles Plexo's own
* (`bundled`), in which case the api form becomes an advanced fallback. The api_hash itself
* never crosses to the window: it's the bundled secret in release builds, and the user's own
* is a stored secret either way. */
export interface TelegramAuthState {
signedIn: boolean
/** The release build ships Plexo's own credentials: sign in with a phone (or the QR) alone. */
bundled?: boolean
/** The stored api registration is the user's own (not the bundled pair) — its api_hash field
* can stay empty and the stored keys keep winning. */
hasOwnKeys?: boolean
apiId?: number
phone?: string
/** A code was sent and not yet accepted: the dialog asks for it. */
awaitingCode: boolean
/** The account has two-step verification: the dialog asks for its password. */
awaitingPassword: boolean
/** A QR login is live: `qrDataUrl` holds the current code, which Telegram rotates. */
awaitingQr?: boolean
qrDataUrl?: string
/** The signed-in account's name, as Telegram reports it. */
userName?: string
error?: string
}
/** A live Telegram connection fetching the file. Like an HTTP stream without its range: each
* reader takes blocks as they free up. */
export interface TelegramReaderState {
id: number
/** The network its bytes are attributed to (see TelegramDownloadState). */
interfaceId: string
bytesDownloaded: number
speedBytesPerSec: number
status: 'pending' | 'downloading' | 'retrying' | 'paused' | 'completed' | 'cancelled'
currentBlockIndex?: number
}
export interface TelegramDownloadNetwork extends DownloadNetworkBase {
transfer: 'telegram'
}
/**
* - on: in use.
* - off: the user switched it off. A network that turns up mid-download starts off.
* - offline: not connected to this computer. It's used again as soon as it is.
* - unreachable: connected, but the server can't be reached through it. One connection keeps
* trying, and the rest follow once it gets through.
* - failed: the server kept refusing requests over it (`error` says how). Switching it off and
* on, reconnecting it, or resuming tries again.
* - limit: it has used up its data for the chosen period (NetworkPreference.dataLimit). It's used again
* once the period ends or the limit is raised.
*/
export type NetworkStatus = 'on' | 'off' | 'offline' | 'unreachable' | 'failed' | 'limit'
/** A network as one download sees it: whether the user has it on, and how it is doing. */
interface DownloadNetworkBase {
/** A NetworkInterfaceInfo id. */
id: string
/** Its name and kind as the OS last reported them. */
label: string
kind: NetworkInterfaceKind
/** The user's choice; `status` is what came of it. */
enabled: boolean
status: NetworkStatus
error?: string
/** Bytes of the file it delivered. */
bytesDownloaded: number
speedBytesPerSec: number
/** Requests over it that failed and were tried again. */
retries: number
}
export interface HttpDownloadNetwork extends DownloadNetworkBase {
transfer: 'http'
}
export interface TorrentDownloadNetwork extends DownloadNetworkBase {
transfer: 'torrent'
bytesUploaded: number
uploadSpeedBytesPerSec: number
}
export type DownloadNetwork = HttpDownloadNetwork | TorrentDownloadNetwork | TelegramDownloadNetwork
interface DownloadStateBase {
id: string
url: string
fileName: string
destinationPath: string
/** 0 means the size could not be determined ahead of time. */
totalBytes: number
bytesDownloaded: number
speedBytesPerSec: number
/** Seconds left at this speed, smoothed (see updateTimeLeft); unset when there's no telling:
* the size unknown, or nothing moving. */
timeLeftSeconds?: number
status: DownloadStatus
error?: string
/** For an error: whether resuming can pick up where it stopped. False when the progress was
* thrown away, e.g. the file changed on the server. */
resumable?: boolean
startedAt: number
/** Enrolled in the scheduled queue; survives relaunches until manually paused. */
scheduled?: boolean
/** While queued: its place in the queue, lowest first. */
queuedAt?: number
pausedAt?: number
totalPausedMs?: number
completedAt?: number
/** Each network's speed, by network id, sampled once a second over the last minute it ran.
* Every series is as long as the others, so they line up in time. */
speedHistory?: Record<string, number[]>
/** The best combined speed held for a few seconds, so it only ever rises; unset until it has
* run that long. A download done sooner gets the best speed it showed. */
peakSpeedBytesPerSec?: number
/** The update this state is as of (see DownloadUpdate). */
seq?: number
}
export interface HttpDownloadState extends DownloadStateBase {
kind: 'http'
networks: HttpDownloadNetwork[]
streams: HttpStreamState[]
peakStreams: number
blocks: HttpBlockState[]
totalBlocks: number
blockSizeBytes: number
/** The disk can't keep up: most streams are waiting for their writes (see concurrency.ts). */
diskLimited?: boolean
fromBrowser?: string
}
export interface TorrentDownloadState extends DownloadStateBase {
kind: 'torrent'
networks: TorrentDownloadNetwork[]
peers: TorrentPeerState[]
peakPeers: number
pieces: TorrentPieceState[]
totalPieces: number
pieceLength: number
/** How many files it has, how many are chosen, and which (by index; unset: every one). */
files: { chosen: number; total: number; selected?: number[] }
/** Its files come in the torrent's folder (`fileName`), rather than as one file. */
folder: boolean
/** Of `totalBytes`, the bytes of pieces that no chosen file needs. */
skippedBytes: number
bytesUploaded: number
uploadSpeedBytesPerSec: number
}
export interface TelegramDownloadState extends DownloadStateBase {
kind: 'telegram'
networks: TelegramDownloadNetwork[]
/** The connections fetching from Telegram. Unlike HTTP streams they aren't pinned to a
* network — Telegram is always reached the way the OS routes — so their bytes are attributed
* to whichever network was first-enabled as each block was claimed. */
readers: TelegramReaderState[]
peakReaders: number
blocks: HttpBlockState[]
totalBlocks: number
blockSizeBytes: number
}
/** One file of an NZB download. */
export interface NzbFileState {
/** As it is saved, in the download's folder. */
name: string
/** What its articles add up to, as the NZB counts them. */
bytes: number
/** Its real size, from its articles' yEnc headers; unset until one has come in. */
size?: number
segments: number
/** Articles the server didn't have, or sent damaged (see NzbSegmentStatus). */
missing: number
}
/** A Usenet download: an NZB's articles, fetched over connections to the user's news server. Its
* streams are those connections, its blocks the articles. */
export interface NzbDownloadState extends DownloadStateBase {
kind: 'nzb'
networks: HttpDownloadNetwork[]
streams: HttpStreamState[]
peakStreams: number
blocks: NzbSegmentState[]
totalBlocks: number
nzbFiles: NzbFileState[]
/** Of `totalBytes`, the bytes of articles that are missing. */
missingBytes: number
/** The news server it downloads from, by host name. */
server: string
}
export type DownloadState =
HttpDownloadState | TorrentDownloadState | TelegramDownloadState | NzbDownloadState
/** A finished download as history keeps it: its state without the work units and connections,
* which only a running download needs. */
export type FinishedDownload = (
| Omit<HttpDownloadState, 'blocks' | 'streams'>
| Omit<TorrentDownloadState, 'pieces' | 'peers'>
| Omit<TelegramDownloadState, 'blocks' | 'readers'>
| Omit<NzbDownloadState, 'blocks' | 'streams'>
) & {
/** The blocks or pieces it was written in (a torrent's: those its chosen files needed; an
* NZB's: its articles that came in). */
unitsWritten: number
/** Set when listed: its file or folder is no longer where it was saved. */
missing?: boolean
/** Chosen torrent files (or an NZB's files) relative to its destination folder, retained for
* safe file removal. */
downloadedFiles?: string[]
}
/** What the main process sends as a download changes: everything but its blocks, and only the
* blocks that changed since it last sent. A download can have tens of thousands of blocks, and
* copying every one several times a second would cost the process that carries every byte. A
* snapshot is the same with every block in it. */
export interface HttpDownloadUpdate {
seq: number
state: Omit<HttpDownloadState, 'blocks'>
blocks: HttpBlockState[]
}
export interface TorrentDownloadUpdate {
seq: number
state: Omit<TorrentDownloadState, 'pieces'>
pieces: TorrentPieceState[]
}
export interface TelegramDownloadUpdate {
seq: number
state: Omit<TelegramDownloadState, 'blocks'>
blocks: HttpBlockState[]
}
export interface NzbDownloadUpdate {
seq: number
state: Omit<NzbDownloadState, 'blocks'>
blocks: NzbSegmentState[]
}
export type DownloadUpdate =
HttpDownloadUpdate | TorrentDownloadUpdate | TelegramDownloadUpdate | NzbDownloadUpdate
/** User customization for one physical network, keyed by NetworkInterfaceInfo.id — lets a
* cryptic OS device name (e.g. "feth0") get a real label, and a color distinct from its
* kind's default. Persisted in the main process, independent of any single download. */
export type ProxyType = 'http' | 'https' | 'socks4' | 'socks5'
export interface ProxyConfig {
enabled: boolean
type: ProxyType
host: string
port: number
username?: string
password?: string
}
export type DataLimitPeriod = 'day' | 'week' | 'month'
export interface NetworkPreference {
customName?: string
/** One of the app's curated swatch ids (see NETWORK_COLOR_SWATCHES) — not a raw hex, so every
* swatch is guaranteed to have a legible on-solid text color already picked out for it. */
colorId?: string
/** Optional per-interface proxy configuration. */
proxy?: ProxyConfig
/** Left out of the last download started, so New download starts without it too (it remembers
* the last pick, like the folder). A click there puts it back. */
off?: boolean
/** Bytes a second all downloads together may take over it. */
speedLimit?: number
/** Bytes Plexo may receive in the chosen calendar period. */
dataLimit?: number
/** Defaults to month for existing settings. Weeks start Monday in local time. */
dataLimitPeriod?: DataLimitPeriod
}
export type NetworkPreferences = Record<string, NetworkPreference>
/** Where the app's own update is (see main/updater.ts). `version` is the update's, once one is
* found; `percent` only means something while downloading. */
export interface UpdateState {
status: 'idle' | 'checking' | 'available' | 'downloading' | 'ready' | 'error'
autoUpdate: boolean
version?: string
percent?: number
}
/** A repeating window for all transfers, interpreted in the computer's local timezone. */
export interface DownloadSchedule {
enabled: boolean
/** Minutes since local midnight. Equal start/stop times are invalid. */
startMinute: number
endMinute: number
/** Days on which a window starts, Sunday = 0. */
days: number[]
/** Last local date on which a window may start (YYYY-MM-DD). */
endDate?: string
}
/** What app-settings.json holds, and what the renderer sends to change it (merged over the saved
* values, `undefined` clearing one). A missing field was never set. */
export interface AppSettings {
downloadSchedule?: DownloadSchedule
themeSource?: ThemeSource
/** Only ever saved as false: updates download on their own unless turned off. */
autoUpdate?: boolean
/** The last destination folder picked. */
destinationDir?: string
/** User customizations (name/color) per network interface id. */
networkPreferences?: NetworkPreferences
/** How many downloads run at once; the rest wait in the queue. */
downloadsAtOnce?: number
/** Bytes a second every download together may take, over every network; unset: no limit. */
speedLimit?: number
/** While on, slowModeSpeed stands in for speedLimit: a one-click lower limit for calls. */
slowMode?: boolean
slowModeSpeed?: number
/** How speeds are shown everywhere; sizes stay in bytes either way. */
speedUnit?: SpeedUnit
browserExtensionUsed?: boolean
}
/** bytes: MB/s. bits: Mbps, as internet plans and speed tests count them. */
export type SpeedUnit = 'bytes' | 'bits'
export const DOWNLOADS_AT_ONCE = { default: 2, min: 1, max: 4 }
/** Seconds of speed history a download keeps (a sample a second), and so the span the throughput
* chart always shows. */
export const SPEED_HISTORY_SECONDS = 60
export const DEFAULT_SLOW_MODE_SPEED = 2 * 1024 ** 2
/** Everything the renderer needs for its first paint, read synchronously by the preload so no
* saved value flashes in over a default a moment after launch. */
export interface InitialState {
downloadSchedule?: DownloadSchedule
homeDir: string
downloadsDir: string
themeSource: ThemeSource
networkPreferences: NetworkPreferences
downloadsAtOnce: number
speedLimit?: number
slowMode: boolean
slowModeSpeed: number
speedUnit: SpeedUnit
/** The last folder picked, if it still exists — otherwise the renderer uses downloadsDir. */
destinationDir?: string
}
interface StartDownloadRequestBase {
url: string
destinationDir: string
suggestedFileName: string
/** 0 means unknown. */
totalBytes: number
supportsRanges: boolean
/** The networks to start on. Every other one starts switched off. */
interfaceIds: string[]
etag: string | null
lastModified: string | null
}
export interface StartHttpDownloadRequest extends StartDownloadRequestBase {
kind: 'http'
/** Streams per network the user picked; left out, the count is decided automatically. */
streamsPerNetwork?: number
browser?: BrowserContext
}
/** The fields of chrome.cookies.Cookie that decide where it's sent. */
export interface BrowserCookie {
name: string
value: string
/** With or without a leading dot: `hostOnly` decides whether subdomains get it. */
domain: string
hostOnly: boolean
path: string
secure: boolean
}
/** So a link that needs a signed-in session, or checks the page it came from, works as it does
* in the browser. */
export interface BrowserContext {
cookies: BrowserCookie[]
referer?: string
userAgent?: string
name?: string
}
export interface PendingLink {
id: string
url: string
/** Reused by New download: checking a single-use link again would spend it. */
probe?: ProbeResult
from?: string
signedInTo?: string
/** A failed download this looks like the same file as, for the user to resume instead. */
resumes?: { id: string; fileName: string }
}
export interface StartTorrentDownloadRequest extends StartDownloadRequestBase {
kind: 'torrent'
/** The download starts from the .torrent retained when this info hash was probed. */
infoHash: string
/** For a torrent: the files to download, as indexes into its probe's `files`. Left out: all. */
selectedFiles?: number[]
}
export interface StartTelegramDownloadRequest extends StartDownloadRequestBase {
kind: 'telegram'
/** The Saved Messages message the media is on; its media is looked up as the download starts
* (and again whenever Telegram says the file reference went stale). */
messageId: number
mediaType: TelegramMediaType
}
export interface StartNzbDownloadRequest extends StartDownloadRequestBase {
kind: 'nzb'
/** The download starts from the NZB retained when it was probed (see NzbInfo.hash). */
nzbHash: string
}
export type StartDownloadRequest =
| StartHttpDownloadRequest
| StartTorrentDownloadRequest
| StartTelegramDownloadRequest
| StartNzbDownloadRequest
/** The news server NZB downloads come from, as the window sees it: never its password. */
export interface UsenetServer {
/** NZBs download from it; off, an NZB link downloads as a plain file. */
enabled: boolean
host: string
port: number
tls: boolean
username: string
/** How many connections the server allows at once, for every network together. */
connections: number
/** A password is set. */
hasPassword: boolean
/** Its password is kept only until Plexo quits: this computer offers no keychain to seal it
* with (see main/download/nzb/usenetServer.ts). */
passwordInMemory?: boolean
}
/** What the window sends to set the news server, or to test one. `password` or `enabled` left out
* keeps the one already saved. */
export interface UsenetServerInput {
enabled?: boolean
host: string
port: number
tls: boolean
username: string
connections: number
password?: string
}