package downloader

Import Path
	github.com/gotd/td/telegram/downloader (on go.dev)

Dependency Relation
	imports 22 packages, and imported by one package

Involved Source Files

	    builder.go
	    cdn.go
	    cdn_plan.go
	    cdn_state_machine.go
	    cdn_verify.go
	    client.go
	  d downloader.go
		Package downloader contains downloading files helpers.

	    master.go
	    parallel.go
	    reader.go
	    retry.go
	    retry_event.go
	    sink.go
	    stream.go
	    verifier.go
	    web.go
Package-Level Type Names (total 19, in which 8 are exported)

	/* sort exporteds by: alphabet | popularity */
	 type Builder (struct)
		Builder is a download builder.

		Fields (total 5, none are exported)
			/* 5 unexporteds ... *//* 5 unexporteds: */
			downloader *Downloader
			hashes []tg.FileHash
			schema schema
			threads int
			verify bool
				verify controls legacy outer verifier (reader + verifier queue).
				CDN redirect path has mandatory protocol-level verification in cdn schema,
				independent from this flag.

		Methods (total 11, in which 6 are exported)
			(*Builder) Parallel(ctx context.Context, output io.WriterAt) (_ tg.StorageFileTypeClass, err error)
				Parallel downloads file to given io.WriterAt.

			(*Builder) Stream(ctx context.Context, output io.Writer) (_ tg.StorageFileTypeClass, err error)
				Stream downloads file to given io.Writer.
				NB: in this mode download can't be parallel.

			(*Builder) ToPath(ctx context.Context, path string) (_ tg.StorageFileTypeClass, err error)
				ToPath downloads file to given path.

			(*Builder) WithRetryHandler(handler RetryHandler) *Builder
				WithRetryHandler sets callback for transient download errors that are retried
				internally.
				
				Handler can be called concurrently from download workers.

			(*Builder) WithThreads(threads int) *Builder
				WithThreads sets downloading goroutines limit.

			(*Builder) WithVerify(verify bool) *Builder
				WithVerify controls global hash verification behavior.
				
				`true` enables classic verifier reader (preloads hash queue and validates all
				chunks, both legacy and CDN).
				`false` disables classic verifier reader.
				
				If not called explicitly:
				- non-CDN path preserves old behavior (no upfront hash requests);
				- CDN path enables strict inline CDN verification after redirect.
				
				Use WithVerify(true) to force verifier-queue mode on all paths.

			/* 5 unexporteds ... *//* 5 unexporteds: */
			(*Builder) prepare() (_ *Builder, closeCDN func() error, err error)
			(*Builder) prepareCDNPath(m master, provider CDNProvider) *Builder
			(*Builder) prepareMaster(m master, allowCDN bool) *Builder
			(*Builder) reader() *reader
			(*Builder) shouldAllowCDN() bool
		As Outputs Of (at least 11, in which 7 are exported)
			func (*Builder).WithRetryHandler(handler RetryHandler) *Builder
			func (*Builder).WithThreads(threads int) *Builder
			func (*Builder).WithVerify(verify bool) *Builder
			func (*Downloader).Download(rpc Client, location tg.InputFileLocationClass) *Builder
			func (*Downloader).Web(rpc Client, location tg.InputWebFileLocationClass) *Builder
			func github.com/gotd/td/telegram.(*Client).Download(location tg.InputFileLocationClass) *Builder
			func github.com/gotd/td/telegram.(*Client).DownloadWeb(location tg.InputWebFileLocationClass) *Builder
			/* 4+ unexporteds ... *//* 4+ unexporteds: */
			func newBuilder(downloader *Downloader, schema schema) *Builder
			func (*Builder).prepare() (_ *Builder, closeCDN func() error, err error)
			func (*Builder).prepareCDNPath(m master, provider CDNProvider) *Builder
			func (*Builder).prepareMaster(m master, allowCDN bool) *Builder

	 type CDN (interface)
		CDN represents Telegram RPC client to CDN server.

		Methods (only one, which is exported)
			( CDN) UploadGetCDNFile(ctx context.Context, request *tg.UploadGetCDNFileRequest) (tg.UploadCDNFileClass, error)
		Implemented By (at least one exported)
			*github.com/gotd/td/tg.Client
		As Outputs Of (at least one exported)
			func CDNProvider.CDN(ctx context.Context, dc int, max int64) (CDN, io.Closer, error)

	 type CDNProvider (interface)
		CDNProvider creates client bound to requested CDN DC.
		Returned closer is schema-scoped; for shared client-level pool adapters this
		can be a no-op closer.

		Methods (only one, which is exported)
			( CDNProvider) CDN(ctx context.Context, dc int, max int64) (CDN, io.Closer, error)
		Implemented By (at least one unexported)
			/* at least one unexported ... *//* at least one unexported: */
			 github.com/gotd/td/telegram.downloadClient
		As Inputs Of (at least 2, neither is exported)
			/* 2+ unexporteds ... *//* 2+ unexporteds: */
			func newCDNSchema(masterSchema master, provider CDNProvider, pool *bin.Pool, max int64, verifyCDNInline bool, retryHandler RetryHandler) *cdn
			func (*Builder).prepareCDNPath(m master, provider CDNProvider) *Builder

	 type Client (interface)
		Client represents Telegram RPC client.

		Methods (total 5, all are exported)
			( Client) UploadGetCDNFileHashes(ctx context.Context, request *tg.UploadGetCDNFileHashesRequest) ([]tg.FileHash, error)
			( Client) UploadGetFile(ctx context.Context, request *tg.UploadGetFileRequest) (tg.UploadFileClass, error)
			( Client) UploadGetFileHashes(ctx context.Context, request *tg.UploadGetFileHashesRequest) ([]tg.FileHash, error)
			( Client) UploadGetWebFile(ctx context.Context, request *tg.UploadGetWebFileRequest) (*tg.UploadWebFile, error)
			( Client) UploadReuploadCDNFile(ctx context.Context, request *tg.UploadReuploadCDNFileRequest) ([]tg.FileHash, error)
		Implemented By (at least 2, in which 1 is exported)
			*github.com/gotd/td/tg.Client
			/* at least one unexported ... *//* at least one unexported: */
			 github.com/gotd/td/telegram.downloadClient
		As Inputs Of (at least 2, both are exported)
			func (*Downloader).Download(rpc Client, location tg.InputFileLocationClass) *Builder
			func (*Downloader).Web(rpc Client, location tg.InputWebFileLocationClass) *Builder

	 type Downloader (struct)
		Downloader is Telegram file downloader.

		Fields (total 4, none are exported)
			/* 4 unexporteds ... *//* 4 unexporteds: */
			allowCDN *bool
				allowCDN is tri-state:
				nil  -> keep default downloader behavior (CDN disabled),
				true -> allow redirect flow,
				false-> force legacy master-only flow.

			partSize int
			pool *bin.Pool
			retryHandler RetryHandler
				retryHandler observes transient downloader errors that are retried.

		Methods (total 7, in which 5 are exported)
			(*Downloader) Download(rpc Client, location tg.InputFileLocationClass) *Builder
				Download creates Builder for plain downloads.

			(*Downloader) Web(rpc Client, location tg.InputWebFileLocationClass) *Builder
				Web creates Builder for web files downloads.

			(*Downloader) WithAllowCDN(allow bool) *Downloader
				WithAllowCDN explicitly enables or disables CDN redirect flow.
				
				This flag is explicit: if it is not set, downloader keeps legacy
				master-DC-only behavior and does not attempt CDN redirect handling.
				Client integration (`telegram.Client.Downloader`) sets this option from
				`telegram.Options.AllowCDN`.

			(*Downloader) WithPartSize(partSize int) *Downloader
				WithPartSize sets chunk size.
				Must be divisible by 4KB.
				
				See https://core.telegram.org/api/files#downloading-files.

			(*Downloader) WithRetryHandler(handler RetryHandler) *Downloader
				WithRetryHandler sets callback for transient download errors that are retried
				internally by downloader.
				
				Handler can be called concurrently from download workers.

			/* 2 unexporteds ... *//* 2 unexporteds: */
			(*Downloader) parallel(ctx context.Context, r *reader, threads int, w io.WriterAt) (tg.StorageFileTypeClass, error)
				nolint:gocognit

			(*Downloader) stream(ctx context.Context, r *reader, w io.Writer) (tg.StorageFileTypeClass, error)
		As Outputs Of (at least 5, all are exported)
			func NewDownloader() *Downloader
			func (*Downloader).WithAllowCDN(allow bool) *Downloader
			func (*Downloader).WithPartSize(partSize int) *Downloader
			func (*Downloader).WithRetryHandler(handler RetryHandler) *Downloader
			func github.com/gotd/td/telegram.(*Client).Downloader() *Downloader
		As Inputs Of (at least one unexported)
			/* at least one unexported ... *//* at least one unexported: */
			func newBuilder(downloader *Downloader, schema schema) *Builder

	 type RedirectError (struct)
		RedirectError error is returned when Downloader get CDN redirect.
		See https://core.telegram.org/constructor/upload.fileCdnRedirect.

		Fields (only one, which is exported)
			Redirect *tg.UploadFileCDNRedirect
		Methods (only one, which is exported)
			(*RedirectError) Error() string
				Error implements error interface.

		Implements (at least one exported)
			*RedirectError : error

	 type RetryEvent (struct)
		RetryEvent describes retried transient downloader error.

		Fields (total 3, all are exported)
			Attempt int
				Attempt is 1-based counter inside current retry loop.

			Err error
				Err is the error that triggered retry.

			Operation string
				Operation identifies retry source.


	 type RetryHandler (func)
		RetryHandler is called for every downloader error that is retried internally.

		As Inputs Of (at least 3, in which 2 are exported)
			func (*Builder).WithRetryHandler(handler RetryHandler) *Builder
			func (*Downloader).WithRetryHandler(handler RetryHandler) *Downloader
			/* at least one unexported ... *//* at least one unexported: */
			func newCDNSchema(masterSchema master, provider CDNProvider, pool *bin.Pool, max int64, verifyCDNInline bool, retryHandler RetryHandler) *cdn

	/* 11 unexporteds ... *//* 11 unexporteds: */
	 type block (struct)

		Fields (total 5, none are exported)
			/* 5 unexporteds ... *//* 5 unexporteds: */
			chunk chunk
			chunk.data []byte
			chunk.tag tg.StorageFileTypeClass
			offset int64
			partSize int
		Methods (only one, which is unexported)
			/* one unexported ... *//* one unexported: */
			( block) last() bool
				last compares partSize and chunk length to determine last part.

		As Inputs Of (at least 2, neither is exported)
			/* 2+ unexporteds ... *//* 2+ unexporteds: */
			func writeAtLoop(w io.WriterAt, toWrite <-chan block) func(context.Context) error
			func writeLoop(w io.Writer, toWrite <-chan block) func(context.Context) error

	 type cdn (struct)
		cdn is a download schema that starts on the master DC and switches to CDN on
		upload.fileCdnRedirect without losing the original request.

		Fields (total 23, none are exported)
			/* 23 unexporteds ... *//* 23 unexporteds: */
			cdn CDN
			client Client
			clientDC int
			clientMux sync.Mutex
				clientMux serializes CDN client (re)creation per schema instance.

			closer io.Closer
			hashOffsets []int64
			hashes map[int64]tg.FileHash
			hashesMux sync.RWMutex
				hashesMux guards in-memory cache of CDN hashes by offset.

			master master
				master preserves regular path that may return redirect errors when
				allowCDN=true.

			max int64
				max is forwarded to provider pool creation, usually mapped from number of
				download threads.

			mode cdnMode
			pool *bin.Pool
			provider CDNProvider
			redirect *tg.UploadFileCDNRedirect
			refreshMux sync.Mutex
				refreshMux serializes redirect refreshes so only one goroutine asks master
				for new token when CDN reports token invalid.

			retryHandler RetryHandler
				retryHandler observes retried transient downloader errors.

			rev uint64
			stateMux sync.RWMutex
				stateMux guards mode/redirect/client pointer/revision.

			verify bool
				verify enables inline verification for decrypted CDN chunks.

			windows map[int64][]byte
			windowsFIFO []int64
			windowsLoad singleflight.Group
				windowsLoad deduplicates concurrent fetches of the same full hash window.

			windowsMux sync.Mutex
				windowsMux guards bounded cache of verified CDN hash windows used to
				handle custom part sizes that split hash windows.

		Methods (total 22, in which 3 are exported)
			(*cdn) Chunk(ctx context.Context, offset int64, limit int) (chunk, error)
			(*cdn) Close() error
			(*cdn) Hashes(ctx context.Context, offset int64) ([]tg.FileHash, error)
			/* 19 unexporteds ... *//* 19 unexporteds: */
			(*cdn) activateRedirect(ctx context.Context, redirect *tg.UploadFileCDNRedirect) error
			(*cdn) cacheHashes(hashes []tg.FileHash)
			(*cdn) cacheWindow(hash tg.FileHash, data []byte)
			(*cdn) cachedWindow(hash tg.FileHash) ([]byte, bool)
			(*cdn) closeClient()
			(*cdn) decrypt(src []byte, offset int64, redirect *tg.UploadFileCDNRedirect) ([]byte, error)
				decrypt decrypts file chunk from Telegram CDN.
				See https://core.telegram.org/cdn#decrypting-files.

			(*cdn) ensureClient(ctx context.Context, dcID int) (CDN, error)
			(*cdn) hash(offset int64) (tg.FileHash, bool)
			(*cdn) hashForOffset(ctx context.Context, offset int64) (tg.FileHash, error)
			(*cdn) loadAndVerifyWindow(ctx context.Context, hash tg.FileHash) ([]byte, error)
			(*cdn) recoverCDNControlError(ctx context.Context, err error, offset int64, limit int, rev uint64, loopAttempt int) (fallback *chunk, retry bool, handled bool, outErr error)
			(*cdn) refreshRedirect(ctx context.Context, offset int64, limit int, prevRev uint64, loopAttempt int) (*chunk, error)
			(*cdn) reportRetry(operation string, attempt int, err error)
			(*cdn) resetHashes()
			(*cdn) resetWindows()
			(*cdn) setMaster()
			(*cdn) setRedirect(redirect *tg.UploadFileCDNRedirect)
			(*cdn) snapshot() (mode cdnMode, redirect *tg.UploadFileCDNRedirect, rev uint64)
			(*cdn) verifyChunk(ctx context.Context, offset int64, requestedLimit int, data []byte) error
		Implements (at least 3, in which 1 is exported)
			*cdn : io.Closer
			/* 2+ unexporteds ... *//* 2+ unexporteds: */
			*cdn : retryReporter
			*cdn : schema
		As Outputs Of (at least one unexported)
			/* at least one unexported ... *//* at least one unexported: */
			func newCDNSchema(masterSchema master, provider CDNProvider, pool *bin.Pool, max int64, verifyCDNInline bool, retryHandler RetryHandler) *cdn

	 type cdnMode uint8 (basic type)

		As Types Of (total 2, neither is exported)
			/* 2 unexporteds ... *//* 2 unexporteds: */
			const modeCDN
			const modeMaster

	 type cdnRequestRange (struct)

		Fields (total 2, neither is exported)
			/* 2 unexporteds ... *//* 2 unexporteds: */
			limit int
			offset int64
		As Outputs Of (at least one unexported)
			/* at least one unexported ... *//* at least one unexported: */
			func buildCDNRequestPlan(offset int64, limit int) ([]cdnRequestRange, error)

	 type chunk (struct)

		Fields (total 2, neither is exported)
			/* 2 unexporteds ... *//* 2 unexporteds: */
			data []byte
			tag tg.StorageFileTypeClass

	 type master (struct)
		master is a master DC download schema.
		See https://core.telegram.org/api/files#downloading-files.

		Fields (total 5, none are exported)
			/* 5 unexporteds ... *//* 5 unexporteds: */
			allowCDN bool
			client Client
			location tg.InputFileLocationClass
			precise bool
			retryHandler RetryHandler
				retryHandler observes retried transient downloader errors.

		Methods (total 3, in which 2 are exported)
			( master) Chunk(ctx context.Context, offset int64, limit int) (chunk, error)
			( master) Hashes(ctx context.Context, offset int64) ([]tg.FileHash, error)
			/* one unexported ... *//* one unexported: */
			( master) reportRetry(operation string, attempt int, err error)
		Implements (at least 2, neither is exported)
			/* 2+ unexporteds ... *//* 2+ unexporteds: */
			 master : retryReporter
			 master : schema
		As Inputs Of (at least 3, none are exported)
			/* 3+ unexporteds ... *//* 3+ unexporteds: */
			func newCDNSchema(masterSchema master, provider CDNProvider, pool *bin.Pool, max int64, verifyCDNInline bool, retryHandler RetryHandler) *cdn
			func (*Builder).prepareCDNPath(m master, provider CDNProvider) *Builder
			func (*Builder).prepareMaster(m master, allowCDN bool) *Builder

	 type reader (struct)

		Fields (total 5, none are exported)
			/* 5 unexporteds ... *//* 5 unexporteds: */
			offset int64
			offsetMux sync.Mutex
			partSize int
				// immutable

			sch schema
				// immutable

			verifier *verifier
				// immutable

		Methods (total 4, in which 1 is exported)
			(*reader) Next(ctx context.Context) (block, error)
			/* 3 unexporteds ... *//* 3 unexporteds: */
			(*reader) next(ctx context.Context, offset int64, limit int) (block, error)
			(*reader) nextHashed(ctx context.Context) (block, error)
			(*reader) nextPlain(ctx context.Context) (block, error)
		As Outputs Of (at least 3, none are exported)
			/* 3+ unexporteds ... *//* 3+ unexporteds: */
			func plainReader(sch schema, partSize int) *reader
			func verifiedReader(sch schema, verifier *verifier) *reader
			func (*Builder).reader() *reader
		As Inputs Of (at least 2, neither is exported)
			/* 2+ unexporteds ... *//* 2+ unexporteds: */
			func (*Downloader).parallel(ctx context.Context, r *reader, threads int, w io.WriterAt) (tg.StorageFileTypeClass, error)
			func (*Downloader).stream(ctx context.Context, r *reader, w io.Writer) (tg.StorageFileTypeClass, error)

	 type retryReporter (interface)

		Methods (only one, which is unexported)
			/* one unexported ... *//* one unexported: */
			( retryReporter) reportRetry(operation string, attempt int, err error)
		Implemented By (at least 3, none are exported)
			/* 3+ unexporteds ... *//* 3+ unexporteds: */
			*cdn
			 master
			 web

	 type schema (interface)
		schema is simple interface for different download schemas.

		Methods (total 2, both are exported)
			( schema) Chunk(ctx context.Context, offset int64, limit int) (chunk, error)
			( schema) Hashes(ctx context.Context, offset int64) ([]tg.FileHash, error)
		Implemented By (at least 3, none are exported)
			/* 3+ unexporteds ... *//* 3+ unexporteds: */
			*cdn
			 master
			 web
		As Inputs Of (at least 6, none are exported)
			/* 6+ unexporteds ... *//* 6+ unexporteds: */
			func closeSchema(s schema) func() error
			func newBuilder(downloader *Downloader, schema schema) *Builder
			func newVerifier(client schema, hashes ...tg.FileHash) *verifier
			func plainReader(sch schema, partSize int) *reader
			func reportSchemaRetry(s schema, operation string, attempt int, err error)
			func verifiedReader(sch schema, verifier *verifier) *reader

	 type verifier (struct)

		Fields (total 4, none are exported)
			/* 4 unexporteds ... *//* 4 unexporteds: */
			client schema
			hashes []tg.FileHash
				hashes is ordered queue consumed by reader.

			mux sync.Mutex
			offset int64
				offset points to next hash window to request from server.

		Methods (total 4, none are exported)
			/* 4 unexporteds ... *//* 4 unexporteds: */
			(*verifier) next(ctx context.Context) (tg.FileHash, bool, error)
			(*verifier) pop() (tg.FileHash, bool)
			(*verifier) update(hashes ...tg.FileHash) (tg.FileHash, bool)
			(*verifier) verify(hash tg.FileHash, data []byte) bool
		As Outputs Of (at least one unexported)
			/* at least one unexported ... *//* at least one unexported: */
			func newVerifier(client schema, hashes ...tg.FileHash) *verifier
		As Inputs Of (at least one unexported)
			/* at least one unexported ... *//* at least one unexported: */
			func verifiedReader(sch schema, verifier *verifier) *reader

	 type web (struct)
		web is a web file download schema.
		See https://core.telegram.org/api/files#downloading-webfiles.

		Fields (total 3, none are exported)
			/* 3 unexporteds ... *//* 3 unexporteds: */
			client Client
			location tg.InputWebFileLocationClass
			retryHandler RetryHandler
				retryHandler observes retried transient downloader errors.

		Methods (total 3, in which 2 are exported)
			( web) Chunk(ctx context.Context, offset int64, limit int) (chunk, error)
			( web) Hashes(ctx context.Context, offset int64) ([]tg.FileHash, error)
			/* one unexported ... *//* one unexported: */
			( web) reportRetry(operation string, attempt int, err error)
		Implements (at least 2, neither is exported)
			/* 2+ unexporteds ... *//* 2+ unexporteds: */
			 web : retryReporter
			 web : schema


