Uploaded image for project: 'Puppet'
  1. Puppet
  2. PUP-6768

Implement 'lookup context' object in the lookup v5 API



    • Type: New Feature
    • Status: Closed
    • Priority: Normal
    • Resolution: Fixed
    • Affects Version/s: None
    • Fix Version/s: PUP 4.8.0
    • Component/s: None
    • Labels:
    • Template:
    • Acceptance Criteria:

      This is enabling functionality - there should be unit test coverage of the features provided in the LookupContext API.

      This is enabling functionality - there should be unit test coverage of the features provided in the LookupContext API.
    • Team:
      Puppet Developer Experience
    • Story Points:
    • Sprint:
      PDS 2016-10-19
    • Release Notes:
      Not Needed
    • Release Notes Summary:
      Part of the lookup feature.


      In Lookup (v5) as defined by PUP-6484, the data provider API is built on 4.x functions. A helper mechanism is needed since:

      • functions cannot hold state, and this is needed when implementing something like a key by key lookup from an external source (for session key, private cached data, etc.)
      • undef is valid value and cannot be used to signal "not found"
      • there needs to be a way for a called function to provide explanations of its actions, and these needs to be appropriately nested.

      To accommodate for this, all of the function-kinds (hashed_data, lookup_key, data_dig) should take an object of Puppet::LookupContext kind. This object has an API as follows:

      • LookupContext::new(<args tbd>)
        Allows a helper to be created for the purpose of testing a data provider function directly
      • not_found()
        Handles all aspects of a key not being found (cache, trace, etc). This method does not return. This method must be called when there is no value for a root key, or no data available at all for a hashed_data function.
      • explain() || { < lambda producing message > }

        Adds a trace/explanation for the processing done to arrive at either not_found or found. The lambda is only called if explanations are wanted. (Alternatively allow being called with a message string). This method must be called for decisions made in the function that are of value when a user tries to understand where a value came from.

      • cache(key, value)
        Caches a value private to this function layer. The intended functionality is to allow a function to store a session key, RPC connection or similar object. The private values are not part of regular data and cannot be looked up externally. This method is of value since the function cannot hold any state. It is also much preferred over home-grown caching in the function implementation (which is hard to get right, and to correctly support different versions of puppet). Privately cached values are made immutable on addition, but the keys may be bound to new immutable values.
      • cache(hash)
        Caches all values in the hash.
      • cached_value(key)
        Returns an earlier privately cached value for the key
      • all_cached() | $key, $val | { }
        Returns an Iterable version (if not called with a lambda) of the immutable entries in the cache. (If an immutable hash is wanted from the result this can be achieved with Hash(all_cached()). (Using an Iterable prevents the mutable hash holding the cache from escaping into puppet as is).
      • environment_name()
        Returns the name of the environment the configuration is part of.
      • module_name()
        Returns the name of the module where the function is included in the respective configuration. Returns undef if the functions is part of the environment's configuration.

      The lookup feature manages the creation/nesting of instances during lookup such that the lookup function can be called from within a data provider function as well as a nested lookup taking place indirectly via some other calls that are not lookup related.




            henrik.lindberg Henrik Lindberg
            0 Vote for this issue
            3 Start watching this issue



                Zendesk Support