1. Home
  2. Reference documentation
  3. Compute
  4. Language SDKs
  5. C++
  6. fastly
  7. http

Request

Classin httpcompute-sdk-cpp 0.7.0View source

Include fastly/http/request.h to use this class.

An HTTP request, including body, headers, method, and URL.

Getting the client request

Call Request::from_client() to get the client request being handled by this execution of the Compute program.

Creation and conversion

New requests can be created programmatically with the Request() constructor. In addition, there are convenience constructors like Request::get() which automatically select the appropriate method.

Sending backend requests

Requests can be sent to a backend in blocking or asynchronous fashion using Request::send(), Request::send_async(), or Request::send_async_streaming().

Builder-style methods

Request can be used as a builder allowing requests to be constructed and used through method chaining. Methods with the with_ name prefix, such as Request::with_header(), return a moved Request to allow chaining. The builder style is typically most useful when constructing and using a request in a single expression.

For example:

Setter methods

Setter methods, such as Request::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 request involves conditional branches or loops.

For example:

Request::get("https://example.com")
    .with_header("my-header", "hello!")
    .with_header("my-other-header", "Здравствуйте!")
    .send("example_backend");
auto req{Request::get("https://example.com").with_header("my-header",
"hello!")};
if (needs_translation) {
    req.set_header("my-other-header", "Здравствуйте!");
}
req.send("example_backend");

Constructor

View source
fastly::http::Request::Request(Method method, std::string_view url)

Create a new request with the given method and URL, no headers, and an empty body.

Parameters

method: Method
url: std::string_view

Methods

append_body

View source
void fastly::http::Request::append_body(Body &body)

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

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

This method should be used when combining bodies that have not necessarily been read yet, such as the body of the client. To append contents that are already in memory as strings or bytes, you should instead use get_body_mut() to write the contents to the end of the body.

Examples

Parameters

body: Body &

Returns

