Merge pull request #39 from VoxelGroup/update-docs

feat: update docs

Author: fermins

README.md

@@ -70,13 +70,13 @@ As you can see, you need to derive from MiddyNet, and specify the type of event
 After your code is executed, Middy .NET will call the after methods of the middlewares in reverse order. You can use this to, for example, alter the response in some way (adding headers, for example).
 
 ### Handling errors
-Errors can happen in the `Before` method of the middleware or in the `After` method of them. Although we capture those errors, we treat those them slightly different.
+Errors can happen in the `Before` method of the middleware or in the `After` method of them. Although we capture those errors, we treat them slightly differently.
 
 #### Errors on Before
 When an exception is thrown by a middleware in the `Before` method, the exception is captured and added to the `MiddlewareBeforeExceptions` list, so that the following middlewares and the function can react to it.
 
 #### Errors on Handler
-When an exception is thrown by the function in its `Handle` method and before the `After` middlewares are called, the exception is captured in the `HandlerException` property of the context, so that the following middlewares can react to it.
+When an exception is thrown by the function in its `Handle` method and before the `After` middlewares are called, the exception is captured in the `HandlerException` property of the context, so that the following middlewares' `After` method can react to it.
 
 #### Errors on After
 When an exception is thrown by a middleware in the `After` method, the exception is captured and added to the `MiddlewareAfterExceptions` list, so that the following middlewares can react to it.

docs/source/intro/howitworks.rst

@@ -3,6 +3,6 @@ How it works
 
 **MiddyNet** is a lightweight middleware engine. A middleware is a piece of code that can be run before or after your function is run. In the *before* section, middlewares are run in the same order that are added. In the *after* section, middlewares are run in the inverse order that are added. Usually, a middleware will only make sense to do anything in one of the sections.
 
-Exceptions can be thrown by the middlewares and they are captured by the library. If the exception is thrown in the *before* section, the exception is made available to the following middlewares and eventually to your function via the context. If the exception is thrown in the *after* section, it's eventually thrown by the library as an *AggregateException*.
+Exceptions can be thrown by the middlewares and they are captured by the library. If the exception is thrown in the *before* section, the exception is made available to the following middlewares and eventually to your function via the context. If the exception is thrown in the *handler* or in the *after* section, it's eventually thrown by the library as an *AggregateException*. Non cleaned ``MiddlewareBeforeExceptions`` will also be included in the resulting AggregateException.
 
 **MiddyNet** also adds a Logger to log structured logging and a way to capture and propagate the TraceContext as described `here <https://www.w3.org/TR/trace-context/>`_.

docs/source/nuget/packages.rst

@@ -263,3 +263,54 @@ And like this for Http API::
             return Task.FromResult(result);
         }
     }
+
+Voxel.MiddyNet.ProblemDetailsMiddleware
+---------------------------------------
+The middleware contained in this package formats Api exceptions as ProblemDetails following [RFC7807](https://tools.ietf.org/html/rfc7807).
+
+There are two versions avalaible: 
+
+* One for REST Api (APIGatewayProxyRequest and APIGatewayProxyResponse).
+* And another for Http Api (APIGatewayHttpApiV2ProxyRequest and APIGatewayHttpApiV2ProxyResponse).
+
+Configuration
+^^^^^^^^^^^^^
+It can receive a ``ProblemDetailsMiddlewareOptions`` to specify mappings from a particular exception type to an Http status code. E.g: 
+
+    var options = new ProblemDetailsMiddlewareOptions();
+    options.Map<NotImplementedException>(501)));
+    
+When a ``NotImplementedException`` is thrown, ProblemDetailsMiddleware will return the exception message with a 501 Http status code.
+
+Sample code
+^^^^^^^^^^^
+A typical usage of the ProblemDetailsMiddleware for REST Api whould look something like:
+
+    public class ApiGatewayProblemDetails : MiddyNet<APIGatewayProxyRequest, APIGatewayProxyResponse>
+    {
+        public ApiGatewayProblemDetails()
+        {
+            Use(new ProblemDetailsMiddleware.ProblemDetailsMiddleware(new ProblemDetailsMiddlewareOptions().Map<NotImplementedException>(501)));
+        }
+
+        protected override Task<APIGatewayProxyResponse> Handle(APIGatewayProxyRequest lambdaEvent, MiddyNetContext context)
+        {
+            throw new NotImplementedException("this will be used in the problem details description");
+        }
+    }
+
+And for Http Api:
+
+    public class ApiGatewayProblemDetails : MiddyNet<APIGatewayHttpApiV2ProxyRequest, APIGatewayHttpApiV2ProxyResponse>
+    {
+        public ApiGatewayProblemDetails()
+        {
+            Use(new ProblemDetailsMiddleware.ProblemDetailsMiddleware(new ProblemDetailsMiddlewareOptions().Map<NotImplementedException>(501)));
+        }
+
+        protected override Task<APIGatewayHttpApiV2ProxyResponse> Handle(APIGatewayHttpApiV2ProxyRequest lambdaEvent, MiddyNetContext context)
+        {
+            throw new NotImplementedException("this will be used in the problem details description");
+        }
+    }
+

docs/source/started/middycontext.rst

@@ -15,9 +15,25 @@ A ``Dictionary<string, object>`` filled with the information that the different
 
 MiddlewareExceptions
 --------------------
+There are 4 properties and a method related to exceptions:
 
-A ``List<Exception>``, with the exceptions thrown by the different middlewares. 
+* ``List<Exception> MiddlewareBeforeExceptions { get; }``, *Middleare with the exceptions thrown by the middlewares' *Before* method.
+* ``Exception HandlerException { get; set; }``, with the exception thrown by the custom handler's *Handle* method.
+* ``List<Exception> MiddlewareAfterExceptions { get; }``, with the exceptions thrown by the middlewares' *After* method. 
+* ``bool HasExceptions { get; }``, which tells if there are any exceptions  in the aforementioned properties
+* ``List<Exception> GetAllExceptions()``, which returns the exceptions in the three properties as a single list, in the same order as they happened.
+
+You may want to check whether any exceptions occured before proceeding with your custom logic in the handler like so:
+
+	if (context.HasExceptions)
+    {
+        // do stuff...
+        context.MiddlewareBeforeExceptions.Clear();
+    }
+
+This will prevent those exceptions to be returned at the end of the pipeline processing.
 
 Logger
 ------
-An object of type MiddyLogger to allow you to log structured logs. It uses the ``ILambdaLogger`` provided by AWS internally. See more information about the :doc:`/logger`.
+An object of type MiddyLogger to allow you to log structured logs. It uses the ``ILambdaLogger`` provided by AWS internally. See more information about the :doc:`/logger`.
+

docs/source/writing/writing.rst

@@ -34,4 +34,4 @@ The value of the property can be whatever you want, from a single type to a comp
 
 Exceptions
 ----------
-You don't need to catch exceptions in the middleware. The library will catch them for you and add them to the ``MiddlewareExceptions`` property.
+You don't need to catch exceptions in the middleware. The library will catch them for you and add them to the context's corresponding exceptions collection (``MiddlewareBeforeExceptions``, ``HandlerException`` or ``MiddlewareAfterExceptions`` depending on where was the exception thrown).