Workaround for caching with iOS 8 and NSURLSession.

Observationally, we've seen the NSURL loading system fail to insert
items into the NSURLCache when using NSURLSession and iOS 7/8.
NSURLConnection works fine on all these, and NSURLSession works fine on
iOS 9. Best guess is there's a bug in the NSURLProtocol implementation
that fails to insert into the cache.

So, here we are creating a workaround for that specific case. CocoaSPDY
will buffer the data internally, up to a certain size limit based on the
cache size, and will manually insert into the cache when the response is
done. This could potentially be expanded in the future for unclaimed,
finished push responses, but for now those are excluded.

This change also adds a few additional caching-related unit tests.

README.md

@@ -67,6 +67,29 @@ Most existing SPDY implementations use a TLS extension called Next Protocol Impl
 In order to aid with protocol inference, this SPDY implementation includes a non-standard settings id at index 0: `SETTINGS_MINOR_VERSION`. This is necessary to differentiate between SPDY/3 and SPDY/3.1 connections that were not negotiated with NPN, since only the major version is included in the frame header. Because not all servers may support this particular setting, sending it can be disabled at runtime through protocol configuration.
 
 ## Implementation Notes
+### Caching with NSURLCache
+CocoaSPDY partially supports HTTP caching using NSURLCaches, though there are a number of caveats. The default policy for `NSURLConnection` is to disable caching, in order to maintain backward-compatibility and mimize risk. CocoaSPDY does not perform HEAD validation requests, so any cached response that will require revalidation with the server will result in a full request and response. 
+
+**NSURLConnection**
+* Ensure the global `[NSURLCache sharedCached]` is set to the desired `NSURLCache`
+* Set the `NSMutableURLRequest.cachePolicy` to the desired policy (`NSURLRequestUseProtocolCachePolicy` will result in no caching)
+
+**NSURLSession**
+* Set the `NSMutableURLRequest.SPDYURLSession` to your NSURLSession instance
+* Set the `NSURLSessionConfiguration.URLCache` to the desired `NSURLCache`
+* Set the `NSURLSessionConfiguration.cachePolicy` to the desired policy (can be left as `NSURLRequestUseProtocolCachePolicy`)
+
+**Request/response requirements**
+* Request must not include an `Authorization` header.
+* Request must be a GET.
+* Response must include a `Date` header.
+* Response must include a `Cache-Control` header with a "max-age" parameter set to a non-zero value. And when retrieving the cached response, this must not result in a stale item.
+* The `Cache-Control` response header must not have "no-cache", "no-store", or "must-revalidate" in it.
+* To prevent caching of a response, set `Cache-Control: no-store` in the request.
+* For all the requirements, see implementation details at https://github.com/twitter/CocoaSPDY/blob/develop/SPDY/SPDYCacheStoragePolicy.m
+
+Essentially, you must opt-in with `NSURLConnection` by setting a cache policy or with `NSURLSession` by configuring a cache. The response must be cacheable and have a max-age defined, and the request must be a GET request. The cached response must be usable without revalidation.
+
 ### CRIME attack
 The [CRIME attack](http://en.wikipedia.org/wiki/CRIME) is a plaintext injection technique that exploits the fact that information can be inferred from compressed content length to potentially reveal the contents of an encrypted stream. This is a serious issue for browsers, which are subject to hijacks that may allow an attacker to issue an arbitrary number of requests with known plaintext header content and observe the resulting effect on compression. 
 

SPDY/SPDYStream.m

@@ -72,6 +72,10 @@ @implementation SPDYStream
 
     NSURLRequest *_pushRequest;  // stored because we need a strong reference, _request is weak.
     NSHTTPURLResponse *_response;
+
+    NSURLCacheStoragePolicy _cachePolicy;
+    NSMutableData *_cacheDataBuffer; // only used for manual caching.
+    NSInteger _cacheMaxItemSize;
 }
 
 - (instancetype)initWithProtocol:(SPDYProtocol *)protocol
@@ -332,6 +336,9 @@ - (void)_close
     [self markUnblocked];  // just in case. safe if already unblocked.
     _metadata.blockedMs = _blockedElapsed * 1000;
 
+    // Manually make the willCacheResponse callback when needed
+    [self _storeCacheResponse];
+
     [_client URLProtocolDidFinishLoading:_protocol];
 
     if (_delegate && [_delegate respondsToSelector:@selector(streamClosed:)]) {
@@ -585,11 +592,24 @@ - (void)didReceiveResponse
         return;
     }
 
