View source for Honeycomb/Persistence

= Honeycomb persistence proposal =
Persistence proposal for Honeycomb project

Honeycomb needs to support persistence in order to:
* be able to restore its config data tree into "before restart state"
* be able to forward all the persisted configuration into VPP
** data not present in VPP should be created
** data already present in VPP should be ignored
** data already present in VPP, but persisted with different values should be updated in VPP
** data present in VPP, but not present in persisted should be OPTIONALLY deleted

== Involved components/concepts ==
Short description for components and concepts used in the proposal.

=== Components ===
* Context - Context is a non-config storage for metadata related to Yang -> VPP translation. It is hidden from the user, but is necessary for non-trivial translations. This is plugin/model specific component. Example would be: interface name from v3po model to interface index in VPP mapping.
* Initializer - Component responsible for reading initial state of VPP (right after Honeycomb connects to it) and transforming + storing the data in Honeycomb's config data tree. This synchronizes Honeycomb's data tree with whatever is already configured on VPP. Initializers are developed as part of Honeycomb's plugins (if required).

=== Concepts ===
* Soft write - Write that only goes to the config data tree but is not propagated to the translation layer and VPP itself. Useful for writes from Initializers.
* Hard write - Write that is propagated to VPP and only if VPP configuration succeeds, is applied committed to config data tree.

== Persistence process ==
# On each successful commit, persist:
## Entire config data tree
## All the contexts

== Restoration process ==
# Restore contexts
# For each initializer initialize:
## Dump whatever data are neccessary from VPP
## Transform the data
### If context is required use it to transform non-derivable data
## Soft write into config data tree
# Restore persisted data
# Hard write into config data tree (put or merge, depending on whether unpersisted data should be deleted or not from VPP, since put would remove everything that was not persisted by Honeycomb)

== Persisted file format ==
It is necessary to store the configuration in human readable format to enable users to perform manual edits e.g. XML or JSON. This might occur if VPP is restarted/upgraded but no longer accepts persisted configuration.

== Honeycomb restarts ==
Honeycomb needs to handle these situations, where persisted data must be restored:

=== Honeycomb is restarted ===
Honeycomb needs to connect to VPP and restore its config data tree from persisted data + current configuration in VPP. No updates should be triggered on VPP.

=== VPP is restarted ===
Honeycomb needs to detect the restart, reconnect to VPP and perform Restoration process from step 2. Persisted configuration should be reapplied to VPP.

=== Both VPP and Honeycomb are restarted ===
Identical to Honeycomb restart only.