yumaworks-db-api.yang

module yumaworks-db-api {

    namespace "http://yumaworks.com/ns/yumaworks-db-api";

    prefix "ydb";

    import ietf-yang-types { prefix yang; }
    import ietf-yang-patch { prefix yp; }
    import ietf-yang-structure-ext { prefix sx; }
    import yumaworks-ycontrol { prefix yctl; }
    import yuma-ncx { prefix ncx; }
    import yuma-types { prefix yt; }

    organization "YumaWorks, Inc.";

    contact
        "Support <support at yumaworks.com>";

    description
       "YumaPro Database API Sub-Agent message definitions.

     Copyright (c) 2014 - 2023, YumaWorks, Inc. All rights reserved.

     Redistribution and use in source and binary forms, with or
     without modification, is permitted pursuant to, and subject
     to the license terms contained in, the BSD 3-Clause License
     http://opensource.org/licenses/BSD-3-Clause";

    revision 2023-08-04 {
      description
        "22.10T-11: Change CLI container to sx:structure";
    }

    revision 2020-02-19 {
        description
          "Add subrpc-request and subrpc-response messages.";
    }

    revision 2019-01-27 {
        description
          "Add allowed parameter to maintenance mode.
           Add db-lock messages";
    }

    revision 2018-11-13 {
        description
          "Add maintenance mode and set-loglevel support";
    }

    revision 2018-06-13 {
        description
          "Add skip-sil parameter to edit-request message";
    }

    revision 2018-05-31 {
        description
          "Add parameters to getconfig message";
    }

    revision 2017-10-30 {
        description
          "Add getconfig message";
    }

    revision 2017-09-19 {
        description
          "Fix broken augment statement for payload";
    }

    revision 2016-08-29 {
        description
          "Update yp-ha-mode event";
    }

    revision 2016-07-31 {
        description
          "Add new events to support YP-HA mode changes.";
    }

    revision 2015-03-29 {
        description
          "Add edit-type parameter to edit-request.";
    }

    revision 2014-11-18 {
        description
          "Initial version for datastore access.";
    }

    grouping lock-id {
      leaf lock-id {
        type string {
          length "1 .. 64";
        }
        mandatory true;
        description
          "The lock identifier sent by the server in the
           db-lock request. Used to prevent late replies
           from being interpreted as a reply to a new reuest.";
      }
    }

