Skip to content

Latest commit

 

History

History
1002 lines (582 loc) · 26.5 KB

REFERENCE.md

File metadata and controls

1002 lines (582 loc) · 26.5 KB
Raw

Reference

Table of Contents

Classes

Defined types

Functions

Data types

  • Simpkv_test::AppId: String used as the app_id attribute of the simpkv_options parameter in a simpkv function call
  • Simpkv_test::FolderData: Information about an individual folder in a keystore
  • Simpkv_test::FolderInfo: Data structure specifying folder information Folders are unique based on 3 attributes: 1. The backend in which they are stored 2. Whether
  • Simpkv_test::Folders: Data structure specifying folder listings
  • Simpkv_test::Key: Key or folder name The regex is not perfect (doesn't catch sequences that look like relative paths), but sufficient for this test module.
  • Simpkv_test::KeyData: Information about an individual key in a keystore
  • Simpkv_test::KeyInfo: Data structure specifying key information Keys are unique based on 3 attributes: 1. The backend in which they are stored 2. Whether they a
  • Simpkv_test::Keys: Data structure specifying key/value pairs
  • Simpkv_test::NameInfo: Data structure specifying simply key/folder names Key/folder names are unique based on 3 attributes: 1. The backend in which they are store
  • Simpkv_test::NonBinaryKeyData: Information about an individual non-binary key in a keystore

Classes

simpkv_test::remove_folders

Remove folders using simpkv::deletetree

Parameters

The following parameters are available in the simpkv_test::remove_folders class:

foldername_info

Data type: Simpkv_test::NameInfo

Info specifying the names of the folders to remove

simpkv_test::remove_keys

Remove keys using simpkv::delete

Parameters

The following parameters are available in the simpkv_test::remove_keys class:

keyname_info

Data type: Simpkv_test::NameInfo

Info specifying the names of keys to remove

simpkv_test::retrieve_and_verify_folders

Retrieve folder lists with simpkv::list and verify the result

Parameters

The following parameters are available in the simpkv_test::retrieve_and_verify_folders class:

valid_folder_info

Data type: Simpkv_test::FolderInfo

Info specifying folders that are expected to be present in the keystore and their contents

invalid_folder_info

Data type: Simpkv_test::FolderInfo

Info specifying folders that are not expected to be present in the keystore

simpkv_test::retrieve_and_verify_keys

Retrieve keys with simpkv::get and verifies the results

Parameters

The following parameters are available in the simpkv_test::retrieve_and_verify_keys class:

valid_key_info

Data type: Simpkv_test::KeyInfo

Info specifying keys that are expected to be present in the keystore and their stored data

invalid_key_info

Data type: Simpkv_test::KeyInfo

Info specifying keys that are not expected to be present in the keystore

simpkv_test::store_keys

Store keys using simpkv::put

Parameters

The following parameters are available in the simpkv_test::store_keys class:

key_info

Data type: Simpkv_test::KeyInfo

Info specifying the key names and data to be stored

simpkv_test::verify_folders_exist

Check for the existence of folders using simpkv::exists

Parameters

The following parameters are available in the simpkv_test::verify_folders_exist class:

valid_foldername_info

Data type: Simpkv_test::NameInfo

Info specifying names of folder that are expected to be present in the keystore

invalid_foldername_info

Data type: Simpkv_test::NameInfo

Info specifying names of folder that are not expected to be present in the keystore

simpkv_test::verify_keys_exist

Check for the existence of keys using simpkv::exists

Parameters

The following parameters are available in the simpkv_test::verify_keys_exist class:

valid_keyname_info

Data type: Simpkv_test::NameInfo

Info specifying names of keys that are expected to be present in the keystore

invalid_keyname_info

Data type: Simpkv_test::NameInfo

Info specifying names of keys that are not expected to be present in the keystore

Defined types

simpkv_test::defines::remove_folder

Define that simply calls simpkv::deletetree

Parameters

The following parameters are available in the simpkv_test::defines::remove_folder defined type:

folder

Data type: Simpkv_test::Key

Name of the folder to remove

simpkv_options

Data type: Hash

Value of the simpkv_options parameter to be used in the simpkv::deletetree function call

Default value: {}

simpkv_test::defines::remove_key

Define that simply calls simpkv::delete

Parameters

The following parameters are available in the simpkv_test::defines::remove_key defined type:

key

Data type: Simpkv_test::Key

Name of the key to remove

simpkv_options

Data type: Hash

Value of the simpkv_options parameter to be used in the simpkv::delete function call

Default value: {}

simpkv_test::defines::retrieve_and_verify_folder

Fails if validation fails.

Parameters

The following parameters are available in the simpkv_test::defines::retrieve_and_verify_folder defined type:

folder

Data type: Simpkv_test::Key

Name of the folder to be listed

expected_keys

Data type: Variant[Hash[Simpkv_test::Key,Simpkv_test::NonBinaryKeyData],Undef]

Expected key data

expected_folders

Data type: Variant[Array[String[1]],Undef]

Expected folder data

simpkv_options

Data type: Hash

Value of the simpkv_options parameter to be used in the simpkv::list function call

Default value: {}

simpkv_test::defines::retrieve_and_verify_key

Fails if validation fails.

Parameters

The following parameters are available in the simpkv_test::defines::retrieve_and_verify_key defined type:

key

Data type: Simpkv_test::Key

Name of the key to be retrieved

expected_value

Data type: Any

Expected key value

expected_metadata

Data type: Variant[Hash,Undef]

Expected key metadata

simpkv_options

Data type: Hash

Value of the simpkv_options parameter to be used in the simpkv::get function call

binary

Data type: Boolean

Whether the key has a binary value

simpkv_test::defines::store_key

Define that simply calls simpkv::put

Parameters

The following parameters are available in the simpkv_test::defines::store_key defined type:

key

Data type: Simpkv_test::Key

Name of the key to store

value

Data type: NotUndef

Value to store

metadata

Data type: Hash

Metadata to store

Default value: {}

simpkv_options

Data type: Hash

Value of the simpkv_options parameter to be used in the simpkv::put function call

Default value: {}

simpkv_test::defines::verify_name_exists

Fails if validation fails.

Parameters

The following parameters are available in the simpkv_test::defines::verify_name_exists defined type:

key

Data type: Simpkv_test::Key

Name of the key/folder whose existence is to be checked

simpkv_options

Data type: Hash

Value of the simpkv_options parameter to be used in the simpkv::exists function call

Default value: {}

valid

Data type: Boolean

Whether key/folder should exist

Functions

simpkv_test::assert_equal

Type: Puppet Language

Compare 2 values and fail if they differ

simpkv_test::assert_equal(Any $actual, Any $expected, String $message)

The simpkv_test::assert_equal function.

Returns: None

actual

Data type: Any

Actual value

expected

Data type: Any

Expected value

message

Data type: String

Explanatory text that is added to the failure message

simpkv_test::code_source

Type: Puppet Language

"Randomly" assigns the code source from which a simpkv function will be called.

simpkv_test::code_source(String $id)

The simpkv_test::code_source function.

Returns: Enum['class', 'define', 'puppet_function']

id

Data type: String

Id of the key/folder used in the simpkv function

  • Used as the random generator seed

simpkv_test::key_value

Type: Puppet Language

Transforms to Binary as necessary, or undef if the value cannot be determined.

simpkv_test::key_value(Simpkv_test::KeyData $key_data)

Transforms to Binary as necessary, or undef if the value cannot be determined.

Returns: Any

key_data

Data type: Simpkv_test::KeyData

Key specification

simpkv_test::puppet_functions::remove_folder

Type: Puppet Language

Puppet language function that simply calls simpkv::deletetree

simpkv_test::puppet_functions::remove_folder(Simpkv_test::Key $folder, Hash $simpkv_options)

The simpkv_test::puppet_functions::remove_folder function.

Returns: None

folder

Data type: Simpkv_test::Key

Name of the folder to remove

simpkv_options

Data type: Hash

Value of the simpkv_options parameter to be used in the simpkv::deletetree function call

simpkv_test::puppet_functions::remove_key

Type: Puppet Language

Puppet language function that simply calls simpkv::delete

simpkv_test::puppet_functions::remove_key(Simpkv_test::Key $key, Hash $simpkv_options)

The simpkv_test::puppet_functions::remove_key function.

Returns: None

key

Data type: Simpkv_test::Key

Name of the key to remove

simpkv_options

Data type: Hash

Value of the simpkv_options parameter to be used in the simpkv::delete function call

simpkv_test::puppet_functions::retrieve_and_verify_folder

Type: Puppet Language

Fails if validation fails.

simpkv_test::puppet_functions::retrieve_and_verify_folder(Simpkv_test::Key $folder, Variant[Hash[Simpkv_test::Key,Simpkv_test::NonBinaryKeyData],Undef] $expected_keys, Variant[Array[String[1]],Undef] $expected_folders, Hash $simpkv_options = {})

Fails if validation fails.

Returns: None

folder

Data type: Simpkv_test::Key

Name of the folder to be listed

expected_keys

Data type: Variant[Hash[Simpkv_test::Key,Simpkv_test::NonBinaryKeyData],Undef]

Expected key data

expected_folders

Data type: Variant[Array[String[1]],Undef]

Expected folder data

simpkv_options

Data type: Hash

Value of the simpkv_options parameter to be used in the simpkv::list function call

simpkv_test::puppet_functions::retrieve_and_verify_key

Type: Puppet Language

Fails if validation fails.

simpkv_test::puppet_functions::retrieve_and_verify_key(Simpkv_test::Key $key, Any $expected_value, Variant[Hash,Undef] $expected_metadata, Hash $simpkv_options, Boolean $binary)

Fails if validation fails.

Returns: None

key

Data type: Simpkv_test::Key

Name of the key to be retrieved

expected_value

Data type: Any

Expected key value

expected_metadata

Data type: Variant[Hash,Undef]

Expected key metadata

simpkv_options

Data type: Hash

Value of the simpkv_options parameter to be used in the simpkv::get function call

binary

Data type: Boolean

Whether the key has a binary value

simpkv_test::puppet_functions::store_key

Type: Puppet Language

Puppet language function that simply calls simpkv::put

simpkv_test::puppet_functions::store_key(Simpkv_test::Key $key, NotUndef $value, Hash $metadata, Hash $simpkv_options)

The simpkv_test::puppet_functions::store_key function.

Returns: None

key

Data type: Simpkv_test::Key

Name of the key to store

value

Data type: NotUndef

Value to store

metadata

Data type: Hash

Metadata to store

simpkv_options

Data type: Hash

Value of the simpkv_options parameter to be used in the simpkv::put function call

simpkv_test::puppet_functions::verify_name_exists

Type: Puppet Language

Fails if validation fails.

simpkv_test::puppet_functions::verify_name_exists(Simpkv_test::Key $key, Hash $simpkv_options, Boolean $valid)

Fails if validation fails.

Returns: None

key

Data type: Simpkv_test::Key

Name of the key/folder whose existence is to be checked

simpkv_options

Data type: Hash

Value of the simpkv_options parameter to be used in the simpkv::exists function call

valid

Data type: Boolean

Whether key/folder should exist

simpkv_test::simpkv_options

Type: Puppet Language

Generates simpkv_options Hash for use in simpkv function calls

simpkv_test::simpkv_options(Simpkv_test::AppId $app_id, Enum['env', 'global'] $key_type, Hash $other_options = {})

The simpkv_test::simpkv_options function.

Returns: Hash

app_id

Data type: Simpkv_test::AppId

app_id to be set in the simpkv_options Hash

  • Ignored when an empty string
key_type

Data type: Enum['env', 'global']

The key/folder type

  • 'env': key/folder is tied to a Puppet environment
  • 'global': key/folder is global
other_options

Data type: Hash

Other options to be set in the returned simpkv_options Hash

simpkv_test::verify_folder_data

Type: Puppet Language

Compare expected and actual folder contents and fail if they differ

simpkv_test::verify_folder_data(Variant[Hash,Undef] $list_result, Variant[Hash[Simpkv_test::Key,Simpkv_test::NonBinaryKeyData],Undef] $expected_keys, Variant[Array[String[1]],Undef] $expected_folders, String[1] $message)

The simpkv_test::verify_folder_data function.

Returns: None

list_result

Data type: Variant[Hash,Undef]

The actual simpkv::list result

expected_keys

Data type: Variant[Hash[Simpkv_test::Key,Simpkv_test::NonBinaryKeyData],Undef]

Expected key data

expected_folders

Data type: Variant[Array[String[1]],Undef]

Expected folder data

message

Data type: String[1]

Explanatory text that is added to the failure message, if the comparison fails

simpkv_test::verify_key_data

Type: Puppet Language

Compare expected and actual key data and fail if they differ

simpkv_test::verify_key_data(Variant[Hash,Undef] $get_result, Any $expected_value, Variant[Hash,Undef] $expected_metadata, Boolean $binary, String[1] $message)

The simpkv_test::verify_key_data function.

Returns: None

get_result

Data type: Variant[Hash,Undef]

The actual simpkv::get result

expected_value

Data type: Any

Expected key value

expected_metadata

Data type: Variant[Hash,Undef]

Expected key metadata

binary

Data type: Boolean

Whether the key has a binary value

message

Data type: String[1]

Explanatory text that is added to the failure message, if the comparison fails

Data types

Simpkv_test::AppId

String used as the app_id attribute of the simpkv_options parameter in a simpkv function call

Alias of

String

Simpkv_test::FolderData

Information about an individual folder in a keystore

Alias of

Struct[{
  # Info about keys in the directory
  # - Currently restricted to keys with non-binary data because of
  #   test manifest limitations
  Optional[keys]    => Hash[Simpkv_test::Key,Simpkv_test::NonBinaryKeyData],

  # List of subfolder names
  Optional[folders] => Array[String[1]]
}]

Simpkv_test::FolderInfo

Data structure specifying folder information

Folders are unique based on 3 attributes:

  1. The backend in which they are stored
  2. Whether they are tied to a Puppet environment or global
  3. The folder names (each of which may include a relative path)

The grouping below was chosen to ensure uniqueness for test folders, ASSUMING, backends are uniquely mapped to the app_id attribute that will be used in the simpkv_options parameter of each simpkv function call.

If you are mapping multiple app_id values to the same backend in a test, be sure you don't have any folders that will resolve to the same storage location!

Alias of

Hash[Simpkv_test::AppId, Struct[{
    # - Any folder in 'env' is a folder tied to the Puppet environment.
    # - Any folder in 'global' is a global folder.
    #   - For these folders, the 'global' attribute of the `simpkv_options`
    #     parameter of each simpkv function call will be automatically set
    #     to `true`.
    Optional[env]    => Simpkv_test::Folders,
    Optional[global] => Simpkv_test::Folders
  }]]

Simpkv_test::Folders

Data structure specifying folder listings

Alias of

Hash[Simpkv_test::Key, Simpkv_test::FolderData]

Simpkv_test::Key

Key or folder name

The regex is not perfect (doesn't catch sequences that look like relative paths), but sufficient for this test module.

Alias of

Pattern['^[a-z0-9._:\-\/]+$']

Simpkv_test::KeyData

Information about an individual key in a keystore

Alias of

Struct[{
  # Either 'value' or 'file' needs to be set.
  # If both are set, 'value' will be used over 'file'.
  # If neither are set, the Simpkv_test::KeyData instance will be skipped.

  # Non-binary value
  Optional[value]    => NotUndef,

  # File containing binary value
  # - argument to binary_file, which is an absolute path or
  #   <module name>/<file name> string referencing a module file
  Optional[file]     => String[1],

  # Optional metadata stored with the value
  Optional[metadata] => Hash
}]

Simpkv_test::KeyInfo

Data structure specifying key information

Keys are unique based on 3 attributes:

  1. The backend in which they are stored
  2. Whether they are tied to a Puppet environment or global
  3. The key names (each of which may include a relative folder path)

The grouping below was chosen to ensure uniqueness for test keys, ASSUMING, backends are uniquely mapped to the app_id attribute that will be used in the simpkv_options parameter of each simpkv function call.

If you are mapping multiple app_id values to the same backend in a test, be sure you don't have any keys that will resolve to the same storage location!

Alias of

Hash[Simpkv_test::AppId, Struct[{
    # - Any key in 'env' is a key tied to the Puppet environment.
    # - Any key in 'global' is a global key.
    #   - For these keys, the 'global' attribute of the `simpkv_options`
    #     parameter of each simpkv function call will be automatically set
    #     to `true`.
    Optional[env]    => Simpkv_test::Keys,
    Optional[global] => Simpkv_test::Keys
  }]]

Simpkv_test::Keys

Data structure specifying key/value pairs

Alias of

Hash[Simpkv_test::Key, Simpkv_test::KeyData]

Simpkv_test::NameInfo

Data structure specifying simply key/folder names

Key/folder names are unique based on 3 attributes:

  1. The backend in which they are stored
  2. Whether they are tied to a Puppet environment or global
  3. The key/folder names (each of which may include a relative folder path)

The grouping below was chosen to ensure uniqueness for test key/folder names, ASSUMING, backends are uniquely mapped to the app_id attribute that will be used in the simpkv_options parameter of each simpkv function call.

If you are mapping multiple app_id values to the same backend in a test, be sure you don't have any keys/folders that will resolve to the same storage location!

Alias of

Hash[Simpkv_test::AppId, Struct[{
    # - Any key/folder in 'env' is tied to the Puppet environment.
    # - Any key/folder in 'global' is global
    #   - For these entities, the 'global' attribute of the `simpkv_options`
    #     parameter of each simpkv function call will be automatically set
    #     to `true`.
    Optional[env]    => Array[Simpkv_test::Key],
    Optional[global] => Array[Simpkv_test::Key]
  }]]

Simpkv_test::NonBinaryKeyData

Information about an individual non-binary key in a keystore

Alias of

Struct[{
  # Non-binary value
  value              => NotUndef,

  # Optional metadata stored with the value
  Optional[metadata] => Hash
}]