Fix missing signatures (#51)

# Description

The WebSocket class was abstracting the `System.net.WebSockets.ClientWebSocket` object by storing it in a `dynamic` variable. 
This was made to allow mocking the ClientWebSocket class (which is final and thus cannot be extended) via duck typing, using a custom `IClientWebSocket` interface which reproduces parts of the ClientWebSocket API.

Problem is: it seems that the Visual Studio C# linker is smart enough to remove unused functions from compiled applications, but it's unable to detect functions used through dynamic variables.
This made ClientWebSocket functions stripped from applications using our SDK, making it useless with that protocol.

This PR fixes this situation by making our WebSocket protocol implementation use only objects implementing our IClientWebSocket interface, completely removing duck typing. 
I added a humble object creating and wrapping ClientWebSocket instances to make that class compatible with our custom interface. That humble object explicitly uses ClientWebSocket functions, forcing the C# linker to keep them in the compiled product.

Mocking is made by injecting a custom mock objecting implementing that interface.

# Other changes

* Fix all warnings (99% of them being missing XML documentation)

# How to review

The actual fix is in the Kuzzle/Protocol/WebSocket.cs file (and its unit test counterpart). All other changes are about fixing warnings.

Author: scottinet

.travis.yml

@@ -35,16 +35,20 @@ jobs:
       name: Dead link check
       if: type = pull_request OR type = push AND branch =~ /^master|[0-9]+-(dev|stable)$/ OR type = cron
       language: node_js
-      node_js: 10
-
+      node_js: 12
+      cache:
+        directories:
+          - $HOME/.gem/specs
+      install:
+        - gem install typhoeus
+        - npm ci --silent
       before_script:
-        - npm ci
         - npm run doc-prepare
         - $(npm bin)/kuzdoc iterate-repos:install --repos_path doc/framework/.repos/
         - $(npm bin)/kuzdoc framework:link -d /sdk/csharp/2/ -v 2
       script:
-        - gem install typhoeus
-        - cd doc/framework/ && HYDRA_MAX_CONCURRENCY=20 ruby .ci/dead-links.rb -p src/sdk/csharp/2/
+        - cd doc/framework/
+        - HYDRA_MAX_CONCURRENCY=20 ruby .ci/dead-links.rb -p src/sdk/csharp/2/
 
     - stage: Tests
       name: Build documentation
@@ -58,7 +62,7 @@ jobs:
 
     - stage: Deployments
       name: NuGet
-      if: tag IS present AND branch = master
+      if: type = push AND branch =~ /^(master|[0-9]+-stable)$/
       language: csharp
       solution: sdk-csharp.sln
       sudo: required
@@ -88,7 +92,6 @@ jobs:
       language: node_js
       node_js: 10
       env:
-        - BRANCH=dev
         - NODE_ENV=production
         - S3_BUCKET=docs-next.kuzzle.io
         - CLOUDFRONT_DISTRIBUTION_ID=E2ZCCEK9GRB49U
@@ -102,7 +105,6 @@ jobs:
 
       install:
         - pip install awscli --upgrade --user
-        - npm ci
 
       script:
         - npm run doc-prepare
@@ -113,8 +115,6 @@ jobs:
         script:
           - npm run doc-upload
         skip_cleanup: true
-        on:
-          all_branches: true
 
       after_deploy:
         - npm run doc-cloudfront
@@ -138,7 +138,6 @@ jobs:
 
       install:
         - pip install awscli --upgrade --user
-        - npm ci
 
       script:
         - npm run doc-prepare
@@ -149,8 +148,6 @@ jobs:
         script:
           - npm run doc-upload
         skip_cleanup: true
-        on:
-          all_branches: true
 
       after_deploy:
         - npm run doc-cloudfront

Kuzzle.Tests/Protocol/WebSocketTest.cs

@@ -1,34 +1,78 @@
 using System;
 using System.Threading;
 using System.Threading.Tasks;
+using System.Net.WebSockets;
 using KuzzleSdk.Protocol;
 using Moq;
 using Xunit;
 
 namespace Kuzzle.Tests.Protocol {
-  public class TestableWebSocket : WebSocket {
-    internal Mock<IClientWebSocket> MockSocket;
-    public int StateChangesCount = 0;
-    public ProtocolState LastStateDispatched = ProtocolState.Closed;
+  public class MockClientWebSocketAdapter : IClientWebSocket {
+    public Mock<IClientWebSocket> mockedSocket;
+    public WebSocketState _state = WebSocketState.Open;
 
-    public TestableWebSocket(Uri uri) : base(uri) {
-      StateChanged += (sender, e) => {
-        StateChangesCount++;
-        LastStateDispatched = e;
-      };
+    public WebSocketState State {
+      get { return _state; }
     }
 
-    internal override dynamic CreateClientSocket() {
-      MockSocket = new Mock<IClientWebSocket>();
+    public MockClientWebSocketAdapter () {
+      mockedSocket = new Mock<IClientWebSocket>();
 
-      MockSocket
+      mockedSocket
         .Setup(s => s.ConnectAsync(
           It.IsAny<Uri>(), It.IsAny<CancellationToken>()))
         .Returns(Task.CompletedTask);
+    }
+
+    public Task ConnectAsync(Uri uri, CancellationToken cancellationToken) {
+      return mockedSocket.Object.ConnectAsync(uri, cancellationToken);
+    }
+
+    public Task SendAsync(
+      ArraySegment<byte> buffer,
+      WebSocketMessageType msgType,
+      bool endOfMessage,
+      CancellationToken cancellationToken
+    ) {
+      return mockedSocket.Object.SendAsync(
+        buffer,
+        msgType,
+        endOfMessage,
+        cancellationToken);
+    }
+
+    public Task<WebSocketReceiveResult> ReceiveAsync(
+      ArraySegment<byte> buffer,
+      CancellationToken cancellationToken
+    ) {
+      Task.Delay(10000).Wait();
+      return mockedSocket.Object.ReceiveAsync(buffer, cancellationToken);
+    }
+
+    public void Abort() {
+      mockedSocket.Object.Abort();
+    }
+  }
+
+  public class TestableWebSocket : AbstractWebSocket {
+    public Mock<IClientWebSocket> mockedSocket;
+    public int StateChangesCount = 0;
+    public ProtocolState LastStateDispatched = ProtocolState.Closed;
 
-      MockSocket.Object.State = System.Net.WebSockets.WebSocketState.Open;
+    public TestableWebSocket(Uri uri)
+      : base(typeof(MockClientWebSocketAdapter), uri)
+    {
+      StateChanged += (sender, e) => {
+        StateChangesCount++;
+        LastStateDispatched = e;
+      };
+    }
 
-      return MockSocket.Object;
+    public override async Task ConnectAsync(
+      CancellationToken cancellationToken
+    ) {
+      await base.ConnectAsync(cancellationToken);
+      mockedSocket = ((MockClientWebSocketAdapter)socket).mockedSocket;
     }
   }
 
@@ -55,7 +99,7 @@ public void ConstructorRejectsNullUri() {
     }
 
     [Fact]
-    public async void ConnectAsyncTest() {
+    public async Task ConnectAsyncTest() {
       await _ws.ConnectAsync(CancellationToken.None);
 
       Assert.NotNull(_ws.socket);
@@ -64,7 +108,7 @@ public async void ConnectAsyncTest() {
       await _ws.ConnectAsync(CancellationToken.None);
       await _ws.ConnectAsync(CancellationToken.None);
 
-      _ws.MockSocket.Verify(
+      _ws.mockedSocket.Verify(
         s => s.ConnectAsync(uri, CancellationToken.None),
         Times.Once);
 
@@ -74,7 +118,7 @@ public async void ConnectAsyncTest() {
     }
 
     [Fact]
-    public async void DisconnectTest() {
+    public async Task DisconnectTest() {
       await _ws.ConnectAsync(CancellationToken.None);
 
       Assert.Equal(ProtocolState.Open, _ws.State);
@@ -91,7 +135,7 @@ public async void DisconnectTest() {
       Assert.Equal(2, _ws.StateChangesCount);
       Assert.Equal(ProtocolState.Closed, _ws.LastStateDispatched);
 
-      _ws.MockSocket.Verify(s => s.Abort(), Times.Once);
+      _ws.mockedSocket.Verify(s => s.Abort(), Times.Once);
     }
 
     [Fact]

Kuzzle/API/Controllers/AdminController.cs

@@ -2,6 +2,9 @@
 using Newtonsoft.Json.Linq;
 
 namespace KuzzleSdk.API.Controllers {
+  /// <summary>
+  /// Implement the "admin" controller of the Kuzzle API
+  /// </summary>
   public class AdminController : BaseController {
     internal AdminController(IKuzzleApi k) : base(k) { }
 

Kuzzle/API/Controllers/RealtimeController.cs

@@ -10,15 +10,14 @@
 using static KuzzleSdk.API.Controllers.RealtimeController;
 
 namespace KuzzleSdk.API.Controllers {
-
   internal interface IRealtimeController {
     Task<string> SubscribeAndAddToRecoverer(
         string index, string collection, JObject filters,
         NotificationHandler handler, SubscribeOptions options = null, bool addToRecoverer = true);
     }
 
   /// <summary>
-  /// Implements the "realtime" Kuzzle API controller
+  /// Implement the "realtime" Kuzzle API controller
   /// </summary>
   public sealed class RealtimeController : BaseController, IRealtimeController {
     /// <summary>
@@ -112,7 +111,7 @@ internal RealtimeController(IKuzzleApi api) : base(api) {
     }
 
     /// <summary>
-    /// Releases unmanaged resources and performs other cleanup operations 
+    /// Releases unmanaged resources and performs other cleanup operations
     /// before the <see cref="T:KuzzleSdk.API.Controllers.RealtimeController"/>
     /// is reclaimed by garbage collection.
     /// </summary>
@@ -134,8 +133,8 @@ public async Task<int> CountAsync(string roomId) {
     }
 
     /// <summary>
-    /// Sends a real-time message to Kuzzle. The message will be dispatched to 
-    /// all clients with subscriptions matching the index, the collection and 
+    /// Sends a real-time message to Kuzzle. The message will be dispatched to
+    /// all clients with subscriptions matching the index, the collection and
     /// the message content.
     /// </summary>
     public async Task PublishAsync(
@@ -153,8 +152,8 @@ await api.QueryAsync(new JObject {
     }
 
     /// <summary>
-    /// Subscribes by providing a set of filters: messages, document changes 
-    /// and, optionally, user events matching the provided filters will 
+    /// Subscribes by providing a set of filters: messages, document changes
+    /// and, optionally, user events matching the provided filters will
     /// generate real-time notifications, sent to you in real-time by Kuzzle.
     /// </summary>
     public async Task<string> SubscribeAsync(
@@ -218,16 +217,32 @@ private async Task<string> SubscribeAndAddToSubscriptionRecoverer(
     }
 
     /// <summary>
-    /// Subscribes by providing a set of filters: messages, document changes 
-    /// and, optionally, user events matching the provided filters will 
+    /// Subscribes by providing a set of filters: messages, document changes
+    /// and, optionally, user events matching the provided filters will
     /// generate real-time notifications, sent to you in real-time by Kuzzle.
     /// and add the Subscription to the SubscriptionRecoverer for Offline Mode
     /// </summary>
+    /// <param name="index">Storage index</param>
+    /// <param name="collection">Storage collection</param>
+    /// <param name="filters">Realtime filters (Koncorde format)</param>
+    /// <param name="handler">Callback invoked each time a realtime notification is received</param>
+    /// <param name="options">Subscription options</param>
     /// <param name="addToRecoverer">If set to <c>true</c> add to recoverer.</param>
     async Task<string> IRealtimeController.SubscribeAndAddToRecoverer(
-        string index, string collection, JObject filters,
-        NotificationHandler handler, SubscribeOptions options, bool addToRecoverer) {
-      return await SubscribeAndAddToSubscriptionRecoverer(index, collection, filters, handler, options, addToRecoverer);
+        string index,
+        string collection,
+        JObject filters,
+        NotificationHandler handler,
+        SubscribeOptions options,
+        bool addToRecoverer
+    ) {
+      return await SubscribeAndAddToSubscriptionRecoverer(
+        index,
+        collection,
+        filters,
+        handler,
+        options,
+        addToRecoverer);
     }
 
   }

Kuzzle/Enums/CollectionController/TypeFilter.cs

@@ -1,8 +1,20 @@
 using System;
 namespace KuzzleSdk.Enums.CollectionController {
+  /// <summary>
+  /// Controls the kind of collections to be returned by collection:list
+  /// </summary>
   public enum TypeFilter {
+    /// <summary>
+    /// Return all collections (stored and real-time)
+    /// </summary>
     All,
+    /// <summary>
+    /// Return only stored collections
+    /// </summary>
     Stored,
+    /// <summary>
+    /// Return only real-time collections
+    /// </summary>
     Realtime,
   }
 }

Kuzzle/EventHandler/AbstractKuzzleEventHandler.cs

@@ -3,13 +3,38 @@
 using KuzzleSdk.EventHandler.Events;
 
 namespace KuzzleSdk.EventHandler {
+  /// <summary>
+  /// Abstract class describing this SDK event handler
+  /// </summary>
   public abstract class AbstractKuzzleEventHandler {
+    /// <summary>
+    /// Events occuring on realtime subscriptions
+    /// </summary>
     public abstract event EventHandler<SubscriptionEvent> Subscription;
+    /// <summary>
+    /// Events occuring on a successful login
+    /// </summary>
     public abstract event EventHandler<UserLoggedInEvent> UserLoggedIn;
+    /// <summary>
+    /// Events occuring on a successful logout
+    /// </summary>
     public abstract event Action UserLoggedOut;
+    /// <summary>
+    /// Events occuring whenever the SDK reconnects after a connection loss
+    /// </summary>
     public abstract event Action Reconnected;
+    /// <summary>
+    /// Events occuring when queued items during a connection loss have all
+    /// been replayed
+    /// </summary>
     public abstract event Action QueueRecovered;
+    /// <summary>
+    /// Events occuring on an unknown query response received from Kuzzle
+    /// </summary>
     public abstract event EventHandler<Response> UnhandledResponse;
+    /// <summary>
+    /// Events occuring when the authentication token has expired
+    /// </summary>
     public abstract event Action TokenExpired;
 
     internal abstract void DispatchSubscription(SubscriptionEvent subscriptionData);