From 5e05fe8e7877ffd6bc473b77b8ca0a12ad26bd67 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lo=C3=AFc=20Hoguin?= Date: Thu, 14 Mar 2024 16:23:56 +0100 Subject: Cowboy 2.12, Cowlib 2.13, Gun 2.1 --- .../en/cowboy/2.12/manual/cowboy_static/index.html | 278 +++++++++++++++++++++ 1 file changed, 278 insertions(+) create mode 100644 docs/en/cowboy/2.12/manual/cowboy_static/index.html (limited to 'docs/en/cowboy/2.12/manual/cowboy_static/index.html') diff --git a/docs/en/cowboy/2.12/manual/cowboy_static/index.html b/docs/en/cowboy/2.12/manual/cowboy_static/index.html new file mode 100644 index 00000000..9066460e --- /dev/null +++ b/docs/en/cowboy/2.12/manual/cowboy_static/index.html @@ -0,0 +1,278 @@ + + + + + + + + + + Nine Nines: cowboy_static(3) + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

cowboy_static(3)

+ +

Name

+

cowboy_static - Static file handler

+

Description

+

The module cowboy_static implements file serving capabilities using the REST semantics provided by cowboy_rest.

+

The static file handler is a pre-written handler coming with Cowboy. To serve files, use it in your routes.

+

Options

+
+
opts() :: {priv_file, App, Path}
+        | {priv_file, App, Path, Extra}
+        | {file, Path}
+        | {file, Path, Extra}
+        | {priv_dir, App, Path}
+        | {priv_dir, App, Path, Extra}
+        | {dir, Path}
+        | {dir, Path, Extra}
+
+App        :: atom()
+Path       :: binary() | string()
+Extra      :: [Charset | Etag | Mimetypes]
+
+Charset    :: {charset, module(), function()}
+            | {charset, binary()}
+
+Etag       :: {etag, module(), function()}
+            | {etag, false}
+
+Mimetypes  :: {mimetypes, module(), function()}
+            | {mimetypes, binary() | ParsedMime}
+
+ParsedMime :: {Type :: binary(), SubType :: binary(), Params}
+Params     :: [{Key :: binary(), Value :: binary()}]
+
+

Static handler configuration.

+
priv_file
+

Send a file.

+

The path is relative to the given application's private directory.

+
+
file
+

Send a file.

+

The path is either absolute or relative to the Erlang node's current directory.

+
+
priv_dir
+

Recursively serve files from a directory.

+

The path is relative to the given application's private directory.

+
+
dir
+

Recursively serve files from a directory.

+

The path is either absolute or relative to the Erlang node's current directory.

+
+
+

The extra options allow you to define how the etag should be calculated and how the MIME type of files should be detected.

+

By default the static handler will not send a charset with the response. You can provide a specific charset that will be used for all files using the text media type, or provide a module and function that will be called when needed:

+
+
detect_charset(Path :: binary()) -> Charset :: binary()
+
+

A charset must always be returned even if it doesn't make sense considering the media type of the file. A good default is <<"utf-8">>.

+

By default the static handler will generate an etag based on the size and modification time of the file. You may disable the etag entirely with {etag, false} or provide a module and function that will be called when needed:

+
+
generate_etag(Path, Size, Mtime) -> {strong | weak, binary()}
+
+Path  :: binary()
+Size  :: non_neg_integer()
+Mtime :: file:date_time()
+
+

By default the static handler will detect Web-related MIME types by looking at the file extension. You can provide a specific MIME type that will always be used, or a module and function that will be called when needed:

+
+
detect_mimetype(Path) -> ParsedMime
+
+Path       :: binary()
+ParsedMime :: {Type :: binary(), SubType :: binary(), Params}
+Params     :: [{Key :: binary(), Value :: binary()}]
+
+ +

Cowboy comes with two such functions; the default function cow_mimetypes:web/1, and a second function generated from the Apache mime.types file, cow_mimetypes:all/1.

+

The MIME type function should return {<<"application">>, <<"octet-stream">>, []} when it fails to detect a file's MIME type.

+

Changelog

+
  • 2.11: Support for range requests was added in 2.6 and is now considered stable. +
    • +
  • 2.6: The charset extra option was added. +
    • +
  • 1.0: Handler introduced. +
    • +
+

Examples

+
Custom etag function
+
+
generate_etag(Path, Size, Mtime) ->
+    {strong, integer_to_binary(
+        erlang:phash2({Path, Size, Mtime}, 16#ffffffff))}.
+
+
Custom MIME type function
+
+
always_octet_stream(_Path) ->
+    case filename:extension(Path) of
+        <<".erl">> -> {<<"text">>, <<"plain">>, []};
+        _ -> {<<"application">>, <<"octet-stream">>, []}
+    end.
+
+

See also

+

cowboy(7), cowboy_router(3)

+ + + + + + +
+ +
+ + +

+ Cowboy + 2.12 + Function Reference + +

+ + + +

Navigation

+ +

Version select

+ + +

Like my work? Donate!

+

Donate to Loïc Hoguin because his work on Cowboy, Ranch, Gun and Erlang.mk is fantastic:

+
+ + + + + + + + + +

Recurring payment options are also available via GitHub Sponsors. These funds are used to cover the recurring expenses like food, dedicated servers or domain names.

+ + + +
+
+
+
+ + + + + + + + + -- cgit v1.2.3