Skip to content

Commit d757cd7

Browse files
committed
feat: RFC 0008 environment wrap actions
Implement RFC 0008 WRAP_ACTIONS support in the Python sessions runtime, allowing environments to wrap task and environment actions via the onWrapEnvEnter, onWrapTaskRun, and onWrapEnvExit hooks. - Run wrap hooks through EnvironmentScriptRunner (wrap_env_enter / wrap_env_exit) and the task-run wrap path, injecting Task.Action.*, Env.Wrapped.Action.*, and WrappedAction.* symbols per the final RFC wording. - Seed WrappedAction.Cancelation.Mode (string?) and WrappedAction.Cancelation.NotifyPeriodInSeconds (int?) for all three hooks, applying the Template Schemas 5.3.2 notify-period defaults (120 seconds for a task's onRun, 30 otherwise). Mode is None when the wrapped action declares no <Cancelation>, preserving the distinction from an explicit TERMINATE and rendering as the empty string per RFC 0005 null semantics. - Allow normal format string behavior for the cancelation mode per review feedback on openjd-specifications PR #148: partial interpolation like "{{ 'NOTIFY' }}_THEN_TERMINATE" is valid, and the resolved value is checked against the two mode names at run time. Null semantics (dropping the cancelation object) apply only when the mode is a whole-field "{{ ... }}" expression, per the Template Schemas 5.3 wording; a normal format string that resolves to the empty string is an invalid mode, matching the openjd-rs typed-resolution behavior. - Support round-trip cancelation/timeout forwarding: a deferred cancelation mode (CancelationMethodDeferred) resolves against the live symbol table via a shared resolve_effective_cancelation helper used by both the seed path and the cancel enforcement paths, so wrap scripts always see the values the runtime enforces. WrappedAction. Timeout is int? (None when the wrapped action has no timeout), and FormatString timeouts resolve at launch with null meaning "no timeout field". - WrappedAction.Environment carries only openjd_env-defined variables, flattened cumulatively in environment-entry order (overrides and unsets collapse to the effective entry), with the exiting environment's own variables captured before removal on the onWrapEnvExit path. - Fail gracefully (normal FAIL callback path, session to READY_ENDING) when WrappedAction.* injection cannot resolve the wrapped action's format strings, instead of leaking FormatStringError through the public API. - Inherit Rust-backed EXPR format-string evaluation transparently from openjd-model; guard _run_wrap_hook against unknown hook names; warn when a wrap environment is active but run_task() lacks step_name. All WRAP_ACTIONS conformance fixtures pass against the Python CLI, along with the new wrap/cancelation unit test suites. Signed-off-by: David Leong <116610336+leongdl@users.noreply.github.com>
1 parent f0bfb98 commit d757cd7

9 files changed

Lines changed: 1977 additions & 84 deletions

File tree

‎.gitignore‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,3 +23,6 @@ __pycache__/
2323
/dist
2424
_version.py
2525
*.log
26+
27+
# Local one-off helper scripts (not part of the project)
28+
/tmp/

‎src/openjd/sessions/_runner_base.py‎

Lines changed: 145 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -11,13 +11,15 @@
1111
from enum import Enum
1212
from pathlib import Path
1313
from threading import Lock, Timer
14-
from typing import Callable, Optional, Sequence, Type, cast
14+
from typing import Any, Callable, Optional, Sequence, Type, cast
1515
from types import TracebackType
1616
from tempfile import mkstemp
1717

1818
from openjd.model import SymbolTable
1919
from openjd.model import FormatStringError
2020
from openjd.model.v2023_09 import Action as Action_2023_09
21+
from openjd.model.v2023_09 import CancelationMethodDeferred as CancelationMethodDeferred_2023_09
22+
from openjd.model.v2023_09 import CancelationMode as CancelationMode_2023_09
2123
from ._embedded_files import EmbeddedFiles, EmbeddedFilesScope, write_file_for_user
2224
from ._logging import log_subsection_banner, LoggerAdapter, LogContent, LogExtraInfo
2325
from ._os_checker import is_posix
@@ -90,6 +92,110 @@ class NotifyCancelMethod(CancelMethod):
9092
"""Amount of time after a SIGTERM to wait to do the SIGKILL"""
9193

9294

95+
def resolve_effective_cancelation(
96+
cancelation: Any, symtab: SymbolTable
97+
) -> tuple[Optional[str], Optional[int]]:
98+
"""Resolve an action's cancelation config against the symbol table into
99+
an effective ``(mode, notify_period_seconds)`` pair.
100+
101+
What is the problem this solves?
102+
103+
Format strings are normally delay-processed: the parser stores "this is
104+
a format string" and the value resolves right before the action runs.
105+
But a cancelation's ``mode`` is the *schema selector* — the parser needs
106+
it to know which object shape it is reading — while a forwarded value
107+
like ``mode: "{{WrappedAction.Cancelation.Mode}}"`` (RFC 0008
108+
round-trip forwarding) only exists at run time. The model therefore
109+
carries such a mode as :class:`CancelationMethodDeferred`, and *this*
110+
function is where the deferred decision finally lands: with the
111+
``WrappedAction.*`` values in the symbol table, the mode expression
112+
resolves to ``"TERMINATE"``, ``"NOTIFY_THEN_TERMINATE"``, or null — and
113+
a null mode means the whole cancelation object is treated as never
114+
declared (the runtime default applies).
115+
116+
Returns:
117+
(mode, notify_period_seconds) where ``mode`` is ``"TERMINATE"``,
118+
``"NOTIFY_THEN_TERMINATE"``, or ``None`` (no ``<Cancelation>``
119+
declared, or a deferred mode that resolved to null); and
120+
``notify_period_seconds`` is ``None`` when the field was omitted or
121+
its whole-field expression resolved to null — the caller applies
122+
the positional schema default.
123+
124+
Raises:
125+
ValueError: If a deferred mode resolves to anything other than the
126+
two method names or null, if a resolved TERMINATE carries a
127+
non-null notify period, or if a notify period does not resolve
128+
to a positive integer.
129+
FormatStringError: If expression resolution itself fails.
130+
"""
131+
132+
def resolve_period(period: Any) -> Optional[int]:
133+
if period is None:
134+
return None
135+
if isinstance(period, int):
136+
return period
137+
# FormatString form (FEATURE_BUNDLE_1). A whole-field expression
138+
# that resolves to null renders as the empty string and is treated
139+
# as if the field were not provided (schema defaults apply).
140+
resolved = period.resolve(symtab=symtab)
141+
if resolved == "":
142+
return None
143+
value = int(resolved) # raises ValueError on non-integer
144+
# Mirror the static validator's bounds on literal values (Template
145+
# Schemas 5.3.2: 1..600): format-string values could not be checked
146+
# at parse time, so the resolved value is bounds-checked here.
147+
if value < 1 or value > 600:
148+
raise ValueError(f"notifyPeriodInSeconds must be between 1 and 600, got '{value}'")
149+
return value
150+
151+
if cancelation is None:
152+
return (None, None)
153+
if isinstance(cancelation, CancelationMethodDeferred_2023_09):
154+
# Null semantics apply only to a whole-field expression
155+
# ("{{ ... }}" with no surrounding text, target type string? —
156+
# Template Schemas 5.3). A normal format string that happens to
157+
# resolve to the empty string is NOT null; it falls through to the
158+
# "must resolve to..." error below.
159+
raw = str(cancelation.mode).strip()
160+
is_whole_field = (
161+
raw.startswith("{{")
162+
and raw.endswith("}}")
163+
and raw.count("{{") == 1
164+
and raw.count("}}") == 1
165+
)
166+
mode = cancelation.mode.resolve(symtab=symtab)
167+
if mode == "" and is_whole_field:
168+
# Null mode drops the ENTIRE cancelation object: mode is the
169+
# object's required discriminator, so an "omitted" mode cannot
170+
# leave a partial object behind. The action behaves exactly as
171+
# if no <Cancelation> were declared.
172+
return (None, None)
173+
if mode == CancelationMode_2023_09.TERMINATE.value:
174+
# Post-resolution the object must validate against the resolved
175+
# variant's shape: TERMINATE admits no notify period.
176+
if resolve_period(cancelation.notifyPeriodInSeconds) is not None:
177+
raise ValueError(
178+
"cancelation mode resolved to TERMINATE, which does not "
179+
"accept notifyPeriodInSeconds"
180+
)
181+
return (CancelationMode_2023_09.TERMINATE.value, None)
182+
if mode == CancelationMode_2023_09.NOTIFY_THEN_TERMINATE.value:
183+
return (
184+
CancelationMode_2023_09.NOTIFY_THEN_TERMINATE.value,
185+
resolve_period(cancelation.notifyPeriodInSeconds),
186+
)
187+
raise ValueError(
188+
"cancelation mode must resolve to TERMINATE, NOTIFY_THEN_TERMINATE, "
189+
f"or null; got '{mode}'"
190+
)
191+
if cancelation.mode == CancelationMode_2023_09.TERMINATE:
192+
return (CancelationMode_2023_09.TERMINATE.value, None)
193+
return (
194+
CancelationMode_2023_09.NOTIFY_THEN_TERMINATE.value,
195+
resolve_period(getattr(cancelation, "notifyPeriodInSeconds", None)),
196+
)
197+
198+
93199
class ScriptRunnerBase(ABC):
94200
"""Base class for a runnable Environment or Step Script.
95201
Responsible for running a *single* Action, and optionally canceling it.
@@ -463,8 +569,44 @@ def _run_action(
463569
self._callback(ActionState.FAILED)
464570
else:
465571
time_limit: Optional[timedelta] = default_timeout
466-
if action.timeout:
467-
time_limit = timedelta(seconds=action.timeout) # type: ignore[arg-type]
572+
if action.timeout is not None:
573+
if isinstance(action.timeout, int):
574+
time_limit = timedelta(seconds=action.timeout)
575+
else:
576+
# FormatString form (FEATURE_BUNDLE_1), resolved right
577+
# before the action runs. A whole-field expression that
578+
# resolves to null renders as the empty string — e.g.
579+
# forwarding `timeout: "{{WrappedAction.Timeout}}"`
580+
# (RFC 0008) when the wrapped action specified no
581+
# timeout — and is treated as if the field were not
582+
# provided, so the positional default applies.
583+
try:
584+
resolved = action.timeout.resolve(symtab=symtab)
585+
except FormatStringError as exc:
586+
self._logger.info(
587+
f"openjd_fail: {str(exc)}",
588+
extra=LogExtraInfo(openjd_log_content=LogContent.EXCEPTION_INFO),
589+
)
590+
self._state_override = ScriptRunnerState.FAILED
591+
if self._callback is not None:
592+
self._callback(ActionState.FAILED)
593+
return
594+
if resolved != "":
595+
try:
596+
seconds = int(resolved)
597+
if seconds < 1:
598+
raise ValueError
599+
except ValueError:
600+
self._logger.info(
601+
f"openjd_fail: timeout must be a positive integer, "
602+
f"got '{resolved}'",
603+
extra=LogExtraInfo(openjd_log_content=LogContent.EXCEPTION_INFO),
604+
)
605+
self._state_override = ScriptRunnerState.FAILED
606+
if self._callback is not None:
607+
self._callback(ActionState.FAILED)
608+
return
609+
time_limit = timedelta(seconds=seconds)
468610
self._run(command, time_limit)
469611

470612
def _cancel(

‎src/openjd/sessions/_runner_env_script.py‎

Lines changed: 76 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -5,12 +5,9 @@
55
from pathlib import Path
66
from typing import Callable, Optional
77

8-
from openjd.model import SymbolTable
8+
from openjd.model import FormatStringError, SymbolTable
99
from openjd.model.v2023_09 import Action as Action_2023_09
1010
from openjd.model.v2023_09 import CancelationMode as CancelationMode_2023_09
11-
from openjd.model.v2023_09 import (
12-
CancelationMethodNotifyThenTerminate as CancelationMethodNotifyThenTerminate_2023_09,
13-
)
1411
from openjd.model.v2023_09 import EnvironmentScript as EnvironmentScript_2023_09
1512
from ._embedded_files import EmbeddedFilesScope
1613
from ._logging import log_subsection_banner
@@ -20,9 +17,15 @@
2017
ScriptRunnerBase,
2118
ScriptRunnerState,
2219
TerminateCancelMethod,
20+
resolve_effective_cancelation,
2321
)
2422
from ._session_user import SessionUser
25-
from ._types import ActionModel, ActionState, EnvironmentScriptModel
23+
from ._types import (
24+
ENV_ACTION_DEFAULT_NOTIFY_PERIOD_SECONDS,
25+
ActionModel,
26+
ActionState,
27+
EnvironmentScriptModel,
28+
)
2629

2730
__all__ = ("EnvironmentScriptRunner",)
2831

@@ -181,6 +184,52 @@ def exit(self) -> None:
181184
default_timeout=_ENV_EXIT_DEFAULT_TIMEOUT,
182185
)
183186

187+
def wrap_task_run(self) -> None:
188+
"""Run the Environment's onWrapTaskRun action, wrapping a task's onRun."""
189+
self._run_wrap_hook("onWrapTaskRun")
190+
191+
def wrap_env_enter(self) -> None:
192+
"""RFC 0008: run this Environment's ``onWrapEnvEnter`` action,
193+
substituting it for an inner environment's ``onEnter``."""
194+
self._run_wrap_hook("onWrapEnvEnter")
195+
196+
def wrap_env_exit(self) -> None:
197+
"""RFC 0008: run this Environment's ``onWrapEnvExit`` action,
198+
substituting it for an inner environment's ``onExit``."""
199+
self._run_wrap_hook("onWrapEnvExit", default_timeout=_ENV_EXIT_DEFAULT_TIMEOUT)
200+
201+
def _run_wrap_hook(self, hook: str, *, default_timeout: Optional[timedelta] = None) -> None:
202+
"""Common dispatch for the three RFC 0008 wrap hooks. ``hook`` is
203+
one of ``onWrapEnvEnter``, ``onWrapTaskRun``, or ``onWrapEnvExit``."""
204+
if hook not in ("onWrapEnvEnter", "onWrapTaskRun", "onWrapEnvExit"):
205+
# Guard the getattr below: without this, a typo'd hook name
206+
# would silently become a SUCCESS no-op.
207+
raise ValueError(f"Unknown wrap hook name: {hook}")
208+
if self.state != ScriptRunnerState.READY:
209+
raise RuntimeError("This cannot be used to run a second subprocess.")
210+
211+
# For the type checker
212+
if self._environment_script is not None:
213+
assert isinstance(self._environment_script, EnvironmentScript_2023_09)
214+
215+
action = (
216+
getattr(self._environment_script.actions, hook, None)
217+
if self._environment_script is not None
218+
else None
219+
)
220+
if action is None:
221+
self._state_override = ScriptRunnerState.SUCCESS
222+
# Nothing to do, no wrap action defined. Call the callback
223+
# to inform the caller that the run is complete, and then exit.
224+
if self._callback is not None:
225+
self._callback(ActionState.SUCCESS)
226+
return
227+
228+
if default_timeout is not None:
229+
self._run_env_action(action, default_timeout=default_timeout)
230+
else:
231+
self._run_env_action(action)
232+
184233
def cancel(
185234
self, *, time_limit: Optional[timedelta] = None, mark_action_failed: bool = False
186235
) -> None:
@@ -191,24 +240,32 @@ def cancel(
191240
# For the type checker
192241
assert isinstance(self._action, Action_2023_09)
193242

243+
# Resolve the cancelation config against the symbol table: a
244+
# deferred (format-string) mode and/or a FEATURE_BUNDLE_1 notify
245+
# period decide their values here, right when they are needed
246+
# (see resolve_effective_cancelation for the full story). A cancel
247+
# must always proceed, so resolution errors fall back to Terminate.
248+
try:
249+
mode, period = resolve_effective_cancelation(self._action.cancelation, self._symtab)
250+
except (ValueError, FormatStringError) as exc:
251+
self._logger.warning(
252+
f"Failed to resolve the action's cancelation; canceling by "
253+
f"termination instead: {exc}"
254+
)
255+
mode, period = (None, None)
256+
194257
method: CancelMethod
195-
if (
196-
self._action.cancelation is None
197-
or self._action.cancelation.mode == CancelationMode_2023_09.TERMINATE
198-
):
199-
# Note: Default cancelation for a 2023-09 Step Script is Terminate
258+
if mode != CancelationMode_2023_09.NOTIFY_THEN_TERMINATE.value:
259+
# Note: Default cancelation for a 2023-09 Environment Script is Terminate
200260
method = TerminateCancelMethod()
201261
else:
202-
model_cancel_method = self._action.cancelation
203-
# For the type checker
204-
assert isinstance(model_cancel_method, CancelationMethodNotifyThenTerminate_2023_09)
205-
if model_cancel_method.notifyPeriodInSeconds is None:
206-
# Default grace period is 30s for a 2023-09 Environment Script's notify cancel
207-
method = NotifyCancelMethod(terminate_delay=timedelta(seconds=30))
208-
else:
209-
method = NotifyCancelMethod(
210-
terminate_delay=timedelta(seconds=model_cancel_method.notifyPeriodInSeconds) # type: ignore[arg-type]
262+
method = NotifyCancelMethod(
263+
terminate_delay=timedelta(
264+
seconds=(
265+
period if period is not None else ENV_ACTION_DEFAULT_NOTIFY_PERIOD_SECONDS
266+
)
211267
)
268+
)
212269

213270
# Note: If the given time_limit is less than that in the method, then the time_limit will be what's used.
214271
self._cancel(method, time_limit, mark_action_failed)

‎src/openjd/sessions/_runner_step_script.py‎

Lines changed: 26 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -5,12 +5,9 @@
55
from pathlib import Path
66
from typing import Callable, Optional
77

8-
from openjd.model import SymbolTable
8+
from openjd.model import FormatStringError, SymbolTable
99
from openjd.model.v2023_09 import CancelationMode as CancelationMode_2023_09
1010
from openjd.model.v2023_09 import StepScript as StepScript_2023_09
11-
from openjd.model.v2023_09 import (
12-
CancelationMethodNotifyThenTerminate as CancelationMethodNotifyThenTerminate_2023_09,
13-
)
1411
from ._embedded_files import EmbeddedFilesScope
1512
from ._logging import log_subsection_banner
1613
from ._runner_base import (
@@ -19,9 +16,10 @@
1916
ScriptRunnerBase,
2017
ScriptRunnerState,
2118
TerminateCancelMethod,
19+
resolve_effective_cancelation,
2220
)
2321
from ._session_user import SessionUser
24-
from ._types import ActionState, StepScriptModel
22+
from ._types import TASK_RUN_DEFAULT_NOTIFY_PERIOD_SECONDS, ActionState, StepScriptModel
2523

2624
__all__ = ("StepScriptRunner",)
2725

@@ -127,24 +125,34 @@ def cancel(
127125
# For the type checker.
128126
assert isinstance(self._script, StepScript_2023_09)
129127

128+
# Resolve the cancelation config against the symbol table: a
129+
# deferred (format-string) mode and/or a FEATURE_BUNDLE_1 notify
130+
# period decide their values here, right when they are needed
131+
# (see resolve_effective_cancelation for the full story). A cancel
132+
# must always proceed, so resolution errors fall back to Terminate.
133+
try:
134+
mode, period = resolve_effective_cancelation(
135+
self._script.actions.onRun.cancelation, self._symtab
136+
)
137+
except (ValueError, FormatStringError) as exc:
138+
self._logger.warning(
139+
f"Failed to resolve the action's cancelation; canceling by "
140+
f"termination instead: {exc}"
141+
)
142+
mode, period = (None, None)
143+
130144
method: CancelMethod
131-
if (
132-
self._script.actions.onRun.cancelation is None
133-
or self._script.actions.onRun.cancelation.mode == CancelationMode_2023_09.TERMINATE
134-
):
145+
if mode != CancelationMode_2023_09.NOTIFY_THEN_TERMINATE.value:
135146
# Note: Default cancelation for a 2023-09 Step Script is Terminate
136147
method = TerminateCancelMethod()
137148
else:
138-
model_cancel_method = self._script.actions.onRun.cancelation
139-
# For the type checker
140-
assert isinstance(model_cancel_method, CancelationMethodNotifyThenTerminate_2023_09)
141-
if model_cancel_method.notifyPeriodInSeconds is None:
142-
# Default grace period is 120s for a 2023-09 Step Script's notify cancel
143-
method = NotifyCancelMethod(terminate_delay=timedelta(seconds=120))
144-
else:
145-
method = NotifyCancelMethod(
146-
terminate_delay=timedelta(seconds=model_cancel_method.notifyPeriodInSeconds) # type: ignore[arg-type]
149+
method = NotifyCancelMethod(
150+
terminate_delay=timedelta(
151+
seconds=(
152+
period if period is not None else TASK_RUN_DEFAULT_NOTIFY_PERIOD_SECONDS
153+
)
147154
)
155+
)
148156

149157
# Note: If the given time_limit is less than that in the method, then the time_limit will be what's used.
150158
self._cancel(method, time_limit, mark_action_failed)

0 commit comments

Comments
 (0)