[mirror_ovs.git] / ovsdb / raft-private.h

/*
 * Copyright (c) 2017, 2018 Nicira, Inc.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at:
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

#ifndef RAFT_PRIVATE_H
#define RAFT_PRIVATE_H 1

/* Data structures for use internally within the Raft implementation. */

#include "raft.h"
#include <stdint.h>
#include "openvswitch/hmap.h"
#include "openvswitch/uuid.h"
#include "sset.h"

struct ds;
struct ovsdb_parser;
\f
/* Formatting server IDs and cluster IDs for use in human-readable logs.  Do
 * not use these in cases where the whole server or cluster ID is needed; use
 * UUID_FMT and UUID_ARGS in that case.*/

#define SID_FMT "%04x"
#define SID_ARGS(SID) uuid_prefix(SID, 4)
#define SID_LEN 4

#define CID_FMT "%04x"
#define CID_ARGS(CID) uuid_prefix(CID, 4)
#define CID_LEN 4
\f
struct ovsdb_error *raft_address_validate(const char *address)
    OVS_WARN_UNUSED_RESULT;
struct ovsdb_error *raft_addresses_from_json(const struct json *,
                                             struct sset *addresses)
    OVS_WARN_UNUSED_RESULT;
struct json *raft_addresses_to_json(const struct sset *addresses);

char *raft_address_to_nickname(const char *address, const struct uuid *sid);
\f
enum raft_server_phase {
    RAFT_PHASE_STABLE,          /* Not being changed. */

    /* Phases for servers being added. */
    RAFT_PHASE_CATCHUP,         /* Populating new server's log. */
    RAFT_PHASE_CAUGHT_UP,       /* Waiting for prev configuration to commit. */
    RAFT_PHASE_COMMITTING,      /* Waiting for new configuration to commit. */

    /* Phases for servers to be removed. */
    RAFT_PHASE_REMOVE,          /* To be removed. */
};

const char *raft_server_phase_to_string(enum raft_server_phase);

/* Information about a server in a Raft cluster.
 *
 * Often within struct raft's 'servers' or 'add_servers' hmap. */
struct raft_server {
    struct hmap_node hmap_node; /* Hashed based on 'sid'. */

    struct uuid sid;            /* Unique Server ID. */
    char *address;              /* "(tcp|ssl):1.2.3.4:5678" */
    char *nickname;             /* "1ab3(s3)" */

    /* Volatile state on candidates.  Reinitialized at start of election. */
    struct uuid vote;           /* Server ID of vote, or all-zeros. */

    /* Volatile state on leaders.  Reinitialized after election. */
    uint64_t next_index;     /* Index of next log entry to send this server. */
    uint64_t match_index;    /* Index of max log entry server known to have. */
    enum raft_server_phase phase;
    /* For use in adding and removing servers: */
    struct uuid requester_sid;  /* Nonzero if requested via RPC. */
    struct unixctl_conn *requester_conn; /* Only if requested via unixctl. */
};

void raft_server_destroy(struct raft_server *);
void raft_servers_destroy(struct hmap *servers);
struct raft_server *raft_server_add(struct hmap *servers,
                                    const struct uuid *sid,
                                    const char *address);
struct raft_server *raft_server_find(const struct hmap *servers,
                                     const struct uuid *sid);
const char *raft_servers_get_nickname__(const struct hmap *servers,
                                        const struct uuid *sid);
const char *raft_servers_get_nickname(const struct hmap *servers,
                                      const struct uuid *sid,
                                      char buf[SID_LEN + 1], size_t bufsize);
struct ovsdb_error *raft_servers_from_json(const struct json *,
                                           struct hmap *servers)
    OVS_WARN_UNUSED_RESULT;
struct ovsdb_error *raft_servers_validate_json(const struct json *);
    OVS_WARN_UNUSED_RESULT
struct json *raft_servers_to_json(const struct hmap *servers);
void raft_servers_format(const struct hmap *servers, struct ds *ds);
\f
/* A raft_entry is an in-memory data structure that represents a Raft log
 * entry.  */
