API reference

DownloadRequest Class

Modifiers: final

Describes a pak download: source URL, destination, and optional integrity constraints.

Constructors

DownloadRequest ( uri , destinationFile , pakName , expectedSizeBytes , validator , allowResume , resumeValidator , headers , refreshAuthHeaders , validatorTimeoutMs )

Signature

constructor(uri: Uri, destinationFile: File, pakName: String, expectedSizeBytes: Long? = null, validator: (File) -> DownloadError?? = null, allowResume: Boolean = true, resumeValidator: (File, Long) -> Boolean? = null, headers: Map<String, String> = emptyMap(), refreshAuthHeaders: (Int) -> Map<String, String>?? = null, validatorTimeoutMs: Long? = null)

Parameters

uri: Uri Source URL for the pak file.

destinationFile: File Where to write the final file. Parent directory must exist.

pakName: String The mount name that will be used with PakManager.mount(). Used for deduplication tracking and logging, NOT for auto-mounting.

expectedSizeBytes: Long? Optional expected file size for post-download validation.

validator: Function1? Optional pluggable validation function. Called after download completes. Return null if valid, or a DownloadError describing the problem. When DownloadRequest is set, the validator runs on the manager's executor with a bounded timeout. The validator must check Thread.currentThread().isInterrupted at safe points (e.g. between disk-read chunks, between hash updates) and return promptly when interrupted. If your validator ignores interrupts, the executor thread will leak until JVM shutdown when a timeout fires — the manager surfaces ValidationFailed to the caller on schedule, but the runaway thread keeps consuming CPU / file handles in the background.

allowResume: Boolean If true and a partial file exists at DownloadRequest, the PakDownloader will be asked to resume from the existing byte offset.

resumeValidator: Function2? Optional function to verify a partial file is still valid for resuming. Receives the partial file and its byte length. Return true to resume, false to delete and restart. Use this to verify ETag, Last-Modified, or content prefix against server state.

headers: Map Optional HTTP headers to include in the download request. Use for authorization (Bearer tokens, API keys, custom auth schemes), cache control, or CDN-specific headers. Keys are header names, values are header values. Example: mapOf("Authorization" to "Bearer <token>").

refreshAuthHeaders: Function1? Optional callback invoked by the PakDownloader when the server returns an authorization-failure status (401 / 403). Receives the failing HTTP status code and should return a fresh headers map (e.g. with a refreshed bearer token) to retry the request, or null to give up and surface the failure. Implementations that don't need this can leave it unset; downloaders that don't support it will ignore it.

validatorTimeoutMs: Long? Optional maximum time (in milliseconds) the DownloadRequest is allowed to run before the manager gives up and reports DownloadError.ValidationFailed. Default null means "no timeout" — a hung validator will park the download worker thread indefinitely. Set to a finite value (e.g. 30_000) when validators do non-trivial work (CRC, hash, parse) and you want a hung-validator path that the user can recover from via cleanup / retry.

allowResume : Boolean [Get]	If true and a partial file exists at DownloadRequest.destinationFile, the PakDownloader will be asked to resume from the existing byte offset. Signature val allowResume: Boolean = true
destinationFile : File [Get]	Where to write the final file. Parent directory must exist. Signature val destinationFile: File
expectedSizeBytes : Long? [Get]	Optional expected file size for post-download validation. Signature val expectedSizeBytes: Long? = null
headers : Map [Get]	Optional HTTP headers to include in the download request. Use for authorization (Bearer tokens, API keys, custom auth schemes), cache control, or CDN-specific headers. Keys are header names, values are header values. Example: `mapOf("Authorization" to "Bearer <token>")`. Signature val headers: Map<String, String>
pakName : String [Get]	The mount name that will be used with PakManager.mount(). Used for deduplication tracking and logging, NOT for auto-mounting. Signature val pakName: String
refreshAuthHeaders : Function1? [Get]	Optional callback invoked by the PakDownloader when the server returns an authorization-failure status (401 / 403). Receives the failing HTTP status code and should return a fresh headers map (e.g. with a refreshed bearer token) to retry the request, or null to give up and surface the failure. Implementations that don't need this can leave it unset; downloaders that don't support it will ignore it. Signature val refreshAuthHeaders: (Int) -> Map<String, String>?? = null
resumeValidator : Function2? [Get]	Optional function to verify a partial file is still valid for resuming. Receives the partial file and its byte length. Return true to resume, false to delete and restart. Use this to verify ETag, Last-Modified, or content prefix against server state. Signature val resumeValidator: (File, Long) -> Boolean? = null
uri : Uri [Get]	Source URL for the pak file. Signature val uri: Uri
validator : Function1? [Get]	Optional pluggable validation function. Called after download completes. Return null if valid, or a DownloadError describing the problem. When DownloadRequest.validatorTimeoutMs is set, the validator runs on the manager's executor with a bounded timeout. The validator must check `Thread.currentThread().isInterrupted` at safe points (e.g. between disk-read chunks, between hash updates) and return promptly when interrupted. If your validator ignores interrupts, the executor thread will leak until JVM shutdown when a timeout fires — the manager surfaces `ValidationFailed` to the caller on schedule, but the runaway thread keeps consuming CPU / file handles in the background. Signature val validator: (File) -> DownloadError?? = null
validatorTimeoutMs : Long? [Get]	Optional maximum time (in milliseconds) the DownloadRequest.validator is allowed to run before the manager gives up and reports DownloadError.ValidationFailed. Default null means "no timeout" — a hung validator will park the download worker thread indefinitely. Set to a finite value (e.g. 30_000) when validators do non-trivial work (CRC, hash, parse) and you want a hung-validator path that the user can recover from via cleanup / retry. Signature val validatorTimeoutMs: Long? = null

DownloadRequest Class

Constructors

Properties