From aa4d86b81f6095316813c599659014c15bf9b935 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lo=C3=AFc=20Hoguin?= Date: Wed, 24 Sep 2014 14:39:17 +0300 Subject: Remove the onrequest hook It was redundant with middlewares. Allows us to save a few operations for every incoming requests. --- doc/src/guide/hooks.ezdoc | 48 +--------- doc/src/guide/http_req_resp.png | Bin 33228 -> 28370 bytes doc/src/guide/http_req_resp.svg | 174 ++++++++++++++--------------------- doc/src/manual/cowboy.ezdoc | 9 -- doc/src/manual/cowboy_protocol.ezdoc | 5 - doc/src/manual/cowboy_req.ezdoc | 6 +- doc/src/manual/cowboy_spdy.ezdoc | 5 - 7 files changed, 75 insertions(+), 172 deletions(-) (limited to 'doc/src') diff --git a/doc/src/guide/hooks.ezdoc b/doc/src/guide/hooks.ezdoc index e835a6f..1c19648 100644 --- a/doc/src/guide/hooks.ezdoc +++ b/doc/src/guide/hooks.ezdoc @@ -1,45 +1,7 @@ ::: Hooks -Cowboy provides two hooks. `onrequest` is called once the request -line and headers have been received. `onresponse` is called just -before sending the response. - -:: Onrequest - -The `onrequest` hook is called as soon as Cowboy finishes fetching -the request headers. It occurs before any other processing, including -routing. It can be used to perform any modification needed on the -request object before continuing with the processing. If a reply is -sent inside this hook, then Cowboy will move on to the next request, -skipping any subsequent handling. - -This hook is a function that takes a request object as argument, -and returns a request object. This function MUST NOT crash. Cowboy -will not send any reply if a crash occurs in this function. - -You can specify the `onrequest` hook when creating the listener, -inside the request options. - -``` erlang -cowboy:start_http(my_http_listener, 100, - [{port, 8080}], - [ - {env, [{dispatch, Dispatch}]}, - {onrequest, fun ?MODULE:debug_hook/1} - ] -). -``` - -The following hook function prints the request object everytime a -request is received. This can be useful for debugging, for example. - -``` erlang -debug_hook(Req) -> - erlang:display(Req), - Req. -``` - -Make sure to always return the last request object obtained. +Hooks allow the user to customize Cowboy's behavior during specific +operations. :: Onresponse @@ -48,9 +10,9 @@ to the socket. It can be used for the purposes of logging responses, or for modifying the response headers or body. The best example is providing custom error pages. -Note that like the `onrequest` hook, this function MUST NOT crash. -Cowboy may or may not send a reply if this function crashes. If a reply -is sent, the hook MUST explicitly provide all headers that are needed. +Note that this function MUST NOT crash. Cowboy may or may not send a +reply if this function crashes. If a reply is sent, the hook MUST +explicitly provide all headers that are needed. You can specify the `onresponse` hook when creating the listener. diff --git a/doc/src/guide/http_req_resp.png b/doc/src/guide/http_req_resp.png index e38935f..8c9cae9 100644 Binary files a/doc/src/guide/http_req_resp.png and b/doc/src/guide/http_req_resp.png differ diff --git a/doc/src/guide/http_req_resp.svg b/doc/src/guide/http_req_resp.svg index 0cfa0ae..d1e7f78 100644 --- a/doc/src/guide/http_req_resp.svg +++ b/doc/src/guide/http_req_resp.svg @@ -65,15 +65,15 @@ inkscape:pageopacity="1" inkscape:pageshadow="2" inkscape:zoom="1.4142136" - inkscape:cx="229.71447" + inkscape:cx="82.28271" inkscape:cy="764.83183" inkscape:document-units="px" inkscape:current-layer="layer1" showgrid="false" - inkscape:window-width="1920" - inkscape:window-height="1014" + inkscape:window-width="2560" + inkscape:window-height="1402" inkscape:window-x="0" - inkscape:window-y="33" + inkscape:window-y="38" inkscape:window-maximized="1" inkscape:snap-global="true" showguides="true"> @@ -93,7 +93,7 @@ image/svg+xml - + @@ -101,42 +101,28 @@ inkscape:label="Layer 1" inkscape:groupmode="layer" id="layer1"> - - - + + inkscape:export-filename="/home/essen/extend/cowboy/guide/http_req_resp.png" + inkscape:connector-curvature="0" + id="use5777" + d="m 178.49877,231.1517 203.00246,0.045" + style="fill:none;stroke:#6d8e41;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:1.99999999, 3.99999998;stroke-dashoffset:0" /> - - + transform="translate(205.03261,-207.5)"> + + + - - + style="fill:#d1f2a5;fill-opacity:1;fill-rule:nonzero;stroke:#a9ca7d;stroke-width:3;stroke-linecap:butt;stroke-linejoin:round;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0" /> router + y="323.0921">router some text - onrequest handler + y="410.38519">handler middlewares reply + y="236.73991">reply onresponse + y="323.09195">onresponse diff --git a/doc/src/manual/cowboy.ezdoc b/doc/src/manual/cowboy.ezdoc index 209d473..c26ed37 100644 --- a/doc/src/manual/cowboy.ezdoc +++ b/doc/src/manual/cowboy.ezdoc @@ -25,15 +25,6 @@ A binary status can be used to set a custom message. HTTP version. -: onrequest_fun() = fun((cowboy_req:req()) -> cowboy_req:req()) - -Fun called immediately after receiving a request. - -It can perform any operation on the Req object, including -reading the request body or replying. If a reply is sent, -the processing of the request ends here, before any middleware -is executed. - : onresponse_fun() = fun((http_status(), http_headers(), iodata(), cowboy_req:req()) -> cowboy_req:req()) diff --git a/doc/src/manual/cowboy_protocol.ezdoc b/doc/src/manual/cowboy_protocol.ezdoc index 6813295..335f2ff 100644 --- a/doc/src/manual/cowboy_protocol.ezdoc +++ b/doc/src/manual/cowboy_protocol.ezdoc @@ -14,7 +14,6 @@ as a Ranch protocol. | {max_keepalive, non_neg_integer()} | {max_request_line_length, non_neg_integer()} | {middlewares, [module()]} - | {onrequest, cowboy:onrequest_fun()} | {onresponse, cowboy:onresponse_fun()} | {timeout, timeout()}] @@ -67,10 +66,6 @@ Maximum length of the request line. List of middlewares to execute for every requests. -: onrequest (undefined) - -Fun called every time a request is received. - : onresponse (undefined) Fun called every time a response is sent. diff --git a/doc/src/manual/cowboy_req.ezdoc b/doc/src/manual/cowboy_req.ezdoc index 94556b2..bcec9b9 100644 --- a/doc/src/manual/cowboy_req.ezdoc +++ b/doc/src/manual/cowboy_req.ezdoc @@ -126,8 +126,7 @@ Types: Return the requested URL excluding the path component. This function will always return `undefined` until the -`cowboy_router` middleware has been executed. This includes -the `onrequest` hook. +`cowboy_router` middleware has been executed. : match_cookies(Req, Fields) -> Map @@ -371,8 +370,7 @@ Types: Return the requested URL. This function will always return `undefined` until the -`cowboy_router` middleware has been executed. This includes -the `onrequest` hook. +`cowboy_router` middleware has been executed. : version(Req) -> Version diff --git a/doc/src/manual/cowboy_spdy.ezdoc b/doc/src/manual/cowboy_spdy.ezdoc index 51a2110..534434c 100644 --- a/doc/src/manual/cowboy_spdy.ezdoc +++ b/doc/src/manual/cowboy_spdy.ezdoc @@ -6,7 +6,6 @@ The `cowboy_spdy` module implements SPDY/3 as a Ranch protocol. : opts() = [{env, cowboy_middleware:env()} | {middlewares, [module()]} - | {onrequest, cowboy:onrequest_fun()} | {onresponse, cowboy:onresponse_fun()}] Configuration for the SPDY protocol handler. @@ -30,10 +29,6 @@ Initial middleware environment. List of middlewares to execute for every requests. -: onrequest (undefined) - -Fun called every time a request is received. - : onresponse (undefined) Fun called every time a response is sent. -- cgit v1.2.3