FSharp.Control.Websockets 0.3.0-beta001

FSharp.Control.Websockets

FSharp.Control.WebSockets wraps dotnet websockets in FSharp friendly functions and has a ThreadSafe version.

Why?

Thread safety

Dotnet websockets only allow for one receive and one send at a time. If multiple threads try to write to a websocket, it will throw a System.InvalidOperationException with the message There is already one outstanding 'SendAsync' call for this WebSocket instance. ReceiveAsync and SendAsync can be called simultaneously, but at most one outstanding operation for each of them is allowed at the same time.. This wraps a websocket in a FIFO that allows for multiple threads to write or read at the same time. See Websocket Remarks on Microsoft for more information.

F# friendly and correct behavior

This provides a readMessage type function. This is the biggest stumbling block people have when working with websockets. You have to keep reading from the message until it’s finished. People either don’t and end up having corrupted messages with a small buffer or have a buffer that is giant and can be a memory hog for smaller messages.

Memory usage

Uses RecyclableMemoryStreamManager and ArrayPool to help keep memory usage and GC down.

Builds

GitHub Actions

Nuget

Name	Stable	Prerelease
FSharp.Control.Websockets
FSharp.Control.Websockets.TPL

Using

open System
open System.Net.WebSockets
open System.Threading.Tasks
open Microsoft.AspNetCore.Builder
open Microsoft.AspNetCore.Hosting
open Microsoft.AspNetCore.Http
open FSharp.Control.Websockets
open Microsoft.Extensions.Configuration

let echoWebSocket (httpContext: HttpContext) (next: unit -> Async<unit>) =
  async {
    if httpContext.WebSockets.IsWebSocketRequest then
      let! websocket =
        httpContext.WebSockets.AcceptWebSocketAsync()
        |> Async.AwaitTask
      // Create a thread-safe WebSocket from an existing websocket
      let threadSafeWebSocket =
        ThreadSafeWebSocket.createFromWebSocket websocket

      while threadSafeWebSocket.State = WebSocketState.Open do
        try
          let! result =
            threadSafeWebSocket
            |> ThreadSafeWebSocket.receiveMessageAsUTF8

          match result with
          | Ok (WebSocket.ReceiveUTF8Result.String text) ->
              //Echo it back to the client
              do! WebSocket.sendMessageAsUTF8 websocket (text)
          | Ok (WebSocket.ReceiveUTF8Result.Closed (status, reason)) -> printfn "Socket closed %A - %s" status reason
          | Error (ex) -> printfn "Receiving threw an exception %A" ex.SourceException
        with e -> printfn "%A" e

    else
      do! next ()
  }

//Convenience function for making middleware with F# asyncs and funcs
let fuse (middlware: HttpContext -> (unit -> Async<unit>) -> Async<unit>) (app: IApplicationBuilder) =
  app.Use
    (fun env next ->
      middlware env (next.Invoke >> Async.AwaitTask)
      |> Async.StartAsTask
      :> Task)


let configureEchoServer (appBuilder: IApplicationBuilder) =
  appBuilder.UseWebSockets()
  |> fuse (echoWebSocket)
  |> ignore

let getKestrelServer configureServer uri =
  let configBuilder = new ConfigurationBuilder()
  let configBuilder = configBuilder.AddInMemoryCollection()
  let config = configBuilder.Build()
  config.["server.urls"] <- uri

  let host =
    WebHostBuilder()
      .UseConfiguration(config)
      .UseKestrel()
      .Configure(fun app -> configureServer app)
      .Build()
      .Start()

  host

[<EntryPoint>]
let main argv =
  getKestrelServer configureEchoServer "http://localhost:3000"
  Console.ReadKey() |> ignore

  0

Building

Make sure the following requirements are installed in your system:

• dotnet SDK 2.0 or higher
• Mono if you're on Linux or macOS.

> build.cmd // on windows
$ ./build.sh  // on unix

Environment Variables

• CONFIGURATION will set the configuration of the dotnet commands. If not set it will default to Release.
  • CONFIGURATION=Debug ./build.sh will result in things like dotnet build -c Debug
• GITHUB_TOKEN will be used to upload release notes and nuget packages to github.
  • Be sure to set this before releasing

Watch Tests

The WatchTests target will use dotnet-watch to watch for changes in your lib or tests and re-run your tests on all TargetFrameworks

./build.sh WatchTests

Releasing

• Start a git repo with a remote

git add .
git commit -m "Scaffold"
git remote add origin origin https://github.com/user/MyCoolNewLib.git
git push -u origin master

• Add your nuget API key to paket

paket config add-token "https://www.nuget.org" 4003d786-cc37-4004-bfdf-c4f3e8ef9b3a

• Create a GitHub OAuth Token

  • You can then set the GITHUB_TOKEN to upload release notes and artifacts to github
  • Otherwise it will fallback to username/password

• Then update the RELEASE_NOTES.md with a new version, date, and release notes ReleaseNotesHelper

#### 0.2.0 - 2017-04-20
* FEATURE: Does cool stuff!
* BUGFIX: Fixes that silly oversight

• You can then use the Release target. This will:
  • make a commit bumping the version: Bump version to 0.2.0 and add the release notes to the commit
  • publish the package to nuget
  • push a git tag

./build.sh Release

Code formatting

To format code run the following target

./build.sh FormatCode

This uses Fantomas to do code formatting. Please report code formatting bugs to that repository.