ovsdb/raft-private.h

   1 /*
   2  * Copyright (c) 2017, 2018 Nicira, Inc.
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the "License");
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at:
   7  *
   8  *     http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17 #ifndef RAFT_PRIVATE_H
  18 #define RAFT_PRIVATE_H 1
  19
  20 /* Data structures for use internally within the Raft implementation. */
  21
  22 #include "raft.h"
  23 #include <stdint.h>
  24 #include "openvswitch/hmap.h"
  25 #include "openvswitch/uuid.h"
  26 #include "sset.h"
  27
  28 struct ds;
  29 struct ovsdb_parser;
  30 struct raft_install_snapshot_request;
  31 \f
  32 /* Formatting server IDs and cluster IDs for use in human-readable logs.  Do
  33  * not use these in cases where the whole server or cluster ID is needed; use
  34  * UUID_FMT and UUID_ARGS in that case.*/
  35
  36 #define SID_FMT "%04x"
  37 #define SID_ARGS(SID) uuid_prefix(SID, 4)
  38 #define SID_LEN 4
  39
  40 #define CID_FMT "%04x"
  41 #define CID_ARGS(CID) uuid_prefix(CID, 4)
  42 #define CID_LEN 4
  43 \f
  44 struct ovsdb_error *raft_address_validate(const char *address)
  45     OVS_WARN_UNUSED_RESULT;
  46 struct ovsdb_error *raft_addresses_from_json(const struct json *,
  47                                              struct sset *addresses)
  48     OVS_WARN_UNUSED_RESULT;
  49 struct json *raft_addresses_to_json(const struct sset *addresses);
  50
  51 char *raft_address_to_nickname(const char *address, const struct uuid *sid);
  52 \f
  53 enum raft_server_phase {
  54     RAFT_PHASE_STABLE,          /* Not being changed. */
  55
  56     /* Phases for servers being added. */
  57     RAFT_PHASE_CATCHUP,         /* Populating new server's log. */
  58     RAFT_PHASE_CAUGHT_UP,       /* Waiting for prev configuration to commit. */
  59     RAFT_PHASE_COMMITTING,      /* Waiting for new configuration to commit. */
  60
  61     /* Phases for servers to be removed. */
  62     RAFT_PHASE_REMOVE,          /* To be removed. */
  63 };
  64
  65 const char *raft_server_phase_to_string(enum raft_server_phase);
  66
  67 /* Information about a server in a Raft cluster.
  68  *
  69  * Often within struct raft's 'servers' or 'add_servers' hmap. */
  70 struct raft_server {
  71     struct hmap_node hmap_node; /* Hashed based on 'sid'. */
  72
  73     struct uuid sid;            /* Unique Server ID. */
  74     char *address;              /* "(tcp|ssl):1.2.3.4:5678" */
  75     char *nickname;             /* "1ab3(s3)" */
  76
  77     /* Volatile state on candidates.  Reinitialized at start of election. */
  78     struct uuid vote;           /* Server ID of vote, or all-zeros. */
  79
  80     /* Volatile state on leaders.  Reinitialized after election. */
  81     uint64_t next_index;     /* Index of next log entry to send this server. */
  82     uint64_t match_index;    /* Index of max log entry server known to have. */
  83     enum raft_server_phase phase;
  84     bool replied;            /* Reply to append_request was received from this
  85                                 node during current election_timeout interval.
  86                                 */
  87     /* Copy of the last install_snapshot_request sent to this server. */
  88     struct raft_install_snapshot_request *last_install_snapshot_request;
  89
  90     /* For use in adding and removing servers: */
  91     struct uuid requester_sid;  /* Nonzero if requested via RPC. */
  92     struct unixctl_conn *requester_conn; /* Only if requested via unixctl. */
  93 };
  94
  95 void raft_server_destroy(struct raft_server *);
  96 void raft_servers_destroy(struct hmap *servers);
  97 struct raft_server *raft_server_add(struct hmap *servers,
  98                                     const struct uuid *sid,
  99                                     const char *address);
 100 struct raft_server *raft_server_find(const struct hmap *servers,
 101                                      const struct uuid *sid);
 102 const char *raft_servers_get_nickname__(const struct hmap *servers,
 103                                         const struct uuid *sid);
 104 const char *raft_servers_get_nickname(const struct hmap *servers,
 105                                       const struct uuid *sid,
 106                                       char buf[SID_LEN + 1], size_t bufsize);
 107 struct ovsdb_error *raft_servers_from_json(const struct json *,
 108                                            struct hmap *servers)
 109     OVS_WARN_UNUSED_RESULT;
 110 struct ovsdb_error *raft_servers_validate_json(const struct json *);
 111     OVS_WARN_UNUSED_RESULT
 112 struct json *raft_servers_to_json(const struct hmap *servers);
 113 void raft_servers_format(const struct hmap *servers, struct ds *ds);
 114 \f
 115 /* A raft_entry is an in-memory data structure that represents a Raft log
 116  * entry.  */
 117 struct raft_entry {
 118     uint64_t term;
 119     struct json *data;
 120     struct uuid eid;
 121     struct json *servers;
 122     uint64_t election_timer;
 123 };
 124
 125 void raft_entry_clone(struct raft_entry *, const struct raft_entry *);
 126 void raft_entry_uninit(struct raft_entry *);
 127 struct json *raft_entry_to_json(const struct raft_entry *);
 128 struct ovsdb_error *raft_entry_from_json(struct json *, struct raft_entry *)
 129     OVS_WARN_UNUSED_RESULT;
 130 bool raft_entry_equals(const struct raft_entry *, const struct raft_entry *);
 131 \f
 132 /* On disk data serialization and deserialization. */
 133
 134 /* First record in a Raft log. */
 135 struct raft_header {
 136     /* All servers. */
 137     struct uuid sid;            /* Server ID. */
 138     struct uuid cid;            /* Cluster ID.  May be zero if 'joining'. */
 139     char *name;                 /* Database name. */
 140     char *local_address;        /* Address for Raft server to listen. */
 141     bool joining;               /* True iff cluster not joined yet. */
 142
 143     /* Only for servers that haven't joined the cluster yet. */
 144     struct sset remote_addresses; /* Address of other Raft servers. */
 145
 146     /* Only for servers that have joined the cluster. */
 147     uint64_t snap_index;        /* Snapshot's index. */
 148     struct raft_entry snap;     /* Snapshot. */
 149 };
 150
 151 void raft_header_uninit(struct raft_header *);
 152 struct ovsdb_error *raft_header_from_json(struct raft_header *,
 153                                           const struct json *)
 154     OVS_WARN_UNUSED_RESULT;
 155 struct json *raft_header_to_json(const struct raft_header *);
 156
 157 enum raft_record_type {
 158     /* Record types that match those in the Raft specification. */
 159     RAFT_REC_ENTRY,             /* A log entry. */
 160     RAFT_REC_TERM,              /* A new term. */
 161     RAFT_REC_VOTE,              /* A vote. */
 162
 163     /* Extensions. */
 164     RAFT_REC_NOTE,              /* A note about some significant event. */
 165     RAFT_REC_COMMIT_INDEX,      /* An update to the local commit_index. */
 166     RAFT_REC_LEADER,            /* A server has become leader for this term. */
 167 };
 168
 169 /* Type used for the second and subsequent records in a Raft log. */
 170 struct raft_record {
 171     enum raft_record_type type;
 172     char *comment;
 173
 174     /* Valid in RAFT_REC_ENTRY, RAFT_REC_TERM, RAFT_REC_LEADER, and
 175      * RAFT_REC_VOTE, and otherwise 0. */
 176     uint64_t term;
 177
 178     union {
 179         char *note;             /* RAFT_REC_NOTE. */
 180
 181         uint64_t commit_index;  /* RAFT_REC_COMMIT_INDEX. */
 182
 183         struct uuid sid;        /* RAFT_REC_VOTE, RAFT_REC_LEADER. */
 184
 185         struct {                /* RAFT_REC_ENTRY. */
 186             uint64_t index;
 187             struct json *data;
 188             struct json *servers;
 189             uint64_t election_timer;
 190             struct uuid eid;
 191         } entry;
 192     };
 193 };
 194
 195 void raft_record_uninit(struct raft_record *);
 196 struct ovsdb_error *raft_record_from_json(struct raft_record *,
 197                                           const struct json *)
 198     OVS_WARN_UNUSED_RESULT;
 199 struct json *raft_record_to_json(const struct raft_record *);
 200 \f
 201 void raft_put_uint64(struct json *object, const char *name, uint64_t integer);
 202 uint64_t raft_parse_optional_uint64(struct ovsdb_parser *, const char *name);
 203 uint64_t raft_parse_required_uint64(struct ovsdb_parser *, const char *name);
 204
 205 bool raft_parse_required_boolean(struct ovsdb_parser *, const char *name);
 206 int raft_parse_optional_boolean(struct ovsdb_parser *, const char *name);
 207 const char *raft_parse_required_string(struct ovsdb_parser *,
 208                                            const char *name);
 209 const char *raft_parse_optional_string(struct ovsdb_parser *,
 210                                            const char *name);
 211 bool raft_parse_uuid(struct ovsdb_parser *, const char *name, bool optional,
 212                      struct uuid *);
 213 struct uuid raft_parse_required_uuid(struct ovsdb_parser *, const char *name);
 214 bool raft_parse_optional_uuid(struct ovsdb_parser *, const char *name,
 215                          struct uuid *);
 216
 217 #endif /* raft-private.h */