Skip to content

Commit 2f33345

Browse files
net0wellclaude
andcommitted
feat(core): Abstractions e Core Runner (spec 001)
- Abstractions: FieldType/FieldDefinition, StageDefinition, RunResult, PsrFile, ICatalog, ISecretProvider, IRunRecorder e exceções - Core: catálogo em código e em pasta (stage.json validado pelo JSON Schema), binding/validação das entradas, ambientes uv com lock e cache por hash, executor de processo (ambiente limpo, timeout, cancelamento, Job Object no Windows, cauda de log com segredos mascarados, validação das saídas), RunStageAsync com retry, telemetria (ActivitySource/Meter) e AddPythonScriptRunner - 62 testes (unitários + integração com Python real), um por critério de aceite Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
1 parent 642d2ca commit 2f33345

50 files changed

Lines changed: 5575 additions & 0 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.
Lines changed: 105 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,105 @@
1+
namespace PythonScriptRunner;
2+
3+
/// <summary>Base class of PythonScriptRunner exceptions.</summary>
4+
public abstract class PsrException : Exception
5+
{
6+
/// <summary>Creates the exception.</summary>
7+
/// <param name="message">Message.</param>
8+
/// <param name="innerException">Cause.</param>
9+
protected PsrException(string message, Exception? innerException = null)
10+
: base(message, innerException)
11+
{
12+
}
13+
}
14+
15+
/// <summary>The stage does not exist in the catalog.</summary>
16+
public sealed class StageNotFoundException : PsrException
17+
{
18+
/// <summary>Creates the exception.</summary>
19+
/// <param name="stageKey">Requested key.</param>
20+
public StageNotFoundException(string stageKey)
21+
: base($"Stage '{stageKey}' was not found.")
22+
{
23+
StageKey = stageKey;
24+
}
25+
26+
/// <summary>Requested key.</summary>
27+
public string StageKey { get; }
28+
}
29+
30+
/// <summary>The stage exists but not in the requested version.</summary>
31+
public sealed class VersionNotFoundException : PsrException
32+
{
33+
/// <summary>Creates the exception.</summary>
34+
/// <param name="key">Stage or pipeline key.</param>
35+
/// <param name="version">Requested version.</param>
36+
public VersionNotFoundException(string key, int version)
37+
: base($"Version {version} of '{key}' was not found.")
38+
{
39+
Key = key;
40+
Version = version;
41+
}
42+
43+
/// <summary>Stage or pipeline key.</summary>
44+
public string Key { get; }
45+
46+
/// <summary>Requested version.</summary>
47+
public int Version { get; }
48+
}
49+
50+
/// <summary>One invalid input.</summary>
51+
/// <param name="Field">Field path (e.g. <c>coeficientes[2]</c>).</param>
52+
/// <param name="Code">Stable code (e.g. <c>MISSING_REQUIRED_INPUT</c>).</param>
53+
/// <param name="Message">Human-readable message.</param>
54+
public sealed record InputError(string Field, string Code, string Message);
55+
56+
/// <summary>The inputs of a call do not match the contract; no run was created.</summary>
57+
public sealed class InputValidationException : PsrException
58+
{
59+
/// <summary>Creates the exception.</summary>
60+
/// <param name="errors">Every invalid input.</param>
61+
public InputValidationException(IReadOnlyList<InputError> errors)
62+
: base("Invalid inputs: " + string.Join("; ", errors.Select(e => $"{e.Field}: {e.Message}")))
63+
{
64+
Errors = errors;
65+
}
66+
67+
/// <summary>Every invalid input.</summary>
68+
public IReadOnlyList<InputError> Errors { get; }
69+
}
70+
71+
/// <summary>The runner, a catalog or a stage definition is misconfigured.</summary>
72+
public sealed class PsrConfigurationException : PsrException
73+
{
74+
/// <summary>Creates the exception.</summary>
75+
/// <param name="message">What is wrong.</param>
76+
/// <param name="innerException">Cause.</param>
77+
public PsrConfigurationException(string message, Exception? innerException = null)
78+
: base(message, innerException)
79+
{
80+
}
81+
}
82+
83+
/// <summary>Thrown by <see cref="RunResult.EnsureSuccess"/> when the run did not succeed.</summary>
84+
public sealed class RunFailedException : PsrException
85+
{
86+
/// <summary>Creates the exception.</summary>
87+
/// <param name="result">The run result.</param>
88+
public RunFailedException(RunResult result)
89+
: base(BuildMessage(result))
90+
{
91+
Result = result;
92+
}
93+
94+
/// <summary>The run result.</summary>
95+
public RunResult Result { get; }
96+
97+
private static string BuildMessage(RunResult result)
98+
{
99+
ArgumentNullException.ThrowIfNull(result);
100+
var error = result.Error;
101+
return error is null
102+
? $"Run {result.Id} ended with status {result.Status}."
103+
: $"Run {result.Id} ended with status {result.Status}: [{error.Kind}{(error.Code is null ? "" : $"/{error.Code}")}] {error.Message}";
104+
}
105+
}
Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
using System.Text.Json.Nodes;
2+
3+
namespace PythonScriptRunner;
4+
5+
/// <summary>Source of stage definitions (memory, folder or database).</summary>
6+
public interface ICatalog
7+
{
8+
/// <summary>Finds a stage version.</summary>
9+
/// <param name="key">Stage key.</param>
10+
/// <param name="version">Exact version, or <c>null</c> for the latest published version.</param>
11+
/// <param name="cancellationToken">Cancellation token.</param>
12+
/// <returns>The definition, or <c>null</c> when not found.</returns>
13+
ValueTask<StageDefinition?> FindStageAsync(string key, int? version, CancellationToken cancellationToken = default);
14+
}
15+
16+
/// <summary>Resolves the secrets declared by stages.</summary>
17+
public interface ISecretProvider
18+
{
19+
/// <summary>Returns the value of a secret, or <c>null</c> when it is not configured.</summary>
20+
/// <param name="name">Secret name (e.g. <c>SMTP_PASSWORD</c>).</param>
21+
/// <param name="cancellationToken">Cancellation token.</param>
22+
ValueTask<string?> GetSecretAsync(string name, CancellationToken cancellationToken = default);
23+
}
24+
25+
/// <summary>Receives run transitions so they can be persisted. The default implementation does nothing.</summary>
26+
public interface IRunRecorder
27+
{
28+
/// <summary>A run started.</summary>
29+
/// <param name="run">Run data.</param>
30+
/// <param name="cancellationToken">Cancellation token.</param>
31+
ValueTask RunStartedAsync(RunStarted run, CancellationToken cancellationToken);
32+
33+
/// <summary>An attempt finished.</summary>
34+
/// <param name="attempt">Attempt data.</param>
35+
/// <param name="cancellationToken">Cancellation token.</param>
36+
ValueTask AttemptFinishedAsync(AttemptFinished attempt, CancellationToken cancellationToken);
37+
38+
/// <summary>A run finished.</summary>
39+
/// <param name="run">Final data.</param>
40+
/// <param name="cancellationToken">Cancellation token.</param>
41+
ValueTask RunFinishedAsync(RunFinished run, CancellationToken cancellationToken);
42+
}
43+
44+
/// <summary>A run started.</summary>
45+
/// <param name="RunId">Run identifier.</param>
46+
/// <param name="Kind">What is executed.</param>
47+
/// <param name="TargetKey">Stage or pipeline key.</param>
48+
/// <param name="TargetVersion">Stage or pipeline version.</param>
49+
/// <param name="TriggeredBy">Who requested the run.</param>
50+
/// <param name="StartedAt">Start time.</param>
51+
/// <param name="Inputs">Validated inputs in wire format.</param>
52+
public sealed record RunStarted(
53+
RunId RunId, RunKind Kind, string TargetKey, int TargetVersion, string TriggeredBy, DateTimeOffset StartedAt, JsonObject Inputs);
54+
55+
/// <summary>An attempt finished.</summary>
56+
/// <param name="RunId">Run identifier.</param>
57+
/// <param name="StepKey">Step key.</param>
58+
/// <param name="Attempt">Attempt outcome.</param>
59+
public sealed record AttemptFinished(RunId RunId, string StepKey, AttemptResult Attempt);
60+
61+
/// <summary>A run finished.</summary>
62+
/// <param name="RunId">Run identifier.</param>
63+
/// <param name="Status">Final status.</param>
64+
/// <param name="FinishedAt">End time.</param>
65+
/// <param name="Outputs">Declared outputs in wire format.</param>
66+
/// <param name="Error">Failure, when the run did not succeed.</param>
67+
public sealed record RunFinished(RunId RunId, RunStatus Status, DateTimeOffset FinishedAt, JsonObject? Outputs, RunError? Error);
Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
using System.Text.Json.Nodes;
2+
3+
namespace PythonScriptRunner;
4+
5+
/// <summary>Declaration of one input or output of a stage.</summary>
6+
/// <param name="Name">Field name (<c>^[a-z_][a-z0-9_]{0,63}$</c>).</param>
7+
/// <param name="Type">Field type.</param>
8+
public sealed record FieldDefinition(string Name, FieldType Type)
9+
{
10+
/// <summary>Whether a value must be provided (inputs) or produced (outputs). Default: <c>true</c>.</summary>
11+
public bool Required { get; init; } = true;
12+
13+
/// <summary>Default value in wire format; not allowed for files and tables.</summary>
14+
public JsonNode? Default { get; init; }
15+
16+
/// <summary>Text shown in the panel and in generated forms (up to 500 chars).</summary>
17+
public string? Description { get; init; }
18+
19+
/// <summary>Accepted MIME types for <c>file</c>/<c>list&lt;file&gt;</c> fields (optional).</summary>
20+
public IReadOnlyList<string>? ContentTypes { get; init; }
21+
22+
/// <summary>Declared columns of a <c>table</c> field (optional).</summary>
23+
public IReadOnlyList<TableColumn>? Columns { get; init; }
24+
}
25+
26+
/// <summary>A declared column of a <c>table</c> field.</summary>
27+
/// <param name="Name">Column name.</param>
28+
/// <param name="Type">Scalar type of the column.</param>
29+
public sealed record TableColumn(string Name, FieldType Type);

0 commit comments

Comments
 (0)