prepare 1.0.0-beta23 release

.circleci/config.yml

@@ -24,6 +24,9 @@ jobs:
     docker:
       - image: ldcircleci/ld-xamarin-android-linux:api27
 
+    environment:
+      LD_SKIP_XML_DOCS: 1  # there seems to be a bug in Xamarin Android builds on Linux that makes the XML build step fail
+
     steps:
       - checkout
 

.gitignore

@@ -6,6 +6,7 @@
 [Bb]in/
 packages/
 TestResults/
+test-packages/
 
 # globs
 Makefile.in

CHANGELOG.md

@@ -3,6 +3,29 @@
 All notable changes to the LaunchDarkly Client-side SDK for Xamarin will be documented in this file.
 This project adheres to [Semantic Versioning](http://semver.org).
 
+## [1.0.0-beta23] - 2019-08-30
+### Added:
+- XML documentation comments are now included in the package, so they should be visible in Visual Studio for all LaunchDarkly types and methods.
+
+### Changed:
+- The `Online` property of `LdClient` was not useful because it could reflect either a deliberate change to whether the client is allowed to go online (that is, it would be false if you had set `Offline` to true in the configuration), _or_ a change in network availability. It has been removed and replaced with `Offline`, which is only used for explicitly forcing the client to be offline. This is a read-only property; to set it, use `SetOffline` or `SetOfflineAsync`.
+- The synchronous `Identify` method now requires a timeout parameter, and returns false if it times out.
+- `LdClient.Initialized` is now a property, not a method.
+- `LdClient.Version` is now static, since it describes the entire package rather than a client instance.
+- In `Configuration` and `IConfigurationBuilder`, `HttpClientTimeout` is now `ConnectionTimeout`.
+- There is now more debug-level logging for stream connection state changes.
+
+### Fixed:
+- Network availability changes are now detected in both Android and iOS. The SDK should not attempt to connect to LaunchDarkly if the OS has told it that the network is unavailable.
+- Background polling was never enabled, even if `Configuration.EnableBackgroundUpdating` was true.
+- When changing from offline to online by setting `client.Online = true`, or calling `await client.SetOnlineAsync(true)` (the equivalent now would be `client.Offline = false`, etc.), the SDK was returning too soon before it had acquired flags from LaunchDarkly. The known issues in 1.0.0-beta22 have been fixed.
+- If the SDK was online and then was explicitly set to be offline, or if network connectivity was lost, the SDK was still attempting to send analytics events. It will no longer do so.
+- If the SDK was originally set to be offline and then was put online, the SDK was _not_ sending analytics events. Now it will.
+
+### Removed:
+- `ConfigurationBuilder.UseReport`. Due to [an issue](https://github.com/xamarin/xamarin-android/issues/3544) with the Android implementation of HTTP, the HTTP REPORT method is not currently usable in the Xamarin SDK.
+- `IConnectionManager` interface. The SDK now always uses a platform-appropriate implementation of this logic.
+
 ## [1.0.0-beta22] - 2019-08-12
 ### Changed:
 - By default, on Android and iOS the SDK now uses Xamarin's platform-specific implementations of `HttpMessageHandler` that are based on native APIs, rather than the basic `System.Net.Http.HttpClientHandler`. This improves performance and stability on mobile platforms.

CONTRIBUTING.md

@@ -50,3 +50,13 @@ You can run the mobile test projects from Visual Studio (the iOS tests require M
 Note that the mobile unit tests currently do not cover background-mode behavior or connectivity detection.
 
 ### Packaging/releasing
+
+Run `./scripts/update-version.sh <VERSION>` to set the project version.
+
+Run `./scripts/release.sh` to build the project for all target frameworks and upload the package to NuGet. You must have already configured the necessary NuGet key locally.
+
+To verify that the package can be built without uploading it, run `./scripts/package.sh`.
+
+### Building a temporary package
+
+If you need to build a `.nupkg` for testing another application (in cases where linking directly to this project is not an option), run `./scripts/build-test-package.sh`. This will create a package with a unique version string in `./test-packages`. You can then set your other project to use `test-packages` as a NuGet package source.

scripts/build-test-package.sh

@@ -0,0 +1,32 @@
+#!/bin/bash
+
+set -e
+
+# build-test-package.sh
+# Temporarily changes the project version to a unique prerelease version string based on the current
+# date and time, builds a .nupkg package, and places the package in ./test-packages. You can then use
+# the test-packages directory as a package source to use this package in our testing tools.
+
+TEST_VERSION="0.0.1-$(date +%Y%m%d.%H%M%S)"
+PROJECT_FILE=src/LaunchDarkly.XamarinSdk/LaunchDarkly.XamarinSdk.csproj
+SAVE_PROJECT_FILE="${PROJECT_FILE}.orig"
+TEST_PACKAGE_DIR=./test-packages
+
+mkdir -p "${TEST_PACKAGE_DIR}"
+
+cp "${PROJECT_FILE}" "${SAVE_PROJECT_FILE}"
+
+"$(dirname "$0")/update-version.sh" "${TEST_VERSION}"
+
+trap 'mv "${SAVE_PROJECT_FILE}" "${PROJECT_FILE}"' EXIT
+
+msbuild /restore
+
+NUPKG_FILE="src/LaunchDarkly.XamarinSdk/bin/Debug/LaunchDarkly.XamarinSdk.${TEST_VERSION}.nupkg"
+if [ -f "${NUPKG_FILE}" ]; then
+	mv "${NUPKG_FILE}" "${TEST_PACKAGE_DIR}"
+	echo; echo; echo "Success! Created test package version ${TEST_VERSION} in ${TEST_PACKAGE_DIR}"
+else
+	echo; echo "Unknown problem - did not build the expected package file"
+	exit 1
+fi

scripts/update-version.sh

@@ -0,0 +1,12 @@
+#!/bin/bash
+
+# update-version.sh <version string>
+# Updates the version string in the project file.
+
+NEW_VERSION="$1"
+
+PROJECT_FILE=./src/LaunchDarkly.XamarinSdk/LaunchDarkly.XamarinSdk.csproj
+TEMP_FILE="${PROJECT_FILE}.tmp"
+
+sed "s#^\( *\)<Version>[^<]*</Version>#\1<Version>${NEW_VERSION}</Version>#g" "${PROJECT_FILE}" > "${TEMP_FILE}"
+mv "${TEMP_FILE}" "${PROJECT_FILE}"

src/LaunchDarkly.XamarinSdk/Configuration.cs

@@ -27,7 +27,6 @@ public sealed class Configuration
         private readonly int _eventCapacity;
         private readonly Uri _eventsUri;
         private readonly HttpMessageHandler _httpMessageHandler;
-        private readonly TimeSpan _httpClientTimeout;
         private readonly bool _inlineUsersInEvents;
         private readonly bool _isStreamingEnabled;
         private readonly string _mobileKey;
@@ -43,7 +42,8 @@ public sealed class Configuration
         private readonly TimeSpan _userKeysFlushInterval;
 
         // Settable only for testing
-        internal readonly IConnectionManager _connectionManager;
+        internal readonly IBackgroundModeManager _backgroundModeManager;
+        internal readonly IConnectivityStateManager _connectivityStateManager;
         internal readonly IDeviceInfo _deviceInfo;
         internal readonly IEventProcessor _eventProcessor;
         internal readonly IFlagCacheManager _flagCacheManager;
@@ -80,7 +80,7 @@ public sealed class Configuration
         /// <summary>
         /// The connection timeout to the LaunchDarkly server.
         /// </summary>
-        public TimeSpan ConnectionTimeout { get; internal set; }
+        public TimeSpan ConnectionTimeout => _connectionTimeout;
 
         /// <summary>
         /// Whether to enable feature flag updates when the application is running in the background.
@@ -130,11 +130,6 @@ public sealed class Configuration
         /// </summary>
         public HttpMessageHandler HttpMessageHandler => _httpMessageHandler;
 
-        /// <summary>
-        /// The connection timeout. The default value is 10 seconds.
-        /// </summary>
-        public TimeSpan HttpClientTimeout => _httpClientTimeout;
-
         /// <summary>
         /// Sets whether to include full user details in every analytics event.
         /// </summary>
@@ -216,7 +211,8 @@ public sealed class Configuration
         /// encoded into the request URI. Using REPORT allows the user data to be sent in the request body instead.
         /// However, some network gateways do not support REPORT.
         /// </remarks>
-        public bool UseReport => _useReport;
+        internal bool UseReport => _useReport;
+        // UseReport is currently disabled due to Android HTTP issues (ch47341), but it's still implemented internally
 
         /// <summary>
         /// The number of user keys that the event processor can remember at any one time.
@@ -249,7 +245,6 @@ public sealed class Configuration
         internal static readonly TimeSpan DefaultEventFlushInterval = TimeSpan.FromSeconds(5);
         internal static readonly TimeSpan DefaultReadTimeout = TimeSpan.FromMinutes(5);
         internal  static readonly TimeSpan DefaultReconnectTime = TimeSpan.FromSeconds(1);
-        internal static readonly TimeSpan DefaultHttpClientTimeout = TimeSpan.FromSeconds(10);
         internal static readonly int DefaultUserKeysCapacity = 1000;
         internal static readonly TimeSpan DefaultUserKeysFlushInterval = TimeSpan.FromMinutes(5);
         internal static readonly TimeSpan DefaultBackgroundPollingInterval = TimeSpan.FromMinutes(60);
@@ -328,7 +323,6 @@ internal Configuration(ConfigurationBuilder builder)
             _eventCapacity = builder._eventCapacity;
             _eventsUri = builder._eventsUri;
             _httpMessageHandler = builder._httpMessageHandler;
-            _httpClientTimeout = builder._httpClientTimeout;
             _inlineUsersInEvents = builder._inlineUsersInEvents;
             _isStreamingEnabled = builder._isStreamingEnabled;
             _mobileKey = builder._mobileKey;
@@ -344,7 +338,8 @@ internal Configuration(ConfigurationBuilder builder)
             _userKeysCapacity = builder._userKeysCapacity;
             _userKeysFlushInterval = builder._userKeysFlushInterval;
 
-            _connectionManager = builder._connectionManager;
+            _backgroundModeManager = builder._backgroundModeManager;
+            _connectivityStateManager = builder._connectivityStateManager;
             _deviceInfo = builder._deviceInfo;
             _eventProcessor = builder._eventProcessor;
             _flagCacheManager = builder._flagCacheManager;
@@ -364,7 +359,7 @@ private class EventProcessorAdapter : IEventProcessorConfiguration
             public int EventCapacity => Config.EventCapacity;
             public TimeSpan EventFlushInterval => Config.EventFlushInterval;
             public Uri EventsUri => Config.EventsUri;
-            public TimeSpan HttpClientTimeout => Config.HttpClientTimeout;
+            public TimeSpan HttpClientTimeout => Config.ConnectionTimeout;
             public bool InlineUsersInEvents => Config.InlineUsersInEvents;
             public IImmutableSet<string> PrivateAttributeNames => Config.PrivateAttributeNames;
             public TimeSpan ReadTimeout => Config.ReadTimeout;
@@ -385,7 +380,7 @@ private class StreamManagerAdapter : IStreamManagerConfiguration
             internal Configuration Config { get; set; }
             public string HttpAuthorizationKey => Config.MobileKey;
             public HttpMessageHandler HttpMessageHandler => Config.HttpMessageHandler;
-            public TimeSpan HttpClientTimeout => Config.HttpClientTimeout;
+            public TimeSpan HttpClientTimeout => Config.ConnectionTimeout;
             public TimeSpan ReadTimeout => Config.ReadTimeout;
             public TimeSpan ReconnectTime => Config.ReconnectTime;
         }

src/LaunchDarkly.XamarinSdk/ConfigurationBuilder.cs

@@ -48,7 +48,8 @@ public interface IConfigurationBuilder
         /// Sets the interval between feature flag updates when the application is running in the background.
         /// </summary>
         /// <remarks>
-        /// This is only relevant on mobile platforms.
+        /// This is only relevant on mobile platforms. The default is <see cref="Configuration.DefaultBackgroundPollingInterval"/>;
+        /// the minimum is <see cref="Configuration.MinimumPollingInterval"/>.
         /// </remarks>
         /// <param name="backgroundPollingInterval">the background polling interval</param>
         /// <returns>the same builder</returns>
@@ -61,6 +62,30 @@ public interface IConfigurationBuilder
         /// <returns>the same builder</returns>
         IConfigurationBuilder BaseUri(Uri baseUri);
 
+        /// <summary>
+        /// Sets the connection timeout for all HTTP requests.
+        /// </summary>
+        /// <remarks>
+        /// The default value is 10 seconds.
+        /// </remarks>
+        /// <param name="connectionTimeout">the connection timeout</param>
+        /// <returns>the same builder</returns>
+        IConfigurationBuilder ConnectionTimeout(TimeSpan connectionTimeout);
+
+        /// <summary>
+        /// Sets whether to enable feature flag polling when the application is in the background.
+        /// </summary>
+        /// <remarks>
+        /// By default, on Android and iOS the SDK can still receive feature flag updates when an application
+        /// is in the background, but it will use polling rather than maintaining a streaming connection (and
+        /// will use <see cref="BackgroundPollingInterval(TimeSpan)"/> rather than <see cref="PollingInterval(TimeSpan)"/>).
+        /// If you set <c>EnableBackgroundUpdating</c> to false, it will not check for feature flag updates
+        /// until the application returns to the foreground.
+        /// </remarks>
+        /// <param name="enableBackgroundUpdating">true if background updating should be allowed</param>
+        /// <returns>the same builder</returns>
+        IConfigurationBuilder EnableBackgroundUpdating(bool enableBackgroundUpdating);
+
         /// <summary>
         /// Set to true if LaunchDarkly should provide additional information about how flag values were
         /// calculated.
@@ -119,13 +144,6 @@ public interface IConfigurationBuilder
         /// <returns>the same builder</returns>
         IConfigurationBuilder HttpMessageHandler(HttpMessageHandler httpMessageHandler);
 
-        /// <summary>
-        /// Sets the connection timeout. The default value is 10 seconds.
-        /// </summary>
-        /// <param name="httpClientTimeout">the connection timeout</param>
-        /// <returns>the same builder</returns>
-        IConfigurationBuilder HttpClientTimeout(TimeSpan httpClientTimeout);
-
         /// <summary>
         /// Sets whether to include full user details in every analytics event.
         /// </summary>
@@ -180,7 +198,8 @@ public interface IConfigurationBuilder
         /// Sets the polling interval (when streaming is disabled).
         /// </summary>
         /// <remarks>
-        /// Values less than the default of 30 seconds will be changed to the default.
+        /// The default is <see cref="Configuration.DefaultPollingInterval"/>; the minimum is
+        /// <see cref="Configuration.MinimumPollingInterval"/>.
         /// </remarks>
         /// <param name="pollingInterval">the rule update polling interval</param>
         /// <returns>the same builder</returns>
@@ -228,18 +247,6 @@ public interface IConfigurationBuilder
         /// <returns>the same builder</returns>
         IConfigurationBuilder StreamUri(Uri streamUri);
 
-        /// <summary>
-        /// Sets whether to use the HTTP REPORT method for feature flag requests.
-        /// </summary>
-        /// <remarks>
-        /// By default, polling and streaming connections are made with the GET method, witht the user data
-        /// encoded into the request URI. Using REPORT allows the user data to be sent in the request body instead.
-        /// However, some network gateways do not support REPORT.
-        /// </remarks>
-        /// <param name="useReport">whether to use REPORT mode</param>
-        /// <returns>the same builder</returns>
-        IConfigurationBuilder UseReport(bool useReport);
-
         /// <summary>
         /// Sets the number of user keys that the event processor can remember at any one time.
         /// </summary>
@@ -269,14 +276,13 @@ internal sealed class ConfigurationBuilder : IConfigurationBuilder
         internal bool _allAttributesPrivate = false;
         internal TimeSpan _backgroundPollingInterval;
         internal Uri _baseUri = Configuration.DefaultUri;
-        internal TimeSpan _connectionTimeout;
-        internal bool _enableBackgroundUpdating;
+        internal TimeSpan _connectionTimeout = Configuration.DefaultConnectionTimeout;
+        internal bool _enableBackgroundUpdating = true;
         internal bool _evaluationReasons = false;
         internal int _eventCapacity = Configuration.DefaultEventCapacity;
         internal TimeSpan _eventFlushInterval = Configuration.DefaultEventFlushInterval;
         internal Uri _eventsUri = Configuration.DefaultEventsUri;
         internal HttpMessageHandler _httpMessageHandler = PlatformSpecific.Http.GetHttpMessageHandler(); // see Http.shared.cs
-        internal TimeSpan _httpClientTimeout = Configuration.DefaultHttpClientTimeout;
         internal bool _inlineUsersInEvents = false;
         internal bool _isStreamingEnabled = true;
         internal string _mobileKey;
@@ -292,7 +298,8 @@ internal sealed class ConfigurationBuilder : IConfigurationBuilder
         internal TimeSpan _userKeysFlushInterval = Configuration.DefaultUserKeysFlushInterval;
 
         // Internal properties only settable for testing
-        internal IConnectionManager _connectionManager;
+        internal IBackgroundModeManager _backgroundModeManager;
+        internal IConnectivityStateManager _connectivityStateManager;
         internal IDeviceInfo _deviceInfo;
         internal IEventProcessor _eventProcessor;
         internal IFlagCacheManager _flagCacheManager;
@@ -317,7 +324,6 @@ internal ConfigurationBuilder(Configuration copyFrom)
             _eventFlushInterval = copyFrom.EventFlushInterval;
             _eventsUri = copyFrom.EventsUri;
             _httpMessageHandler = copyFrom.HttpMessageHandler;
-            _httpClientTimeout = copyFrom.HttpClientTimeout;
             _inlineUsersInEvents = copyFrom.InlineUsersInEvents;
             _isStreamingEnabled = copyFrom.IsStreamingEnabled;
             _mobileKey = copyFrom.MobileKey;
@@ -407,12 +413,6 @@ public IConfigurationBuilder HttpMessageHandler(HttpMessageHandler httpMessageHa
             return this;
         }
 
-        public IConfigurationBuilder HttpClientTimeout(TimeSpan httpClientTimeout)
-        {
-            _httpClientTimeout = httpClientTimeout;
-            return this;
-        }
-
         public IConfigurationBuilder InlineUsersInEvents(bool inlineUsersInEvents)
         {
             _inlineUsersInEvents = inlineUsersInEvents;
@@ -485,12 +485,6 @@ public IConfigurationBuilder StreamUri(Uri streamUri)
             return this;
         }
 
-        public IConfigurationBuilder UseReport(bool useReport)
-        {
-            _useReport = useReport;
-            return this;
-        }
-
         public  IConfigurationBuilder UserKeysCapacity(int userKeysCapacity)
         {
             _userKeysCapacity = userKeysCapacity;
@@ -509,9 +503,21 @@ public IConfigurationBuilder UserKeysFlushInterval(TimeSpan userKeysFlushInterva
         // and then call these methods before you have called any of the public methods (since
         // only these methods return ConfigurationBuilder rather than IConfigurationBuilder).
 
-        internal ConfigurationBuilder ConnectionManager(IConnectionManager connectionManager)
+        internal ConfigurationBuilder BackgroundModeManager(IBackgroundModeManager backgroundModeManager)
+        {
+            _backgroundModeManager = backgroundModeManager;
+            return this;
+        }
+
+        internal IConfigurationBuilder BackgroundPollingIntervalWithoutMinimum(TimeSpan backgroundPollingInterval)
+        {
+            _backgroundPollingInterval = backgroundPollingInterval;
+            return this;
+        }
+
+        internal ConfigurationBuilder ConnectivityStateManager(IConnectivityStateManager connectivityStateManager)
         {
-            _connectionManager = connectionManager;
+            _connectivityStateManager = connectivityStateManager;
             return this;
         }