Skip to content

Commit 0b2f51a

Browse files
net0wellclaude
andcommitted
feat(core): contratos de gestão e motor IRunEngine (spec 004)
- Abstractions: ICatalogAdmin, IRunManager, IArtifactStore, IAuditWriter/IAuditReader, Actor, erros de domínio com códigos estáveis e IDs UUID v7 tipados. - IRunRecorder recebe todas as transições (execução, passo, tentativa, arquivos) e reserva a chave de idempotência; RunResult.Deduplicated. - IRunEngine: roda definições (rascunhos), retoma execuções que falharam e cancela execuções em andamento no processo. - CatalogManifests público para importar e exportar o formato de pasta; IStageValidator; verificação de sintaxe e hash de ambiente no IEnvironmentManager. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
1 parent c00401c commit 0b2f51a

25 files changed

Lines changed: 2374 additions & 199 deletions

‎src/PythonScriptRunner.Abstractions/Exceptions.cs‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -47,6 +47,61 @@ public VersionNotFoundException(string key, int version)
4747
public int Version { get; }
4848
}
4949

50+
/// <summary>The version exists but cannot run (it is a draft or was archived).</summary>
51+
public sealed class VersionNotRunnableException : PsrException
52+
{
53+
/// <summary>Creates the exception.</summary>
54+
/// <param name="key">Stage or pipeline key.</param>
55+
/// <param name="version">Requested version.</param>
56+
/// <param name="status">Current status of the version.</param>
57+
public VersionNotRunnableException(string key, int version, VersionStatus status)
58+
: base($"Version {version} of '{key}' is {status} and cannot run; only published versions run.")
59+
{
60+
Key = key;
61+
Version = version;
62+
Status = status;
63+
}
64+
65+
/// <summary>Stage or pipeline key.</summary>
66+
public string Key { get; }
67+
68+
/// <summary>Requested version.</summary>
69+
public int Version { get; }
70+
71+
/// <summary>Current status of the version.</summary>
72+
public VersionStatus Status { get; }
73+
}
74+
75+
/// <summary>The run does not exist (or is beyond the retention).</summary>
76+
public sealed class RunNotFoundException : PsrException
77+
{
78+
/// <summary>Creates the exception.</summary>
79+
/// <param name="runId">Requested run.</param>
80+
public RunNotFoundException(RunId runId)
81+
: base($"Run {runId} was not found.")
82+
{
83+
RunId = runId;
84+
}
85+
86+
/// <summary>Requested run.</summary>
87+
public RunId RunId { get; }
88+
}
89+
90+
/// <summary>The stored file does not exist (or is beyond the retention).</summary>
91+
public sealed class ArtifactNotFoundException : PsrException
92+
{
93+
/// <summary>Creates the exception.</summary>
94+
/// <param name="artifactId">Requested file.</param>
95+
public ArtifactNotFoundException(ArtifactId artifactId)
96+
: base($"Artifact {artifactId} was not found.")
97+
{
98+
ArtifactId = artifactId;
99+
}
100+
101+
/// <summary>Requested file.</summary>
102+
public ArtifactId ArtifactId { get; }
103+
}
104+
50105
/// <summary>One invalid input.</summary>
51106
/// <param name="Field">Field path (e.g. <c>coeficientes[2]</c>).</param>
52107
/// <param name="Code">Stable code (e.g. <c>MISSING_REQUIRED_INPUT</c>).</param>

‎src/PythonScriptRunner.Abstractions/Extensibility/Interfaces.cs‎

Lines changed: 125 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -2,24 +2,35 @@
22

33
namespace 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>
66
public 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>
2435
public 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>
3347
public 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);

‎src/PythonScriptRunner.Abstractions/Files/PsrFile.cs‎

Lines changed: 55 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -27,10 +27,20 @@ public sealed class PsrFile
2727

2828
private readonly string? _path;
2929
private readonly ReadOnlyMemory<byte>? _bytes;
30+
private readonly Func<CancellationToken, Task<Stream>>? _opener;
31+
private readonly long? _knownLength;
3032
private Stream? _stream;
3133
private string? _sha256;
3234

