lib/mgmt_fe_client.h

   1 // SPDX-License-Identifier: GPL-2.0-or-later
   2 /*
   3  * MGMTD Frontend Client Library api interfaces
   4  * Copyright (C) 2021  Vmware, Inc.
   5  *                     Pushpasis Sarkar <spushpasis@vmware.com>
   6  */
   7
   8 #ifndef _FRR_MGMTD_FE_CLIENT_H_
   9 #define _FRR_MGMTD_FE_CLIENT_H_
  10
  11 #ifdef __cplusplus
  12 extern "C" {
  13 #endif
  14
  15 #include "mgmt_pb.h"
  16 #include "frrevent.h"
  17 #include "mgmtd/mgmt_defines.h"
  18
  19 /***************************************************************
  20  * Macros
  21  ***************************************************************/
  22
  23 /*
  24  * The server port MGMTD daemon is listening for Backend Client
  25  * connections.
  26  */
  27
  28 #define MGMTD_FE_CLIENT_ERROR_STRING_MAX_LEN 32
  29
  30 #define MGMTD_FE_DEFAULT_CONN_RETRY_INTVL_SEC 5
  31
  32 #define MGMTD_FE_MSG_PROC_DELAY_USEC 10
  33 #define MGMTD_FE_MAX_NUM_MSG_PROC 500
  34
  35 #define MGMTD_FE_MSG_WRITE_DELAY_MSEC 1
  36 #define MGMTD_FE_MAX_NUM_MSG_WRITE 100
  37
  38 #define GMGD_FE_MAX_NUM_REQ_ITEMS 64
  39
  40 #define MGMTD_FE_MSG_MAX_LEN 9000
  41
  42 #define MGMTD_SOCKET_FE_SEND_BUF_SIZE 65535
  43 #define MGMTD_SOCKET_FE_RECV_BUF_SIZE MGMTD_SOCKET_FE_SEND_BUF_SIZE
  44
  45 /***************************************************************
  46  * Data-structures
  47  ***************************************************************/
  48
  49 #define MGMTD_SESSION_ID_NONE 0
  50
  51 #define MGMTD_CLIENT_ID_NONE 0
  52
  53 #define MGMTD_DS_NONE MGMTD__DATASTORE_ID__DS_NONE
  54 #define MGMTD_DS_RUNNING MGMTD__DATASTORE_ID__RUNNING_DS
  55 #define MGMTD_DS_CANDIDATE MGMTD__DATASTORE_ID__CANDIDATE_DS
  56 #define MGMTD_DS_OPERATIONAL MGMTD__DATASTORE_ID__OPERATIONAL_DS
  57 #define MGMTD_DS_MAX_ID MGMTD_DS_OPERATIONAL + 1
  58
  59 /*
  60  * All the client specific information this library needs to
  61  * initialize itself, setup connection with MGMTD FrontEnd interface
  62  * and carry on all required procedures appropriately.
  63  *
  64  * FrontEnd clients need to initialise a instance of this structure
  65  * with appropriate data and pass it while calling the API
  66  * to initialize the library (See mgmt_fe_client_lib_init for
  67  * more details).
  68  */
  69 struct mgmt_fe_client_params {
  70         char name[MGMTD_CLIENT_NAME_MAX_LEN];
  71         uintptr_t user_data;
  72         unsigned long conn_retry_intvl_sec;
  73
  74         void (*client_connect_notify)(uintptr_t lib_hndl,
  75                                       uintptr_t user_data,
  76                                       bool connected);
  77
  78         void (*client_session_notify)(uintptr_t lib_hndl,
  79                                       uintptr_t user_data,
  80                                       uint64_t client_id,
  81                                       bool create, bool success,
  82                                       uintptr_t session_id,
  83                                       uintptr_t user_session_ctx);
  84
  85         void (*lock_ds_notify)(uintptr_t lib_hndl, uintptr_t user_data,
  86                                uint64_t client_id, uintptr_t session_id,
  87                                uintptr_t user_session_ctx, uint64_t req_id,
  88                                bool lock_ds, bool success,
  89                                Mgmtd__DatastoreId ds_id, char *errmsg_if_any);
  90
  91         void (*set_config_notify)(uintptr_t lib_hndl, uintptr_t user_data,
  92                                   uint64_t client_id, uintptr_t session_id,
  93                                   uintptr_t user_session_ctx, uint64_t req_id,
  94                                   bool success, Mgmtd__DatastoreId ds_id,
  95                                   char *errmsg_if_any);
  96
  97         void (*commit_config_notify)(
  98                 uintptr_t lib_hndl, uintptr_t user_data, uint64_t client_id,
  99                 uintptr_t session_id, uintptr_t user_session_ctx,
 100                 uint64_t req_id, bool success, Mgmtd__DatastoreId src_ds_id,
 101                 Mgmtd__DatastoreId dst_ds_id, bool validate_only,
 102                 char *errmsg_if_any);
 103
 104         enum mgmt_result (*get_data_notify)(
 105                 uintptr_t lib_hndl, uintptr_t user_data, uint64_t client_id,
 106                 uintptr_t session_id, uintptr_t user_session_ctx,
 107                 uint64_t req_id, bool success, Mgmtd__DatastoreId ds_id,
 108                 Mgmtd__YangData **yang_data, size_t num_data, int next_key,
 109                 char *errmsg_if_any);
 110
 111         enum mgmt_result (*data_notify)(
 112                 uint64_t client_id, uint64_t session_id, uintptr_t user_data,
 113                 uint64_t req_id, Mgmtd__DatastoreId ds_id,
 114                 Mgmtd__YangData **yang_data, size_t num_data);
 115 };
 116
 117 extern struct debug mgmt_dbg_fe_client;
 118
 119 #define MGMTD_FE_CLIENT_DBG(fmt, ...)                                          \
 120         DEBUGD(&mgmt_dbg_fe_client, "FE-CLIENT: %s:" fmt, __func__,            \
 121                ##__VA_ARGS__)
 122 #define MGMTD_FE_CLIENT_ERR(fmt, ...)                                          \
 123         zlog_err("FE-CLIENT: %s: ERROR: " fmt, __func__, ##__VA_ARGS__)
 124 #define MGMTD_DBG_FE_CLIENT_CHECK()                                            \
 125         DEBUG_MODE_CHECK(&mgmt_dbg_fe_client, DEBUG_MODE_ALL)
 126
 127
 128 /***************************************************************
 129  * API prototypes
 130  ***************************************************************/
 131
 132 /*
 133  * Initialize library and try connecting with MGMTD FrontEnd interface.
 134  *
 135  * params
 136  *    Frontend client parameters.
 137  *
 138  * master_thread
 139  *    Thread master.
 140  *
 141  * Returns:
 142  *    Frontend client lib handler (nothing but address of mgmt_fe_client_ctx)
 143  */
 144 extern uintptr_t mgmt_fe_client_lib_init(struct mgmt_fe_client_params *params,
 145                                          struct event_loop *master_thread);
 146
 147 /*
 148  * Initialize library vty (adds debug support).
 149  *
 150  * This call should be added to your component when enabling other vty code to
 151  * enable mgmtd client debugs. When adding, one needs to also add a their
 152  * component in `xref2vtysh.py` as well.
 153  */
 154 extern void mgmt_fe_client_lib_vty_init(void);
 155
 156 /*
 157  * Print enabled debugging commands.
 158  */
 159 extern void mgmt_debug_fe_client_show_debug(struct vty *vty);
 160
 161 /*
 162  * Create a new Session for a Frontend Client connection.
 163  *
 164  * lib_hndl
 165  *    Client library handler.
 166  *
 167  * client_id
 168  *    Unique identifier of client.
 169  *
 170  * user_ctx
 171  *    Client context.
 172  *
 173  * Returns:
 174  *    MGMTD_SUCCESS on success, MGMTD_* otherwise.
 175  */
 176 extern enum mgmt_result mgmt_fe_create_client_session(uintptr_t lib_hndl,
 177                                                           uint64_t client_id,
 178                                                           uintptr_t user_ctx);
 179
 180 /*
 181  * Delete an existing Session for a Frontend Client connection.
 182  *
 183  * lib_hndl
 184  *    Client library handler.
 185  *
 186  * client_id
 187  *    Unique identifier of client.
 188  *
 189  * Returns:
 190  *    MGMTD_SUCCESS on success, MGMTD_* otherwise.
 191  */
 192 extern enum mgmt_result mgmt_fe_destroy_client_session(uintptr_t lib_hndl,
 193                                                        uint64_t client_id);
 194
 195 /*
 196  * Send UN/LOCK_DS_REQ to MGMTD for a specific Datastore DS.
 197  *
 198  * lib_hndl
 199  *    Client library handler.
 200  *
 201  * session_id
 202  *    Client session ID.
 203  *
 204  * req_id
 205  *    Client request ID.
 206  *
 207  * ds_id
 208  *    Datastore ID (Running/Candidate/Oper/Startup)
 209  *
 210  * lock_ds
 211  *    TRUE for lock request, FALSE for unlock request.
 212  *
 213  * Returns:
 214  *    MGMTD_SUCCESS on success, MGMTD_* otherwise.
 215  */
 216 extern enum mgmt_result mgmt_fe_lock_ds(uintptr_t lib_hndl, uint64_t session_id,
 217                                         uint64_t req_id,
 218                                         Mgmtd__DatastoreId ds_id, bool lock_ds);
 219
 220 /*
 221  * Send SET_CONFIG_REQ to MGMTD for one or more config data(s).
 222  *
 223  * lib_hndl
 224  *    Client library handler.
 225  *
 226  * session_id
 227  *    Client session ID.
 228  *
 229  * req_id
 230  *    Client request ID.
 231  *
 232  * ds_id
 233  *    Datastore ID (Running/Candidate/Oper/Startup)
 234  *
 235  * conf_req
 236  *    Details regarding the SET_CONFIG_REQ.
 237  *
 238  * num_req
 239  *    Number of config requests.
 240  *
 241  * implcit commit
 242  *    TRUE for implicit commit, FALSE otherwise.
 243  *
 244  * dst_ds_id
 245  *    Destination Datastore ID where data needs to be set.
 246  *
 247  * Returns:
 248  *    MGMTD_SUCCESS on success, MGMTD_* otherwise.
 249  */
 250 extern enum mgmt_result
 251 mgmt_fe_set_config_data(uintptr_t lib_hndl, uint64_t session_id,
 252                         uint64_t req_id, Mgmtd__DatastoreId ds_id,
 253                         Mgmtd__YangCfgDataReq **config_req, int num_req,
 254                         bool implicit_commit, Mgmtd__DatastoreId dst_ds_id);
 255
 256 /*
 257  * Send SET_COMMMIT_REQ to MGMTD for one or more config data(s).
 258  *
 259  * lib_hndl
 260  *    Client library handler.
 261  *
 262  * session_id
 263  *    Client session ID.
 264  *
 265  * req_id
 266  *    Client request ID.
 267  *
 268  * src_ds_id
 269  *    Source datastore ID from where data needs to be committed from.
 270  *
 271  * dst_ds_id
 272  *    Destination datastore ID where data needs to be committed to.
 273  *
 274  * validate_only
 275  *    TRUE if data needs to be validated only, FALSE otherwise.
 276  *
 277  * abort
 278  *    TRUE if need to restore Src DS back to Dest DS, FALSE otherwise.
 279  *
 280  * Returns:
 281  *    MGMTD_SUCCESS on success, MGMTD_* otherwise.
 282  */
 283 extern enum mgmt_result
 284 mgmt_fe_commit_config_data(uintptr_t lib_hndl, uint64_t session_id,
 285                            uint64_t req_id, Mgmtd__DatastoreId src_ds_id,
 286                            Mgmtd__DatastoreId dst_ds_id, bool validate_only,
 287                            bool abort);
 288
 289 /*
 290  * Send GET_CONFIG_REQ to MGMTD for one or more config data item(s).
 291  *
 292  * lib_hndl
 293  *    Client library handler.
 294  *
 295  * session_id
 296  *    Client session ID.
 297  *
 298  * req_id
 299  *    Client request ID.
 300  *
 301  * ds_id
 302  *    Datastore ID (Running/Candidate)
 303  *
 304  * data_req
 305  *    Get config requested.
 306  *
 307  * num_req
 308  *    Number of get config requests.
 309  *
 310  * Returns:
 311  *    MGMTD_SUCCESS on success, MGMTD_* otherwise.
 312  */
 313 extern enum mgmt_result
 314 mgmt_fe_get_config_data(uintptr_t lib_hndl, uint64_t session_id,
 315                         uint64_t req_id, Mgmtd__DatastoreId ds_id,
 316                         Mgmtd__YangGetDataReq **data_req, int num_reqs);
 317
 318 /*
 319  * Send GET_DATA_REQ to MGMTD for one or more data item(s).
 320  *
 321  * Similar to get config request but supports getting data
 322  * from operational ds aka backend clients directly.
 323  */
 324 extern enum mgmt_result mgmt_fe_get_data(uintptr_t lib_hndl,
 325                                          uint64_t session_id, uint64_t req_id,
 326                                          Mgmtd__DatastoreId ds_id,
 327                                          Mgmtd__YangGetDataReq **data_req,
 328                                          int num_reqs);
 329
 330 /*
 331  * Send NOTIFY_REGISTER_REQ to MGMTD daemon.
 332  *
 333  * lib_hndl
 334  *    Client library handler.
 335  *
 336  * session_id
 337  *    Client session ID.
 338  *
 339  * req_id
 340  *    Client request ID.
 341  *
 342  * ds_id
 343  *    Datastore ID.
 344  *
 345  * register_req
 346  *    TRUE if registering, FALSE otherwise.
 347  *
 348  * data_req
 349  *    Details of the YANG notification data.
 350  *
 351  * num_reqs
 352  *    Number of data requests.
 353  *
 354  * Returns:
 355  *    MGMTD_SUCCESS on success, MGMTD_* otherwise.
 356  */
 357 extern enum mgmt_result
 358 mgmt_fe_register_yang_notify(uintptr_t lib_hndl, uint64_t session_id,
 359                              uint64_t req_id, Mgmtd__DatastoreId ds_id,
 360                              bool register_req, Mgmtd__YangDataXPath **data_req,
 361                              int num_reqs);
 362
 363 /*
 364  * Destroy library and cleanup everything.
 365  */
 366 extern void mgmt_fe_client_lib_destroy(void);
 367
 368 /*
 369  * Get count of open sessions.
 370  */
 371 extern uint mgmt_fe_client_session_count(uintptr_t lib_hndl);
 372
 373 #ifdef __cplusplus
 374 }
 375 #endif
 376
 377 #endif /* _FRR_MGMTD_FE_CLIENT_H_ */