github.com/opentofu/opentofu@v1.7.1/internal/states/statemgr/transient.go (about)

     1  // Copyright (c) The OpenTofu Authors
     2  // SPDX-License-Identifier: MPL-2.0
     3  // Copyright (c) 2023 HashiCorp, Inc.
     4  // SPDX-License-Identifier: MPL-2.0
     5  
     6  package statemgr
     7  
     8  import "github.com/opentofu/opentofu/internal/states"
     9  
    10  // Transient is a union of the Reader and Writer interfaces, for types that
    11  // deal with transient snapshots.
    12  //
    13  // Transient snapshots are ones that are generally retained only locally and
    14  // to not create any historical version record when updated. Transient
    15  // snapshots are not expected to outlive a particular OpenTofu process,
    16  // and are not shared with any other process.
    17  //
    18  // A state manager type that is primarily concerned with persistent storage
    19  // may embed type Transient and then call State from its PersistState and
    20  // WriteState from its RefreshState in order to build on any existing
    21  // Transient implementation, such as the one returned by NewTransientInMemory.
    22  type Transient interface {
    23  	Reader
    24  	Writer
    25  }
    26  
    27  // Reader is the interface for managers that can return transient snapshots
    28  // of state.
    29  //
    30  // Retrieving the snapshot must not fail, so retrieving a snapshot from remote
    31  // storage (for example) should be dealt with elsewhere, often in an
    32  // implementation of Refresher. For a type that implements both Reader
    33  // and Refresher, it is okay for State to return nil if called before
    34  // a RefreshState call has completed.
    35  //
    36  // For a type that implements both Reader and Writer, State must return the
    37  // result of the most recently completed call to WriteState, and the state
    38  // manager must accept concurrent calls to both State and WriteState.
    39  //
    40  // Each caller of this function must get a distinct copy of the state, and
    41  // it must also be distinct from any instance cached inside the reader, to
    42  // ensure that mutations of the returned state will not affect the values
    43  // returned to other callers.
    44  type Reader interface {
    45  	// State returns the latest state.
    46  	//
    47  	// Each call to State returns an entirely-distinct copy of the state, with
    48  	// no storage shared with any other call, so the caller may freely mutate
    49  	// the returned object via the state APIs.
    50  	State() *states.State
    51  }
    52  
    53  // Writer is the interface for managers that can create transient snapshots
    54  // from state.
    55  //
    56  // Writer is the opposite of Reader, and so it must update whatever the State
    57  // method reads from. It does not write the state to any persistent
    58  // storage, and (for managers that support historical versions) must not
    59  // be recorded as a persistent new version of state.
    60  //
    61  // Implementations that cache the state in memory must take a deep copy of it,
    62  // since the caller may continue to modify the given state object after
    63  // WriteState returns.
    64  type Writer interface {
    65  	// WriteState saves a transient snapshot of the given state.
    66  	//
    67  	// The caller must ensure that the given state object is not concurrently
    68  	// modified while a WriteState call is in progress. WriteState itself
    69  	// will never modify the given state.
    70  	WriteState(*states.State) error
    71  }