    sx:augment-structure
      "/yctl:ycontrol/yctl:message-payload/yctl:payload/yctl:payload" {
      container db-api {

        choice message-type {
          mandatory true;

          leaf register-request {
            type empty;
            description
             "Message type: subsys-request;
              Purpose: register the DB-API subsystem
              Expected Response Message: ok or error";
          }

          container edit-request {
            description
             "Message type: subsys-request;
              Purpose: Ask the main server to accept an edit request
              to be added to the running configuration, and saved to
              NV-storage unless the :startup capability is supported.

              Expected Response Message: ok or error";

            leaf target {
              type string;  // target-path-string
              mandatory true;
              description
               "Identifies the target resource for the edit
                operation.";
            }

            leaf edit-type {
              type enumeration {
                enum user {
                  description "A user edit with access control";
                }
                enum system {
                  description "A system edit without access control";
                }
              }
              default user;
              description
               "Indicates whether this is a user edit or system edit.
                System edits will bypass all access control enforcement,
                including the ncx:user-write extension.";
            }

            leaf skip-sil {
              type boolean;
              default true;
              description
               "Skip the SIL and SIL-SA callbacks for this transaction.
                This is the normal mode since the DB-API edit is
                generated by the system, so the edits do not need
                to be applied again by the server.";
            }

            uses yp:yang-patch;

          }  // container edit-request

          container yp-ha-mode {
            description
             "Message type: subsys-request;
              Purpose: send mode change request to the server
              Expected Response Message: ok or error";

            choice action {
              mandatory true;
              leaf go-active {
                type empty;
                description
                  "Become the YP-HA active server.
                   All normal management operations are supported
                   in this mode.";
              }
              container go-standby {
                description
                  "Become a YP-HA standby server, and try to connect
                   to the active server 'new-active'. Only the superuser
                   can use management sesssions in this mode.";

                leaf new-active {
                  type string;
                  mandatory true;
                  description
                    "Server name of the active server to use";
                }
              }
              leaf go-none {
                type empty;
                description
                  "Leave current YP-HA role and wait new role.
                   Only the superuser can use management sesssions
                   in this mode.";
              }

            }
          }  // container yp-ha-mode

          container getconfig {
            description
             "Message type: subsys-request;
              Purpose: Ask the main server to send the running
              configuration contents

              Expected Response Message: config";

              leaf withdef {
                type boolean;
                default false;
                description
                  "Include defaults (according to the server
                   --default-style CLI parameter) if 'true'.
                   Do not include defaults if 'false'.";
              }

              leaf with-state {
                type boolean;
                default false;
                description
                  "Include operational data (like <get> operation)";
              }

              leaf xpath-filter {
                type yang:xpath1.0;
                description
                  "XPath filter to use for this retrieval operation";
              }

          }  // container getconfig

          container config {
            ncx:root;
            description
             "Message type: server-response;
              Purpose: Provide the contents of the running
              configuration contents

              Expected Response Message: none";

          }  // container config


          container enter-maintmode {
            description
             "Message type: subsys-request.
              Purpose: Enter maintenance mode.
              Expected Response Message: server-response
              The server will send ok or error.";

            leaf allowed {
              type bits {
                bit read {
                  position 0;
                  description
                    "Allow client sessions for operations that
                     read datastores or operational data.";
                }
                bit operation {
                  position 1;
                  description
                    "Allow client sessions for general operations
                     that do not access any datastores.";
                }
              }
              default "";
              description
                "The client activity that is allowed during
                 maintenance mode. By default client sessions
                 are disabled during maintenance mode, and any
                 existing sessions will get 'access-denied' errors
                 for all operations started after maintenance mode
                 is started.";
            }
          }  // container enter-maintmode

          container exit-maintmode {
            description
             "Message type: subsys-request.
              Purpose: Exit maintenance mode.
              Expected Response Message: server-response
              The server will send ok or error.";

          }  // container exit-maintmode

          container set-log-level {
            description
             "Message type: subsys-request.
              Purpose: Set the log-level parameter.
              Expected Response Message: server-response
              The server will send ok or error.";

            leaf log-level {
              type yt:NcDebugType;
              mandatory true;
              description "The new log level to set";
            }

          }  // container set-log-level

          container db-lock-init {
            description
             "Message type: subsys-request.
              Purpose: Establish the subsystem as the DB-Edit-Lock
              controller. This is done once after the db-api service
              is registered.
              Expected Response Message: server-response
              The server will send ok or error.";
          }

          container db-lock {
            description
             "Message type: server-request.
              Purpose: Request the system config write lock.
              Expected Response Message: subsys-response
              The subsystem will send db-lock-response or error.";
            uses lock-id;
          }

          container db-lock-response {
            description
             "Message type: subsys-response.
              Purpose: Response for the system config write lock.
              Expected Response Message: none";
            uses lock-id;
          }

          container db-unlock {
            description
             "Message type: server-event.
              Purpose: Release the system config write lock.
              Expected Response Message: none";
            uses lock-id;
          }

          container subrpc-request {
            description
             "Message type: subsys-request;
              Purpose: Start an RPC transaction to the main server.

              This message requests that a new remote procedure
              call be validated and invoked on the server and
              possibly one or more SIL-SA subsystems.

              If not valid or if the operation cannot be performed,
              the server must return an error.

              Expected Response Message: subrpc-response";

            leaf user-id {
              type string;
              description
                "Identifies the user that should be used for
                 access control and logging purposes.
                 If not present then the system user will be used
                 and all access control will be skipped.";
            }

            leaf rpc-module {
              type yt:NcxName;
              description
                "Identifies the module name of the RPC definition.
                 If not present then the server will use the first
                 RPC method with the same name as 'rpc-name'.";
            }

            leaf rpc-name {
              type yt:NcxName;
              mandatory true;
              description
                "Identifies the name of the RPC definition.";
            }

            anyxml rpc-method {
              description
                "Contains the RPC method element and all child nodes
                 representing the input parameters. This is structured
                 exactly the same as the contents of an <rpc> element
                 from RFC 6241. If not present then an empty method
                 element will be constructed using 'rpc-module' and
                 'rpc-name' values.";
            }
          }

          container subrpc-response {
            description
             "Message type: server-response
              Purpose: Return <rpc-reply> message
              Expected Response Message: none";

            leaf rpc-module {
              type yt:NcxName;
              mandatory true;
              description
                "Identifies the module name of the RPC definition.";
            }

            leaf rpc-name {
              type yt:NcxName;
              mandatory true;
              description
                "Identifies the name of the RPC definition.";
            }

            anyxml reply {
               mandatory true;
               description
                 "Contains the RPC reply message for the subrpc-request.";
            }
          }

        } // choice message-type
      } // container db-api
    } // augment
}