ietf-dtnma-agent.yang

module ietf-dtnma-agent {
  yang-version 1.1;
  namespace "ari://ietf/dtnma-agent/";
  prefix da;

  import ietf-amm {
    prefix amm;
  }

  organization
    "IETF Delay Tolerant Networking (DTN) Working Group" {
    amm:enum 1;
  }
  contact
    "WG Web: <http://tools.ietf.org/wg/dtn/>
     WG List: <mailto:dtn@ietf.org>

     Editor: Brian Sipos
             <mailto:brian.sipos+ietf@gmail.com>";
  description
    "This module implements the DTN Management Architecture (DTNMA)
     Agent core functionality.

     Copyright (c) 2024 IETF Trust and the persons identified as
     authors of the code.  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 Revised BSD License set
     forth in Section 4.c of the IETF Trust's Legal Provisions
     Relating to IETF Documents
     (https://trustee.ietf.org/license-info).

     This version of this YANG module is part of RFC XXXX
     (https://www.rfc-editor.org/info/rfcXXXX); see the RFC itself
     for full legal notices.";
  reference
    "draft-ietf-dtn-adm-yang";

  revision 2025-01-31 {
    description
      "Updated for latest ADM document.";
    reference
      "draft-ietf-dtn-adm-yang";
  }

  feature rules {
    description
      "Conforming to this feature enables time-based and
       state-based autonomy rules.";
  }

  grouping obj-list-params {
    description
      "Common parameters for object listing";
    amm:parameter include-adm {
      description
        "If true, listings will include objects from ADMs";
      amm:default "false";
      amm:type "/ARITYPE/BOOL";
    }
  }

  grouping any-binary-operands {
    description
      "Any-value bianry operands";
    amm:operand left {
      description
        "The left-side operand.";
      amm:type "//ietf/amm/TYPEDEF/ANY";
    }
    amm:operand right {
      description
        "The left-side operand.";
      amm:type "//ietf/amm/TYPEDEF/ANY";
    }
  }

  grouping numeric-unary-operands {
    description
      "Numeric unary operand";
    amm:operand val {
      description
        "The single value.";
      amm:type "//ietf/amm/TYPEDEF/NUMERIC";
    }
  }

  grouping numeric-binary-operands {
    description
      "Numeric bianry operands";
    amm:operand left {
      description
        "The left-side operand.";
      amm:type "//ietf/amm/TYPEDEF/NUMERIC";
    }
    amm:operand right {
      description
        "The left-side operand.";
      amm:type "//ietf/amm/TYPEDEF/NUMERIC";
    }
  }

  grouping numeric-unary-result {
    description
      "Numeric result";
    amm:result result {
      description
        "The single value.";
      amm:type "//ietf/amm/TYPEDEF/NUMERIC";
    }
  }

  grouping integer-unary-operands {
    description
      "Integer unary operand";
    amm:operand val {
      description
        "The single value.";
      amm:type "//ietf/amm/TYPEDEF/INTEGER";
    }
  }

  grouping integer-binary-operands {
    description
      "Integer bianry operands";
    amm:operand left {
      description
        "The left-side operand.";
      amm:type "//ietf/amm/TYPEDEF/INTEGER";
    }
    amm:operand right {
      description
        "The left-side operand.";
      amm:type "//ietf/amm/TYPEDEF/INTEGER";
    }
  }

  grouping integer-unary-result {
    description
      "Integer result";
    amm:result result {
      description
        "The single value.";
      amm:type "//ietf/amm/TYPEDEF/INTEGER";
    }
  }

  grouping bool-unary-operands {
    description
      "Boolean unary operand";
    amm:operand val {
      description
        "The single value.";
      amm:type "/ARITYPE/BOOL";
    }
  }

  grouping bool-binary-operands {
    description
      "Boolean bianry operands";
    amm:operand left {
      description
        "The left-side operand.";
      amm:type "/ARITYPE/BOOL";
    }
    amm:operand right {
      description
        "The left-side operand.";
      amm:type "/ARITYPE/BOOL";
    }
  }

  grouping bool-unary-result {
    description
      "Boolean result";
    amm:result result {
      description
        "The single value.";
      amm:type "/ARITYPE/BOOL";
    }
  }

  amm:enum 1;
  amm:edd sw-vendor {
    amm:enum 0;
    description
      "The vendor for this Agent implementation.";
    amm:type "/ARITYPE/TEXTSTR";
  }
  amm:edd sw-version {
    amm:enum 1;
    description
      "The version for this Agent implementation.";
    amm:type "/ARITYPE/TEXTSTR";
  }
  amm:edd capability {
    amm:enum 2;
    description
      "A table to indicate the ADM capability of the sending agent.";
    amm:tblt {
      amm:key "org-name adm-name";
      amm:column org-name {
        description
          "The organization name containing the ADM";
        amm:type "/ARITYPE/TEXTSTR";
      }
      amm:column org-enum {
        description
          "The organization enumeration containing the ADM";
        amm:type "/ARITYPE/VAST";
      }
      amm:column model-name {
        description
          "The model name of the ADM";
        amm:type "/ARITYPE/TEXTSTR";
      }
      amm:column model-enum {
        description
          "The model enumeration of the ADM";
        amm:type "/ARITYPE/VAST";
      }
      amm:column revision {
        description
          "The specific revision the agent supports.";
        amm:type "/ARITYPE/TEXTSTR";
      }
      amm:column features {
        description
          "The features of the ADM which the agent supports.";
        amm:ulist {
          amm:type "/ARITYPE/TEXTSTR";
        }
      }
    }
  }
  amm:const hello {
    amm:enum 0;
    description
      "A report template to indicate the presence of an agent
       on a network.";
    amm:init-value "/AC/(./EDD/sw-vendor,./EDD/sw-version,./EDD/capability)";
    amm:type "//ietf/amm/TYPEDEF/RPTT";
  }

  // Messaging counters
  amm:edd num-msg-rx {
    amm:enum 3;
    amm:type "//ietf/amm/TYPEDEF/counter64";
  }
  amm:edd num-msg-rx-failed {
    amm:enum 4;
    amm:type "//ietf/amm/TYPEDEF/counter64";
  }
  amm:edd num-msg-tx {
    amm:enum 5;
    amm:type "//ietf/amm/TYPEDEF/counter64";
  }
  amm:edd num-msg-tx-failed {
    amm:enum 15;
    amm:type "//ietf/amm/TYPEDEF/counter64";
  }

  // Execution counters and states
  amm:edd num-exec-started {
    amm:enum 6;
    amm:type "//ietf/amm/TYPEDEF/counter64";
  }
  amm:edd num-exec-succeeded {
    amm:enum 7;
    amm:type "//ietf/amm/TYPEDEF/counter64";
  }
  amm:edd num-exec-failed {
    amm:enum 8;
    amm:type "//ietf/amm/TYPEDEF/counter64";
  }
  amm:edd exec-running {
    amm:enum 9;
    amm:tblt {
      amm:key "pid";
      amm:column pid {
        amm:type "/ARITYPE/UVAST";
      }
      amm:column target {
        amm:type "//ietf/amm/TYPEDEF/ANY";
      }
      amm:column state {
        amm:type "/ARITYPE/BYTE" {
          amm:int-labels {
            enum waiting {
              value 0;
              description
                "The execution is waiting on a condition or timer to continue.";
            }
            enum running {
              value 1;
              description
                "The execution is currently running.";
            }
          }
        }
      }
    }
  }

  // MAC helper controls
  amm:ctrl if-then-else {
    amm:enum 0;
    description
      "Evaluate an expression and follow one of two branches of
       further evaluation.";
    amm:parameter condition {
      description
        "The condition to evaluate.";
      amm:type "//ietf/amm/TYPEDEF/eval-tgt";
    }
    amm:parameter on-truthy {
      description
        "The object to execute when the condition is truthy.";
      amm:default "null";
      amm:union {
        amm:type "//ietf/amm/TYPEDEF/exec-tgt";
        amm:type "/ARITYPE/NULL";
      }
    }
    amm:parameter on-falsy {
      description
        "An optional execution when the condition is falsey.";
      amm:default "null";
      amm:union {
        amm:type "//ietf/amm/TYPEDEF/exec-tgt";
        amm:type "/ARITYPE/NULL";
      }
    }
    amm:result branch {
      description
        "Indication of which branch was executed.";
      amm:type "/ARITYPE/BOOL";
    }
  }
  amm:ctrl catch {
    amm:enum 1;
    description
      "Attempt to execute a target, and if there is some failure catch it
       and execute an alternative target.";
    amm:parameter try {
      description
        "The object to execute.";
      amm:type "//ietf/amm/TYPEDEF/exec-tgt";
    }
    amm:parameter on-failure {
      description
        "An optional execution after failure.";
      amm:default "null";
      amm:union {
        amm:type "//ietf/amm/TYPEDEF/exec-tgt";
        amm:type "/ARITYPE/NULL";
      }
    }
    amm:result try-success {
      description
        "True if the try target succeeded without exception.";
      amm:type "/ARITYPE/BOOL";
    }
  }
  amm:ctrl wait-for {
    amm:enum 2;
    description
      "This control causes the execution to pause for a given amount of time.
       This is intended to be used within a macro to separate controls
       in time.";
    amm:parameter duration {
      amm:type "/ARITYPE/TD";
    }
  }
  amm:ctrl wait-until {
    amm:enum 3;
    description
      "This control causes the execution to pause until a specific absolute
       time point.
       This is intended to be used within a macro to separate controls
       in time or as a first macro item to delay execution after the time
       of reception.";
    amm:parameter time {
      amm:type "/ARITYPE/TP";
    }
  }
  amm:ctrl wait-cond {
    amm:enum 4;
    description
      "This control causes the execution to pause until a condition expression
       evaluates to truthy.
       This is intended to be used within a macro to separate controls
       in time or as a first macro item to delay execution until the
       condition is met.";
    amm:parameter condition {
      amm:type "//ietf/amm/TYPEDEF/eval-tgt";
    }
  }

  // Value production and reporting
  amm:ctrl inspect {
    amm:enum 5;
    description
      "Produce a result value to inspect the agent state.
       This does not perform any EXPR evaluation or RPTT handling.";
    amm:parameter ref {
      description
        "An object to produce a value from.";
      amm:type "//ietf/amm/TYPEDEF/VALUE-OBJ";
    }
    amm:result val {
      description
        "The produced value.";
      amm:type "//ietf/amm/TYPEDEF/ANY";
    }
  }
  amm:ctrl report-on {
    amm:enum 6;
    description
      "Agent-wide control to generate a report from a report template (RPTT).
       The parameter is a single RPTT list that would be produced by an object.
       If used for more than one-shot diagnostics, defining a RPTT
       (e.g. in a CONST within an ODM) is more efficient because the RPTT
       value would not need be present in the EXECSET or RPTSET.";
    amm:parameter template {
      description
        "The reporting template, either as a RPTT value directly or as
         a reference to a value-producing object (possibly parameterized)
         which itself produces an RPTT value.";
      amm:type "//ietf/amm/TYPEDEF/rpt-tgt";
    }
    amm:parameter destinations {
      description
        "One or more destination for the resulting report.
         It is possible that each destination has different access
         limitations so each destination might see different report
         contents.";
      amm:union {
        // FIXME: decide on whether this is a URI or a more complex ident hierarchy
        amm:type "/ARITYPE/textstr";
        amm:type "/ARITYPE/null";
      }
    }
  }

  // Helpers for VAR
  amm:ctrl var-reset {
    amm:enum 7;
    description
      "Modify a VAR state to its default value.";
    amm:parameter target {
      description
        "The VAR object to affect.";
      amm:type "/ARITYPE/VAR";
    }
  }
  amm:ctrl var-store {
    amm:enum 8;
    description
      "Modify a VAR state to a specific value.";
    amm:parameter target {
      description
        "The VAR object to affect.";
      amm:type "/ARITYPE/VAR";
    }
    amm:parameter value {
      description
        "The exact value to store in the VAR.";
      amm:type "//ietf/amm/TYPEDEF/ANY";
    }
  }

  // Objects related to TYPEDEF handling
  amm:edd typedef-list {
    amm:enum 10;
    description
      "A table of TYPEDEF within the agent.";
    uses obj-list-params;
    amm:tblt {
      amm:key "obj";
      amm:column obj {
        amm:type "/ARITYPE/TYPEDEF";
      }
    }
  }

  // Objects related to CONST handling
  amm:edd const-list {
    amm:enum 14;
    description
      "A table of CONST within the agent.";
    uses obj-list-params;
    amm:tblt {
      amm:key "obj";
      amm:column obj {
        amm:type "/ARITYPE/CONST";
      }
      amm:column type {
        amm:type "//ietf/amm/TYPEDEF/semtype";
      }
    }
  }
  amm:ctrl ensure-const {
    amm:enum 11;
    description
      "Ensure a specific CONST is present.";
    amm:parameter obj {
      description
        "A reference to a CONST within an ODM only.";
      amm:type "/ARITYPE/CONST";
    }
    amm:parameter type {
      description
        "The type for the CONST object.";
      amm:type "//ietf/amm/TYPEDEF/semtype";
    }
    amm:parameter init {
      description
        "A required initializer expression.
         This expression is evaluated once at the time of object creation.";
      amm:type "//ietf/amm/TYPEDEF/EXPR";
    }
  }
  amm:ctrl discard-const {
    amm:enum 12;
    description
      "Discard a specific CONST if it is present.";
    amm:parameter obj {
      description
        "A reference to a CONST within an ODM only.";
      amm:type "/ARITYPE/CONST";
    }
  }

  // Objects related to VAR handling
  amm:edd var-list {
    amm:enum 11;
    description
      "A table of VAR within the agent.";
    uses obj-list-params;
    amm:tblt {
      amm:key "obj";
      amm:column obj {
        amm:type "/ARITYPE/VAR";
      }
      amm:column type {
        amm:type "//ietf/amm/TYPEDEF/semtype";
      }
    }
  }
  amm:ctrl ensure-var {
    amm:enum 9;
    description
      "Ensure a specific VAR is present.";
    amm:parameter obj {
      description
        "A reference to a VAR within an ODM only.";
      amm:type "/ARITYPE/VAR";
    }
    amm:parameter type {
      description
        "The type for the VAR object.";
      amm:type "//ietf/amm/TYPEDEF/semtype";
    }
    amm:parameter init {
      description
        "An optional initializer expression.
         This expression is evaluated once at the time of object creation.";
      amm:default "null";
      amm:union {
        amm:type "/ARITYPE/NULL";
        amm:type "//ietf/amm/TYPEDEF/EXPR";
      }
    }
  }
  amm:ctrl discard-var {
    amm:enum 10;
    description
      "Discard a specific VAR if it is present.";
    amm:parameter obj {
      description
        "A reference to a VAR within an ODM only.";
      amm:type "/ARITYPE/VAR";
    }
  }

  // Objects related to SBR handling
  amm:edd sbr-list {
    if-feature "rules";
    amm:enum 12;
    description
      "A table of SBR within the agent.";
    amm:tblt {
      amm:key "obj";
      amm:column obj {
        amm:type "/ARITYPE/SBR";
      }
      amm:column action {
        description
          "The execution when this rule triggers.";
        amm:type "//ietf/amm/TYPEDEF/MAC";
      }
      amm:column start-time {
        amm:type "//ietf/amm/TYPEDEF/TIME";
      }
      amm:column condition {
        amm:type "//ietf/amm/TYPEDEF/EXPR";
      }
      amm:column min-interval {
        amm:type "/ARITYPE/TD";
      }
      amm:column max-count {
        amm:type "/ARITYPE/UVAST";
      }
    }
  }
  amm:edd tbr-list {
    if-feature "rules";
    amm:enum 13;
    description
      "A table of TBR within the agent.";
    amm:tblt {
      amm:key "obj";
      amm:column obj {
        amm:type "/ARITYPE/TBR";
      }
      amm:column action {
        description
          "The execution when this rule triggers.";
        amm:type "//ietf/amm/TYPEDEF/MAC";
      }
      amm:column start-time {
        amm:type "//ietf/amm/TYPEDEF/TIME";
      }
      amm:column period {
        amm:type "/ARITYPE/TD";
      }
      amm:column max-count {
        amm:type "/ARITYPE/UVAST";
      }
    }
  }

  // Numeric operators
  amm:oper negate {
    amm:enum 0;
    description
      "Negate a value.
       This is equivalent to multiplying by -1 but a shorter
       expression.";
    uses numeric-unary-operands;
    uses numeric-unary-result;
  }
  amm:oper add {
    amm:enum 1;
    description
      "Add two numeric values.
       The operands are cast to the least compatible numeric type
       before the arithmetic.";
    uses numeric-binary-operands;
    uses numeric-unary-result;
  }
  amm:oper sub {
    amm:enum 2;
    uses numeric-binary-operands;
    uses numeric-unary-result;
  }
  amm:oper multiply {
    amm:enum 3;
    uses numeric-binary-operands;
    uses numeric-unary-result;
  }
  amm:oper divide {
    amm:enum 4;
    uses numeric-binary-operands;
    uses numeric-unary-result;
  }
  amm:oper remainder {
    amm:enum 5;
    uses numeric-binary-operands;
    uses numeric-unary-result;
  }

  // Bitwise operators
  amm:oper bit-not {
    amm:enum 6;
    uses integer-unary-operands;
    uses integer-unary-result;
  }
  amm:oper bit-and {
    amm:enum 7;
    uses integer-binary-operands;
    uses integer-unary-result;
  }
  amm:oper bit-or {
    amm:enum 8;
    uses integer-binary-operands;
    uses integer-unary-result;
  }
  amm:oper bit-xor {
    amm:enum 9;
    uses integer-binary-operands;
    uses integer-unary-result;
  }

  // Boolean operators
  amm:oper bool-not {
    amm:enum 10;
    uses bool-unary-operands;
    uses bool-unary-result;
  }
  amm:oper bool-and {
    amm:enum 11;
    uses bool-binary-operands;
    uses bool-unary-result;
  }
  amm:oper bool-or {
    amm:enum 12;
    uses bool-binary-operands;
    uses bool-unary-result;
  }
  amm:oper bool-xor {
    amm:enum 13;
    uses bool-binary-operands;
    uses bool-unary-result;
  }

  // Value comparison
  amm:oper compare-eq {
    amm:enum 14;
    uses any-binary-operands;
    uses bool-unary-result;
  }
  amm:oper compare-ne {
    amm:enum 15;
    uses any-binary-operands;
    uses bool-unary-result;
  }

  // Numeric comparison
  amm:oper compare-gt {
    amm:enum 16;
    description
      "Compare two numbers by value.
       The result is true if the left value is greater than the right.
       The operands are cast to the least compatible numeric type
       before the comparison.";
    uses numeric-binary-operands;
    uses bool-unary-result;
  }
  amm:oper compare-ge {
    amm:enum 17;
    description
      "Compare two numbers by value.
       The result is true if the left value is greater than or equal
       to the right.
       The operands are cast to the least compatible numeric type
       before the comparison.";
    uses numeric-binary-operands;
    uses bool-unary-result;
  }
  amm:oper compare-lt {
    amm:enum 18;
    description
      "Compare two operands by value.
       The result is true if the left value is less than the right.
       The operands are cast to the least compatible numeric type
       before the comparison.";
    uses numeric-binary-operands;
    uses bool-unary-result;
  }
  amm:oper compare-le {
    amm:enum 19;
    description
      "Compare two operands by value.
       The result is true if the left value is less than or
       equal to the right.
       The operands are cast to the least compatible numeric type
       before the comparison.";
    uses numeric-binary-operands;
    uses bool-unary-result;
  }

  // Table filtering
  amm:typedef column-id {
    amm:enum 1;
    description
      "Name or index of an individual column in a table.";
    amm:union {
      amm:type "/ARITYPE/UVAST";
      amm:type "/ARITYPE/TEXTSTR";
    }
  }
  amm:oper tbl-filter {
    amm:enum 20;
    description
      "Filter a table first by rows and then by columns.";
    amm:parameter row-match {
      description
        "A filter to match rows with specific cell contents.
         Each key is a column to compare and each value is an expression
         with LABEL values substituted by column names.";
      amm:ulist {
        amm:type "//ietf/amm/TYPEDEF/EXPR";
      }
    }
    amm:parameter columns {
      description
        "A filter to match rows with specific cell contents.
         Each key is a column to compare and each value is an expression
         with LABEL values substituted by column names.";
      amm:ulist {
        amm:type "./TYPEDEF/column-id";
      }
    }
    amm:operand in {
      description
        "Table to filter.";
      amm:type "/ARITYPE/TBL";
    }
    amm:result out {
      description
        "The filtered table.";
      amm:type "/ARITYPE/TBL";
    }
  }
}