Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel
Stabilize v1 API contracts with response envelopes
Yuechen Li9fcb245e1015
diff --git a/Aetheris.Server.Tests/KernelApiIntegrationTests.cs b/Aetheris.Server.Tests/KernelApiIntegrationTests.csindex 75ebb044..5b1b157d 100644--- a/Aetheris.Server.Tests/KernelApiIntegrationTests.cs+++ b/Aetheris.Server.Tests/KernelApiIntegrationTests.cs@@ -15,29 +15,35 @@ public sealed class KernelApiIntegrationTests : IClassFixture<WebApplicationFact}[Fact]- public async Task CreateDocument_CreateBox_TessellateAndPick_Succeeds()+ public async Task V1_CreateDocument_CreateBox_TessellateAndPick_ReturnsExpectedEnvelope(){- var document = await CreateDocumentAsync();+ var document = await CreateDocumentAsync("/api/v1/documents");var boxResponse = await _client.PostAsJsonAsync(- $"/api/documents/{document.DocumentId}/bodies/primitives/box",+ $"/api/v1/documents/{document.Data!.DocumentId}/bodies/primitives/box",new BoxCreateRequestDto(2, 2, 2));boxResponse.EnsureSuccessStatusCode();- var boxBody = await boxResponse.Content.ReadFromJsonAsync<BodyCreatedResponseDto>();+ var boxBody = await boxResponse.Content.ReadFromJsonAsync<ApiResponseDto<BodyCreatedResponseDto>>();Assert.NotNull(boxBody);+ Assert.True(boxBody!.Success);+ Assert.NotNull(boxBody.Data);+ Assert.Empty(boxBody.Diagnostics);var tessellationResponse = await _client.PostAsJsonAsync(- $"/api/documents/{document.DocumentId}/bodies/{boxBody!.BodyId}/tessellate",+ $"/api/v1/documents/{document.Data.DocumentId}/bodies/{boxBody.Data!.BodyId}/tessellate",new TessellateRequestDto(null));tessellationResponse.EnsureSuccessStatusCode();- var tessellation = await tessellationResponse.Content.ReadFromJsonAsync<TessellationResponseDto>();+ var tessellation = await tessellationResponse.Content.ReadFromJsonAsync<ApiResponseDto<TessellationResponseDto>>();Assert.NotNull(tessellation);- Assert.NotEmpty(tessellation!.FacePatches);+ Assert.True(tessellation!.Success);+ Assert.NotNull(tessellation.Data);+ Assert.NotEmpty(tessellation.Data!.FacePatches);+ Assert.Empty(tessellation.Diagnostics);var pickResponse = await _client.PostAsJsonAsync(- $"/api/documents/{document.DocumentId}/bodies/{boxBody.BodyId}/pick",+ $"/api/v1/documents/{document.Data.DocumentId}/bodies/{boxBody.Data.BodyId}/pick",new PickRequestDto(new Point3Dto(0, 0, 5),new Vector3Dto(0, 0, -1),@@ -45,20 +51,22 @@ public sealed class KernelApiIntegrationTests : IClassFixture<WebApplicationFactPickOptions: new PickOptionsDto(NearestOnly: true, IncludeBackfaces: null, EdgeTolerance: null, SortTieTolerance: null, MaxDistance: null)));pickResponse.EnsureSuccessStatusCode();- var pick = await pickResponse.Content.ReadFromJsonAsync<PickResponseDto>();+ var pick = await pickResponse.Content.ReadFromJsonAsync<ApiResponseDto<PickResponseDto>>();Assert.NotNull(pick);- Assert.Single(pick!.Hits);+ Assert.True(pick!.Success);+ Assert.NotNull(pick.Data);+ Assert.Single(pick.Data!.Hits);+ Assert.NotNull(pick.Data.Hits[0].Point);}[Fact]- public async Task UnsupportedBoolean_ReturnsStructuredError()+ public async Task UnsupportedBoolean_OnV1_ReturnsUnprocessableEntityWithDiagnosticEnvelope(){- var document = await CreateDocumentAsync();- var left = await CreateBoxAsync(document.DocumentId, 1, 1, 1);- var right = await CreateBoxAsync(document.DocumentId, 1, 1, 1);+ var document = await CreateDocumentAsync("/api/v1/documents");+ var left = await CreateBoxAsync("/api/v1/documents", document.Data!.DocumentId, 1, 1, 1);var extrudeResponse = await _client.PostAsJsonAsync(- $"/api/documents/{document.DocumentId}/operations/extrude",+ $"/api/v1/documents/{document.Data.DocumentId}/operations/extrude",new ExtrudeRequestDto([new ProfilePoint2Dto(-0.5, -0.5), new ProfilePoint2Dto(0.5, -0.5), new ProfilePoint2Dto(0.5, 0.5), new ProfilePoint2Dto(-0.5, 0.5)],new Point3Dto(4, 0, 0),@@ -67,48 +75,79 @@ public sealed class KernelApiIntegrationTests : IClassFixture<WebApplicationFact1));extrudeResponse.EnsureSuccessStatusCode();- var moved = await extrudeResponse.Content.ReadFromJsonAsync<BodyCreatedResponseDto>();+ var moved = await extrudeResponse.Content.ReadFromJsonAsync<ApiResponseDto<BodyCreatedResponseDto>>();Assert.NotNull(moved);+ Assert.NotNull(moved!.Data);var booleanResponse = await _client.PostAsJsonAsync(- $"/api/documents/{document.DocumentId}/operations/boolean",- new BooleanRequestDto(left.BodyId, moved!.BodyId, "union"));+ $"/api/v1/documents/{document.Data.DocumentId}/operations/boolean",+ new BooleanRequestDto(left.Data!.BodyId, moved.Data!.BodyId, "union"));Assert.Equal(HttpStatusCode.UnprocessableEntity, booleanResponse.StatusCode);- var error = await booleanResponse.Content.ReadFromJsonAsync<ErrorResponseDto>();- Assert.NotNull(error);- Assert.Contains(error!.Diagnostics, d => d.Code == "NotImplemented");+ var envelope = await booleanResponse.Content.ReadFromJsonAsync<ApiResponseDto<object>>();+ Assert.NotNull(envelope);+ Assert.False(envelope!.Success);+ Assert.Null(envelope.Data);+ Assert.Contains(envelope.Diagnostics, d => d.Code == "NotImplemented");+ Assert.All(envelope.Diagnostics, d =>+ {+ Assert.False(string.IsNullOrWhiteSpace(d.Code));+ Assert.False(string.IsNullOrWhiteSpace(d.Severity));+ Assert.False(string.IsNullOrWhiteSpace(d.Message));+ });}[Fact]- public async Task MissingDocumentAndBody_ReturnNotFound()+ public async Task MissingDocumentAndBody_OnV1_ReturnNotFoundWithDiagnosticEnvelope(){var missingDocId = Guid.NewGuid();var missingBodyId = Guid.NewGuid();- var docResponse = await _client.GetAsync($"/api/documents/{missingDocId}");+ var docResponse = await _client.GetAsync($"/api/v1/documents/{missingDocId}");Assert.Equal(HttpStatusCode.NotFound, docResponse.StatusCode);+ var missingDoc = await docResponse.Content.ReadFromJsonAsync<ApiResponseDto<object>>();+ Assert.NotNull(missingDoc);+ Assert.False(missingDoc!.Success);+ Assert.NotEmpty(missingDoc.Diagnostics);- var created = await CreateDocumentAsync();+ var created = await CreateDocumentAsync("/api/v1/documents");var bodyResponse = await _client.PostAsJsonAsync(- $"/api/documents/{created.DocumentId}/bodies/{missingBodyId}/tessellate",+ $"/api/v1/documents/{created.Data!.DocumentId}/bodies/{missingBodyId}/tessellate",new TessellateRequestDto(null));Assert.Equal(HttpStatusCode.NotFound, bodyResponse.StatusCode);++ var missingBody = await bodyResponse.Content.ReadFromJsonAsync<ApiResponseDto<object>>();+ Assert.NotNull(missingBody);+ Assert.False(missingBody!.Success);+ Assert.NotEmpty(missingBody.Diagnostics);+ }++ [Fact]+ public async Task UnversionedRoute_CompatibilityAlias_StillWorks()+ {+ var response = await _client.PostAsJsonAsync("/api/documents", new DocumentCreateRequestDto("compat"));+ response.EnsureSuccessStatusCode();++ var envelope = await response.Content.ReadFromJsonAsync<ApiResponseDto<DocumentCreateResponseDto>>();+ Assert.NotNull(envelope);+ Assert.True(envelope!.Success);+ Assert.NotNull(envelope.Data);+ Assert.Equal("compat", envelope.Data!.Name);}- private async Task<DocumentCreateResponseDto> CreateDocumentAsync()+ private async Task<ApiResponseDto<DocumentCreateResponseDto>> CreateDocumentAsync(string routePrefix){- var response = await _client.PostAsJsonAsync("/api/documents", new DocumentCreateRequestDto("test"));+ var response = await _client.PostAsJsonAsync(routePrefix, new DocumentCreateRequestDto("test"));response.EnsureSuccessStatusCode();- var payload = await response.Content.ReadFromJsonAsync<DocumentCreateResponseDto>();+ var payload = await response.Content.ReadFromJsonAsync<ApiResponseDto<DocumentCreateResponseDto>>();return payload!;}- private async Task<BodyCreatedResponseDto> CreateBoxAsync(Guid documentId, double w, double h, double d)+ private async Task<ApiResponseDto<BodyCreatedResponseDto>> CreateBoxAsync(string routePrefix, Guid documentId, double w, double h, double d){- var response = await _client.PostAsJsonAsync($"/api/documents/{documentId}/bodies/primitives/box", new BoxCreateRequestDto(w, h, d));+ var response = await _client.PostAsJsonAsync($"{routePrefix}/{documentId}/bodies/primitives/box", new BoxCreateRequestDto(w, h, d));response.EnsureSuccessStatusCode();- var body = await response.Content.ReadFromJsonAsync<BodyCreatedResponseDto>();+ var body = await response.Content.ReadFromJsonAsync<ApiResponseDto<BodyCreatedResponseDto>>();return body!;}}diff --git a/Aetheris.Server/Api/ApiMappings.cs b/Aetheris.Server/Api/ApiMappings.csindex 924befdb..b5194803 100644--- a/Aetheris.Server/Api/ApiMappings.cs+++ b/Aetheris.Server/Api/ApiMappings.cs@@ -10,11 +10,14 @@ namespace Aetheris.Server.Api;public static class ApiMappings{+ public static IResult Ok<T>(T data)+ => Results.Ok(new ApiResponseDto<T>(true, data, []));+public static IResult KernelFailure(IReadOnlyList<KernelDiagnostic> diagnostics){var mapped = diagnostics.Select(ToDiagnostic).ToArray();var statusCode = ResolveStatusCode(diagnostics);- return Results.Json(new ErrorResponseDto(mapped), statusCode: statusCode);+ return Results.Json(new ApiResponseDto<object>(false, null, mapped), statusCode: statusCode);}public static DiagnosticDto ToDiagnostic(KernelDiagnostic diagnostic)@@ -41,7 +44,7 @@ public static class ApiMappingspublic static IResult NotFound(string message, string source){var diagnostic = new KernelDiagnostic(KernelDiagnosticCode.InvalidArgument, KernelDiagnosticSeverity.Error, message, source);- return Results.NotFound(new ErrorResponseDto([ToDiagnostic(diagnostic)]));+ return Results.NotFound(new ApiResponseDto<object>(false, null, [ToDiagnostic(diagnostic)]));}public static Point3Dto ToPointDto(Point3D point) => new(point.X, point.Y, point.Z);@@ -72,8 +75,8 @@ public static class ApiMappingsh.SourcePatchIndex,h.SourcePrimitiveIndex)).ToArray());- public static BadRequest<ErrorResponseDto> BadRequestFromMessage(string message, string source)- => TypedResults.BadRequest(new ErrorResponseDto([new DiagnosticDto(+ public static BadRequest<ApiResponseDto<object>> BadRequestFromMessage(string message, string source)+ => TypedResults.BadRequest(new ApiResponseDto<object>(false, null, [new DiagnosticDto(KernelDiagnosticCode.InvalidArgument.ToString(),KernelDiagnosticSeverity.Error.ToString(),message,diff --git a/Aetheris.Server/Api/KernelEndpoints.cs b/Aetheris.Server/Api/KernelEndpoints.csindex d1f7cf14..a6c7d645 100644--- a/Aetheris.Server/Api/KernelEndpoints.cs+++ b/Aetheris.Server/Api/KernelEndpoints.cs@@ -13,12 +13,16 @@ public static class KernelEndpoints{public static void MapKernelApi(this WebApplication app){- var documents = app.MapGroup("/api/documents");+ MapDocumentRoutes(app.MapGroup("/api/v1/documents"));+ MapDocumentRoutes(app.MapGroup("/api/documents"));+ }+ private static void MapDocumentRoutes(RouteGroupBuilder documents)+ {documents.MapPost("", (DocumentCreateRequestDto? request, KernelDocumentStore store) =>{var created = store.Create(request?.Name);- return Results.Ok(new DocumentCreateResponseDto(created.Id, created.Name, Volatile: true));+ return ApiMappings.Ok(new DocumentCreateResponseDto(created.Id, created.Name, Volatile: true));});documents.MapGet("/{documentId:guid}", (Guid documentId, KernelDocumentStore store) =>@@ -29,7 +33,7 @@ public static class KernelEndpoints}var bodyIds = document.SnapshotBodies().Keys.OrderBy(id => id).ToArray();- return Results.Ok(new DocumentSummaryResponseDto(document.Id, document.Name, bodyIds.Length, bodyIds));+ return ApiMappings.Ok(new DocumentSummaryResponseDto(document.Id, document.Name, bodyIds.Length, bodyIds));});documents.MapPost("/{documentId:guid}/bodies/primitives/box", (Guid documentId, BoxCreateRequestDto request, KernelDocumentStore store) =>@@ -41,7 +45,7 @@ public static class KernelEndpointsreturn ApiMappings.KernelFailure(kernel.Diagnostics);}- return Results.Ok(CreateBodyResponse(document, kernel.Value));+ return ApiMappings.Ok(CreateBodyResponse(document, kernel.Value));}));documents.MapPost("/{documentId:guid}/bodies/primitives/cylinder", (Guid documentId, CylinderCreateRequestDto request, KernelDocumentStore store) =>@@ -53,7 +57,7 @@ public static class KernelEndpointsreturn ApiMappings.KernelFailure(kernel.Diagnostics);}- return Results.Ok(CreateBodyResponse(document, kernel.Value));+ return ApiMappings.Ok(CreateBodyResponse(document, kernel.Value));}));documents.MapPost("/{documentId:guid}/bodies/primitives/sphere", (Guid documentId, SphereCreateRequestDto request, KernelDocumentStore store) =>@@ -65,7 +69,7 @@ public static class KernelEndpointsreturn ApiMappings.KernelFailure(kernel.Diagnostics);}- return Results.Ok(CreateBodyResponse(document, kernel.Value));+ return ApiMappings.Ok(CreateBodyResponse(document, kernel.Value));}));documents.MapPost("/{documentId:guid}/operations/extrude", (Guid documentId, ExtrudeRequestDto request, KernelDocumentStore store) =>@@ -88,7 +92,7 @@ public static class KernelEndpointsreturn ApiMappings.KernelFailure(kernel.Diagnostics);}- return Results.Ok(CreateBodyResponse(document, kernel.Value));+ return ApiMappings.Ok(CreateBodyResponse(document, kernel.Value));}));documents.MapPost("/{documentId:guid}/operations/revolve", (Guid documentId, RevolveRequestDto request, KernelDocumentStore store) =>@@ -129,7 +133,7 @@ public static class KernelEndpointsreturn ApiMappings.KernelFailure(kernel.Diagnostics);}- return Results.Ok(CreateBodyResponse(document, kernel.Value));+ return ApiMappings.Ok(CreateBodyResponse(document, kernel.Value));}));documents.MapPost("/{documentId:guid}/operations/boolean", (Guid documentId, BooleanRequestDto request, KernelDocumentStore store) =>@@ -163,7 +167,7 @@ public static class KernelEndpointsreturn ApiMappings.KernelFailure(kernel.Diagnostics);}- return Results.Ok(CreateBodyResponse(document, kernel.Value));+ return ApiMappings.Ok(CreateBodyResponse(document, kernel.Value));}));documents.MapPost("/{documentId:guid}/bodies/{bodyId:guid}/tessellate", (Guid documentId, Guid bodyId, TessellateRequestDto? request, KernelDocumentStore store) =>@@ -176,7 +180,7 @@ public static class KernelEndpointsreturn ApiMappings.KernelFailure(kernel.Diagnostics);}- return Results.Ok(ApiMappings.ToTessellationResponse(kernel.Value));+ return ApiMappings.Ok(ApiMappings.ToTessellationResponse(kernel.Value));}));documents.MapPost("/{documentId:guid}/bodies/{bodyId:guid}/pick", (Guid documentId, Guid bodyId, PickRequestDto request, KernelDocumentStore store) =>@@ -199,7 +203,7 @@ public static class KernelEndpointsreturn ApiMappings.KernelFailure(kernel.Diagnostics);}- return Results.Ok(ApiMappings.ToPickResponse(kernel.Value));+ return ApiMappings.Ok(ApiMappings.ToPickResponse(kernel.Value));}));}diff --git a/Aetheris.Server/Contracts/ApiContracts.cs b/Aetheris.Server/Contracts/ApiContracts.csindex 28804d55..7539bed6 100644--- a/Aetheris.Server/Contracts/ApiContracts.cs+++ b/Aetheris.Server/Contracts/ApiContracts.cs@@ -2,7 +2,7 @@ namespace Aetheris.Server.Contracts;public sealed record DiagnosticDto(string Code, string Severity, string Message, string? Source);-public sealed record ErrorResponseDto(IReadOnlyList<DiagnosticDto> Diagnostics);+public sealed record ApiResponseDto<T>(bool Success, T? Data, IReadOnlyList<DiagnosticDto> Diagnostics);public sealed record DocumentCreateRequestDto(string? Name);diff --git a/docs/milestones.md b/docs/milestones.mdindex 6db14bc2..f9a118ed 100644--- a/docs/milestones.md+++ b/docs/milestones.md@@ -144,3 +144,13 @@- [x] Add deterministic kernel diagnostic-to-HTTP mapping with structured error payloads for invalid, unsupported, validation, and missing-resource paths.- [x] Add focused integration tests for core happy paths and deterministic error behavior.- [x] Defer frontend integration details and API versioning to M17+.++## M17 — Web Protocol Stabilization + Versioned Contracts v1++- [x] Stabilize the canonical backend API surface under `/api/v1/documents/...` for frontend integration.+- [x] Adopt a consistent HTTP response envelope for all routes: `success`, `data`, `diagnostics`.+- [x] Normalize diagnostics payload shape (`code`, `severity`, `message`, `source`) for all errors, including not-found responses.+- [x] Preserve M16 capability coverage (document summary/create, primitives, extrude/revolve/boolean, tessellate, pick) while standardizing protocol shape only.+- [x] Keep temporary unversioned compatibility aliases under `/api/documents/...` during migration; v1 routes are canonical.+- [x] Add integration tests that lock versioned route behavior, envelope shape, diagnostics determinism, and compatibility alias behavior.+- [x] M18 frontend integration targets stable v1 contracts and envelope semantics.