Skip to content

l0.DependencyControl.UpdateTask

UpdateTask = require "l0.DependencyControl.UpdateTask"

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

UpdateTask

Mutable execution state for one install/update operation.

Constructor 

updateTask = UpdateTask record, targetVersionNumber, addFeeds, optional, channel, reason, updater

local updateTask = UpdateTask(record, targetVersionNumber, addFeeds, optional, channel, reason, updater)

Creates an update task for one record.

param type description
record PackageRecord
targetVersionNumber? number Minimum version to install (default 0, i.e. any).
addFeeds? string[]
optional? boolean Treat this as an optional dependency.
channel? string Update channel to use.
reason? UpdateReason Why this task runs; a prompt is allowed only when this reason is permitted by that prompt kind's configured threshold.
updater Updater

Instance methods

run 

updateTask\run waitLock

updateTask:run(waitLock)

Runs the full update/install flow for this task. Acquires the global updater lock but does not release it — the caller (a PackageRecord.requireModules / macro-hook / Toolbox entry point) must call updater\releaseLock once its whole operation is done, or the lock is held until its lease lapses (orphanTimeout), blocking other scripts' updates.

param type description
waitLock? boolean Wait for a concurrent update to finish instead of bailing.

Returns:

refreshRecord 

updateTask\refreshRecord!

updateTask:refreshRecord()

Reloads this task's record from its config file to pick up an install/update another updater performed concurrently: on a version bump (or a virtual record becoming real) it reloads the module and marks the task updated. Called after waiting on the updater lock, so a task doesn't redo work already done.

Class methods

isWithinContextCeiling 

UpdateTask.isWithinContextCeiling reason, ceiling

UpdateTask.isWithinContextCeiling(reason, ceiling)

Reports whether an update context is allowed under a ceiling on the context ladder.

param type description
reason UpdateReason The context asking to act.
ceiling? UpdateContextCeiling The most autonomous context still allowed.

Returns:

  • within boolean — True when the context sits at or below the ceiling; false when the ceiling is off, unset, or unrecognized.

getUpdaterErrorMsg 

UpdateTask.getUpdaterErrorMsg code, name, scriptType, isInstall, detailMsg

UpdateTask.getUpdaterErrorMsg(code, name, scriptType, isInstall, detailMsg)

Converts updater status/error codes into user-facing error messages.

param type description
code? UpdateStatus A nil or unmapped code yields a generic message naming the code.
name string
scriptType ScriptType A domain.ScriptType value.
isInstall boolean
detailMsg? string

Returns:

  • message string — The user-facing error text for the status code.

resolveSourceUrl 

UpdateTask.resolveSourceUrl source, selfFeed, userFeed, modulesSection

UpdateTask.resolveSourceUrl(source, selfFeed, userFeed, modulesSection)

Resolves the feed URL a persisted source record maps to, given the owning package's feed fields.

param type description
source SourceChoiceRecord The persisted source record.
selfFeed? string The package's declared feed (used for a self-declared source).
userFeed? string The package's per-package override feed (used for a user-feed source).
modulesSection? table<string, table> The modules config section (used to resolve a provider source).

Returns:

  • url string? — The resolved feed URL, or nil if it can't be determined.

Fields

field type description
defaultFeedTrustPromptThreshold UpdateContextCeiling
defaultPackageChoicePromptThreshold UpdateContextCeiling

Enums

UpdateStatus

