The body is represented using a
StringBuilder
. If you have a
String
you can use the
string_builder.from_string
function to convert it.
A body of binary data.
The body is represented using a
StringBuilder
. If you have a
String
you can use the
string_builder.from_string
function to convert it.
A body of the contents of a file.
This will be sent efficiently using the
send_file
function of the
underlying HTTP server. The file will not be read into memory so it is
safe to send large files this way.
An empty body. This may be returned by the
require_*
middleware
functions in the event of a failure, invalid request, or other situation
in which the request cannot be processed.
Your application may wish to use a middleware to provide default responses
in place of any with an empty body.
The connection to the client for a HTTP request.
The body of the request can be read from this connection using functions
such as
require_multipart_body
.
pub opaque type Connection
A convenient alias for a HTTP request with a Wisp connection as the body.
pub type Request =
HttpRequest(Connection)
The value is signed to prevent modification.
The client will be able to read the value but not modify it, or create new
values.
The location of the file on the server.
This is a temporary file and will be deleted when the request has
finished being handled.
Create an empty response with status code 202: Accepted.
Examples
accepted()
// -> Response(202, [], Empty)
pub fn bad_request() -> Response(Body)
Create an empty response with status code 400: Bad request.
Examples
bad_request()
// -> Response(400, [], Empty)
pub fn configure_logger() -> Nil
Configure the Erlang logger, setting the minimum log level to info, to be
called when your application starts.
You may wish to use an alternative for this such as one provided by a more
sophisticated logging library.
In future this function may be extended to change the output format.
Create a connection which will return the given body when read.
This function is intended for use in tests, though you probably want the
wisp/testing module instead.
Delete any temporary files created for the given request.
If you are using the mist_handler function or another compliant web server
adapter then this file will be deleted for you when the request is complete.
Otherwise you will need to call this function yourself.
pub fn entity_too_large() -> Response(Body)
Create an empty response with status code 413: Entity too large.
Examples
entity_too_large()
// -> Response(413, [], Empty)
pub fn escape_html(content: String) -> String
Escape a string so that it can be safely included in a HTML document.
Any content provided by the user should be escaped before being included in
a HTML document to prevent cross-site scripting attacks.
The operating system send_file function is used to efficiently send the
file over the network socket without reading the entire file into memory.
The content-disposition header will be set to attachment; filename="name" to ensure the file is downloaded by the browser. This is
especially good for files that the browser would otherwise attempt to open
as this can result in cross-site scripting vulnerabilities.
If you wish to not set the content-disposition header you could use the
set_body function with the File body variant.
If your file is already on the disc use file_download instead, to avoid
having to read the file into memory to send it.
The content-disposition header will be set to attachment; filename="name" to ensure the file is downloaded by the browser. This is
especially good for files that the browser would otherwise attempt to open
as this can result in cross-site scripting vulnerabilities.
pub fn get_max_files_size(request: Request(Connection)) -> Int
Get the maximum permitted total size of a files uploaded by a request in
bytes.
) -> List(#(String, String))
Parse the query parameters of a request into a list of key-value pairs. The
key_find function in the gleam/list stdlib module may be useful for
finding values in the list.
Query parameter names do not have to be unique and so may appear multiple
times in the list.
pub fn get_read_chunk_size(request: Request(Connection)) -> Int
Get the size limit for each chunk of the request body when read from the
client.
A middleware function that converts HEAD requests to GET requests,
handles the request, and then discards the response body. This is useful so
that your application can handle HEAD requests without having to implement
handlers for them.
The x-original-method header is set to "HEAD" for requests that were
originally HEAD requests.
This function overrides an incoming POST request with a method given in
the request’s _method query paramerter. This is useful as web browsers
typically only support GET and POST requests, but our application may
expect other HTTP methods that are more semantically correct.
The methods PUT, PATCH, and DELETE are accepted for overriding, all others
are ignored.
The _method query paramerter can be specified in a HTML form like so:
Examples
fn handle_request(request: Request) -> Response {
let request = wisp.method_override(request)
// The method has now been overridden if appropriate
Create an empty response with status code 308: Moved Permanently, and the
location header set to the given URL. Used to redirect the client to
another page.
This redirect is permanent and the client is expected to cache the new
location, using it for future requests.
Create a new temporary directory for the given request.
If you are using the mist_handler function or another compliant web server
adapter then this file will be deleted for you when the request is complete.
Otherwise you will need to call the delete_temporary_files function
yourself.
pub fn no_content() -> Response(Body)
Create an empty response with status code 204: No content.
Examples
no_content()
// -> Response(204, [], Empty)
pub fn not_found() -> Response(Body)
Create an empty response with status code 404: No content.
Examples
not_found()
// -> Response(404, [], Empty)
Read the entire body of the request as a bit string.
You may instead wish to use the require_bit_array_body or the
require_string_body middleware functions instead.
This function does not cache the body in any way, so if you call this
function (or any other body reading function) more than once it may hang or
return an incorrect value, depending on the underlying web server. It is the
responsibility of the caller to cache the body if it is needed multiple
times.
If the body is larger than the max_body_size limit then an empty response
with status code 413: Entity too large will be returned to the client.
pub fn redirect(to url: String) -> Response(Body)
Create an empty response with status code 303: See Other, and the location
header set to the given URL. Used to redirect the client to another page.
A middleware function which reads the entire body of the request as a bit
string.
This function does not cache the body in any way, so if you call this
function (or any other body reading function) more than once it may hang or
return an incorrect value, depending on the underlying web server. It is the
responsibility of the caller to cache the body if it is needed multiple
times.
If the body is larger than the max_body_size limit then an empty response
with status code 413: Entity too large will be returned to the client.
Examples
fn handle_request(request: Request) -> Response {
use body <- wisp.require_string_body(request)
// ...
This middleware function ensures that the request has a value for the
content-type header, returning an empty response with status code 415:
Unsupported media type if the header is not the expected value
A middleware which extracts form data from the body of a request that is
encoded as either application/x-www-form-urlencoded or
multipart/form-data.
Extracted fields are sorted into alphabetical order by key, so if you wish
to use pattern matching the order can be relied upon.
fn handle_request(request: Request) -> Response {
use form <- wisp.require_form(request)
case form.values {
[#("password", pass), #("username", username)] -> // ...
_ -> // ...
The set_max_body_size, set_max_files_size, and set_read_chunk_size can
be used to configure the reading of the request body.
Any file uploads will streamed into temporary files on disc. These files are
automatically deleted when the request handler returns, so if you wish to
use them after the request has completed you will need to move them to a new
location.
If the request does not have a recognised content-type header then an
empty response with status code 415: Unsupported media type will be returned
to the client.
If the request body is larger than the max_body_size or max_files_size
limits then an empty response with status code 413: Entity too large will be
returned to the client.
If the body cannot be parsed successfully then an empty response with status
code 400: Bad request will be returned to the client.
A middleware which extracts JSON from the body of a request.
fn handle_request(request: Request) -> Response {
use json <- wisp.require_json(request)
// decode and use JSON here...
The set_max_body_size and set_read_chunk_size can be used to configure
the reading of the request body.
If the request does not have the content-type set to application/json an
empty response with status code 415: Unsupported media type will be returned
to the client.
If the request body is larger than the max_body_size or max_files_size
limits then an empty response with status code 413: Entity too large will be
returned to the client.
If the body cannot be parsed successfully then an empty response with status
code 400: Bad request will be returned to the client.
This middleware function ensures that the request has a specific HTTP
method, returning an empty response with status code 405: Method not allowed
if the method is not correct.
A middleware function which reads the entire body of the request as a string.
This function does not cache the body in any way, so if you call this
function (or any other body reading function) more than once it may hang or
return an incorrect value, depending on the underlying web server. It is the
responsibility of the caller to cache the body if it is needed multiple
times.
If the body is larger than the max_body_size limit then an empty response
with status code 413: Entity too large will be returned to the client.
If the body is found not to be valid UTF-8 then an empty response with
status code 400: Bad request will be returned to the client.
Examples
fn handle_request(request: Request) -> Response {
use body <- wisp.require_string_body(request)
// ...
) -> Response(Body)
A middleware function that rescues crashes and returns an empty response
with status code 500: Internal server error.
Create an empty response with the given status code.
Examples
response(200)
// -> Response(200, [], Empty)
A middleware function that serves files from a directory, along with a
suitable content-type header for known file extensions.
Files are sent using the File response body type, so they will be sent
directly to the client from the disc, without being read into memory.
The under parameter is the request path prefix that must match for the
file to be served.
This middleware will discard any .. path segments in the request path to
prevent the client from accessing files outside of the directory. It is
advised not to serve a directory that contains your source code, application
configuration, database, or other private files.
Typically you static assets may be kept in your project in a directory
called priv. The priv_directory function can be used to get a path to
this directory.
fn handle_request(req: Request) -> Response {
let assert Ok(priv) = priv_directory("my_application")
use <- wisp.serve_static(req, under: "/static", from: priv)
// ...
Set a cookie on the response. After max_age seconds the cookie will be
expired by the client.
This function will sign the value if the security parameter is set to
Signed, making it so the cookie cannot be tampered with by the client.
Values are base64 encoded so they can contain any characters you want, even
if they would not be permitted directly in a cookie.
Cookies are set using gleam_http’s default attributes for HTTPS. If you
wish for more control over the cookie attributes then you may want to use
the gleam/http/cookie module from the gleam_http package instead of this
function. Be sure to sign and escape the cookie value as needed.
Examples
Setting a plain text cookie that the client can read and modify:
Set the maximum permitted size of a request body of the request in bytes.
If a body is larger than this size attempting to read the body will result
in a response with status code 413: Entity too large will be returned to the
client.
This limit only applies for headers and bodies that get read into memory.
Part of a multipart body that contain files and so are streamed to disc
instead use the max_files_size limit.
) -> Request(Connection)
Set the maximum permitted size of all files uploaded by a request, in bytes.
If a request contains fails which are larger in total than this size
then attempting to read the body will result in a response with status code
413: Entity too large will be returned to the client.
This limit only applies for files in a multipart body that get streamed to
disc. For headers and other content that gets read into memory use the
max_files_size limit.
) -> Request(Connection)
The the size limit for each chunk of the request body when read from the
client.
This value is passed to the underlying web server when reading the body and
the exact size of chunks read depends on the server implementation. It most
likely will read chunks smaller than this size if not yet enough data has
been received from the client.
) -> Request(Connection)
Set the secret key base used to sign cookies and other sensitive data.
This key must be at least 64 bytes long and should be kept secret. Anyone
with this secret will be able to manipulate signed cookies and other sensitive
data.
Panics
This function will panic if the key is less than 64 bytes long.
Sign a message which can later be verified using the verify_signed_message
function to detect if the message has been tampered with.
Signed messages are not encrypted and can be read by anyone. They are not
suitable for storing sensitive information.
This function uses the secret key base from the request. If the secret
changes then the signature will no longer be verifiable.
Set the body of a response to a given string builder.
You likely want to also set the request content-type header to an
appropriate value for the format of the content.
Examples
let body =
response(201)
|> string_body("Hello, Joe!")
// -> Response(
// 201,
// [],
// Text(string_builder.from_string("Hello, Joe"))
Set the body of a response to a given string builder.
You likely want to also set the request content-type header to an
appropriate value for the format of the content.
Examples
let body = string_builder.from_string("Hello, Joe!")
response(201)
|> string_builder_body(body)
// -> Response(201, [], Text(body))
pub fn unprocessable_entity() -> Response(Body)
Create an empty response with status code 422: Unprocessable entity.
