From 7f0e3543d2820c87604a3b43d0108d943942cc43 Mon Sep 17 00:00:00 2001 From: Attila Gulyas Date: Sat, 23 Mar 2024 20:50:07 -0400 Subject: [PATCH 1/2] [docs/index] Update "NuGet" section [..] Since the "Introduction" was written, the .NET CLI has assumed the same roles that Paket was created to fill - and Suave's NuGet page has all possible install / usage method listed. --- docs/index.md | 19 +++---------------- 1 file changed, 3 insertions(+), 16 deletions(-) diff --git a/docs/index.md b/docs/index.md index 9bdbe6ab..28f08068 100644 --- a/docs/index.md +++ b/docs/index.md @@ -12,23 +12,10 @@ of embedding web server capabilities in my own applications. Still in its early stages Suave supports HTTPS, multiple TCP/IP bindings, Basic Access Authentication, Keep-Alive and HTTP compression. -NuGet ------ +Getting started +--------------- -To install Suave, add the following to your -[paket](https://github.com/fsprojects/Paket).dependencies: - -{% highlight dosbatch %} -source https://nuget.org/api/v2 -nuget Suave -{% endhighlight %} - -Or you can use the legacy NuGet command line [Package Manager -Console](http://docs.nuget.org/docs/start-here/using-the-package-manager-console): - -{% highlight dosbatch %} -PM> Install-Package Suave -{% endhighlight %} +See [Suave's NuGet page](https://www.nuget.org/packages/Suave) for installation / usage instructions. The simplest possible application: Hello World! ----------------------------------------------- From f58f188676ce5ab9e40b508a6672d43efc1ab73e Mon Sep 17 00:00:00 2001 From: Attila Gulyas Date: Sat, 23 Mar 2024 20:59:28 -0400 Subject: [PATCH 2/2] [docs/index] Split "Hello World!" section into 3 parts [..] Part 1: Simplest "Hello World!" Suave example with admonition Part 2: Cancellable "Hello World!" example with run instructions Part 3: Note on documentation Removed references to `fsharpi` because it was used by Mono, but Mono has become part of .NET Core. + https://stackoverflow.com/questions/62905814/net-5-and-mono + https://github.com/fsharp/fslang-suggestions/issues/921 In Part 2, removed the `EntryPoint` attribute and `let main argv` (among others), because it didn't work with `dotnet fsi` (perhaps `fsharpi` used to run things differently?). --- docs/index.md | 70 +++++++++++++++++++++++++-------------------------- 1 file changed, 34 insertions(+), 36 deletions(-) diff --git a/docs/index.md b/docs/index.md index 28f08068..7381d72a 100644 --- a/docs/index.md +++ b/docs/index.md @@ -5,12 +5,9 @@ layout: default Introduction ============ -Suave is a lightweight, non-blocking web server. The non-blocking I/O model is efficient and suitable for building fast, scalable network applications. In fact, Suave is written in a **completely non-blocking** fashion throughout. Suave **runs on Linux**, OS X and Windows flawlessly. +Suave is a lightweight, non-blocking web server. The non-blocking I/O model is efficient and suitable for building fast, scalable network applications. In fact, Suave is written in a **completely non-blocking** fashion throughout. Suave **runs on Linux**, OS X, and Windows flawlessly. -Suave is inspired in the simplicity of Happstack and born out of the necessity -of embedding web server capabilities in my own applications. Still in its early -stages Suave supports HTTPS, multiple TCP/IP bindings, Basic Access -Authentication, Keep-Alive and HTTP compression. +Suave was inspired by the simplicity of [Happstack](https://www.happstack.com/) and born out of the necessity of embedding web server capabilities in my own applications. Suave supports HTTPS, multiple TCP/IP bindings, Basic Access Authentication, Keep-Alive, and HTTP compression. Getting started --------------- @@ -20,56 +17,57 @@ See [Suave's NuGet page](https://www.nuget.org/packages/Suave) for installation The simplest possible application: Hello World! ----------------------------------------------- -The simplest Suave application is a simple HTTP server that greets all visitors -with the string `"Hello World!"` +The simplest Suave application is an HTTP server that greets all visitors with the string `"Hello World!"`. {% highlight fsharp %} open Suave +// record WebPart startWebServer defaultConfig (Successful.OK "Hello World!") {% endhighlight %} The above statement will start a web server on default port 8080 over HTTP. -`startWebServer` takes a configuration record and the WebPart `(OK "Hello -World")` It's worth noting that with the above, your application will block on -the function call, until you cancel the `Async.DefaultCancellationToken`. If you -want to handle disposal of the async yourself, have a look at -`startWebServerAsync`. +`startWebServer` takes a configuration record (in this case,[ `Web.defaultConfig`](https://github.com/SuaveIO/suave/blob/d9deb5f4f973fd21d15bdd7e85ac9c0bee05baab/src/Suave/Web.fs#L78-L93)) and a `WebPart` (in this case, [`Successful.OK`](https://github.com/SuaveIO/suave/blob/d9deb5f4f973fd21d15bdd7e85ac9c0bee05baab/src/Suave/Combinators.fs#L129-L150)` "Hello World"`). Ta-daa! -To test the above yourself, paste that code in `Hello.fsx` and then invoke it -with `fsharpi Hello.fsx` (or `fsi Hello.fsx` on Windows). Completely new? Here -are installation instructions on [OS X/macOS](http://fsharp.org/use/mac/), -[Windows](http://fsharp.org/use/windows/) and -[Linux](http://fsharp.org/use/linux/). If you have Visual Studio installed you -should be able to find the "F# Interactive" in your menus. +> NOTE +> The snippet above will block on the function call! That is, if you run it in an IDE, you'll probably have to restart it to stop Suave. +To avoid this, you have to cancel the [`Async.DefaultCancellationToken`](https://fsharp.github.io/fsharp-core-docs/reference/fsharp-control-fsharpasync.html#DefaultCancellationToken), and if you want to handle disposal of the async yourself, have a look at [`startWebServerAsync`](https://github.com/SuaveIO/suave/blob/d9deb5f4f973fd21d15bdd7e85ac9c0bee05baab/src/Suave/Web.fs#L26-L67). +> +> See next section for a cancellable example. + +Cancellable "Hello World!" on the terminal +------------------------------------------- -If you are running in an IDE, and not starting Suave via `Hello.fsx`, you'll -want to provide a way of stopping the server without having to restart the IDE; -the code below will run the server until a key is pressed in the console window, -then shuts down the server. +Paste the code below into an [`.fsx`](https://learn.microsoft.com/en-us/dotnet/fsharp/tools/fsharp-interactive/#scripting-with-f) file (e.g., `Hello.fsx`): {% highlight fsharp %} +#r "nuget: Suave, 2.6.2" + open System open System.Threading open Suave -[] -let main argv = - let cts = new CancellationTokenSource() - let conf = { defaultConfig with cancellationToken = cts.Token } - let listening, server = startWebServerAsync conf (Successful.OK "Hello World") - - Async.Start(server, cts.Token) - printfn "Make requests now" - Console.ReadKey true |> ignore - - cts.Cancel() - - 0 // return an integer exit code +let cts = new CancellationTokenSource() +let conf = { defaultConfig with cancellationToken = cts.Token } +let listening, server = startWebServerAsync conf (Successful.OK "Hello World") + +Async.Start(server, cts.Token) + +Console.ReadKey true |> ignore +cts.Cancel() {% endhighlight %} -In suave, we have opted to write a lot of documentation inside the code; so just +Now run it with `dotnet fsi Hello.fsx`. The code above will run the server until a key is pressed in the console window. + +> INFO +> Completely new? Here are installation instructions on [OS X/macOS](http://fsharp.org/use/mac/), [Windows](http://fsharp.org/use/windows/), and [Linux](http://fsharp.org/use/linux/). If you have Visual Studio installed you +should be able to find the "F# Interactive" in your menus. + +Documentation +------------- + +In Suave, we have opted to write a lot of documentation inside the code; so just hover the function in your IDE or use an assembly browser to bring out the XML docs. You can also browse [our API reference](/Suave.html).