fastly::http::Response Class Reference

#include <response.h>

Public Member Functions
	Response ()
bool	is_from_backend ()
	Return whether the response is from a backend request.
Response	clone_without_body ()
Response	clone_with_body ()
Response	with_body (Body body) &&
	Builder-style equivalent of Response::set_body().
bool	has_body ()
	Returns true if this response has a body.
void	set_body (Body body)
	Set the given value as the response's body.
Body	take_body ()
void	append_body (Body body)
std::vector< uint8_t >	into_body_bytes ()
	Consume the response and return its body as a byte vector.
std::string	into_body_string ()
	Consume the response and return its body as a string.
Body	into_body ()
	Consume the response and return its body.
fastly::expected< Response >	with_body_text_plain (std::string_view body) &&
fastly::expected< void >	set_body_text_plain (std::string_view body)
fastly::expected< Response >	with_body_text_html (std::string_view body) &&
fastly::expected< void >	set_body_text_html (std::string_view body)
std::string	take_body_string ()
Response	with_body_octet_stream (std::vector< uint8_t > body) &&
void	set_body_octet_stream (std::vector< uint8_t > body)
std::vector< uint8_t >	take_body_bytes ()
std::optional< std::string >	get_content_type ()
Response	with_content_type (std::string_view mime) &&
void	set_content_type (std::string_view mime)
std::optional< size_t >	get_content_length ()
fastly::expected< bool >	contains_header (std::string_view name)
	Returns whether the given header name is present in the response.
fastly::expected< Response >	with_header (std::string_view name, std::string_view value) &&
	Builder-style equivalent of Response::append_header().
fastly::expected< Response >	with_set_header (std::string_view name, std::string_view value) &&
	Builder-style equivalent of Response::set_header().
fastly::expected< std::optional< HeaderValue > >	get_header (std::string_view name)
fastly::expected< HeaderValuesRange >	get_header_all (std::string_view name)
	Get an iterator of all the values of a header.
fastly::expected< HeadersRange >	get_headers ()
fastly::expected< HeaderNamesRange >	get_header_names ()
fastly::expected< void >	set_header (std::string_view name, std::string_view value)
fastly::expected< void >	append_header (std::string_view name, std::string_view value)
fastly::expected< std::optional< std::string > >	remove_header (std::string_view name)
Response	with_status (StatusCode status) &&
	Builder-style equivalent of Response::set_status().
void	set_status (StatusCode status)
Response	with_version (Version version) &&
	Builder-style equivalent of Response::set_version().
Version	get_version ()
	Get the HTTP version of this response.
void	set_version (Version version)
	Set the HTTP version of this response.
std::optional< std::string >	get_backend_name ()
std::optional< fastly::backend::Backend >	get_backend ()
std::optional< std::string >	get_backend_addr ()
std::optional< Request >	take_backend_request ()
void	send_to_client ()
StreamingBody	stream_to_client ()
std::optional< std::chrono::milliseconds >	get_ttl ()
std::optional< std::chrono::milliseconds >	get_age ()
std::optional< std::chrono::milliseconds >	get_stale_while_revalidate ()

Static Public Member Functions
static Response	from_body (Body body)
	Create a new Response with the given value as the body.
static Response	from_status (StatusCode status)
	Create a new response with the given status code.
static Response	see_other (std::string_view destination)
static Response	redirect (std::string_view destination)
static Response	temporary_redirect (std::string_view destination)

Friends
std::pair< fastly::expected< Response >, std::vector< request::PendingRequest > >	request::select (std::vector< request::PendingRequest > &reqs)

Detailed Description

An HTTP response, including body, headers, and status code.

Sending to the client

Each execution of a Compute program may send a single response back to the client:

• Response::send_to_client()
• Response::stream_to_client()

If no response is explicitly sent by the program, a default 200 OK response is sent.

Creation and conversion

Responses can be created programmatically:

• Response::new()
• Response::from_body()
• Response::from_status()

Responses are also returned from backend requests:

• Request::send()
• Request::send_async()
• Request::send_async_streaming()

Builder-style methods

Response can be used as a builder, allowing responses to be constructed and used through method chaining. Methods with the with_ name prefix, such as Response::with_header(), return std::move(*this) to allow chaining. The builder style is typically most useful when constructing and using a response in a single expression. For example:

Response()
    .with_header("my-header", "hello!")
    .with_header("my-other-header", "Здравствуйте!")
    .send_to_client();

Setter methods

Setter methods, such as Response::set_header(), are prefixed by set_, and can be used interchangeably with the builder-style methods, allowing you to mix and match styles based on what is most convenient for your program. Setter methods tend to work better than builder-style methods when constructing a value involves conditional branches or loops. For example:

