docs: Added documentation for changes

docs/guide/http/marten.md

@@ -33,7 +33,7 @@ look like this:
         return Results.Ok(invoice);
     }
 ```
-<sup><a href='https://github.com/JasperFx/wolverine/blob/main/src/Http/WolverineWebApi/Marten/Documents.cs#L11-L28' title='Snippet source file'>snippet source</a> | <a href='#snippet-sample_get_invoice_longhand' title='Start of snippet'>anchor</a></sup>
+<sup><a href='https://github.com/JasperFx/wolverine/blob/main/src/Http/WolverineWebApi/Marten/Documents.cs#L13-L30' title='Snippet source file'>snippet source</a> | <a href='#snippet-sample_get_invoice_longhand' title='Start of snippet'>anchor</a></sup>
 <!-- endSnippet -->
 
 Pretty straightforward, but it's a little annoying to have to scatter in all the attributes for OpenAPI and there's definitely
@@ -49,7 +49,7 @@ public static Invoice Get([Document] Invoice invoice)
     return invoice;
 }
 ```
-<sup><a href='https://github.com/JasperFx/wolverine/blob/main/src/Http/WolverineWebApi/Marten/Documents.cs#L30-L38' title='Snippet source file'>snippet source</a> | <a href='#snippet-sample_using_document_attribute' title='Start of snippet'>anchor</a></sup>
+<sup><a href='https://github.com/JasperFx/wolverine/blob/main/src/Http/WolverineWebApi/Marten/Documents.cs#L32-L40' title='Snippet source file'>snippet source</a> | <a href='#snippet-sample_using_document_attribute' title='Start of snippet'>anchor</a></sup>
 <!-- endSnippet -->
 
 Notice that the `[Document]` attribute was able to use the "id" route parameter. By default, Wolverine is looking first
@@ -66,7 +66,7 @@ public static IMartenOp Approve([Document("number")] Invoice invoice)
     return MartenOps.Store(invoice);
 }
 ```
-<sup><a href='https://github.com/JasperFx/wolverine/blob/main/src/Http/WolverineWebApi/Marten/Documents.cs#L47-L56' title='Snippet source file'>snippet source</a> | <a href='#snippet-sample_overriding_route_argument_with_document_attribute' title='Start of snippet'>anchor</a></sup>
+<sup><a href='https://github.com/JasperFx/wolverine/blob/main/src/Http/WolverineWebApi/Marten/Documents.cs#L49-L58' title='Snippet source file'>snippet source</a> | <a href='#snippet-sample_overriding_route_argument_with_document_attribute' title='Start of snippet'>anchor</a></sup>
 <!-- endSnippet -->
 
 
@@ -253,3 +253,42 @@ public static (OrderStatus, Events) Post(MarkItemReady command, Order order)
 <sup><a href='https://github.com/JasperFx/wolverine/blob/main/src/Http/WolverineWebApi/Marten/Orders.cs#L193-L223' title='Snippet source file'>snippet source</a> | <a href='#snippet-sample_returning_multiple_events_from_http_endpoint' title='Start of snippet'>anchor</a></sup>
 <!-- endSnippet -->
 
+### Compiled Query Resource Writer Policy
+
+Marten integration comes with an `IResourceWriterPolicy` policy that handles compiled queries as return types. 
+Register it in `WolverineHttpOptions` like this:
+
+<!-- snippet: sample_user_marten_compiled_query_policy -->
+<a id='snippet-sample_user_marten_compiled_query_policy'></a>
+```cs
+opts.UseMartenCompiledQueryResultPolicy();
+```
+<sup><a href='https://github.com/JasperFx/wolverine/blob/main/src/Http/WolverineWebApi/Program.cs#L144-L146' title='Snippet source file'>snippet source</a> | <a href='#snippet-sample_user_marten_compiled_query_policy' title='Start of snippet'>anchor</a></sup>
+<!-- endSnippet -->
+
+If you now return a compiled query from an Endpoint the result will get directly streamed to the client as JSON. Short circuiting JSON deserialization.
+<!-- snippet: sample_compiled_query_return_endpoint -->
+<a id='snippet-sample_compiled_query_return_endpoint'></a>
+```cs
+[WolverineGet("/invoices/approved")]
+public static ApprovedInvoicedCompiledQuery GetApproved()
+{
+    return new ApprovedInvoicedCompiledQuery();
+}
+```
+<sup><a href='https://github.com/JasperFx/wolverine/blob/main/src/Http/WolverineWebApi/Marten/Documents.cs#L60-L66' title='Snippet source file'>snippet source</a> | <a href='#snippet-sample_compiled_query_return_endpoint' title='Start of snippet'>anchor</a></sup>
+<!-- endSnippet -->
+
+<!-- snippet: sample_compiled_query_return_query -->
+<a id='snippet-sample_compiled_query_return_query'></a>
+```cs
+public class ApprovedInvoicedCompiledQuery : ICompiledListQuery<Invoice>
+{
+    public Expression<Func<IMartenQueryable<Invoice>, IEnumerable<Invoice>>> QueryIs()
+    {
+        return q => q.Where(x => x.Approved);
+    }
+}
+```
+<sup><a href='https://github.com/JasperFx/wolverine/blob/main/src/Http/WolverineWebApi/Marten/Documents.cs#L82-L92' title='Snippet source file'>snippet source</a> | <a href='#snippet-sample_compiled_query_return_query' title='Start of snippet'>anchor</a></sup>
+<!-- endSnippet -->

docs/guide/http/policies.md

@@ -65,7 +65,7 @@ app.MapWolverineEndpoints(opts =>
     // Wolverine.Http.FluentValidation
     opts.UseFluentValidationProblemDetailMiddleware();
 ```