33-
private PsrFile(string fileName, string contentType, string? path, ReadOnlyMemory<byte>? bytes, Stream? stream, string? sha256)
35+
private PsrFile(
36+
string fileName,
37+
string contentType,
38+
string? path,
39+
ReadOnlyMemory<byte>? bytes,
40+
Stream? stream,
41+
string? sha256,
42+
Func<CancellationToken, Task<Stream>>? opener = null,
43+
long? knownLength = null)
3444
{
3545
ArgumentException.ThrowIfNullOrWhiteSpace(fileName);
3646
ArgumentException.ThrowIfNullOrWhiteSpace(contentType);
@@ -40,6 +50,8 @@ private PsrFile(string fileName, string contentType, string? path, ReadOnlyMemor
4050
_bytes = bytes;
4151
_stream = stream;
4252
_sha256 = sha256;
53+
_opener = opener;
54+
_knownLength = knownLength;
4355
}
4456

4557
/// <summary>A file on disk.</summary>
@@ -90,6 +102,38 @@ public static PsrFile FromText(string text, string fileName, string contentType
90102
public static PsrFile FromProducedFile(string path, string fileName, string contentType, string sha256) =>
91103
new(fileName, contentType, Path.GetFullPath(path), null, null, sha256);
92104

105+
/// <summary>A stored file (e.g. in the database) that is streamed on demand.</summary>
106+
/// <param name="artifactId">Identifier of the stored file.</param>
107+
/// <param name="fileName">File name.</param>
108+
/// <param name="contentType">MIME type.</param>
109+
/// <param name="length">Size in bytes.</param>
110+
/// <param name="sha256">SHA-256 as lowercase hex.</param>
111+
/// <param name="open">Opens the content; called once per read.</param>
112+
public static PsrFile FromArtifact(
113+
ArtifactId artifactId, string fileName, string contentType, long length, string sha256, Func<CancellationToken, Task<Stream>> open)
114+
{
115+
ArgumentNullException.ThrowIfNull(open);
116+
var file = new PsrFile(fileName, contentType, null, null, null, sha256, open, length);
117+
file.AttachArtifact(artifactId);
118+
return file;
119+
}
120+
121+
/// <summary>Identifier of the stored copy of this file, when a persistence package stored it.</summary>
122+
public ArtifactId? ArtifactId { get; private set; }
123+
124+
/// <summary>Associates the file with its stored copy (used by persistence packages).</summary>
125+
/// <param name="artifactId">Identifier of the stored file.</param>
126+
/// <exception cref="InvalidOperationException">The file is already associated with another stored file.</exception>
127+
public void AttachArtifact(ArtifactId artifactId)
128+
{
129+
if (ArtifactId is { } current && current != artifactId)
130+
{
131+
throw new InvalidOperationException($"File '{FileName}' is already stored as artifact {current}.");
132+
}
133+
134+
ArtifactId = artifactId;
135+
}
136+
93137
/// <summary>File name (without directories).</summary>
94138
public string FileName { get; }
95139

@@ -114,6 +158,11 @@ public long? Length
114158
return bytes.Length;
115159
}
116160

161+
if (_knownLength is { } known)
162+
{
163+
return known;
164+
}
165+
117166
return _stream is { CanSeek: true } stream ? stream.Length - stream.Position : null;
118167
}
119168
}
@@ -159,6 +208,11 @@ public Task<Stream> OpenReadAsync(CancellationToken cancellationToken = default)
159208
return Task.FromResult<Stream>(new MemoryStream(bytes.ToArray(), writable: false));
160209
}
161210

211+
if (_opener is not null)
212+
{
213+
return _opener(cancellationToken);
214+
}
215+
162216
var stream = Interlocked.Exchange(ref _stream, null)
163217
?? throw new InvalidOperationException($"The stream of file '{FileName}' was already consumed.");
164218
return Task.FromResult(stream);

0 commit comments

Comments
 (0)