struct raft_entry {
    uint64_t term;
    struct json *data;
    struct uuid eid;
    struct json *servers;
};

void raft_entry_clone(struct raft_entry *, const struct raft_entry *);
void raft_entry_uninit(struct raft_entry *);
struct json *raft_entry_to_json(const struct raft_entry *);
struct ovsdb_error *raft_entry_from_json(struct json *, struct raft_entry *)
    OVS_WARN_UNUSED_RESULT;
bool raft_entry_equals(const struct raft_entry *, const struct raft_entry *);
\f
/* On disk data serialization and deserialization. */

/* First record in a Raft log. */
struct raft_header {
    /* All servers. */
    struct uuid sid;            /* Server ID. */
    struct uuid cid;            /* Cluster ID.  May be zero if 'joining'. */
    char *name;                 /* Database name. */
    char *local_address;        /* Address for Raft server to listen. */
    bool joining;               /* True iff cluster not joined yet. */

    /* Only for servers that haven't joined the cluster yet. */
    struct sset remote_addresses; /* Address of other Raft servers. */

    /* Only for servers that have joined the cluster. */
    uint64_t snap_index;        /* Snapshot's index. */
    struct raft_entry snap;     /* Snapshot. */
};

void raft_header_uninit(struct raft_header *);
struct ovsdb_error *raft_header_from_json(struct raft_header *,
                                          const struct json *)
    OVS_WARN_UNUSED_RESULT;
struct json *raft_header_to_json(const struct raft_header *);

enum raft_record_type {
    /* Record types that match those in the Raft specification. */
    RAFT_REC_ENTRY,             /* A log entry. */
    RAFT_REC_TERM,              /* A new term. */
    RAFT_REC_VOTE,              /* A vote. */

    /* Extensions. */
    RAFT_REC_NOTE,              /* A note about some significant event. */
    RAFT_REC_COMMIT_INDEX,      /* An update to the local commit_index. */
    RAFT_REC_LEADER,            /* A server has become leader for this term. */
};

/* Type used for the second and subsequent records in a Raft log. */
struct raft_record {
    enum raft_record_type type;
    char *comment;

    /* Valid in RAFT_REC_ENTRY, RAFT_REC_TERM, RAFT_REC_LEADER, and
     * RAFT_REC_VOTE, and otherwise 0. */
    uint64_t term;

    union {
        char *note;             /* RAFT_REC_NOTE. */

        uint64_t commit_index;  /* RAFT_REC_COMMIT_INDEX. */

        struct uuid sid;        /* RAFT_REC_VOTE, RAFT_REC_LEADER. */

        struct {                /* RAFT_REC_ENTRY. */
            uint64_t index;
            struct json *data;
            struct json *servers;
            struct uuid eid;
        } entry;
    };
};

void raft_record_uninit(struct raft_record *);
struct ovsdb_error *raft_record_from_json(struct raft_record *,
                                          const struct json *)
    OVS_WARN_UNUSED_RESULT;
struct json *raft_record_to_json(const struct raft_record *);
\f
void raft_put_uint64(struct json *object, const char *name, uint64_t integer);
uint64_t raft_parse_optional_uint64(struct ovsdb_parser *, const char *name);
uint64_t raft_parse_required_uint64(struct ovsdb_parser *, const char *name);

bool raft_parse_required_boolean(struct ovsdb_parser *, const char *name);
int raft_parse_optional_boolean(struct ovsdb_parser *, const char *name);
const char *raft_parse_required_string(struct ovsdb_parser *,
                                           const char *name);
const char *raft_parse_optional_string(struct ovsdb_parser *,
                                           const char *name);
bool raft_parse_uuid(struct ovsdb_parser *, const char *name, bool optional,
                     struct uuid *);
struct uuid raft_parse_required_uuid(struct ovsdb_parser *, const char *name);
bool raft_parse_optional_uuid(struct ovsdb_parser *, const char *name,
                         struct uuid *);

#endif /* raft-private.h */
Commit	Line	Data
1b1d2e6d BP	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 */