bionic (3) md_src_plugins_struct_README.3elektra.gz

NAME

       md_src_plugins_struct_READMEREADME
        -

       • infos = Information about struct plugin is in keys below

       • infos/author = Markus Raab elektra@libelektra.org

       • infos/licence = BSD

       • infos/needs =

       • infos/provides = apply

       • infos/ordering = check

       • infos/placements = presetstorage

       • infos/description = Copies meta data to keys using structbing

       This plugin is a check plugin which checks the structure and interrelations of Keys in order the verify
       that they represent a valid configuration.

   Purpose
       The glob plugin together with the check plugins create a good combination to check keys which are present
       in the KeySet. For some storage plugins like fstab, however, missing keys are as fatal as not validating
       keys – it is not possible to write a valid configuration file without them.

       The problem can be described as a structure built with lists and other structures that must match with
       the key names of a KeySet. If a structure must have an element, contrary to glob, the plugin can yield an
       error if it is missing. During the matching, the plugin also applies metadata to the individual keys.
       Such plugins that check the structure and interrelations of keys are called structure checker. They can
       require that various subkeys have to or must not exist. This can happen recursively to specify any
       structure.

       The struct plugin implements such a behaviour. It allows enforcement of a strong consistency within the
       keys of one backend.

   Usage
       In order for the struct plugin to do its job, it needs a plugin configuration to know which structure it
       should check for. This configuration can be passed from a storage plugin’s config/needs clause.

   Example
       The fstab plugin uses the struct plugin to verify the correct structure. Here is a snippet from it's
       contract:

           keyNew ("system/elektra/modules/fstab/config/needs/struct",
           KEY_VALUE, "list FStab",
           KEY_END),
           keyNew ("system/elektra/modules/fstab/config/needs/struct/FStab",
           KEY_META, "check/type", "null empty",
           KEY_END),
           keyNew ("system/elektra/modules/fstab/config/needs/struct/FStab/device",
           KEY_META, "check/type", "string",
           KEY_META, "check/path", "device",
           KEY_END),
           keyNew ("system/elektra/modules/fstab/config/needs/struct/FStab/mpoint",
           KEY_META, "check/type", "string",
           KEY_META, "check/path", "directory",
           KEY_END),
           keyNew ("system/elektra/modules/fstab/config/needs/struct/FStab/type",
           KEY_META, "check/type", "FSType",
           KEY_END),
           keyNew ("system/elektra/modules/fstab/config/needs/struct/FStab/options",
           KEY_META, "check/type", "string",
           KEY_END),
           keyNew ("system/elektra/modules/fstab/config/needs/struct/FStab/dumpfreq",
           KEY_META, "check/type", "unsigned_short",
           KEY_END), keyNew ("system/elektra/modules/fstab/config/needs/struct/FStab/passno",
           KEY_META, "check/type", "unsigned_short",
           KEY_END),

       The key value of needs/struct within the plugin configuration marks the starting point. list describes
       the first structure to be generated. It is a built-in structure of the struct plugin that supports all
       subkeys in one level. It applies to every direct subkey the structure check received by the template
       parameter. The template parameter is, in this case, FStab. The rest of the configuration specifies how
       entries of FStab must look.

       The information applied to the keys is given through metadata. This metadata is copied to each key during
       the structure check. If,however,a key is missing,the structure check will terminate with a failure. Any
       additional key will also lead to an error.

       The metadata may be evaluated by subsequent checks. In the situation of fstab a typechecker and a path
       checker are both useful.

       The purpose of such structure checks is that only a valid configuration can be stored and that neither
       applications nor storage plugins are surprised by configuration they do not understand.

       The fstab plugin trusts the fact that no invalid configuration is passed. It does not check it again.
       Missing configuration would lead to partially set data structures. The internally used API setmntent
       crashes in that case. This leads us to the {purpose of contracts}: We want a guarantee that specific
       conditions are already met because we know that the code of the plugin cannot handle it.

       Let us look at a different scenario with the same configuration. Instead of using the fstab plugin, we
       will use a general purpose storage plugin. For example, the dump plugin. Note that the metadata will be
       stored permanently in this situation. No plugin exports a config/needs clauses for the struct plugin in
       this situation. But the user can add the struct plugin and the plugin configuration, as shown in the code
       above, to the backend manually. Applications still can be sure that only a specific configuration will be
       stored and passed to them. The unwritten contract is between the application and the backend. No contract
       checker, however, would detect the missing configuration.

   Limitation
       This approach for defining the structure works recursively. Every element can have a value with a new
       structure check. Additionally, multiple template parameters can support even more generic data
       structures. This is, however, not yet implemented.