Just a short one for today, mostly to answer a question that came in earlier this week.
When using Wolverine.Http to expose HTTP endpoint services that end up capturing Marten events, you might have an endpoint coded like this one from the Wolverine tests that takes in a command message and tries to start a new Marten event stream for the Order aggregate:
[Transactional] // This can be omitted if you use auto-transactions
[WolverinePost("/orders/create4")]
public static (OrderStatus, IStartStream) StartOrder4(StartOrderWithId command)
{
var items = command.Items.Select(x => new Item { Name = x }).ToArray();
// This is unique to Wolverine (we think)
var startStream = MartenOps
.StartStream<Order>(command.Id,new OrderCreated(items));
return (
new OrderStatus(startStream.StreamId, false),
startStream
);
}
Where the command looks like this:
public record StartOrderWithId(Guid Id, string[] Items);
In the HTTP endpoint above, we’re:
- Creating a new event stream for
Orderthat uses the stream/order id sent in the command - Returning a response body of type
OrderStatusto the caller - Using Wolverine’s Marten integration to also return an
IStartStreamobject that integrated middleware will apply to Marten’sIDocumentSession(more on this in my next post because we think this is a big deal by itself).
Great, easy enough right? Just to add some complexity, if the caller happens to send up the same, new order id additional times then Marten will throw an exception called `ExistingStreamIdCollisionException` just noting that no, you can’t create a new stream with that id because one already exists.
Marten’s behavior helps protect the data from duplication, but what about trying to make the HTTP response a little nicer by catching that exception automatically, and returning a ProblemDetails body with a 400 Bad Request status code to denote exactly what happened?
While you actually could do that globally with a bit of ASP.Net Core middleware, that applies everywhere at runtime and not just on the specific routes that could throw that exception. I’m not sure how big a deal this is to many of you, but using ASP.Net Core middleware would also be unable to have any impact on OpenAPI descriptions of your endpoints and it would be up to you to explicitly add attributes on your endpoints to denote the error handling response.
Fortunately, Wolverine’s middleware strategy will allow you to specifically target only the relevant routes and also add OpenAPI descriptions to your API’s generated documentation. And do so in a way that is arguably more efficient than the ASP.Net Core middleware approach at runtime anyway.
Jumping right into the deep end of the pool (I’m helping take my little ones swimming this afternoon and maybe thinking ahead), I’m going to build that policy like so:
public class StreamCollisionExceptionPolicy : IHttpPolicy
{
private bool shouldApply(HttpChain chain)
{
// TODO -- and Wolverine needs a utility method on IChain to make this declarative
// for future middleware construction
return chain
.HandlerCalls()
.SelectMany(x => x.Creates)
.Any(x => x.VariableType.CanBeCastTo<IStartStream>());
}
public void Apply(IReadOnlyList<HttpChain> chains, GenerationRules rules, IContainer container)
{
// Find *only* the HTTP routes where the route tries to create new Marten event streams
foreach (var chain in chains.Where(shouldApply))
{
// Add the middleware on the outside
chain.Middleware.Insert(0, new CatchStreamCollisionFrame());
// Alter the OpenAPI metadata to register the ProblemDetails
// path
chain.Metadata.ProducesProblem(400);
}
}
// Make the codegen easier by doing most of the work in this one method
public static Task RespondWithProblemDetails(ExistingStreamIdCollisionException e, HttpContext context)
{
var problems = new ProblemDetails
{
Detail = $"Duplicated id '{e.Id}'",
Extensions =
{
["Id"] = e.Id
},
Status = 400 // The default is 500, so watch this
};
return Results.Problem(problems).ExecuteAsync(context);
}
}
// This is the actual middleware that's injecting some code
// into the runtime code generation
internal class CatchStreamCollisionFrame : AsyncFrame
{
public override void GenerateCode(GeneratedMethod method, ISourceWriter writer)
{
writer.Write("BLOCK:try");
// Write the inner code here
Next?.GenerateCode(method, writer);
writer.FinishBlock();
writer.Write($@"
BLOCK:catch({typeof(ExistingStreamIdCollisionException).FullNameInCode()} e)
await {typeof(StreamCollisionExceptionPolicy).FullNameInCode()}.{nameof(StreamCollisionExceptionPolicy.RespondWithProblemDetails)}(e, httpContext);
return;
END
");
}
}
And apply the middleware to the application like so:
app.MapWolverineEndpoints(opts =>
{
// more configuration for HTTP...
opts.AddPolicy<StreamCollisionExceptionPolicy>();
});
And lastly, here’s a test using Alba that just verifies the behavior end to end by trying to create a new event stream with the same id multiple times:
[Fact]
public async Task use_stream_collision_policy()
{
var id = Guid.NewGuid();
// First time should be fine
await Scenario(x =>
{
x.Post.Json(new StartOrderWithId(id, new[] { "Socks", "Shoes", "Shirt" })).ToUrl("/orders/create4");
});
// Second time hits an exception from stream id collision
var result2 = await Scenario(x =>
{
x.Post.Json(new StartOrderWithId(id, new[] { "Socks", "Shoes", "Shirt" })).ToUrl("/orders/create4");
x.StatusCodeShouldBe(400);
});
// And let's verify that we got what we expected for the ProblemDetails
// in the HTTP response body of the 2nd request
var details = result2.ReadAsJson<ProblemDetails>();
Guid.Parse(details.Extensions["Id"].ToString()).ShouldBe(id);
details.Detail.ShouldBe($"Duplicated id '{id}'");
}
To maybe make this a little clearer what’s going on, Wolverine can always show you the generated code it uses for your HTTP endpoints like this (I reformatted the code for legibility with Rider):
public class POST_orders_create4 : HttpHandler
{
private readonly WolverineHttpOptions _options;
private readonly ISessionFactory _sessionFactory;
public POST_orders_create4(WolverineHttpOptions options, ISessionFactory sessionFactory) : base(options)
{
_options = options;
_sessionFactory = sessionFactory;
}
public override async Task Handle(HttpContext httpContext)
{
await using var documentSession = _sessionFactory.OpenSession();
try
{
var (command, jsonContinue) = await ReadJsonAsync<StartOrderWithId>(httpContext);
if (jsonContinue == HandlerContinuation.Stop)
{
return;
}
var (orderStatus, startStream) = MarkItemEndpoint.StartOrder4(command);
// Placed by Wolverine's ISideEffect policy
startStream.Execute(documentSession);
// Commit any outstanding Marten changes
await documentSession.SaveChangesAsync(httpContext.RequestAborted).ConfigureAwait(false);
await WriteJsonAsync(httpContext, orderStatus);
}
catch (ExistingStreamIdCollisionException e)
{
await StreamCollisionExceptionPolicy.RespondWithProblemDetails(e, httpContext);
}
}
}
The Shade Tree Developer 