Merge "Address comment in gerrit 17266"
[controller.git] / opendaylight / md-sal / sal-akka-raft / src / main / java / org / opendaylight / controller / cluster / raft / RaftActor.java
1 /*
2  * Copyright (c) 2014 Cisco Systems, Inc. and others.  All rights reserved.
3  * Copyright (c) 2015 Brocade Communications Systems, Inc. and others.  All rights reserved.
4  *
5  * This program and the accompanying materials are made available under the
6  * terms of the Eclipse Public License v1.0 which accompanies this distribution,
7  * and is available at http://www.eclipse.org/legal/epl-v10.html
8  */
9
10 package org.opendaylight.controller.cluster.raft;
11
12 import akka.actor.ActorRef;
13 import akka.actor.ActorSelection;
14 import akka.japi.Procedure;
15 import akka.persistence.SnapshotSelectionCriteria;
16 import com.google.common.annotations.VisibleForTesting;
17 import com.google.common.base.Objects;
18 import com.google.common.base.Optional;
19 import com.google.common.collect.ImmutableMap;
20 import com.google.common.collect.Lists;
21 import java.io.Serializable;
22 import java.util.Collection;
23 import java.util.List;
24 import java.util.Map;
25 import java.util.concurrent.TimeUnit;
26 import javax.annotation.Nonnull;
27 import org.apache.commons.lang3.time.DurationFormatUtils;
28 import org.opendaylight.controller.cluster.DataPersistenceProvider;
29 import org.opendaylight.controller.cluster.DelegatingPersistentDataProvider;
30 import org.opendaylight.controller.cluster.NonPersistentDataProvider;
31 import org.opendaylight.controller.cluster.PersistentDataProvider;
32 import org.opendaylight.controller.cluster.common.actor.AbstractUntypedPersistentActor;
33 import org.opendaylight.controller.cluster.notifications.LeaderStateChanged;
34 import org.opendaylight.controller.cluster.notifications.RoleChanged;
35 import org.opendaylight.controller.cluster.raft.base.messages.ApplyJournalEntries;
36 import org.opendaylight.controller.cluster.raft.base.messages.ApplyState;
37 import org.opendaylight.controller.cluster.raft.base.messages.Replicate;
38 import org.opendaylight.controller.cluster.raft.behaviors.AbstractLeader;
39 import org.opendaylight.controller.cluster.raft.behaviors.DelegatingRaftActorBehavior;
40 import org.opendaylight.controller.cluster.raft.behaviors.Follower;
41 import org.opendaylight.controller.cluster.raft.behaviors.RaftActorBehavior;
42 import org.opendaylight.controller.cluster.raft.client.messages.FindLeader;
43 import org.opendaylight.controller.cluster.raft.client.messages.FindLeaderReply;
44 import org.opendaylight.controller.cluster.raft.client.messages.FollowerInfo;
45 import org.opendaylight.controller.cluster.raft.client.messages.GetOnDemandRaftState;
46 import org.opendaylight.controller.cluster.raft.client.messages.OnDemandRaftState;
47 import org.opendaylight.controller.cluster.raft.protobuff.client.messages.Payload;
48 import org.slf4j.Logger;
49 import org.slf4j.LoggerFactory;
50
51 /**
52  * RaftActor encapsulates a state machine that needs to be kept synchronized
53  * in a cluster. It implements the RAFT algorithm as described in the paper
54  * <a href='https://ramcloud.stanford.edu/wiki/download/attachments/11370504/raft.pdf'>
55  * In Search of an Understandable Consensus Algorithm</a>
56  * <p/>
57  * RaftActor has 3 states and each state has a certain behavior associated
58  * with it. A Raft actor can behave as,
59  * <ul>
60  * <li> A Leader </li>
61  * <li> A Follower (or) </li>
62  * <li> A Candidate </li>
63  * </ul>
64  * <p/>
65  * <p/>
66  * A RaftActor MUST be a Leader in order to accept requests from clients to
67  * change the state of it's encapsulated state machine. Once a RaftActor becomes
68  * a Leader it is also responsible for ensuring that all followers ultimately
69  * have the same log and therefore the same state machine as itself.
70  * <p/>
71  * <p/>
72  * The current behavior of a RaftActor determines how election for leadership
73  * is initiated and how peer RaftActors react to request for votes.
74  * <p/>
75  * <p/>
76  * Each RaftActor also needs to know the current election term. It uses this
77  * information for a couple of things. One is to simply figure out who it
78  * voted for in the last election. Another is to figure out if the message
79  * it received to update it's state is stale.
80  * <p/>
81  * <p/>
82  * The RaftActor uses akka-persistence to store it's replicated log.
83  * Furthermore through it's behaviors a Raft Actor determines
84  * <p/>
85  * <ul>
86  * <li> when a log entry should be persisted </li>
87  * <li> when a log entry should be applied to the state machine (and) </li>
88  * <li> when a snapshot should be saved </li>
89  * </ul>
90  */
91 public abstract class RaftActor extends AbstractUntypedPersistentActor {
92
93     private static final long APPLY_STATE_DELAY_THRESHOLD_IN_NANOS = TimeUnit.MILLISECONDS.toNanos(50L); // 50 millis
94
95     protected final Logger LOG = LoggerFactory.getLogger(getClass());
96
97     /**
98      * The current state determines the current behavior of a RaftActor
99      * A Raft Actor always starts off in the Follower State
100      */
101     private final DelegatingRaftActorBehavior currentBehavior = new DelegatingRaftActorBehavior();
102
103     /**
104      * This context should NOT be passed directly to any other actor it is
105      * only to be consumed by the RaftActorBehaviors
106      */
107     private final RaftActorContextImpl context;
108
109     private final DelegatingPersistentDataProvider delegatingPersistenceProvider = new DelegatingPersistentDataProvider(null);
110
111     private RaftActorRecoverySupport raftRecovery;
112
113     private RaftActorSnapshotMessageSupport snapshotSupport;
114
115     private final BehaviorStateHolder reusableBehaviorStateHolder = new BehaviorStateHolder();
116
117     public RaftActor(String id, Map<String, String> peerAddresses) {
118         this(id, peerAddresses, Optional.<ConfigParams>absent());
119     }
120
121     public RaftActor(String id, Map<String, String> peerAddresses,
122          Optional<ConfigParams> configParams) {
123
124         context = new RaftActorContextImpl(this.getSelf(),
125             this.getContext(), id, new ElectionTermImpl(delegatingPersistenceProvider, id, LOG),
126             -1, -1, peerAddresses,
127             (configParams.isPresent() ? configParams.get(): new DefaultConfigParamsImpl()),
128             delegatingPersistenceProvider, LOG);
129
130         context.setReplicatedLog(ReplicatedLogImpl.newInstance(context, delegatingPersistenceProvider, currentBehavior));
131     }
132
133     @Override
134     public void preStart() throws Exception {
135         LOG.info("Starting recovery for {} with journal batch size {}", persistenceId(),
136                 context.getConfigParams().getJournalRecoveryLogBatchSize());
137
138         super.preStart();
139
140         snapshotSupport = newRaftActorSnapshotMessageSupport();
141     }
142
143     @Override
144     public void postStop() {
145         if(currentBehavior.getDelegate() != null) {
146             try {
147                 currentBehavior.close();
148             } catch (Exception e) {
149                 LOG.debug("{}: Error closing behavior {}", persistenceId(), currentBehavior.state());
150             }
151         }
152
153         super.postStop();
154     }
155
156     @Override
157     public void handleRecover(Object message) {
158         if(raftRecovery == null) {
159             raftRecovery = newRaftActorRecoverySupport();
160         }
161
162         boolean recoveryComplete = raftRecovery.handleRecoveryMessage(message);
163         if(recoveryComplete) {
164             if(!persistence().isRecoveryApplicable()) {
165                 // Delete all the messages from the akka journal so that we do not end up with consistency issues
166                 // Note I am not using the dataPersistenceProvider and directly using the akka api here
167                 deleteMessages(lastSequenceNr());
168
169                 // Delete all the akka snapshots as they will not be needed
170                 deleteSnapshots(new SnapshotSelectionCriteria(scala.Long.MaxValue(), scala.Long.MaxValue()));
171             }
172
173             onRecoveryComplete();
174
175             initializeBehavior();
176
177             raftRecovery = null;
178         }
179     }
180
181     protected RaftActorRecoverySupport newRaftActorRecoverySupport() {
182         return new RaftActorRecoverySupport(delegatingPersistenceProvider, context, currentBehavior,
183                 getRaftActorRecoveryCohort());
184     }
185
186     protected void initializeBehavior(){
187         changeCurrentBehavior(new Follower(context));
188     }
189
190     protected void changeCurrentBehavior(RaftActorBehavior newBehavior){
191         reusableBehaviorStateHolder.init(getCurrentBehavior());
192         setCurrentBehavior(newBehavior);
193         handleBehaviorChange(reusableBehaviorStateHolder, getCurrentBehavior());
194     }
195
196     @Override
197     public void handleCommand(Object message) {
198         if (message instanceof ApplyState){
199             ApplyState applyState = (ApplyState) message;
200
201             long elapsedTime = (System.nanoTime() - applyState.getStartTime());
202             if(elapsedTime >= APPLY_STATE_DELAY_THRESHOLD_IN_NANOS){
203                 LOG.warn("ApplyState took more time than expected. Elapsed Time = {} ms ApplyState = {}",
204                         TimeUnit.NANOSECONDS.toMillis(elapsedTime), applyState);
205             }
206
207             if(LOG.isDebugEnabled()) {
208                 LOG.debug("{}: Applying state for log index {} data {}",
209                     persistenceId(), applyState.getReplicatedLogEntry().getIndex(),
210                     applyState.getReplicatedLogEntry().getData());
211             }
212
213             applyState(applyState.getClientActor(), applyState.getIdentifier(),
214                 applyState.getReplicatedLogEntry().getData());
215
216         } else if (message instanceof ApplyJournalEntries){
217             ApplyJournalEntries applyEntries = (ApplyJournalEntries) message;
218             if(LOG.isDebugEnabled()) {
219                 LOG.debug("{}: Persisting ApplyLogEntries with index={}", persistenceId(), applyEntries.getToIndex());
220             }
221
222             persistence().persist(applyEntries, NoopProcedure.instance());
223
224         } else if (message instanceof FindLeader) {
225             getSender().tell(
226                 new FindLeaderReply(getLeaderAddress()),
227                 getSelf()
228             );
229         } else if(message instanceof GetOnDemandRaftState) {
230             onGetOnDemandRaftStats();
231         } else if(!snapshotSupport.handleSnapshotMessage(message)) {
232             reusableBehaviorStateHolder.init(getCurrentBehavior());
233
234             setCurrentBehavior(currentBehavior.handleMessage(getSender(), message));
235
236             handleBehaviorChange(reusableBehaviorStateHolder, getCurrentBehavior());
237         }
238     }
239
240     protected RaftActorSnapshotMessageSupport newRaftActorSnapshotMessageSupport() {
241         return new RaftActorSnapshotMessageSupport(delegatingPersistenceProvider, context,
242                 currentBehavior, getRaftActorSnapshotCohort());
243     }
244
245     private void onGetOnDemandRaftStats() {
246         // Debugging message to retrieve raft stats.
247
248         OnDemandRaftState.Builder builder = OnDemandRaftState.builder()
249                 .commitIndex(context.getCommitIndex())
250                 .currentTerm(context.getTermInformation().getCurrentTerm())
251                 .inMemoryJournalDataSize(replicatedLog().dataSize())
252                 .inMemoryJournalLogSize(replicatedLog().size())
253                 .isSnapshotCaptureInitiated(context.getSnapshotManager().isCapturing())
254                 .lastApplied(context.getLastApplied())
255                 .lastIndex(replicatedLog().lastIndex())
256                 .lastTerm(replicatedLog().lastTerm())
257                 .leader(getLeaderId())
258                 .raftState(currentBehavior.state().toString())
259                 .replicatedToAllIndex(currentBehavior.getReplicatedToAllIndex())
260                 .snapshotIndex(replicatedLog().getSnapshotIndex())
261                 .snapshotTerm(replicatedLog().getSnapshotTerm())
262                 .votedFor(context.getTermInformation().getVotedFor())
263                 .peerAddresses(ImmutableMap.copyOf(context.getPeerAddresses()));
264
265         ReplicatedLogEntry lastLogEntry = getLastLogEntry();
266         if (lastLogEntry != null) {
267             builder.lastLogIndex(lastLogEntry.getIndex());
268             builder.lastLogTerm(lastLogEntry.getTerm());
269         }
270
271         if(getCurrentBehavior() instanceof AbstractLeader) {
272             AbstractLeader leader = (AbstractLeader)getCurrentBehavior();
273             Collection<String> followerIds = leader.getFollowerIds();
274             List<FollowerInfo> followerInfoList = Lists.newArrayListWithCapacity(followerIds.size());
275             for(String id: followerIds) {
276                 final FollowerLogInformation info = leader.getFollower(id);
277                 followerInfoList.add(new FollowerInfo(id, info.getNextIndex(), info.getMatchIndex(),
278                         info.isFollowerActive(), DurationFormatUtils.formatDurationHMS(info.timeSinceLastActivity())));
279             }
280
281             builder.followerInfoList(followerInfoList);
282         }
283
284         sender().tell(builder.build(), self());
285
286     }
287
288     private void handleBehaviorChange(BehaviorStateHolder oldBehaviorState, RaftActorBehavior currentBehavior) {
289         RaftActorBehavior oldBehavior = oldBehaviorState.getBehavior();
290
291         if (oldBehavior != currentBehavior){
292             onStateChanged();
293         }
294
295         String oldBehaviorLeaderId = oldBehavior == null ? null : oldBehaviorState.getLeaderId();
296         String oldBehaviorStateName = oldBehavior == null ? null : oldBehavior.state().name();
297
298         // it can happen that the state has not changed but the leader has changed.
299         Optional<ActorRef> roleChangeNotifier = getRoleChangeNotifier();
300         if(!Objects.equal(oldBehaviorLeaderId, currentBehavior.getLeaderId())) {
301             if(roleChangeNotifier.isPresent()) {
302                 roleChangeNotifier.get().tell(new LeaderStateChanged(getId(), currentBehavior.getLeaderId()), getSelf());
303             }
304
305             onLeaderChanged(oldBehaviorLeaderId, currentBehavior.getLeaderId());
306         }
307
308         if (roleChangeNotifier.isPresent() &&
309                 (oldBehavior == null || (oldBehavior.state() != currentBehavior.state()))) {
310             roleChangeNotifier.get().tell(new RoleChanged(getId(), oldBehaviorStateName ,
311                     currentBehavior.state().name()), getSelf());
312         }
313     }
314
315     /**
316      * When a derived RaftActor needs to persist something it must call
317      * persistData.
318      *
319      * @param clientActor
320      * @param identifier
321      * @param data
322      */
323     protected void persistData(final ActorRef clientActor, final String identifier,
324         final Payload data) {
325
326         ReplicatedLogEntry replicatedLogEntry = new ReplicatedLogImplEntry(
327             context.getReplicatedLog().lastIndex() + 1,
328             context.getTermInformation().getCurrentTerm(), data);
329
330         if(LOG.isDebugEnabled()) {
331             LOG.debug("{}: Persist data {}", persistenceId(), replicatedLogEntry);
332         }
333
334         final RaftActorContext raftContext = getRaftActorContext();
335
336         replicatedLog().appendAndPersist(replicatedLogEntry, new Procedure<ReplicatedLogEntry>() {
337             @Override
338             public void apply(ReplicatedLogEntry replicatedLogEntry) throws Exception {
339                 if(!hasFollowers()){
340                     // Increment the Commit Index and the Last Applied values
341                     raftContext.setCommitIndex(replicatedLogEntry.getIndex());
342                     raftContext.setLastApplied(replicatedLogEntry.getIndex());
343
344                     // Apply the state immediately
345                     applyState(clientActor, identifier, data);
346
347                     // Send a ApplyJournalEntries message so that we write the fact that we applied
348                     // the state to durable storage
349                     self().tell(new ApplyJournalEntries(replicatedLogEntry.getIndex()), self());
350
351                     context.getSnapshotManager().trimLog(context.getLastApplied(), currentBehavior);
352
353                 } else if (clientActor != null) {
354                     // Send message for replication
355                     currentBehavior.handleMessage(getSelf(),
356                             new Replicate(clientActor, identifier, replicatedLogEntry));
357                 }
358             }
359         });
360     }
361
362     private ReplicatedLog replicatedLog() {
363         return context.getReplicatedLog();
364     }
365
366     protected String getId() {
367         return context.getId();
368     }
369
370     @VisibleForTesting
371     void setCurrentBehavior(RaftActorBehavior behavior) {
372         currentBehavior.setDelegate(behavior);
373     }
374
375     protected RaftActorBehavior getCurrentBehavior() {
376         return currentBehavior.getDelegate();
377     }
378
379     /**
380      * Derived actors can call the isLeader method to check if the current
381      * RaftActor is the Leader or not
382      *
383      * @return true it this RaftActor is a Leader false otherwise
384      */
385     protected boolean isLeader() {
386         return context.getId().equals(currentBehavior.getLeaderId());
387     }
388
389     /**
390      * Derived actor can call getLeader if they need a reference to the Leader.
391      * This would be useful for example in forwarding a request to an actor
392      * which is the leader
393      *
394      * @return A reference to the leader if known, null otherwise
395      */
396     protected ActorSelection getLeader(){
397         String leaderAddress = getLeaderAddress();
398
399         if(leaderAddress == null){
400             return null;
401         }
402
403         return context.actorSelection(leaderAddress);
404     }
405
406     /**
407      *
408      * @return the current leader's id
409      */
410     protected String getLeaderId(){
411         return currentBehavior.getLeaderId();
412     }
413
414     protected RaftState getRaftState() {
415         return currentBehavior.state();
416     }
417
418     protected ReplicatedLogEntry getLastLogEntry() {
419         return replicatedLog().last();
420     }
421
422     protected Long getCurrentTerm(){
423         return context.getTermInformation().getCurrentTerm();
424     }
425
426     protected Long getCommitIndex(){
427         return context.getCommitIndex();
428     }
429
430     protected Long getLastApplied(){
431         return context.getLastApplied();
432     }
433
434     protected RaftActorContext getRaftActorContext() {
435         return context;
436     }
437
438     protected void updateConfigParams(ConfigParams configParams) {
439         context.setConfigParams(configParams);
440     }
441
442     public final DataPersistenceProvider persistence() {
443         return delegatingPersistenceProvider.getDelegate();
444     }
445
446     public void setPersistence(DataPersistenceProvider provider) {
447         delegatingPersistenceProvider.setDelegate(provider);
448     }
449
450     protected void setPersistence(boolean persistent) {
451         if(persistent) {
452             setPersistence(new PersistentDataProvider(this));
453         } else {
454             setPersistence(new NonPersistentDataProvider() {
455                 /**
456                  * The way snapshotting works is,
457                  * <ol>
458                  * <li> RaftActor calls createSnapshot on the Shard
459                  * <li> Shard sends a CaptureSnapshotReply and RaftActor then calls saveSnapshot
460                  * <li> When saveSnapshot is invoked on the akka-persistence API it uses the SnapshotStore to save
461                  * the snapshot. The SnapshotStore sends SaveSnapshotSuccess or SaveSnapshotFailure. When the
462                  * RaftActor gets SaveSnapshot success it commits the snapshot to the in-memory journal. This
463                  * commitSnapshot is mimicking what is done in SaveSnapshotSuccess.
464                  * </ol>
465                  */
466                 @Override
467                 public void saveSnapshot(Object o) {
468                     // Make saving Snapshot successful
469                     // Committing the snapshot here would end up calling commit in the creating state which would
470                     // be a state violation. That's why now we send a message to commit the snapshot.
471                     self().tell(RaftActorSnapshotMessageSupport.COMMIT_SNAPSHOT, self());
472                 }
473             });
474         }
475     }
476
477     /**
478      * setPeerAddress sets the address of a known peer at a later time.
479      * <p>
480      * This is to account for situations where a we know that a peer
481      * exists but we do not know an address up-front. This may also be used in
482      * situations where a known peer starts off in a different location and we
483      * need to change it's address
484      * <p>
485      * Note that if the peerId does not match the list of peers passed to
486      * this actor during construction an IllegalStateException will be thrown.
487      *
488      * @param peerId
489      * @param peerAddress
490      */
491     protected void setPeerAddress(String peerId, String peerAddress){
492         context.setPeerAddress(peerId, peerAddress);
493     }
494
495     /**
496      * The applyState method will be called by the RaftActor when some data
497      * needs to be applied to the actor's state
498      *
499      * @param clientActor A reference to the client who sent this message. This
500      *                    is the same reference that was passed to persistData
501      *                    by the derived actor. clientActor may be null when
502      *                    the RaftActor is behaving as a follower or during
503      *                    recovery.
504      * @param identifier  The identifier of the persisted data. This is also
505      *                    the same identifier that was passed to persistData by
506      *                    the derived actor. identifier may be null when
507      *                    the RaftActor is behaving as a follower or during
508      *                    recovery
509      * @param data        A piece of data that was persisted by the persistData call.
510      *                    This should NEVER be null.
511      */
512     protected abstract void applyState(ActorRef clientActor, String identifier,
513         Object data);
514
515     /**
516      * Returns the RaftActorRecoveryCohort to participate in persistence recovery.
517      */
518     @Nonnull
519     protected abstract RaftActorRecoveryCohort getRaftActorRecoveryCohort();
520
521     /**
522      * This method is called when recovery is complete.
523      */
524     protected abstract void onRecoveryComplete();
525
526     /**
527      * Returns the RaftActorSnapshotCohort to participate in persistence recovery.
528      */
529     @Nonnull
530     protected abstract RaftActorSnapshotCohort getRaftActorSnapshotCohort();
531
532     /**
533      * This method will be called by the RaftActor when the state of the
534      * RaftActor changes. The derived actor can then use methods like
535      * isLeader or getLeader to do something useful
536      */
537     protected abstract void onStateChanged();
538
539     /**
540      * Notifier Actor for this RaftActor to notify when a role change happens
541      * @return ActorRef - ActorRef of the notifier or Optional.absent if none.
542      */
543     protected abstract Optional<ActorRef> getRoleChangeNotifier();
544
545     protected void onLeaderChanged(String oldLeader, String newLeader){};
546
547     private String getLeaderAddress(){
548         if(isLeader()){
549             return getSelf().path().toString();
550         }
551         String leaderId = currentBehavior.getLeaderId();
552         if (leaderId == null) {
553             return null;
554         }
555         String peerAddress = context.getPeerAddress(leaderId);
556         if(LOG.isDebugEnabled()) {
557             LOG.debug("{}: getLeaderAddress leaderId = {} peerAddress = {}",
558                     persistenceId(), leaderId, peerAddress);
559         }
560
561         return peerAddress;
562     }
563
564     protected boolean hasFollowers(){
565         return getRaftActorContext().hasFollowers();
566     }
567
568     /**
569      * @deprecated Deprecated in favor of {@link org.opendaylight.controller.cluster.raft.base.messages.DeleteEntriesTest}
570      *             whose type for fromIndex is long instead of int. This class was kept for backwards
571      *             compatibility with Helium.
572      */
573     @Deprecated
574     static class DeleteEntries implements Serializable {
575         private static final long serialVersionUID = 1L;
576         private final int fromIndex;
577
578         public DeleteEntries(int fromIndex) {
579             this.fromIndex = fromIndex;
580         }
581
582         public int getFromIndex() {
583             return fromIndex;
584         }
585     }
586
587     static class UpdateElectionTerm implements Serializable {
588         private static final long serialVersionUID = 1L;
589         private final long currentTerm;
590         private final String votedFor;
591
592         public UpdateElectionTerm(long currentTerm, String votedFor) {
593             this.currentTerm = currentTerm;
594             this.votedFor = votedFor;
595         }
596
597         public long getCurrentTerm() {
598             return currentTerm;
599         }
600
601         public String getVotedFor() {
602             return votedFor;
603         }
604     }
605
606     private static class BehaviorStateHolder {
607         private RaftActorBehavior behavior;
608         private String leaderId;
609
610         void init(RaftActorBehavior behavior) {
611             this.behavior = behavior;
612             this.leaderId = behavior != null ? behavior.getLeaderId() : null;
613         }
614
615         RaftActorBehavior getBehavior() {
616             return behavior;
617         }
618
619         String getLeaderId() {
620             return leaderId;
621         }
622     }
623 }