Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[docs] Update Introduction #784

Open
wants to merge 2 commits into
base: master
Choose a base branch
from
Open

[docs] Update Introduction #784

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
7f0e354
[docs/index] Update "NuGet" section [..]
toraritte Mar 24, 2024
f58f188
[docs/index] Split "Hello World!" section into 3 parts [..]
toraritte Mar 24, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
89 changes: 37 additions & 52 deletions docs/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,84 +5,69 @@ 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.

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!
-----------------------------------------------

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

[<EntryPoint>]
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).