l0.DependencyControl.Downloader¶

MoonScriptLua

Downloader = require "l0.DependencyControl.Downloader"

local Downloader = require("l0.DependencyControl.Downloader")

Download ¶

A single download: its URL, output path, transfer state, and event callbacks. Events (see Download.Event): Progress (data arrived), Finish (reached a terminal status). A Finish listener may downgrade the status via markFailed (e.g. for a failed hash verification). The current state is exposed via @status (Download.Status).

Constructor ¶

MoonScriptLua

download = Download url, outfile, id

local download = Download(url, outfile, id)

Creates a single download in the Queued state.

param	type	description
url	`string`
outfile	`string`	Full output path.
id?	`number`	An identifier assigned by the Downloader.

Instance methods¶

cancel ¶

MoonScriptLua

download\cancel!

download:cancel()

Requests cancellation of this download. The downloader releases its resources and sets the status to Cancelled on its next scheduling pass.

markFailed ¶

MoonScriptLua

download\markFailed err

download:markFailed(err)

Marks the download as failed (e.g. from a Finish listener performing hash verification).

param	type	description
err	`string`	The failure reason.

_notifyProgress ¶

MoonScriptLua

download\_notifyProgress!

download:_notifyProgress()

Part of the download-runner callback contract: a runner calls this to fire this download's Progress listeners as bytes arrive.

_complete ¶

MoonScriptLua

download\_complete transportError

download:_complete(transportError)

Part of the download-runner callback contract: a runner calls this when the transfer ends to finalize it (success, or a transport-level error) and fire Finish listeners (which may downgrade the status via markFailed). Idempotent — only the first call takes effect.

param	type	description
transportError?	`string`	A transport-level error, if any.

_cancel ¶

MoonScriptLua

download\_cancel!

download:_cancel()

Part of the download-runner callback contract: a runner calls this to finalize the download as cancelled and fire Finish listeners. Idempotent.

Fields¶

field	type	description
status	DownloadStatus	Current lifecycle state of this download.

Enums¶

DownloadStatus ¶

member	value	description
Queued	`"queued"`	created, not yet started
Active	`"active"`	transfer in progress
Finished	`"finished"`	completed successfully
Failed	`"failed"`	completed with an error
Cancelled	`"cancelled"`	cancelled before completion

DownloadEvent ¶

member	value	description
Progress	`"progress"`	transfer data arrived
Finish	`"finish"`	the download reached a terminal status

Downloader ¶

Manages a set of concurrent downloads. This is DepCtrl's own engine; the DM.DownloadManager-compatible API lives in l0.DependencyControl.DownloadManager. Events (see Downloader.Event): Progress (overall %), Finished (await completed).

Constructor ¶

MoonScriptLua

downloader = Downloader runner, options

local downloader = Downloader(runner, options)

Creates a downloader.

param	type	description
runner?	`fun(downloader: Downloader)`	Overrides the transfer implementation (defaults to the platform backend).
options?	DownloaderOptions	Optional downloader settings.

Instance methods¶

addDownload ¶

MoonScriptLua

downloader\addDownload url, outfile, sha1

downloader:addDownload(url, outfile, sha1)

Queues a download. Transfers happen later, in await. Register progress/finish listeners on the returned Download as needed.

param	type	description
url	`string`
outfile	`string`	Full output path (relative paths unsupported).
sha1?	`string`	Expected SHA-1 hash; verified automatically on finish.

Returns:

download Download?
err string?

await ¶

MoonScriptLua

downloader\await onProgress

downloader:await(onProgress)

Performs all queued downloads, blocking until they finish or are cancelled. Subscribe to Progress/Finished via on; a Progress listener may call cancel!. Inspect each download's final state via its @status (Download.Status).

param	type	description
onProgress?	`fun(downloader: Downloader, percent: number)`	Called with this downloader and the aggregate progress (0-100) on each Progress event, for the duration of this call only.

Returns:

self Downloader — for chaining

_reportProgress ¶

MoonScriptLua

downloader\_reportProgress percent

downloader:_reportProgress(percent)

Part of the download-runner callback contract: a runner calls this to report the manager's aggregate progress and fire the Downloader's Progress listeners.

param	type	description
percent	`number`	Aggregate progress, 0-100.

cancel ¶

MoonScriptLua

downloader\cancel!

downloader:cancel()

Cancels all remaining downloads (e.g. from within a Progress listener).

clear ¶

MoonScriptLua

downloader\clear!

downloader:clear()

Removes all downloads and resets state. Empties the array in place so external references stay valid.

isInternetConnected ¶

MoonScriptLua

downloader\isInternetConnected!

downloader:isInternetConnected()

Returns:

connected boolean — Whether an internet connection appears to be available.

Class methods¶

multiplex ¶

MoonScriptLua

Downloader.multiplex manager, driver

Downloader.multiplex(manager, driver)

Drives every queued download of the given downloader to completion with a round-robin scheduler, keeping up to its maxConnections transfers active and honoring its cancellation and stall-timeout settings. Blocks until all transfers finish or are cancelled.

param	type	description
manager	Downloader	The downloader whose queued downloads are transferred.
driver	`table`	The transfer backend, providing `start(dl)`, `step(dl)`, `finish(dl)`, and an optional `shutdown()`.

Fields¶

field	type	description
progress	`number`	Current aggregate download progress across all queued transfers, 0-100 (read-only).
Download	Download
maxConnections	`integer`
stallTimeout	`integer`

Enums¶

DownloaderEvent ¶

member	value	description
Progress	`"progress"`	aggregate progress across queued transfers changed
Finished	`"finished"`	await completed

Types¶

DownloaderOptions ¶

Options accepted by the Downloader constructor.

field	type	description
stallTimeout?	`number`	Seconds a transfer may receive no data before it's aborted; 0/false disables stall detection.
maxConnections?	`integer`	Maximum simultaneous transfers (also the per-server connection limit); excess transfers queue.
blockPrivateHosts?	`boolean`	Refuse URLs whose host is a private/loopback/link-local address (an SSRF guard).
maxFileSize?	`number`	Maximum response size in bytes; a transfer found to exceed it is aborted (0/nil = unlimited).
timeout?	`number`	Maximum total seconds a transfer may take before it's aborted (0/nil = unlimited).