Setup basic Runtime with properties and platform.

recipe_engine/run.py

 # Copyright 2016 The LUCI Authors. All rights reserved.
 # Use of this source code is governed under the Apache License, Version 2.0
 # that can be found in the LICENSE file.
 
 """Entry point for fully-annotated builds.
 
 This script is part of the effort to move all builds to annotator-based
 systems. Any builder configured to use the AnnotatorFactory.BaseFactory()
 found in scripts/master/factory/annotator_factory.py executes a single
 AddAnnotatedScript step. That step (found in annotator_commands.py) calls
@@ skipping 46 matching lines @@
     the current history of what steps have run, what they returned, and any
     json data they emitted. Additionally, the OrderedDict has the following
     convenience functions defined:
       * last_step   - Returns the last step that ran or None
       * nth_step(n) - Returns the N'th step that ran or None
 
 'failed' is a boolean representing if the build is in a 'failed' state.
 """
 
 import collections
+import copy
 import json
 import os
-import sys
 import traceback
 
 from . import env
 
 from . import loader
 from . import recipe_api
 from . import recipe_test_api
 from . import step_runner as step_runner_module
 from . import types
 from . import util
@@ skipping 101 matching lines @@
 
 
 # Return value of run_steps and RecipeEngine.run.  Just a container for the
 # literal return value of the recipe.
 RecipeResult = collections.namedtuple('RecipeResult', 'result')
 
 
 # TODO(dnj): Replace "properties" with a generic runtime instance. This instance
 # will be used to seed recipe clients and expanded to include managed runtime
 # entities.
-def run_steps(properties, stream_engine, step_runner, universe_view):
+def run_steps(rt, stream_engine, step_runner, universe_view):
   """Runs a recipe (given by the 'recipe' property).
 
   Args:
-    properties: a dictionary of properties to pass to the recipe.  The
-      'recipe' property defines which recipe to actually run.
+    rt (Runtime): The runtime instance.
     stream_engine: the StreamEngine to use to create individual step streams.
     step_runner: The StepRunner to use to 'actually run' the steps.
     universe_view: The RecipeUniverse to use to load the recipes & modules.
 
   Returns: RecipeResult
   """
   with stream_engine.make_step_stream('setup_build') as s:
-    engine = RecipeEngine(step_runner, properties, universe_view)
+    engine = RecipeEngine(step_runner, rt, universe_view)
 
     # Create all API modules and top level RunSteps function.  It doesn't launch
     # any recipe code yet; RunSteps needs to be called.
     api = None
 
-    assert 'recipe' in properties
-    recipe = properties['recipe']
+    assert 'recipe' in rt.properties
+    recipe = rt.properties['recipe']
 
     root_package = universe_view.universe.package_deps.root_package
     run_recipe_help_lines = [
         'To repro this locally, run the following line from the root of a %r'
           ' checkout:' % (root_package.name),
         '',
         '%s run --properties-file - %s <<EOF' % (
             os.path.join( '.', root_package.relative_recipes_dir, 'recipes.py'),
             recipe),
-        '%s' % json.dumps(properties),
+        '%s' % rt.properties.to_json(sort_keys=True),
         'EOF',
         '',
         'To run on Windows, you can put the JSON in a file and redirect the',
         'contents of the file into run_recipe.py, with the < operator.',
     ]
 
     with s.new_log_stream('run_recipe') as l:
       for line in run_recipe_help_lines:
         l.write_line(line)
 
-    _isolate_environment()
+    os.environ = _isolate_environment(rt, os.environ)
 
     # Find and load the recipe to run.
     try:
       recipe_script = universe_view.load_recipe(recipe, engine=engine)
-      s.write_line('Running recipe with %s' % (properties,))
+      s.write_line('Running recipe with %s' % (rt.properties,))
 
       api = loader.create_recipe_api(recipe_script.LOADED_DEPS,
                                      engine,
                                      recipe_test_api.DisabledTestData())
 
       s.add_step_text('running recipe: "%s"' % recipe)
     except (loader.LoaderError, ImportError, AssertionError) as e:
       for line in str(e).splitlines():
         s.add_step_text(line)
       s.set_step_status('EXCEPTION')
       return RecipeResult({
           'status_code': 2,
           'reason': str(e),
       })
 
   # Run the steps emitted by a recipe via the engine, emitting annotations
   # into |stream| along the way.
-  return engine.run(recipe_script, api, properties)
+  return engine.run(recipe_script, api)
 
 
-def _isolate_environment():
+def _isolate_environment(rt, env):
   """Isolate the environment to a known subset set."""
-  if sys.platform.startswith('win'):
+  if rt.platform.is_win():
     whitelist = ENV_WHITELIST_WIN
-  elif sys.platform in ('darwin', 'posix', 'linux2'):
+  elif rt.platform.is_posix():
     whitelist = ENV_WHITELIST_POSIX
   else:
