0e0f2b52.1460c938.js

(window.webpackJsonp=window.webpackJsonp||[]).push([[3],{52:function(e,t,n){"use strict";n.r(t),n.d(t,"frontMatter",(function(){return o})),n.d(t,"metadata",(function(){return r})),n.d(t,"rightToc",(function(){return c})),n.d(t,"default",(function(){return d}));var a=n(2),s=n(6),i=(n(0),n(73)),o={id:"guide-http-handler",title:"Http Response",sidebar_label:"Http Response"},r={unversionedId:"guide-http-handler",id:"guide-http-handler",isDocsHomePage:!1,title:"Http Response",description:"Sending a response",source:"@site/docs/guide-http-handler.md",permalink:"/pistache.github.io/docs/guide-http-handler",editUrl:"https://github.com/facebook/docusaurus/edit/master/website/docs/guide-http-handler.md",sidebar_label:"Http Response",sidebar:"someSidebar",previous:{title:"Hello World",permalink:"/pistache.github.io/docs/getting-started-hello-world"},next:{title:"Namespace",permalink:"/pistache.github.io/docs/namespace"}},c=[],p={rightToc:c};function d(e){var t=e.components,n=Object(s.a)(e,["components"]);return Object(i.b)("wrapper",Object(a.a)({},p,n,{components:t,mdxType:"MDXLayout"}),Object(i.b)("h1",{id:"sending-a-response"},"Sending a response"),Object(i.b)("p",null,Object(i.b)("inlineCode",{parentName:"p"},"ResponseWriter")," is an object from which the final http response is sent to the client.\nThe ",Object(i.b)("inlineCode",{parentName:"p"},"onRequest()")," function does not return anything.\nInstead, the response is sent through the ",Object(i.b)("inlineCode",{parentName:"p"},"ResponseWriter")," class.\nThis class provides a bunch of ",Object(i.b)("inlineCode",{parentName:"p"},"send()")," function overloads to send the response:"),Object(i.b)("pre",null,Object(i.b)("code",Object(a.a)({parentName:"pre"},{className:"language-cpp"}),"Async::Promise<ssize_t> send(Code code);\n")),Object(i.b)("p",null,"You can use this overload to send a response with an empty body and a given HTTP Code (e.g ",Object(i.b)("inlineCode",{parentName:"p"},"Http::Code::Ok"),")"),Object(i.b)("pre",null,Object(i.b)("code",Object(a.a)({parentName:"pre"},{className:"language-cpp"}),"Async::Promise<ssize_t> send(Code code, const std::string& body, const Mime::MediaType &mime = Mime::MediaType());\n")),Object(i.b)("p",null,"This overload can be used to send a response with static, fixed-size content (body).\nA MIME type can also be specified, which will be sent through the ",Object(i.b)("inlineCode",{parentName:"p"},"Content-Type")," header."),Object(i.b)("pre",null,Object(i.b)("code",Object(a.a)({parentName:"pre"},{className:"language-cpp"}),"template<size_t N>\nAsync::Promise<ssize_t> send(Code code, const char (&arr)[N], const Mime::MediaType& mime = Mime::MediaType());\n")),Object(i.b)("p",null,"This version can also be used to send a fixed-size response with a body except that it does not need to construct a string (no memory is allocated). The size of the content is directly deduced by the compiler. This version only works with raw string literals."),Object(i.b)("p",null,"These functions are asynchronous, meaning that they do not return a plain old ",Object(i.b)("inlineCode",{parentName:"p"},"ssize_t")," value indicating the number of bytes being sent,\nbut instead a ",Object(i.b)("inlineCode",{parentName:"p"},"Promise")," that will be fulfilled later on."),Object(i.b)("p",null,"See the next section for more details on asynchronous programming with Pistache."),Object(i.b)("h1",{id:"response-streaming"},"Response streaming"),Object(i.b)("p",null,"Sometimes, content that is to be sent back to the user can not be known in advance, thus the length can not be determined in advance."),Object(i.b)("p",null,"For that matter, the HTTP specification defines a special data-transfer mechanism called ",Object(i.b)("a",Object(a.a)({parentName:"p"},{href:"http://tools.ietf.org/html/rfc7230#section-4.1"}),"chunked encoding"),"\nwhere data is sent in a series of chunks.\nThis mechanism uses the ",Object(i.b)("inlineCode",{parentName:"p"},"Transfer-Encoding")," HTTP header in place of the Content-Length one."),Object(i.b)("p",null,"To stream content, Pistache provides a special ",Object(i.b)("inlineCode",{parentName:"p"},"ResponseStream")," class. To get a ",Object(i.b)("inlineCode",{parentName:"p"},"ResponseStream")," from a ",Object(i.b)("inlineCode",{parentName:"p"},"ResponseWriter"),", call the ",Object(i.b)("inlineCode",{parentName:"p"},"stream()")," member function:"),Object(i.b)("pre",null,Object(i.b)("code",Object(a.a)({parentName:"pre"},{className:"language-cpp"}),"auto stream = response.stream(Http::Code::Ok);\n")),Object(i.b)("p",null,"To initate a stream, you have to pass the HTTP status code to the stream function (here ",Object(i.b)("inlineCode",{parentName:"p"},"Http::Code::Ok")," or HTTP 200).\nThe ",Object(i.b)("inlineCode",{parentName:"p"},"ResponseStream")," class provides an iostream like interface that overloads the ",Object(i.b)("inlineCode",{parentName:"p"},"<<")," operator."),Object(i.b)("pre",null,Object(i.b)("code",Object(a.a)({parentName:"pre"},{className:"language-cpp"}),'stream << "PO"\nstream << "NG"\n')),Object(i.b)("p",null,'The first line will write a chunk of size 2 with the content "PO" to the stream\u2019s buffer.\nThe second line will write a second chunk of size 2 with the content "NG".\nTo end the stream and flush the content, use the special ',Object(i.b)("inlineCode",{parentName:"p"},"ends")," marker:"),Object(i.b)("pre",null,Object(i.b)("code",Object(a.a)({parentName:"pre"},{className:"language-cpp"}),"stream << ends\n")),Object(i.b)("p",null,"The ",Object(i.b)("inlineCode",{parentName:"p"},"ends")," marker will write the last chunk of size 0 and send the final data over the network.\nTo simply flush the stream\u2019s buffer without ending the stream, you can use the ",Object(i.b)("inlineCode",{parentName:"p"},"flush")," marker:"),Object(i.b)("pre",null,Object(i.b)("code",Object(a.a)({parentName:"pre"},{className:"language-cpp"}),"stream << flush\n")),Object(i.b)("div",{className:"admonition admonition-caution alert alert--warning"},Object(i.b)("div",Object(a.a)({parentName:"div"},{className:"admonition-heading"}),Object(i.b)("h5",{parentName:"div"},Object(i.b)("span",Object(a.a)({parentName:"h5"},{className:"admonition-icon"}),Object(i.b)("svg",Object(a.a)({parentName:"span"},{xmlns:"http://www.w3.org/2000/svg",width:"16",height:"16",viewBox:"0 0 16 16"}),Object(i.b)("path",Object(a.a)({parentName:"svg"},{fillRule:"evenodd",d:"M8.893 1.5c-.183-.31-.52-.5-.887-.5s-.703.19-.886.5L.138 13.499a.98.98 0 0 0 0 1.001c.193.31.53.501.886.501h13.964c.367 0 .704-.19.877-.5a1.03 1.03 0 0 0 .01-1.002L8.893 1.5zm.133 11.497H6.987v-2.003h2.039v2.003zm0-3.004H6.987V5.987h2.039v4.006z"})))),"HTTP headers")),Object(i.b)("div",Object(a.a)({parentName:"div"},{className:"admonition-content"}),Object(i.b)("p",{parentName:"div"},"After starting a stream, headers become immutable. They must be written to the response before creating a ",Object(i.b)("inlineCode",{parentName:"p"},"ResponseStream"),":"),Object(i.b)("pre",{parentName:"div"},Object(i.b)("code",Object(a.a)({parentName:"pre"},{className:"language-cpp"}),'response.headers()\n    .add<Header::Server>("lys")\n    .add<Header::ContentType>(MIME(Text, Plain));\n\nauto stream = response.stream();\nstream << "PO" << "NG" << ends;\n')))))}d.isMDXComponent=!0}}]);