contrast-agent 6.11.0 → 6.12.0

data/ext/cs__scope/cs__scope.c

@@ -1,22 +1,35 @@
-/* Copyright (c) 2022 Contrast Security, Inc.  See
+/* Copyright (c) 2023 Contrast Security, Inc.  See
  * https://www.contrastsecurity.com/enduser-terms-0317a for more details. */
 
 #include "cs__scope.h"
 #include "../cs__common/cs__common.h"
 #include <ruby.h>
+#include <stdlib.h>
+
+/*-----------------------------------------
+ |  Calls to Contrast modules and classes
+ ------------------------------------------*/
 
-/* Calls to Contrast modules and classes */
 VALUE contrast, agent, components;
 VALUE scope_interface, scope_inst_methods;
 VALUE scope_mod, scope_klass;
 
-/* helpers */
+/*---------
+ |  Arrays
+ ----------*/
+static char truthy_arr[3][5] = {"true", "True", "TRUE"};
+
+/*----------
+ |  Helpers
+ -----------*/
 
-/* get scope for ec or create new
+/**
+ * @brief get scope for ec or create new
  *
- * [Ruby definition]
+ * @note [Ruby definition] EXECUTION_CONTEXT[Fiber.current] ||=
+ * Contrast::Agent::Scope.new
  *
- *  EXECUTION_CONTEXT[Fiber.current] ||= Contrast::Agent::Scope.new
+ * @return VALUE [Contrast::Agent::Scope]
  */
 VALUE get_ec() {
     VALUE ec, scope_inst, new_inst, keys, fiber;
@@ -36,11 +49,21 @@ VALUE get_ec() {
     }
 }
 
-/* create new Scope class instance */
+/**
+ * @brief  create new Scope class instance
+ *
+ * @return VALUE [Contrast::Agent::Scope]
+ */
 VALUE rb_new_c_scope() {
     return rb_class_new_instance(0, 0, scope_klass);
 }
 
