Default-supported HTTP Verbs
See RFC 2616.
These applicatives match on HTTP verbs.
The first argument to
startWebServer is a configuration record with the
following signature. (See below for tips
on customizing this.)
MimeType defined like follows:
A request life-cycle begins with the
HttpProcessor that takes an
and the request as bytes and starts parsing it. It returns an
option that, if Some, gets run against the WebParts passed.
A web part is a thing that acts on a HttpContext, the web part could fail by
None or succeed and produce a new HttpContext. Each web part can
execute asynchronously, and it’s not until it is evaluated that the async is
evaluated. It will be evaluated on the same fibre (asynchronous execution
context) that is consuming from the browser’s TCP socket.
An error handler takes the exception, a programmer-provided message, a request (that failed) and returns a web part for the handling of the error.
Changing the Default Configuration
defaultConfig (defined in
Suave.Web) has sane defaults, and for many users,
these will be fine. However, since
SuaveConfig is a record type, it is easy
to swap out one or more of the default settings, tweaking the configuration to
your precise needs. While we will discuss the default values below, you can
review the defaults at the bottom of
If you’re looking to get started quickly, you can jump straight to sections detailing how to change the IP addres or port, specify a home directory, and set the server’s cryptography key. For those whose descriptions are prefixed with “(advanced)”, there is the potential to degrade Suave’s performance; you should take great care when changing these from their default values.
Changing the server’s IP address or port
The default binding for Suave is http://127.0.0.1:8080. It is rather simple to change that, though.
bindings is a list, you can also configure Suave to listen on any
combination of IP addresses and ports.
Changing the server’s cryptography key
Suave encrypts state stored in sessions, and the key used for
that is the
serverKey configuration setting. This key is required to be a
specific length (256 bits as of this writing), so there is a
that helps ensure that the key is the proper length. The importance of this
key, how to generate one, and how to plug it into your Suave config can be found
under the Server Keys heading on that page.
While the examples all demonstrate using a base64-encoded string, if you have
256 bits already in a byte array that you want to use as a server key, you can
ServerKey.validate instead of
ServerKey.fromBase64; it will ensure that
the key is the proper length.
Changing the error handler
Suave’s default error handler logs the error, then returns an HTTP 500
response. For local requests, it returns the error and stack trace in the body
of the response; for others, it returns “Internal Server Error”. The best way
to customize it would be to start with
near the top of Web.fs,
and tweak it to your liking. Then…
Changing the listen timeout
(advanced) This is the
TimeSpan Suave will wait, on startup, for its request
to bind to a specific TCP port to be successful. The default value is for
listenTimeout is 2 seconds.
Changing the cancellation token
As with any asynchronous process, Suave can be controlled by the cancellation
token used to start the process. By default, it uses the default cancellation
token; however, giving
cancellationToken a specific value here will allow for
scenarios such as stopping and restarting Suave programmatically.
Changing the buffer size
bufferSize that is used for socket operations (low-level
communications). Its default value is 8192 bytes (8KB).
Changing whether the buffer can automatically grow
(advanced) This boolean specifies whether the buffer manager is allowed to
autoGrow defaults to
Changing the maximum concurrent operations
(advanced) This is the maximum number of concurrent socket operations that
Suave will attempt to serve. The default value for
maxOps is 100.
Changing the MIME type map
Writers module has a default MIME type map, and that is the default map
in the configuration. Suave will not serve a file for which it cannot determine
a MIME type, so if you are serving files that are not
current in the MIME type map,
you will need to add this type.
The above paragraph uses the word “map” several times, but it’s technically a mapping function; to modify it, you need a function of your own. As of this writing, .iso files are not in the default mapping. Here’s how we could add it.
Changing the home folder
Suave does not have a default home folder. If you want to serve files from
a folder, just specify it as a
Some string. If an absolute path is not given,
it is interpreted from the current working directory when Suave was started.
For example, if we follow the .NET Core convention of putting our
publicly-available files under
wwwroot, this example sets it as the home
Changing the compressed files folder
Suave writes temporary files to disk when performing compression; the default
directory where these files are placed is the current working directory when
Suave was started. However, if you want these files to go somewhere specific,
you can specify them the exact same way we did above for the home folder; just
compressedFilesFolder field instead. (Suave deletes these files once
they are served, so their lifetime is usually less than a second.)
Changing logging options
A good overview can be found on the logging page.
Changing the default TCP server
Suave’s default TCP server uses the .NET CLR’s socket implementation to bind and listen. Suave also comes with a TCP server implementation based on LibUV; to use it…
Changing the default cookie serializer
By default, Suave uses a binary formatter to serialize a
into a string that is encrypted and used as a cookie payload. On the “State and
Sessions” page, there is an
example of swapping out the default cookie serializer for one based on JSON.NET.
Changing the default TLS provider
(advanced) The TLS provider supports encrypted communications (HTTPS). The
default is an instance of the
DefaultTlsProvider class; customizing it would
require implementing the
TlsProvider interface, and providing an instance of
that class in your configuration’s
Changing whether the header is shown
By default, Suave adds a
Server header to each response, identifying itself
as the software that handled the request. If this behavior is not desired, you
Changing the maximum file upload size
maxContentLength field controls the maximum allowed upload size, in bytes;
its default is 10000000 (10 MiB).