Changes to support server-side environment resolution

Adds support in template_utils to optionally produce an ordered list of
environment file names and include the environment file contents in the
files dict. This will be passed to the server to trigger the server-side
handling of resolving overrides for multiple environments.

The original behavior of merging the environments client-side is left in
for backward compatibility purposes. Both are sent to the server. For
mitaka and newer, the client-submitted environment is ignored and the
merging is done server-side. For liberty and older, the
environment_files list is ignored entirely and the passed in environment
is used.

Note that the merging, regardless if it is done client or server-side,
is handled by the same code; it has not been copied or duplicated in the
server.

Change-Id: If187c8ca3d80008c21e8f6066d335ab0c30315e6
Implements: blueprint multi-environments
Depends-On: Ibe46fd35de7988920c101a83259c06c8f8a3ed0b

1 files changed, 76 insertions, 9 deletions

diff --git a/heatclient/common/template_utils.py b/heatclient/common/template_utils.py
index a14f35c..fad243d 100644
--- a/heatclient/common/template_utils.py
+++ b/heatclient/common/template_utils.py
@@ -189,17 +189,51 @@ def deep_update(old, new):
 def process_multiple_environments_and_files(env_paths=None, template=None,
                                             template_url=None,
                                             env_path_is_object=None,
-                                            object_request=None):
-
+                                            object_request=None,
+                                            env_list_tracker=None):
+    """Reads one or more environment files.
+
+    Reads in each specified environment file and returns a dictionary
+    of the filenames->contents (suitable for the files dict)
+    and the consolidated environment (after having applied the correct
+    overrides based on order).
+
+    If a list is provided in the env_list_tracker parameter, the behavior
+    is altered to take advantage of server-side environment resolution.
+    Specifically, this means:
+
+    * Populating env_list_tracker with an ordered list of environment file
+      URLs to be passed to the server
+    * Including the contents of each environment file in the returned
+      files dict, keyed by one of the URLs in env_list_tracker
+
+    :param env_paths: list of paths to the environment files to load; if
+           None, empty results will be returned
+    :type  env_paths: list or None
+    :param template: unused; only included for API compatibility
+    :param template_url: unused; only included for API compatibility
+    :param env_list_tracker: if specified, environment filenames will be
+           stored within
+    :type  env_list_tracker: list or None
+    :return: tuple of files dict and a dict of the consolidated environment
+    :rtype:  tuple
+    """
     merged_files = {}
     merged_env = {}
 
+    # If we're keeping a list of environment files separately, include the
+    # contents of the files in the files dict
+    include_env_in_files = env_list_tracker is not None
+
     if env_paths:
         for env_path in env_paths:
-            files, env = process_environment_and_files(env_path, template,
-                                                       template_url,
-                                                       env_path_is_object,
-                                                       object_request)
+            files, env = process_environment_and_files(
+                env_path=env_path,
+                template=template,
+                template_url=template_url,
+                env_path_is_object=env_path_is_object,
+                object_request=object_request,
+                include_env_in_files=include_env_in_files)
 
             # 'files' looks like {"filename1": contents, "filename2": contents}
             # so a simple update is enough for merging
@@ -209,12 +243,32 @@ def process_multiple_environments_and_files(env_paths=None, template=None,
             # not enough
             merged_env = deep_update(merged_env, env)
 
+            if env_list_tracker is not None:
+                env_url = utils.normalise_file_path_to_url(env_path)
+                env_list_tracker.append(env_url)
+
     return merged_files, merged_env
 
 
-def process_environment_and_files(env_path=None, template=None,
-                                  template_url=None, env_path_is_object=None,
-                                  object_request=None):
+def process_environment_and_files(env_path=None,
+                                  template=None,
+                                  template_url=None,
+                                  env_path_is_object=None,
+                                  object_request=None,
+                                  include_env_in_files=False):
+    """Loads a single environment file.
+
+    Returns an entry suitable for the files dict which maps the environment
+    filename to its contents.
+
+    :param env_path: full path to the file to load
+    :type  env_path: str or None
+    :param include_env_in_files: if specified, the raw environment file itself
+           will be included in the returned files dict
+    :type  include_env_in_files: bool
+    :return: tuple of files dict and the loaded environment as a dict
+    :rtype:  (dict, dict)
+    """
     files = {}
     env = {}
 
@@ -234,6 +288,10 @@ def process_environment_and_files(env_path=None, template=None,
         env_url = utils.normalise_file_path_to_url(env_path)
         env_base_url = utils.base_url_for_url(env_url)
         raw_env = request.urlopen(env_url).read()
+
+        if include_env_in_files:
+            files[env_url] = raw_env
+
         env = environment_format.parse(raw_env)
 
         resolve_environment_urls(
@@ -246,6 +304,15 @@ def process_environment_and_files(env_path=None, template=None,
 
 def resolve_environment_urls(resource_registry, files, env_base_url,
                              is_object=False, object_request=None):
+    """Handles any resource URLs specified in an environment.
+
+    :param resource_registry: mapping of type name to template filename
+    :type  resource_registry: dict
+    :param files: dict to store loaded file contents into
+    :type  files: dict
+    :param env_base_url: base URL to look in when loading files
+    :type  env_base_url: str or None
+    """
     if resource_registry is None:
         return