Skip to content

Commit e211510

Browse files
net0wellclaude
andcommitted
feat(core): passo isolado no motor e contratos de fila, eventos e agendamentos (specs 005, 006)
- IRunEngine.ExecuteStepAsync executa uma tentativa de um passo sem gravar nada (D-102); BindInputs valida entradas sem executar; RemoveOrphanWorkFolders limpa pastas. - Contratos v1: IRunQueue/RunHandle, RunEvent/IRunEventHandler, ExecuteStepCommand, StartPipelineRunCommand, CancelRunCommand e PsrMessageJson. - Agendamentos no ICatalogAdmin (D-101) e novos códigos de erro. - RunOptions.CorrelationId; RunSnapshot com correlação, agendamento e trigger_details (D-108). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
1 parent be4beb5 commit e211510

14 files changed

Lines changed: 699 additions & 12 deletions

File tree

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

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -107,6 +107,12 @@ public sealed record RunStarting
107107
/// <summary>Deduplication key given by the caller.</summary>
108108
public string? IdempotencyKey { get; init; }
109109

110+
/// <summary>Correlation given by the caller.</summary>
111+
public string? CorrelationId { get; init; }
112+
113+
/// <summary>W3C trace context of the caller (<c>traceparent</c>).</summary>
114+
public string? TraceParent { get; init; }
115+
110116
/// <summary>Validated inputs in wire format (files carry metadata only).</summary>
111117
public required JsonObject Inputs { get; init; }
112118

‎src/PythonScriptRunner.Abstractions/Ids.cs‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,10 @@
1+
using System.Text.Json.Serialization;
2+
13
namespace PythonScriptRunner;
24

