Return the non-empty segments of a request path.

Examples

> request.new()
> |> request.set_path("/one/two/three")
> |> wisp.path_segments
["one", "two", "three"]

Returns the path of a package’s priv directory, where extra non-Gleam or Erlang files are typically kept.

Returns an error if no package was found with the given name.

Example

> erlang.priv_directory("my_app")
// -> Ok("/some/location/my_app/priv")

Set a given header to a given value, replacing any existing value.

Examples

> wisp.ok()
> |> wisp.set_header("content-type", "application/json")
Request(200, [#("content-type", "application/json")], Empty)

Create an empty response with status code 202: Accepted.

Examples

accepted()
// -> Response(202, [], Empty)

Create an empty response with status code 400: Bad request.

Examples

bad_request()
// -> Response(400, [], Empty)

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.

Create an empty response with status code 201: Created.

Examples

created()
// -> Response(201, [], Empty)

Delete any temporary files created for the given request.

If you are using the Mist adapter 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.

Create an empty response with status code 413: Entity too large.

Examples

entity_too_large()
// -> Response(413, [], Empty)

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.

Examples

escape_html("<h1>Hello, Joe!</h1>")
// -> "&lt;h1&gt;Hello, Joe!&lt;/h1&gt;"

Send a file from the disc as a file download.

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.

Examples

response(200)
|> file_download(named: "myfile.txt", from: "/tmp/myfile.txt")
// -> Response(
//   200,
//   [#("content-disposition", "attachment; filename=\"myfile.txt\"")],
//   File("/tmp/myfile.txt"),
// )

Send a file from memory as a file download.

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.

Examples

response(200)
|> file_download_from_memory(named: "myfile.txt", containing: "Hello, Joe!")
// -> Response(
//   200,
//   [#("content-disposition", "attachment; filename=\"myfile.txt\"")],
//   File("/tmp/myfile.txt"),
// )

Get a cookie from the request.

If a cookie is missing, found to be malformed, or the signature is invalid for a signed cookie, then Error(Nil) is returned.

wisp.get_cookie(request, "group", wisp.PlainText)
// -> Ok("A")

Get the maximum permitted size of a request body of the request in bytes.

Get the maximum permitted total size of a files uploaded by a request in bytes.

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.

Get the size limit for each chunk of the request body when read from the client.

Get the secret key base used to sign cookies and other sensitive data.

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.

Examples

fn handle_request(req: Request) -> Response {
  use req <- wisp.handle_head(req)
  // ...
}

Set the body of a response to a given HTML document, and set the content-type header to text/html.

The body is expected to be valid HTML, though this is not validated.

Examples

let body = string_builder.from_string("<h1>Hello, Joe!</h1>")
response(201)
|> html_body(body)
// -> Response(201, [#("content-type", "text/html; charset=utf-8")], Text(body))

Create a HTML response.

The body is expected to be valid HTML, though this is not validated. The content-type header will be set to text/html.

Examples

let body = string_builder.from_string("<h1>Hello, Joe!</h1>")
html_response(body, 200)
// -> Response(200, [#("content-type", "text/html")], Text(body))

Create an empty response with status code 500: Internal server error.

Examples

internal_server_error()
// -> Response(500, [], Empty)

Set the body of a response to a given JSON document, and set the content-type header to application/json.

The body is expected to be valid JSON, though this is not validated.

Examples

let body = string_builder.from_string("{\"name\": \"Joe\"}")
response(201)
|> json_body(body)
// -> Response(201, [#("content-type", "application/json; charset=utf-8")], Text(body))

Create a JSON response.

The body is expected to be valid JSON, though this is not validated. The content-type header will be set to application/json.

Examples

let body = string_builder.from_string("{\"name\": \"Joe\"}")
json_response(body, 200)
// -> Response(200, [#("content-type", "application/json")], Text(body))

Log a message to the Erlang logger with the level of alert.

See the Erlang logger documentation for more information.

Log a message to the Erlang logger with the level of critical.

See the Erlang logger documentation for more information.

Log a message to the Erlang logger with the level of debug.

See the Erlang logger documentation for more information.

Log a message to the Erlang logger with the level of emergency.

See the Erlang logger documentation for more information.

Log a message to the Erlang logger with the level of error.

See the Erlang logger documentation for more information.

Log a message to the Erlang logger with the level of info.

See the Erlang logger documentation for more information.

Log a message to the Erlang logger with the level of notice.

See the Erlang logger documentation for more information.

A middleware function that logs details about the request and response.

The format used logged by this middleware may change in future versions of Wisp.

Examples

fn handle_request(req: Request) -> Response {
  use <- wisp.log_request(req)
  // ...
}

Log a message to the Erlang logger with the level of warning.

See the Erlang logger documentation for more information.

Create an empty response with status code 405: Method Not Allowed. Use this when a request does not have an appropriate method to be handled.

The allow header will be set to a comma separated list of the permitted methods.

Examples

method_not_allowed(allowed: [Get, Post])
// -> Response(405, [#("allow", "GET, POST")], Empty)

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.

Examples

moved_permanently(to: "https://example.com")
// -> Response(308, [#("location", "https://example.com")], Empty)

Create a new temporary directory for the given request.

If you are using the Mist adapter 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.

Create an empty response with status code 204: No content.

Examples

no_content()
// -> Response(204, [], Empty)

Create an empty response with status code 404: No content.

Examples

not_found()
// -> Response(404, [], Empty)

Create an empty response with status code 200: OK.

Examples

ok()
// -> Response(200, [], Empty)

Generate a random string of the given length.

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.

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.

Examples

redirect(to: "https://example.com")
// -> Response(303, [#("location", "https://example.com")], Empty)

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

Examples

fn handle_request(request: Request) -> Response {
  use <- wisp.require_content_type(request, "application/json")
  // ...
}

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.

Examples

fn handle_request(request: Request) -> Response {
  use <- wisp.require_method(request, http.Patch)
  // ...
}

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)
  // ...
}

A middleware function that rescues crashes and returns an empty response with status code 500: Internal server error.

Examples

fn handle_request(req: Request) -> Response {
  use <- wisp.rescue_crashes
  // ...
}

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.

Examples

fn handle_request(req: Request) -> Response {
  use <- wisp.serve_static(req, under: "/static", from: "/public")
  // ...
}

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 the body of a response.

Examples

response(200)
|> set_body(File("/tmp/myfile.txt"))
// -> Response(200, [], File("/tmp/myfile.txt"))

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:

wisp.ok()
|> wisp.set_cookie(request, "id", "123", wisp.PlainText, 60 * 60)

Setting a signed cookie that the client can read but not modify:

wisp.ok()
|> wisp.set_cookie(request, "id", value, wisp.Signed, 60 * 60)

Set the log level of the Erlang logger to log_level.

See the Erlang logger documentation for more information.

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.

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_body_size limit.

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.

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

Create an empty response with status code 422: Unprocessable entity.

Examples

unprocessable_entity()
// -> Response(422, [], Empty)

Create an empty response with status code 415: Unsupported media type.

The allow header will be set to a comma separated list of the permitted content-types.

Examples

unsupported_media_type(accept: ["application/json", "text/plain"])
// -> Response(415, [#("allow", "application/json, text/plain")], Empty)

Verify a signed message which was signed using the sign_message function.

Returns the content of the message if the signature is valid, otherwise returns an error.

This function uses the secret key base from the request. If the secret changes then the signature will no longer be verifiable.