Skip to main content

LocalStateProvider

Keeps state in a directory on the local filesystem.

Good for experimenting on your own machine. It is not shared, so a team running Octo against the same infrastructure needs a provider that persists somewhere they all reach.

Releasing the lock seals the run into archives/<commitId>/, the newest of which is the sealed state. Deleting old archives is up to you.

@example
await octo.initialize(new LocalStateProvider('./infrastructure'));
@group

Services/State Management

@see

Techniques for State Providers.

Implements

Index

Constructors

Methods

Constructors

constructor

  • Parameters

    • localStateDirectoryPath: string

      The directory state files are written into.

    Returns LocalStateProvider

Methods

getAppLock

  • getAppLock(): Promise<string | undefined>

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

    Returns Promise<string | undefined>

getSealedStates

  • getSealedStates(stateFileNames: string[]): Promise<(Buffer<ArrayBufferLike> | undefined)[]>

  • Reads state files from the newest archive, found by the time at the start of its commit id. Only one lock is held at a time, so the last lock taken is the last run sealed.

    Parameters

    • stateFileNames: string[]

    Returns Promise<(Buffer<ArrayBufferLike> | undefined)[]>

getState

  • getState(stateFileName: string): Promise<Buffer<ArrayBufferLike>>

  • Reads a state file.

    @throws

    TransactionError With the message No state found! when the file does not exist.

    Parameters

    • stateFileName: string

    Returns Promise<Buffer<ArrayBufferLike>>

getTemporaryFilePath

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

  • A new path beside the state files, named .<name>.<random>.tmp.

    Parameters

    • name: string

    Returns 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.

    Parameters

    • prefix: string

    Returns Promise<string[]>

lockApp

  • lockApp(lock: { commitId: string } | { lockId: string }): Promise<{ commitId: string; lockId: string }>

  • Takes the app lock, writing its id, its commit and the time it was taken into local-state.lock beside the state files. With lockId, resumes the run already holding it. The lock never expires.

    @throws

    AppLockError When a lock is held, naming the id that holds it and how long it has been held. When lockId is given and is not the lock held.

    Parameters

    • lock: { commitId: string } | { lockId: string }
      • commitId: string
      • lockId: string

    Returns Promise<{ commitId: string; lockId: string }>

refreshState

  • refreshState(): Promise<{ replaced: boolean }>

  • Does nothing: the directory is the only copy of the state, so it is always the newest.

    Returns Promise<{ replaced: boolean }>

saveStates

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

  • Writes state files, overwriting whatever was there, moving each one given a filePath, and deleting each one given no data.

    Each file is written under a temporary name and renamed into place, so a process killed mid-write leaves the file whole, and a reader holding it through a hard link keeps what it holds.

    Parameters

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

    Returns Promise<void>

unlockApp

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

  • Seals the run with LocalStateProvider.archiveState, then releases the app lock by deleting the lock file. A run that cannot be archived keeps the lock held.

    @throws

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

    Parameters

    • lockId: string

    Returns Promise<void>

Page Options