-    print ('WARNING: unknown platform %s, not isolating environment.' %
-           sys.platform)
-    return
+    print 'WARNING: unknown platform %s, not isolating environment.' % (
+        rt.platform,)
+    return env
+  return {k: v for k, v in env.iteritems() if k in whitelist}
 
-  for k in os.environ.keys():
-    if k not in whitelist:
-      del os.environ[k]
+
+class Runtime(object):
+  """Container for instance-global state."""
+
+  def __init__(self, properties, platform=None):
+    # Store both the frozen and mutable properties. We will use the frozen ones
+    # internally to ensure recipe engine code doesn't modify them. The
+    # properties client may serve the original properties dict.
+    self._properties = types.freeze(properties)
+    self._properties_dict = copy.deepcopy(properties)
+
+    self._platform = platform if platform else util.Platform.probe()
+
+  @property
+  def properties(self):
+    """Returns (types.FrozenDict): The input properties."""
+    return self._properties
+
+  def mutable_properties(self):
+    """Returns (dict): A copy of the input properties."""
+    return copy.deepcopy(self._properties_dict)
+
+  @property
+  def platform(self):
+    """Returns (util.Platform): The current running Platform."""
+    return self._platform
 
 
 class RecipeEngine(object):
   """
   Knows how to execute steps emitted by a recipe, holds global state such as
   step history and build properties. Each recipe module API has a reference to
   this object.
-
-  Recipe modules that are aware of the engine:
-    * properties - uses engine.properties.
-    * step - uses engine.create_step(...), and previous_step_result.
   """
 
   ActiveStep = collections.namedtuple('ActiveStep', (
       'config', 'step_result', 'open_step'))
 
-  def __init__(self, step_runner, properties, universe_view):
+  def __init__(self, step_runner, rt, universe_view):
     """See run_steps() for parameter meanings."""
     self._step_runner = step_runner
-    self._properties = properties
+    self._rt = rt
     self._universe_view = universe_view
     self._clients = {client.IDENT: client for client in (
         recipe_api.StepClient(self),
-        recipe_api.PropertiesClient(self),
+        recipe_api.PropertiesClient(self._rt),
+        recipe_api.PlatformClient(self._rt.platform),
         recipe_api.DependencyManagerClient(self),
     )}
 
     # A stack of ActiveStep objects, holding the most recently executed step at
     # each nest level (objects deeper in the stack have lower nest levels).
     # When we pop from this stack, we close the corresponding step stream.
     self._step_stack = []
 
-    # TODO(iannucci): come up with a more structured way to advertise/set mode
-    # flags/options for the engine.
-    if '$recipe_engine' in properties:
-      options = properties['$recipe_engine']
-      try:
-        mode_flags = options.get('mode_flags')
-        if mode_flags:
-          if mode_flags.get('use_subprocess42'):
-            print "IGNORING MODE_SUBPROCESS42"
-      except Exception as e:
-        print "Failed to set recipe_engine options, got: %r: %s" % (options, e)
-
   @property
   def properties(self):
-    return self._properties
+    return self._rt.properties
 
   @property
   def universe(self):
     return self._universe_view.universe
 
   def _close_through_level(self, level):
     """Close all open steps whose nest level is >= the supplied level.
 
     Args:
       level (int): the nest level to close through.
@@ skipping 49 matching lines @@
           state = 'EXCEPTION'
           exc = recipe_api.InfraFailure
 
         step_result.presentation.status = state
 
         self._step_stack[-1].open_step.stream.write_line(
             'step returned non-zero exit code: %d' % step_result.retcode)
 
         raise exc(step_config.name, step_result)
 
-  def run(self, recipe_script, api, properties):
+  def run(self, recipe_script, api):
     """Run a recipe represented by a recipe_script object.
 
     This function blocks until recipe finishes.
     It mainly executes the recipe, and has some exception handling logic, and
     adds the step history to the result.
 
     Args:
       recipe_script: The recipe to run, as represented by a RecipeScript object.
       api: The api, with loaded module dependencies.
            Used by the some special modules.
-      properties: a dictionary of properties to pass to the recipe.
 
     Returns:
       RecipeResult which has return value or status code and exception.
     """
     result = None
 
     with self._step_runner.run_context():
       try:
         try:
-          recipe_result = recipe_script.run(api, properties)
+          recipe_result = recipe_script.run(api, self._rt)
           result = {
             "recipe_result": recipe_result,
             "status_code": 0
           }
         finally:
           self._close_through_level(0)
       except recipe_api.StepFailure as f:
         result = {
           # Include "recipe_result" so it doesn't get marked as infra failure.
           "recipe_result": None,
@@ skipping 52 matching lines @@
         results.append(
           loader._invoke_with_properties(
             run_recipe, properties, recipe_script.PROPERTIES,
             properties.keys()))
       except TypeError as e:
         raise TypeError(
             "Got %r while trying to call recipe %s with properties %r" % (
               e, recipe, properties))
 
     return results