auto resp{Response().with_header("my-header", "hello!")};
if (needs_translation) {
    resp.set_header("my-other-header", "Здравствуйте!");
}
resp.send_to_client();

Constructor & Destructor Documentation

Response()

fastly::http::Response::Response

(

)

Create a new Response.

The new response is created with status code 200 OK, no headers, and an empty body.

Member Function Documentation

append_body()

void fastly::http::Response::append_body

(

Body

body

)

Append another Body to the body of this response without reading or writing any body contents.

If this response does not have a body, the appended body is set as the response's body.

This method should be used when combining bodies that have not necessarily been read yet, such as a body returned from a backend response.

Examples

auto resp{Response::from_body("hello! backend says: ")};
auto backend_resp{
  Request::get("https://example.com/").send("example_backend")
};
resp.append_body(backend_resp.into_body());
resp.send_to_client();

append_header()

fastly::expected< void > fastly::http::Response::append_header	(	std::string_view	name,
		std::string_view	value )

Add a request header with given value.

Unlike Response::set_header(), this does not discard existing values for the same header name.

clone_with_body()

Response fastly::http::Response::clone_with_body

(

)

Clone this response by reading in its body, and then writing the same body to the original and the cloned response.

This method requires mutable access to this response because reading from and writing to the body can involve an HTTP connection.

clone_without_body()

Response fastly::http::Response::clone_without_body

(

)

Make a new response with the same headers, status, and version of this response, but no body.

If you also need to clone the response body, use Response::clone_with_body().

contains_header()

fastly::expected< bool > fastly::http::Response::contains_header

(

std::string_view

name

)

Returns whether the given header name is present in the response.

from_body()

Response fastly::http::Response::from_body ( Body body )

static

Create a new Response with the given value as the body.

from_status()

Response fastly::http::Response::from_status ( StatusCode status )

static

Create a new response with the given status code.

get_age()

std::optional< std::chrono::milliseconds > fastly::http::Response::get_age

(

)

The current age of the response, if it is cached.

Returns std::nullopt if the response is not cached.

get_backend()

std::optional< fastly::backend::Backend > fastly::http::Response::get_backend

(

)

Get the backend this response came from, or std::nullopt if the response is synthetic.

Examples

From a backend response:

auto backend_resp{
  Request::get("https://example.com/").send("example_backend")
};
assert(
  backend_resp.get_backend() ==
  std::optional(Backend::from_name("example_backend"))
);

From a synthetic response:

Response synthetic_resp;
assert(synthetic_resp.get_backend() == std::nullopt);

get_backend_addr()

std::optional< std::string > fastly::http::Response::get_backend_addr

(

)

Get the address of the backend this response came from, or std::nullopt when the response is synthetic or cached.

Examples

From a backend response:

auto backend_resp{Request::get("https://example.com/")
    .with_pass(true)
    .send("example_backend")};
assert(
   backend_resp.get_backend_addr() ==
   std::optional("127.0.0.1:443"));

From a synthetic response:

Response synthetic_resp;
assert(synthetic_resp.get_backend_addr() == std::nullopt);

get_backend_name()

std::optional< std::string > fastly::http::Response::get_backend_name

(

)

Get the name of the Backend this response came from, or std::nullopt if the response is synthetic.

Examples

From a backend response:

auto
backend_resp{Request::get("https://example.com/").send("example_backend")};
assert(backend_resp.get_backend_name(),
std::optional("example_backend"));

From a synthetic response:

Response synthetic_resp;
assert(synthetic_resp.get_backend_name() == std::nullopt);

get_content_length()

std::optional< size_t > fastly::http::Response::get_content_length

(

)

Get the value of the response's Content-Length header, if it exists.

get_content_type()

std::optional< std::string > fastly::http::Response::get_content_type

(

)

Get the MIME type described by the response's Content-Type header, or std::nullopt if that header is absent or contains an invalid MIME type.

get_header()

fastly::expected< std::optional< HeaderValue > > fastly::http::Response::get_header

(

std::string_view

name

)

Get the value of a header, or std::nullopt if the header is not present.

If there are multiple values for the header, only one is returned, which may be any of the values. See Response::get_header_all() all of the values.

get_header_all()

fastly::expected< HeaderValuesRange > fastly::http::Response::get_header_all

(

std::string_view

name

)

Get an iterator of all the values of a header.

get_header_names()

fastly::expected< HeaderNamesRange > fastly::http::Response::get_header_names

(

)

get_headers()

fastly::expected< HeadersRange > fastly::http::Response::get_headers

(

)

get_stale_while_revalidate()

