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 \f
  31 /* Formatting server IDs and cluster IDs for use in human-readable logs.  Do
  32  * not use these in cases where the whole server or cluster ID is needed; use
  33  * UUID_FMT and UUID_ARGS in that case.*/
  34
  35 #define SID_FMT "%04x"
  36 #define SID_ARGS(SID) uuid_prefix(SID, 4)
  37 #define SID_LEN 4
  38
  39 #define CID_FMT "%04x"
  40 #define CID_ARGS(CID) uuid_prefix(CID, 4)
  41 #define CID_LEN 4
  42 \f
  43 struct ovsdb_error *raft_address_validate(const char *address)
  44     OVS_WARN_UNUSED_RESULT;
  45 struct ovsdb_error *raft_addresses_from_json(const struct json *,
  46                                              struct sset *addresses)
  47     OVS_WARN_UNUSED_RESULT;
  48 struct json *raft_addresses_to_json(const struct sset *addresses);
  49
  50 char *raft_address_to_nickname(const char *address, const struct uuid *sid);
  51 \f
  52 enum raft_server_phase {
  53     RAFT_PHASE_STABLE,          /* Not being changed. */
  54
  55     /* Phases for servers being added. */
  56     RAFT_PHASE_CATCHUP,         /* Populating new server's log. */
  57     RAFT_PHASE_CAUGHT_UP,       /* Waiting for prev configuration to commit. */
  58     RAFT_PHASE_COMMITTING,      /* Waiting for new configuration to commit. */
  59
  60     /* Phases for servers to be removed. */
  61     RAFT_PHASE_REMOVE,          /* To be removed. */
  62 };
  63
  64 const char *raft_server_phase_to_string(enum raft_server_phase);
  65
  66 /* Information about a server in a Raft cluster.
  67  *
  68  * Often within struct raft's 'servers' or 'add_servers' hmap. */
  69 struct raft_server {
  70     struct hmap_node hmap_node; /* Hashed based on 'sid'. */
  71
  72     struct uuid sid;            /* Unique Server ID. */
  73     char *address;              /* "(tcp|ssl):1.2.3.4:5678" */
  74     char *nickname;             /* "1ab3(s3)" */
  75
  76     /* Volatile state on candidates.  Reinitialized at start of election. */
  77     struct uuid vote;           /* Server ID of vote, or all-zeros. */
  78
  79     /* Volatile state on leaders.  Reinitialized after election. */
  80     uint64_t next_index;     /* Index of next log entry to send this server. */
  81     uint64_t match_index;    /* Index of max log entry server known to have. */
  82     enum raft_server_phase phase;
  83     /* For use in adding and removing servers: */
  84     struct uuid requester_sid;  /* Nonzero if requested via RPC. */
  85     struct unixctl_conn *requester_conn; /* Only if requested via unixctl. */
  86 };
  87
  88 void raft_server_destroy(struct raft_server *);
  89 void raft_servers_destroy(struct hmap *servers);
  90 struct raft_server *raft_server_add(struct hmap *servers,
  91                                     const struct uuid *sid,
  92                                     const char *address);
  93 struct raft_server *raft_server_find(const struct hmap *servers,
  94                                      const struct uuid *sid);
  95 const char *raft_servers_get_nickname__(const struct hmap *servers,
  96                                         const struct uuid *sid);
  97 const char *raft_servers_get_nickname(const struct hmap *servers,
  98                                       const struct uuid *sid,
  99                                       char buf[SID_LEN + 1], size_t bufsize);
 100 struct ovsdb_error *raft_servers_from_json(const struct json *,
 101                                            struct hmap *servers)
 102     OVS_WARN_UNUSED_RESULT;
 103 struct ovsdb_error *raft_servers_validate_json(const struct json *);
 104     OVS_WARN_UNUSED_RESULT
 105 struct json *raft_servers_to_json(const struct hmap *servers);
 106 void raft_servers_format(const struct hmap *servers, struct ds *ds);
 107 \f
 108 /* A raft_entry is an in-memory data structure that represents a Raft log
 109  * entry.  */
 110 struct raft_entry {
 111     uint64_t term;
 112     struct json *data;
 113     struct uuid eid;
 114     struct json *servers;
 115 };
 116
 117 void raft_entry_clone(struct raft_entry *, const struct raft_entry *);
 118 void raft_entry_uninit(struct raft_entry *);
 119 struct json *raft_entry_to_json(const struct raft_entry *);
 120 struct ovsdb_error *raft_entry_from_json(struct json *, struct raft_entry *)
 121     OVS_WARN_UNUSED_RESULT;
 122 bool raft_entry_equals(const struct raft_entry *, const struct raft_entry *);
 123 \f
 124 /* On disk data serialization and deserialization. */
 125
 126 /* First record in a Raft log. */
 127 struct raft_header {
 128     /* All servers. */
 129     struct uuid sid;            /* Server ID. */
 130     struct uuid cid;            /* Cluster ID.  May be zero if 'joining'. */
 131     char *name;                 /* Database name. */
 132     char *local_address;        /* Address for Raft server to listen. */
 133     bool joining;               /* True iff cluster not joined yet. */
 134
 135     /* Only for servers that haven't joined the cluster yet. */
 136     struct sset remote_addresses; /* Address of other Raft servers. */
 137
 138     /* Only for servers that have joined the cluster. */
 139     uint64_t snap_index;        /* Snapshot's index. */
 140     struct raft_entry snap;     /* Snapshot. */
 141 };
 142
 143 void raft_header_uninit(struct raft_header *);
 144 struct ovsdb_error *raft_header_from_json(struct raft_header *,
 145                                           const struct json *)
 146     OVS_WARN_UNUSED_RESULT;
 147 struct json *raft_header_to_json(const struct raft_header *);
 148
 149 enum raft_record_type {
 150     /* Record types that match those in the Raft specification. */
 151     RAFT_REC_ENTRY,             /* A log entry. */
 152     RAFT_REC_TERM,              /* A new term. */
 153     RAFT_REC_VOTE,              /* A vote. */
 154
 155     /* Extensions. */
 156     RAFT_REC_NOTE,              /* A note about some significant event. */
 157     RAFT_REC_COMMIT_INDEX,      /* An update to the local commit_index. */
 158     RAFT_REC_LEADER,            /* A server has become leader for this term. */
 159 };
 160
 161 /* Type used for the second and subsequent records in a Raft log. */
 162 struct raft_record {
 163     enum raft_record_type type;
 164     char *comment;
 165
 166     /* Valid in RAFT_REC_ENTRY, RAFT_REC_TERM, RAFT_REC_LEADER, and
 167      * RAFT_REC_VOTE, and otherwise 0. */
 168     uint64_t term;
 169
 170     union {
 171         char *note;             /* RAFT_REC_NOTE. */
 172
 173         uint64_t commit_index;  /* RAFT_REC_COMMIT_INDEX. */
 174
 175         struct uuid sid;        /* RAFT_REC_VOTE, RAFT_REC_LEADER. */
 176
 177         struct {                /* RAFT_REC_ENTRY. */
 178             uint64_t index;
 179             struct json *data;
 180             struct json *servers;
 181             struct uuid eid;
 182         } entry;
 183     };
 184 };
 185
 186 void raft_record_uninit(struct raft_record *);
 187 struct ovsdb_error *raft_record_from_json(struct raft_record *,
 188                                           const struct json *)
 189     OVS_WARN_UNUSED_RESULT;
 190 struct json *raft_record_to_json(const struct raft_record *);
 191 \f
 192 void raft_put_uint64(struct json *object, const char *name, uint64_t integer);
 193 uint64_t raft_parse_optional_uint64(struct ovsdb_parser *, const char *name);
 194 uint64_t raft_parse_required_uint64(struct ovsdb_parser *, const char *name);
 195
 196 bool raft_parse_required_boolean(struct ovsdb_parser *, const char *name);
 197 int raft_parse_optional_boolean(struct ovsdb_parser *, const char *name);
 198 const char *raft_parse_required_string(struct ovsdb_parser *,
 199                                            const char *name);
 200 const char *raft_parse_optional_string(struct ovsdb_parser *,
 201                                            const char *name);
 202 bool raft_parse_uuid(struct ovsdb_parser *, const char *name, bool optional,
 203                      struct uuid *);
 204 struct uuid raft_parse_required_uuid(struct ovsdb_parser *, const char *name);
 205 bool raft_parse_optional_uuid(struct ovsdb_parser *, const char *name,
 206                          struct uuid *);
 207
 208 #endif /* raft-private.h */