void
auto req{Request::post("https://example.com").with_body("hello! client
says: ")}; req.append_body(Request::from_client().into_body());
req.send("example_backend");

append_header

View source
fastly::expected<void> fastly::http::Request::append_header(std::string_view name, std::string_view value)

Add a request header with given value.

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

Parameters

name: std::string_view
value: std::string_view

Returns

fastly::expected<void>

clone_with_body

View source
Request fastly::http::Request::clone_with_body()

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

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

Returns

Request

clone_without_body

View source
Request fastly::http::Request::clone_without_body()

Make a new request with the same method, url, headers, and version of this request, but no body.

If you also need to clone the request body, use clone_with_body()

Examples

Returns

Request
1
2
3
4
5
6
7
8
9
auto original = Request::post("https://example.com")
    .with_header("hello", "world!")
    .with_body("hello");
auto new_req = original.clone_without_body();
assert(original.get_method() == new.get_method());
assert(original.get_url() == new.get_url());
assert(original.get_header("hello") == new.get_header("hello"));
assert(original.has_body());
assert(!new.has_body());

connect

staticView source
static Request fastly::http::Request::connect(std::string_view url)

Create a new CONNECT Request with the given URL, no headers, and an empty body.

Parameters

url: std::string_view

Returns

Request

contains_header

View source
fastly::expected<bool> fastly::http::Request::contains_header(std::string_view name)

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

Parameters

name: std::string_view

Returns

fastly::expected<bool>

delete_

staticView source
static Request fastly::http::Request::delete_(std::string_view url)

Create a new DELETE Request with the given URL, no headers, and an empty body.

Parameters

url: std::string_view

Returns

Request

fastly_key_is_valid

View source
bool fastly::http::Request::fastly_key_is_valid()

Returns whether or not the client request had a Fastly-Key header which is valid for purging content for the service.

This function ignores the current value of any Fastly-Key header for this request.

Returns

bool

from_client

staticView source
static Request fastly::http::Request::from_client()

Get the client request being handled by this execution of the Compute program.

Panics

This method panics if the client request has already been retrieved by this method or by the low-level handle API.

Returns

Request

get

staticView source
static Request fastly::http::Request::get(std::string_view url)

Create a new GET Request with the given URL, no headers, and an empty body.

Parameters

url: std::string_view

Returns

Request

get_client_ddos_detected

View source
std::optional<bool> fastly::http::Request::get_client_ddos_detected()

Returns whether the request was tagged as contributing to a DDoS attack

Returns std::nullopt if this is not the client request.

Returns

std::optional<bool>

get_client_ip_addr

View source
std::optional<std::string> fastly::http::Request::get_client_ip_addr()

Returns

std::optional<std::string>

get_content_length

View source
std::optional<size_t> fastly::http::Request::get_content_length()

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

Returns

std::optional<size_t>

get_content_type

View source
std::optional<std::string> fastly::http::Request::get_content_type()

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

Returns

std::optional<std::string>

get_header

View source
fastly::expected<std::optional<HeaderValue>> fastly::http::Request::get_header(std::string_view name)

Get the value of a header as a string, 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 Request::get_header_all() all of the values.

Parameters

name: std::string_view

Returns

fastly::expected<std::optional<HeaderValue>>

get_header_all

View source
fastly::expected<HeaderValuesRange> fastly::http::Request::get_header_all(std::string_view name)

Get an iterator of all the values of a header.

Parameters

name: std::string_view

Returns

fastly::expected<HeaderValuesRange>

get_header_names

View source
fastly::expected<HeaderNamesRange> fastly::http::Request::get_header_names()

Returns

fastly::expected<HeaderNamesRange>

get_headers

View source
fastly::expected<HeadersRange> fastly::http::Request::get_headers()

Returns

fastly::expected<HeadersRange>

get_method

View source
Method fastly::http::Request::get_method()

Get the request method.

Returns

Method

get_original_header_count

View source
std::optional<uint32_t> fastly::http::Request::get_original_header_count()

Returns

std::optional<uint32_t>

get_original_header_names

View source
std::optional<OriginalHeaderNamesRange> fastly::http::Request::get_original_header_names()

Returns

std::optional<OriginalHeaderNamesRange>

get_path

View source
std::string fastly::http::Request::get_path()

Get the path component of the request URL.

Examples

Returns

std::string
auto req{Request::get("https://example.com/hello#world")};
assert(req.get_path() == "/hello");

get_query_parameter

View source
std::optional<std::string> fastly::http::Request::get_query_parameter(std::string_view param)

Get the value of a query parameter in the request's URL.

This assumes that the query string is a & separated list of parameter=value pairs. The value of the first occurrence of parameter is returned. No URL decoding is performed.

Parameters

param: std::string_view

Returns

std::optional<std::string>

get_query_string

View source
std::optional<std::string> fastly::http::Request::get_query_string()

Get the query component of the request URL, if it exists, as a percent-encoded ASCII string.

Returns

std::optional<std::string>

get_server_ip_addr

View source
std::optional<std::string> fastly::http::Request::get_server_ip_addr()

Returns

std::optional<std::string>

get_url

View source
std::string fastly::http::Request::get_url()

Get the request URL as a string.

Returns

std::string

get_version

View source
Version fastly::http::Request::get_version()

Get the HTTP version of this request.

Returns

Version

has_body

View source
bool fastly::http::Request::has_body()

Returns true if this request has a body.

Returns

bool

head

staticView source
static Request fastly::http::Request::head(std::string_view url)

Create a new HEAD Request with the given URL, no headers, and an empty body.

Parameters

url: std::string_view

Returns

Request

into_body

View source
Body fastly::http::Request::into_body()

Consume the request and return its body as a Body instance.

Returns

Body

into_body_bytes

View source
std::vector<uint8_t> fastly::http::Request::into_body_bytes()

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

Returns

std::vector<uint8_t>

into_body_string

View source
std::string fastly::http::Request::into_body_string()

Consume the request and return its body as a string.

Returns

std::string

is_cacheable

View source
bool fastly::http::Request::is_cacheable()

Gets whether the request is potentially cacheable.

Returns

bool

is_from_client

View source
bool fastly::http::Request::is_from_client()

Return true if this request is from the client of this execution of the Compute program.

Returns

bool

options

staticView source
static Request fastly::http::Request::options(std::string_view url)

Create a new OPTIONS Request with the given URL, no headers, and an empty body.

Parameters

url: std::string_view

Returns

Request

patch

staticView source
static Request fastly::http::Request::patch(std::string_view url)

Create a new PATCH Request with the given URL, no headers, and an empty body.

Parameters

url: std::string_view

Returns

Request

post

staticView source
static Request fastly::http::Request::post(std::string_view url)

Create a new POST Request with the given URL, no headers, and an empty body.

Parameters

url: std::string_view

Returns

Request

put

staticView source
static Request fastly::http::Request::put(std::string_view url)

Create a new PUT Request with the given URL, no headers, and an empty body.

Parameters

url: std::string_view

Returns

Request

remove_header

View source
fastly::expected<std::optional<std::string>> fastly::http::Request::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.

Parameters

name: std::string_view

Returns

fastly::expected<std::optional<std::string>>

remove_query

View source
void fastly::http::Request::remove_query()

Remove the query component from the request URL, if one exists.

Returns

void

send

Overload 1 of 2

fastly::expected<Response> fastly::http::Request::send(fastly::backend::Backend &backend)
View source

Retrieve a reponse for the request, either from cache or by sending it to the given backend server. Returns once the response headers have been received, or an error occurs.

Examples

Sending the client request to a backend without modification:

Sending a synthetic request:

Parameters

backend: fastly::backend::Backend &

Returns

fastly::expected<Response>
auto backend_resp{Request::from_client().send("example_backend")};
assert(backend_resp.get_status().is_success());
auto
backend_resp{Request::get("https://example.com").send("example_backend")};
assert(backend_resp.get_status().is_success());

Overload 2 of 2

fastly::expected<Response> fastly::http::Request::send(std::string_view backend_name)
View source

Parameters

backend_name: std::string_view

Returns

fastly::expected<Response>

send_async

Overload 1 of 2

fastly::expected<request::PendingRequest> fastly::http::Request::send_async(fastly::backend::Backend &backend)
View source

Begin sending the request to the given backend server, and return a PendingRequest that can yield the backend response or an error.

This method returns as soon as the request begins sending to the backend, and transmission of the request body and headers will continue in the background.

This method allows for sending more than one request at once and receiving their responses in arbitrary orders. See PendingRequest for more details on how to wait on, poll, or select between pending requests.

This method is also useful for sending requests where the response is unimportant, but the request may take longer than the Compute program is able to run, as the request will continue sending even after the program that initiated it exits.

Examples

Sending a request to two backends and returning whichever response finishes first:

Sending a long-running request and ignoring its result so that the program can exit before it completes:

Parameters

backend: fastly::backend::Backend &

Returns

fastly::expected<request::PendingRequest>
auto backend_resp_1{Request::get("https://example.com/")
    .send_async("example_backend_1")};
auto backend_resp_2{Request::get("https://example.com/")
    .send_async("example_backend_2")};
auto [selected_resp, _others] =
fastly::http::request::select({backend_resp_1, backend_resp_2});
selected_resp.send_to_client();
Request::post("https://example.com")
    .with_body(some_large_file)
    .send_async("example_backend");

Overload 2 of 2

fastly::expected<request::PendingRequest> fastly::http::Request::send_async(std::string_view backend_name)
View source

Parameters

backend_name: std::string_view

Returns

fastly::expected<request::PendingRequest>

send_async_streaming

Overload 1 of 2

fastly::expected<std::pair<StreamingBody, request::PendingRequest>> fastly::http::Request::send_async_streaming(fastly::backend::Backend &backend)
View source

Begin sending the request to the given backend server, and return a PendingRequest that can yield the backend response or an error along with a StreamingBody that can accept further data to send.

The backend connection is only closed once StreamingBody::finish() is called. The PendingRequest will not yield a Response until the StreamingBody is finished.

This method is most useful for programs that do some sort of processing or inspection of a potentially-large client request 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 request begins sending to the backend, and transmission of the request body and headers will continue in the background.

Examples

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

Parameters

backend: fastly::backend::Backend &

Returns

fastly::expected<std::pair<StreamingBody, request::PendingRequest>>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
auto req{Request::from_client()};
// Take the body so we can iterate through its lines later
auto req_body{req.take_body()};
// Start sending the client request to the client with a now-empty body
auto [backend_body, pending_req] = req
    .send_async_streaming("example_backend");


size_t num_lines{0};
std::string buf;
while (std::getline(req_body, buf)) {
  num_lines++;
  // Write the line to the streaming backend body
  backend_body << buf << "\n" << std::flush;
}
// Finish the streaming body to allow the backend connection to close
backend_body.finish();


std::cout
  << "client request body contained "
  << num_lines
  << " lines"
  << std::endl;

Overload 2 of 2

fastly::expected<std::pair<StreamingBody, request::PendingRequest>> fastly::http::Request::send_async_streaming(std::string_view backend_name)
View source

Parameters

backend_name: std::string_view

Returns

fastly::expected<std::pair<StreamingBody, request::PendingRequest>>

set_auto_decompress_gzip

View source
void fastly::http::Request::set_auto_decompress_gzip(bool gzip)

Set whether a gzip-encoded response to this request will be automatically decompressed.

Enabling this will set the Accept-Encoding header before the request is sent, regardless of the original value in the request, to ensure that any values originally sent by a browser or other client get replaced with gzip, so that the backend will not try sending unsupported compression algorithms.

If the response to this request is gzip-encoded, it will be presented in decompressed form, and the Content-Encoding and Content-Length headers will be removed.

Parameters

gzip: bool

Returns

void

set_body

View source
void fastly::http::Request::set_body(Body body)

Set the given value as the request's body.

Parameters

body: Body

Returns

void

set_body_octet_stream

View source
void fastly::http::Request::set_body_octet_stream(std::vector<uint8_t> body)

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

Parameters

body: std::vector<uint8_t>

Returns

void

set_body_text_html

View source
fastly::expected<void> fastly::http::Request::set_body_text_html(std::string_view body)

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

Parameters

body: std::string_view

Returns

fastly::expected<void>

set_body_text_plain

View source
fastly::expected<void> fastly::http::Request::set_body_text_plain(std::string_view body)

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

Parameters

body: std::string_view

Returns

fastly::expected<void>

set_cache_key

Overload 1 of 2

void fastly::http::Request::set_cache_key(std::string_view key)
View source

Set the cache key to be used when attempting to satisfy this request from a cached response.

Parameters

key: std::string_view

Returns

void

Overload 2 of 2

void fastly::http::Request::set_cache_key(std::vector<uint8_t> key)
View source

Set the cache key to be used when attempting to satisfy this request from a cached response.

Parameters

key: std::vector<uint8_t>

Returns

void

set_content_type

View source
void fastly::http::Request::set_content_type(std::string_view mime)

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

Any existing Content-Type header values will be overwritten.

Parameters

mime: std::string_view

Returns

void

set_header

View source
fastly::expected<void> fastly::http::Request::set_header(std::string_view name, std::string_view value)

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

Parameters

name: std::string_view
value: std::string_view

Returns

fastly::expected<void>

set_method

View source
void fastly::http::Request::set_method(Method method)

Set the request method.

Parameters

method: Method

Returns

void

set_pass

View source
void fastly::http::Request::set_pass(bool pass)

Set whether this request should be cached if sent to a backend.

By default this is false, which means the backend will only be reached if a cached response is not available. Set this to true to send the request directly to the backend without caching.

Overrides

Setting this to true overrides any other custom caching behaviors for this request, such as Request::set_ttl() or Request::set_surrogate_key().

Parameters

pass: bool

Returns

void

set_path

View source
fastly::expected<void> fastly::http::Request::set_path(std::string_view path)

Set the path component of the request URL.

Examples

Parameters

path: std::string_view

Returns

fastly::expected<void>
auto req{Request::get("https://example.com/")};
req.set_path("/hello");
assert!(req.get_url(), "https://example.com/hello");

set_pci

View source
void fastly::http::Request::set_pci(bool pci)

Override the caching behavior of this request to enable or disable PCI/HIPAA-compliant non-volatile caching.

By default, this is false, which means the request may not be PCI/HIPAA-compliant. Set it to true to enable compliant caching.

See the Fastly PCI-Compliant Caching and Delivery documentation for details.

Overrides

This sets the Request::set_pass() behavior to false.

Parameters

pci: bool

Returns

void

set_query_string

View source
fastly::expected<void> fastly::http::Request::set_query_string(std::string_view query)

Set the query string of the request URL query component to the given string, performing percent-encoding if necessary.

Examples

Parameters

query: std::string_view

Returns

fastly::expected<void>
_run
auto req{Request::get("https://example.com/foo")};
req.set_query_string("hello=🌐!&bar=baz");
assert(req.get_url(),
"https://example.com/foo?hello=%F0%9F%8C%90!&bar=baz");

set_stale_while_revalidate

View source
void fastly::http::Request::set_stale_while_revalidate(uint32_t swr)

Override the caching behavior of this request to use the given stale-while-revalidate time, in seconds.

Overrides

This overrides the behavior specified in the response headers, and sets the Request::set_pass() behavior to false.

Parameters

swr: uint32_t

Returns

void

set_surrogate_key

View source
fastly::expected<void> fastly::http::Request::set_surrogate_key(std::string_view sk)

Override the caching behavior of this request to include the given surrogate key(s), provided as a header value.

The header value can contain more than one surrogate key, separated by spaces.

Surrogate keys must contain only printable ASCII characters (those between 0x21 and 0x7E, inclusive). Any invalid keys will be ignored.

See the Fastly surrogate keys guide for details.

Overrides

This sets the Request::set_pass() behavior to false, and extends (but does not replace) any Surrogate-Key response headers from the backend.

Parameters

sk: std::string_view

Returns

fastly::expected<void>

set_ttl

View source
void fastly::http::Request::set_ttl(uint32_t ttl)

Override the caching behavior of this request to use the given Time to Live (TTL), in seconds.

Overrides

This overrides the behavior specified in the response headers, and sets the Request::set_pass() behavior to false.

Parameters

ttl: uint32_t

Returns

void

set_url

View source
fastly::expected<void> fastly::http::Request::set_url(std::string_view url)

Set the request URL.

Parameters

url: std::string_view

Returns

fastly::expected<void>

set_version

View source
void fastly::http::Request::set_version(Version version)

Set the HTTP version of this request.

Parameters

version: Version

Returns

void

take_body

View source
Body fastly::http::Request::take_body()

Take and return the body from this request.

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

Returns

Body

take_body_bytes

View source
std::vector<uint8_t> fastly::http::Request::take_body_bytes()

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

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

Returns

std::vector<uint8_t>

take_body_string

View source
std::string fastly::http::Request::take_body_string()

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

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

Returns

std::string

trace

staticView source
static Request fastly::http::Request::trace(std::string_view url)

Create a new TRACE Request with the given URL, no headers, and an empty body.

Parameters

url: std::string_view

Returns

Request

with_auto_decompress_gzip

View source
Request fastly::http::Request::with_auto_decompress_gzip(bool gzip) &&

Builder-style equivalent of Request::set_auto_decompress_gzip().

Parameters

gzip: bool

Returns

Request

with_body

View source
Request fastly::http::Request::with_body(Body body) &&

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

Parameters

body: Body

Returns

Request

with_body_octet_stream

View source
Request fastly::http::Request::with_body_octet_stream(std::vector<uint8_t> body) &&

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

Parameters

body: std::vector<uint8_t>

Returns

Request

with_body_text_html

View source
fastly::expected<Request> fastly::http::Request::with_body_text_html(std::string_view body) &&

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

Parameters

body: std::string_view

Returns

fastly::expected<Request>

with_body_text_plain

View source
fastly::expected<Request> fastly::http::Request::with_body_text_plain(std::string_view body) &&

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

Parameters

body: std::string_view

Returns

fastly::expected<Request>

with_cache_key

Overload 1 of 2

Request fastly::http::Request::with_cache_key(std::string_view key) &&
View source

Builder-style equivalent of Request::set_cache_key().

Parameters

key: std::string_view

Returns

Request

Overload 2 of 2

Request fastly::http::Request::with_cache_key(std::vector<uint8_t> key) &&
View source

Builder-style equivalent of Request::set_cache_key().

Parameters

key: std::vector<uint8_t>

Returns

Request

with_content_type

View source
Request fastly::http::Request::with_content_type(std::string_view mime) &&

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

Parameters

mime: std::string_view

Returns

Request

with_header

View source
fastly::expected<Request> fastly::http::Request::with_header(std::string_view name, std::string_view value) &&

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

Parameters

name: std::string_view
value: std::string_view

Returns

fastly::expected<Request>

with_method

View source
Request fastly::http::Request::with_method(Method method) &&

Builder-style equivalent of Request::set_method().

Parameters

method: Method

Returns

Request

with_pass

View source
Request fastly::http::Request::with_pass(bool pass) &&

Builder-style equivalent of Request::set_pass().

Parameters

pass: bool

Returns

Request

with_path

View source
fastly::expected<Request> fastly::http::Request::with_path(std::string_view path) &&

Builder-style equivalent of Request::set_path().

Parameters

path: std::string_view

Returns

fastly::expected<Request>

with_pci

View source
Request fastly::http::Request::with_pci(bool pci) &&

Builder-style equivalent of Request::set_pci().

Parameters

pci: bool

Returns

Request

with_query_string

View source
fastly::expected<Request> fastly::http::Request::with_query_string(std::string_view query) &&

Builder-style equivalent of Request::set_query().

Parameters

query: std::string_view

Returns

fastly::expected<Request>

with_set_header

View source
fastly::expected<Request> fastly::http::Request::with_set_header(std::string_view name, std::string_view value) &&

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

Parameters

name: std::string_view
value: std::string_view

Returns

fastly::expected<Request>

with_stale_while_revalidate

View source
Request fastly::http::Request::with_stale_while_revalidate(uint32_t swr) &&

Builder-style equivalent of Request::set_stale_while_revalidate().

Parameters

swr: uint32_t

Returns

Request

with_surrogate_key

View source
fastly::expected<Request> fastly::http::Request::with_surrogate_key(std::string_view sk) &&

Builder-style equivalent of Request::set_surrogate_key().

Parameters

sk: std::string_view

Returns

fastly::expected<Request>

with_ttl

View source
Request fastly::http::Request::with_ttl(uint32_t ttl) &&

Builder-style equivalent of Request::set_ttl().

Parameters

ttl: uint32_t

Returns

Request

with_url

View source
fastly::expected<Request> fastly::http::Request::with_url(std::string_view url) &&

Builder-style equivalent of Request::set_url().

Parameters

url: std::string_view

Returns

fastly::expected<Request>

with_version

View source
Request fastly::http::Request::with_version(Version version) &&

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

Parameters

version: Version

Returns

Request
Fastly
© Fastly 2026