-    if (_client) {
-        NSURLCacheStoragePolicy cachePolicy = SPDYCacheStoragePolicy(_request, _response);
-        [_client URLProtocol:_protocol
-          didReceiveResponse:_response
-          cacheStoragePolicy:cachePolicy];
+    _cachePolicy = SPDYCacheStoragePolicy(_request, _response);
+    [_client URLProtocol:_protocol
+      didReceiveResponse:_response
+      cacheStoragePolicy:_cachePolicy];
+
+    // Prepare for manual caching, if needed
+    NSURLCache *cache = _protocol.associatedSession.configuration.URLCache;
+    if (_cachePolicy != NSURLCacheStorageNotAllowed &&  // cacheable?
+        [self _shouldUseManualCaching] &&                // hack needed and NSURLSession used?
+        cache != nil &&                                 // cache configured (NSURLSession-specific)?
+        _local) {                                       // not a push request?
+
+        // The NSURLCache has a heuristic to limit the max size of items based on the capacity of the
+        // cache. This is our attempt to mimic that behavior and prevent unlimited buffering of large
+        // responses. These numbers were found by manually experimenting and are only approximate.
+        // See SPDYNSURLCachingTest testResponseNearItemCacheSize_DoesUseCache.
+        _cacheDataBuffer = [[NSMutableData alloc] init];
+        _cacheMaxItemSize = MAX(cache.memoryCapacity * 0.05, cache.diskCapacity * 0.01);
     }
 }
 
@@ -689,7 +709,7 @@ - (void)didLoadData:(NSData *)data
             NSUInteger inflatedLength = DECOMPRESSED_CHUNK_LENGTH - _zlibStream.avail_out;
             inflatedData.length = inflatedLength;
             if (inflatedLength > 0) {
-                [_client URLProtocol:_protocol didLoadData:inflatedData];
+                [self _didLoadDataChunk:inflatedData];
             }
 
             // This can happen if the decompressed data is size N * DECOMPRESSED_CHUNK_LENGTH,
@@ -711,7 +731,77 @@ - (void)didLoadData:(NSData *)data
         }
     } else {
         NSData *dataCopy = [[NSData alloc] initWithBytes:data.bytes length:dataLength];
-        [_client URLProtocol:_protocol didLoadData:dataCopy];
+        [self _didLoadDataChunk:dataCopy];
+    }
+}
+
+- (void)_didLoadDataChunk:(NSData *)data
+{
+    [_client URLProtocol:_protocol didLoadData:data];
+
+    if (_cacheDataBuffer) {
+        NSUInteger bufferSize = _cacheDataBuffer.length + data.length;
+        if (bufferSize < _cacheMaxItemSize) {
+            [_cacheDataBuffer appendData:data];
+        } else {
+            // Throw away anything already buffered, it's going to be too big
+            _cacheDataBuffer = nil;
+        }
+    }
+}
+
+// NSURLSession on iOS 8 and iOS 7 does not cache items. Seems to be a bug with its interation
+// with NSURLProtocol. This flag represents whether our workaround, to insert into the cache
+// ourselves, is turned on.
+- (bool)_shouldUseManualCaching
+{
+    NSInteger osVersion = 0;
+    NSProcessInfo *processInfo = [NSProcessInfo processInfo];
+    if ([processInfo respondsToSelector:@selector(operatingSystemVersion)]) {
+        osVersion = [processInfo operatingSystemVersion].majorVersion;
+    }
+
+    // iOS 8 and earlier and using NSURLSession
+    return (osVersion <= 8 && _protocol.associatedSession != nil && _protocol.associatedSessionTask != nil);
+}
+
+- (void)_storeCacheResponse
+{
+    if (_cacheDataBuffer == nil) {
+        return;
+    }
+
+    NSCachedURLResponse *cachedResponse;
+    cachedResponse = [[NSCachedURLResponse alloc] initWithResponse:_response
+                                                              data:_cacheDataBuffer
+                                                          userInfo:nil
+                                                     storagePolicy:_cachePolicy];
+    NSURLCache *cache = _protocol.associatedSession.configuration.URLCache;
+    NSURLSessionDataTask *dataTask = (NSURLSessionDataTask *)_protocol.associatedSessionTask;
+
+    // Make "official" willCacheResponse callback to app, bypassing the NSURL loading system.
+    id<NSURLSessionDataDelegate> delegate = (id)_protocol.associatedSession.delegate;
+    if ([delegate respondsToSelector:@selector(URLSession:dataTask:willCacheResponse:completionHandler:)]) {
+        NSOperationQueue *queue = _protocol.associatedSession.delegateQueue;
+        [(queue) ?: [NSOperationQueue mainQueue] addOperationWithBlock:^{
+            [delegate URLSession:_protocol.associatedSession dataTask:dataTask willCacheResponse:cachedResponse completionHandler:^(NSCachedURLResponse * cachedResponse) {
+                // This block may execute asynchronously at any time. No need to come back to the SPDY/NSURL thread
+                if (cachedResponse) {
+                    if ([cache respondsToSelector:@selector(storeCachedResponse:forDataTask:)]) {
+                        [cache storeCachedResponse:cachedResponse forDataTask:dataTask];
+                    } else {
+                        [cache storeCachedResponse:cachedResponse forRequest:_request];
+                    }
+                }
+            }];
+        }];
+    } else {
+        // willCacheResponse delegate not implemented. Default behavior is to cache.
+        if ([cache respondsToSelector:@selector(storeCachedResponse:forDataTask:)]) {
+            [cache storeCachedResponse:cachedResponse forDataTask:dataTask];
+        } else {
+            [cache storeCachedResponse:cachedResponse forRequest:_request];
+        }
     }
 }
 

SPDYUnitTests/SPDYIntegrationTestHelper.h

@@ -29,11 +29,13 @@
 - (BOOL)didLoadFromNetwork;
 - (BOOL)didLoadFromCache;
 - (BOOL)didGetResponse;
+- (BOOL)didLoadData;
 - (BOOL)didGetError;
 - (BOOL)didCacheResponse;
 
 - (void)reset;
 - (void)loadRequest:(NSURLRequest *)request;
+- (void)provideResponseWithStatus:(NSUInteger)status cacheControl:(NSString *)cacheControl date:(NSDate *)date dataChunks:(NSArray *)dataChunks;
 - (void)provideResponseWithStatus:(NSUInteger)status cacheControl:(NSString *)cacheControl date:(NSDate *)date;
 - (void)provideBasicUncacheableResponse;
 - (void)provideBasicCacheableResponse;

SPDYUnitTests/SPDYIntegrationTestHelper.m

@@ -43,19 +43,24 @@ - (instancetype)init
 
 - (BOOL)didLoadFromNetwork
 {
-    return self.didGetResponse && _stream != nil;
+    return self.didGetResponse && self.didLoadData && _stream != nil;
 }
 
 - (BOOL)didLoadFromCache
 {
-    return self.didGetResponse && _stream == nil;
+    return self.didGetResponse && self.didLoadData && _stream == nil;
 }
 
 - (BOOL)didGetResponse
 {
     return _response != nil;
 }
 
+- (BOOL)didLoadData
+{
+    return _data.length > 0;
+}
+
 - (BOOL)didGetError
 {
     return _connectionError != nil;
@@ -100,12 +105,10 @@ - (NSString *)dateHeaderValue:(NSDate *)date
     return string;
 }
 
-- (void)provideResponseWithStatus:(NSUInteger)status cacheControl:(NSString *)cacheControl date:(NSDate *)date
+- (void)provideResponseWithStatus:(NSUInteger)status cacheControl:(NSString *)cacheControl date:(NSDate *)date dataChunks:(NSArray *)dataChunks
 {
     [SPDYMockSessionManager shared].streamQueuedBlock = ^(SPDYStream *stream) {
         _stream = stream;
-        uint8_t dataBytes[] = {1};
-        NSData *data = [NSData dataWithBytes:dataBytes length:1];
         NSMutableDictionary *headers = [NSMutableDictionary dictionaryWithDictionary:@{
                 @":status": [@(status) stringValue],
                 @":version": @"1.1",
@@ -119,10 +122,19 @@ - (void)provideResponseWithStatus:(NSUInteger)status cacheControl:(NSString *)ca
 
         [stream mergeHeaders:headers];
         [stream didReceiveResponse];
-        [stream didLoadData:data];
+        for (NSData *data in dataChunks) {
+            [stream didLoadData:data];
+        }
     };
 }
 
+- (void)provideResponseWithStatus:(NSUInteger)status cacheControl:(NSString *)cacheControl date:(NSDate *)date
+{
+    uint8_t dataBytes[] = {1};
+    NSArray *dataChunks = @[ [NSData dataWithBytes:dataBytes length:1] ];
+    [self provideResponseWithStatus:status cacheControl:cacheControl date:date dataChunks:dataChunks];
+}
+
 - (void)provideBasicUncacheableResponse
 {
     [self provideResponseWithStatus:200 cacheControl:@"no-store, no-cache, must-revalidate" date:[NSDate date]];
@@ -157,6 +169,7 @@ - (NSString *)description
     NSDictionary *params = @{
                              @"didLoadFromNetwork": @([self didLoadFromNetwork]),
                              @"didGetResponse": @([self didGetResponse]),
+                             @"didLoadData": @([self didLoadData]),
                              @"didGetError": @([self didGetError]),
                              @"didCacheResponse": @([self didCacheResponse]),
                              @"stream": _stream ?: @"<nil>",
@@ -237,6 +250,7 @@ - (instancetype)init
     }
     return self;
 }
+
 - (void)loadRequest:(NSMutableURLRequest *)request
 {
     [super loadRequest:request];