Package-Level Functions (total 18, in which 1 is exported)

	 func NewDownloader() *Downloader
		NewDownloader creates new Downloader.

	/* 17 unexporteds ... *//* 17 unexporteds: */
	 func buildCDNRequestPlan(offset int64, limit int) ([]cdnRequestRange, error)
	 func closeSchema(s schema) func() error
	 func isCDNFingerprintErr(err error) bool
	 func isCDNMasterFallbackErr(err error) bool
	 func isRetryableTimeout(ctx context.Context, err error) bool
	 func largestCDNValidLimit(max int) int
	 func newBuilder(downloader *Downloader, schema schema) *Builder
	 func newCDNSchema(masterSchema master, provider CDNProvider, pool *bin.Pool, max int64, verifyCDNInline bool, retryHandler RetryHandler) *cdn
	 func newVerifier(client schema, hashes ...tg.FileHash) *verifier
	 func plainReader(sch schema, partSize int) *reader
	 func reportSchemaRetry(s schema, operation string, attempt int, err error)
	 func retryLimitErr(op string, attempts int, err error) error
	 func retryRequest[T](ctx context.Context, op string, onRetry func(attempt int, err error), fn func() (T, error)) (_ T, err error)

		Type Parameters:
			T: any

	 func verifiedReader(sch schema, verifier *verifier) *reader
	 func windowLoadKey(hash tg.FileHash) string
	 func writeAtLoop(w io.WriterAt, toWrite <-chan block) func(context.Context) error
	 func writeLoop(w io.Writer, toWrite <-chan block) func(context.Context) error