std::optional< std::chrono::milliseconds > fastly::http::Response::get_stale_while_revalidate

(

)

The time for which the response can safely be used despite being considered stale, if it is cached.

Returns std::nullopt if the response is not cached.

get_ttl()

std::optional< std::chrono::milliseconds > fastly::http::Response::get_ttl

(

)

Get the Time to Live (TTL) in the cache for this response, if it is cached.

The TTL provides the duration of "freshness" for the cached response after it is inserted into the cache. If the response is stale, the TTL is 0 (i.e. this returns std::optional(0).

Returns std::nullopt if the response is not cached.

get_version()

Version fastly::http::Response::get_version

(

)

Get the HTTP version of this response.

has_body()

bool fastly::http::Response::has_body

(

)

Returns true if this response has a body.

into_body()

Body fastly::http::Response::into_body

(

)

Consume the response and return its body.

into_body_bytes()

std::vector< uint8_t > fastly::http::Response::into_body_bytes

(

)

Consume the response and return its body as a byte vector.

into_body_string()

std::string fastly::http::Response::into_body_string

(

)

Consume the response and return its body as a string.

is_from_backend()

bool fastly::http::Response::is_from_backend

(

)

Return whether the response is from a backend request.

redirect()

Response fastly::http::Response::redirect ( std::string_view destination )

static

Create a 308 Permanent Redirect response with the given value as the Location header.

Examples

auto resp{Response::redirect("https://www.fastly.com")};
assert(resp.get_status() == StatusCode::PERMANENT_REDIRECT);
assert(resp.get_header("Location").value(), "https://www.fastly.com");

remove_header()

fastly::expected< std::optional< std::string > > fastly::http::Response::remove_header

(

std::string_view

name

)

Remove all request headers of the given name, and return one of the removed header values if any were present.

see_other()

Response fastly::http::Response::see_other ( std::string_view destination )

static

Create a 303 See Other response with the given value as the Location header.

Examples

auto resp{Response::see_other("https://www.fastly.com")};
assert(resp.get_status() == StatusCode::SEE_OTHER);
assert(resp.get_header("Location").value(), "https://www.fastly.com");

send_to_client()

void fastly::http::Response::send_to_client

(

)

Begin sending the response to the client.

This method returns as soon as the response header begins sending to the client, and transmission of the response will continue in the background.

Once this method is called, nothing else may be added to the response body. To stream additional data to a response body after it begins to send, use Response::stream_to_client().

Panics

This method panics if another response has already been sent to the client by this method, by Response::stream_to_client().

Examples

Sending a backend response without modification:

Request::get("https://example.com/").send("example_backend").send_to_client();

Removing a header from a backend response before sending to the client:

auto
backend_resp{Request::get("https://example.com/").send("example_backend")};
backend_resp.remove_header("bad-header");
backend_resp.send_to_client();

Sending a synthetic response:

Response::from_body("hello, world!").send_to_client();

Examples

async_reqs.cpp, clock.cpp, config_store.cpp, device_detection.cpp, echo.cpp, ngwaf_inspect.cpp, random.cpp, robots.txt.cpp, router.cpp, and streaming_response.cpp.

set_body()

void fastly::http::Response::set_body

(

Body

body

)

Set the given value as the response's body.

set_body_octet_stream()

void fastly::http::Response::set_body_octet_stream

(

std::vector< uint8_t >

body

)

Set the given bytes as the response's body with content type application/octet-stream.

set_body_text_html()

fastly::expected< void > fastly::http::Response::set_body_text_html

(

std::string_view

body

)

Set the given string as the response's body with content type text/html; / charset=UTF-8.

set_body_text_plain()

fastly::expected< void > fastly::http::Response::set_body_text_plain

(

std::string_view

body

)

Set the given string as the response's body with content type text/plain; / charset=UTF-8.

set_content_type()

void fastly::http::Response::set_content_type

(

std::string_view

mime

)

Set the MIME type described by the response's Content-Type header.

Any existing Content-Type header values will be overwritten.

set_header()

fastly::expected< void > fastly::http::Response::set_header	(	std::string_view	name,
		std::string_view	value )

Set a response header to the given value, discarding any previous values for the given header name.

set_status()

void fastly::http::Response::set_status

(

StatusCode

status

)

Set the HTTP status code of the response.

Examples

Using the constants from StatusCode:

auto resp{fastly::Response::from_body("not found!")};
resp.set_status(fastly::http::StatusCode::NOT_FOUND);
resp.send_to_client();

Using a uint16_t:

auto resp{fastly::Response::from_body("not found!")};
resp.set_status(404);
resp.send_to_client();

set_version()

void fastly::http::Response::set_version

(

Version

version

)

Set the HTTP version of this response.

stream_to_client()

StreamingBody fastly::http::Response::stream_to_client

(

)

Begin sending the response to the client, and return a StreamingBody that can accept further data to send.

The client connection must be closed when finished writing the response by calling StreamingBody::finish().

This method is most useful for programs that do some sort of processing or inspection of a potentially-large backend response body. Streaming allows the program to operate on small parts of the body rather than having to read it all into memory at once.

This method returns as soon as the response header begins sending to the client, and transmission of the response will continue in the background.

Panics

This method panics if another response has already been sent to the client by this method, by Response::send_to_client().

Examples

Count the number of lines in a UTF-8 backend response body while sending it to the client:

auto backend_resp{
   Request::get("https://example.com/").send("example_backend")
};
 
// Take the body so we can iterate through its lines later
auto backend_resp_body{backend_resp.take_body()};
 
// Start sending the backend response to the client with a now-empty body
auto client_body{backend_resp.stream_to_client()};
 
size_t num_lines{0};
std::string line;
while (getline(backend_resp_body, line)) {
  num_lines++;
  client_body << line;
}
// Finish the streaming body to close the client connection.
client_body.finish();
 
std::cout
  << "backend response body contained "
  << num_lines
  << " lines"
  << std::endl;

take_backend_request()

std::optional< Request > fastly::http::Response::take_backend_request

(

)

Take and return the request this response came from, or std::nullopt if the response is synthetic.

Note that the returned request will only have the headers and metadata of the original request, as the body is consumed when sending the request.

Examples

From a backend response:

auto backend_resp{Request::post("https://example.com/")
    .with_body("hello")
    .send("example_backend")};
auto backend_req{backend_resp.take_backend_request().value()};
assert(backend_req.get_url() == "https://example.com/");
assert(!backend_req.has_body());
backend_req.with_body("goodbye").send("example_backend");

From a synthetic response:

Response synthetic_resp;
assert(synthetic_resp.take_backend_request() == std::nullopt);

take_body()

Body fastly::http::Response::take_body

(

)

Take and return the body from this response.

After calling this method, this response will no longer have a body.

take_body_bytes()

std::vector< uint8_t > fastly::http::Response::take_body_bytes

(

)

Take and return the body from this response as a vector of bytes.

After calling this method, this response will no longer have a body.

take_body_string()

std::string fastly::http::Response::take_body_string

(

)

Take and return the body from this response as a string.

After calling this method, this response will no longer have a body.

temporary_redirect()

Response fastly::http::Response::temporary_redirect ( std::string_view destination )

static

Create a 307 Temporary Redirect response with the given value as the Location header.

Examples

auto resp{Response::temporary_redirect("https://www.fastly.com")};
assert(resp.get_status() == StatusCode::TEMPORARY_REDIRECT);
assert(resp.get_header("Location").value(), "https://www.fastly.com");

with_body()

Response fastly::http::Response::with_body

(

Body

body

)

&&

Builder-style equivalent of Response::set_body().

Examples

router.cpp.

with_body_octet_stream()

Response fastly::http::Response::with_body_octet_stream

(

std::vector< uint8_t >

body

)

&&

Builder-style equivalent of Response::set_body_octet_stream().

with_body_text_html()

fastly::expected< Response > fastly::http::Response::with_body_text_html

(

std::string_view

body

)

&&

Builder-style equivalent of Response::set_body_text_html().

with_body_text_plain()

fastly::expected< Response > fastly::http::Response::with_body_text_plain

(

std::string_view

body

)

&&

Builder-style equivalent of Response::set_body_text_plain().

with_content_type()

Response fastly::http::Response::with_content_type

(

std::string_view

mime

)

&&

Builder-style equivalent of Response::set_content_type().

with_header()

fastly::expected< Response > fastly::http::Response::with_header	(	std::string_view	name,
		std::string_view	value ) &&

Builder-style equivalent of Response::append_header().

with_set_header()

fastly::expected< Response > fastly::http::Response::with_set_header	(	std::string_view	name,
		std::string_view	value ) &&

Builder-style equivalent of Response::set_header().

with_status()

Response fastly::http::Response::with_status

(

StatusCode

status

)

&&

Builder-style equivalent of Response::set_status().

Examples

robots.txt.cpp.

with_version()

Response fastly::http::Response::with_version

(

Version

version

)

&&

Builder-style equivalent of Response::set_version().

Friends And Related Symbol Documentation

request::select

std::pair< fastly::expected< Response >, std::vector< request::PendingRequest > > request::select ( std::vector< request::PendingRequest > & reqs )

friend

---

The documentation for this class was generated from the following file:

• include/fastly/http/response.h