diff options
-rw-r--r-- | src/objective-c/NetworkTransitionBehavior.md | 48 |
1 files changed, 27 insertions, 21 deletions
diff --git a/src/objective-c/NetworkTransitionBehavior.md b/src/objective-c/NetworkTransitionBehavior.md index a0c2e781c4..73b5e6f522 100644 --- a/src/objective-c/NetworkTransitionBehavior.md +++ b/src/objective-c/NetworkTransitionBehavior.md @@ -15,8 +15,10 @@ The expected gRPC iOS channel and network transition behaviors are: happens when * The network interface is no longer available, e.g. WiFi or cellular interface is turned off or goes offline, airplane mode turned on, etc; - * The underlying TCP connection is no longer valid, e.g. WiFi connects to another hotspot, cellular data switched from LTE to 4G, etc; - * A network interface more preferable by the OS is valid, e.g. WiFi gets connected when the channel connects via cellular. + * The underlying TCP connection is no longer valid, e.g. WiFi connects to + another hotspot, cellular data switched from LTE to 4G, etc; + * A network interface more preferable by the OS is valid, e.g. WiFi gets + connected when the channel is already connected via cellular. * A channel in TRANSIENT\_FAILURE state attempts reconnection on start of the next call to the same host, but only after a certain backoff period (see corresponding @@ -27,34 +29,38 @@ The expected gRPC iOS channel and network transition behaviors are: * Conncetion failed; calls will be failed and return UNAVAILABLE status code; * The call's deadline is reached; the call will fail and return DEADLINE\_EXCEEDED status code. + The length of backoff period of a channel is reset whenever a connection + attempt is successful. ## Implementations ### gRPC iOS with TCP Sockets gRPC's default implementation is to use TCP sockets for networking. It turns out that although Apple supports this type of usage, it is [not recommended by Apple](https://developer.apple.com/library/archive/documentation/NetworkingInternetWeb/Conceptual/NetworkingOverview/SocketsAndStreams/SocketsAndStreams.html) -and is also flawed. +and has some issues described below. -#### TCP Sockets Issues +#### Issues with TCP Sockets The TCP sockets on iOS is flawed in that it does not reflect the viability of -the channel connection. Particularly, we found the following issues related to -TCP sockets: -* When a TCP sockets connection is established on cellular data and WiFi +the channel connection. Particularly, we observed the following issues when +using TCP sockets: +* When a TCP socket connection is established on cellular data and WiFi becomes available, the TCP socket neither return an error event nor continue sending/receiving data on it, but still accepts write on it. -* The TCP sockets does not report certain events that happens in the +* A TCP sockets does not report certain events that happen in the background. When a TCP connection breaks in the background for the reason like WiFi connects to another hotspot, the socket neither return an error nor continue sending/receiving data on it, but still accepts write on it. +In both situations, the user will see the call hangs for an extended period of +time before the TCP socket times out. -#### gRPC iOS resolutions +#### gRPC iOS library's resolution to TCP socket issues We introduced [`ConnectivityMonitor`](https://developer.apple.com/library/archive/documentation/NetworkingInternetWeb/Conceptual/NetworkingOverview/SocketsAndStreams/SocketsAndStreams.html) -in gRPC iOS library to alleviate these issues in TCP sockets, which changes the -network transition behaviors a bit. +in gRPC iOS library v0.14.0 to alleviate these issues in TCP sockets, +which changes the network transition behaviors a bit. -We classfy network connectivity state of the device into three categories based -on flags obtained from `SCNetworkReachability` API: +We classify network connectivity state of the device into three categories +based on flags obtained from `SCNetworkReachability` API: | Reachable | ConnectionRequired | IsWWAN | **Category** | |:---------:|:------------------:|:------:|:------------:| @@ -74,13 +80,13 @@ To solve that issue the best solution is to switch to CFStream implementation which eliminates all of them. ### gRPC iOS with CFStream -gRPC iOS with CFStream implementation uses Apple's networking API to make -connections. It resolves the issues above that is known to TCP sockets on iOS. -Users are recommended to use this implementation rather than TCP socket -implementation. The detailed behavior of streams in CFStream is not documented -by Apple, but our experiments show that it accords to the expected behaviors. -With CFStream implementation, an event is always received when the underlying -connection is no longer viable. For more detailed information and usages of -CFStream implementation, refer to the +gRPC iOS with CFStream implementation (introduced in v1.13.0) uses Apple's +networking API to make connections. It resolves the issues with TCP sockets +mentioned above. Users are recommended to use this implementation rather than +TCP socket implementation. The detailed behavior of streams in CFStream is not +documented by Apple, but our experiments show that it accords to the expected +behaviors. With CFStream implementation, an event is always received when the +underlying connection is no longer viable. For more detailed information and +usages of CFStream implementation, refer to the [user guide](https://github.com/grpc/grpc/blob/master/src/objective-c/README-CFSTREAM.md). |