github.com/simpleiot/simpleiot@v0.18.3/docs/adr/3-node-lifecycle.md (about)

     1  # Node Lifecycle
     2  
     3  - Author: Cliff Brake, last updated: 2022-02-16
     4  - PR/Discussion:
     5  - Status: discussion
     6  
     7  ## Context
     8  
     9  In the process of implementing a
    10  [feature to duplicate a node tree](https://github.com/simpleiot/simpleiot/issues/312),
    11  several problems have surfaced related to the lifecycle of creating and updating
    12  nodes.
    13  
    14  ### Node creation (< 0.5.0)
    15  
    16  - if a point was sent and node did not exist, SIOT created a "device" node as a
    17    child of the root node with this point. This was based on this initial use of
    18    SIOT with 1-wire devices.
    19  - there is also a feature where if we send a point to a Device node that does
    20    not have an upstream path to root, or that path is tombstoned, we create this
    21    path. This ensures that we don't have orphaned device nodes in an upstream if
    22    they are still active. This happens to the root node on clear startup.
    23  - by the user in the UI -- Http API, `/v1/nodes` POST, accepts a NodeEdge struct
    24    and then sends out node points and then edge points via NATs to create the
    25    node.
    26  - node is sent first, then the edge
    27  
    28  The creation process for a node involves:
    29  
    30  1. sending all the points of a node including a meta point with the node type.
    31  1. sending the edge points of a node to describe the upstream connection
    32  
    33  There are two problems with this:
    34  
    35  1. When creating a node, we send all the node points, then the edge points.
    36     However this can create an issue in that an upstream edge for a device node
    37     does not exist yet, so in a multi-level upstream configuration A->B->C, if B
    38     is syncing to C for the first time, multiple instances of A will be created
    39     on C.
    40  1. If a point is sent for a node that does not exist, a new device node will be
    41     created.
    42  
    43  An attempt was made to switch the sending edge points of new nodes before node
    44  points, however this created other issues (this was some time ago, so don't
    45  recall exactly what they were).
    46  
    47  ### Node creation (>= 0.5.0)
    48  
    49  With the swith to a SQLite store, a lot of code was rewritten, and in the
    50  process we changed the order of creating nodes to:
    51  
    52  1. send the edge points first
    53  1. then send node points
    54  
    55  (See the `SendNode()` function).
    56  
    57  ### discussion
    58  
    59  Sending node and edge points separately for new nodes creates an issue in that
    60  these don't happen in one communication transaction, so there is a period of
    61  time between the two where the node state is indeterminate. Consideration was
    62  given to adding a NATS endpoint to create nodes where everything could be sent
    63  at once. However, this is problematic in that now there is another NATS subject
    64  for everyone to listen to and process, rather than just listening for new
    65  points. It seems less than ideal to have multiple subjects that can
    66  create/modify node points.
    67  
    68  It seems at this point we can probably deprecate the feature to create new
    69  devices nodes based on a single point. This will force new nodes to be
    70  explicitly created. This is probably OK as new nodes are created in several
    71  ways:
    72  
    73  1. by the user in the UI
    74  2. by the upstream sync mechanism -- if the hash does match or a node does not
    75     exist upstream, it is sent. This is continuously checked so if a message does
    76     not succeed, it will eventually get resent.
    77  3. plug-n-play discovery mechanisms that detect new devices and automatically
    78     populate new nodes. Again, it is not a big deal if a message gets lost as the
    79     discovery mechanism will continue to try to create the new device if it does
    80     not find it.
    81  
    82  Sending edge before parents can be problematic for things like the client
    83  manager that might be listening for tombstone points to detect node
    84  creation/deletion. (Why is this???)
    85  
    86  ## Decision
    87  
    88  ## Consequences