+/**
+ * @brief Increases scope value by 1.
+ *
+ * @param scope int
+ * @return int
+ */
 int scope_increase(int scope) {
     int inc = scope;
     inc = inc + 1;
@@ -48,6 +71,12 @@ int scope_increase(int scope) {
     return INT2FIX(inc);
 }
 
+/**
+ * @brief Decreases scope value by 1.
+ *
+ * @param scope int
+ * @return int
+ */
 int scope_decrease(int scope) {
     int inc = scope;
     inc = inc - 1;
@@ -55,6 +84,12 @@ int scope_decrease(int scope) {
     return INT2FIX(inc);
 }
 
+/**
+ * @brief returns Qfalse or Qtrue if is in defined scope
+ *
+ * @param scope int
+ * @return VALUE
+ */
 VALUE is_in_scope(int scope) {
     if (scope > 0) {
         return Qtrue;
@@ -63,60 +98,105 @@ VALUE is_in_scope(int scope) {
     }
 }
 
-/* default: raise NoMethodError, "Scope '#{ name.inspect }' is not registered as
- * a scope." */
+/**
+ * @error: raise NoMethodError, "Scope '#{ name.inspect }' is not registered as
+ * a scope."
+ */
 void rb_raise_scope_no_method_err(const VALUE method_scope_sym) {
     rb_raise(rb_eNoMethodError,
              "Scope ':%" PRIsVALUE "' is not registered as a scope.",
              rb_sym_to_s(method_scope_sym));
 }
 
-/*
- * @class Contrast::Agent::Scope
- */
+/*---------------------------------
+ |  @class Contrast::Agent::Scope
+ ----------------------------------*/
 
-/*
- * @method initialize
+/**
+ * @brief sets scope instance variables.
+ *
+ * @param self VALUE
+ * @param args VALUE
+ * @return VALUE self
  *
- * sets scope instance variables.
- * def initialize
- *    @contrast_scope = 0
- *    @deserialization_scope = 0
- *    @split_scope = 0
- * end
+ * @note def initialize
+ *        @contrast_scope = 0
+ *        @deserialization_scope = 0
+ *        @split_scope = 0
+ *       end
  */
 VALUE contrast_scope_klass_init(VALUE self, VALUE args) {
-    rb_iv_set(self, rb_iv_cntr_scope, INT2FIX(0));
+    rb_iv_set(self, rb_iv_cntr_scope, contrast_scope_application_update());
     rb_iv_set(self, rb_iv_dslr_scope, INT2FIX(0));
     rb_iv_set(self, rb_iv_split_scope, INT2FIX(0));
 
     return self;
 }
 
-/*
- * @method in_contrast_scope?
- *
- * Check if we are in contrast scope.
+/**
+ * @brief This function will determine if the Application Scope flag is set.
+ * If the value set is not valid the Contrast Scope with start with 0.
+ * If the value is validated, then the Contrast Scope will be set to 1.
+ * If the value is nil the Contrast Scope will be set as default => 0.
  *
- * @return [Boolean] check if we are in contrast scope
+ * To be valid app scope must be one of the truthy_arr: ["true", "True", "TRUE",
+ * "1"]
+ */
+VALUE contrast_scope_application_update() {
+    /**
+     * ENV variables are null-terminated strings.
+     *
+     * getenv() returns a pointer to a string within the environment list.
+     * The caller must take care not to modify this string,
+     * since that would change the environment of the process.
+     *
+     * [ Do not touch, do not free. We don't control it! ]
+     */
+    char *eVar = getenv(c_const_ctr_agent_app_scope);
+    VALUE app_scope = eVar;
+
+    /* check to see if the ENV variable is set */
+    if (RTEST(app_scope)) {
+        /* Application Scope is set*/
+        for (int i = 0; i < sizeof(truthy_arr) / sizeof(truthy_arr[0]); i++) {
+            if (strcmp(eVar, truthy_arr[i]) == 0) {
+                return INT2FIX(1);
+            }
+        }
+        /* this covers all of the false values */
+        return INT2FIX(0);
+    } else {
+        /* Application Scope is not set ( NULL )*/
+        return INT2FIX(0);
+    }
+}
+
+/**
+ * @brief Check if we are in contrast scope.
+ * @note  @method in_contrast_scope?
+ * @param self VALUE
+ * @param args VALUE
+ * @return VALUE [Boolean] check if we are in contrast scope
  *                    if the scope is above 0 return true.
- * def in_contrast_scope?
- *  @contrast_scope.positive?
- * end
+ *
+ * @note def in_contrast_scope?
+ *        @contrast_scope.positive?
+ *       end
  */
 VALUE in_cntr_scope(VALUE self, VALUE args) {
     return is_in_scope(FIX2INT(rb_iv_get(self, rb_iv_cntr_scope)));
 }
 
-/*
- * @method enter_contrast_scope!
+/**
+ * @brief Enters contrast scope.
  *
- * Enters contrast scope.
+ * @param self VALUE
+ * @param args VALUE
+ * @return VALUE [Integer] contrast scope increased.
  *
- * @return @contrast_scope [Integer] contrast scope increased.
- * def enter_contrast_scope!
- *    @contrast_scope += 1
- * end
+ * @note def enter_contrast_scope!
+ *        @contrast_scope += 1
+ *       end
  */
 VALUE enter_cntr_scope(VALUE self, VALUE args) {
     int scope = FIX2INT(rb_iv_get(self, rb_iv_cntr_scope));
@@ -125,15 +205,16 @@ VALUE enter_cntr_scope(VALUE self, VALUE args) {
     return rb_iv_get(self, rb_iv_cntr_scope);
 }
 
-/*
- * @method exit_contrast_scope!
+/**
+ * @brief Exits contrast scope.
  *
- * Exits contrast scope.
+ * @param self VALUE
+ * @param args VALUE
+ * @return VALUE [Integer] contrast scope decreased.
  *
- * @return @contrast_scope [Integer] contrast scope decreased.
- * def exit_contrast_scope!
- *    @contrast_scope -= 1
- * end
+ * @note def exit_contrast_scope!
+ *         @contrast_scope -= 1
+ *       end
  */
 VALUE exit_cntr_scope(VALUE self, VALUE args) {
     int scope = FIX2INT(rb_iv_get(self, rb_iv_cntr_scope));
@@ -142,30 +223,32 @@ VALUE exit_cntr_scope(VALUE self, VALUE args) {
     return rb_iv_get(self, rb_iv_cntr_scope);
 }
 
-/*
- * @method in_deserialization_scope?
- *
- * Check if we are in deserialization scope.
+/**
+ * @brief Check if we are in deserialization scope.
  *
- * @return [Boolean] check if we are in deserialization scope
+ * @param self VALUE
+ * @param args VALUE
+ * @return VALUE [Boolean] check if we are in deserialization scope
  *                    if the scope is above 0 return true.
- * def in_deserialization_scope?
- *  @deserialization_scope.positive?
- * end
+ *
+ * @note  def in_deserialization_scope?
+ *         @deserialization_scope.positive?
+ *        end
  */
 VALUE in_dslr_scope(VALUE self, VALUE args) {
     return is_in_scope(FIX2INT(rb_iv_get(self, rb_iv_dslr_scope)));
 }
 
-/*
- * @method enter_deserialization_scope!
+/**
+ * @brief Enters deserialization scope.
  *
- * Enters deserialization scope.
+ * @param self VALUE
+ * @param args VALUE
+ * @return VALUE [Integer] deserialization scope increased.
  *
- * @return @deserialization_scope [Integer] deserialization scope increased.
- * def enter_deserialization_scope!
- *    @deserialization_scope += 1
- * end
+ * @note def enter_deserialization_scope!
+ *         @deserialization_scope += 1
+ *       end
  */
 VALUE enter_dsrl_scope(VALUE self, VALUE args) {
     int scope = FIX2INT(rb_iv_get(self, rb_iv_dslr_scope));
@@ -174,15 +257,17 @@ VALUE enter_dsrl_scope(VALUE self, VALUE args) {
     return rb_iv_get(self, rb_iv_dslr_scope);
 }
 
-/*
- * @method exit_deserialization_scope!
+/**
+ * @brief Exits deserialization scope.
  *
- * Exits deserialization scope.
+ * @param self VALUE
+ * @param args VALUE
+ * @return VALUE [Integer] deserialization scope decreased.
  *
- * @return @deserialization_scope [Integer] deserialization scope decreased.
- * def enter_deserialization_scope!
- *    @deserialization_scope += 1
- * end
+ * @note def enter_deserialization_scope!
+ *        @deserialization_scope += 1
+ *       end
+
  */
 VALUE exit_dsrl_scope(VALUE self, VALUE args) {
     int scope = FIX2INT(rb_iv_get(self, rb_iv_dslr_scope));
@@ -191,30 +276,32 @@ VALUE exit_dsrl_scope(VALUE self, VALUE args) {
     return rb_iv_get(self, rb_iv_dslr_scope);
 }
 
-/*
- * @method in_split_scope?
- *
- * Check if we are in split scope.
+/**
+ * @brief Check if we are in split scope.
  *
- * @return [Boolean] check if we are in split scope
+ * @param self VALUE
+ * @param args VALUE
+ * @return VALUE [Boolean] check if we are in split scope
  *                    if the scope is above 0 return true.
- * def in_split_scope?
- *  @split_scope.positive?
- * end
+ *
+ * @note  def in_split_scope?
+ *          @split_scope.positive?
+ *        end
  */
 VALUE in_split_scope(VALUE self, VALUE args) {
     return is_in_scope(FIX2INT(rb_iv_get(self, rb_iv_split_scope)));
 }
 
-/*
- * @method enter_split_scope!
+/**
+ * @brief Enters split scope.
  *
- * Enters split scope.
+ * @param self VALUE
+ * @param args VALUE
+ * @return VALUE [Integer] split scope increased.
  *
- * @return @split_scope [Integer] split scope increased.
- * def enter_split_scope!
- *    @split_scope += 1
- * end
+ * @note def enter_split_scope!
+ *         @split_scope += 1
+ *       end
  */
 VALUE enter_split_scope(VALUE self, VALUE args) {
     int scope = FIX2INT(rb_iv_get(self, rb_iv_split_scope));
@@ -223,15 +310,16 @@ VALUE enter_split_scope(VALUE self, VALUE args) {
     return rb_iv_get(self, rb_iv_split_scope);
 }
 
-/*
- * @method exit_split_scope!
+/**
+ * @brief Exits split scope.
  *
- * Exits split scope.
+ * @param self VALUE
+ * @param args VALUE
+ * @return VALUE [Integer] split scope decreased.
  *
- * @return @split_scope [Integer] split scope decreased.
- * def enter_split_scope!
- *    @split_scope -= 1
- * end
+ * @note def enter_split_scope!
+ *         @split_scope -= 1
+ *       end
  */
 VALUE exit_split_scope(VALUE self, VALUE args) {
     int scope = FIX2INT(rb_iv_get(self, rb_iv_split_scope));
@@ -240,44 +328,47 @@ VALUE exit_split_scope(VALUE self, VALUE args) {
     return rb_iv_get(self, rb_iv_split_scope);
 }
 
-/*
- * @method split_scope_depth
+/**
+ * @brief Returns split scope current depth.
  *
- * Returns split scope current depth.
+ * @param self VALUE
+ * @param args VALUE
+ * @return VALUE [Integer]
  *
- * @return @split_scope [Integer]
- * def split_scope_depth
- *    @split_scope
- * end
+ * @note def split_scope_depth
+ *        @split_scope
+ *       end
  */
 VALUE split_scope_depth(VALUE self, VALUE args) {
     return rb_iv_get(self, rb_iv_split_scope);
 }
 
-/*
+/**
  * Static methods to be used, the cases are defined by the usage from the above
  * methods if more methods are added - please extend the case statements as they
- * are no longed dynamic
+ * are no longed dynamic.
  */
 
-/*
- * @method in_scope?
- *
- * Check if we are in specific scope.
- *
- * @param name [Symbol] scope symbol representing scope to check.
- * @return [Boolean] check if we are in passed scope.
- * def in_scope? name
- *    case name
- *    when :contrast
- *      in_contrast_scope?
- *    when :deserialization
- *      in_deserialization_scope?
- *    when :split
- *      in_split_scope?
- *    else
- *      raise NoMethodError, "Scope '#{ name.inspect }' is not registered as a
- * scope." end end
+/**
+ * @brief Check if we are in specific scope.
+ *
+ * @param self VALUE
+ * @param method_scope_sym VALUE [Symbol] scope symbol representing scope to
+ * check.
+ * @return VALUE [Boolean] check if we are in passed scope.
+ * @error: NoMethodError
+ *
+ * @note def in_scope? name
+ *         case name
+ *         when :contrast
+ *           in_contrast_scope?
+ *         when :deserialization
+ *           in_deserialization_scope?
+ *         when :split
+ *           in_split_scope?
+ *         else
+ *           raise NoMethodError, "Scope '#{ name.inspect }' is not registered
+ * as a scope." end end
  */
 VALUE scope_klass_in_scope(VALUE self, VALUE method_scope_sym) {
     VALUE in_scope = Qnil;
@@ -298,24 +389,25 @@ VALUE scope_klass_in_scope(VALUE self, VALUE method_scope_sym) {
     return in_scope;
 }
 
-/*
- * @method enter_scope!
- *
- * Enters specific scope.
- *
- * @param name [Symbol] scope symbol representing scope to enter.
- * @return [Boolean] entered scope value increased.
- * def enter_scope! name
- *   case name
- *    when :contrast
- *      enter_contrast_scope!
- *    when :deserialization
- *      enter_deserialization_scope!
- *    when :split
- *      enter_split_scope!
- *    else
- *      raise NoMethodError, "Scope '#{ name.inspect }' is not registered as a
- * scope." end end
+/**
+ * @brief Enters specific scope.
+ *
+ * @param self VALUE
+ * @param method_scope_sym VALUE [Symbol] scope symbol representing scope to
+ * enter.
+ * @return VALUE [Boolean] entered scope value increased.
+ *
+ * @note def enter_scope! name
+ *         case name
+ *       when :contrast
+ *         enter_contrast_scope!
+ *       when :deserialization
+ *         enter_deserialization_scope!
+ *       when :split
+ *         enter_split_scope!
+ *       else
+ *         raise NoMethodError, "Scope '#{ name.inspect }' is not registered as
+ * a scope." end end
  */
 VALUE scope_klass_enter_scope(VALUE self, VALUE method_scope_sym) {
     VALUE enter_scope = Qnil;
@@ -333,13 +425,15 @@ VALUE scope_klass_enter_scope(VALUE self, VALUE method_scope_sym) {
     return enter_scope;
 }
 
-/*
- * @method exit_scope!
+/**
+ * @brief Exits specific scope.
  *
- * Exits specific scope.
+ * @param self VALUE
+ * @param method_scope_sym VALUE [Symbol] scope symbol representing scope to
+ * exit.
+ * @return VALUE [Boolean] entered scope value decreased.
  *
- * @param name [Symbol] scope symbol representing scope to exit.
- * @return [Boolean] entered scope value decreased.
+ * @note
  * def exit_scope! name
  *   case name
  *    when :contrast
@@ -368,18 +462,18 @@ VALUE scope_klass_exit_scope(VALUE self, VALUE method_scope_sym) {
     return exit_scope;
 }
 
-/*
- * @class Contrast::Components::Interface
- */
+/*-----------------------------------------
+ |  @class Contrast::Components::Interface
+ ------------------------------------------*/
 
-/* @method #initialize
- *
- * init set new scope for current fiber
- * @return ec [Hash<Fiber => Scope>]
+/**
+ * @brief init set new scope for current fiber
  *
- * [Ruby definition]
+ * @param self VALUE
+ * @param args VALUE
+ * @return VALUE [Hash<Fiber => Scope>] ec
  *
- * EXECUTION_CONTEXT[Fiber.current] = Contrast::Agent::Scope.new
+ * @note EXECUTION_CONTEXT[Fiber.current] = Contrast::Agent::Scope.new
  */
 VALUE contrast_scope_interface_init(VALUE self, VALUE args) {
     VALUE ec = rb_const_get(scope_mod, rb_intern(rb_const_ec));
@@ -388,26 +482,24 @@ VALUE contrast_scope_interface_init(VALUE self, VALUE args) {
     return ec;
 }
 
-/*
- * @method #scope_for_current_ec
- *
- * This returns the scope governing the current execution context. Use this
- * sparingly, preferring the instance & class methods to access and query scope,
- * rather than interacting with the scope object directly.
+/**
+ * @brief This returns the scope governing the current execution context. Use
+ * this sparingly, preferring the instance & class methods to access and query
+ * scope, rather than interacting with the scope object directly.
  *
  * Alternative to Monitor => mutex.synchronize
  * rb_mutex_new(void)
  * rb_mutex_synchronize (VALUE mutex, VALUE(*func)(VALUE arg), VALUE arg)
  * Mutex.synchronize do ... end goes here:
  *
+ * @param self VALUE
+ * @param args VALUE
+ * @return VALUE
  *
- * [ruby definition]
- *
- *  def scope_for_current_ec
- *    MONITOR.synchronize do
- *      return EXECUTION_CONTEXT[Fiber.current] ||= Contrast::Agent::Scope.new
- *    end
- *  end
+ * @note def scope_for_current_ec
+ *         MONITOR.synchronize do
+ *           return EXECUTION_CONTEXT[Fiber.current] ||=
+ * Contrast::Agent::Scope.new end end
  */
 VALUE contrast_scope_for_current_ec(VALUE self, VALUE args) {
     /* synchronize */
@@ -416,26 +508,23 @@ VALUE contrast_scope_for_current_ec(VALUE self, VALUE args) {
     return rb_mutex_synchronize(mutex, get_ec, 0);
 }
 
-/*
- * @module Contrast::Components::Scope::InstanceMethods
- */
+/*--------------------------------------------------------
+ |  @module Contrast::Components::Scope::InstanceMethods
+ ---------------------------------------------------------*/
 
-/*
- * @method #enter_method_scope!
- *
- * Iterates over the method policy's scopes and enters in each one.
+/**
+ * @brief Iterates over the method policy's scopes and enters in each one.
  *
- *     @param scopes_to_enter   [Array<Symbol>] Scopes form
+ * @param self VALUE
+ * @param scopes_to_enter VALUE [Array<Symbol>] Scopes form
  * method_policy#scopes_to_enter for the scope current method policy
- *     @return scopes_to_enter [Array<Symbol>]
- *
- * [Ruby definition]
+ * @return VALUE [Array<Symbol>] scopes_to_enter
  *
- *     def enter_method_scope! scopes_to_enter
- *       scopes_to_enter.each do |scope|
- *        enter_scope!(scope)
+ * @note def enter_method_scope! scopes_to_enter
+ *        scopes_to_enter.each do |scope|
+ *         enter_scope!(scope)
+ *       end
  *      end
- *    end
  */
 VALUE inst_methods_enter_method_scope(VALUE self, VALUE scopes_to_enter) {
     VALUE scopes_ary, scope;
@@ -451,22 +540,19 @@ VALUE inst_methods_enter_method_scope(VALUE self, VALUE scopes_to_enter) {
     return scopes_to_enter;
 }
 
-/*
- * @method #exit_method_scope!
- *
- * Iterates over the method policy's scopes and exits each one.
+/**
+ * @brief Iterates over the method policy's scopes and exits each one.
  *
- *     @param scopes_to_exit   [Array<Symbol>] Scopes form
+ * @param self VALUE
+ * @param scopes_to_exit VALUE [Array<Symbol>] Scopes form
  * method_policy#scopes_to_exit for the scope current method policy
- *     @return scopes_to_exit [Array<Symbol>]
+ * @return VALUE [Array<Symbol>] scopes_to_exit
  *
- * [Ruby definition]
- *
- *     def enter_method_scope! scopes_to_exit
- *       scopes_to_exit.each do |scope|
- *        enter_scope!(scope)
+ * @note def enter_method_scope! scopes_to_exit
+ *         scopes_to_exit.each do |scope|
+ *          enter_scope!(scope)
+ *        end
  *      end
- *    end
  */
 VALUE inst_methods_exit_method_scope(VALUE self, VALUE scopes_to_exit) {
     VALUE scopes_ary, scope;
@@ -482,19 +568,34 @@ VALUE inst_methods_exit_method_scope(VALUE self, VALUE scopes_to_exit) {
     return scopes_to_exit;
 }
 
-/* For the InstanceMethods we need to call all the scope methods from the
+/**
+ * For the InstanceMethods we need to call all the scope methods from the
  * current ec context All methods bellow are with same names as
  * Contrast::Agent::Scope class with the difference that they act as forwarders:
- * exp:
  *    def in_contrast_scope?
  *      scope_for_current_ec.in_contrast_scope?
  *    end
  */
+
+/**
+ * @brief scope_for_current_ec.in_contrast_scope?
+ *
+ * @param self VALUE
+ * @param args VALUE
+ * @return VALUE
+ */
 VALUE inst_methods_in_cntr_scope(VALUE self, VALUE args) {
     return is_in_scope(FIX2INT(
         rb_iv_get(contrast_scope_for_current_ec(self, 0), rb_iv_cntr_scope)));
 }
 
+/**
+ * @brief scope_for_current_ec.enter_contrast_scope!
+ *
+ * @param self VALUE
+ * @param args VALUE
+ * @return VALUE
+ */
 VALUE inst_methods_enter_cntr_scope(VALUE self, VALUE args) {
     int scope = FIX2INT(
         rb_iv_get(contrast_scope_for_current_ec(self, 0), rb_iv_cntr_scope));
@@ -504,6 +605,13 @@ VALUE inst_methods_enter_cntr_scope(VALUE self, VALUE args) {
     return rb_iv_get(contrast_scope_for_current_ec(self, 0), rb_iv_cntr_scope);
 }
 
+/**
+ * @brief scope_for_current_ec.exit_contrast_scope!
+ *
+ * @param self VALUE
+ * @param args VALUE
+ * @return VALUE
+ */
 VALUE inst_methods_exit_cntr_scope(VALUE self, VALUE args) {
     int scope = FIX2INT(
         rb_iv_get(contrast_scope_for_current_ec(self, 0), rb_iv_cntr_scope));
@@ -513,11 +621,25 @@ VALUE inst_methods_exit_cntr_scope(VALUE self, VALUE args) {
     return rb_iv_get(contrast_scope_for_current_ec(self, 0), rb_iv_cntr_scope);
 }
 
+/**
+ * @brief scope_for_current_ec.in_split_scope?
+ *
+ * @param self VALUE
+ * @param args VALUE
+ * @return VALUE
+ */
 VALUE inst_methods_in_split_scope(VALUE self, VALUE args) {
     return is_in_scope(FIX2INT(
         rb_iv_get(contrast_scope_for_current_ec(self, 0), rb_iv_split_scope)));
 }
 
+/**
+ * @brief scope_for_current_ec.enter_split_scope!
+ *
+ * @param self VALUE
+ * @param args VALUE
+ * @return VALUE
+ */
 VALUE inst_methods_enter_split_scope(VALUE self, VALUE args) {
     int scope = FIX2INT(
         rb_iv_get(contrast_scope_for_current_ec(self, 0), rb_iv_split_scope));
@@ -526,6 +648,13 @@ VALUE inst_methods_enter_split_scope(VALUE self, VALUE args) {
                      scope_increase(scope));
 }
 
+/**
+ * @brief scope_for_current_ec.exit_split_scope!
+ *
+ * @param self VALUE
+ * @param args VALUE
+ * @return VALUE
+ */
 VALUE inst_methods_exit_split_scope(VALUE self, VALUE args) {
     int scope = FIX2INT(
         rb_iv_get(contrast_scope_for_current_ec(self, 0), rb_iv_split_scope));
@@ -535,15 +664,36 @@ VALUE inst_methods_exit_split_scope(VALUE self, VALUE args) {
     return rb_iv_get(contrast_scope_for_current_ec(self, 0), rb_iv_split_scope);
 }
 
+/**
+ * @brief Get Deserialization scope iv.
+ *
+ * @param self
+ * @param args
+ * @return VALUE
+ */
 VALUE inst_methods_split_scope_depth(VALUE self, VALUE args) {
     return rb_iv_get(contrast_scope_for_current_ec(self, 0), rb_iv_split_scope);
 }
 
+/**
+ * @brief scope_for_current_ec.in_deserialization_scope?
+ *
+ * @param self VALUE
+ * @param args VALUE
+ * @return VALUE
+ */
 VALUE inst_methods_in_dsrl_scope(VALUE self, VALUE args) {
     return is_in_scope(FIX2INT(
         rb_iv_get(contrast_scope_for_current_ec(self, 0), rb_iv_dslr_scope)));
 }
 
+/**
+ * @brief scope_for_current_ec.enter_deserialization_scope!
+ *
+ * @param self VALUE
+ * @param args VALUE
+ * @return VALUE
+ */
 VALUE inst_methods_enter_dsrl_scope(VALUE self, VALUE args) {
     int scope = FIX2INT(
         rb_iv_get(contrast_scope_for_current_ec(self, 0), rb_iv_dslr_scope));
@@ -553,6 +703,13 @@ VALUE inst_methods_enter_dsrl_scope(VALUE self, VALUE args) {
     return rb_iv_get(contrast_scope_for_current_ec(self, 0), rb_iv_dslr_scope);
 }
 
+/**
+ * @brief scope_for_current_ec.exit_deserialization_scope!
+ *
+ * @param self VALUE
+ * @param args VALUE
+ * @return VALUE
+ */
 VALUE inst_methods_exit_dsrl_scope(VALUE self, VALUE args) {
     int scope = FIX2INT(
         rb_iv_get(contrast_scope_for_current_ec(self, 0), rb_iv_dslr_scope));
@@ -562,6 +719,15 @@ VALUE inst_methods_exit_dsrl_scope(VALUE self, VALUE args) {
     return rb_iv_get(contrast_scope_for_current_ec(self, 0), rb_iv_dslr_scope);
 }
 
+/**
+ * @brief Check to see if we are in scope by parameter symbol passed. Raises
+ * error if symbol is not valid.
+ *
+ * @param self VALUE
+ * @param method_scope_sym VALUE [Symbol]
+ * @error: rb_raise_scope_no_method_err [NoMethodError]
+ * @return VALUE
+ */
 VALUE inst_methods_in_scope(VALUE self, VALUE method_scope_sym) {
     if (method_scope_sym == rb_sym_contrast) {
         inst_methods_in_cntr_scope(self, 0);
@@ -574,6 +740,15 @@ VALUE inst_methods_in_scope(VALUE self, VALUE method_scope_sym) {
     }
 }
 
+/**
+ * @brief Enters scope by parameter symbol passed. Raises error if symbol is not
+ * valid.
+ *
+ * @param self VALUE
+ * @param method_scope_sym VALUE [Symbol]
+ * @error: rb_raise_scope_no_method_err [NoMethodError]
+ * @return VALUE
+ */
 VALUE inst_methods_enter_scope(VALUE self, VALUE method_scope_sym) {
     if (method_scope_sym == rb_sym_contrast) {
         inst_methods_enter_cntr_scope(self, 0);
@@ -586,6 +761,15 @@ VALUE inst_methods_enter_scope(VALUE self, VALUE method_scope_sym) {
     }
 }
 
+/**
+ * @brief Exits scope by parameter symbol passed. Raises error if symbol is not
+ * valid.
+ *
+ * @param self VALUE
+ * @param method_scope_sym VALUE [Symbol]
+ * @error: rb_raise_scope_no_method_err [NoMethodError]
+ * @return VALUE
+ */
 VALUE inst_methods_exit_scope(VALUE self, VALUE method_scope_sym) {
     if (method_scope_sym == rb_sym_contrast) {
         inst_methods_exit_cntr_scope(self, 0);
@@ -598,22 +782,16 @@ VALUE inst_methods_exit_scope(VALUE self, VALUE method_scope_sym) {
     }
 }
 
-/*
- *   @module Contrast::Components::Scope
- *
- *   TODO: RUBY-534, #sweep_dead_ecs compensates for a lack of weak tables. when
+/**
+ * @brief Sweeps and cleans any unused Execution Contexts.
+ * TODO: RUBY-534, #sweep_dead_ecs compensates for a lack of weak tables. when
  * we can use WeakRef, we should investigate removing this call and instead use
  * the WeakRef for the Execution Context's Keys or using our Finalizers Hash for
  * Fibers
  *
- *   [Ruby definition]
- *
- *    MONITOR.synchronize do
- *      EXECUTION_CONTEXT.delete_if do |ec, _scope|
- *        !ec.alive?
- *      end
- *    end
- *   end
+ * @param self VALUE
+ * @param args VALUE
+ * @return VALUE
  */
 VALUE scope_mod_sweep_dead_ecs(VALUE self, VALUE args) {
     VALUE mutex, ec, ec_keys, key, test;
@@ -649,6 +827,7 @@ void Init_cs__scope() {
     rb_const_mon = "MONITOR";
     rb_const_ec = "EXECUTION_CONTEXT";
     rb_const_ec_keys = "EC_KEYS";
+    c_const_ctr_agent_app_scope = "CONTRAST__AGENT__RUBY__APPLICATION_SCOPE";
 
     /* Symbols */
     rb_sym_scope_mod = rb_intern("Scope");
@@ -675,6 +854,7 @@ void Init_cs__scope() {
 
     /* Define the new scope modules and objects */
     contrast = rb_define_module("Contrast");
+    /* contrast::Agent */
     agent = rb_define_module_under(contrast, "Agent");
     /* components => Contrast::Components */
     components = rb_define_module_under(contrast, "Components");
@@ -687,7 +867,7 @@ void Init_cs__scope() {
     /* scope_klass => Contrast::Agent::Scope */
     scope_klass = rb_define_class_under(agent, "Scope", rb_cObject);
 
-    /*
+    /**
      * @class Contrast::Agent::Scope
      */
 
@@ -721,7 +901,7 @@ void Init_cs__scope() {
     rb_define_method(scope_klass, rb_method_name_exit_scope,
                      scope_klass_exit_scope, 1);
 
-    /*
+    /**
      * @class Contrast::Components::Interface
      */
 
@@ -732,7 +912,7 @@ void Init_cs__scope() {
     rb_define_method(scope_interface, rb_method_name_scope_for_current_ec,
                      contrast_scope_for_current_ec, 0);
 
-    /*
+    /**
      * @module Contrast::Components::Scope
      */
 
@@ -742,10 +922,10 @@ void Init_cs__scope() {
     rb_const_set(scope_mod, rb_intern(rb_const_ec_keys), rb_ary_new());
     /* Contrast::Components::Scope::EXECUTION_CONTEXT => {} */
     rb_define_const(scope_mod, rb_const_ec, rb_hash_new());
-    /* Contrast::Components::Scope::MONITOR => Mutex.new */
+    /* Contrast::Components::Scope::MONITOR => Mutex.new.freeze */
     rb_define_const(scope_mod, rb_const_mon, rb_mutex_new());
 
-    /*
+    /**
      * @module Contrast::Components::Scope::InstanceMethods
      */
 
@@ -780,13 +960,16 @@ void Init_cs__scope() {
     rb_define_method(scope_inst_methods, rb_method_name_exit_scope,
                      inst_methods_exit_scope, 1);
 
-    /*
+    /**
      * @module Contrast::Components::Scope
      */
     rb_define_singleton_method(scope_mod, "sweep_dead_ecs",
                                scope_mod_sweep_dead_ecs, 0);
+    /* Contrast::Components::Scope#cs__with_app_scope? */
+    rb_define_singleton_method(scope_mod, "cs__with_app_scope?",
+                               contrast_scope_application_update, 0);
 
-    /*
+    /**
      * @module Contrast::Components::Scope::InstanceMethods
      */
     rb_define_method(scope_inst_methods, "contrast_enter_method_scopes!",