#lang scribble/manual

@(require (for-label racket/base
                     racket/contract
                     racket-mimetypes))

@title{racket-mimetypes}
@author[@author+email["Hans Dijkema" "hans@dijkewijk.nl"]]

@defmodule[racket-mimetypes]

The @racketmodname[racket-mimetypes] library maps file extensions to MIME
types. It uses a built-in fallback table and keeps a validated copy of
Apache's @tt{mime.types} in Racket's user cache directory.
The cache file is stored below @racket[(find-system-path 'cache-dir)] in the
@tt{racket-mimetypes} directory.

The first lookup that finds an expired cache starts a background update.
Lookups never wait for the download. After a successful update, the next
check is performed after seven days. After a failed update, the next attempt
is made after one day. Both outcomes are written as debug messages through
the @racketmodname[simple-log] logging system.

The downloaded file is parsed and validated before it replaces the cache.
If downloading, parsing, validation, or replacement fails, the existing
cache remains available. If Apache assigns an extension more than once, the
last assignment in the file is used.

@defproc[(mimetype-for-ext
          [ext (or/c path? string? symbol?)]
          [#:default default string? "application/octet-stream"])
         string?]{

Returns the MIME type associated with @racket[ext], or @racket[default] when
the extension is unknown.

@racket[ext] can be an extension, a file name, or a path. Strings and symbols
can contain an extension with or without a leading dot. For a file name or
path, the text after the last dot in the last path component is used.
Matching is case-insensitive.

The procedure does not parse URLs and does not inspect file contents.

@racketblock[
  (mimetype-for-ext 'mp3)
  (mimetype-for-ext ".PNG")
  (mimetype-for-ext "music/track.opus")
  (mimetype-for-ext "unknown" #:default "unknown/type")
]}