member value description
UpToDate 0 the installed version already satisfies the target
Installed 1 the install or update succeeded
AlreadyUpdated 2 another in-flight update already brought the package to the target version
SkippedOptional 3 an optional dependency couldn't be satisfied and was skipped
UpdaterDisabled -1 the updater is disabled in the config
InvalidNamespace -2 the record's namespace doesn't conform to the rules
Unmanaged -3 the record is virtual or unmanaged, so it isn't updated
AnotherUpdateRunning -5 another script or process holds the updater lock
NoSuitablePackage -6 no feed offered a package satisfying the requirement
NoInternet -7 no internet connection is available
InvalidVersion -8 the requested version string couldn't be parsed
ProtectedInstall -9 the entry point is in Aegisub's ?data automation directory
TaskAlreadyRunning -10 this update task is already running
RequirementsUnmet -15 the package's own required modules couldn't be satisfied
UntrustedFeed -16 the only suitable package is in an untrusted feed
PinnedUnavailable -17 the pinned package source is no longer available
UserAborted -18 the user aborted the update
BlockedFeed -19 the only suitable package is in a feed the user blocked
TempDirFailed -30 the temporary download directory couldn't be created
PathTraversal -33 a feed file tried to deploy outside its namespaced path
BadHash -35 a feed file carried a missing or malformed SHA-1 hash
MoveFailed -50 some downloaded files couldn't be moved into place
ModuleNotFound -55 the install succeeded but the module loader couldn't find the module
ModuleLoadFailed -56 the install succeeded but the module raised while loading
MissingVersionRecord -57 the installed module exposes no version record
RecordCreateFailed -58 creating an unmanaged record for the installed module failed
DownloadAddFailed -140 a file download couldn't be queued
DownloadFailed -245 one or more file downloads failed

UpdateContextCeiling

member value description
Off "off" no context at all
UserRequested "user-requested" only actions the user starts themselves (e.g. via the Toolbox)
DependencyResolution "dependency-resolution" also installing/updating a module as a dependency
AutoUpdate "auto-update" also background scheduled update checks

UpdateReason

member value description
UserRequested "user-requested" an explicit user/UI request (e.g. the Toolbox)
DependencyResolution "dependency-resolution" installing/updating a module as a dependency of another
AutoUpdate "auto-update" a background scheduled update check

SourceChoiceStickiness

member value description
Unset "unset" no preference recorded yet; resolve normally and prompt only if interactive
Once "once" prompt again whenever a choice remains, preselecting the remembered pick
Retain "retain" reuse the remembered pick whenever it's still eligible, without prompting
Pinned "pinned" always reuse the remembered pick; if it's gone, abort (required) or skip (optional)
Auto "auto" never prompt; always resolve via the ranking, refreshing the remembered pick for information

SourceFeedKind

member value description
SelfDeclared "self-declared" the feed declared in the record
UserFeed "user-feed" the per-package user override feed
Provider "provider" another module that provides the required one (URL taken from the provider's own source)
Other "other" a third-party trusted/extra feed; stores a literal feedUrl

FeedTrustDecision

member value description
Once "once" use the untrusted feed for this install only
Always "always" add the feed to the user's trusted feeds
Never "never" add the feed to the user's blocked feeds

Types

UpdaterTrustBand

value description
1 DeclaredDirect: the declared/own feed, trusted, offering the module by name
2 TrustedDirect: another trusted feed, offering the module by name
3 TrustedProvider: a trusted feed, offering a module that provides it
4 UntrustedDirect: an untrusted feed, offering the module by name
5 UntrustedProvider: an untrusted feed, offering a provider

CandidatePackageSource

A potential package source pooled during resolution to collect a feed's update record, where it came from and its trust status.

field type description
updateRecord ScriptUpdateRecord The feed's update record for this candidate, channel already selected.
feedUrl string URL of the feed the candidate was found in.
isDirect boolean True when the feed offers the required package by name; false when via a provider.
trustBand UpdaterTrustBand The candidate's trust band.
providesVersion? string For a provider, the alias version range it declares (nil = any version).

UpdaterResolution

The outcome of resolving a package source: either a source to install or a status to return.

field type description
installRequired boolean Whether the caller must perform an install/update.
statusCode? UpdateStatus The status to return when no install is required (installRequired false).
statusDetailMessage? any Detail accompanying statusCode (e.g. an untrusted feed URL or an error string).
selectedSource? CandidatePackageSource The source to install; set when installRequired is true.
stickiness? SourceChoiceStickiness The source-choice stickiness to persist; set when installRequired is true.
maxVersion? number The highest candidate version found during resolution; set when installRequired is true.

SourceChoiceRecord

A package's remembered source, persisted per-package as currentSource.

field type description
feedSource SourceFeedKind Where the source came from.
feedUrl? string The literal feed URL; only stored (and required) for the other feedSource.
channel string The update channel the source was resolved on.
provider? { namespace: string, version?: string } The provider that satisfied the requirement, when resolved indirectly.
stickiness SourceChoiceStickiness How sticky the choice is.