Merge pull request #560 from lucasmreis/websockets-docs-example

Websockets docs example

Author: Henrik Feldt

docs/_layouts/default.html

@@ -96,6 +96,7 @@ <h2 id="project_tagline">Suave is a simple web development F# library providing
             <li><a href="azure-app-service.html">Deploying Suave to Azure App Service</a></li>
             <li><a href="logs.html">Getting Hold of Suave’s Logs</a></li>
             <li><a href="paket.html">Suave + Paket = ♥</a></li>
+            <li><a href="websockets.html">Realtime messages with WebSockets</a></li>
             <li><a href="https://www.gitbook.com/book/theimowski/suave-music-store/">Music Store Tutorial</a></li>
             <li><a href="http://products.tamizhvendan.in/fsharp-applied/">E-Book: Web Development In F# Using Suave</a></li>
             <li><a href="http://blog.2mas.xyz/fsharp-suave-app-on-dotnet-core-on-kubernetes-on-google-cloud/">Suave on dotnet core on kubernetes on google cloud</a></li>

docs/websockets.md

@@ -0,0 +1,61 @@
+---
+layout: default
+---
+
+Realtime Messages With WebSockets
+---------------------------------
+
+It's easy to set up WebSockets with Suave.
+
+First, define a function that takes `WebSocket` and `HttpContext` typed parameters, and returns a socket computation expression:
+
+{% highlight fsharp %}
+open Suave.Sockets
+open Suave.Sockets.Control
+open Suave.WebSocket
+
+let ws (webSocket : WebSocket) (context: HttpContext) =
+    socket {
+      ...
+    }
+{% endhighlight %}
+
+Next, use the `read` and `send` function to receive and send messages to the clients:
+
+{% highlight fsharp %}
+    socket {
+        let mutable loop = true
+
+        while loop do
+            let! msg = webSocket.read()
+
+            match msg with
+            | (Text, data, true) ->
+                let str = UTF8.toString data
+                let response = sprintf "response to %s" str
+                let byteResponse =
+                    response
+                    |> System.Text.Encoding.ASCII.GetBytes
+                    |> ByteSegment
+                do! webSocket.send Text byteResponse true
+
+            | (Close, _, _) ->
+                let emptyResponse = [||] |> ByteSegment
+                do! webSocket.send Close emptyResponse true
+                loop <- false
+
+            | _ -> ()
+      }
+{% endhighlight %}
+
+Then, use the `handShake` function to fit it in your web server:
+
+{% highlight fsharp %}
+let app : WebPart =
+    choose [
+      path "/websocket" >=> handShake ws
+      GET >=> choose [ path "/" >=> file "index.html"; browseHome ]
+      NOT_FOUND "Found no handlers." ]
+{% endhighlight %}
+
+The complete example can be found [here](https://github.com/SuaveIO/suave/tree/master/examples/WebSocket).

examples/WebSocket/Program.fs

@@ -16,31 +16,69 @@ open Suave.Sockets
 open Suave.Sockets.Control
 open Suave.WebSocket
 
-let echo (webSocket : WebSocket) =
-  fun cx -> socket {
-    let loop = ref true
-    while !loop do
+let ws (webSocket : WebSocket) (context: HttpContext) =
+  socket {
+    // if `loop` is set to false, the server will stop receiving messages
+    let mutable loop = true
+
+    while loop do
+      // the server will wait for a message to be received without blocking the thread
       let! msg = webSocket.read()
+
       match msg with
+      // the message has type (Opcode * byte [] * bool)
+      //
+      // Opcode type:
+      //   type Opcode = Continuation | Text | Binary | Reserved | Close | Ping | Pong
+      //
+      // byte [] contains the actual message
+      //
+      // the last element is the FIN byte, explained later
       | (Text, data, true) ->
+        // the message can be converted to a string
         let str = UTF8.toString data
-        do! webSocket.send Text (ArraySegment data) true
-      | (Ping, _, _) ->
-        do! webSocket.send Pong (ArraySegment([||])) true
+        let response = sprintf "response to %s" str
+
+        // the response needs to be converted to a ByteSegment
+        let byteResponse =
+          response
+          |> System.Text.Encoding.ASCII.GetBytes
+          |> ByteSegment
+
+        // the `send` function sends a message back to the client
+        do! webSocket.send Text byteResponse true
+
       | (Close, _, _) ->
-        do! webSocket.send Close (ArraySegment([||])) true
-        loop := false
+        let emptyResponse = [||] |> ByteSegment
+        do! webSocket.send Close emptyResponse true
+
+        // after sending a Close message, stop the loop
+        loop <- false
+
       | _ -> ()
-  }
+    }
 
 let app : WebPart =
   choose [
-    path "/websocket" >=> handShake echo
-    GET >=> choose [ path "/" >=> file "index.html"; browseHome ];
-    NOT_FOUND "Found no handlers."
-    ]
+    path "/websocket" >=> handShake ws
+    GET >=> choose [ path "/" >=> file "index.html"; browseHome ]
+    NOT_FOUND "Found no handlers." ]
 
 [<EntryPoint>]
 let main _ =
   startWebServer { defaultConfig with logger = Targets.create Verbose [||] } app
-  0
+  0
+
+//
+// The FIN byte:
+//
+// A single message can be sent separated by fragments. The FIN byte indicates the final fragment. Fragments
+//
+// As an example, this is valid code, and will send only one message to the client:
+//
+// do! webSocket.send Text firstPart false
+// do! webSocket.send Continuation secondPart false
+// do! webSocket.send Continuation thirdPart true
+//
+// More information on the WebSocket protocol can be found at: https://tools.ietf.org/html/rfc6455#page-34
+//