Skip to main content

StateManagementService

Reads and writes Octo's state files through the configured IStateProvider.

Resolve it from the Container when you need to inspect what the last run recorded. Octo manages its own state files, so writing through this service is rarely the right move.

@group

Services/State Management

Index

Constructors

Properties

Methods

Constructors

constructor

Properties

readonlyactualResourceStateFileName

actualResourceStateFileName: string = 'resources-actual.json'

The resource graph as it stands after the last commit.

readonlyexternalResourceStateFileNamePrefix

externalResourceStateFileNamePrefix: string = 'resource-state-'

The prefix of each record an external resource's action writes, until commit folds it into the resource graph.

readonlyimportStateFileName

importStateFileName: string = 'imports.json'

The other apps' sealed states the last generate read.

readonlymodelStateFileName

modelStateFileName: string = 'models.json'

The model graph as it stands after the last commit.

readonlyoldResourceStateFileName

oldResourceStateFileName: string = 'resources-old.json'

The resource graph as intent described it on the last commit.

readonlystateVersion

stateVersion: number = 1

The version of the state files this octo writes, and the only one it reads.

Methods

getAppLock

  • getAppLock(): Promise<string | undefined>

  • The id of the lock currently held, or undefined when the app is unlocked.

    Returns Promise<string | undefined>

getModelState

  • getModelState(stateFileName: string, __namedParameters?: { freeze?: boolean }): Promise<ModelStateFile>

  • Reads the model graph. Returns an empty graph when no state exists yet.

    Parameters

    • stateFileName: string
    • __namedParameters: { freeze?: boolean } = {}
      • optionalfreeze: boolean = true

    Returns Promise<ModelStateFile>

getResourceState

  • getResourceState(stateFileName: string, __namedParameters?: { freeze?: boolean }): Promise<ResourceStateFile>

  • Reads a resource graph. Returns an empty graph when no state exists yet.

    Parameters

    • stateFileName: string
    • __namedParameters: { freeze?: boolean } = {}
      • optionalfreeze: boolean = true

    Returns Promise<ResourceStateFile>

getSealedState

  • The model graph and the resource graph of the newest sealed state, both from the one seal. A graph the sealed state does not hold, or all of them when nothing is sealed yet, is empty.

    Returns Promise<{ modelState: ModelStateFile; resourceState: ResourceStateFile }>

getState

  • getState(stateFileName: string, defaultValue?: any): Promise<Buffer<ArrayBufferLike>>

  • Reads a state file as-is.

    Parameters

    • stateFileName: string

      The file's name in the state provider.

    • optionaldefaultValue: any

      Returned instead of throwing when the file does not exist.

    Returns Promise<Buffer<ArrayBufferLike>>

getTemporaryFilePath

  • getTemporaryFilePath(name: string): Promise<string>

isAppLocked

  • isAppLocked(lockId: string): Promise<boolean>

  • Whether lockId is the lock currently held.

    @throws

    TransactionError With the message Invalid lock ID! when a different lock is held.

    Parameters

    • lockId: string

    Returns Promise<boolean>

listStates

  • listStates(prefix: string): Promise<string[]>

  • The names of the state files whose name starts with prefix. See IStateProvider.listStates.

    Parameters

    • prefix: string

    Returns Promise<string[]>

lockApp

  • lockApp(lockId?: string): Promise<{ commitId?: string; lockId: string; resumedFrom?: directory | run | sealed }>

  • Takes the app lock and returns its id. With lockId, resumes the run already holding it.

    A new lock is refused while the state holds a journal file of any command but generate, validate or lock: a run that finished without its journal being archived.

    @throws

    AppLockError

    • When a lock is held, naming the id that holds it.
    • When lockId is given and is not the lock held.
    • When the state holds journal files of an unfinished run.

    Parameters

    • optionallockId: string

    Returns Promise<{ commitId?: string; lockId: string; resumedFrom?: directory | run | sealed }>

refreshState

  • refreshState(): Promise<{ commitId?: string; previousCommitId?: string; replaced: boolean }>

  • Brings the state up to the newest a run may plan against. See IStateProvider.refreshState.

    Returns Promise<{ commitId?: string; previousCommitId?: string; replaced: boolean }>

saveStates

  • saveStates(stateFiles: ({ data: Buffer<ArrayBufferLike> | undefined; stateFileName: string } | { filePath: string; stateFileName: string })[]): Promise<void>

  • Writes state files as-is and as one change, moving each one given a filePath and deleting each one given no data. Listeners of StateFilesSavingEvent may add files to the change first.

    Parameters

    • stateFiles: ({ data: Buffer<ArrayBufferLike> | undefined; stateFileName: string } | { filePath: string; stateFileName: string })[]

    Returns Promise<void>

unlockApp

  • unlockApp(lockId: string): Promise<void>

  • Seals the run and releases the app lock. Unlocking an app that is not locked is not an error.

    In order: listeners of AppUnlockingEvent write the last of the run, and a failure there keeps the lock held; the provider seals the run and releases the lock, see IStateProvider.unlockApp.

    @throws

    TransactionError With the message Invalid lock ID! when a different lock is held.

    Parameters

    • lockId: string

    Returns Promise<void>

Page Options