Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
80 commits
Select commit Hold shift + click to select a range
ca745e4
feat: Models the core contract needs
Alexander-Auer Oct 2, 2026
da8fb42
Feat: Protocols and Exceptions added for the core contract
Alexander-Auer Oct 2, 2026
58a5886
Feat: Private protocols for the BatchBackend
Alexander-Auer Oct 2, 2026
135879a
feat: a fake backend to run unit tests against
Alexander-Auer Oct 6, 2026
c97a24d
fix: some code cleanup in the helper functions
Alexander-Auer Oct 6, 2026
a5cda76
feat: setup for the unit test suite
Alexander-Auer Oct 6, 2026
db0683c
chore: style fix
Alexander-Auer Oct 6, 2026
a3eef9a
chore: styling, unit test fixture
Alexander-Auer Oct 6, 2026
f9dbb4c
chore: single letter var `h` refering to hanlde changed to `handle`
Alexander-Auer Oct 6, 2026
9fbd6f0
fix: unused parameter in `test_injected_failure_is_reported_per_job()…
Alexander-Auer Oct 6, 2026
1890fb6
chore: Making room in local fork for my documentation so i can easily…
Alexander-Auer Oct 7, 2026
cad5cea
fix: placed in the wrong folder :/
Alexander-Auer Oct 7, 2026
835c7aa
chore: added testplan
Alexander-Auer Oct 7, 2026
9332673
feat: Models the core contract needs
Alexander-Auer Oct 2, 2026
c77a73c
Feat: Protocols and Exceptions added for the core contract
Alexander-Auer Oct 2, 2026
3171383
Feat: Private protocols for the BatchBackend
Alexander-Auer Oct 2, 2026
0ecafb7
feat: a fake backend to run unit tests against
Alexander-Auer Oct 6, 2026
4c054e5
fix: some code cleanup in the helper functions
Alexander-Auer Oct 6, 2026
d311a91
feat: setup for the unit test suite
Alexander-Auer Oct 6, 2026
9831cab
chore: style fix
Alexander-Auer Oct 6, 2026
cf68d07
chore: styling, unit test fixture
Alexander-Auer Oct 6, 2026
bd78383
chore: single letter var `h` refering to hanlde changed to `handle`
Alexander-Auer Oct 6, 2026
1f185a0
fix: unused parameter in `test_injected_failure_is_reported_per_job()…
Alexander-Auer Oct 6, 2026
8f33853
Merge branch 'feat/core-contract' of github.com:Alexander-Auer/interc…
Alexander-Auer Oct 7, 2026
deeb558
fix: made the OutputSpec optional as it is not suppoerted by all and …
Alexander-Auer Oct 7, 2026
5d18685
Feat: Core contract issue #16 (#1)
Alexander-Auer Oct 7, 2026
51d56e8
fix: These documents should not exist in this way in the main repository
Alexander-Auer Oct 7, 2026
bb1427c
fix: None check for the outputs in submissionspec
Alexander-Auer Oct 7, 2026
aec9426
chore: trailing white spaces
Alexander-Auer Oct 7, 2026
d8d5413
chore: fixed pre commit locally
Alexander-Auer Oct 7, 2026
7be1814
chore: removed pdf, as they just take up space and no one will use th…
Alexander-Auer Oct 9, 2026
a916473
fix: JobHandle key is now a combination of the handle's fields instea…
Alexander-Auer Oct 19, 2026
1e46227
Merge branch 'main' into feat/core-contract
Alexander-Auer Oct 19, 2026
6c13e44
feat: backend configuration and a closed registry
Alexander-Auer Oct 19, 2026
dcf68e0
test: expand unit test coverage to every logical case
Alexander-Auer Oct 20, 2026
b6946d6
feat: credential models and provider-based supply
Alexander-Auer Oct 20, 2026
f046db0
Merge branch 'main' into feat/core-contract
Alexander-Auer Oct 23, 2026
ceb3c21
test: trim the unit tests to logical cases that can happen
Alexander-Auer Oct 23, 2026
9858175
Merge branch 'feat/core-contract' into stack/registry
Alexander-Auer Oct 23, 2026
ef717e2
test: trim the registry and configuration tests to logical cases
Alexander-Auer Oct 23, 2026
a2c106d
Merge branch 'stack/registry' into stack/test-expansion
Alexander-Auer Oct 23, 2026
838578e
test: trim the expanded tests to logical cases that can happen
Alexander-Auer Oct 23, 2026
ce476b9
Merge branch 'stack/test-expansion' into stack/credential-models
Alexander-Auer Oct 23, 2026
1931408
test: trim the credential tests to logical cases that can happen
Alexander-Auer Oct 23, 2026
893ab2d
docs: follow the Diátaxis structure for the user documentation
Alexander-Auer Oct 23, 2026
7b9ca48
fix: address the review of the core contract
Alexander-Auer Oct 23, 2026
aac93fe
Merge branch 'feat/core-contract' into stack/registry
Alexander-Auer Oct 23, 2026
2cfc4dc
fix: no references to the ADRs in the registry and configuration
Alexander-Auer Oct 23, 2026
951de16
Merge branch 'stack/registry' into stack/test-expansion
Alexander-Auer Oct 23, 2026
168bab7
Merge branch 'stack/test-expansion' into stack/credential-models
Alexander-Auer Oct 23, 2026
a1166ea
fix: no references to the ADRs in the credential code
Alexander-Auer Oct 23, 2026
cd4d127
Merge DIRACGrid main into stack/registry (the core contract, squash-m…
Alexander-Auer Oct 26, 2026
7380539
fix: apply the core contract review to the registry
Alexander-Auer Oct 26, 2026
d2a00f9
refactor: rename registry.backend() to get_backend()
Alexander-Auer Oct 26, 2026
055c31e
refactor!: one public configuration model per backend kind
Alexander-Auer Oct 26, 2026
b8fb65f
docs: generate the configuration reference from the models
Alexander-Auer Oct 26, 2026
4e6758f
Merge branch 'stack/registry' into stack/test-expansion
Alexander-Auer Oct 26, 2026
46dc501
test: remove leftovers of the flat configuration model
Alexander-Auer Oct 26, 2026
b068c5e
Merge branch 'stack/test-expansion' into stack/credential-models
Alexander-Auer Oct 26, 2026
3923887
fix: Rename FakeSettings to FakeConfig to stay in line with the revie…
Alexander-Auer Oct 26, 2026
a10537a
Merge remote-tracking branch 'origin/stack/registry' into stack/test-…
Alexander-Auer Oct 27, 2026
24df600
test: keep the existing model tests where they are
Alexander-Auer Oct 27, 2026
dcde224
Merge DIRACGrid main into stack/test-expansion (the registry, squash-…
Alexander-Auer Oct 27, 2026
1514a5b
test: a configuration that is not a mapping is refused
Alexander-Auer Oct 27, 2026
0b79099
Merge branch 'stack/test-expansion' into stack/credential-models
Alexander-Auer Oct 27, 2026
d419ccf
Merge DIRACGrid main into stack/credential-models (the test expansion…
Alexander-Auer Oct 27, 2026
e83c067
fix: credential errors never repeat the value they were given
Alexander-Auer Oct 27, 2026
904138f
fix: a provider's error text stays out of the AuthenticationError
Alexander-Auer Oct 27, 2026
ca1fe28
docs: document the credential fields in the API reference
Alexander-Auer Oct 27, 2026
f104906
docs: Google-style docstrings for the credential functions
Alexander-Auer Oct 27, 2026
031b670
fix: Removed the x509 proxy as it will not be used anymore, and also …
Alexander-Auer Nov 4, 2026
cedffad
Merge branch 'main' into stack/credential-models
Alexander-Auer Nov 4, 2026
11e435b
fix: Added a small credentialcache so each scope can get its own toke…
Alexander-Auer Nov 5, 2026
f34a072
test: give each backend its own folder in the unit tests
Alexander-Auer Nov 3, 2026
be8457e
feat: HTCondor submit descriptions in the shared core
Alexander-Auer Nov 3, 2026
8fc0b56
feat: HTCondor commands and the state map in the shared core
Alexander-Auer Nov 3, 2026
c7d9385
fix: no X.509 proxy in HTCondor submit descriptions
Alexander-Auer Nov 4, 2026
3b6f140
ci: run integration tests side by side and name what is skipped
Alexander-Auer Nov 3, 2026
9556be7
test: the htcondor integration stack
Alexander-Auer Nov 3, 2026
b4691af
Merge branch 'main' into stack/htcondor-2-integration-stack
Alexander-Auer Nov 16, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 6 additions & 3 deletions .github/workflows/integration.yml
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,7 @@ on:
- ".github/workflows/integration.yml"
- "tests/conftest.py"
- "pyproject.toml"
- "src/**"

permissions:
contents: read
Expand Down Expand Up @@ -77,11 +78,13 @@ jobs:
# TODO(#13/#14): ship the suite in the image and exec as an unprivileged user.
runner=(docker compose -f "$COMPOSE_FILE" exec -T backend pytest)
else
runner=(pixi run -e py313 pytest)
# Independent tests, run side by side (stacks.yml `workers`).
runner=(pixi run -e py313 pytest -n "${{ matrix.workers }}")
fi
set +e
"${runner[@]}" tests/integration -m "$MARKERS" \
--stack="$STACK" --config="$CONFIG"
# -rs --no-fold-skipped: name every skipped test and why.
"${runner[@]}" tests/integration -m "${{ matrix.markers }}" -rs --no-fold-skipped \
--stack="${{ matrix.stack }}" --config="${{ matrix.config }}"
rc=$?
# Exit 5 = no tests selected; tolerated until the contract suite lands.
if [ "$rc" -eq 5 ]; then
Expand Down
2 changes: 1 addition & 1 deletion docs/dev/how-to/add-an-integration-stack.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@ You do not need to change any CI workflow. CI finds the stack in `stacks.yml`.

```sh
docker compose -f tests/integration/stacks/<id>/compose.yml up --wait
pixi run -e py313 pytest tests/integration -m "<markers>" --stack=<id> --config=basic
pixi run -e py313 pytest tests/integration -n 4 -m "<markers>" --stack=<id> --config=basic
pixi run -e py313 pytest tests/integration/test_manifest.py
```

Expand Down
5 changes: 4 additions & 1 deletion docs/dev/how-to/run-integration-tests-locally.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,9 +16,12 @@ CI runs the same commands as below, so you can reproduce any CI job on your mach
2. Run the tests. Copy `<markers>` from the stack's entry in `stacks.yml`:

```sh
pixi run -e py313 pytest tests/integration -m "<markers>" --stack=<id> --config=basic
pixi run -e py313 pytest tests/integration -n 4 -m "<markers>" --stack=<id> --config=basic
```

`-n 4` runs four tests at the same time, as CI does. Use the stack's `workers` value from
`stacks.yml` if it sets one, or leave `-n` out to run one test at a time while debugging.

For stacks with `exec_in_container: true` (the `local-*` stacks), run the tests inside the
container instead:

Expand Down
1 change: 1 addition & 0 deletions docs/dev/reference/integration-stacks.md
Original file line number Diff line number Diff line change
Expand Up @@ -44,6 +44,7 @@ tests/integration/
| `versions` | no | Backend versions to test, for example `[lts, latest]`. Default: `[latest]`. |
| `markers` | yes | `pytest -m` expression that selects the tests for this stack. |
| `exec_in_container` | no | `true`: run pytest inside the backend container. Default: `false`. |
| `workers` | no | How many tests run at the same time (pytest-xdist). Default: `4`. Set `1` for a backend that cannot take several jobs at once. |

## When a stack gets CI jobs

Expand Down
8 changes: 8 additions & 0 deletions docs/user/reference/api.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,14 @@ Anything else, including every name starting with `_`, is internal.

::: intercede.registry

## Credentials

::: intercede.auth.models

::: intercede.auth.protocols

::: intercede.auth.providers

## Exceptions

::: intercede.exceptions
11 changes: 11 additions & 0 deletions src/intercede/_backends/_htcondor/__init__.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
"""What interCEde knows about HTCondor, shared by every backend that drives it.

Plain functions and data only, with no dependency on any backend class: the
HTCondor-CE backend uses them directly, and the HTCondor scheduler of the
composed backend (issue #21) will use the same ones over its transport. They
share these functions, never a subtype.

- ``submit``: a submit description built from a ``SubmissionSpec``
- ``commands``: the argv of each HTCondor tool, and parsers for their output
- ``status``: the state mapping from job ads to ``JobStatus``
"""
117 changes: 117 additions & 0 deletions src/intercede/_backends/_htcondor/commands.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,117 @@
"""The argv of each HTCondor tool, and parsers for what they print.

``remote`` is how a tool reaches its schedd: ``schedd_options(pool, name)``
for a remote schedd, as an HTCondor-CE is reached, or ``()`` for the schedd
of the host the tool runs on, as the composed backend reaches it.
"""

from __future__ import annotations

import re
from collections.abc import Sequence

from intercede.models import JobID

# Ids per command line, so a status poll of thousands of jobs stays bounded.
CHUNK = 100


def schedd_options(pool: str, name: str) -> list[str]:
"""Reach the schedd ``name`` through the collector ``pool`` (host:port)."""
return ["-pool", pool, "-name", name]


def submit(
description: str, pool: str | None = None, name: str | None = None
) -> list[str]:
"""Submit a description file and spool its inputs to the schedd.

Spooling copies the inputs at submit time, so nothing on the submitting
host is needed afterwards. With ``pool`` and ``name`` the schedd is a
remote one (``-remote`` implies spooling); without, it is the local one.
"""
if (pool is None) != (name is None):
raise ValueError("a remote schedd needs both pool and name")

command = ["condor_submit", "-terse"]

if pool is None or name is None:
command.append("-spool")
else:
command.extend(["-pool", pool, "-remote", name])

command.append(description)
return command


def query(
ids: Sequence[JobID], attributes: Sequence[str], remote: Sequence[str]
) -> list[str]:
"""Read the ads of jobs still in the queue."""
return ["condor_q", *remote, *ids, "-attributes", ",".join(attributes), "-json"]


def history(
ids: Sequence[JobID], attributes: Sequence[str], remote: Sequence[str]
) -> list[str]:
"""Read the ads of jobs that have left the queue."""
return [
"condor_history",
*remote,
*ids,
"-attributes",
",".join(attributes),
"-json",
]


def remove(ids: Sequence[JobID], remote: Sequence[str]) -> list[str]:
"""Remove jobs: cancels active ones, releases finished ones."""
return ["condor_rm", *remote, *ids]


def transfer_data(ids: Sequence[JobID], remote: Sequence[str]) -> list[str]:
"""Fetch the spooled output of jobs into the directory they were submitted from."""
return ["condor_transfer_data", *remote, *ids]


def chunks(ids: Sequence[JobID]) -> list[Sequence[JobID]]:
"""Split ids into groups of at most ``CHUNK``."""
return [ids[start : start + CHUNK] for start in range(0, len(ids), CHUNK)]


_TERSE = re.compile(
r"\s*(?P<cluster>\d+)\.(?P<first>\d+)"
r"\s*-\s*"
r"(?P<last_cluster>\d+)\.(?P<last>\d+)\s*"
)


def parse_submit(raw: str) -> list[JobID]:
"""Parse job IDs from condor_submit -terse output, e.g. '12.0 - 12.3'."""
lines = [line for line in raw.splitlines() if line.strip()]

if len(lines) != 1:
raise ValueError(f"unexpected condor_submit output: {raw.strip()!r}")

match = _TERSE.fullmatch(lines[0])
if match is None:
raise ValueError(f"unexpected condor_submit output: {raw.strip()!r}")

cluster = int(match["cluster"])
first = int(match["first"])
last_cluster = int(match["last_cluster"])
last = int(match["last"])

if cluster != last_cluster or last < first:
raise ValueError(f"unexpected condor_submit output: {raw.strip()!r}")

return [JobID(f"{cluster}.{proc}") for proc in range(first, last + 1)]


_REMOVED = re.compile(r"^Job (\d+\.\d+) marked for removal", re.MULTILINE)


def parse_remove(raw: str) -> set[JobID]:
"""Return the ids ``condor_rm`` reports as removed; any other id was not."""
return {JobID(job) for job in _REMOVED.findall(raw)}
124 changes: 124 additions & 0 deletions src/intercede/_backends/_htcondor/status.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,124 @@
"""From HTCondor job ads to ``JobStatus``.

Reading only: the state is taken from what HTCondor records about a job, never
from a policy interCEde sets on it. A finished job reads as FAILED when its
payload exited non-zero or was killed by a signal, from ``ExitCode`` and
``ExitBySignal``.

Ported from DIRAC's ``BatchSystems/Condor.py`` (``STATES_MAP`` and
``getCondorStatus``), with differences: DIRAC puts a payload that fails on
hold to recognise it, where the exit code is read here instead; the states
DIRAC leaves unmapped (6, 7) are mapped; and a removed job reports what it did
before it was removed, so a purged job keeps its result.
"""

from __future__ import annotations

import json
from collections.abc import Mapping, Sequence
from typing import Any

from intercede.models import JobID, JobStatus

# The ad attributes every status query asks for.
STATE_ATTRIBUTES: Sequence[str] = (
"ClusterId",
"ProcId",
"JobStatus",
"LastJobStatus",
"ExitCode",
"ExitBySignal",
"HoldReasonCode",
"HoldReason",
)

# HTCondor's JobStatus codes.
_IDLE, _RUNNING, _REMOVED, _COMPLETED, _HELD, _TRANSFERRING, _SUSPENDED = range(1, 8)

_STATES: Mapping[int, JobStatus] = {
_IDLE: JobStatus.WAITING,
_RUNNING: JobStatus.RUNNING,
_TRANSFERRING: JobStatus.RUNNING, # transferring output after running
_SUSPENDED: JobStatus.WAITING,
}

_HOLD_SPOOLING = 16 # HoldReasonCode: input files are still being spooled


def job_id(ad: Mapping[str, Any]) -> JobID:
"""Return the ``cluster.proc`` id of a job ad."""
return JobID(f"{ad['ClusterId']}.{ad['ProcId']}")


def job_status(ad: Mapping[str, Any]) -> JobStatus:
"""Map one job ad to the common status."""
code = ad.get("JobStatus")
if code == _COMPLETED:
return _result(ad)
if code == _REMOVED:
# purge() removes finished jobs to release them, after which the
# history only says "removed": the state it left tells the result.
return (
_result(ad) if ad.get("LastJobStatus") == _COMPLETED else JobStatus.ABORTED
)
if code == _HELD:
# Held by the site or by HTCondor, not by interCEde: the job is stuck,
# except while its inputs are still being spooled.
return (
JobStatus.WAITING
if ad.get("HoldReasonCode") == _HOLD_SPOOLING
else JobStatus.ABORTED
)
return (
_STATES.get(code, JobStatus.UNKNOWN)
if isinstance(code, int)
else JobStatus.UNKNOWN
)


def is_removed(ad: Mapping[str, Any]) -> bool:
"""Tell whether a job was removed, even while it is still in the queue.

``condor_rm`` only marks a job for removal: the schedd drops it from the
queue a moment later. In between it is already released.

Args:
ad: A job ad with ``JobStatus``.

Returns:
True when the job has been removed.

"""
return ad.get("JobStatus") == _REMOVED


def _result(ad: Mapping[str, Any]) -> JobStatus:
"""Tell DONE from FAILED for a job whose payload has finished."""
if ad.get("ExitBySignal") is True:
return JobStatus.FAILED
exit_code = ad.get("ExitCode")
return (
JobStatus.FAILED
if isinstance(exit_code, int) and exit_code != 0
else JobStatus.DONE
)


def hold_reason(ad: Mapping[str, Any]) -> str | None:
"""Return why a held job is held, if it is."""
reason = ad.get("HoldReason")
return reason if ad.get("JobStatus") == _HELD and isinstance(reason, str) else None


def parse_ads(raw: str) -> list[dict[str, Any]]:
"""Parse ``condor_q -json`` or ``condor_history -json`` output.

``condor_q`` prints nothing at all when no job matches, and
``condor_history`` prints an empty list.
"""
if not raw.strip():
return []
ads = json.loads(raw)
if not isinstance(ads, list) or not all(isinstance(ad, dict) for ad in ads):
raise ValueError("expected a JSON list of job ads")
return ads
Loading
Loading