ddeutil-workflow 0.0.50__py3-none-any.whl → 0.0.51__py3-none-any.whl

ddeutil/workflow/stages.py

@@ -56,9 +56,10 @@ from typing_extensions import Self
 from .__types import DictData, DictStr, TupleStr
 from .conf import dynamic
 from .exceptions import StageException, UtilException, to_dict
-from .result import FAILED, SUCCESS, WAIT, Result, Status
+from .result import CANCEL, FAILED, SUCCESS, WAIT, Result, Status
 from .reusables import TagFunc, extract_call, not_in_template, param2template
 from .utils import (
+    delay,
     filter_func,
     gen_id,
     make_exec,
@@ -72,7 +73,8 @@ class BaseStage(BaseModel, ABC):
     metadata. If you want to implement any custom stage, you can use this class
     to parent and implement ``self.execute()`` method only.
 
-        This class is the abstraction class for any stage class.
+        This class is the abstraction class for any stage model that want to
+    implement to workflow model.
     """
 
     extras: DictData = Field(
@@ -226,7 +228,7 @@ class BaseStage(BaseModel, ABC):
         and want to set on the `to` like;
 
             ... (i)   output: {'foo': bar}
-            ... (ii)  to: {}
+            ... (ii)  to: {'stages': {}}
 
             The result of the `to` argument will be;
 
@@ -234,11 +236,15 @@ class BaseStage(BaseModel, ABC):
                         'stages': {
                             '<stage-id>': {
                                 'outputs': {'foo': 'bar'},
-                                'skipped': False
+                                'skipped': False,
                             }
                         }
                     }
 
+        Important:
+            This method is use for reconstruct the result context and transfer
+        to the `to` argument.
+
         :param output: (DictData) An output data that want to extract to an
             output key.
         :param to: (DictData) A context data that want to add output result.
@@ -269,7 +275,11 @@ class BaseStage(BaseModel, ABC):
             if "skipped" in output
             else {}
         )
-        to["stages"][_id] = {"outputs": output, **skipping, **errors}
+        to["stages"][_id] = {
+            "outputs": copy.deepcopy(output),
+            **skipping,
+            **errors,
+        }
         return to
 
     def get_outputs(self, outputs: DictData) -> DictData:
@@ -330,6 +340,7 @@ class BaseStage(BaseModel, ABC):
 
 
 class BaseAsyncStage(BaseStage):
+    """Base Async Stage model."""
 
     @abstractmethod
     def execute(
@@ -432,12 +443,13 @@ class EmptyStage(BaseAsyncStage):
 
     echo: Optional[str] = Field(
         default=None,
-        description="A string statement that want to logging",
+        description="A string message that want to show on the stdout.",
     )
     sleep: float = Field(
         default=0,
-        description="A second value to sleep before start execution",
+        description="A second value to sleep before start execution.",
         ge=0,
+        lt=1800,
     )
 
     def execute(
@@ -464,12 +476,23 @@ class EmptyStage(BaseAsyncStage):
         :rtype: Result
         """
         result: Result = result or Result(
-            run_id=gen_id(self.name + (self.id or ""), unique=True)
+            run_id=gen_id(self.name + (self.id or ""), unique=True),
+            extras=self.extras,
         )
 
+        if not self.echo:
+            message: str = "..."
+        else:
+            message: str = param2template(
+                dedent(self.echo), params, extras=self.extras
+            )
+            if "\n" in self.echo:
+                message: str = "\n\t" + message.replace("\n", "\n\t").strip(
+                    "\n"
+                )
+
         result.trace.info(
-            f"[STAGE]: Empty-Execute: {self.name!r}: "
-            f"( {param2template(self.echo, params, extras=self.extras) or '...'} )"
+            f"[STAGE]: Empty-Execute: {self.name!r}: ( {message} )"
         )
         if self.sleep > 0:
             if self.sleep > 5:
@@ -497,9 +520,10 @@ class EmptyStage(BaseAsyncStage):
 
         :rtype: Result
         """
-        if result is None:  # pragma: no cov
+        if result is None:
             result: Result = Result(
-                run_id=gen_id(self.name + (self.id or ""), unique=True)
+                run_id=gen_id(self.name + (self.id or ""), unique=True),
+                extras=self.extras,
             )
 
         await result.trace.ainfo(
@@ -540,8 +564,8 @@ class BashStage(BaseStage):
     env: DictStr = Field(
         default_factory=dict,
         description=(
-            "An environment variable mapping that want to set before execute "
-            "this shell statement."
+            "An environment variables that set before start execute by adding "
+            "on the header of the `.sh` file."
         ),
     )
 
@@ -603,7 +627,8 @@ class BashStage(BaseStage):
         """
         if result is None:  # pragma: no cov
             result: Result = Result(
-                run_id=gen_id(self.name + (self.id or ""), unique=True)
+                run_id=gen_id(self.name + (self.id or ""), unique=True),
+                extras=self.extras,
             )
 
         bash: str = param2template(
@@ -616,7 +641,7 @@ class BashStage(BaseStage):
             env=param2template(self.env, params, extras=self.extras),
             run_id=result.run_id,
         ) as sh:
-            result.trace.debug(f"... Start create `{sh[1]}` file.")
+            result.trace.debug(f"... Create `{sh[1]}` file.")
             rs: CompletedProcess = subprocess.run(
                 sh, shell=False, capture_output=True, text=True
             )
@@ -660,18 +685,20 @@ class PyStage(BaseStage):
     """
 
     run: str = Field(
-        description="A Python string statement that want to run with exec.",
+        description="A Python string statement that want to run with `exec`.",
     )
     vars: DictData = Field(
         default_factory=dict,
         description=(
-            "A mapping to variable that want to pass to globals in exec."
+            "A variable mapping that want to pass to globals parameter in the "
+            "`exec` func."
         ),
     )
 
     @staticmethod
     def filter_locals(values: DictData) -> Iterator[str]:
-        """Filter a locals input values.
+        """Filter a locals mapping values that be module, class, or
+        __annotations__.
 
         :param values: (DictData) A locals values that want to filter.
 
@@ -728,7 +755,8 @@ class PyStage(BaseStage):
         """
         if result is None:  # pragma: no cov
             result: Result = Result(
-                run_id=gen_id(self.name + (self.id or ""), unique=True)
+                run_id=gen_id(self.name + (self.id or ""), unique=True),
+                extras=self.extras,
             )
 
         lc: DictData = {}
@@ -741,11 +769,11 @@ class PyStage(BaseStage):
 
         # NOTE: Start exec the run statement.
         result.trace.info(f"[STAGE]: Py-Execute: {self.name}")
-        result.trace.warning(
-            "[STAGE]: This stage allow use `eval` function, so, please "
-            "check your statement be safe before execute."
-        )
-
+        # result.trace.warning(
+        #     "[STAGE]: This stage allow use `eval` function, so, please "
+        #     "check your statement be safe before execute."
+        # )
+        #
         # WARNING: The exec build-in function is very dangerous. So, it
         #   should use the re module to validate exec-string before running.
         exec(
@@ -811,11 +839,17 @@ class CallStage(BaseStage):
         :param event: (Event) An event manager that use to track parent execute
             was not force stopped.
 
+        :raise ValueError: If necessary arguments does not pass from the `args`
+            field.
+        :raise TypeError: If the result from the caller function does not by
+            a `dict` type.
+
         :rtype: Result
         """
         if result is None:  # pragma: no cov
             result: Result = Result(
-                run_id=gen_id(self.name + (self.id or ""), unique=True)
+                run_id=gen_id(self.name + (self.id or ""), unique=True),
+                extras=self.extras,
             )
 
         has_keyword: bool = False
@@ -890,9 +924,12 @@ class CallStage(BaseStage):
         """Parse Pydantic model from any dict data before parsing to target
         caller function.
 
-        :param func:
-        :param args:
-        :param result: (Result)
+        :param func: A tag function that want to get typing.
+        :param args: An arguments before passing to this tag function.
+        :param result: (Result) A result object for keeping context and status
+            data.
+
+        :rtype: DictData
         """
         try:
             type_hints: dict[str, Any] = get_type_hints(func)
@@ -965,22 +1002,29 @@ class TriggerStage(BaseStage):
 
         :rtype: Result
         """
+        from .exceptions import WorkflowException
         from .workflow import Workflow
 
         if result is None:
             result: Result = Result(
-                run_id=gen_id(self.name + (self.id or ""), unique=True)
+                run_id=gen_id(self.name + (self.id or ""), unique=True),
+                extras=self.extras,
             )
 
         _trigger: str = param2template(self.trigger, params, extras=self.extras)
         result.trace.info(f"[STAGE]: Trigger-Execute: {_trigger!r}")
-        rs: Result = Workflow.from_conf(
-            _trigger, extras=self.extras | {"stage_raise_error": True}
-        ).execute(
-            params=param2template(self.params, params, extras=self.extras),
-            result=result,
-            event=event,
-        )
+        try:
+            rs: Result = Workflow.from_conf(
+                name=_trigger,
+                extras=self.extras | {"stage_raise_error": True},
+            ).execute(
+                params=param2template(self.params, params, extras=self.extras),
+                parent_run_id=result.run_id,
+                event=event,
+            )
+        except WorkflowException as e:
+            raise StageException("Trigger workflow stage was failed") from e
+
         if rs.status == FAILED:
             err_msg: str | None = (
                 f" with:\n{msg}"
@@ -1020,17 +1064,25 @@ class ParallelStage(BaseStage):  # pragma: no cov
     """
 
     parallel: dict[str, list[Stage]] = Field(
-        description="A mapping of parallel branch ID.",
+        description="A mapping of parallel branch name and stages.",
+    )
+    max_workers: int = Field(
+        default=2,
+        ge=1,
+        lt=20,
+        description=(
+            "The maximum thread pool worker size for execution parallel."
+        ),
+        alias="max-workers",
     )
-    max_parallel_core: int = Field(default=2)
 
-    @staticmethod
-    def task(
+    def execute_task(
+        self,
         branch: str,
         params: DictData,
         result: Result,
-        stages: list[Stage],
         *,
+        event: Event | None = None,
         extras: DictData | None = None,
     ) -> DictData:
         """Task execution method for passing a branch to each thread.
@@ -1039,32 +1091,82 @@ class ParallelStage(BaseStage):  # pragma: no cov
         :param params: A parameter data that want to use in this execution.
         :param result: (Result) A result object for keeping context and status
             data.
-        :param stages:
-        :param extras
+        :param event: (Event) An event manager that use to track parent execute
+            was not force stopped.
+        :param extras: (DictData) An extra parameters that want to override
+            config values.
 
         :rtype: DictData
         """
-        context = {"branch": branch, "stages": {}}
-        result.trace.debug(f"[STAGE]: Execute parallel branch: {branch!r}")
-        for stage in stages:
+        result.trace.debug(f"... Execute branch: {branch!r}")
+        context: DictData = copy.deepcopy(params)
+        context.update({"branch": branch, "stages": {}})
+        for stage in self.parallel[branch]:
+
             if extras:
                 stage.extras = extras
 
+            if stage.is_skipped(params=context):
+                result.trace.info(f"... Skip stage: {stage.iden!r}")
+                stage.set_outputs(output={"skipped": True}, to=context)
+                continue
+
+            if event and event.is_set():
+                error_msg: str = (
+                    "Branch-Stage was canceled from event that had set before "
+                    "stage item execution."
+                )
+                return result.catch(
+                    status=CANCEL,
+                    parallel={
+                        branch: {
+                            "branch": branch,
+                            "stages": filter_func(context.pop("stages", {})),
+                            "errors": StageException(error_msg).to_dict(),
+                        }
+                    },
+                )
+
             try:
-                stage.set_outputs(
-                    stage.handler_execute(
-                        params=params,
-                        run_id=result.run_id,
-                        parent_run_id=result.parent_run_id,
-                    ).context,
-                    to=context,
+                rs: Result = stage.handler_execute(
+                    params=context,
+                    run_id=result.run_id,
+                    parent_run_id=result.parent_run_id,
+                    raise_error=True,
+                    event=event,
                 )
+                stage.set_outputs(rs.context, to=context)
             except StageException as e:  # pragma: no cov
-                result.trace.error(
-                    f"[STAGE]: Catch:\n\t{e.__class__.__name__}:" f"\n\t{e}"
+                result.trace.error(f"[STAGE]: {e.__class__.__name__}: {e}")
+                raise StageException(
+                    f"Sub-Stage execution error: {e.__class__.__name__}: {e}"
+                ) from None
+
+            if rs.status == FAILED:
+                error_msg: str = (
+                    f"Item-Stage was break because it has a sub stage, "
+                    f"{stage.iden}, failed without raise error."
+                )
+                return result.catch(
+                    status=FAILED,
+                    parallel={
+                        branch: {
+                            "branch": branch,
+                            "stages": filter_func(context.pop("stages", {})),
+                            "errors": StageException(error_msg).to_dict(),
+                        },
+                    },
                 )
-                context.update({"errors": e.to_dict()})
-        return context
+
+        return result.catch(
+            status=SUCCESS,
+            parallel={
+                branch: {
+                    "branch": branch,
+                    "stages": filter_func(context.pop("stages", {})),
+                },
+            },
+        )
 
     def execute(
         self,
@@ -1086,41 +1188,46 @@ class ParallelStage(BaseStage):  # pragma: no cov
         """
         if result is None:  # pragma: no cov
             result: Result = Result(
-                run_id=gen_id(self.name + (self.id or ""), unique=True)
+                run_id=gen_id(self.name + (self.id or ""), unique=True),
+                extras=self.extras,
             )
-
+        event: Event = Event() if event is None else event
         result.trace.info(
-            f"[STAGE]: Parallel-Execute with {self.max_parallel_core} cores."
+            f"[STAGE]: Parallel-Execute: {self.max_workers} workers."
         )
-        rs: DictData = {"parallel": {}}
-        status = SUCCESS
+        result.catch(status=WAIT, context={"parallel": {}})
         with ThreadPoolExecutor(
-            max_workers=self.max_parallel_core,
+            max_workers=self.max_workers,
             thread_name_prefix="parallel_stage_exec_",
         ) as executor:
 
-            futures: list[Future] = []
-            for branch in self.parallel:
-                futures.append(
-                    executor.submit(
-                        self.task,
-                        branch=branch,
-                        params=params,
-                        result=result,
-                        stages=self.parallel[branch],
-                        extras=self.extras,
-                    )
+            context: DictData = {}
+            status: Status = SUCCESS
+
+            futures: list[Future] = (
+                executor.submit(
+                    self.execute_task,
+                    branch=branch,
+                    params=params,
+                    result=result,
+                    event=event,
+                    extras=self.extras,
                 )
+                for branch in self.parallel
+            )
 
             done = as_completed(futures, timeout=1800)
             for future in done:
-                context: DictData = future.result()
-                rs["parallel"][context.pop("branch")] = context
-
-                if "errors" in context:
+                try:
+                    future.result()
+                except StageException as e:
                     status = FAILED
+                    result.trace.error(
+                        f"[STAGE]: {e.__class__.__name__}:\n\t{e}"
+                    )
+                    context.update({"errors": e.to_dict()})
 
-        return result.catch(status=status, context=rs)
+        return result.catch(status=status, context=context)
 
 
 class ForEachStage(BaseStage):
@@ -1182,9 +1289,11 @@ class ForEachStage(BaseStage):
         :param event: (Event) An event manager that use to track parent execute
             was not force stopped.
 
+        :raise StageException: If the stage execution raise errors.
+
         :rtype: Result
         """
-        result.trace.debug(f"[STAGE]: Execute item: {item!r}")
+        result.trace.debug(f"... Execute item: {item!r}")
         context: DictData = copy.deepcopy(params)
         context.update({"item": item, "stages": {}})
         for stage in self.stages:
@@ -1193,17 +1302,17 @@ class ForEachStage(BaseStage):
                 stage.extras = self.extras
 
             if stage.is_skipped(params=context):
-                result.trace.info(f"[STAGE]: Skip stage: {stage.iden!r}")
+                result.trace.info(f"... Skip stage: {stage.iden!r}")
                 stage.set_outputs(output={"skipped": True}, to=context)
                 continue
 
-            if event and event.is_set():
+            if event and event.is_set():  # pragma: no cov
                 error_msg: str = (
                     "Item-Stage was canceled from event that had set before "
                     "stage item execution."
                 )
                 return result.catch(
-                    status=FAILED,
+                    status=CANCEL,
                     foreach={
                         item: {
                             "item": item,
@@ -1219,31 +1328,31 @@ class ForEachStage(BaseStage):
                     run_id=result.run_id,
                     parent_run_id=result.parent_run_id,
                     raise_error=True,
+                    event=event,
                 )
                 stage.set_outputs(rs.context, to=context)
-                if rs.status == FAILED:
-                    error_msg: str = (
-                        f"Item-Stage was break because it has a sub stage, "
-                        f"{stage.iden}, failed without raise error."
-                    )
-                    return result.catch(
-                        status=FAILED,
-                        foreach={
-                            item: {
-                                "item": item,
-                                "stages": filter_func(
-                                    context.pop("stages", {})
-                                ),
-                                "errors": StageException(error_msg).to_dict(),
-                            },
-                        },
-                    )
             except (StageException, UtilException) as e:
                 result.trace.error(f"[STAGE]: {e.__class__.__name__}: {e}")
                 raise StageException(
                     f"Sub-Stage execution error: {e.__class__.__name__}: {e}"
                 ) from None
 
+            if rs.status == FAILED:
+                error_msg: str = (
+                    f"Item-Stage was break because it has a sub stage, "
+                    f"{stage.iden}, failed without raise error."
+                )
+                return result.catch(
+                    status=FAILED,
+                    foreach={
+                        item: {
+                            "item": item,
+                            "stages": filter_func(context.pop("stages", {})),
+                            "errors": StageException(error_msg).to_dict(),
+                        },
+                    },
+                )
+
         return result.catch(
             status=SUCCESS,
             foreach={
@@ -1291,7 +1400,7 @@ class ForEachStage(BaseStage):
         result.catch(status=WAIT, context={"items": foreach, "foreach": {}})
         if event and event.is_set():  # pragma: no cov
             return result.catch(
-                status=FAILED,
+                status=CANCEL,
                 context={
                     "errors": StageException(
                         "Stage was canceled from event that had set "
@@ -1310,6 +1419,7 @@ class ForEachStage(BaseStage):
                     item=item,
                     params=params,
                     result=result,
+                    event=event,
                 )
                 for item in foreach
             ]
@@ -1334,7 +1444,7 @@ class ForEachStage(BaseStage):
                 except StageException as e:
                     status = FAILED
                     result.trace.error(
-                        f"[STAGE]: Catch:\n\t{e.__class__.__name__}:\n\t{e}"
+                        f"[STAGE]: {e.__class__.__name__}:\n\t{e}"
                     )
                     context.update({"errors": e.to_dict()})
 
@@ -1358,7 +1468,12 @@ class UntilStage(BaseStage):  # pragma: no cov
         ... }
     """
 
-    item: Union[str, int, bool] = Field(description="An initial value.")
+    item: Union[str, int, bool] = Field(
+        default=0,
+        description=(
+            "An initial value that can be any value in str, int, or bool type."
+        ),
+    )
     until: str = Field(description="A until condition.")
     stages: list[Stage] = Field(
         default_factory=list,
@@ -1367,11 +1482,12 @@ class UntilStage(BaseStage):  # pragma: no cov
             "correct."
         ),
     )
-    max_until_loop: int = Field(
+    max_loop: int = Field(
         default=10,
         ge=1,
         lt=100,
         description="The maximum value of loop for this until stage.",
+        alias="max-loop",
     )
 
     def execute_item(
@@ -1396,7 +1512,7 @@ class UntilStage(BaseStage):  # pragma: no cov
 
         :rtype: tuple[Result, T]
         """
-        result.trace.debug(f"[STAGE]: Execute until item: {item!r}")
+        result.trace.debug(f"... Execute until item: {item!r}")
         context: DictData = copy.deepcopy(params)
         context.update({"loop": loop, "item": item, "stages": {}})
         next_item: T = None
@@ -1406,7 +1522,7 @@ class UntilStage(BaseStage):  # pragma: no cov
                 stage.extras = self.extras
 
             if stage.is_skipped(params=context):
-                result.trace.info(f"[STAGE]: Skip stage: {stage.iden!r}")
+                result.trace.info(f"... Skip stage: {stage.iden!r}")
                 stage.set_outputs(output={"skipped": True}, to=context)
                 continue
 
@@ -1417,7 +1533,7 @@ class UntilStage(BaseStage):  # pragma: no cov
                 )
                 return (
                     result.catch(
-                        status=FAILED,
+                        status=CANCEL,
                         until={
                             loop: {
                                 "loop": loop,
@@ -1438,6 +1554,7 @@ class UntilStage(BaseStage):  # pragma: no cov
                     run_id=result.run_id,
                     parent_run_id=result.parent_run_id,
                     raise_error=True,
+                    event=event,
                 )
                 stage.set_outputs(rs.context, to=context)
                 if "item" in (
@@ -1486,6 +1603,7 @@ class UntilStage(BaseStage):  # pragma: no cov
             result: Result = Result(
                 run_id=gen_id(self.name + (self.id or ""), unique=True)
             )
+
         result.trace.info(f"[STAGE]: Until-Execution: {self.until}")
         item: Union[str, int, bool] = param2template(
             self.item, params, extras=self.extras
@@ -1494,11 +1612,11 @@ class UntilStage(BaseStage):  # pragma: no cov
         track: bool = True
         exceed_loop: bool = False
         result.catch(status=WAIT, context={"until": {}})
-        while track and not (exceed_loop := loop >= self.max_until_loop):
+        while track and not (exceed_loop := loop >= self.max_loop):
 
             if event and event.is_set():
                 return result.catch(
-                    status=FAILED,
+                    status=CANCEL,
                     context={
                         "errors": StageException(
                             "Stage was canceled from event that had set "
@@ -1512,6 +1630,7 @@ class UntilStage(BaseStage):  # pragma: no cov
                 loop=loop,
                 params=params,
                 result=result,
+                event=event,
             )
 
             loop += 1
@@ -1536,11 +1655,12 @@ class UntilStage(BaseStage):  # pragma: no cov
                     "Return type of until condition does not be boolean, it"
                     f"return: {next_track!r}"
                 )
-            track = not next_track
+            track: bool = not next_track
+            delay(0.025)
 
         if exceed_loop:
             raise StageException(
-                f"The until loop was exceed {self.max_until_loop} loops"
+                f"The until loop was exceed {self.max_loop} loops"
             )
         return result.catch(status=SUCCESS)
 
@@ -1552,7 +1672,7 @@ class Match(BaseModel):
     stage: Stage = Field(description="A stage to execution for this case.")
 
 
-class CaseStage(BaseStage):  # pragma: no cov
+class CaseStage(BaseStage):
     """Case execution stage.
 
     Data Validate:
@@ -1590,6 +1710,14 @@ class CaseStage(BaseStage):  # pragma: no cov
     match: list[Match] = Field(
         description="A list of Match model that should not be an empty list.",
     )
+    skip_not_match: bool = Field(
+        default=False,
+        description=(
+            "A flag for making skip if it does not match and else condition "
+            "does not set too."
+        ),
+        alias="skip-not-match",
+    )
 
     def execute(
         self,
@@ -1610,53 +1738,73 @@ class CaseStage(BaseStage):  # pragma: no cov
         """
         if result is None:  # pragma: no cov
             result: Result = Result(
-                run_id=gen_id(self.name + (self.id or ""), unique=True)
+                run_id=gen_id(self.name + (self.id or ""), unique=True),
+                extras=self.extras,
             )
 
-        _case = param2template(self.case, params, extras=self.extras)
+        _case: Optional[str] = param2template(
+            self.case, params, extras=self.extras
+        )
 
         result.trace.info(f"[STAGE]: Case-Execute: {_case!r}.")
-        _else = None
+        _else: Optional[Match] = None
         stage: Optional[Stage] = None
-        context = {}
-        status = SUCCESS
         for match in self.match:
-            if (c := match.case) != "_":
-                _condition = param2template(c, params, extras=self.extras)
-            else:
-                _else = match
+            if (c := match.case) == "_":
+                _else: Match = match
                 continue
 
+            _condition: str = param2template(c, params, extras=self.extras)
             if stage is None and _case == _condition:
                 stage: Stage = match.stage
 
         if stage is None:
             if _else is None:
-                raise StageException(
-                    "This stage does not set else for support not match "
-                    "any case."
+                if not self.skip_not_match:
+                    raise StageException(
+                        "This stage does not set else for support not match "
+                        "any case."
+                    )
+                result.trace.info(
+                    "... Skip this stage because it does not match."
+                )
+                error_msg: str = (
+                    "Case-Stage was canceled because it does not match any "
+                    "case and else condition does not set too."
+                )
+                return result.catch(
+                    status=CANCEL,
+                    context={"errors": StageException(error_msg).to_dict()},
                 )
-
             stage: Stage = _else.stage
 
         if self.extras:
             stage.extras = self.extras
 
+        if event and event.is_set():  # pragma: no cov
+            return result.catch(
+                status=CANCEL,
+                context={
+                    "errors": StageException(
+                        "Stage was canceled from event that had set before "
+                        "case-stage execution."
+                    ).to_dict()
+                },
+            )
+
         try:
-            context.update(
-                stage.handler_execute(
+            return result.catch(
+                status=SUCCESS,
+                context=stage.handler_execute(
                     params=params,
                     run_id=result.run_id,
                     parent_run_id=result.parent_run_id,
-                ).context
+                    event=event,
+                ).context,
             )
         except StageException as e:  # pragma: no cov
-            status = FAILED
-            result.trace.error(
-                f"[STAGE]: Catch:\n\t{e.__class__.__name__}:" f"\n\t{e}"
-            )
-            context.update({"errors": e.to_dict()})
-        return result.catch(status=status, context=context)
+            result.trace.error(f"[STAGE]: {e.__class__.__name__}:" f"\n\t{e}")
+            return result.catch(status=FAILED, context={"errors": e.to_dict()})
 
 
 class RaiseStage(BaseStage):  # pragma: no cov
@@ -1672,7 +1820,9 @@ class RaiseStage(BaseStage):  # pragma: no cov
     """
 
     message: str = Field(
-        description="An error message that want to raise",
+        description=(
+            "An error message that want to raise with StageException class"
+        ),
         alias="raise",
     )
 
@@ -1693,7 +1843,8 @@ class RaiseStage(BaseStage):  # pragma: no cov
         """
         if result is None:  # pragma: no cov
             result: Result = Result(
-                run_id=gen_id(self.name + (self.id or ""), unique=True)
+                run_id=gen_id(self.name + (self.id or ""), unique=True),
+                extras=self.extras,
             )
         message: str = param2template(self.message, params, extras=self.extras)
         result.trace.info(f"[STAGE]: Raise-Execute: {message!r}.")
@@ -1728,10 +1879,15 @@ class DockerStage(BaseStage):  # pragma: no cov
         ...     "image": "image-name.pkg.com",
         ...     "env": {
         ...         "ENV": "dev",
+        ...         "DEBUG": "true",
         ...     },
         ...     "volume": {
         ...         "secrets": "/secrets",
         ...     },
+        ...     "auth": {
+        ...         "username": "__json_key",
+        ...         "password": "${GOOGLE_CREDENTIAL_JSON_STRING}",
+        ...     },
         ... }
     """
 
@@ -1750,6 +1906,7 @@ class DockerStage(BaseStage):  # pragma: no cov
 
     def execute_task(
         self,
+        params: DictData,
         result: Result,
     ):
         from docker import DockerClient
@@ -1762,26 +1919,32 @@ class DockerStage(BaseStage):  # pragma: no cov
         resp = client.api.pull(
             repository=f"{self.image}",
             tag=self.tag,
-            # NOTE: For pulling from GCS.
-            # {
-            #     "username": "_json_key",
-            #     "password": credential-json-string,
-            # }
-            auth_config=self.auth,
+            auth_config=param2template(self.auth, params, extras=self.extras),
             stream=True,
             decode=True,
         )
         for line in resp:
             result.trace.info(f"... {line}")
 
-        unique_image_name: str = f"{self.image}_{datetime.now():%Y%m%d%H%M%S}"
+        unique_image_name: str = f"{self.image}_{datetime.now():%Y%m%d%H%M%S%f}"
         container = client.containers.run(
             image=f"{self.image}:{self.tag}",
             name=unique_image_name,
             environment=self.env,
             volumes=(
-                {Path.cwd() / ".docker.logs": {"bind": "/logs", "mode": "rw"}}
-                | self.volume
+                {
+                    Path.cwd()
+                    / f".docker.{result.run_id}.logs": {
+                        "bind": "/logs",
+                        "mode": "rw",
+                    },
+                }
+                | {
+                    Path.cwd() / source: {"bind": target, "mode": "rw"}
+                    for source, target in (
+                        volume.split(":", maxsplit=1) for volume in self.volume
+                    )
+                }
             ),
             detach=True,
         )