IStateProvider
Implemented by
Index
Methods
getAppLock
The id of the lock currently held, or
undefinedwhen the app is unlocked.Returns Promise<string | undefined>
getSealedStates
Reads state files from the newest sealed state, which a released lock left behind, all from the one seal. Another app reads this one's state here, never while one of its runs is half done.
Returns one entry per name in the order given,
undefinedfor a file the sealed state does not hold. All areundefinedwhen nothing is sealed yet.Parameters
stateFileNames: string[]
Returns Promise<(Buffer<ArrayBufferLike> | undefined)[]>
getState
Reads a state file.
Parameters
stateFileName: string
Returns Promise<Buffer<ArrayBufferLike>>
getTemporaryFilePath
A new path where a writer prepares a file before saving it by its path, named after
name. It is no state file, and the writer removes it if it never saves it.Parameters
name: string
Returns Promise<string>
isAppLocked
Whether
lockIdis the lock currently held.Parameters
lockId: string
Returns Promise<boolean>
listStates
The names of the state files whose name starts with
prefix, named as IStateProvider.getState would be given them.Octo reads state by name everywhere else, so this is the only way it can discover a file it was not told about - a record an interrupted run left behind. Returns an empty list when the store holds nothing matching, including when it does not exist yet.
Parameters
prefix: string
Returns Promise<string[]>
lockApp
Takes the app lock and returns its id, which
applyandcommitmust then present.The lock is taken atomically, so of two callers racing for it exactly one wins.
commitIdnames what the run writes into and seals as, and starts with the time it was made. WithlockId, resumes the run already holding that lock instead, which is how a run that died is finished.A provider sharing state names where a resume took the state directory from in
resumedFrom:directory, the directory the lock was taken in, left as it was;run, what the run uploaded so far;sealed, the newest sealed state, because the run uploaded nothing.Parameters
lock: { commitId: string } | { lockId: string }
commitId: string
lockId: string
Returns Promise<{ commitId?: string; lockId: string; resumedFrom?: directory | run | sealed }>
refreshState
Brings the state up to the newest a run may plan against.
generatecalls it before reading any.A provider whose state is always the newest does nothing here, and returns
replaced: false. One that replaced the state files names the commit it replaced them with, and the one before.Returns Promise<{ commitId?: string; previousCommitId?: string; replaced: boolean }>
saveStates
Writes state files as one change, overwriting whatever was there. A file comes from
data, or is moved fromfilePath, a path IStateProvider.getTemporaryFilePath gave, without being read into memory; one givendata: undefinedis deleted. Deleting one that is not there is not an error.A provider that pays per write makes one write of the whole change rather than one per file.
Parameters
stateFiles: ({ data: Buffer<ArrayBufferLike> | undefined; stateFileName: string } | { filePath: string; stateFileName: string })[]
Returns Promise<void>
unlockApp
Seals the state, then releases the app lock. Unlocking an app that is not locked is not an error.
Parameters
lockId: string
Returns Promise<void>
Where Octo's state files live.
Octo has no database - it records what it built in state files, and reads them back on the next run to work out the diff. A state provider is only asked to put a named blob somewhere and hand it back later, so implementing this interface is all it takes to keep state in S3, a database, or anywhere else your team already trusts.
Pass one to Octo.initialize.
Services/State Management
Techniques for State Providers.