| // 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. |
| |
| // This file declares HttpCache::Transaction, a private class of HttpCache so |
| // it should only be included by http_cache.cc |
| |
| #ifndef NET_HTTP_HTTP_CACHE_TRANSACTION_H_ |
| #define NET_HTTP_HTTP_CACHE_TRANSACTION_H_ |
| |
| #include <stddef.h> |
| #include <stdint.h> |
| |
| #include <memory> |
| #include <string> |
| |
| #include "base/macros.h" |
| #include "base/memory/ref_counted.h" |
| #include "base/memory/weak_ptr.h" |
| #include "base/time/time.h" |
| #include "net/base/completion_callback.h" |
| #include "net/base/io_buffer.h" |
| #include "net/base/ip_endpoint.h" |
| #include "net/base/load_states.h" |
| #include "net/base/net_error_details.h" |
| #include "net/base/request_priority.h" |
| #include "net/base/upload_progress.h" |
| #include "net/http/http_cache.h" |
| #include "net/http/http_request_headers.h" |
| #include "net/http/http_response_headers.h" |
| #include "net/http/http_response_info.h" |
| #include "net/http/http_transaction.h" |
| #include "net/http/partial_data.h" |
| #include "net/log/net_log.h" |
| #include "net/socket/connection_attempts.h" |
| #include "net/websockets/websocket_handshake_stream_base.h" |
| |
| namespace net { |
| |
| class PartialData; |
| struct HttpRequestInfo; |
| struct LoadTimingInfo; |
| class SSLPrivateKey; |
| |
| // This is the transaction that is returned by the HttpCache transaction |
| // factory. |
| class HttpCache::Transaction : public HttpTransaction { |
| public: |
| // The transaction has the following modes, which apply to how it may access |
| // its cache entry. |
| // |
| // o If the mode of the transaction is NONE, then it is in "pass through" |
| // mode and all methods just forward to the inner network transaction. |
| // |
| // o If the mode of the transaction is only READ, then it may only read from |
| // the cache entry. |
| // |
| // o If the mode of the transaction is only WRITE, then it may only write to |
| // the cache entry. |
| // |
| // o If the mode of the transaction is READ_WRITE, then the transaction may |
| // optionally modify the cache entry (e.g., possibly corresponding to |
| // cache validation). |
| // |
| // o If the mode of the transaction is UPDATE, then the transaction may |
| // update existing cache entries, but will never create a new entry or |
| // respond using the entry read from the cache. |
| enum Mode { |
| NONE = 0, |
| READ_META = 1 << 0, |
| READ_DATA = 1 << 1, |
| READ = READ_META | READ_DATA, |
| WRITE = 1 << 2, |
| READ_WRITE = READ | WRITE, |
| UPDATE = READ_META | WRITE, // READ_WRITE & ~READ_DATA |
| }; |
| |
| Transaction(RequestPriority priority, |
| HttpCache* cache); |
| ~Transaction() override; |
| |
| Mode mode() const { return mode_; } |
| |
| const std::string& key() const { return cache_key_; } |
| |
| // Writes |buf_len| bytes of meta-data from the provided buffer |buf|. to the |
| // HTTP cache entry that backs this transaction (if any). |
| // Returns the number of bytes actually written, or a net error code. If the |
| // operation cannot complete immediately, returns ERR_IO_PENDING, grabs a |
| // reference to the buffer (until completion), and notifies the caller using |
| // the provided |callback| when the operation finishes. |
| // |
| // The first time this method is called for a given transaction, previous |
| // meta-data will be overwritten with the provided data, and subsequent |
| // invocations will keep appending to the cached entry. |
| // |
| // In order to guarantee that the metadata is set to the correct entry, the |
| // response (or response info) must be evaluated by the caller, for instance |
| // to make sure that the response_time is as expected, before calling this |
| // method. |
| int WriteMetadata(IOBuffer* buf, |
| int buf_len, |
| const CompletionCallback& callback); |
| |
| // This transaction is being deleted and we are not done writing to the cache. |
| // We need to indicate that the response data was truncated. Returns true on |
| // success. Keep in mind that this operation may have side effects, such as |
| // deleting the active entry. |
| bool AddTruncatedFlag(); |
| |
| HttpCache::ActiveEntry* entry() { return entry_; } |
| |
| // Returns the LoadState of the writer transaction of a given ActiveEntry. In |
| // other words, returns the LoadState of this transaction without asking the |
| // http cache, because this transaction should be the one currently writing |
| // to the cache entry. |
| LoadState GetWriterLoadState() const; |
| |
| const CompletionCallback& io_callback() { return io_callback_; } |
| |
| const BoundNetLog& net_log() const; |
| |
| // Bypasses the cache lock whenever there is lock contention. |
| void BypassLockForTest() { |
| bypass_lock_for_test_ = true; |
| } |
| |
| // Generates a failure when attempting to conditionalize a network request. |
| void FailConditionalizationForTest() { |
| fail_conditionalization_for_test_ = true; |
| } |
| |
| // HttpTransaction methods: |
| int Start(const HttpRequestInfo* request_info, |
| const CompletionCallback& callback, |
| const BoundNetLog& net_log) override; |
| int RestartIgnoringLastError(const CompletionCallback& callback) override; |
| int RestartWithCertificate(X509Certificate* client_cert, |
| SSLPrivateKey* client_private_key, |
| const CompletionCallback& callback) override; |
| int RestartWithAuth(const AuthCredentials& credentials, |
| const CompletionCallback& callback) override; |
| bool IsReadyToRestartForAuth() override; |
| int Read(IOBuffer* buf, |
| int buf_len, |
| const CompletionCallback& callback) override; |
| void StopCaching() override; |
| bool GetFullRequestHeaders(HttpRequestHeaders* headers) const override; |
| int64_t GetTotalReceivedBytes() const override; |
| int64_t GetTotalSentBytes() const override; |
| void DoneReading() override; |
| const HttpResponseInfo* GetResponseInfo() const override; |
| LoadState GetLoadState() const override; |
| UploadProgress GetUploadProgress(void) const override; |
| void SetQuicServerInfo(QuicServerInfo* quic_server_info) override; |
| bool GetLoadTimingInfo(LoadTimingInfo* load_timing_info) const override; |
| bool GetRemoteEndpoint(IPEndPoint* endpoint) const override; |
| void PopulateNetErrorDetails(NetErrorDetails* details) const override; |
| void SetPriority(RequestPriority priority) override; |
| void SetWebSocketHandshakeStreamCreateHelper( |
| WebSocketHandshakeStreamBase::CreateHelper* create_helper) override; |
| void SetBeforeNetworkStartCallback( |
| const BeforeNetworkStartCallback& callback) override; |
| void SetBeforeHeadersSentCallback( |
| const BeforeHeadersSentCallback& callback) override; |
| int ResumeNetworkStart() override; |
| void GetConnectionAttempts(ConnectionAttempts* out) const override; |
| |
| private: |
| static const size_t kNumValidationHeaders = 2; |
| // Helper struct to pair a header name with its value, for |
| // headers used to validate cache entries. |
| struct ValidationHeaders { |
| ValidationHeaders() : initialized(false) {} |
| |
| std::string values[kNumValidationHeaders]; |
| bool initialized; |
| }; |
| |
| enum State { |
| // Normally, states are traversed in approximately this order. |
| STATE_NONE, |
| STATE_GET_BACKEND, |
| STATE_GET_BACKEND_COMPLETE, |
| STATE_INIT_ENTRY, |
| STATE_OPEN_ENTRY, |
| STATE_OPEN_ENTRY_COMPLETE, |
| STATE_DOOM_ENTRY, |
| STATE_DOOM_ENTRY_COMPLETE, |
| STATE_CREATE_ENTRY, |
| STATE_CREATE_ENTRY_COMPLETE, |
| STATE_ADD_TO_ENTRY, |
| STATE_ADD_TO_ENTRY_COMPLETE, |
| STATE_CACHE_READ_RESPONSE, |
| STATE_CACHE_READ_RESPONSE_COMPLETE, |
| STATE_TOGGLE_UNUSED_SINCE_PREFETCH, |
| STATE_TOGGLE_UNUSED_SINCE_PREFETCH_COMPLETE, |
| STATE_CACHE_DISPATCH_VALIDATION, |
| STATE_CACHE_QUERY_DATA, |
| STATE_CACHE_QUERY_DATA_COMPLETE, |
| STATE_START_PARTIAL_CACHE_VALIDATION, |
| STATE_COMPLETE_PARTIAL_CACHE_VALIDATION, |
| STATE_SEND_REQUEST, |
| STATE_SEND_REQUEST_COMPLETE, |
| STATE_SUCCESSFUL_SEND_REQUEST, |
| STATE_UPDATE_CACHED_RESPONSE, |
| STATE_CACHE_WRITE_UPDATED_RESPONSE, |
| STATE_CACHE_WRITE_UPDATED_RESPONSE_COMPLETE, |
| STATE_UPDATE_CACHED_RESPONSE_COMPLETE, |
| STATE_OVERWRITE_CACHED_RESPONSE, |
| STATE_CACHE_WRITE_RESPONSE, |
| STATE_CACHE_WRITE_RESPONSE_COMPLETE, |
| STATE_TRUNCATE_CACHED_DATA, |
| STATE_TRUNCATE_CACHED_DATA_COMPLETE, |
| STATE_TRUNCATE_CACHED_METADATA, |
| STATE_TRUNCATE_CACHED_METADATA_COMPLETE, |
| STATE_PARTIAL_HEADERS_RECEIVED, |
| STATE_CACHE_READ_METADATA, |
| STATE_CACHE_READ_METADATA_COMPLETE, |
| |
| // These states are entered from Read/AddTruncatedFlag. |
| STATE_NETWORK_READ, |
| STATE_NETWORK_READ_COMPLETE, |
| STATE_CACHE_READ_DATA, |
| STATE_CACHE_READ_DATA_COMPLETE, |
| STATE_CACHE_WRITE_DATA, |
| STATE_CACHE_WRITE_DATA_COMPLETE, |
| STATE_CACHE_WRITE_TRUNCATED_RESPONSE, |
| STATE_CACHE_WRITE_TRUNCATED_RESPONSE_COMPLETE |
| }; |
| |
| // Used for categorizing transactions for reporting in histograms. Patterns |
| // cover relatively common use cases being measured and considered for |
| // optimization. Many use cases that are more complex or uncommon are binned |
| // as PATTERN_NOT_COVERED, and details are not reported. |
| // NOTE: This enumeration is used in histograms, so please do not add entries |
| // in the middle. |
| enum TransactionPattern { |
| PATTERN_UNDEFINED, |
| PATTERN_NOT_COVERED, |
| PATTERN_ENTRY_NOT_CACHED, |
| PATTERN_ENTRY_USED, |
| PATTERN_ENTRY_VALIDATED, |
| PATTERN_ENTRY_UPDATED, |
| PATTERN_ENTRY_CANT_CONDITIONALIZE, |
| PATTERN_MAX, |
| }; |
| |
| // Used for categorizing validation triggers in histograms. |
| // NOTE: This enumeration is used in histograms, so please do not add entries |
| // in the middle. |
| enum ValidationCause { |
| VALIDATION_CAUSE_UNDEFINED, |
| VALIDATION_CAUSE_VARY_MISMATCH, |
| VALIDATION_CAUSE_VALIDATE_FLAG, |
| VALIDATION_CAUSE_STALE, |
| VALIDATION_CAUSE_ZERO_FRESHNESS, |
| VALIDATION_CAUSE_MAX |
| }; |
| |
| // Runs the state transition loop. Resets and calls |callback_| on exit, |
| // unless the return value is ERR_IO_PENDING. |
| int DoLoop(int result); |
| |
| // Each of these methods corresponds to a State value. If there is an |
| // argument, the value corresponds to the return of the previous state or |
| // corresponding callback. |
| int DoGetBackend(); |
| int DoGetBackendComplete(int result); |
| int DoInitEntry(); |
| int DoOpenEntry(); |
| int DoOpenEntryComplete(int result); |
| int DoDoomEntry(); |
| int DoDoomEntryComplete(int result); |
| int DoCreateEntry(); |
| int DoCreateEntryComplete(int result); |
| int DoAddToEntry(); |
| int DoAddToEntryComplete(int result); |
| int DoCacheReadResponse(); |
| int DoCacheReadResponseComplete(int result); |
| int DoCacheToggleUnusedSincePrefetch(); |
| int DoCacheToggleUnusedSincePrefetchComplete(int result); |
| int DoCacheDispatchValidation(); |
| int DoCacheQueryData(); |
| int DoCacheQueryDataComplete(int result); |
| int DoStartPartialCacheValidation(); |
| int DoCompletePartialCacheValidation(int result); |
| int DoSendRequest(); |
| int DoSendRequestComplete(int result); |
| int DoSuccessfulSendRequest(); |
| int DoUpdateCachedResponse(); |
| int DoCacheWriteUpdatedResponse(); |
| int DoCacheWriteUpdatedResponseComplete(int result); |
| int DoUpdateCachedResponseComplete(int result); |
| int DoOverwriteCachedResponse(); |
| int DoCacheWriteResponse(); |
| int DoCacheWriteResponseComplete(int result); |
| int DoTruncateCachedData(); |
| int DoTruncateCachedDataComplete(int result); |
| int DoTruncateCachedMetadata(); |
| int DoTruncateCachedMetadataComplete(int result); |
| int DoPartialHeadersReceived(); |
| int DoCacheReadMetadata(); |
| int DoCacheReadMetadataComplete(int result); |
| int DoNetworkRead(); |
| int DoNetworkReadComplete(int result); |
| int DoCacheReadData(); |
| int DoCacheReadDataComplete(int result); |
| int DoCacheWriteData(int num_bytes); |
| int DoCacheWriteDataComplete(int result); |
| int DoCacheWriteTruncatedResponse(); |
| int DoCacheWriteTruncatedResponseComplete(int result); |
| |
| // Sets request_ and fields derived from it. |
| void SetRequest(const BoundNetLog& net_log, const HttpRequestInfo* request); |
| |
| // Returns true if the request should be handled exclusively by the network |
| // layer (skipping the cache entirely). |
| bool ShouldPassThrough(); |
| |
| // Called to begin reading from the cache. Returns network error code. |
| int BeginCacheRead(); |
| |
| // Called to begin validating the cache entry. Returns network error code. |
| int BeginCacheValidation(); |
| |
| // Called to begin validating an entry that stores partial content. Returns |
| // a network error code. |
| int BeginPartialCacheValidation(); |
| |
| // Validates the entry headers against the requested range and continues with |
| // the validation of the rest of the entry. Returns a network error code. |
| int ValidateEntryHeadersAndContinue(); |
| |
| // Called to start requests which were given an "if-modified-since" or |
| // "if-none-match" validation header by the caller (NOT when the request was |
| // conditionalized internally in response to LOAD_VALIDATE_CACHE). |
| // Returns a network error code. |
| int BeginExternallyConditionalizedRequest(); |
| |
| // Called to restart a network transaction after an error. Returns network |
| // error code. |
| int RestartNetworkRequest(); |
| |
| // Called to restart a network transaction with a client certificate. |
| // Returns network error code. |
| int RestartNetworkRequestWithCertificate(X509Certificate* client_cert, |
| SSLPrivateKey* client_private_key); |
| |
| // Called to restart a network transaction with authentication credentials. |
| // Returns network error code. |
| int RestartNetworkRequestWithAuth(const AuthCredentials& credentials); |
| |
| // Called to determine if we need to validate the cache entry before using it, |
| // and whether the validation should be synchronous or asynchronous. |
| ValidationType RequiresValidation(); |
| |
| // Called to make the request conditional (to ask the server if the cached |
| // copy is valid). Returns true if able to make the request conditional. |
| bool ConditionalizeRequest(); |
| |
| // Makes sure that a 206 response is expected. Returns true on success. |
| // On success, handling_206_ will be set to true if we are processing a |
| // partial entry. |
| bool ValidatePartialResponse(); |
| |
| // Handles a response validation error by bypassing the cache. |
| void IgnoreRangeRequest(); |
| |
| // Fixes the response headers to match expectations for a HEAD request. |
| void FixHeadersForHead(); |
| |
| // Setups the transaction for reading from the cache entry. |
| int SetupEntryForRead(); |
| |
| // Called to write data to the cache entry. If the write fails, then the |
| // cache entry is destroyed. Future calls to this function will just do |
| // nothing without side-effect. Returns a network error code. |
| int WriteToEntry(int index, int offset, IOBuffer* data, int data_len, |
| const CompletionCallback& callback); |
| |
| // Called to write response_ to the cache entry. |truncated| indicates if the |
| // entry should be marked as incomplete. |
| int WriteResponseInfoToEntry(bool truncated); |
| |
| // Helper function, should be called with result of WriteResponseInfoToEntry |
| // (or the result of the callback, when WriteResponseInfoToEntry returns |
| // ERR_IO_PENDING). Calls DoneWritingToEntry if |result| is not the right |
| // number of bytes. It is expected that the state that calls this will |
| // return whatever net error code this function returns, which currently |
| // is always "OK". |
| int OnWriteResponseInfoToEntryComplete(int result); |
| |
| // Called when we are done writing to the cache entry. |
| void DoneWritingToEntry(bool success); |
| |
| // Returns an error to signal the caller that the current read failed. The |
| // current operation |result| is also logged. If |restart| is true, the |
| // transaction should be restarted. |
| int OnCacheReadError(int result, bool restart); |
| |
| // Called when the cache lock timeout fires. |
| void OnAddToEntryTimeout(base::TimeTicks start_time); |
| |
| // Deletes the current partial cache entry (sparse), and optionally removes |
| // the control object (partial_). |
| void DoomPartialEntry(bool delete_object); |
| |
| // Performs the needed work after receiving data from the network, when |
| // working with range requests. |
| int DoPartialNetworkReadCompleted(int result); |
| |
| // Performs the needed work after receiving data from the cache, when |
| // working with range requests. |
| int DoPartialCacheReadCompleted(int result); |
| |
| // Restarts this transaction after deleting the cached data. It is meant to |
| // be used when the current request cannot be fulfilled due to conflicts |
| // between the byte range request and the cached entry. |
| int DoRestartPartialRequest(); |
| |
| // Resets the relavant internal state to remove traces of internal processing |
| // related to range requests. Deletes |partial_| if |delete_object| is true. |
| void ResetPartialState(bool delete_object); |
| |
| // Resets |network_trans_|, which must be non-NULL. Also updates |
| // |old_network_trans_load_timing_|, which must be NULL when this is called. |
| void ResetNetworkTransaction(); |
| |
| // Returns true if we should bother attempting to resume this request if it |
| // is aborted while in progress. If |has_data| is true, the size of the stored |
| // data is considered for the result. |
| bool CanResume(bool has_data); |
| |
| void UpdateTransactionPattern(TransactionPattern new_transaction_pattern); |
| void RecordHistograms(); |
| |
| // Called to signal completion of asynchronous IO. |
| void OnIOComplete(int result); |
| |
| State next_state_; |
| const HttpRequestInfo* request_; |
| RequestPriority priority_; |
| BoundNetLog net_log_; |
| std::unique_ptr<HttpRequestInfo> custom_request_; |
| HttpRequestHeaders request_headers_copy_; |
| // If extra_headers specified a "if-modified-since" or "if-none-match", |
| // |external_validation_| contains the value of those headers. |
| ValidationHeaders external_validation_; |
| base::WeakPtr<HttpCache> cache_; |
| HttpCache::ActiveEntry* entry_; |
| HttpCache::ActiveEntry* new_entry_; |
| std::unique_ptr<HttpTransaction> network_trans_; |
| CompletionCallback callback_; // Consumer's callback. |
| HttpResponseInfo response_; |
| HttpResponseInfo auth_response_; |
| const HttpResponseInfo* new_response_; |
| std::string cache_key_; |
| Mode mode_; |
| bool reading_; // We are already reading. Never reverts to false once set. |
| bool invalid_range_; // We may bypass the cache for this request. |
| bool truncated_; // We don't have all the response data. |
| bool is_sparse_; // The data is stored in sparse byte ranges. |
| bool range_requested_; // The user requested a byte range. |
| bool handling_206_; // We must deal with this 206 response. |
| bool cache_pending_; // We are waiting for the HttpCache. |
| bool done_reading_; // All available data was read. |
| bool vary_mismatch_; // The request doesn't match the stored vary data. |
| bool couldnt_conditionalize_request_; |
| bool bypass_lock_for_test_; // A test is exercising the cache lock. |
| bool fail_conditionalization_for_test_; // Fail ConditionalizeRequest. |
| scoped_refptr<IOBuffer> read_buf_; |
| int io_buf_len_; |
| int read_offset_; |
| int effective_load_flags_; |
| int write_len_; |
| std::unique_ptr<PartialData> partial_; // We are dealing with range requests. |
| UploadProgress final_upload_progress_; |
| CompletionCallback io_callback_; |
| |
| // Members used to track data for histograms. |
| TransactionPattern transaction_pattern_; |
| ValidationCause validation_cause_; |
| base::TimeTicks entry_lock_waiting_since_; |
| base::TimeTicks first_cache_access_since_; |
| base::TimeTicks send_request_since_; |
| base::Time open_entry_last_used_; |
| base::TimeDelta stale_entry_freshness_; |
| base::TimeDelta stale_entry_age_; |
| |
| int64_t total_received_bytes_; |
| int64_t total_sent_bytes_; |
| |
| // Load timing information for the last network request, if any. Set in the |
| // 304 and 206 response cases, as the network transaction may be destroyed |
| // before the caller requests load timing information. |
| std::unique_ptr<LoadTimingInfo> old_network_trans_load_timing_; |
| |
| ConnectionAttempts old_connection_attempts_; |
| IPEndPoint old_remote_endpoint_; |
| |
| // The helper object to use to create WebSocketHandshakeStreamBase |
| // objects. Only relevant when establishing a WebSocket connection. |
| // This is passed to the underlying network transaction. It is stored here in |
| // case the transaction does not exist yet. |
| WebSocketHandshakeStreamBase::CreateHelper* |
| websocket_handshake_stream_base_create_helper_; |
| |
| BeforeNetworkStartCallback before_network_start_callback_; |
| BeforeHeadersSentCallback before_headers_sent_callback_; |
| |
| base::WeakPtrFactory<Transaction> weak_factory_; |
| |
| DISALLOW_COPY_AND_ASSIGN(Transaction); |
| }; |
| |
| } // namespace net |
| |
| #endif // NET_HTTP_HTTP_CACHE_TRANSACTION_H_ |