Source registry

Sources are external file providers. When a download's file lives somewhere other than the add-on's own storage (GitHub release, S3 bucket, magnet link, arbitrary HTTPS URL), a source adapter knows how to probe it for size, hash, and last-modified, and how to redirect the user to it on download.

Key	Value
Container key	mc_dm.source_registry
Event	mc_dm_source_handlers

Built-in sources

ID	Class	What it does
direct_url	MC\DownloadsManager\Source\DirectUrlSource	Catch-all for any HTTPS URL. Probes via HEAD for size, MIME, and filename; can either redirect on download (link-only) or fetch and rehost the bytes locally — see link vs. cache below.
github_release	MC\DownloadsManager\Source\GitHubReleaseSource	Resolves a GitHub release asset by owner/repo + tag (or latest), pulls size, hash, and published date from the GitHub API. Honours the same link-vs-cache choice as direct_url. Supports a personal-access-token for private repos and rate-limit relief.
s3	MC\DownloadsManager\Source\S3Source	Stores bucket + key references, signs short-lived URLs at serve time, and pulls size + ETag from S3 head-object. Works with any S3-compatible provider (AWS, R2, B2, MinIO).
magnet	MC\DownloadsManager\Source\MagnetSource	Parses a magnet URI for the info-hash and tracker list. Probe is metadata-only (no piece-availability check); serves the magnet link directly. Always link-only — there's nothing to fetch.

Link vs. cache

DirectUrlSource and GitHubReleaseSource can operate in two modes per file:

• Link-only. The URL is stored, probed for metadata (size, MIME, filename), and the user is 302-redirected to it on download. The bytes never touch your server.
• Cache. The FetchFile job downloads the body into the addon's storage (subject to per-category size limits), hashes it, and serves it like a normal upload from then on. The original URL stays attached as the external_url for reference and re-fetch.

Which modes are available is controlled per category by the External URL mode setting (disabled, cache_only, link_only, cache, link). See per-category settings. When both modes are allowed, the upload form shows a "Don't cache, link only" checkbox the author can toggle per file.

S3Source and MagnetSource are always reference-only — S3 signs against the upstream bucket, magnet URIs have no canonical bytes to fetch.

Interface

namespace MC\DownloadsManager\Source;

interface ExternalSource
{
    public function probe(string $url): SourceProbeResult;
    public function getDownloadUrl(DownloadFile $file): string;
}

SourceProbeResult returns size, last-modified, and (when the source supports it) a hash.

Wiring an adapter

public static function sourceHandlers(SourceRegistry $registry)
{
    $registry->register('github', new YourAddon\Source\GitHubSource());
}