aboutsummaryrefslogtreecommitdiffstats
path: root/doc
diff options
context:
space:
mode:
authorLoïc Hoguin <[email protected]>2014-09-24 14:39:17 +0300
committerLoïc Hoguin <[email protected]>2014-09-24 14:39:17 +0300
commitaa4d86b81f6095316813c599659014c15bf9b935 (patch)
treed503405a06e70c314975cde6dbf706939825890a /doc
parent25259671f51c076720b64959a700263eaa0937b2 (diff)
downloadcowboy-aa4d86b81f6095316813c599659014c15bf9b935.tar.gz
cowboy-aa4d86b81f6095316813c599659014c15bf9b935.tar.bz2
cowboy-aa4d86b81f6095316813c599659014c15bf9b935.zip
Remove the onrequest hook
It was redundant with middlewares. Allows us to save a few operations for every incoming requests.
Diffstat (limited to 'doc')
-rw-r--r--doc/src/guide/hooks.ezdoc48
-rw-r--r--doc/src/guide/http_req_resp.pngbin33228 -> 28370 bytes
-rw-r--r--doc/src/guide/http_req_resp.svg174
-rw-r--r--doc/src/manual/cowboy.ezdoc9
-rw-r--r--doc/src/manual/cowboy_protocol.ezdoc5
-rw-r--r--doc/src/manual/cowboy_req.ezdoc6
-rw-r--r--doc/src/manual/cowboy_spdy.ezdoc5
7 files changed, 75 insertions, 172 deletions
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
--- a/doc/src/guide/http_req_resp.png
+++ b/doc/src/guide/http_req_resp.png
Binary files 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 @@
<dc:format>image/svg+xml</dc:format>
<dc:type
rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
- <dc:title></dc:title>
+ <dc:title />
</cc:Work>
</rdf:RDF>
</metadata>
@@ -101,42 +101,28 @@
inkscape:label="Layer 1"
inkscape:groupmode="layer"
id="layer1">
- <use
- x="0"
- y="0"
- xlink:href="#path5757"
- id="use5779"
- transform="matrix(0.59961275,-0.80029029,0.80029029,0.59961275,-103.8895,437.48518)"
- width="744.09448"
- height="1052.3622"
- inkscape:export-filename="/home/essen/extend/cowboy/guide/http_req_resp.png"
+ <path
+ inkscape:export-ydpi="89.926643"
inkscape:export-xdpi="89.926643"
- inkscape:export-ydpi="89.926643" />
- <use
- x="0"
- y="0"
- xlink:href="#path5757"
- id="use5777"
- transform="matrix(0.92125726,-0.38895379,0.38895379,0.92125726,-85.14742,176.0134)"
- width="744.09448"
- height="1052.3622"
inkscape:export-filename="/home/essen/extend/cowboy/guide/http_req_resp.png"
- inkscape:export-xdpi="89.926643"
- inkscape:export-ydpi="89.926643" />
- <path
- style="fill:none;stroke:#6d8e41;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;stroke-miterlimit:4;stroke-dasharray:2, 4;stroke-dashoffset:0"
- d="m 188.5,231.36218 187,79"
- id="path5757"
inkscape:connector-curvature="0"
- inkscape:export-filename="/home/essen/extend/cowboy/guide/http_req_resp.png"
+ id="use5779"
+ d="M 194.29441,340.67017 369.64493,238.3853"
+ style="fill:none;stroke:#6d8e41;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:2, 4;stroke-dashoffset:0" />
+ <path
+ inkscape:export-ydpi="89.926643"
inkscape:export-xdpi="89.926643"
- inkscape:export-ydpi="89.926643" />
+ 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" />
<use
x="0"
y="0"
xlink:href="#g5650"
id="use5753"
- transform="translate(475.11201,-33.017248)"
+ transform="translate(475.11201,-117.70525)"
width="744.09448"
height="1052.3622"
inkscape:export-filename="/home/essen/extend/cowboy/guide/http_req_resp.png"
@@ -154,12 +140,12 @@
inkscape:export-xdpi="89.926643"
inkscape:export-ydpi="89.926643" />
<rect
- style="fill:#ffffff;fill-opacity:1;fill-rule:nonzero;stroke:#a9ca7d;stroke-width:2.44279908999999984;stroke-linecap:butt;stroke-linejoin:round;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0"
+ style="fill:#ffffff;fill-opacity:1;fill-rule:nonzero;stroke:#a9ca7d;stroke-width:2.44279909;stroke-linecap:butt;stroke-linejoin:round;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0"
id="rect5367"
width="207.05719"
height="171.55719"
x="43.721401"
- y="360.88528"
+ y="276.1973"
rx="11.072577"
inkscape:export-filename="/home/essen/extend/cowboy/guide/http_req_resp.png"
inkscape:export-xdpi="89.926643"
@@ -169,34 +155,38 @@
y="0"
xlink:href="#g5650"
id="use5654"
- transform="translate(205.03261,53.351708)"
- width="744.09448"
- height="1052.3622"
- inkscape:export-filename="/home/essen/extend/cowboy/guide/http_req_resp.png"
- inkscape:export-xdpi="89.926643"
- inkscape:export-ydpi="89.926643" />
- <use
- x="0"
- y="0"
- xlink:href="#use5656"
- id="use5658"
- transform="translate(0,-86.13396)"
+ transform="translate(205.03261,-31.336292)"
width="744.09448"
height="1052.3622"
inkscape:export-filename="/home/essen/extend/cowboy/guide/http_req_resp.png"
inkscape:export-xdpi="89.926643"
inkscape:export-ydpi="89.926643" />
- <use
- x="0"
- y="0"
- xlink:href="#use5658"
+ <g
id="use5660"
- transform="translate(0,-87.519558)"
- width="744.09448"
- height="1052.3622"
- inkscape:export-filename="/home/essen/extend/cowboy/guide/http_req_resp.png"
- inkscape:export-xdpi="89.926643"
- inkscape:export-ydpi="89.926643" />
+ transform="translate(205.03261,-207.5)">
+ <path
+ style="opacity:0.8;fill:none;stroke:#6d8e41;stroke-width:2;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none"
+ d="m -57.78256,351.41962 0,52.3259"
+ id="path3051"
+ inkscape:connector-curvature="0" />
+ <path
+ sodipodi:type="star"
+ style="opacity:0.8;fill:#6d8e41;fill-opacity:1;fill-rule:nonzero;stroke:#6d8e41;stroke-width:0;stroke-linecap:butt;stroke-linejoin:round;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0"
+ id="path3053"
+ sodipodi:sides="3"
+ sodipodi:cx="-222.73865"
+ sodipodi:cy="415.25897"
+ sodipodi:r1="14.849242"
+ sodipodi:r2="7.4246211"
+ sodipodi:arg1="1.5707963"
+ sodipodi:arg2="2.6179939"
+ inkscape:flatsided="true"
+ inkscape:rounded="0"
+ inkscape:randomized="0"
+ d="m -222.73865,430.10821 -12.85982,-22.27386 25.71964,0 z"
+ inkscape:transform-center-y="2.1823437"
+ transform="matrix(0.58787746,0,0,0.58787746,73.160466,163.35774)" />
+ </g>
<use
x="0"
y="0"
@@ -287,17 +277,6 @@
<use
x="0"
y="0"
- xlink:href="#rect5273"
- id="use5335"
- transform="translate(318.97597,268.31614)"
- width="744.09448"
- height="1052.3622"
- inkscape:export-filename="/home/essen/extend/cowboy/guide/http_req_resp.png"
- inkscape:export-xdpi="89.926643"
- inkscape:export-ydpi="89.926643" />
- <use
- x="0"
- y="0"
xlink:href="#rect5273-22"
id="use5355"
transform="translate(318.97592,-176.5)"
@@ -328,23 +307,20 @@
inkscape:export-filename="/home/essen/extend/cowboy/guide/http_req_resp.png"
inkscape:export-xdpi="89.926643"
inkscape:export-ydpi="89.926643" />
- <use
- x="0"
- y="0"
- xlink:href="#use5335"
+ <rect
+ rx="15"
+ y="386.37247"
+ x="94.955292"
+ height="36.392323"
+ width="104.5895"
id="use5363"
- transform="translate(0,173.33215)"
- width="744.09448"
- height="1052.3622"
- inkscape:export-filename="/home/essen/extend/cowboy/guide/http_req_resp.png"
- inkscape:export-xdpi="89.926643"
- inkscape:export-ydpi="89.926643" />
+ 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" />
<use
x="0"
y="0"
xlink:href="#use5361"
id="use5365"
- transform="translate(0,173.66424)"
+ transform="translate(0,88.97624)"
width="744.09448"
height="1052.3622"
inkscape:export-filename="/home/essen/extend/cowboy/guide/http_req_resp.png"
@@ -393,7 +369,7 @@
xml:space="preserve"
style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#77823c;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans"
x="146.53125"
- y="407.78009"
+ y="323.0921"
id="text5371-5"
sodipodi:linespacing="125%"
inkscape:export-filename="/home/essen/extend/cowboy/guide/http_req_resp.png"
@@ -402,7 +378,7 @@
sodipodi:role="line"
id="tspan5373-0"
x="146.53125"
- y="407.78009">router</tspan></text>
+ y="323.0921">router</tspan></text>
<text
xml:space="preserve"
style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#6d8e41;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans"
@@ -417,22 +393,8 @@
<text
xml:space="preserve"
style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#6d8e41;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans"
- x="147.00391"
- y="321.39722"
- id="text5371-2-3"
- sodipodi:linespacing="125%"
- inkscape:export-filename="/home/essen/extend/cowboy/guide/http_req_resp.png"
- inkscape:export-xdpi="89.926643"
- inkscape:export-ydpi="89.926643"><tspan
- sodipodi:role="line"
- id="tspan5373-6-7"
- x="147.00391"
- y="321.39722">onrequest</tspan></text>
- <text
- xml:space="preserve"
- style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#6d8e41;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans"
x="146.53125"
- y="495.07318"
+ y="410.38519"
id="text5371-2-3-0"
sodipodi:linespacing="125%"
inkscape:export-filename="/home/essen/extend/cowboy/guide/http_req_resp.png"
@@ -441,11 +403,11 @@
sodipodi:role="line"
id="tspan5373-6-7-3"
x="146.53125"
- y="495.07318">handler</tspan></text>
+ y="410.38519">handler</tspan></text>
<text
xml:space="preserve"
style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#6d8e41;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans"
- x="-446.99591"
+ x="-362.30792"
y="63.078125"
id="text5371-2-3-0-7"
sodipodi:linespacing="125%"
@@ -455,7 +417,7 @@
inkscape:export-ydpi="89.926643"><tspan
sodipodi:role="line"
id="tspan5373-6-7-3-9"
- x="-446.99591"
+ x="-362.30792"
y="63.078125">middlewares</tspan></text>
<text
xml:space="preserve"
@@ -487,7 +449,7 @@
y="0"
xlink:href="#rect5273-7"
id="use5668"
- transform="translate(589.05532,207.03588)"
+ transform="translate(589.05532,122.34788)"
width="744.09448"
height="1052.3622"
inkscape:export-filename="/home/essen/extend/cowboy/guide/http_req_resp.png"
@@ -498,7 +460,7 @@
y="0"
xlink:href="#rect5273"
id="use5670"
- transform="translate(589.05538,355.27934)"
+ transform="translate(589.05538,270.59134)"
width="744.09448"
height="1052.3622"
inkscape:export-filename="/home/essen/extend/cowboy/guide/http_req_resp.png"
@@ -509,7 +471,7 @@
y="0"
xlink:href="#use5355"
id="use5672"
- transform="translate(270.07946,434.91762)"
+ transform="translate(270.07946,350.22962)"
width="744.09448"
height="1052.3622"
inkscape:export-filename="/home/essen/extend/cowboy/guide/http_req_resp.png"
@@ -520,7 +482,7 @@
y="0"
xlink:href="#text5371-4-0"
id="use5674"
- transform="translate(270.29655,434.16115)"
+ transform="translate(270.29655,349.47315)"
width="744.09448"
height="1052.3622"
inkscape:export-filename="/home/essen/extend/cowboy/guide/http_req_resp.png"
@@ -530,7 +492,7 @@
xml:space="preserve"
style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#77823c;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans"
x="417.30829"
- y="321.42792"
+ y="236.73991"
id="text5371-9"
sodipodi:linespacing="125%"
inkscape:export-filename="/home/essen/extend/cowboy/guide/http_req_resp.png"
@@ -539,12 +501,12 @@
sodipodi:role="line"
id="tspan5373-57"
x="417.30829"
- y="321.42792">reply</tspan></text>
+ y="236.73991">reply</tspan></text>
<text
xml:space="preserve"
style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#6d8e41;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans"
x="417.30829"
- y="407.77994"
+ y="323.09195"
id="text5371-2-0"
sodipodi:linespacing="125%"
inkscape:export-filename="/home/essen/extend/cowboy/guide/http_req_resp.png"
@@ -553,6 +515,6 @@
sodipodi:role="line"
id="tspan5373-6-8"
x="417.30829"
- y="407.77994">onresponse</tspan></text>
+ y="323.09195">onresponse</tspan></text>
</g>
</svg>
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.