22
33namespace PythonScriptRunner ;
44
5- /// <summary>Source of stage definitions (memory, folder or database).</summary>
5+ /// <summary>Source of stage and pipeline definitions (memory, folder or database).</summary>
66public interface ICatalog
77{
88 /// <summary>Finds a stage version.</summary>
99 /// <param name="key">Stage key.</param>
1010 /// <param name="version">Exact version, or <c>null</c> for the latest published version.</param>
1111 /// <param name="cancellationToken">Cancellation token.</param>
1212 /// <returns>The definition, or <c>null</c> when not found.</returns>
13+ /// <exception cref="VersionNotRunnableException">The version exists but is a draft or archived.</exception>
1314 ValueTask < StageDefinition ? > FindStageAsync ( string key , int ? version , CancellationToken cancellationToken = default ) ;
1415
1516 /// <summary>Finds a pipeline version.</summary>
1617 /// <param name="key">Pipeline key.</param>
1718 /// <param name="version">Exact version, or <c>null</c> for the latest published version.</param>
1819 /// <param name="cancellationToken">Cancellation token.</param>
1920 /// <returns>The definition, or <c>null</c> when not found.</returns>
21+ /// <exception cref="VersionNotRunnableException">The version exists but is a draft or archived.</exception>
2022 ValueTask < PipelineDefinition ? > FindPipelineAsync ( string key , int ? version , CancellationToken cancellationToken = default ) ;
2123}
2224
25+ /// <summary>Validates stage definitions (contract, limits and secret names).</summary>
26+ public interface IStageValidator
27+ {
28+ /// <summary>Validates a stage definition.</summary>
29+ /// <param name="stage">The definition.</param>
30+ /// <returns>Errors (code <c>STAGE_DEFINITION</c>) and warnings.</returns>
31+ ValidationReport Validate ( StageDefinition stage ) ;
32+ }
33+
2334/// <summary>Resolves the secrets declared by stages.</summary>
2435public interface ISecretProvider
2536{
@@ -29,46 +40,145 @@ public interface ISecretProvider
2940 ValueTask < string ? > GetSecretAsync ( string name , CancellationToken cancellationToken = default ) ;
3041}
3142
32- /// <summary>Receives run transitions so they can be persisted. The default implementation does nothing.</summary>
43+ /// <summary>
44+ /// Receives every transition of a run so it can be persisted. The default implementation does nothing; the
45+ /// EntityFrameworkCore package stores runs, steps, attempts, logs and files.
46+ /// </summary>
3347public interface IRunRecorder
3448{
35- /// <summary>A run started.</summary>
49+ /// <summary>A run is about to start (inputs already validated). Reserves the idempotency key.</summary>
50+ /// <param name="run">Run data.</param>
51+ /// <param name="cancellationToken">Cancellation token.</param>
52+ /// <returns>The existing run when the idempotency key was already used (the new run must not start); otherwise <c>null</c>.</returns>
53+ ValueTask < RunResult ? > RunStartingAsync ( RunStarting run , CancellationToken cancellationToken ) ;
54+
55+ /// <summary>A failed run is being reprocessed: it is running again and skipped steps are pending.</summary>
3656 /// <param name="run">Run data.</param>
3757 /// <param name="cancellationToken">Cancellation token.</param>
38- ValueTask RunStartedAsync ( RunStarted run , CancellationToken cancellationToken ) ;
58+ ValueTask RunResumingAsync ( RunResuming run , CancellationToken cancellationToken ) ;
59+
60+ /// <summary>A step started with its resolved inputs.</summary>
61+ /// <param name="step">Step data.</param>
62+ /// <param name="cancellationToken">Cancellation token.</param>
63+ ValueTask StepStartedAsync ( StepStarted step , CancellationToken cancellationToken ) ;
3964
40- /// <summary>An attempt finished.</summary>
65+ /// <summary>An attempt (one Python process) started.</summary>
66+ /// <param name="attempt">Attempt data.</param>
67+ /// <param name="cancellationToken">Cancellation token.</param>
68+ ValueTask AttemptStartedAsync ( AttemptStarted attempt , CancellationToken cancellationToken ) ;
69+
70+ /// <summary>An attempt finished (with its logs).</summary>
4171 /// <param name="attempt">Attempt data.</param>
4272 /// <param name="cancellationToken">Cancellation token.</param>
4373 ValueTask AttemptFinishedAsync ( AttemptFinished attempt , CancellationToken cancellationToken ) ;
4474
75+ /// <summary>A step finished (succeeded with outputs and files, failed, cancelled or skipped).</summary>
76+ /// <param name="step">Step data.</param>
77+ /// <param name="cancellationToken">Cancellation token.</param>
78+ ValueTask StepFinishedAsync ( StepFinished step , CancellationToken cancellationToken ) ;
79+
4580 /// <summary>A run finished.</summary>
4681 /// <param name="run">Final data.</param>
4782 /// <param name="cancellationToken">Cancellation token.</param>
4883 ValueTask RunFinishedAsync ( RunFinished run , CancellationToken cancellationToken ) ;
4984}
5085
51- /// <summary>A run started.</summary>
86+ /// <summary>A run is about to start.</summary>
87+ public sealed record RunStarting
88+ {
89+ /// <summary>Run identifier (its timestamp is the creation time).</summary>
90+ public required RunId RunId { get ; init ; }
91+
92+ /// <summary>What is executed.</summary>
93+ public required RunKind Kind { get ; init ; }
94+
95+ /// <summary>Stage or pipeline key.</summary>
96+ public required string TargetKey { get ; init ; }
97+
98+ /// <summary>Stage or pipeline version.</summary>
99+ public required int TargetVersion { get ; init ; }
100+
101+ /// <summary>How the run started.</summary>
102+ public required RunTrigger Trigger { get ; init ; }
103+
104+ /// <summary>Who requested the run.</summary>
105+ public required string TriggeredBy { get ; init ; }
106+
107+ /// <summary>Deduplication key given by the caller.</summary>
108+ public string ? IdempotencyKey { get ; init ; }
109+
110+ /// <summary>Validated inputs in wire format (files carry metadata only).</summary>
111+ public required JsonObject Inputs { get ; init ; }
112+
113+ /// <summary>Input files by field name.</summary>
114+ public IReadOnlyDictionary < string , IReadOnlyList < PsrFile > > InputFiles { get ; init ; } = new Dictionary < string , IReadOnlyList < PsrFile > > ( ) ;
115+
116+ /// <summary>Steps that will run, in order.</summary>
117+ public required IReadOnlyList < PlannedStep > Steps { get ; init ; }
118+
119+ /// <summary>Start time.</summary>
120+ public required DateTimeOffset StartedAt { get ; init ; }
121+ }
122+
123+ /// <summary>A step of a run that is about to start.</summary>
124+ /// <param name="StepKey">Step key (the stage key for single-stage runs).</param>
125+ /// <param name="Order">1-based position.</param>
126+ /// <param name="StageKey">Stage key.</param>
127+ /// <param name="StageVersion">Exact stage version.</param>
128+ public sealed record PlannedStep ( string StepKey , int Order , string StageKey , int StageVersion ) ;
129+
130+ /// <summary>A failed run is being reprocessed.</summary>
131+ /// <param name="RunId">Run identifier.</param>
132+ /// <param name="TriggeredBy">Who reprocesses.</param>
133+ /// <param name="ResumedAt">When.</param>
134+ public sealed record RunResuming ( RunId RunId , string TriggeredBy , DateTimeOffset ResumedAt ) ;
135+
136+ /// <summary>A step started.</summary>
52137/// <param name="RunId">Run identifier.</param>
53- /// <param name="Kind">What is executed .</param>
54- /// <param name="TargetKey">Stage or pipeline key .</param>
55- /// <param name="TargetVersion">Stage or pipeline version .</param>
56- /// <param name="TriggeredBy">Who requested the run .</param>
138+ /// <param name="StepKey">Step key .</param>
139+ /// <param name="Order">1-based position .</param>
140+ /// <param name="Inputs">Resolved inputs in wire format .</param>
141+ /// <param name="InputFiles">Input files by field name .</param>
57142/// <param name="StartedAt">Start time.</param>
58- /// <param name="Inputs">Validated inputs in wire format.</param>
59- public sealed record RunStarted (
60- RunId RunId , RunKind Kind , string TargetKey , int TargetVersion , string TriggeredBy , DateTimeOffset StartedAt , JsonObject Inputs ) ;
143+ public sealed record StepStarted (
144+ RunId RunId , string StepKey , int Order , JsonObject Inputs , IReadOnlyDictionary < string , IReadOnlyList < PsrFile > > InputFiles , DateTimeOffset StartedAt ) ;
145+
146+ /// <summary>An attempt started.</summary>
147+ /// <param name="RunId">Run identifier.</param>
148+ /// <param name="StepKey">Step key.</param>
149+ /// <param name="Order">1-based position of the step.</param>
150+ /// <param name="AttemptId">Attempt identifier.</param>
151+ /// <param name="Number">1-based attempt number.</param>
152+ /// <param name="Cause">Why it started.</param>
153+ /// <param name="TriggeredBy">Who started it.</param>
154+ /// <param name="StartedAt">Start time.</param>
155+ public sealed record AttemptStarted (
156+ RunId RunId , string StepKey , int Order , AttemptId AttemptId , int Number , AttemptCause Cause , string TriggeredBy , DateTimeOffset StartedAt ) ;
61157
62158/// <summary>An attempt finished.</summary>
63159/// <param name="RunId">Run identifier.</param>
64160/// <param name="StepKey">Step key.</param>
161+ /// <param name="Order">1-based position of the step.</param>
65162/// <param name="Attempt">Attempt outcome.</param>
66- public sealed record AttemptFinished ( RunId RunId , string StepKey , AttemptResult Attempt ) ;
163+ public sealed record AttemptFinished ( RunId RunId , string StepKey , int Order , AttemptResult Attempt ) ;
164+
165+ /// <summary>A step finished.</summary>
166+ /// <param name="RunId">Run identifier.</param>
167+ /// <param name="Step">Step outcome (outputs and files when it succeeded).</param>
168+ /// <param name="FinishedAt">End time.</param>
169+ public sealed record StepFinished ( RunId RunId , StepResult Step , DateTimeOffset FinishedAt ) ;
67170
68171/// <summary>A run finished.</summary>
69172/// <param name="RunId">Run identifier.</param>
70173/// <param name="Status">Final status.</param>
71174/// <param name="FinishedAt">End time.</param>
72175/// <param name="Outputs">Declared outputs in wire format.</param>
176+ /// <param name="OutputFiles">Declared file outputs by name.</param>
73177/// <param name="Error">Failure, when the run did not succeed.</param>
74- public sealed record RunFinished ( RunId RunId , RunStatus Status , DateTimeOffset FinishedAt , JsonObject ? Outputs , RunError ? Error ) ;
178+ public sealed record RunFinished (
179+ RunId RunId ,
180+ RunStatus Status ,
181+ DateTimeOffset FinishedAt ,
182+ JsonObject ? Outputs ,
183+ IReadOnlyDictionary < string , IReadOnlyList < PsrFile > > ? OutputFiles ,
184+ RunError ? Error ) ;
0 commit comments