From f3d6b05b863fe177a34a8a6ba48c5f263ef8cf82 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lo=C3=AFc=20Hoguin?= Date: Sun, 29 Oct 2017 19:52:27 +0000 Subject: Add cowboy_req:inform/2,3 User code can now send as many 1xx responses as necessary. --- doc/src/guide/resp.asciidoc | 23 +++++++ doc/src/manual/cowboy_req.asciidoc | 1 + doc/src/manual/cowboy_req.inform.asciidoc | 83 +++++++++++++++++++++++++ doc/src/manual/cowboy_req.push.asciidoc | 1 + doc/src/manual/cowboy_req.reply.asciidoc | 1 + doc/src/manual/cowboy_req.stream_reply.asciidoc | 1 + 6 files changed, 110 insertions(+) create mode 100644 doc/src/manual/cowboy_req.inform.asciidoc (limited to 'doc/src') diff --git a/doc/src/guide/resp.asciidoc b/doc/src/guide/resp.asciidoc index 2eaa804..6d4967e 100644 --- a/doc/src/guide/resp.asciidoc +++ b/doc/src/guide/resp.asciidoc @@ -262,6 +262,29 @@ Req = cowboy_req:reply(200, #{ // example would be automatic concatenation of CSS or JS // files. +=== Informational responses + +Cowboy allows you to send informational responses. + +Informational responses are responses that have a status +code between 100 and 199. Any number can be sent before +the proper response. Sending an informational response +does not change the behavior of the proper response, and +clients are expected to ignore any informational response +they do not understand. + +The following snippet sends a 103 informational response +with some headers that are expected to be in the final +response. + +[source,erlang] +---- +Req = cowboy_req:inform(103, #{ + <<"link">> => <<"; rel=preload; as=style">>, + <<"link">> => <<"; rel=preload; as=script">> +}, Req0). +---- + === Push The HTTP/2 protocol introduced the ability to push resources diff --git a/doc/src/manual/cowboy_req.asciidoc b/doc/src/manual/cowboy_req.asciidoc index b038764..b2875bc 100644 --- a/doc/src/manual/cowboy_req.asciidoc +++ b/doc/src/manual/cowboy_req.asciidoc @@ -80,6 +80,7 @@ Response: * link:man:cowboy_req:delete_resp_header(3)[cowboy_req:delete_resp_header(3)] - Delete a response header * link:man:cowboy_req:set_resp_body(3)[cowboy_req:set_resp_body(3)] - Set the response body * link:man:cowboy_req:has_resp_body(3)[cowboy_req:has_resp_body(3)] - Is there a response body? +* link:man:cowboy_req:inform(3)[cowboy_req:inform(3)] - Send an informational response * link:man:cowboy_req:reply(3)[cowboy_req:reply(3)] - Send the response * link:man:cowboy_req:stream_reply(3)[cowboy_req:stream_reply(3)] - Send the response headers * link:man:cowboy_req:stream_body(3)[cowboy_req:stream_body(3)] - Stream the response body diff --git a/doc/src/manual/cowboy_req.inform.asciidoc b/doc/src/manual/cowboy_req.inform.asciidoc new file mode 100644 index 0000000..d4421ba --- /dev/null +++ b/doc/src/manual/cowboy_req.inform.asciidoc @@ -0,0 +1,83 @@ += cowboy_req:inform(3) + +== Name + +cowboy_req:inform - Send an informational response + +== Description + +[source,erlang] +---- +inform(Status, Req :: cowboy_req:req()) + -> inform(StatusCode, #{}, Req) + +inform(Status, Headers, Req :: cowboy_req:req()) + -> ok + +Status :: cowboy:http_status() +Headers :: cowboy:http_headers() +---- + +Send an informational response. + +Informational responses use a status code between 100 and 199. +They cannot include a body. This function will not use any +of the previously set headers. All headers to be sent must +be given directly. + +Any number of informational responses can be sent as long as +they are sent before the proper response. Attempting to use +this function after sending a normal response will result +in an error. + +The header names must be given as lowercase binary strings. +While header names are case insensitive, Cowboy requires them +to be given as lowercase to function properly. + +== Arguments + +Status:: + +The status code for the response. + +Headers:: + +The response headers. + +Header names must be given as lowercase binary strings. + +Req:: + +The Req object. + +== Return value + +The atom `ok` is always returned. It can be safely ignored. + +== Changelog + +* *2.0*: Function introduced. + +== Examples + +.Send an informational response +[source,erlang] +---- +Req = cowboy_req:inform(102, Req0). +---- + +.Send an informational response with headers +[source,erlang] +---- +Req = cowboy_req:inform(103, #{ + <<"link">> => <<"; rel=preload; as=style">>, + <<"link">> => <<"; rel=preload; as=script">> +}, Req0). +---- + +== See also + +link:man:cowboy_req(3)[cowboy_req(3)], +link:man:cowboy_req:reply(3)[cowboy_req:reply(3)], +link:man:cowboy_req:stream_reply(3)[cowboy_req:stream_reply(3)], +link:man:cowboy_req:push(3)[cowboy_req:push(3)] diff --git a/doc/src/manual/cowboy_req.push.asciidoc b/doc/src/manual/cowboy_req.push.asciidoc index 200561f..5a3509f 100644 --- a/doc/src/manual/cowboy_req.push.asciidoc +++ b/doc/src/manual/cowboy_req.push.asciidoc @@ -94,5 +94,6 @@ cowboy_req:push("/static/style.css", #{ == See also link:man:cowboy_req(3)[cowboy_req(3)], +link:man:cowboy_req:inform(3)[cowboy_req:inform(3)], link:man:cowboy_req:reply(3)[cowboy_req:reply(3)], link:man:cowboy_req:stream_reply(3)[cowboy_req:stream_reply(3)] diff --git a/doc/src/manual/cowboy_req.reply.asciidoc b/doc/src/manual/cowboy_req.reply.asciidoc index 37e32c9..7da306b 100644 --- a/doc/src/manual/cowboy_req.reply.asciidoc +++ b/doc/src/manual/cowboy_req.reply.asciidoc @@ -113,5 +113,6 @@ link:man:cowboy_req:set_resp_cookie(3)[cowboy_req:set_resp_cookie(3)], link:man:cowboy_req:set_resp_header(3)[cowboy_req:set_resp_header(3)], link:man:cowboy_req:set_resp_headers(3)[cowboy_req:set_resp_headers(3)], link:man:cowboy_req:set_resp_body(3)[cowboy_req:set_resp_body(3)], +link:man:cowboy_req:inform(3)[cowboy_req:inform(3)], link:man:cowboy_req:stream_reply(3)[cowboy_req:stream_reply(3)], link:man:cowboy_req:push(3)[cowboy_req:push(3)] diff --git a/doc/src/manual/cowboy_req.stream_reply.asciidoc b/doc/src/manual/cowboy_req.stream_reply.asciidoc index 8c4a7ae..19d46ca 100644 --- a/doc/src/manual/cowboy_req.stream_reply.asciidoc +++ b/doc/src/manual/cowboy_req.stream_reply.asciidoc @@ -103,6 +103,7 @@ link:man:cowboy_req(3)[cowboy_req(3)], link:man:cowboy_req:set_resp_cookie(3)[cowboy_req:set_resp_cookie(3)], link:man:cowboy_req:set_resp_header(3)[cowboy_req:set_resp_header(3)], link:man:cowboy_req:set_resp_headers(3)[cowboy_req:set_resp_headers(3)], +link:man:cowboy_req:inform(3)[cowboy_req:inform(3)], link:man:cowboy_req:reply(3)[cowboy_req:reply(3)], link:man:cowboy_req:stream_body(3)[cowboy_req:stream_body(3)], link:man:cowboy_req:push(3)[cowboy_req:push(3)] -- cgit v1.2.3