35
/// <summary>Identifier of a run (time-ordered UUID v7). Its timestamp is the creation time of the run.</summary>
46
/// <param name="Value">The underlying GUID.</param>
7+
[JsonConverter(typeof(RunIdJsonConverter))]
58
public readonly record struct RunId(Guid Value)
69
{
710
/// <summary>Creates a new time-ordered identifier.</summary>
@@ -35,6 +38,7 @@ public readonly record struct AttemptId(Guid Value)
3538

3639
/// <summary>Identifier of a step within a run (time-ordered UUID v7).</summary>
3740
/// <param name="Value">The underlying GUID.</param>
41+
[JsonConverter(typeof(StepRunIdJsonConverter))]
3842
public readonly record struct StepRunId(Guid Value)
3943
{
4044
/// <summary>Creates a new time-ordered identifier.</summary>

‎src/PythonScriptRunner.Abstractions/Management/CatalogAdmin.cs‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -238,6 +238,52 @@ Task<PipelineDetail> UpdatePipelineRetentionAsync(
238238
/// <param name="actor">Author.</param>
239239
/// <param name="cancellationToken">Cancellation token.</param>
240240
Task<ImportReport> ImportAsync(Stream zip, Actor actor, CancellationToken cancellationToken = default);
241+
242+
/// <summary>Lists schedules ordered by name.</summary>
243+
/// <param name="query">Pipeline filter and page.</param>
244+
/// <param name="cancellationToken">Cancellation token.</param>
245+
Task<Page<ScheduleDetail>> ListSchedulesAsync(ScheduleQuery query, CancellationToken cancellationToken = default);
246+
247+
/// <summary>Reads a schedule.</summary>
248+
/// <param name="id">Schedule identifier.</param>
249+
/// <param name="cancellationToken">Cancellation token.</param>
250+
/// <returns>The schedule, or <c>null</c> when it does not exist.</returns>
251+
Task<ScheduleDetail?> GetScheduleAsync(ScheduleId id, CancellationToken cancellationToken = default);
252+
253+
/// <summary>
254+
/// Creates a cron schedule of a pipeline. Validates the cron expression, the IANA time zone, the version (pinned or the latest
255+
/// published) and the fixed inputs: <c>SCHEDULE_INVALID</c>, <c>SCHEDULE_FILE_INPUT</c> (pipelines with file inputs cannot be
256+
/// scheduled) or <see cref="InputValidationException"/>.
257+
/// </summary>
258+
/// <param name="pipelineKey">Pipeline key.</param>
259+
/// <param name="schedule">Schedule settings.</param>
260+
/// <param name="actor">Author.</param>
261+
/// <param name="cancellationToken">Cancellation token.</param>
262+
Task<ScheduleDetail> CreateScheduleAsync(string pipelineKey, ScheduleData schedule, Actor actor, CancellationToken cancellationToken = default);
263+
264+
/// <summary>Changes a schedule (same validation as <see cref="CreateScheduleAsync"/>); the next run is recomputed.</summary>
265+
/// <param name="id">Schedule identifier.</param>
266+
/// <param name="schedule">New settings.</param>
267+
/// <param name="expectedRowVersion">Row version read by the caller.</param>
268+
/// <param name="actor">Author.</param>
269+
/// <param name="cancellationToken">Cancellation token.</param>
270+
Task<ScheduleDetail> UpdateScheduleAsync(
271+
ScheduleId id, ScheduleData schedule, uint expectedRowVersion, Actor actor, CancellationToken cancellationToken = default);
272+
273+
/// <summary>Enables or disables a schedule; enabling recomputes the next run from now.</summary>
274+
/// <param name="id">Schedule identifier.</param>
275+
/// <param name="enabled">Whether it fires.</param>
276+
/// <param name="expectedRowVersion">Row version read by the caller.</param>
277+
/// <param name="actor">Author.</param>
278+
/// <param name="cancellationToken">Cancellation token.</param>
279+
Task<ScheduleDetail> SetScheduleEnabledAsync(
280+
ScheduleId id, bool enabled, uint expectedRowVersion, Actor actor, CancellationToken cancellationToken = default);
281+
282+
/// <summary>Deletes a schedule (its runs stay in the history).</summary>
283+
/// <param name="id">Schedule identifier.</param>
284+
/// <param name="actor">Author.</param>
285+
/// <param name="cancellationToken">Cancellation token.</param>
286+
Task DeleteScheduleAsync(ScheduleId id, Actor actor, CancellationToken cancellationToken = default);
241287
}
242288

243289
/// <summary>Search and page of a catalog list.</summary>

‎src/PythonScriptRunner.Abstractions/Management/DomainErrors.cs‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -56,6 +56,18 @@ public static class PsrErrorCodes
5656

5757
/// <summary>The imported archive is not a valid catalog folder.</summary>
5858
public const string ImportInvalid = "IMPORT_INVALID";
59+
60+
/// <summary>The schedule does not exist.</summary>
61+
public const string ScheduleNotFound = "SCHEDULE_NOT_FOUND";
62+
63+
/// <summary>The schedule has an invalid cron expression, time zone or version.</summary>
64+
public const string ScheduleInvalid = "SCHEDULE_INVALID";
65+
66+
/// <summary>Pipelines with file inputs cannot be scheduled nor started by the public queue command (D-89).</summary>
67+
public const string ScheduleFileInput = "SCHEDULE_FILE_INPUT";
68+
69+
/// <summary>The pipeline has file inputs, which the public queue command cannot send (D-89).</summary>
70+
public const string FileInputNotAllowed = "FILE_INPUT_NOT_ALLOWED";
5971
}
6072

6173
/// <summary>A business rule rejected the operation; <see cref="Code"/> is stable (see <see cref="PsrErrorCodes"/>).</summary>

‎src/PythonScriptRunner.Abstractions/Management/RunManagement.cs‎

Lines changed: 13 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -38,7 +38,10 @@ public interface IRunManager
3838
/// </summary>
3939
/// <param name="runId">Run identifier.</param>
4040
/// <param name="actor">Who reprocesses.</param>
41-
/// <param name="mode"><see cref="ExecutionMode.Sync"/> runs it now in this process; <see cref="ExecutionMode.Async"/> needs a run queue.</param>
41+
/// <param name="mode">
42+
/// <see cref="ExecutionMode.Sync"/> runs it now in this process; <see cref="ExecutionMode.Async"/> queues the failed step for the
43+
/// workers (requires the RabbitMQ package).
44+
/// </param>
4245
/// <param name="cancellationToken">Cancellation token (cancels a synchronous reprocess).</param>
4346
/// <returns>The run after reprocessing (sync) or after it was queued (async).</returns>
4447
Task<RunSnapshot> ReprocessAsync(RunId runId, Actor actor, ExecutionMode mode = ExecutionMode.Async, CancellationToken cancellationToken = default);
@@ -141,6 +144,15 @@ public sealed record RunSnapshot
141144
/// <summary>Idempotency key given by the caller.</summary>
142145
public string? IdempotencyKey { get; init; }
143146

147+
/// <summary>Correlation given by the caller (returned in the events).</summary>
148+
public string? CorrelationId { get; init; }
149+
150+
/// <summary>Schedule that fired the run.</summary>
151+
public ScheduleId? ScheduleId { get; init; }
152+
153+
/// <summary>Details of the trigger, e.g. <c>{"scheduledFor": "...", "missedOccurrences": 10}</c> for a schedule recovery.</summary>
154+
public JsonObject? TriggerDetails { get; init; }
155+
144156
/// <summary>Creation time.</summary>
145157
public required DateTimeOffset CreatedAt { get; init; }
146158

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
using System.Text.Json.Nodes;
2+
3+
namespace PythonScriptRunner;
4+
5+
/// <summary>Settings of a cron schedule of a pipeline.</summary>
6+
public sealed record ScheduleData
7+
{
8+
/// <summary>Default IANA time zone of schedules.</summary>
9+
public const string DefaultTimeZone = "America/Sao_Paulo";
10+
11+
/// <summary>Display name (1-200 chars).</summary>
12+
public required string Name { get; init; }
13+
14+
/// <summary>Cron expression with 5 fields (minute precision) or 6 fields (with seconds).</summary>
15+
public required string Cron { get; init; }
16+
17+
/// <summary>IANA time zone in which the expression is evaluated (daylight saving time handled).</summary>
18+
public string TimeZone { get; init; } = DefaultTimeZone;
19+
20+
/// <summary>Version to run; <c>null</c> runs the latest published version at each firing.</summary>
21+
public int? PinnedVersion { get; init; }
22+
23+
/// <summary>Fixed inputs of the pipeline (no files).</summary>
24+
public JsonObject Inputs { get; init; } = [];
25+
26+
/// <summary>Whether the schedule fires.</summary>
27+
public bool IsEnabled { get; init; } = true;
28+
}
29+
30+
/// <summary>A stored schedule.</summary>
31+
public sealed record ScheduleDetail
32+
{
33+
/// <summary>Identifier.</summary>
34+
public required ScheduleId Id { get; init; }
35+
36+
/// <summary>Scheduled pipeline.</summary>
37+
public required string PipelineKey { get; init; }
38+
39+
/// <summary>Settings.</summary>
40+
public required ScheduleData Data { get; init; }
41+
42+
/// <summary>Next firing (UTC); <c>null</c> when disabled.</summary>
43+
public DateTimeOffset? NextRunAt { get; init; }
44+
45+
/// <summary>Last firing.</summary>
46+
public DateTimeOffset? LastFiredAt { get; init; }
47+
48+
/// <summary>Run created by the last successful firing.</summary>
49+
public RunId? LastRunId { get; init; }
50+
51+
/// <summary>Why the last firing was rejected (cleared by the next successful one).</summary>
52+
public string? LastError { get; init; }
53+
54+
/// <summary>Row version for optimistic concurrency.</summary>
55+
public required uint RowVersion { get; init; }
56+
57+
/// <summary>Who created and last changed it.</summary>
58+
public required Authorship Authorship { get; init; }
59+
}
60+
61+
/// <summary>Filter and page of a schedule list.</summary>
62+
/// <param name="PipelineKey">Only schedules of this pipeline.</param>
63+
/// <param name="PageNumber">1-based page number.</param>
64+
/// <param name="PageSize">Items per page (1-100).</param>
65+
public sealed record ScheduleQuery(string? PipelineKey = null, int PageNumber = 1, int PageSize = 25);
Lines changed: 102 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,102 @@
1+
using System.Text.Json;
2+
using System.Text.Json.Nodes;
3+
using System.Text.Json.Serialization;
4+
5+
namespace PythonScriptRunner;
6+
7+
/// <summary>
8+
/// Internal command <c>psr.execute-step.v1</c>: execute one attempt of a step. It carries identifiers only; inputs and files
9+
/// stay in the database.
10+
/// </summary>
11+
/// <param name="RunId">Run identifier.</param>
12+
/// <param name="RunCreatedAt">Creation time of the run (its partition).</param>
13+
/// <param name="StepRunId">Step identifier.</param>
14+
/// <param name="Attempt">Attempt number to start.</param>
15+
public sealed record ExecuteStepCommand(RunId RunId, DateTimeOffset RunCreatedAt, StepRunId StepRunId, int Attempt)
16+
{
17+
/// <summary>Why the attempt starts.</summary>
18+
public AttemptCause Cause { get; init; } = AttemptCause.Initial;
19+
20+
/// <summary>Who started the attempt (the reprocessing user, or the run's caller).</summary>
21+
public string? TriggeredBy { get; init; }
22+
}
23+
24+
/// <summary>
25+
/// Public command <c>psr.start-pipeline-run.v1</c> (exchange <c>psr.public</c>): lets systems that are not .NET start a
26+
/// pipeline. Inputs cannot contain files.
27+
/// </summary>
28+
public sealed record StartPipelineRunCommand
29+
{
30+
/// <summary>Pipeline key.</summary>
31+
public required string PipelineKey { get; init; }
32+
33+
/// <summary>Version to run; <c>null</c> runs the latest published version.</summary>
34+
public int? Version { get; init; }
35+
36+
/// <summary>Pipeline inputs (no files).</summary>
37+
public JsonObject? Inputs { get; init; }
38+
39+
/// <summary>Deduplicates repeated commands for 24 hours (default: the AMQP <c>message_id</c>).</summary>
40+
public string? IdempotencyKey { get; init; }
41+
42+
/// <summary>Returned in every event of the run.</summary>
43+
public string? CorrelationId { get; init; }
44+
45+
/// <summary>Name of the calling system (the run is triggered by <c>queue:&lt;name&gt;</c>).</summary>
46+
public string? RequestedBy { get; init; }
47+
}
48+
49+
/// <summary>Control message <c>psr.cancel-run.v1</c> (fanout to every instance): stop the processes of a run.</summary>
50+
/// <param name="RunId">Run identifier.</param>
51+
/// <param name="StepRunId">Running step, when known.</param>
52+
/// <param name="RequestedBy">Who cancelled.</param>
53+
public sealed record CancelRunCommand(RunId RunId, StepRunId? StepRunId, string RequestedBy);
54+
55+
/// <summary>Versioned message types (AMQP <c>type</c> property).</summary>
56+
public static class PsrMessageTypes
57+
{
58+
/// <summary><see cref="ExecuteStepCommand"/>.</summary>
59+
public const string ExecuteStep = "psr.execute-step.v1";
60+
61+
/// <summary><see cref="StartPipelineRunCommand"/>.</summary>
62+
public const string StartPipelineRun = "psr.start-pipeline-run.v1";
63+
64+
/// <summary><see cref="CancelRunCommand"/>.</summary>
65+
public const string CancelRun = "psr.cancel-run.v1";
66+
67+
/// <summary><see cref="RunEvent"/>.</summary>
68+
public const string RunEvent = "psr.run-event.v1";
69+
}
70+
71+
/// <summary>JSON settings of the messages: camelCase properties and enum names as strings.</summary>
72+
public static class PsrMessageJson
73+
{
74+
/// <summary>Shared options (do not modify).</summary>
75+
public static JsonSerializerOptions Options { get; } = CreateOptions();
76+
77+
private static JsonSerializerOptions CreateOptions()
78+
{
79+
var options = new JsonSerializerOptions(JsonSerializerDefaults.Web)
80+
{
81+
Converters = { new JsonStringEnumConverter() },
82+
};
83+
options.MakeReadOnly(populateMissingResolver: true);
84+
return options;
85+
}
86+
}
87+
88+
/// <summary>Writes <see cref="RunId"/> as its GUID text.</summary>
89+
internal sealed class RunIdJsonConverter : JsonConverter<RunId>
90+
{
91+
public override RunId Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options) => new(reader.GetGuid());
92+
93+
public override void Write(Utf8JsonWriter writer, RunId value, JsonSerializerOptions options) => writer.WriteStringValue(value.Value);
94+
}
95+
96+
/// <summary>Writes <see cref="StepRunId"/> as its GUID text.</summary>
97+
internal sealed class StepRunIdJsonConverter : JsonConverter<StepRunId>
98+
{
99+
public override StepRunId Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options) => new(reader.GetGuid());
100+
101+
public override void Write(Utf8JsonWriter writer, StepRunId value, JsonSerializerOptions options) => writer.WriteStringValue(value.Value);
102+
}

0 commit comments

Comments
 (0)