123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451 |
- // 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_RESPONSE_HEADERS_H_
- #define NET_HTTP_HTTP_RESPONSE_HEADERS_H_
- #include <stddef.h>
- #include <stdint.h>
- #include <string>
- #include <unordered_set>
- #include <vector>
- #include "base/callback.h"
- #include "base/memory/ref_counted.h"
- #include "base/strings/string_piece.h"
- #include "base/time/time.h"
- #include "net/base/net_export.h"
- #include "net/http/http_version.h"
- #include "net/log/net_log_capture_mode.h"
- #include "third_party/perfetto/include/perfetto/tracing/traced_value_forward.h"
- namespace base {
- class Pickle;
- class PickleIterator;
- class Time;
- class TimeDelta;
- class Value;
- }
- namespace net {
- class HttpByteRange;
- enum ValidationType {
- VALIDATION_NONE, // The resource is fresh.
- VALIDATION_ASYNCHRONOUS, // The resource requires async revalidation.
- VALIDATION_SYNCHRONOUS // The resource requires sync revalidation.
- };
- // HttpResponseHeaders: parses and holds HTTP response headers.
- class NET_EXPORT HttpResponseHeaders
- : public base::RefCountedThreadSafe<HttpResponseHeaders> {
- public:
- // Persist options.
- typedef int PersistOptions;
- static const PersistOptions PERSIST_RAW = -1; // Raw, unparsed headers.
- static const PersistOptions PERSIST_ALL = 0; // Parsed headers.
- static const PersistOptions PERSIST_SANS_COOKIES = 1 << 0;
- static const PersistOptions PERSIST_SANS_CHALLENGES = 1 << 1;
- static const PersistOptions PERSIST_SANS_HOP_BY_HOP = 1 << 2;
- static const PersistOptions PERSIST_SANS_NON_CACHEABLE = 1 << 3;
- static const PersistOptions PERSIST_SANS_RANGES = 1 << 4;
- static const PersistOptions PERSIST_SANS_SECURITY_STATE = 1 << 5;
- struct FreshnessLifetimes {
- // How long the resource will be fresh for.
- base::TimeDelta freshness;
- // How long after becoming not fresh that the resource will be stale but
- // usable (if async revalidation is enabled).
- base::TimeDelta staleness;
- };
- static const char kContentRange[];
- static const char kLastModified[];
- static const char kVary[];
- HttpResponseHeaders() = delete;
- // Parses the given raw_headers. raw_headers should be formatted thus:
- // includes the http status response line, each line is \0-terminated, and
- // it's terminated by an empty line (ie, 2 \0s in a row).
- // (Note that line continuations should have already been joined;
- // see HttpUtil::AssembleRawHeaders)
- //
- // HttpResponseHeaders does not perform any encoding changes on the input.
- //
- explicit HttpResponseHeaders(const std::string& raw_headers);
- // Initializes from the representation stored in the given pickle. The data
- // for this object is found relative to the given pickle_iter, which should
- // be passed to the pickle's various Read* methods.
- explicit HttpResponseHeaders(base::PickleIterator* pickle_iter);
- // Takes headers as an ASCII string and tries to parse them as HTTP response
- // headers. returns nullptr on failure. Unlike the HttpResponseHeaders
- // constructor that takes a std::string, HttpUtil::AssembleRawHeaders should
- // not be called on |headers| before calling this method.
- static scoped_refptr<HttpResponseHeaders> TryToCreate(
- base::StringPiece headers);
- HttpResponseHeaders(const HttpResponseHeaders&) = delete;
- HttpResponseHeaders& operator=(const HttpResponseHeaders&) = delete;
- // Appends a representation of this object to the given pickle.
- // The options argument can be a combination of PersistOptions.
- void Persist(base::Pickle* pickle, PersistOptions options);
- // Performs header merging as described in 13.5.3 of RFC 2616.
- void Update(const HttpResponseHeaders& new_headers);
- // Removes all instances of a particular header.
- void RemoveHeader(base::StringPiece name);
- // Removes all instances of particular headers.
- void RemoveHeaders(const std::unordered_set<std::string>& header_names);
- // Removes a particular header line. The header name is compared
- // case-insensitively.
- void RemoveHeaderLine(const std::string& name, const std::string& value);
- // Adds the specified response header. If a header with the same name is
- // already stored, the two headers are not merged together by this method; the
- // one provided is simply put at the end of the list.
- void AddHeader(base::StringPiece name, base::StringPiece value);
- // Sets the specified response header, removing any matching old one if
- // present. The new header is added to the end of the header list, rather than
- // replacing the old one. This is the same as calling RemoveHeader() followed
- // be SetHeader().
- void SetHeader(base::StringPiece name, base::StringPiece value);
- // Adds a cookie header. |cookie_string| should be the header value without
- // the header name (Set-Cookie).
- void AddCookie(const std::string& cookie_string);
- // Replaces the current status line with the provided one (|new_status| should
- // not have any EOL).
- void ReplaceStatusLine(const std::string& new_status);
- // Updates headers (Content-Length and Content-Range) in the |headers| to
- // include the right content length and range for |byte_range|. This also
- // updates HTTP status line if |replace_status_line| is true.
- // |byte_range| must have a valid, bounded range (i.e. coming from a valid
- // response or should be usable for a response).
- void UpdateWithNewRange(const HttpByteRange& byte_range,
- int64_t resource_size,
- bool replace_status_line);
- // Fetches the "normalized" value of a single header, where all values for the
- // header name are separated by commas. This will be the sequence of strings
- // that would be returned from repeated calls to EnumerateHeader, joined by
- // the string ", ".
- //
- // Returns false if this header wasn't found.
- //
- // Example:
- // Foo: a, b,c
- // Foo: d
- //
- // string value;
- // GetNormalizedHeader("Foo", &value); // Now, |value| is "a, b, c, d".
- //
- // NOTE: Do not make any assumptions about the encoding of this output
- // string. It may be non-ASCII, and the encoding used by the server is not
- // necessarily known to us. Do not assume that this output is UTF-8!
- bool GetNormalizedHeader(base::StringPiece name, std::string* value) const;
- // Returns the normalized status line.
- std::string GetStatusLine() const;
- // Get the HTTP version of the normalized status line.
- HttpVersion GetHttpVersion() const {
- return http_version_;
- }
- // Get the HTTP status text of the normalized status line.
- std::string GetStatusText() const;
- // Enumerate the "lines" of the response headers. This skips over the status
- // line. Use GetStatusLine if you are interested in that. Note that this
- // method returns the un-coalesced response header lines, so if a response
- // header appears on multiple lines, then it will appear multiple times in
- // this enumeration (in the order the header lines were received from the
- // server). Also, a given header might have an empty value. Initialize a
- // 'size_t' variable to 0 and pass it by address to EnumerateHeaderLines.
- // Call EnumerateHeaderLines repeatedly until it returns false. The
- // out-params 'name' and 'value' are set upon success.
- //
- // WARNING: In effect, repeatedly calling EnumerateHeaderLines should return
- // the same collection of (name, value) pairs that you'd obtain from passing
- // each header name into EnumerateHeader and repeatedly calling
- // EnumerateHeader. This means the output will *not* necessarily correspond to
- // the verbatim lines of the headers. For instance, given
- // Foo: a, b
- // Foo: c
- // EnumerateHeaderLines will output ("Foo", "a"), ("Foo", "b"), and
- // ("Foo", "c").
- bool EnumerateHeaderLines(size_t* iter,
- std::string* name,
- std::string* value) const;
- // Enumerate the values of the specified header. If you are only interested
- // in the first header, then you can pass nullptr for the 'iter' parameter.
- // Otherwise, to iterate across all values for the specified header,
- // initialize a 'size_t' variable to 0 and pass it by address to
- // EnumerateHeader. Note that a header might have an empty value. Call
- // EnumerateHeader repeatedly until it returns false.
- //
- // Unless a header is explicitly marked as non-coalescing (see
- // HttpUtil::IsNonCoalescingHeader), headers that contain
- // comma-separated lists are treated "as if" they had been sent as
- // distinct headers. That is, a header of "Foo: a, b, c" would
- // enumerate into distinct values of "a", "b", and "c". This is also
- // true for headers that occur multiple times in a response; unless
- // they are marked non-coalescing, "Foo: a, b" followed by "Foo: c"
- // will enumerate to "a", "b", "c". Commas inside quoted strings are ignored,
- // for example a header of 'Foo: "a, b", "c"' would enumerate as '"a, b"',
- // '"c"'.
- //
- // This can cause issues for headers that might have commas in fields that
- // aren't quoted strings, for example a header of "Foo: <a, b>, <c>" would
- // enumerate as '<a', 'b>', '<c>', rather than as '<a, b>', '<c>'.
- //
- // To handle cases such as this, use GetNormalizedHeader to return the full
- // concatenated header, and then parse manually.
- bool EnumerateHeader(size_t* iter,
- base::StringPiece name,
- std::string* value) const;
- // Returns true if the response contains the specified header-value pair.
- // Both name and value are compared case insensitively.
- bool HasHeaderValue(base::StringPiece name, base::StringPiece value) const;
- // Returns true if the response contains the specified header.
- // The name is compared case insensitively.
- bool HasHeader(base::StringPiece name) const;
- // Get the mime type and charset values in lower case form from the headers.
- // Empty strings are returned if the values are not present.
- void GetMimeTypeAndCharset(std::string* mime_type,
- std::string* charset) const;
- // Get the mime type in lower case from the headers. If there's no mime
- // type, returns false.
- bool GetMimeType(std::string* mime_type) const;
- // Get the charset in lower case from the headers. If there's no charset,
- // returns false.
- bool GetCharset(std::string* charset) const;
- // Returns true if this response corresponds to a redirect. The target
- // location of the redirect is optionally returned if location is non-null.
- bool IsRedirect(std::string* location) const;
- // Returns true if the HTTP response code passed in corresponds to a
- // redirect.
- static bool IsRedirectResponseCode(int response_code);
- // Returns VALIDATION_NONE if the response can be reused without
- // validation. VALIDATION_ASYNCHRONOUS means the response can be re-used, but
- // asynchronous revalidation must be performed. VALIDATION_SYNCHRONOUS means
- // that the result cannot be reused without revalidation.
- // The result is relative to the current_time parameter, which is
- // a parameter to support unit testing. The request_time parameter indicates
- // the time at which the request was made that resulted in this response,
- // which was received at response_time.
- ValidationType RequiresValidation(const base::Time& request_time,
- const base::Time& response_time,
- const base::Time& current_time) const;
- // Calculates the amount of time the server claims the response is fresh from
- // the time the response was generated. See section 13.2.4 of RFC 2616. See
- // RequiresValidation for a description of the response_time parameter. See
- // the definition of FreshnessLifetimes above for the meaning of the return
- // value. See RFC 5861 section 3 for the definition of
- // stale-while-revalidate.
- FreshnessLifetimes GetFreshnessLifetimes(
- const base::Time& response_time) const;
- // Returns the age of the response. See section 13.2.3 of RFC 2616.
- // See RequiresValidation for a description of this method's parameters.
- base::TimeDelta GetCurrentAge(const base::Time& request_time,
- const base::Time& response_time,
- const base::Time& current_time) const;
- // The following methods extract values from the response headers. If a
- // value is not present, or is invalid, then false is returned. Otherwise,
- // true is returned and the out param is assigned to the corresponding value.
- bool GetMaxAgeValue(base::TimeDelta* value) const;
- bool GetAgeValue(base::TimeDelta* value) const;
- bool GetDateValue(base::Time* value) const;
- bool GetLastModifiedValue(base::Time* value) const;
- bool GetExpiresValue(base::Time* value) const;
- bool GetStaleWhileRevalidateValue(base::TimeDelta* value) const;
- // Extracts the time value of a particular header. This method looks for the
- // first matching header value and parses its value as a HTTP-date.
- bool GetTimeValuedHeader(const std::string& name, base::Time* result) const;
- // Determines if this response indicates a keep-alive connection.
- bool IsKeepAlive() const;
- // Returns true if this response has a strong etag or last-modified header.
- // See section 13.3.3 of RFC 2616.
- bool HasStrongValidators() const;
- // 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.
- bool HasValidators() const;
- // Extracts the value of the Content-Length header or returns -1 if there is
- // no such header in the response.
- int64_t GetContentLength() const;
- // Extracts the value of the specified header or returns -1 if there is no
- // such header in the response.
- int64_t GetInt64HeaderValue(const std::string& header) const;
- // Extracts the values in a Content-Range header and returns true if all three
- // values are present and valid for a 206 response; otherwise returns false.
- // The following values will be outputted:
- // |*first_byte_position| = inclusive position of the first byte of the range
- // |*last_byte_position| = inclusive position of the last byte of the range
- // |*instance_length| = size in bytes of the object requested
- // If this method returns false, then all of the outputs will be -1.
- bool GetContentRangeFor206(int64_t* first_byte_position,
- int64_t* last_byte_position,
- int64_t* instance_length) const;
- // Returns true if the response is chunk-encoded.
- bool IsChunkEncoded() const;
- // Creates a Value for use with the NetLog containing the response headers.
- base::Value NetLogParams(NetLogCaptureMode capture_mode) const;
- // Returns the HTTP response code. This is 0 if the response code text seems
- // to exist but could not be parsed. Otherwise, it defaults to 200 if the
- // response code is not found in the raw headers.
- int response_code() const { return response_code_; }
- // Returns the raw header string.
- const std::string& raw_headers() const { return raw_headers_; }
- // Returns true if |name| is a cookie related header name. This is consistent
- // with |PERSIST_SANS_COOKIES|.
- static bool IsCookieResponseHeader(base::StringPiece name);
- // Write a representation of this object into tracing proto.
- void WriteIntoTrace(perfetto::TracedValue context) const;
- private:
- friend class base::RefCountedThreadSafe<HttpResponseHeaders>;
- using HeaderSet = std::unordered_set<std::string>;
- // The members of this structure point into raw_headers_.
- struct ParsedHeader;
- typedef std::vector<ParsedHeader> HeaderList;
- ~HttpResponseHeaders();
- // Initializes from the given raw headers.
- void Parse(const std::string& raw_input);
- // Helper function for ParseStatusLine.
- // Tries to extract the "HTTP/X.Y" from a status line formatted like:
- // HTTP/1.1 200 OK
- // with line_begin and end pointing at the begin and end of this line. If the
- // status line is malformed, returns HttpVersion(0,0).
- static HttpVersion ParseVersion(std::string::const_iterator line_begin,
- std::string::const_iterator line_end);
- // Tries to extract the status line from a header block, given the first
- // line of said header block. If the status line is malformed, we'll
- // construct a valid one. Example input:
- // HTTP/1.1 200 OK
- // with line_begin and end pointing at the begin and end of this line.
- // Output will be a normalized version of this.
- void ParseStatusLine(std::string::const_iterator line_begin,
- std::string::const_iterator line_end,
- bool has_headers);
- // Find the header in our list (case-insensitive) starting with |parsed_| at
- // index |from|. Returns string::npos if not found.
- size_t FindHeader(size_t from, base::StringPiece name) const;
- // Search the Cache-Control header for a directive matching |directive|. If
- // present, treat its value as a time offset in seconds, write it to |result|,
- // and return true.
- bool GetCacheControlDirective(base::StringPiece directive,
- base::TimeDelta* result) const;
- // Add a header->value pair to our list. If we already have header in our
- // list, append the value to it.
- void AddHeader(std::string::const_iterator name_begin,
- std::string::const_iterator name_end,
- std::string::const_iterator value_begin,
- std::string::const_iterator value_end);
- // Add to parsed_ given the fields of a ParsedHeader object.
- void AddToParsed(std::string::const_iterator name_begin,
- std::string::const_iterator name_end,
- std::string::const_iterator value_begin,
- std::string::const_iterator value_end);
- // Replaces the current headers with the merged version of |raw_headers| and
- // the current headers without the headers in |headers_to_remove|. Note that
- // |headers_to_remove| are removed from the current headers (before the
- // merge), not after the merge.
- void MergeWithHeaders(const std::string& raw_headers,
- const HeaderSet& headers_to_remove);
- // Adds the values from any 'cache-control: no-cache="foo,bar"' headers.
- void AddNonCacheableHeaders(HeaderSet* header_names) const;
- // Adds the set of header names that contain cookie values.
- static void AddSensitiveHeaders(HeaderSet* header_names);
- // Adds the set of rfc2616 hop-by-hop response headers.
- static void AddHopByHopHeaders(HeaderSet* header_names);
- // Adds the set of challenge response headers.
- static void AddChallengeHeaders(HeaderSet* header_names);
- // Adds the set of cookie response headers.
- static void AddCookieHeaders(HeaderSet* header_names);
- // Adds the set of content range response headers.
- static void AddHopContentRangeHeaders(HeaderSet* header_names);
- // Adds the set of transport security state headers.
- static void AddSecurityStateHeaders(HeaderSet* header_names);
- // We keep a list of ParsedHeader objects. These tell us where to locate the
- // header-value pairs within raw_headers_.
- HeaderList parsed_;
- // The raw_headers_ consists of the normalized status line (terminated with a
- // null byte) and then followed by the raw null-terminated headers from the
- // input that was passed to our constructor. We preserve the input [*] to
- // maintain as much ancillary fidelity as possible (since it is sometimes
- // hard to tell what may matter down-stream to a consumer of XMLHttpRequest).
- // [*] The status line may be modified.
- std::string raw_headers_;
- // This is the parsed HTTP response code.
- int response_code_;
- // The normalized http version (consistent with what GetStatusLine() returns).
- HttpVersion http_version_;
- };
- using ResponseHeadersCallback =
- base::RepeatingCallback<void(scoped_refptr<const HttpResponseHeaders>)>;
- } // namespace net
- #endif // NET_HTTP_HTTP_RESPONSE_HEADERS_H_
|