github.com/iaas-resource-provision/iaas-rpc@v1.0.7-0.20211021023331-ed21f798c408/internal/states/statemgr/persistent.go (about) 1 package statemgr 2 3 import ( 4 version "github.com/hashicorp/go-version" 5 ) 6 7 // Persistent is a union of the Refresher and Persistent interfaces, for types 8 // that deal with persistent snapshots. 9 // 10 // Persistent snapshots are ones that are retained in storage that will 11 // outlive a particular Terraform process, and are shared with other Terraform 12 // processes that have a similarly-configured state manager. 13 // 14 // A manager may also choose to retain historical persistent snapshots, but 15 // that is an implementation detail and not visible via this API. 16 type Persistent interface { 17 Refresher 18 Persister 19 } 20 21 // Refresher is the interface for managers that can read snapshots from 22 // persistent storage. 23 // 24 // Refresher is usually implemented in conjunction with Reader, with 25 // RefreshState copying the latest persistent snapshot into the latest 26 // transient snapshot. 27 // 28 // For a type that implements both Refresher and Persister, RefreshState must 29 // return the result of the most recently completed successful call to 30 // PersistState, unless another concurrently-running process has persisted 31 // another snapshot in the mean time. 32 // 33 // The Refresher implementation must guarantee that the snapshot is read 34 // from persistent storage in a way that is safe under concurrent calls to 35 // PersistState that may be happening in other processes. 36 type Refresher interface { 37 // RefreshState retrieves a snapshot of state from persistent storage, 38 // returning an error if this is not possible. 39 // 40 // Types that implement RefreshState generally also implement a State 41 // method that returns the result of the latest successful refresh. 42 // 43 // Since only a subset of the data in a state is included when persisting, 44 // a round-trip through PersistState and then RefreshState will often 45 // return only a subset of what was written. Callers must assume that 46 // ephemeral portions of the state may be unpopulated after calling 47 // RefreshState. 48 RefreshState() error 49 } 50 51 // Persister is the interface for managers that can write snapshots to 52 // persistent storage. 53 // 54 // Persister is usually implemented in conjunction with Writer, with 55 // PersistState copying the latest transient snapshot to be the new latest 56 // persistent snapshot. 57 // 58 // A Persister implementation must detect updates made by other processes 59 // that may be running concurrently and avoid destroying those changes. This 60 // is most commonly achieved by making use of atomic write capabilities on 61 // the remote storage backend in conjunction with book-keeping with the 62 // Serial and Lineage fields in the standard state file formats. 63 type Persister interface { 64 PersistState() error 65 } 66 67 // PersistentMeta is an optional extension to Persistent that allows inspecting 68 // the metadata associated with the snapshot that was most recently either 69 // read by RefreshState or written by PersistState. 70 type PersistentMeta interface { 71 // StateSnapshotMeta returns metadata about the state snapshot most 72 // recently created either by a call to PersistState or read by a call 73 // to RefreshState. 74 // 75 // If no persistent snapshot is yet available in the manager then 76 // the return value is meaningless. This method is primarily available 77 // for testing and logging purposes, and is of little use otherwise. 78 StateSnapshotMeta() SnapshotMeta 79 } 80 81 // SnapshotMeta contains metadata about a persisted state snapshot. 82 // 83 // This metadata is usually (but not necessarily) included as part of the 84 // "header" of a state file, which is then written to a raw blob storage medium 85 // by a persistent state manager. 86 // 87 // Not all state managers will have useful values for all fields in this 88 // struct, so SnapshotMeta values are of little use beyond testing and logging 89 // use-cases. 90 type SnapshotMeta struct { 91 // Lineage and Serial can be used to understand the relationships between 92 // snapshots. 93 // 94 // If two snapshots both have an identical, non-empty Lineage 95 // then the one with the higher Serial is newer than the other. 96 // If the Lineage values are different or empty then the two snapshots 97 // are unrelated and cannot be compared for relative age. 98 Lineage string 99 Serial uint64 100 101 // TerraformVersion is the number of the version of Terraform that created 102 // the snapshot. 103 TerraformVersion *version.Version 104 }