Skip to content

Commit 0ac8d74

Browse files
net0wellclaude
andcommitted
feat(core,ef): contratos JSON da API, testes de rascunho pela fila e chaves do painel (spec 007)
- Abstractions: IDs fortes, enums, FieldDefinition e BindingSource serializados no formato das specs (sem alterar opções JSON do host); FieldDefinitionJson e FieldCompatibility públicos. - ICatalogAdmin: EnqueueStageDraftTestAsync/EnqueuePipelineDraftTestAsync (D-114); filtro por status nas listas; auditoria filtrável por ação e chave; ações LoginSucceeded/LoggedOut/UserLocked. - Agendamentos: códigos INVALID_CRON e INVALID_TIME_ZONE (spec 007) e SchedulePreview público. - Migration DashboardKeys: tabela psr.dashboard_keys para as chaves do cookie do login fixo (D-132). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
1 parent 3b343d3 commit 0ac8d74

28 files changed

Lines changed: 1889 additions & 53 deletions

File tree

src/PythonScriptRunner.Core/Pipelines/TypeCompatibility.cs renamed to src/PythonScriptRunner.Abstractions/Fields/FieldCompatibility.cs

Lines changed: 11 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,17 @@
1-
namespace PythonScriptRunner.Core.Pipelines;
1+
namespace PythonScriptRunner;
22

