github.com/m3db/m3@v1.5.1-0.20231129193456-75a402aa583b/src/m3em/node/types.go (about) 1 // Copyright (c) 2017 Uber Technologies, Inc. 2 // 3 // Permission is hereby granted, free of charge, to any person obtaining a copy 4 // of this software and associated documentation files (the "Software"), to deal 5 // in the Software without restriction, including without limitation the rights 6 // to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 7 // copies of the Software, and to permit persons to whom the Software is 8 // furnished to do so, subject to the following conditions: 9 // 10 // The above copyright notice and this permission notice shall be included in 11 // all copies or substantial portions of the Software. 12 // 13 // THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 14 // IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 15 // FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 16 // AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 17 // LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 18 // OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN 19 // THE SOFTWARE. 20 21 package node 22 23 import ( 24 "time" 25 26 "github.com/m3db/m3/src/cluster/placement" 27 "github.com/m3db/m3/src/m3em/build" 28 hb "github.com/m3db/m3/src/m3em/generated/proto/heartbeat" 29 "github.com/m3db/m3/src/m3em/generated/proto/m3em" 30 xclock "github.com/m3db/m3/src/x/clock" 31 "github.com/m3db/m3/src/x/instrument" 32 xretry "github.com/m3db/m3/src/x/retry" 33 34 "google.golang.org/grpc" 35 ) 36 37 // Status indicates the different states a ServiceNode can be in. The 38 // state diagram below describes the transitions between the various states: 39 // 40 // ┌──────────────────┐ 41 // │ │ 42 // ┌Teardown()─────│ Error │ 43 // │ │ │ 44 // │ └──────────────────┘ 45 // │ 46 // ▼ 47 // ┌──────────────────┐ ┌───────────────-──┐ 48 // │ │ Setup() │ │ 49 // │ Uninitialized ├────────────────────────▶│ Setup │◀─┐ 50 // │ │◀───────────┐ │ │ │ 51 // └──────────────────┘ Teardown()└────────────└──────────────────┘ │ 52 // ▲ │ │ 53 // │ │ │ 54 // │ │ │ 55 // │ Start() │ │ 56 // │ ┌─────────────┘ │ 57 // │ │ │ 58 // │ │ │ 59 // │ │ │ 60 // │ ▼ │ 61 // │ ┌──────────────────┐ │ 62 // │Teardown() │ │ | 63 // └────────────────────│ Running │────────────Stop() 64 // │ │ 65 // └──────────────────┘ 66 type Status int 67 68 const ( 69 // StatusUninitialized refers to the state of an un-initialized node. 70 StatusUninitialized Status = iota 71 72 // StatusSetup is the state of a node which has been Setup() 73 StatusSetup 74 75 // StatusRunning is the state of a node which has been Start()-ed 76 StatusRunning 77 78 // StatusError is the state of a node which is in an Error state 79 StatusError 80 ) 81 82 // RemoteOutputType describes the various outputs available on the remote agents 83 type RemoteOutputType int 84 85 const ( 86 // RemoteProcessStdout refers to the remote process stdout 87 RemoteProcessStdout RemoteOutputType = iota 88 89 // RemoteProcessStderr refers to the remote process stderr 90 RemoteProcessStderr 91 92 // TODO(prateek): capture agent remote logs 93 ) 94 95 // ServiceNode represents an executable service node. This object controls both the service 96 // and resources on the host running the service (e.g. fs, processes, etc.) 97 type ServiceNode interface { 98 placement.Instance 99 100 // Setup initializes the directories, config file, and binary for the process being tested. 101 // It does not Start the process on the ServiceNode. 102 Setup( 103 build build.ServiceBuild, 104 config build.ServiceConfiguration, 105 token string, 106 force bool, 107 ) error 108 109 // Start starts the service process for this ServiceNode. 110 Start() error 111 112 // Stop stops the service process for this ServiceNode. 113 Stop() error 114 115 // Status returns the ServiceNode status. 116 Status() Status 117 118 // Teardown releases any remote resources used for testing. 119 Teardown() error 120 121 // Close releases any locally held resources 122 Close() error 123 124 // RegisterListener registers an event listener 125 RegisterListener(Listener) ListenerID 126 127 // DeregisterListener un-registers an event listener 128 DeregisterListener(ListenerID) 129 130 // TransferLocalFile transfers a local file to the specified destination paths 131 // NB: destPaths are not allowed to use relative path specifiers, i.e. '..' is illegal; 132 // the eventual destination path on remote hosts is relative to the working directory 133 // of the remote agent. 134 // e.g. if the remote agent has working directory /var/m3em-agent, and we make the call: 135 // svcNode.TransferLocalFile("some/local/file/path/id", []string{"path/id", "another/path/id"}) 136 // 137 // upon success, there will be two new files under the remote agent working directory: 138 // /var/m3em-agent/ 139 // /var/m3em-agent/path/id <-- same contents as "some/local/file/path/id" 140 // /var/m3em-agent/another/path/id <-- same contents as "some/local/file/path/id" 141 TransferLocalFile(localSrc string, destPaths []string, overwrite bool) error 142 143 // GetRemoteOutput transfers the specified remote file to the specified path 144 GetRemoteOutput(t RemoteOutputType, localDest string) (truncated bool, err error) 145 } 146 147 // ServiceNodeFn performs an operation on a given ServiceNode 148 type ServiceNodeFn func(ServiceNode) error 149 150 // ConcurrentExecutor executes functions on a collection of service 151 // nodes concurrently 152 type ConcurrentExecutor interface { 153 // Run runs the provide ServiceNodeFn concurrently 154 Run() error 155 } 156 157 // HeartbeatRouter routes heartbeats based on registered servers 158 type HeartbeatRouter interface { 159 hb.HeartbeaterServer 160 161 // Endpoint returns the router endpoint 162 Endpoint() string 163 164 // Register registers the specified server under the given id 165 Register(string, hb.HeartbeaterServer) error 166 167 // Deregister un-registers any server registered under the given id 168 Deregister(string) error 169 } 170 171 // ListenerID is a unique identifier for a registered listener 172 type ListenerID int 173 174 // Listener provides callbacks invoked upon remote process state transitions 175 type Listener interface { 176 // OnProcessTerminate is invoked when the remote process being run terminates 177 OnProcessTerminate(node ServiceNode, desc string) 178 179 // OnHeartbeatTimeout is invoked upon remote heartbeats having timed-out 180 OnHeartbeatTimeout(node ServiceNode, lastHeartbeatTs time.Time) 181 182 // OnOverwrite is invoked if remote agent control is overwritten by another 183 // coordinator 184 OnOverwrite(node ServiceNode, desc string) 185 } 186 187 // ServiceNodes is a collection of ServiceNode(s) 188 type ServiceNodes []ServiceNode 189 190 // Options are the various knobs to control Node behavior 191 type Options interface { 192 // Validate validates the NodeOptions 193 Validate() error 194 195 // SetInstrumentOptions sets the instrumentation options 196 SetInstrumentOptions(instrument.Options) Options 197 198 // InstrumentOptions returns the instrumentation options 199 InstrumentOptions() instrument.Options 200 201 // SetOperationTimeout returns the timeout for node operations 202 SetOperationTimeout(time.Duration) Options 203 204 // OperationTimeout returns the timeout for node operations 205 OperationTimeout() time.Duration 206 207 // SetRetrier sets the retrier for node operations 208 SetRetrier(xretry.Retrier) Options 209 210 // OperationRetrier returns the retrier for node operations 211 Retrier() xretry.Retrier 212 213 // SetTransferBufferSize sets the bytes buffer size used during file transfer 214 SetTransferBufferSize(int) Options 215 216 // TransferBufferSize returns the bytes buffer size used during file transfer 217 TransferBufferSize() int 218 219 // SetMaxPullSize sets the max bytes retrieved from remote agents when 220 // fetching output files 221 SetMaxPullSize(int64) Options 222 223 // MaxPullSize returns the max bytes retrieved from remote agents when 224 // fetching output files 225 MaxPullSize() int64 226 227 // SetHeartbeatOptions sets the HeartbeatOptions 228 SetHeartbeatOptions(HeartbeatOptions) Options 229 230 // HeartbeatOptions returns the HeartbeatOptions 231 HeartbeatOptions() HeartbeatOptions 232 233 // SetOperatorClientFn sets the OperatorClientFn 234 SetOperatorClientFn(OperatorClientFn) Options 235 236 // OperatorClientFn returns the OperatorClientFn 237 OperatorClientFn() OperatorClientFn 238 } 239 240 // OperatorClientFn returns a function able to construct connections to remote Operators 241 type OperatorClientFn func() (*grpc.ClientConn, m3em.OperatorClient, error) 242 243 // HeartbeatOptions are the knobs to control heartbeating behavior 244 type HeartbeatOptions interface { 245 // Validate validates the HeartbeatOptions 246 Validate() error 247 248 // SetEnabled sets whether the Heartbeating is enabled 249 SetEnabled(bool) HeartbeatOptions 250 251 // Enabled returns whether the Heartbeating is enabled 252 Enabled() bool 253 254 // SetNowFn sets the NowFn 255 SetNowFn(xclock.NowFn) HeartbeatOptions 256 257 // NowFn returns the NowFn 258 NowFn() xclock.NowFn 259 260 // SetInterval sets the heartbeating interval 261 SetInterval(time.Duration) HeartbeatOptions 262 263 // Interval returns the heartbeating interval 264 Interval() time.Duration 265 266 // SetCheckInterval sets the frequency with which heartbeating timeouts 267 // are checked 268 SetCheckInterval(time.Duration) HeartbeatOptions 269 270 // CheckInterval returns the frequency with which heartbeating timeouts 271 // are checked 272 CheckInterval() time.Duration 273 274 // SetTimeout sets the heartbeat timeout duration, i.e. the window of 275 // time after which missing heartbeats are considered errorneous 276 SetTimeout(time.Duration) HeartbeatOptions 277 278 // Timeout returns the heartbeat timeout duration, i.e. the window of 279 // time after which missing heartbeats are considered errorneous 280 Timeout() time.Duration 281 282 // SetHeartbeatRouter sets the heartbeat router to be used 283 SetHeartbeatRouter(HeartbeatRouter) HeartbeatOptions 284 285 // HeartbeatRouter returns the heartbeat router in use 286 HeartbeatRouter() HeartbeatRouter 287 }