-<sup><a href='https://github.com/JasperFx/wolverine/blob/main/src/Http/WolverineWebApi/Program.cs#L116-L137' title='Snippet source file'>snippet source</a> | <a href='#snippet-sample_using_configure_endpoints' title='Start of snippet'>anchor</a></sup>
+<sup><a href='https://github.com/JasperFx/wolverine/blob/main/src/Http/WolverineWebApi/Program.cs#L117-L138' title='Snippet source file'>snippet source</a> | <a href='#snippet-sample_using_configure_endpoints' title='Start of snippet'>anchor</a></sup>
 <!-- endSnippet -->
 
 The `HttpChain` model is a configuration time structure that Wolverine.Http will use at runtime to create the full
@@ -97,5 +97,42 @@ app.MapWolverineEndpoints(opts =>
     // Wolverine.Http.FluentValidation
     opts.UseFluentValidationProblemDetailMiddleware();
 ```
-<sup><a href='https://github.com/JasperFx/wolverine/blob/main/src/Http/WolverineWebApi/Program.cs#L116-L137' title='Snippet source file'>snippet source</a> | <a href='#snippet-sample_using_configure_endpoints' title='Start of snippet'>anchor</a></sup>
+<sup><a href='https://github.com/JasperFx/wolverine/blob/main/src/Http/WolverineWebApi/Program.cs#L117-L138' title='Snippet source file'>snippet source</a> | <a href='#snippet-sample_using_configure_endpoints' title='Start of snippet'>anchor</a></sup>
 <!-- endSnippet -->
+
+## Resource Writer Policies
+
+Wolverine has an additional type of policy that deals with how an endpoints primary result is handled. 
+
+<!-- snippet: sample_IResourceWriterPolicy -->
+<a id='snippet-sample_iresourcewriterpolicy'></a>
+```cs
+/// <summary>
+///    Use to apply custom handling to the primary result of an HTTP endpoint handler
+/// </summary>
+public interface IResourceWriterPolicy
+{
+    /// <summary>
+    ///  Called during bootstrapping to see whether this policy can handle the chain. If yes no further policies are tried.
+    /// </summary>
+    /// <param name="chain"> The chain to test against</param>
+    /// <returns>True if it applies to the chain, false otherwise</returns>
+    bool TryApply(HttpChain chain);
+}
+```
+<sup><a href='https://github.com/JasperFx/wolverine/blob/main/src/Http/Wolverine.Http/Resources/IResourceWriterPolicy.cs#L3-L17' title='Snippet source file'>snippet source</a> | <a href='#snippet-sample_iresourcewriterpolicy' title='Start of snippet'>anchor</a></sup>
+<!-- endSnippet -->
+
+Only one of these so called resource writer policies can apply to each endpoint and there are a couple of built in policies already.
+
+If you need special handling of a primary return type you can implement `IResourceWriterPolicy` and register it in `WolverineHttpOptions`
+
+<!-- snippet: sample_register_resource_writer_policy -->
+<a id='snippet-sample_register_resource_writer_policy'></a>
+```cs
+opts.AddResourceWriterPolicy<CustomResourceWriterPolicy>();
+```
+<sup><a href='https://github.com/JasperFx/wolverine/blob/main/src/Http/WolverineWebApi/Program.cs#L153-L155' title='Snippet source file'>snippet source</a> | <a href='#snippet-sample_register_resource_writer_policy' title='Start of snippet'>anchor</a></sup>
+<!-- endSnippet -->
+
+Resource writer policies registered this way will be applied in order before all built in policies.

src/Http/Wolverine.Http/Resources/IResourceWriterPolicy.cs

@@ -1,6 +1,17 @@
 namespace Wolverine.Http.Resources;
 
+#region sample_IResourceWriterPolicy
+/// <summary>
+///    Use to apply custom handling to the primary result of an HTTP endpoint handler
+/// </summary>
 public interface IResourceWriterPolicy
 {
+    /// <summary>
+    ///  Called during bootstrapping to see whether this policy can handle the chain. If yes no further policies are tried.
+    /// </summary>
+    /// <param name="chain"> The chain to test against</param>
+    /// <returns>True if it applies to the chain, false otherwise</returns>
     bool TryApply(HttpChain chain);
-}
+}
+
+#endregion

src/Http/WolverineWebApi/CustomResourceWriterPolicy.cs

@@ -0,0 +1,10 @@
+using Wolverine.Http;
+using Wolverine.Http.Resources;
+
+public class CustomResourceWriterPolicy : IResourceWriterPolicy
+{
+    public bool TryApply(HttpChain chain)
+    {
+        return false;
+    }
+}

src/Http/WolverineWebApi/Marten/Documents.cs

@@ -57,11 +57,13 @@ public static IMartenOp Approve([Document("number")] Invoice invoice)
 
     #endregion
 
+    #region sample_compiled_query_return_endpoint
     [WolverineGet("/invoices/approved")]
     public static ApprovedInvoicedCompiledQuery GetApproved()
     {
         return new ApprovedInvoicedCompiledQuery();
     } 
+    #endregion
 
     [WolverineGet("/invoices/compiled/{id}")]
     public static ByIdCompiled GetCompiled(Guid id)
@@ -77,6 +79,8 @@ public class Invoice
     public bool Approved { get; set; }
 }
 
+#region sample_compiled_query_return_query
+
 public class ApprovedInvoicedCompiledQuery : ICompiledListQuery<Invoice>
 {
     public Expression<Func<IMartenQueryable<Invoice>, IEnumerable<Invoice>>> QueryIs()
@@ -85,6 +89,8 @@ public Expression<Func<IMartenQueryable<Invoice>, IEnumerable<Invoice>>> QueryIs
     }
 }
 
+#endregion
+
 public class ByIdCompiled : ICompiledQuery<Invoice, Invoice?>
 {
     public readonly Guid Id;

src/Http/WolverineWebApi/Program.cs

@@ -141,13 +141,19 @@
     opts.AddMiddleware(typeof(BeforeAndAfterMiddleware),
         chain => chain.Method.HandlerType == typeof(MiddlewareEndpoints));
 
+#region sample_user_marten_compiled_query_policy
     opts.UseMartenCompiledQueryResultPolicy();
+#endregion
 
 #region sample_register_http_middleware_by_type
     opts.AddMiddlewareByMessageType(typeof(FakeAuthenticationMiddleware));
     opts.AddMiddlewareByMessageType(typeof(CanShipOrderMiddleWare));
 #endregion
 
+#region sample_register_resource_writer_policy
+    opts.AddResourceWriterPolicy<CustomResourceWriterPolicy>();
+#endregion
+
     // Publish messages coming from 
     opts.PublishMessage<HttpMessage1>(HttpMethod.Post, "/publish/message1").WithTags("messages");
     opts.PublishMessage<HttpMessage2>("/publish/message2").WithTags("messages");