33
/// <summary>Which source types can feed which target types in a binding (spec 003, safe widenings only).</summary>
4-
internal static class TypeCompatibility
4+
public static class FieldCompatibility
55
{
6-
public static bool IsAssignable(FieldDefinition source, FieldDefinition target) =>
7-
IsAssignable(source.Type, target.Type, source, target);
6+
/// <summary>Whether a value of <paramref name="source"/> can be bound to <paramref name="target"/>.</summary>
7+
/// <param name="source">Field that produces the value.</param>
8+
/// <param name="target">Field that receives it.</param>
9+
public static bool IsAssignable(FieldDefinition source, FieldDefinition target)
10+
{
11+
ArgumentNullException.ThrowIfNull(source);
12+
ArgumentNullException.ThrowIfNull(target);
13+
return IsAssignable(source.Type, target.Type, source, target);
14+
}
815

916
private static bool IsAssignable(FieldType source, FieldType target, FieldDefinition sourceField, FieldDefinition targetField)
1017
{

‎src/PythonScriptRunner.Abstractions/Fields/FieldDefinition.cs‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,12 @@
11
using System.Text.Json.Nodes;
2+
using System.Text.Json.Serialization;
23

34
namespace PythonScriptRunner;
45

56
/// <summary>Declaration of one input or output of a stage.</summary>
67
/// <param name="Name">Field name (<c>^[a-z_][a-z0-9_]{0,63}$</c>).</param>
78
/// <param name="Type">Field type.</param>
9+
[JsonConverter(typeof(FieldDefinitionJsonConverter))]
810
public sealed record FieldDefinition(string Name, FieldType Type)
911
{
1012
/// <summary>Whether a value must be provided (inputs) or produced (outputs). Default: <c>true</c>.</summary>

src/PythonScriptRunner.Core/Catalog/FieldDefinitionJson.cs renamed to src/PythonScriptRunner.Abstractions/Fields/FieldDefinitionJson.cs

Lines changed: 11 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,15 @@
11
using System.Text.Json.Nodes;
22

3-
namespace PythonScriptRunner.Core.Catalog;
3+
namespace PythonScriptRunner;
44

5-
/// <summary>Maps <see cref="FieldDefinition"/> to and from the manifest/protocol JSON (camelCase).</summary>
6-
internal static class FieldDefinitionJson
5+
/// <summary>Maps <see cref="FieldDefinition"/> to and from the manifest/protocol JSON (camelCase; data mapping §2.1).</summary>
6+
public static class FieldDefinitionJson
77
{
8+
/// <summary>Writes a field declaration.</summary>
9+
/// <param name="field">The field.</param>
810
public static JsonObject ToJson(FieldDefinition field)
911
{
12+
ArgumentNullException.ThrowIfNull(field);
1013
var type = field.Type;
1114
var json = new JsonObject
1215
{
@@ -47,11 +50,16 @@ public static JsonObject ToJson(FieldDefinition field)
4750
return json;
4851
}
4952

53+
/// <summary>Writes field declarations.</summary>
54+
/// <param name="fields">The fields.</param>
5055
public static JsonArray ToJson(IEnumerable<FieldDefinition> fields) => new([.. fields.Select(f => (JsonNode)ToJson(f))]);
5156

57+
/// <summary>Reads a field declaration.</summary>
58+
/// <param name="json">The JSON object.</param>
5259
/// <exception cref="ArgumentException">The JSON is not a valid field declaration.</exception>
5360
public static FieldDefinition FromJson(JsonObject json)
5461
{
62+
ArgumentNullException.ThrowIfNull(json);
5563
var name = json["name"]?.GetValue<string>() ?? throw new ArgumentException("Field without 'name'.");
5664
var type = FieldType.Parse(
5765
json["type"]?.GetValue<string>() ?? throw new ArgumentException($"Field '{name}' without 'type'."),

‎src/PythonScriptRunner.Abstractions/Ids.cs‎

Lines changed: 126 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -4,8 +4,8 @@ namespace PythonScriptRunner;
44

55
/// <summary>Identifier of a run (time-ordered UUID v7). Its timestamp is the creation time of the run.</summary>
66
/// <param name="Value">The underlying GUID.</param>
7-
[JsonConverter(typeof(RunIdJsonConverter))]
8-
public readonly record struct RunId(Guid Value)
7+
[JsonConverter(typeof(GuidIdJsonConverter<RunId>))]
8+
public readonly record struct RunId(Guid Value) : IGuidId<RunId>
99
{
1010
/// <summary>Creates a new time-ordered identifier.</summary>
1111
public static RunId New() => new(Guid.CreateVersion7());
@@ -21,36 +21,74 @@ public readonly record struct RunId(Guid Value)
2121
/// <summary>Creation time embedded in the identifier (UTC, millisecond precision).</summary>
2222
public DateTimeOffset CreatedAt => UuidV7.Timestamp(Value);
2323

24+
/// <summary>Parses the GUID text (route and query binding).</summary>
25+
/// <param name="text">GUID text.</param>
26+
/// <param name="id">The identifier.</param>
27+
public static bool TryParse(string? text, out RunId id)
28+
{
29+
var parsed = Guid.TryParse(text, out var value);
30+
id = new RunId(value);
31+
return parsed;
32+
}
33+
34+
static RunId IGuidId<RunId>.From(Guid value) => new(value);
35+
2436
/// <inheritdoc />
2537
public override string ToString() => Value.ToString();
2638
}
2739

2840
/// <summary>Identifier of one attempt of a step (time-ordered UUID v7).</summary>
2941
/// <param name="Value">The underlying GUID.</param>
30-
public readonly record struct AttemptId(Guid Value)
42+
[JsonConverter(typeof(GuidIdJsonConverter<AttemptId>))]
43+
public readonly record struct AttemptId(Guid Value) : IGuidId<AttemptId>
3144
{
3245
/// <summary>Creates a new time-ordered identifier.</summary>
3346
public static AttemptId New() => new(Guid.CreateVersion7());
3447

48+
/// <summary>Parses the GUID text (route and query binding).</summary>
49+
/// <param name="text">GUID text.</param>
50+
/// <param name="id">The identifier.</param>
51+
public static bool TryParse(string? text, out AttemptId id)
52+
{
53+
var parsed = Guid.TryParse(text, out var value);
54+
id = new AttemptId(value);
55+
return parsed;
56+
}
57+
58+
static AttemptId IGuidId<AttemptId>.From(Guid value) => new(value);
59+
3560
/// <inheritdoc />
3661
public override string ToString() => Value.ToString();
3762
}
3863

3964
/// <summary>Identifier of a step within a run (time-ordered UUID v7).</summary>
4065
/// <param name="Value">The underlying GUID.</param>
41-
[JsonConverter(typeof(StepRunIdJsonConverter))]
42-
public readonly record struct StepRunId(Guid Value)
66+
[JsonConverter(typeof(GuidIdJsonConverter<StepRunId>))]
67+
public readonly record struct StepRunId(Guid Value) : IGuidId<StepRunId>
4368
{
4469
/// <summary>Creates a new time-ordered identifier.</summary>
4570
public static StepRunId New() => new(Guid.CreateVersion7());
4671

72+
/// <summary>Parses the GUID text (route and query binding).</summary>
73+
/// <param name="text">GUID text.</param>
74+
/// <param name="id">The identifier.</param>
75+
public static bool TryParse(string? text, out StepRunId id)
76+
{
77+
var parsed = Guid.TryParse(text, out var value);
78+
id = new StepRunId(value);
79+
return parsed;
80+
}
81+
82+
static StepRunId IGuidId<StepRunId>.From(Guid value) => new(value);
83+
4784
/// <inheritdoc />
4885
public override string ToString() => Value.ToString();
4986
}
5087

5188
/// <summary>Identifier of a stored file (time-ordered UUID v7).</summary>
5289
/// <param name="Value">The underlying GUID.</param>
53-
public readonly record struct ArtifactId(Guid Value)
90+
[JsonConverter(typeof(GuidIdJsonConverter<ArtifactId>))]
91+
public readonly record struct ArtifactId(Guid Value) : IGuidId<ArtifactId>
5492
{
5593
/// <summary>Creates a new time-ordered identifier.</summary>
5694
public static ArtifactId New() => new(Guid.CreateVersion7());
@@ -59,61 +97,138 @@ public readonly record struct ArtifactId(Guid Value)
5997
/// <param name="text">GUID text.</param>
6098
public static ArtifactId Parse(string text) => new(Guid.Parse(text));
6199

100+
/// <summary>Parses the GUID text (route and query binding).</summary>
101+
/// <param name="text">GUID text.</param>
102+
/// <param name="id">The identifier.</param>
103+
public static bool TryParse(string? text, out ArtifactId id)
104+
{
105+
var parsed = Guid.TryParse(text, out var value);
106+
id = new ArtifactId(value);
107+
return parsed;
108+
}
109+
110+
static ArtifactId IGuidId<ArtifactId>.From(Guid value) => new(value);
111+
62112
/// <inheritdoc />
63113
public override string ToString() => Value.ToString();
64114
}
65115

66116
/// <summary>Identifier of a stage (UUID v7).</summary>
67117
/// <param name="Value">The underlying GUID.</param>
68-
public readonly record struct StageId(Guid Value)
118+
[JsonConverter(typeof(GuidIdJsonConverter<StageId>))]
119+
public readonly record struct StageId(Guid Value) : IGuidId<StageId>
69120
{
70121
/// <summary>Creates a new time-ordered identifier.</summary>
71122
public static StageId New() => new(Guid.CreateVersion7());
72123

124+
/// <summary>Parses the GUID text (route and query binding).</summary>
125+
/// <param name="text">GUID text.</param>
126+
/// <param name="id">The identifier.</param>
127+
public static bool TryParse(string? text, out StageId id)
128+
{
129+
var parsed = Guid.TryParse(text, out var value);
130+
id = new StageId(value);
131+
return parsed;
132+
}
133+
134+
static StageId IGuidId<StageId>.From(Guid value) => new(value);
135+
73136
/// <inheritdoc />
74137
public override string ToString() => Value.ToString();
75138
}
76139

77140
/// <summary>Identifier of a stage version (UUID v7).</summary>
78141
/// <param name="Value">The underlying GUID.</param>
79-
public readonly record struct StageVersionId(Guid Value)
142+
[JsonConverter(typeof(GuidIdJsonConverter<StageVersionId>))]
143+
public readonly record struct StageVersionId(Guid Value) : IGuidId<StageVersionId>
80144
{
81145
/// <summary>Creates a new time-ordered identifier.</summary>
82146
public static StageVersionId New() => new(Guid.CreateVersion7());
83147

148+
/// <summary>Parses the GUID text (route and query binding).</summary>
149+
/// <param name="text">GUID text.</param>
150+
/// <param name="id">The identifier.</param>
151+
public static bool TryParse(string? text, out StageVersionId id)
152+
{
153+
var parsed = Guid.TryParse(text, out var value);
154+
id = new StageVersionId(value);
155+
return parsed;
156+
}
157+
158+
static StageVersionId IGuidId<StageVersionId>.From(Guid value) => new(value);
159+
84160
/// <inheritdoc />
85161
public override string ToString() => Value.ToString();
86162
}
87163

88164
/// <summary>Identifier of a pipeline (UUID v7).</summary>
89165
/// <param name="Value">The underlying GUID.</param>
90-
public readonly record struct PipelineId(Guid Value)
166+
[JsonConverter(typeof(GuidIdJsonConverter<PipelineId>))]
167+
public readonly record struct PipelineId(Guid Value) : IGuidId<PipelineId>
91168
{
92169
/// <summary>Creates a new time-ordered identifier.</summary>
93170
public static PipelineId New() => new(Guid.CreateVersion7());
94171

172+
/// <summary>Parses the GUID text (route and query binding).</summary>
173+
/// <param name="text">GUID text.</param>
174+
/// <param name="id">The identifier.</param>
175+
public static bool TryParse(string? text, out PipelineId id)
176+
{
177+
var parsed = Guid.TryParse(text, out var value);
178+
id = new PipelineId(value);
179+
return parsed;
180+
}
181+
182+
static PipelineId IGuidId<PipelineId>.From(Guid value) => new(value);
183+
95184
/// <inheritdoc />
96185
public override string ToString() => Value.ToString();
97186
}
98187

99188
/// <summary>Identifier of a pipeline version (UUID v7).</summary>
100189
/// <param name="Value">The underlying GUID.</param>
101-
public readonly record struct PipelineVersionId(Guid Value)
190+
[JsonConverter(typeof(GuidIdJsonConverter<PipelineVersionId>))]
191+
public readonly record struct PipelineVersionId(Guid Value) : IGuidId<PipelineVersionId>
102192
{
103193
/// <summary>Creates a new time-ordered identifier.</summary>
104194
public static PipelineVersionId New() => new(Guid.CreateVersion7());
105195

196+
/// <summary>Parses the GUID text (route and query binding).</summary>
197+
/// <param name="text">GUID text.</param>
198+
/// <param name="id">The identifier.</param>
199+
public static bool TryParse(string? text, out PipelineVersionId id)
200+
{
201+
var parsed = Guid.TryParse(text, out var value);
202+
id = new PipelineVersionId(value);
203+
return parsed;
204+
}
205+
206+
static PipelineVersionId IGuidId<PipelineVersionId>.From(Guid value) => new(value);
207+
106208
/// <inheritdoc />
107209
public override string ToString() => Value.ToString();
108210
}
109211

110212
/// <summary>Identifier of a schedule (UUID v7).</summary>
111213
/// <param name="Value">The underlying GUID.</param>
112-
public readonly record struct ScheduleId(Guid Value)
214+
[JsonConverter(typeof(GuidIdJsonConverter<ScheduleId>))]
215+
public readonly record struct ScheduleId(Guid Value) : IGuidId<ScheduleId>
113216
{
114217
/// <summary>Creates a new time-ordered identifier.</summary>
115218
public static ScheduleId New() => new(Guid.CreateVersion7());
116219

220+
/// <summary>Parses the GUID text (route and query binding).</summary>
221+
/// <param name="text">GUID text.</param>
222+
/// <param name="id">The identifier.</param>
223+
public static bool TryParse(string? text, out ScheduleId id)
224+
{
225+
var parsed = Guid.TryParse(text, out var value);
226+
id = new ScheduleId(value);
227+
return parsed;
228+
}
229+
230+
static ScheduleId IGuidId<ScheduleId>.From(Guid value) => new(value);
231+
117232
/// <inheritdoc />
118233
public override string ToString() => Value.ToString();
119234
}

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

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -57,6 +57,12 @@ public sealed record AuditQuery
5757
/// <summary>Only events of this entity type.</summary>
5858
public string? EntityType { get; init; }
5959

60+
/// <summary>Only events of this action (see <see cref="AuditActions"/>).</summary>
61+
public string? Action { get; init; }
62+
63+
/// <summary>Only events of this entity key (e.g. <c>html-para-pdf@3</c>).</summary>
64+
public string? EntityKey { get; init; }
65+
6066
/// <summary>Cursor returned by the previous page.</summary>
6167
public string? Cursor { get; init; }
6268

@@ -96,5 +102,8 @@ public static class AuditActions
96102
public const string RunCancelled = nameof(RunCancelled);
97103
public const string RunReprocessed = nameof(RunReprocessed);
98104
public const string CatalogImported = nameof(CatalogImported);
105+
public const string LoginSucceeded = nameof(LoginSucceeded);
106+
public const string LoggedOut = nameof(LoggedOut);
107+
public const string UserLocked = nameof(UserLocked);
99108
#pragma warning restore CS1591
100109
}

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

Lines changed: 22 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -216,6 +216,26 @@ Task<PipelineDetail> UpdatePipelineSettingsAsync(
216216
Task<PipelineDetail> UpdatePipelineRetentionAsync(
217217
string key, PipelineRetention retention, uint expectedRowVersion, Actor actor, CancellationToken cancellationToken = default);
218218

219+
/// <summary>
220+
/// Validates the current draft of a stage and queues it as a test (<see cref="RunKind.StageTest"/>) for the workers (requires the
221+
/// RabbitMQ package; D-114). <c>STAGE_INVALID</c> when invalid; <see cref="InputValidationException"/> for invalid inputs.
222+
/// </summary>
223+
/// <param name="key">Stage key.</param>
224+
/// <param name="inputs">Stage inputs.</param>
225+
/// <param name="actor">Author.</param>
226+
/// <param name="cancellationToken">Cancellation token.</param>
227+
Task<RunHandle> EnqueueStageDraftTestAsync(string key, object? inputs, Actor actor, CancellationToken cancellationToken = default);
228+
229+
/// <summary>
230+
/// Validates the current draft of a pipeline and queues it as a test (<see cref="RunKind.PipelineTest"/>; D-97, D-114).
231+
/// <c>PIPELINE_INVALID</c> when invalid; <see cref="InputValidationException"/> for invalid inputs.
232+
/// </summary>
233+
/// <param name="key">Pipeline key.</param>
234+
/// <param name="inputs">Pipeline inputs.</param>
235+
/// <param name="actor">Author.</param>
236+
/// <param name="cancellationToken">Cancellation token.</param>
237+
Task<RunHandle> EnqueuePipelineDraftTestAsync(string key, object? inputs, Actor actor, CancellationToken cancellationToken = default);
238+
219239
/// <summary>Validates and runs the current draft as a test (<see cref="RunKind.PipelineTest"/>); <c>PIPELINE_INVALID</c> when invalid.</summary>
220240
/// <param name="key">Pipeline key.</param>
221241
/// <param name="inputs">Pipeline inputs.</param>
@@ -290,7 +310,8 @@ Task<ScheduleDetail> SetScheduleEnabledAsync(
290310
/// <param name="Search">Text contained in the key or the name.</param>
291311
/// <param name="PageNumber">1-based page number.</param>
292312
/// <param name="PageSize">Items per page (1-100).</param>
293-
public sealed record CatalogQuery(string? Search = null, int PageNumber = 1, int PageSize = 25);
313+
/// <param name="Status">Only items that have a version with this status.</param>
314+
public sealed record CatalogQuery(string? Search = null, int PageNumber = 1, int PageSize = 25, VersionStatus? Status = null);
294315

295316
/// <summary>A new stage or pipeline.</summary>
296317
/// <param name="Key">Slug (immutable).</param>

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

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -60,9 +60,15 @@ public static class PsrErrorCodes
6060
/// <summary>The schedule does not exist.</summary>
6161
public const string ScheduleNotFound = "SCHEDULE_NOT_FOUND";
6262

63-
/// <summary>The schedule has an invalid cron expression, time zone or version.</summary>
63+
/// <summary>The schedule targets a version that cannot run (missing, draft or archived).</summary>
6464
public const string ScheduleInvalid = "SCHEDULE_INVALID";
6565

66+
/// <summary>The cron expression is invalid.</summary>
67+
public const string InvalidCron = "INVALID_CRON";
68+
69+
/// <summary>The IANA time zone is unknown.</summary>
70+
public const string InvalidTimeZone = "INVALID_TIME_ZONE";
71+
6672
/// <summary>Pipelines with file inputs cannot be scheduled nor started by the public queue command (D-89).</summary>
6773
public const string ScheduleFileInput = "SCHEDULE_FILE_INPUT";
6874

0 commit comments

Comments
 (0)