blob: 2b70e20d341778c3c7766c14cd4a00cbc3fbd3eb [file] [log] [blame]
// Copyright (c) 2012 The Chromium Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
#ifndef NET_HTTP_HTTP_UTIL_H_
#define NET_HTTP_HTTP_UTIL_H_
#include <stddef.h>
#include <string>
#include <vector>
#include "base/macros.h"
#include "base/memory/ref_counted.h"
#include "base/strings/string_tokenizer.h"
#include "base/time/time.h"
#include "net/base/net_export.h"
#include "net/http/http_byte_range.h"
#include "net/http/http_version.h"
#include "url/gurl.h"
// This is a macro to support extending this string literal at compile time.
// Please excuse me polluting your global namespace!
#define HTTP_LWS " \t"
namespace net {
class NET_EXPORT HttpUtil {
public:
// Returns the absolute URL, to be used for the http request. This url is
// made up of the protocol, host, [port], path, [query]. Everything else
// is stripped (username, password, reference).
static std::string SpecForRequest(const GURL& url);
// Parses the value of a Content-Type header. The resulting mime_type and
// charset values are normalized to lowercase. The mime_type and charset
// output values are only modified if the content_type_str contains a mime
// type and charset value, respectively. The boundary output value is
// optional and will be assigned the (quoted) value of the boundary
// paramter, if any.
static void ParseContentType(const std::string& content_type_str,
std::string* mime_type,
std::string* charset,
bool* had_charset,
std::string* boundary);
// Scans the headers and look for the first "Range" header in |headers|,
// if "Range" exists and the first one of it is well formatted then returns
// true, |ranges| will contain a list of valid ranges. If return
// value is false then values in |ranges| should not be used. The format of
// "Range" header is defined in RFC 7233 Section 2.1.
// https://tools.ietf.org/html/rfc7233#section-2.1
static bool ParseRanges(const std::string& headers,
std::vector<HttpByteRange>* ranges);
// Same thing as ParseRanges except the Range header is known and its value
// is directly passed in, rather than requiring searching through a string.
static bool ParseRangeHeader(const std::string& range_specifier,
std::vector<HttpByteRange>* ranges);
// Parses a Retry-After header that is either an absolute date/time or a
// number of seconds in the future. Interprets absolute times as relative to
// |now|. If |retry_after_string| is successfully parsed and indicates a time
// that is not in the past, fills in |*retry_after| and returns true;
// otherwise, returns false.
static bool ParseRetryAfterHeader(const std::string& retry_after_string,
base::Time now,
base::TimeDelta* retry_after);
// Scans the '\r\n'-delimited headers for the given header name. Returns
// true if a match is found. Input is assumed to be well-formed.
// TODO(darin): kill this
static bool HasHeader(const std::string& headers, const char* name);
// Returns true if it is safe to allow users and scripts to specify the header
// named |name|.
static bool IsSafeHeader(const std::string& name);
// Returns true if |name| is a valid HTTP header name.
static bool IsValidHeaderName(const std::string& name);
// Returns false if |value| contains NUL or CRLF. This method does not perform
// a fully RFC-2616-compliant header value validation.
static bool IsValidHeaderValue(const std::string& value);
// Returns true if |value| is a valid HTTP header value according to
// RFC 7230 and doesn't contain CR or LF.
// i.e. returns true if |value| matches |*field-content| in RFC 7230.
static bool IsValidHeaderValueRFC7230(const base::StringPiece& value);
// Strips all header lines from |headers| whose name matches
// |headers_to_remove|. |headers_to_remove| is a list of null-terminated
// lower-case header names, with array length |headers_to_remove_len|.
// Returns the stripped header lines list, separated by "\r\n".
static std::string StripHeaders(const std::string& headers,
const char* const headers_to_remove[],
size_t headers_to_remove_len);
// Multiple occurances of some headers cannot be coalesced into a comma-
// separated list since their values are (or contain) unquoted HTTP-date
// values, which may contain a comma (see RFC 2616 section 3.3.1).
static bool IsNonCoalescingHeader(std::string::const_iterator name_begin,
std::string::const_iterator name_end);
static bool IsNonCoalescingHeader(const std::string& name) {
return IsNonCoalescingHeader(name.begin(), name.end());
}
// Return true if the character is HTTP "linear white space" (SP | HT).
// This definition corresponds with the HTTP_LWS macro, and does not match
// newlines.
static bool IsLWS(char c);
// Trim HTTP_LWS chars from the beginning and end of the string.
static void TrimLWS(std::string::const_iterator* begin,
std::string::const_iterator* end);
// Whether the character is the start of a quotation mark.
static bool IsQuote(char c);
// Whether the string is a valid |token| as defined in RFC 2616 Sec 2.2.
static bool IsToken(std::string::const_iterator begin,
std::string::const_iterator end);
static bool IsToken(const std::string& str) {
return IsToken(str.begin(), str.end());
}
// Whether the string is a valid |parmname| as defined in RFC 5987 Sec 3.2.1.
static bool IsParmName(std::string::const_iterator begin,
std::string::const_iterator end);
static bool IsParmName(const std::string& str) {
return IsParmName(str.begin(), str.end());
}
// RFC 2616 Sec 2.2:
// quoted-string = ( <"> *(qdtext | quoted-pair ) <"> )
// Unquote() strips the surrounding quotemarks off a string, and unescapes
// any quoted-pair to obtain the value contained by the quoted-string.
// If the input is not quoted, then it works like the identity function.
static std::string Unquote(std::string::const_iterator begin,
std::string::const_iterator end);
// Same as above.
static std::string Unquote(const std::string& str);
// Similar to Unquote(), but additionally validates that the string being
// unescaped actually is a valid quoted string. Returns false for an empty
// string, a string without quotes, a string with mismatched quotes, and
// a string with unescaped embeded quotes.
// In accordance with RFC 2616 this method only allows double quotes to
// enclose the string.
static bool StrictUnquote(std::string::const_iterator begin,
std::string::const_iterator end,
std::string* out) WARN_UNUSED_RESULT;
// Same as above.
static bool StrictUnquote(const std::string& str,
std::string* out) WARN_UNUSED_RESULT;
// The reverse of Unquote() -- escapes and surrounds with "
static std::string Quote(const std::string& str);
// Returns the start of the status line, or -1 if no status line was found.
// This allows for 4 bytes of junk to precede the status line (which is what
// mozilla does too).
static int LocateStartOfStatusLine(const char* buf, int buf_len);
// Returns index beyond the end-of-headers marker or -1 if not found. RFC
// 2616 defines the end-of-headers marker as a double CRLF; however, some
// servers only send back LFs (e.g., Unix-based CGI scripts written using the
// ASIS Apache module). This function therefore accepts the pattern LF[CR]LF
// as end-of-headers (just like Mozilla). The first line of |buf| is
// considered the status line, even if empty.
// The parameter |i| is the offset within |buf| to begin searching from.
static int LocateEndOfHeaders(const char* buf, int buf_len, int i = 0);
// Same as |LocateEndOfHeaders|, but does not expect a status line, so can be
// used on multi-part responses or HTTP/1.x trailers. As a result, if |buf|
// starts with a single [CR]LF, it is considered an empty header list, as
// opposed to an empty status line above a header list.
static int LocateEndOfAdditionalHeaders(const char* buf,
int buf_len,
int i = 0);
// Assemble "raw headers" in the format required by HttpResponseHeaders.
// This involves normalizing line terminators, converting [CR]LF to \0 and
// handling HTTP line continuations (i.e., lines starting with LWS are
// continuations of the previous line). |buf_len| indicates the position of
// the end-of-headers marker as defined by LocateEndOfHeaders.
// If a \0 appears within the headers themselves, it will be stripped. This
// is a workaround to avoid later code from incorrectly interpreting it as
// a line terminator.
//
// TODO(eroman): we should use \n as the canonical line separator rather than
// \0 to avoid this problem. Unfortunately the persistence layer
// is already dependent on newlines being replaced by NULL so
// this is hard to change without breaking things.
static std::string AssembleRawHeaders(const char* buf, int buf_len);
// Converts assembled "raw headers" back to the HTTP response format. That is
// convert each \0 occurence to CRLF. This is used by DevTools.
// Since all line continuations info is already lost at this point, the result
// consists of status line and then one line for each header.
static std::string ConvertHeadersBackToHTTPResponse(const std::string& str);
// Given a comma separated ordered list of language codes, return
// the list with a qvalue appended to each language.
// The way qvalues are assigned is rather simple. The qvalue
// starts with 1.0 and is decremented by 0.2 for each successive entry
// in the list until it reaches 0.2. All the entries after that are
// assigned the same qvalue of 0.2. Also, note that the 1st language
// will not have a qvalue added because the absence of a qvalue implicitly
// means q=1.0.
//
// When making a http request, this should be used to determine what
// to put in Accept-Language header. If a comma separated list of language
// codes *without* qvalue is sent, web servers regard all
// of them as having q=1.0 and pick one of them even though it may not
// be at the beginning of the list (see http://crbug.com/5899).
static std::string GenerateAcceptLanguageHeader(
const std::string& raw_language_list);
// Helper. If |*headers| already contains |header_name| do nothing,
// otherwise add <header_name> ": " <header_value> to the end of the list.
static void AppendHeaderIfMissing(const char* header_name,
const std::string& header_value,
std::string* headers);
// Returns true if the parameters describe a response with a strong etag or
// last-modified header. See section 13.3.3 of RFC 2616.
// An empty string should be passed for missing headers.
static bool HasStrongValidators(HttpVersion version,
const std::string& etag_header,
const std::string& last_modified_header,
const std::string& date_header);
// Returns true if this response has any validator (either a Last-Modified or
// an ETag) regardless of whether it is strong or weak. See section 13.3.3 of
// RFC 2616.
// An empty string should be passed for missing headers.
static bool HasValidators(HttpVersion version,
const std::string& etag_header,
const std::string& last_modified_header);
// Gets a vector of common HTTP status codes for histograms of status
// codes. Currently returns everything in the range [100, 600), plus 0
// (for invalid responses/status codes).
static std::vector<int> GetStatusCodesForHistogram();
// Maps an HTTP status code to one of the status codes in the vector
// returned by GetStatusCodesForHistogram.
static int MapStatusCodeForHistogram(int code);
// Used to iterate over the name/value pairs of HTTP headers. To iterate
// over the values in a multi-value header, use ValuesIterator.
// See AssembleRawHeaders for joining line continuations (this iterator
// does not expect any).
class NET_EXPORT HeadersIterator {
public:
HeadersIterator(std::string::const_iterator headers_begin,
std::string::const_iterator headers_end,
const std::string& line_delimiter);
~HeadersIterator();
// Advances the iterator to the next header, if any. Returns true if there
// is a next header. Use name* and values* methods to access the resultant
// header name and values.
bool GetNext();
// Iterates through the list of headers, starting with the current position
// and looks for the specified header. Note that the name _must_ be
// lower cased.
// If the header was found, the return value will be true and the current
// position points to the header. If the return value is false, the
// current position will be at the end of the headers.
bool AdvanceTo(const char* lowercase_name);
void Reset() {
lines_.Reset();
}
std::string::const_iterator name_begin() const {
return name_begin_;
}
std::string::const_iterator name_end() const {
return name_end_;
}
std::string name() const {
return std::string(name_begin_, name_end_);
}
std::string::const_iterator values_begin() const {
return values_begin_;
}
std::string::const_iterator values_end() const {
return values_end_;
}
std::string values() const {
return std::string(values_begin_, values_end_);
}
private:
base::StringTokenizer lines_;
std::string::const_iterator name_begin_;
std::string::const_iterator name_end_;
std::string::const_iterator values_begin_;
std::string::const_iterator values_end_;
};
// Iterates over delimited values in an HTTP header. HTTP LWS is
// automatically trimmed from the resulting values.
//
// When using this class to iterate over response header values, be aware that
// for some headers (e.g., Last-Modified), commas are not used as delimiters.
// This iterator should be avoided for headers like that which are considered
// non-coalescing (see IsNonCoalescingHeader).
//
// This iterator is careful to skip over delimiters found inside an HTTP
// quoted string.
//
class NET_EXPORT_PRIVATE ValuesIterator {
public:
ValuesIterator(std::string::const_iterator values_begin,
std::string::const_iterator values_end,
char delimiter);
ValuesIterator(const ValuesIterator& other);
~ValuesIterator();
// Set the characters to regard as quotes. By default, this includes both
// single and double quotes.
void set_quote_chars(const char* quotes) {
values_.set_quote_chars(quotes);
}
// Advances the iterator to the next value, if any. Returns true if there
// is a next value. Use value* methods to access the resultant value.
bool GetNext();
std::string::const_iterator value_begin() const {
return value_begin_;
}
std::string::const_iterator value_end() const {
return value_end_;
}
std::string value() const {
return std::string(value_begin_, value_end_);
}
private:
base::StringTokenizer values_;
std::string::const_iterator value_begin_;
std::string::const_iterator value_end_;
};
// Iterates over a delimited sequence of name-value pairs in an HTTP header.
// Each pair consists of a token (the name), an equals sign, and either a
// token or quoted-string (the value). Arbitrary HTTP LWS is permitted outside
// of and between names, values, and delimiters.
//
// String iterators returned from this class' methods may be invalidated upon
// calls to GetNext() or after the NameValuePairsIterator is destroyed.
class NET_EXPORT NameValuePairsIterator {
public:
// Whether or not values are optional. Values::NOT_REQUIRED allows
// e.g. name1=value1;name2;name3=value3, whereas Vaues::REQUIRED
// will treat it as a parse error because name2 does not have a
// corresponding equals sign.
enum class Values { NOT_REQUIRED, REQUIRED };
// Whether or not unmatched quotes should be considered a failure. By
// default this class is pretty lenient and does a best effort to parse
// values with mismatched quotes. When set to STRICT_QUOTES a value with
// mismatched or otherwise invalid quotes is considered a parse error.
enum class Quotes { STRICT_QUOTES, NOT_STRICT };
NameValuePairsIterator(std::string::const_iterator begin,
std::string::const_iterator end,
char delimiter,
Values optional_values,
Quotes strict_quotes);
// Treats values as not optional by default (Values::REQUIRED) and
// treats quotes as not strict.
NameValuePairsIterator(std::string::const_iterator begin,
std::string::const_iterator end,
char delimiter);
NameValuePairsIterator(const NameValuePairsIterator& other);
~NameValuePairsIterator();
// Advances the iterator to the next pair, if any. Returns true if there
// is a next pair. Use name* and value* methods to access the resultant
// value.
bool GetNext();
// Returns false if there was a parse error.
bool valid() const { return valid_; }
// The name of the current name-value pair.
std::string::const_iterator name_begin() const { return name_begin_; }
std::string::const_iterator name_end() const { return name_end_; }
std::string name() const { return std::string(name_begin_, name_end_); }
// The value of the current name-value pair.
std::string::const_iterator value_begin() const {
return value_is_quoted_ ? unquoted_value_.begin() : value_begin_;
}
std::string::const_iterator value_end() const {
return value_is_quoted_ ? unquoted_value_.end() : value_end_;
}
std::string value() const {
return value_is_quoted_ ? unquoted_value_ : std::string(value_begin_,
value_end_);
}
bool value_is_quoted() const { return value_is_quoted_; }
// The value before unquoting (if any).
std::string raw_value() const { return std::string(value_begin_,
value_end_); }
private:
bool IsQuote(char c) const;
HttpUtil::ValuesIterator props_;
bool valid_;
std::string::const_iterator name_begin_;
std::string::const_iterator name_end_;
std::string::const_iterator value_begin_;
std::string::const_iterator value_end_;
// Do not store iterators into this string. The NameValuePairsIterator
// is copyable/assignable, and if copied the copy's iterators would point
// into the original's unquoted_value_ member.
std::string unquoted_value_;
bool value_is_quoted_;
// True if values are required for each name/value pair; false if a
// name is permitted to appear without a corresponding value.
bool values_optional_;
// True if quotes values are required to be properly quoted; false if
// mismatched quotes and other problems with quoted values should be more
// or less gracefully treated as valid.
bool strict_quotes_;
};
};
} // namespace net
#endif // NET_HTTP_HTTP_UTIL_H_