Package-Level Variables (total 2, in which 1 is exported)

	  var ErrHashMismatch error
		ErrHashMismatch means that download hash verification was failed.

	/* one unexported ... *//* one unexported: */
	  var errHashesNotSupported error
Package-Level Constants (total 15, in which 7 are exported)

	const RetryOperationCreateClient = "cdn.create_client"
	const RetryOperationGetFile = "cdn.get_file"
	const RetryOperationGetFileHashes = "cdn.get_file_hashes"
	const RetryOperationReaderChunk = "reader.chunk"
	const RetryOperationReaderHashes = "reader.hashes"
	const RetryOperationRefreshRedirect = "cdn.refresh_redirect"
	const RetryOperationReupload = "cdn.reupload"
	/* 8 unexporteds ... *//* 8 unexporteds: */
	const cdnMaxChunk = 1048576
	const cdnMinChunk = 4096
	const cdnRefreshProbeLimit = 4096
	const defaultPartSize = 524288 // 512 kb
	const maxRetryAttempts = 20
	const maxVerifiedWindowCache = 16
		maxVerifiedWindowCache bounds memory used by split-window verification.
		
		Split windows are needed only when downloader part size does not align with
		Telegram CDN hash window size (typically 128KB). In that case we may fetch a
		full hash window once, verify it, and reuse verified bytes for neighboring
		chunks. A small bounded cache is enough because sequential/parallel readers
		usually work on nearby offsets.

	const modeCDN cdnMode = 1
		modeCDN means active redirect exists and chunks should be fetched from CDN.

	const modeMaster cdnMode = 0
		modeMaster means request master first and switch only on redirect.

The pages are generated with Golds v0.8.4. (GOOS=linux GOARCH=amd64)
Golds is a Go 101 project developed by Tapir Liu.
PR and bug reports are welcome and can be submitted to the issue list.
Please follow @zigo_101 (reachable from the left QR code) to get the latest news of Golds.