"""Rehydrate SPR-KKR results from project run records."""
from __future__ import annotations
import os
from ..common.module_registry import RegistryEntryNotFound
from kkrunner.files import ArtifactAvailabilityState, FileState
from kkrunner.runs import FailurePhase, HistoricalFileMismatchError
from kkrunner import RunState
from ..input_parameters.input_parameters import InputParameters
from ..input_parameters.task_definition import TaskMismatchError
from .reader_registry import reader_registry
[docs]
class ProjectResultUnavailableError(RuntimeError):
"""A stored run cannot be reconstructed as its historical TaskResult."""
def __init__(self, record, message):
self.record = record
super().__init__(f"Run {record.id}: {message}")
[docs]
class UnrecoverableProjectResultError(ProjectResultUnavailableError):
"""The persisted metadata is insufficient to reconstruct this result."""
[docs]
def _record(manager, run):
return manager.store.get(run) if isinstance(run, str) else manager.store.get(run.id)
[docs]
def _task_definition_for_record(record):
try:
return InputParameters.task_registry[application_metadata(record)["task"]]
except RegistryEntryNotFound:
raise UnrecoverableProjectResultError(
record, f"unknown persisted task {application_metadata(record)['task']!r}"
) from None
[docs]
def _reader_for_record(manager, record):
"""Create the task-owned output reader declared by the persisted task."""
task_definition = _task_definition_for_record(record)
parameters = _input_parameters_for_record(manager, record, task_definition)
reader_class = reader_registry.class_for_task(task_definition)
return reader_class(
parameters,
None,
record.execution.directory.local,
task_name=application_metadata(record)["task"],
)
[docs]
def _result_processor_for_record(manager, record):
"""Build the generic execution→TaskResult boundary in the outputs layer."""
reader = _reader_for_record(manager, record)
def process_result(outcome):
return reader.read_from_file(
outcome.output_file,
outcome.error_file,
return_code=(0 if outcome.return_code is None else outcome.return_code),
input_file=outcome.input_file,
directory=record.execution.directory.local,
)
return process_result
[docs]
def attach_project_run(
manager,
run,
*,
executor=None,
callback=None,
output_listener=None,
):
"""Reconnect an active run and resume its client-side lifecycle."""
record = _record(manager, run)
retry_download = (
record.state == RunState.FAILED
and record.failure_phase == FailurePhase.DOWNLOAD
and record.return_code == 0
)
if not retry_download and record.state in (
RunState.FINISHED, RunState.FAILED, RunState.CANCELLED
):
raise ProjectResultUnavailableError(
record, f"run is already terminal ({record.state.value})"
)
# An attach attempt does not own a running processor's lock, so reader
# reconstruction failures must not finalize its processing state.
process_result = _result_processor_for_record(manager, record)
if retry_download:
# Resolve the reader first: a construction error must not turn a
# historically failed transfer into an orphan active run.
record = manager.resume_download(record)
def completed(result):
from .task_result import TaskResult
if isinstance(result, TaskResult):
result.run_record = manager.store.get(record.id)
if callback is not None:
callback(result)
return manager.attach(
record,
process_result=process_result,
client=executor,
callback=completed,
output_listener=output_listener,
)
[docs]
def retry_project_postprocessing(manager, run):
"""Explicitly parse preserved result files again without executing the task."""
record = _record(manager, run)
# Reader construction is outside the transition: programming errors and
# missing definitions must leave the original failure record unchanged.
processor = _result_processor_for_record(manager, record)
result = manager.retry_postprocessing(record, processor)
# TaskResult provenance belongs to the outputs layer, not the generic project manager.
# Generic processors may return immutable or scalar values. Only task
# results carry the optional project provenance attribute.
from .task_result import TaskResult
if isinstance(result, TaskResult):
result.run_record = manager.store.get(record.id)
return result
[docs]
def load_project_result(manager, run):
"""Reconstruct the historical TaskResult of one terminal project run."""
record = _record(manager, run)
if record.state not in (RunState.FINISHED, RunState.FAILED, RunState.CANCELLED):
raise ProjectResultUnavailableError(
record, f"run is still active ({record.state.value})"
)
# Restore every available file independently. Missing auxiliary files do
# not invalidate a historical result whose primary output is intact.
try:
record = manager.retrieve_result_files(record)
except HistoricalFileMismatchError as exc:
# Older KKRunner versions raise the digest mismatch directly, rather
# than returning a per-file failure. Preserve the same public error
# and store the primary result's unavailability in either case.
output_file = None if record.files is None else record.files.output_file
if output_file is not None:
record = manager.update_artifact_availability(
record, output_file, ArtifactAvailabilityState.FAILED, str(exc),
)
raise ProjectResultUnavailableError(record, str(exc)) from exc
result_files = record.files
if result_files is not None and result_files.captured_at is None:
raise ProjectResultUnavailableError(
record, "historical output is unavailable: no authoritative file snapshot"
)
if result_files is None or result_files.output_file is None:
raise ProjectResultUnavailableError(
record, "no persisted output result file"
)
output_file = result_files.output_file
output_available = manager.output_file_is_current(record)
if not output_available:
# Distinguish a changed historical file from a missing file: both must
# prevent parsing, but the user needs the actual reason for recovery.
output_error = (
result_files.stdout.availability_message
if result_files.stdout is not None else None
)
version = next((
item for item in result_files.output_versions
if os.path.abspath(os.fspath(item.path)) == os.path.abspath(os.fspath(output_file))
), None)
if version is not None and version.state() == FileState.OVERWRITTEN:
output_error = f"historical output was overwritten: {output_file}"
raise ProjectResultUnavailableError(
record, output_error or "output result file is unavailable"
)
reader = _reader_for_record(manager, record)
return_code = record.return_code
if return_code is None:
return_code = 0 if record.state == RunState.FINISHED else 1
input_file = None
if manager.input_file_is_current(record) and (
getattr(reader, "input_parameters", None) is not None
):
input_file = result_files.input_file
result = reader.read_from_file(
output_file,
return_code=return_code,
input_file=input_file,
directory=record.execution.directory.local,
)
result.run_record = record
return result