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 /***************************************************************
 118  * API prototypes
 119  ***************************************************************/
 120
 121 /*
 122  * Initialize library and try connecting with MGMTD FrontEnd interface.
 123  *
 124  * params
 125  *    Frontend client parameters.
 126  *
 127  * master_thread
 128  *    Thread master.
 129  *
 130  * Returns:
 131  *    Frontend client lib handler (nothing but address of mgmt_fe_client_ctx)
 132  */
 133 extern uintptr_t mgmt_fe_client_lib_init(struct mgmt_fe_client_params *params,
 134                                          struct event_loop *master_thread);
 135
 136 /*
 137  * Create a new Session for a Frontend Client connection.
 138  *
 139  * lib_hndl
 140  *    Client library handler.
 141  *
 142  * client_id
 143  *    Unique identifier of client.
 144  *
 145  * user_ctx
 146  *    Client context.
 147  *
 148  * Returns:
 149  *    MGMTD_SUCCESS on success, MGMTD_* otherwise.
 150  */
 151 extern enum mgmt_result mgmt_fe_create_client_session(uintptr_t lib_hndl,
 152                                                           uint64_t client_id,
 153                                                           uintptr_t user_ctx);
 154
 155 /*
 156  * Delete an existing Session for a Frontend Client connection.
 157  *
 158  * lib_hndl
 159  *    Client library handler.
 160  *
 161  * client_id
 162  *    Unique identifier of client.
 163  *
 164  * Returns:
 165  *    MGMTD_SUCCESS on success, MGMTD_* otherwise.
 166  */
 167 extern enum mgmt_result mgmt_fe_destroy_client_session(uintptr_t lib_hndl,
 168                                                        uint64_t client_id);
 169
 170 /*
 171  * Send UN/LOCK_DS_REQ to MGMTD for a specific Datastore DS.
 172  *
 173  * lib_hndl
 174  *    Client library handler.
 175  *
 176  * session_id
 177  *    Client session ID.
 178  *
 179  * req_id
 180  *    Client request ID.
 181  *
 182  * ds_id
 183  *    Datastore ID (Running/Candidate/Oper/Startup)
 184  *
 185  * lock_ds
 186  *    TRUE for lock request, FALSE for unlock request.
 187  *
 188  * Returns:
 189  *    MGMTD_SUCCESS on success, MGMTD_* otherwise.
 190  */
 191 extern enum mgmt_result
 192 mgmt_fe_lock_ds(uintptr_t lib_hndl, uintptr_t session_id, uint64_t req_id,
 193                     Mgmtd__DatastoreId ds_id, bool lock_ds);
 194
 195 /*
 196  * Send SET_CONFIG_REQ to MGMTD for one or more config data(s).
 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  * conf_req
 211  *    Details regarding the SET_CONFIG_REQ.
 212  *
 213  * num_req
 214  *    Number of config requests.
 215  *
 216  * implcit commit
 217  *    TRUE for implicit commit, FALSE otherwise.
 218  *
 219  * dst_ds_id
 220  *    Destination Datastore ID where data needs to be set.
 221  *
 222  * Returns:
 223  *    MGMTD_SUCCESS on success, MGMTD_* otherwise.
 224  */
 225 extern enum mgmt_result
 226 mgmt_fe_set_config_data(uintptr_t lib_hndl, uintptr_t session_id,
 227                             uint64_t req_id, Mgmtd__DatastoreId ds_id,
 228                             Mgmtd__YangCfgDataReq **config_req, int num_req,
 229                             bool implicit_commit, Mgmtd__DatastoreId dst_ds_id);
 230
 231 /*
 232  * Send SET_COMMMIT_REQ to MGMTD for one or more config data(s).
 233  *
 234  * lib_hndl
 235  *    Client library handler.
 236  *
 237  * session_id
 238  *    Client session ID.
 239  *
 240  * req_id
 241  *    Client request ID.
 242  *
 243  * src_ds_id
 244  *    Source datastore ID from where data needs to be committed from.
 245  *
 246  * dst_ds_id
 247  *    Destination datastore ID where data needs to be committed to.
 248  *
 249  * validate_only
 250  *    TRUE if data needs to be validated only, FALSE otherwise.
 251  *
 252  * abort
 253  *    TRUE if need to restore Src DS back to Dest DS, FALSE otherwise.
 254  *
 255  * Returns:
 256  *    MGMTD_SUCCESS on success, MGMTD_* otherwise.
 257  */
 258 extern enum mgmt_result
 259 mgmt_fe_commit_config_data(uintptr_t lib_hndl, uintptr_t session_id,
 260                                uint64_t req_id, Mgmtd__DatastoreId src_ds_id,
 261                                Mgmtd__DatastoreId dst_ds_id, bool validate_only,
 262                                bool abort);
 263
 264 /*
 265  * Send GET_CONFIG_REQ to MGMTD for one or more config data item(s).
 266  *
 267  * lib_hndl
 268  *    Client library handler.
 269  *
 270  * session_id
 271  *    Client session ID.
 272  *
 273  * req_id
 274  *    Client request ID.
 275  *
 276  * ds_id
 277  *    Datastore ID (Running/Candidate)
 278  *
 279  * data_req
 280  *    Get config requested.
 281  *
 282  * num_req
 283  *    Number of get config requests.
 284  *
 285  * Returns:
 286  *    MGMTD_SUCCESS on success, MGMTD_* otherwise.
 287  */
 288 extern enum mgmt_result
 289 mgmt_fe_get_config_data(uintptr_t lib_hndl, uintptr_t session_id,
 290                             uint64_t req_id, Mgmtd__DatastoreId ds_id,
 291                             Mgmtd__YangGetDataReq **data_req, int num_reqs);
 292
 293 /*
 294  * Send GET_DATA_REQ to MGMTD for one or more data item(s).
 295  *
 296  * Similar to get config request but supports getting data
 297  * from operational ds aka backend clients directly.
 298  */
 299 extern enum mgmt_result
 300 mgmt_fe_get_data(uintptr_t lib_hndl, uintptr_t session_id, uint64_t req_id,
 301                      Mgmtd__DatastoreId ds_id, Mgmtd__YangGetDataReq **data_req,
 302                      int num_reqs);
 303
 304 /*
 305  * Send NOTIFY_REGISTER_REQ to MGMTD daemon.
 306  *
 307  * lib_hndl
 308  *    Client library handler.
 309  *
 310  * session_id
 311  *    Client session ID.
 312  *
 313  * req_id
 314  *    Client request ID.
 315  *
 316  * ds_id
 317  *    Datastore ID.
 318  *
 319  * register_req
 320  *    TRUE if registering, FALSE otherwise.
 321  *
 322  * data_req
 323  *    Details of the YANG notification data.
 324  *
 325  * num_reqs
 326  *    Number of data requests.
 327  *
 328  * Returns:
 329  *    MGMTD_SUCCESS on success, MGMTD_* otherwise.
 330  */
 331 extern enum mgmt_result
 332 mgmt_fe_register_yang_notify(uintptr_t lib_hndl, uintptr_t session_id,
 333                                  uint64_t req_id, Mgmtd__DatastoreId ds_id,
 334                                  bool register_req,
 335                                  Mgmtd__YangDataXPath **data_req, int num_reqs);
 336
 337 /*
 338  * Destroy library and cleanup everything.
 339  */
 340 extern void mgmt_fe_client_lib_destroy(uintptr_t lib_hndl);
 341
 342 #ifdef __cplusplus
 343 }
 344 #endif
 345
 346 #endif /* _FRR_MGMTD_FE_CLIENT_H_ */