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)