From 903716bcf5c291edc8d595f798b7798aa7290345 Mon Sep 17 00:00:00 2001
From: Thom Dickson <td3of4@gmail.com>
Date: Thu, 25 Jul 2024 20:38:26 -0400
Subject: [PATCH] update docs and examples for endpoint middleware

---
 .../middleware_with_endpoint.zig                | 16 +++++++---------
 src/middleware.zig                              | 17 +++++++++++------
 2 files changed, 18 insertions(+), 15 deletions(-)

diff --git a/examples/middleware_with_endpoint/middleware_with_endpoint.zig b/examples/middleware_with_endpoint/middleware_with_endpoint.zig
index 543600c..3e94450 100644
--- a/examples/middleware_with_endpoint/middleware_with_endpoint.zig
+++ b/examples/middleware_with_endpoint/middleware_with_endpoint.zig
@@ -123,19 +123,17 @@ const SessionMiddleWare = struct {
 //
 // !!!! ENDPOINT !!!
 //
-// We define an endpoint as we usually would.
-// NO ROUTING IS PERFORMED
-// as we are just going to wrap it in a bunch of Middleware components
-// and therefore NOT using an endpoint listener that would the routing for us
+// We define an endpoint as we usually would; however,
+// NO ROUTING IS PERFORMED BY DEFAULT!
 //
-// Hence, the endpoint should check r.path in its on_request to check wether
-// it is adressed or not.
+// This can be changed using the EndpointHandlerOptions passed into the
+// EndpointHandler.init() method.
 //
 // N.B. the EndpointHandler checks if the endpoint turned the request into
 // "finished" state, e.g. by sending anything. If the endpoint didn't finish the
 // request, the EndpointHandler will pass the request on to the next handler in
-// the chain if there is one. See also the EndpointHandler's `breakOnFinish`
-// parameter.
+// the chain if there is one. See also the EndpointHandlerOptions's
+// `breakOnFinish` parameter.
 //
 const HtmlEndpoint = struct {
     ep: zap.Endpoint = undefined,
@@ -210,7 +208,7 @@ pub fn main() !void {
     var htmlHandler = zap.Middleware.EndpointHandler(Handler, Context).init(
         htmlEndpoint.endpoint(), // the endpoint
         null, // no other handler (we are the last in the chain)
-        true, // break on finish. See EndpointHandler for this. Not applicable here.
+        .{}, // We can set custom EndpointHandlerOptions here
     );
 
     // we wrap it in the session Middleware component
diff --git a/src/middleware.zig b/src/middleware.zig
index 4f4e663..c094fee 100644
--- a/src/middleware.zig
+++ b/src/middleware.zig
@@ -51,14 +51,15 @@ pub fn Handler(comptime ContextType: anytype) type {
     };
 }
 
+/// Options used to change the behavior of an `EndpointHandler`
 pub const EndpointHandlerOptions = struct {
     /// If `true`, the handler will stop handing requests down the chain if the
     /// endpoint processed the request.
     breakOnFinish: bool = true,
 
-    /// If `true`, the handler will only execute against request that match the
-    /// endpoint's path setting.
-    useRoutes: bool = false,
+    /// If `true`, the handler will only execute against requests that match
+    /// the endpoint's `path` setting.
+    checkPath: bool = false,
 };
 
 /// A convenience handler for artibrary zap.Endpoint
@@ -71,8 +72,12 @@ pub fn EndpointHandler(comptime HandlerType: anytype, comptime ContextType: anyt
         const Self = @This();
 
         /// Create an endpointhandler from an endpoint and pass in the next (other) handler in the chain.
-        /// If `breakOnFinish` is `true`, the handler will stop handing requests down the chain if
-        /// the endpoint processed the request.
+        ///
+        /// By default no routing is performed on requests. This behavior can be changed by setting
+        /// `checkPath` in the provided options.
+        ///
+        /// If the `breakOnFinish` option is `true`, the handler will stop handing requests down the chain
+        /// if the endpoint processed the request.
         pub fn init(endpoint: *zap.Endpoint, other: ?*HandlerType, options: EndpointHandlerOptions) Self {
             return .{
                 .handler = HandlerType.init(onRequest, other),
@@ -94,7 +99,7 @@ pub fn EndpointHandler(comptime HandlerType: anytype, comptime ContextType: anyt
         pub fn onRequest(handler: *HandlerType, r: zap.Request, context: *ContextType) bool {
             const self: *Self = @fieldParentPtr("handler", handler);
             r.setUserContext(context);
-            if (!self.options.useRoutes or
+            if (!self.options.checkPath or
                 std.mem.startsWith(u8, r.path orelse "", self.endpoint.settings.path))
             {
                 self.endpoint.onRequest(r);