Skip to content

fix!: Bump the bindings to openjd-expr 0.14, openjd-model 0.15 and openjd-sessions 0.9 - #390

Merged
mwiebe merged 21 commits into
OpenJobDescription:mainlinefrom
mwiebe:chore/bump-openjd-rs-crates
Nov 17, 2026
Merged

mwiebe merged 21 commits into
OpenJobDescription:mainlinefrom
mwiebe:chore/bump-openjd-rs-crates

Conversation

@mwiebe

@mwiebe mwiebe commented Nov 11, 2026

Copy link
Copy Markdown
Contributor

Fixes: no GitHub issue filed.

What was the problem/requirement? (What/Why)

The Rust bindings pin openjd-expr 0.12.0, openjd-model 0.13.0 and openjd-sessions 0.8.1. The current releases carry fixes openjd.model._v1 and openjd.expr need, including openjd-rs#486, which #383 builds on.

What was the solution? (How)

Bump to openjd-expr 0.14.0, openjd-model 0.15.0 and openjd-sessions 0.9.0. Cargo.lock also moves serde-saphyr to 2.1.1 and granit-parser to 2.1.0. THIRD-PARTY-LICENSES.txt is regenerated (version lines only).

Compile fixes:

  • INT and CHUNK[INT] range list elements are IntOrFormatString (#486). The template range getter gives each as int or FormatString, as FLOAT already did and as the pure-Python model does.
  • Counts are u64 (#482). __len__ converts, raising OverflowError where it can't fit.
  • Path mapping goes through PathMapper (#472). HostContext.with_rules and PathMappingRule.apply raise ValueError for an invalid rule. Session.extend_path_mapping_rules raises SessionError rather than dropping the error.
  • The pure-Python model builds its EXPR profile inside its try, so an invalid rule raises ExpressionError.

What is the impact of this change?

Behavior changes, each pinned by a test and described in specs/:

  • Path mapping (#472, #483): sources must be absolute; the rule with the most names wins, WINDOWS over POSIX at equal depth, last wins for one location; a UNC share is one component; WINDOWS compares non-ASCII letters case-insensitively; . and empty components are ignored; no doubled separator after the destination; paths and rule paths over 32,768 bytes are refused.
  • RangeExpr is kept in canonical form (#469): str, repr and ranges() give canonical runs, == compares values, any 64-bit value but the most negative is allowed, and parsing accepts 50,000 elements; more than 50,000 canonical runs raise (#470). NONCONTIGUOUS chunks render in canonical form, so [1, 2, 4, 6] is 1,2-6:2.
  • Unresolved list comprehensions are typed list[T | nulltype], and [[range_expr]] is allowed (#462).
  • An empty PATH join behaves like pathlib (#516); escape_format_string("{}}") round-trips (#515).
  • A FLOAT range element's format string is checked at decode; an INT element that doesn't resolve to an integer fails create_job (#486).
  • YAML: tRUE, fALSE and nULL are strings, and core tags such as !!float 1.5 decode (serde-saphyr 2.1).
  • The session working directory is 8 random characters (#444); its rules file is written in precedence order.

Differences from the pure-Python reference that this leaves:

  • IntRangeExpr doesn't write canonical form (a strict xfail in model_v1/test_known_gaps.py).
  • openjd-sessions' path mapping accepts relative sources, picks the first rule on a tie and folds only ASCII letters.

No strict xfail tracking an openjd-rs gap XPASSes, so none are removed. #383's two strict xfails XPASS once it is rebased on this.

How was this change tested?

See DEVELOPMENT.md for information on running tests.

  • Have you run the unit tests? Yes, on Linux with Python 3.12 and 3.10: 6385 passed, 26 skipped, 9 xfailed, 94.3% coverage. ruff, black --check and mypy pass. cargo fmt --check, build --all-targets, clippy -D warnings, test, test --doc, doc -D warnings, cargo deny and scripts/check_third_party_licenses.sh pass.
  • openjd-cli (318) and openjd-sessions-for-python (1005) tests pass, as on mainline. With openjd-cli from source, conformance failures go from 32 to 25, none new.

Was this change documented?

  • Are relevant docstrings in the code base updated? Yes, and the three interface specs.

Is this a breaking change?

Yes, as listed above. Callers must give absolute path mapping sources, and can't rely on rule order, RangeExpr text or the working directory name.

Does this change impact security?

No. Path mapping now caps path length and rule-set size.


By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

…enjd-sessions 0.9

Move rust-bindings to openjd-expr 0.14.0, openjd-model 0.15.0 and
openjd-sessions 0.9.0. Cargo.lock changes only those three crates and
what they pull in: serde-saphyr 1.2.0 -> 2.1.1 and granit-parser
1.2.0 -> 2.1.0.

The new crates needed these binding changes:

- INT and CHUNK[INT] range list elements are now IntOrFormatString
  (openjd-rs#486). The template-side range getter exposes each element
  as an int or a FormatString, as FLOAT elements already were and as
  the pure-Python reference does.
- Counts are u64 on every target (openjd-rs#482). The binding stores
  and passes them as u64, and __len__ converts to usize, raising
  OverflowError where it doesn't fit.
- Path mapping rules apply through a PathMapper (openjd-rs#472).
  HostContext.with_rules builds one and raises ValueError for an
  invalid rule, PathMappingRule.apply builds a one-rule mapper, and
  Session.extend_path_mapping_rules raises SessionError instead of
  dropping the new Result.

Tests changed for behavior the crates changed on purpose:

- A list comprehension over an unresolved value has element type
  T | nulltype, since a run may keep nothing (openjd-rs#462).
- A NONCONTIGUOUS chunk renders in the canonical form of Template
  Schemas 3.4.1.1.1, so [1, 2, 4, 6] is "1,2-6:2" (openjd-rs#469). The
  pure-Python reference still writes "1,2,4,6"; a strict xfail in
  model_v1/test_known_gaps.py records that.
- A FLOAT range list element's format string is checked at decode
  time (openjd-rs#486), as the pure-Python reference already did.

New tests pin the other visible changes: INT and CHUNK[INT] format
string elements, relative path mapping sources rejected and the rule
with the most names winning in any order (openjd-rs#472), empty PATH
join operands (openjd-rs#516), and mixed-case tRUE and nULL read as
strings (openjd-rs#487). No strict xfail tracking an openjd-rs gap
XPASSes, so none are removed.

The specs and the type stub's docstrings describe the new behavior.
No public signature changed.

BREAKING CHANGE: PathMappingRule.apply and HostContext.with_rules raise
ValueError, and Session raises SessionError, for a rule whose POSIX or
WINDOWS source_path is not absolute. When several rules match, the one
whose source path has the most names applies, not the first in the
list. IntTaskParameterDefinition.range and
ChunkIntTaskParameterDefinition.range list elements can be
FormatString as well as int. A NONCONTIGUOUS chunk value is written in
canonical form. An unresolved list comprehension's type is
list[T | nulltype].

Signed-off-by: Mark Wiebe <399551+mwiebe@users.noreply.github.com>
Regenerated with scripts/check_third_party_licenses.sh --update. Only
the version lines of openjd-expr, openjd-model, openjd-sessions,
serde-saphyr and granit-parser changed.

Signed-off-by: Mark Wiebe <399551+mwiebe@users.noreply.github.com>
Review of the bump found visible changes that had no test or note:

- openjd.expr.RangeExpr is kept in canonical form since openjd-expr
  0.13.0 (openjd-rs#469): str, repr and ranges() give the canonical
  runs, and equality is by value. Every constructor caps the canonical
  form at 50,000 runs (openjd-rs#470). New tests pin these, and the
  strict xfail for the pure-Python IntRangeExpr also covers from_str.
- Rules for the same location resolve last-wins (openjd-rs#472). A new
  test pins it.
- An INT range list format string that doesn't resolve to an integer
  fails create_job (openjd-rs#486). A new test pins the message.
- The pure-Python model's EXPR evaluation builds its profile with
  HostContext.with_rules, which now raises ValueError for a relative
  source path. Build the profile inside the existing try, so the
  failure reaches callers as the model's ExpressionError like any
  other evaluation error, and pin it.

BREAKING CHANGE: str(), repr(), ranges() and == of openjd.expr.RangeExpr
follow the canonical form, and a RangeExpr with more than 50,000
canonical runs raises RangeExprError. Between path mapping rules for
the same location, the last one given applies. In the pure-Python
model, an EXPR expression evaluated under a path mapping rule whose
source path is not absolute raises ExpressionError. YAML scalars
spelled tRUE, fALSE or nULL are strings. An unresolved list
comprehension whose filter can never be a boolean gives
list[nulltype] rather than raising.

Signed-off-by: Mark Wiebe <399551+mwiebe@users.noreply.github.com>
…e bump

A second review of the bump found more visible changes with no test or
note:

- No separator is added after a path mapping destination that already
  ends with one (openjd-rs#483), so /dst/ maps /mnt/a/b to /dst/a/b.
- A path longer than 32,768 bytes matches no rule, and a rule with a
  longer source or destination path is invalid (openjd-rs#472).
- escape_format_string escapes a lone "{" before "}}", so "{}}" now
  round-trips (openjd-rs#515).

New tests pin each one, and the expr and sessions specs describe them,
including that a rule added by extend_path_mapping_rules replaces an
existing rule for its location.

The YAML scalar test said the change came from openjd-model 0.15.0. It
comes from serde-saphyr 2.1, which Cargo.lock resolves now that
openjd-model requires serde-saphyr 2, and which openjd-rs adopted in
#487. Reword it. Use "names", as the specs do, in the
extend_path_mapping_rules docstring, and name IntRangeExpr rather than
only from_list in the known-gap reason.

BREAKING CHANGE: a path longer than 32,768 bytes matches no path
mapping rule, and a rule whose source or destination path is longer
raises ValueError (SessionError in a Session).

Signed-off-by: Mark Wiebe <399551+mwiebe@users.noreply.github.com>
…he bump

A third review of the bump found more visible changes:

- The 32,768-byte path limit (openjd-rs#472) has three outcomes, not
  one. PathMappingRule.apply returns no match for a longer path, the
  apply_path_mapping expression function raises ExpressionError, and a
  session errors on a longer PATH or LIST[PATH] value. The specs said
  only "matches no rule". Correct them, and pin apply_path_mapping.
- Between a POSIX and a WINDOWS rule with the same number of names, the
  WINDOWS rule applies in any order (openjd-rs#472). Pin and document it.
- The session working directory is named with 8 random characters and
  no part of the session ID (openjd-rs#444), as the pure-Python
  reference names it. Pin and document it.
- A YAML 1.2 Core tag on a scalar, such as "!!float 1.5", decodes with
  serde-saphyr 2.1. With 1.2 it failed. Pin it.

Not pinned here because this repo's tests can't reach them, or they
only remove a crash: openjd-sessions 0.9.0 maps every LIST[PATH] value
when the session has a base symbol table (openjd-rs#483); a malformed
openjd_unset_env line no longer also unsets a variable named after the
parse error, and redacting a value that starts with a multibyte
character no longer panics (openjd-rs#515); with_number no longer
overflows on i64::MIN (openjd-rs#515); and CHUNK[INT] chunking no
longer overflows or lists every value for huge ranges (openjd-rs#473).

BREAKING CHANGE: apply_path_mapping raises ExpressionError for a path
longer than 32,768 bytes, and a session errors on a PATH or LIST[PATH]
value that long. A WINDOWS path mapping rule applies over a POSIX rule
with the same number of names. Session.working_directory no longer
contains the session ID.

Signed-off-by: Mark Wiebe <399551+mwiebe@users.noreply.github.com>
A fourth review of the bump found that the PathMapper rewrite
(openjd-rs#472) also changed how rules match components, as How Jobs
Are Run, "Path Mapping" item 2 requires:

- A UNC share is one component and must match as a whole, so a rooted
  path such as \srv\share\x no longer matches a \\srv\share rule.
- WINDOWS components compare the way Windows compares file names,
  non-ASCII letters included, so C:\Ünï matches C:\üNÏ. The
  pure-Python reference in openjd-sessions folds only ASCII letters.
- "." and empty components are ignored when matching and left out of
  the mapped path, so /mnt/./a/b matches a /mnt/a rule, and
  /mnt/a/./b//c maps to /d/b/c.

Pin each with a test and describe them in the expr spec, with a pointer
from the sessions spec.

BREAKING CHANGE: a rooted WINDOWS path no longer matches a UNC share
rule, WINDOWS rules match non-ASCII letters case-insensitively, and "."
and empty components are ignored when matching and dropped from the
mapped path.

Signed-off-by: Mark Wiebe <399551+mwiebe@users.noreply.github.com>
Reading the upstream commits behind the bump turned up three more
visible openjd-expr changes:

- RangeExpr values can be any 64-bit integer except the most negative
  one (openjd-rs#469). Before, magnitudes of 2**62 and up raised an
  overflow error.
- Parsing accepts up to 50,000 comma-separated elements (openjd-rs#470).
  Before, the cap was 10,000.
- A range_expr inside two list levels, [[range_expr('1-3')]], is two
  levels deep (openjd-rs#462). Before, it raised "Lists may be nested at
  most 2 levels deep".

Each is a relaxation, so nothing that worked before now fails. Pin them
and describe the first two in the expr spec.

Signed-off-by: Mark Wiebe <399551+mwiebe@users.noreply.github.com>
The expr spec, and the body of the commit that pinned component
matching, cited How Jobs Are Run, "Path Mapping" item 2. The rule is
item 2 of its "Applying Path Mapping Rules within a Job Template"
subsection. The working directory test said the new name came with
openjd-sessions 0.9.0; openjd-rs#444 first shipped in 0.8.2, which
this repo skipped. Move that test to its own file, since it is not
about path mapping rules.

Signed-off-by: Mark Wiebe <399551+mwiebe@users.noreply.github.com>
@github-actions

github-actions Bot commented Nov 11, 2026 •

Copy link
Copy Markdown

Claude review · advisory

Reviewed 9f3a4d5 (changes since b997af4): 0 new, 0 resolved.

Open: 0 blocking · 0 should-fix · 0 nit. ✅ Nothing blocking.

Fix or reply to each thread; the next revision's review re-checks open threads and resolves those it agrees are handled. Resolving a thread yourself also closes it. Later revisions review only what changed.

leongdl
leongdl previously approved these changes Nov 11, 2026
@mwiebe
mwiebe enabled auto-merge (rebase) November 12, 2026 00:24
…enjd-sessions 0.10

Move rust-bindings from openjd-expr 0.14.0, openjd-model 0.15.0 and
openjd-sessions 0.9.0 to 0.15.0, 0.16.0 and 0.10.0. The bindings
compile unchanged. Cargo.lock swaps RustPython's
rustpython-ruff_python_* 0.16.10 for Astral's ruff_python_* 0.0.21,
drops the icu_* crates, and moves phf to 0.14.

The main reason is openjd-rs#531: openjd-expr now parses with Astral's
ruff_python_parser, so an invalid expression parses in time roughly
linear in its length. With 0.14.0, decode_job_template took 2.6 s in a
release build (39 s in a debug build) on the 101-byte
"[i f(" * 20 + "x", and the time doubled per unclosed bracket. The
pure-Python model is affected too, since it evaluates EXPR expressions
with the same parser. A new test_parser_work_bound.py runs the
openjd-rs#489 reproducers through parse_expression, FormatString and
both decode_job_template functions with a 1 s bound; each takes a few
milliseconds now.

Tests changed for intended upstream changes (openjd-rs#531):

- Syntax errors use Ruff's wording: "unexpected EOF while parsing"
  rather than "'(' was never closed", and "missing closing quote in
  string literal" rather than "unterminated string literal". Three
  tests in TestSyntaxErrorCarets.
- A multi-line expression is parsed as written rather than wrapped in
  parentheses, so a binary operator's caret sits on the operator
  (~~^~~~~) instead of one character to its right. Four tests in
  TestMultiLineExpressions.

New tests pin the other visible changes:

- More of Ruff's wording, including a two-line expression's error on
  its second line (openjd-rs#531).
- Keyword placeholders no longer collide with an NFKC-normalized name
  or fall back to an unchecked one (openjd-rs#534).
- A FLOAT given as a number is written as Python's repr writes it:
  2 is "2.0" and 1e20 is "1e+20" (openjd-rs#539).
- A native list of numeric strings is accepted for LIST[INT],
  LIST[FLOAT] and LIST[LIST[INT]], and a LIST[FLOAT] default string
  item keeps its spelling (openjd-rs#538).
- White space around a numeric string value is ignored
  (openjd-rs#530).
- A whole-field FLOAT range expression keeps each float's spelling
  (openjd-rs#540).
- Sessions: a task or environment that fails before it starts fails
  the action (openjd-rs#532); a failed action keeps the session
  ending-only after a successful exit_environment(keep_session_running=
  True) (openjd-rs#524); onExit runs with the enter-time symbol table
  when the exit-time one can't be built (openjd-rs#536).

A new strict xfail in test/openjd/sessions/test_known_gaps.py records
that a run_task the crate refuses, such as on an ending-only session,
returns None and leaves the previous action_status, where the
pure-Python reference raises. The binding still discards the crate's
Result for its non-blocking actions; openjd-rs#524 makes that case
reachable. No strict xfail XPASSes. The three interface specs describe
the changes. No public signature changed.

BREAKING CHANGE: syntax error messages use Ruff's wording, and a
multi-line expression's caret moves one character left. A FLOAT given
as a number is written as Python's repr writes it. A _v1 Session whose
action failed stays READY_ENDING after exit_environment(
keep_session_running=True), and a run_task or enter_environment that
fails before it starts now fails the action and makes the session
ending-only.

Signed-off-by: Mark Wiebe <399551+mwiebe@users.noreply.github.com>
…6/0.10 bump

Regenerated with scripts/check_third_party_licenses.sh --update. The
openjd crates' versions change, Astral's ruff_python_* 0.0.21 and
ruff_unicode_names2 replace rustpython-ruff_python_* 0.16.10 and
unicode_names2, phf moves to 0.14, and the icu_* crates and their
Unicode-3.0 license text, synstructure, displaydoc, stable_deref_trait
and utf8_iter drop out.

Signed-off-by: Mark Wiebe <399551+mwiebe@users.noreply.github.com>
…ters

A review of the openjd-rs 0.15/0.16/0.10 bump found:

- Through a Session, white space around a number in an INT or FLOAT job
  or task parameter value is now ignored (openjd-rs#530). Before, the
  value failed before the action started and the binding didn't report
  it, so the task silently didn't run. Pin it, and say so in the
  sessions spec.
- Only a FLOAT parameter's default given as a number changed its text
  with openjd-rs#539 (2 was written "2", now "2.0"). A value given as a
  Python number and LIST[FLOAT] default items were already written as
  repr writes them. The previous commit's message, the FLOAT test class
  and the model spec read as if all three changed; narrow them.
- The run_task known gap predates openjd-sessions 0.10.0: a run_task
  straight after a failed one was refused the same way with 0.9.0.
  openjd-rs#524 adds a path into it, after a successful
  exit_environment(keep_session_running=True). Reword the comment, and
  record the gap in the sessions quality report.
- Cargo.lock adds phf 0.14 beside phf 0.11, which the stub-gen feature
  still pulls in; the previous commit said phf moved to 0.14.

Signed-off-by: Mark Wiebe <399551+mwiebe@users.noreply.github.com>
A second review of the bump found that openjd-rs#539 changed two more
things, which the previous commit wrongly described as unchanged:

- openjd-expr's float text now takes its digits from ryu, so a
  shortest-digit tie rounds to even as Python's repr does:
  1000000000000000.25 is written 1000000000000000.2, where it was
  1000000000000000.3. This reaches computed floats, FLOAT values given
  as a Python number, and LIST[FLOAT] items.
- A LIST[FLOAT] value given as JSON text reads each number as the
  nearest double (serde_json float_roundtrip). Before,
  2.2250738585072011e-308 read as 2.2250738585072014e-308.

Pin both, correct the FLOAT test class docstring, and describe them in
the expr and model specs. Also correct the sessions spec and quality
report: on a READY_ENDING session, enter_environment returns an
identifier that is never entered rather than None.

Signed-off-by: Mark Wiebe <399551+mwiebe@users.noreply.github.com>
…tions

A third review of the bump found that openjd-model 0.16.0
(openjd-rs#538) writes a LIST[FLOAT] default item given as a string,
such as "2.50", as a JSON string, so that job creation keeps its
spelling. merge_job_parameter_definitions parsed the default as a list
of f64, failed, and fell back to returning the raw JSON text as a str,
breaking the documented native-type contract: [1.5, "2.50"] came back
as '[1.5,"2.50"]' instead of [1.5, 2.5]. Read each item as a number or
a numeric string, as JobListFloatParameterDefinition.default does.

The same review found more upstream changes visible from Python with
no test or note. Pin and document them:

- openjd-rs#531: two keyword attributes no longer get placeholders
  where one is a prefix of the other ("Param.is + Param.assert" gave
  the wrong value about half the time), and a syntax error shows the
  text as written ("Param.if +", not "Param.af +"). The expr spec now
  says unclosed nested f-strings are quadratic, the 200-level bracket
  cap is gone, and a multi-line expression may end in a comment.
- openjd-rs#530: coercing a string to a number with a target_type
  ignores the white space around it.
- openjd-rs#532 also covers exit_environment: a failure before onExit
  starts fails the action, and the environment counts as exited.

Signed-off-by: Mark Wiebe <399551+mwiebe@users.noreply.github.com>
…p retries

A fourth review of the bump found the sessions spec's new sentence
about exit_environment (openjd-rs#532) had no test. Extend the
enter-failure test: the exit fails before onExit starts the same way,
and the environment counts as exited.

openjd-sessions 0.10.0 (openjd-rs#485) also retries removing a session
directory on Windows for up to about 31 s, and the binding's cleanup
holds the GIL while it waits. Say so in the sessions spec.

Signed-off-by: Mark Wiebe <399551+mwiebe@users.noreply.github.com>
…ending_only

The sessions binding's non-blocking actions (enter_environment,
exit_environment, run_task, run_subprocess) handed each call to a
background thread and discarded the openjd-sessions crate's Result. A
call the crate refused returned as if an action had started, ran
nothing, and left the previous action's status showing. With
openjd-sessions 0.10.0 (openjd-rs#524) that is the common case after a
failed action: the session stays READY_ENDING even after a successful
exit_environment(keep_session_running=True), so the next run_task
silently did nothing and action_status still read SUCCESS.

Each action method now waits, with the GIL released, until the crate
either accepts the call or returns. The crate refuses a call before it
changes anything, and accepts one by reporting its action through the
session callback before the action's first await. A refusal raises
SessionError with the crate's message and leaves the state,
action_status and environments_entered as they were, as the Rust method
returns Err. An accepted call returns once its action is RUNNING, or,
for an environment with no script or a failure before the action
starts, once the crate has returned, with the session back in its slot.
Errors after acceptance are on action_status, where the crate records
them; the binding records one there itself if the crate ever doesn't.
A call while another action runs gets the crate's InvalidState message
instead of "An action is already running".

Bind Session.clear_ending_only(), the crate's way back from ending-only
to READY. It raises SessionError unless the session is READY_ENDING.

WindowsSessionUser no longer treats a failure to look up the process
user as "not the process user"; it raises, as the pure-Python reference
does.

Tests: the strict xfail for a refused run_task becomes
test/openjd/sessions/test_refused_calls.py, which drives each refusal
through the binding and checks the exception, the crate's message, and
that state, action_status and environments_entered didn't change, plus
clear_ending_only and accepted calls. The sessions spec, the quality
report and the stub's Session class (regenerated, which also adds
run_task's step_name) describe the new behavior.

BREAKING CHANGE: Session.enter_environment, exit_environment, run_task
and run_subprocess raise SessionError for a call the crate refuses,
including on a READY_ENDING session, instead of returning. A call while
another action runs raises SessionError with the crate's InvalidState
message rather than RuntimeError("An action is already running");
SessionError is a RuntimeError subclass. WindowsSessionUser raises if
the process user can't be determined.

Signed-off-by: Mark Wiebe <399551+mwiebe@users.noreply.github.com>
…other gaps

A review of the previous commit found:

- A cancel_action made as soon as run_task, run_subprocess or
  enter_environment returned nearly always raised "Cannot cancel: no
  action is running", and the action ran to the end. The crate reports
  an action Running just before it installs the action's cancel token,
  and the call now returns on that report. cancel_action now keeps
  trying, with the GIL released, until the token is there or the action
  thread has given the session back, and then lets the crate decide, so
  "nothing to cancel" is always the crate's InvalidState message. It
  sets the snapshot's Canceling state under the session lock, so the
  snapshot can't be left reading Canceling after the action has ended.
- A negative, NaN or infinite run_subprocess timeout or cancel_action
  time_limit panicked in Duration::from_secs_f64, now in the method
  body, raising PanicException, which except Exception doesn't catch.
  It now raises ValueError. Zero still reaches the crate, which refuses
  it.
- If the action runtime couldn't be built, the call returned as if
  accepted and the snapshot was overwritten. It is now a refusal: the
  session is put back unchanged and the call raises SessionError. If the
  action thread can't be spawned, the session is put back rather than
  lost.
- The fallback that records an unreported error on action_status ran
  after the session was back in its slot, where a next action could
  already have started. It now runs under the session lock.
- cleanup() held the GIL through the crate's Windows removal retries
  (up to about 31 s). It now releases it.

cancel_action's arguments now default to None, as the spec documents.
Pin each change, and correct the sessions spec (errors after acceptance
don't raise even when they arrive before the call returns) and the
quality report's rows for cancel_action, run_subprocess and the
environment refusals.

Signed-off-by: Mark Wiebe <399551+mwiebe@users.noreply.github.com>
A second review found that cleanup(), which now releases the GIL, could
deadlock with a concurrent call when INFO logging was on. cleanup holds
the session lock while the crate logs, and pyo3_log takes the GIL for
each record, while the other thread held the GIL waiting for the same
lock (dispatch, clear_ending_only, extend_path_mapping_rules). Every
lock of the session is now taken with the GIL released. A test runs the
pattern in a fresh interpreter with INFO logging.

Also from the review:

- cancel_action's retry for a missing cancel token could spin for ever
  when called on the action thread itself, from a logging handler on the
  crate's "Running Task" banner, which the crate logs before installing
  the token. The wait is now bounded (2 s), then it raises SessionError
  "Cannot cancel: the action has not started yet". Pinned in a fresh
  interpreter.
- The panic branch of the action thread wrote its forced FAILED status
  after releasing the session lock, where a next action could already
  have started. It now writes it under the lock.
- The sessions spec said cleanup holds the GIL, and its signature block
  lagged the binding; it now matches the stub, and says a cancel
  straight after an action that has already ended raises InvalidState
  and a zero time_limit terminates at once. The quality report's
  recommendations for cancel and the negative timeout are struck
  through, the timeout=0 rows are updated, and clear_ending_only is
  listed as binding-only API.

Signed-off-by: Mark Wiebe <399551+mwiebe@users.noreply.github.com>
A third review found that a cancel straight after an action started
could still be lost under load. The crate reports an action Running,
then logs its banner and installs its cancel token; logging needs the
GIL and runs every Python logging handler, so the gap is as long as the
action thread waits for the GIL, seconds when other Python threads are
busy. The previous commit gave up after 2 s everywhere. The binding now
records which thread runs the current action, and only a cancel from
that thread (a logging handler) gives up after 2 s; from any other
thread it waits, with the GIL released, until the token is installed or
the session is back, which the action thread does without help. Pinned
in a fresh interpreter with a logging handler that takes 2.5 s.

Also from the review:

- If an action thread ever ended without telling its caller the
  outcome, the caller would have waited for ever. A guard held by the
  thread now drops the call's sender, only if the slot still holds that
  call, so the caller wakes up.
- Every refusal test now checks state, action_status and
  environments_entered, including the busy, ValueError and
  clear_ending_only cases. The fresh-interpreter tests' timeouts are
  under pytest's 30 s limit.
- The sessions spec's constructor block matches the binding, it
  documents the binding's own "Cannot cancel: the action has not
  started yet" and WindowsSessionUser's RuntimeError, and its new
  paragraphs are rewrapped. The quality report lists the
  WindowsSessionUser change.

Signed-off-by: Mark Wiebe <399551+mwiebe@users.noreply.github.com>
A fourth review found:

- A second cancel_action while the session was CANCELING went through
  the cancel handle and returned, ignoring its time limit. The crate's
  Session::cancel_action refuses it with InvalidState; the binding now
  does the same.
- The unbounded wait for the cancel token could hang for ever when the
  caller held a lock that a logging handler on the action thread needs,
  since the action thread logs its banner before installing the token.
  The wait is now bounded at 20 s from other threads, then raises
  "Cannot cancel: the action has not started yet". On the action
  thread itself it raises at once, since the token can't appear while
  that thread waits.
- dispatch turned a lost wake-up from the action thread into success.
  It now raises SessionError "the action thread ended unexpectedly".
  Nothing produces that today.

The sessions spec now says not to call an action method or
cancel_action while holding a lock that a logging handler takes on
another thread, since each waits for the action thread, which logs.
Fix stale comments about the runtime-build failure, and keep the
tests' waits under pytest's 30 s limit.

Signed-off-by: Mark Wiebe <399551+mwiebe@users.noreply.github.com>
…ng-lock rule

A review noted that refusing a second cancel_action while CANCELING,
as the crate does, changes behavior for callers of the pure-Python
Session, which accepts it and shortens the grace period to the new
time limit. Say so in the cancel_action docstring, the sessions spec
and the quality report. The crate can't shorten a cancel in progress.

Put the rule against calling an action method while holding a lock
that a logging handler takes in each action method's docstring, not
only the spec, and say in the spec where the fix belongs (the crate
should report acceptance and install the cancel token before logging).
Say "typically" for when the 20 s cancel wait ends. Pin that a cancel
from the action thread raises at once, and loosen the straight-after
cancel test's bound to 8 s for slow CI runners.

Signed-off-by: Mark Wiebe <399551+mwiebe@users.noreply.github.com>
…to at most its time limit

Signed-off-by: Mark Wiebe <399551+mwiebe@users.noreply.github.com>
@mwiebe
mwiebe merged commit 33de403 into OpenJobDescription:mainline Nov 17, 2026
28 checks passed
@mwiebe
mwiebe deleted the chore/bump-openjd-rs-crates branch November 17, 2026 00:30
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants