Update to v2.14.0 (#14)

### 2.14.0 - Update `TNLCommunicationAgent` to handle reachability behavior changes - The `Network.framwork` can yield an "other" interface when VPN is enabled (on Mac binaries) - Coerce these into _WiFi_ since we don't have a good way to determine the actual interface used at the moment - The `Network.framework` used to yield _WiFi_ for any network connection on a simulator, but now yields _Wired_ - Rename `TNLNetworkReachabilityReachableViaWiFi` to `TNLNetworkReachabilityReachableViaEthernet` and handle both cases as _Ethernet_ ### 2.13.0 - Refactor _Service Unavailable Backoff_ system to be more abstract and support *any* trigger for backoff - All `*serviceUnavailableBackoff*` APIs are refactored into `*backoff*` APIs - Introduce `[TNLGlobalConfiguration backoffSignaler]` - Implement your own `TNLBackoffSignaler` to customize behavior ... or ... - Default will use `TNLSimpleBackoffSignaler` which will signal on *HTTP 503* ### 2.12.0 - Abstract out _Service Unavailable Backoff Behavior_ for customization to be applied - See `[TNLGlobalConfiguration serviceUnavailableBackoffBehaviorProvider]` for providing a custom backoff behavior - Implement your own `TNLServiceUnavailableBackoffBehaviorProvider` to customize behavior - Due to _Service Unavailable_ signaling being opaque, only the HTTP Headers and the URL can be provided - Default will use `TNLSimpleServiceUnavailableBackoffBehaviorProvider` - Exact same behavior as before (introduced in **TNL** prior to v2.0 open sourcing) ### 2.11.0 - Change the `TNLURLSessionAuthChallengeCompletionBlock` arguments - Leave the _disposition_ parameter - Change the _credentials_ parameter of `NSURLCredentials` to be _credentialsOrCancelContext_ of `id` - This will permit `TNLAuthenticationChallengeHandler` instance to be able to cancel the challenge and provide extra context in the resulting error code - Twitter will use this to cancel _401_ login auth challenges when we don't want a redundant request to be made (since it just yields the same response) - This is to facilitate working around the behavior in `NSURLSession` where an _HTTP 401_ response with `WWW-Authenticate` header will always be transparently be retried (even when unmodified yielding the identical _401_ response). - An additionaly problem is that canceling the _401_ response will discard the response's body. If there is information needed in the response body, it will be lost. - Twitter has updated its `WWW-Authenticate` header responses to include additional metadata since the response body cannot be used. - See https://tools.ietf.org/html/rfc7235#section-4.1 - Apple Feedback: `FB7697492` ### 2.10.0 - Add retriable dependencies to `TNLRequestOperation` - Whenever a `TNLRetryPolicyProvider` would yield a retry, that retry will be delayed by the longer of 2 things: 1. The delay provided by the retry policy provider (minimum of 100 milliseconds) 2. Waiting for all `dependencies` on the `TNLRequestOperation` to complete - Normally, all `dependencies` of a retrying `TNLRequestOperation` will be complete before it has started but it is now possible to add dependencies after the request operation has already started to increase the dependencies on a retry starting. ### 2.9.0 - Introduce `tnlcli`, a command-line-interface for __TNL__ - Like _cURL_ but with __TNL__ features - Verbose mode provides all __TNL__ logging to stdout / stderr along with lots of other details
twitter · May 30, 2020 · 16be3da · 16be3da
1 parent c0be8ec
commit 16be3da
Show file tree

Hide file tree

Showing 204 changed files with 4,256 additions and 1,035 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,14 +2,66 @@
 
 ## Info
 
-**Document version:** 2.8.2
+**Document version:** 2.14.0
 
-**Last updated:** 08/30/2019
+**Last updated:** 04/30/2020
 
 **Author:** Nolan O'Brien
 
 ## History
 
+### 2.14.0
+
+- Update `TNLCommunicationAgent` to handle reachability behavior changes
+  - The `Network.framwork` can yield an "other" interface when VPN is enabled (on Mac binaries)
+    - Coerce these into _WiFi_ since we don't have a good way to determine the actual interface used at the moment
+  - The `Network.framework` used to yield _WiFi_ for any network connection on a simulator, but now yields _Wired_
+    - Rename `TNLNetworkReachabilityReachableViaWiFi` to `TNLNetworkReachabilityReachableViaEthernet` and handle both cases as _Ethernet_
+
+### 2.13.0
+
+- Refactor _Service Unavailable Backoff_ system to be more abstract and support *any* trigger for backoff
+  - All `*serviceUnavailableBackoff*` APIs are refactored into `*backoff*` APIs
+  - Introduce `[TNLGlobalConfiguration backoffSignaler]`
+    - Implement your own `TNLBackoffSignaler` to customize behavior ... or ...
+    - Default will use `TNLSimpleBackoffSignaler` which will signal on *HTTP 503*
+
+### 2.12.0
+
+- Abstract out _Service Unavailable Backoff Behavior_ for customization to be applied
+  - See `[TNLGlobalConfiguration serviceUnavailableBackoffBehaviorProvider]` for providing a custom backoff behavior
+    - Implement your own `TNLServiceUnavailableBackoffBehaviorProvider` to customize behavior
+    - Due to _Service Unavailable_ signaling being opaque, only the HTTP Headers and the URL can be provided
+  - Default will use `TNLSimpleServiceUnavailableBackoffBehaviorProvider`
+    - Exact same behavior as before (introduced in **TNL** prior to v2.0 open sourcing)
+
+### 2.11.0
+
+- Change the `TNLURLSessionAuthChallengeCompletionBlock` arguments
+  - Leave the _disposition_ parameter
+  - Change the _credentials_ parameter of `NSURLCredentials` to be _credentialsOrCancelContext_ of `id`
+    - This will permit `TNLAuthenticationChallengeHandler` instance to be able to cancel the challenge and provide extra context in the resulting error code
+    - Twitter will use this to cancel _401_ login auth challenges when we don't want a redundant request to be made (since it just yields the same response)
+      - This is to facilitate working around the behavior in `NSURLSession` where an _HTTP 401_ response with `WWW-Authenticate` header will always be transparently be retried (even when unmodified yielding the identical _401_ response).
+      - An additionaly problem is that canceling the _401_ response will discard the response's body.  If there is information needed in the response body, it will be lost.
+      - Twitter has updated its `WWW-Authenticate` header responses to include additional metadata since the response body cannot be used.
+        - See https://tools.ietf.org/html/rfc7235#section-4.1
+      - Apple Feedback: `FB7697492`
+
+### 2.10.0
+
+- Add retriable dependencies to `TNLRequestOperation`
+  - Whenever a `TNLRetryPolicyProvider` would yield a retry, that retry will be delayed by the longer of 2 things:
+    1. The delay provided by the retry policy provider (minimum of 100 milliseconds)
+    2. Waiting for all `dependencies` on the `TNLRequestOperation` to complete
+    - Normally, all `dependencies` of a retrying `TNLRequestOperation` will be complete before it has started but it is now possible to add dependencies after the request operation has already started to increase the dependencies on a retry starting.
+
+### 2.9.0
+
+- Introduce `tnlcli`, a command-line-interface for __TNL__
+  - Like _cURL_ but with __TNL__ features
+  - Verbose mode provides all __TNL__ logging to stdout / stderr along with lots of other details
+
 ### 2.8.2
 
 - Add _expensive_ and _constrained_ conditions to the reachability flags on iOS 13+

diff --git a/README.md b/README.md
@@ -508,9 +508,44 @@ APPRetrieveBlobRequest *request = [[APPRetrieveBlobRequest alloc] initWithBlobId
  // APISendMessageResponse's implementation for messageId is just:
  //    return self.result[@"newMessageId"];
 ```
+
+## Using the Command-Line-Interface
+
+__Twitter Network Layer__ includes a target for building a _macOS_ tool called `tnlcli`.  You can build this tool
+run it from _Terminal_ from you _Mac_, similar to _cURL_ or other networking command line utilities.
+
+### Usage
+
+```
+Usage: tnlcli [options] url
+
+    Example: tnlcli --request-method HEAD --response-header-mode file,print --response-header-file response_headers.json https://google.com
+
+Argument Options:
+-----------------
+
+    --request-config-file <filepath>     TNLRequestConfiguration as a json file
+    --request-headers-file <filepath>    json file of key-value-pairs for using as headers
+    --request-body-file <filepath>       file for the HTTP body
+
+    --request-header "Field: Value"      A header to provide with the request (will override the header if also in the request header file). Can provide multiple headers.
+    --request-config "config: value"     A config setting for the TNLRequestConfiguration of the request (will override the config if also in the request config file). Can provide multiple configs.
+    --request-method <method>            HTTP Method from Section 9 in HTTP/1.1 spec (RFC 2616), such as GET, POST, HEAD, etc
+
+    --response-body-mode <mode>          "file" or "print" or a combo using commas
+    --response-body-file <filepath>      file for the response body to save to (requires "file" for --response-body-mode
+    --response-headers-mode <mode>       "file" or "print" or a combo using commas
+    --response-headers-file <filepath>   file for the response headers to save to (as json)
+
+    --dump-cert-chain-directory <dir>    directory for the certification chain to be dumped to (as DER files)
+
+    --verbose                            Will print verbose information and force the --response-body-mode and --responde-headers-mode to have "print".
+    --version                            Will print ther version information.
+```
+
 # License
 
-Copyright 2014-2018 Twitter, Inc.
+Copyright 2014-2020 Twitter, Inc.
 
 Licensed under the Apache License, Version 2.0: https://www.apache.org/licenses/LICENSE-2.0
 

diff --git a/Source/NSCachedURLResponse+TNLAdditions.h b/Source/NSCachedURLResponse+TNLAdditions.h
@@ -3,7 +3,7 @@
 //  TwitterNetworkLayer
 //
 //  Created on 11/22/15.
-//  Copyright © 2015 Twitter. All rights reserved.
+//  Copyright © 2020 Twitter. All rights reserved.
 //
 
 #import <Foundation/Foundation.h>

diff --git a/Source/NSCachedURLResponse+TNLAdditions.m b/Source/NSCachedURLResponse+TNLAdditions.m
@@ -3,7 +3,7 @@
 //  TwitterNetworkLayer
 //
 //  Created on 11/22/15.
-//  Copyright © 2015 Twitter. All rights reserved.
+//  Copyright © 2020 Twitter. All rights reserved.
 //
 
 #import "NSCachedURLResponse+TNLAdditions.h"

diff --git a/Source/NSCoder+TNLAdditions.h b/Source/NSCoder+TNLAdditions.h
@@ -2,8 +2,8 @@
 //  NSCoder+TNLAdditions.h
 //  TwitterNetworkLayer
 //
-//  Created by Nolan on 6/5/19.
-//  Copyright © 2019 Twitter. All rights reserved.
+//  Created on 6/5/19.
+//  Copyright © 2020 Twitter. All rights reserved.
 //
 
 #import <Foundation/Foundation.h>

diff --git a/Source/NSCoder+TNLAdditions.m b/Source/NSCoder+TNLAdditions.m
@@ -2,8 +2,8 @@
 //  NSCoder+TNLAdditions.m
 //  TwitterNetworkLayer
 //
-//  Created by Nolan on 6/5/19.
-//  Copyright © 2019 Twitter. All rights reserved.
+//  Created on 6/5/19.
+//  Copyright © 2020 Twitter. All rights reserved.
 //
 
 #import "NSCoder+TNLAdditions.h"

diff --git a/Source/NSData+TNLAdditions.h b/Source/NSData+TNLAdditions.h
@@ -3,7 +3,7 @@
 //  TwitterNetworkLayer
 //
 //  Created on 9/9/16.
-//  Copyright © 2016 Twitter. All rights reserved.
+//  Copyright © 2020 Twitter. All rights reserved.
 //
 
 #import <Foundation/Foundation.h>

diff --git a/Source/NSData+TNLAdditions.m b/Source/NSData+TNLAdditions.m
@@ -3,7 +3,7 @@
 //  TwitterNetworkLayer
 //
 //  Created on 9/9/16.
-//  Copyright © 2016 Twitter. All rights reserved.
+//  Copyright © 2020 Twitter. All rights reserved.
 //
 
 #import <objc/runtime.h>

diff --git a/Source/NSDictionary+TNLAdditions.h b/Source/NSDictionary+TNLAdditions.h
@@ -3,7 +3,7 @@
 //  TwitterNetworkLayer
 //
 //  Created on 8/24/14.
-//  Copyright (c) 2014 Twitter. All rights reserved.
+//  Copyright © 2020 Twitter. All rights reserved.
 //
 
 #import <Foundation/Foundation.h>

diff --git a/Source/NSDictionary+TNLAdditions.m b/Source/NSDictionary+TNLAdditions.m
@@ -3,7 +3,7 @@
 //  TwitterNetworkLayer
 //
 //  Created on 8/24/14.
-//  Copyright (c) 2014 Twitter. All rights reserved.
+//  Copyright © 2020 Twitter. All rights reserved.
 //
 
 #import "NSDictionary+TNLAdditions.h"

diff --git a/Source/NSHTTPCookieStorage+TNLAdditions.h b/Source/NSHTTPCookieStorage+TNLAdditions.h
@@ -3,7 +3,7 @@
 //  TwitterNetworkLayer
 //
 //  Created on 2/9/15.
-//  Copyright (c) 2015 Twitter. All rights reserved.
+//  Copyright © 2020 Twitter. All rights reserved.
 //
 
 #import <Foundation/Foundation.h>

diff --git a/Source/NSHTTPCookieStorage+TNLAdditions.m b/Source/NSHTTPCookieStorage+TNLAdditions.m
@@ -3,7 +3,7 @@
 //  TwitterNetworkLayer
 //
 //  Created on 2/9/15.
-//  Copyright (c) 2015 Twitter. All rights reserved.
+//  Copyright © 2020 Twitter. All rights reserved.
 //
 
 #import "NSHTTPCookieStorage+TNLAdditions.h"

diff --git a/Source/NSNumber+TNLURLCoding.h b/Source/NSNumber+TNLURLCoding.h
@@ -3,7 +3,7 @@
 //  TwitterNetworkLayer
 //
 //  Created on 9/17/15.
-//  Copyright © 2015 Twitter. All rights reserved.
+//  Copyright © 2020 Twitter. All rights reserved.
 //
 
 #import <Foundation/Foundation.h>
@@ -26,7 +26,7 @@ NS_ASSUME_NONNULL_BEGIN
  For convenience, `TNLBoolean` is provided so that the object can be encoded as `@"true"` or
  `@"false"` based on the `boolValue` of the object always, regardless of encoding format or options.
  */
-@interface NSNumber (TNLURLCoding)
+@interface NSNumber (TNLBooleanCoding)
 
 /**
  Returns a `TNLBoolean` object that will encode as `@"true"` or `@"false"` based on the receiver's
@@ -41,6 +41,27 @@ NS_ASSUME_NONNULL_BEGIN
 
 @end
 
+/**
+ Category for converting numbers to strings
+ */
+@interface NSNumber (TNLStringCoding)
+
+/**
+ For most `NSNumber` instances, this is a faster way of getting the string value than `stringValue`
+ or `descriptionWithLocale:`.
+ Interally falls back to `descriptionWithLocale:` if it cannot convert (never encountered a case yet).
+
+ Random sampling on 124,000 NSNumbers on 1 thread (via Xcode Simulator on 10-core 3GHz Xeon W)
+ -[NSNumber stringValue] = 1.149726s
+ -[NSNumber tnl_quickStringValue] = 0.775426s
+ Pretty consistently achieves 33% speedup on average.
+ Using `TNLURLEncodeDictionary` for converting a `TNLRequestConfiguration` into an identifier string
+ (very regular within TNL) has more than 60% speedup.
+ */
+- (NSString *)tnl_quickStringValue;
+
+@end
+
 /**
  `TNLBoolean` is a convenience object in case it is desirable to have an object for URL encoding
  that is boolean and will yield either `@"true"` or `@"false"` always instead of conditionally based

diff --git a/Source/NSNumber+TNLURLCoding.m b/Source/NSNumber+TNLURLCoding.m
@@ -3,14 +3,14 @@
 //  TwitterNetworkLayer
 //
 //  Created on 9/17/15.
-//  Copyright © 2015 Twitter. All rights reserved.
+//  Copyright © 2020 Twitter. All rights reserved.
 //
 
 #import "NSNumber+TNLURLCoding.h"
 
 NS_ASSUME_NONNULL_BEGIN
 
-@implementation NSNumber (TNLURLCoding)
+@implementation NSNumber (TNLBooleanCoding)
 
 - (BOOL)tnl_isBoolean
 {

diff --git a/Source/NSOperationQueue+TNLSafety.h b/Source/NSOperationQueue+TNLSafety.h
@@ -3,7 +3,7 @@
 //  TwitterNetworkLayer
 //
 //  Created on 8/14/15.
-//  Copyright (c) 2015 Twitter. All rights reserved.
+//  Copyright © 2020 Twitter. All rights reserved.
 //
 
 #import <Foundation/Foundation.h>

diff --git a/Source/NSOperationQueue+TNLSafety.m b/Source/NSOperationQueue+TNLSafety.m
@@ -3,7 +3,7 @@
 //  TwitterNetworkLayer
 //
 //  Created on 8/14/15.
-//  Copyright (c) 2015 Twitter. All rights reserved.
+//  Copyright © 2020 Twitter. All rights reserved.
 //
 
 #import "NSOperationQueue+TNLSafety.h"
@@ -84,16 +84,18 @@ - (void)addOperation:(NSOperation *)op
         return;
     }
 
-    dispatch_async(_queue, ^{
+    tnl_dispatch_async_autoreleasing(_queue, ^{
         [self->_operations addObject:op];
         [op addObserver:self forKeyPath:@"isFinished" options:NSKeyValueObservingOptionNew | NSKeyValueObservingOptionInitial context:NULL];
 
         // There are race conditions where the isFinished KVO may never be observed.
         // Use this async check to weed out any early finishing operations that we didn't observe finishing.
         dispatch_after(dispatch_time(DISPATCH_TIME_NOW, (int64_t)(TNLOperationSafetyGuardCheckForAlreadyFinishedOperationDelay * NSEC_PER_SEC)), self->_queue, ^{
-            if (op.isFinished) {
-                // Call our KVO observer to unify the code path for removing the observer
-                [self observeValueForKeyPath:@"isFinished" ofObject:op change:@{ NSKeyValueChangeNewKey : @YES } context:NULL];
+            @autoreleasepool {
+                if (op.isFinished) {
+                    // Call our KVO observer to unify the code path for removing the observer
+                    [self observeValueForKeyPath:@"isFinished" ofObject:op change:@{ NSKeyValueChangeNewKey : @YES } context:NULL];
+                }
             }
         });
     });
@@ -119,7 +121,9 @@ - (void)observeValueForKeyPath:(nullable NSString *)keyPath ofObject:(nullable i
     if ([keyPath isEqualToString:@"isFinished"] && [change[NSKeyValueChangeNewKey] boolValue]) {
         NSOperation *op = object;
         dispatch_after(dispatch_time(DISPATCH_TIME_NOW, (int64_t)(TNLOperationSafetyGuardRemoveOperationAfterFinishedDelay * NSEC_PER_SEC)), _queue, ^{
-            [self _tnl_background_removeOperation:op];
+            @autoreleasepool {
+                [self _tnl_background_removeOperation:op];
+            }
         });
     }
 }

diff --git a/Source/NSURL+TNLAdditions.h b/Source/NSURL+TNLAdditions.h
@@ -3,7 +3,7 @@
 //  TwitterNetworkLayer
 //
 //  Created on 12/20/16.
-//  Copyright © 2016 Twitter. All rights reserved.
+//  Copyright © 2020 Twitter. All rights reserved.
 //
 
 #import <Foundation/Foundation.h>

diff --git a/Source/NSURL+TNLAdditions.m b/Source/NSURL+TNLAdditions.m
@@ -3,7 +3,7 @@
 //  TwitterNetworkLayer
 //
 //  Created on 12/20/16.
-//  Copyright © 2016 Twitter. All rights reserved.
+//  Copyright © 2020 Twitter. All rights reserved.
 //
 
 #import "NSURL+TNLAdditions.h"

diff --git a/Source/NSURLAuthenticationChallenge+TNLAdditions.h b/Source/NSURLAuthenticationChallenge+TNLAdditions.h
@@ -0,0 +1,34 @@
+//
+//  NSURLAuthenticationChallenge+TNLAdditions.h
+//  TwitterNetworkLayer
+//
+//  Created on 3/17/20.
+//  Copyright © 2020 Twitter. All rights reserved.
+//
+
+#import <Foundation/Foundation.h>
+
+NS_ASSUME_NONNULL_BEGIN
+
+//! `NSURLAuthenticationMethodOAuth` which Apple uses but doesn't expose
+FOUNDATION_EXTERN NSString * const TNLNSURLAuthenticationMethodOAuth;
+//! `NSURLAuthenticationMethodOAuth2` which Apple uses but doesn't expose
+FOUNDATION_EXTERN NSString * const TNLNSURLAuthenticationMethodOAuth2;
+
+//! Is the given challenge method a password challenge?
+FOUNDATION_EXTERN BOOL TNLIsPasswordChallengeAuthenticationChallengeMethod(NSString * __nullable method);
+
+/**
+ __TNL__ additions for `NSURLAuthenticationChallenge`
+ */
+@interface NSURLAuthenticationChallenge (TNLAdditions)
+
+/**
+ @return `YES` if this challenge is an HTTP WWW Authenticate based challenge from an HTTP 401.
+ @note By default, __TNL__ will reject this kind of challenge's protection space if there is no `proposedCredential`, use `TNLAuthenticationChallengeHandler` to specify a different behavior if desired.  This differs from `NSURLSession` default behavior!
+ */
+- (BOOL)tnl_isHTTPWWWAuthenticationChallenge;
+
+@end
+
+NS_ASSUME_NONNULL_END