moonmime

#What it does

• Media types. Parse a Content-Type into an essence and ordered parameters, and write it back with correct quoting (RFC 2045 §5.1, RFC 2046 §4.2). Strict reading follows the MIME Sniffing standard for the places where a wrong guess is worse than a refusal.
• The registry. Map a filename to the media type its extension implies, and a media type to the extension people actually use.
• Content-Disposition. Build and parse the header that names a download, with filename* (RFC 5987) for names that leave ASCII.
• Multipart. Split any multipart body into parts (RFC 2046 §5.1) — the shape an email and a form upload share.
• Streaming. Read a part's header fields before its body has arrived and take the body as it comes; write a body a part at a time into a sink. The bounds hold while reading, not after.
• Related. multipart/related (RFC 2387) with its type, start and start-info: which part is the root, and what the root is to be read as.
• Form data. Read multipart/form-data (RFC 7578) into text fields and file uploads.
• Writing. Frame parts as multipart/mixed, or a Form as multipart/form-data, with a boundary proven absent from the content and filename* (RFC 5987) for a file name that leaves ASCII.
• Encoded words. Write a header value as RFC 2047 encoded words, B or Q, split so no word passes 75 characters, and read any mix of words and plain text back.
• Quoted-printable. moonmime/qp encodes and decodes a body (RFC 2045 §6.7): soft breaks at 76 columns, =XY escapes, trailing whitespace protected.
• Charsets. UTF-8, US-ASCII and ISO-8859-1 come with the library; any other set is a Charset you pass in, so nothing is registered globally.

#Install

moon add moonbitstack/moonmime

import {
  "moonbitstack/moonmime",
}

#Use it

#Read a media type

let mt = @moonmime.media_type("Text/HTML; charset=UTF-8")
println(mt.essence)                         // text/html
println(mt.type_())                         // text
println(mt.subtype())                       // html
println(mt.param("charset").unwrap_or(""))  // UTF-8
println(mt.to_string())                     // text/html; charset=UTF-8

let mt = @moonmime.MediaType::parse("Text/HTML; charset=\"utf-8\"").unwrap()
println(mt.essence)                          // text/html
println(mt.param("charset").unwrap_or(""))   // utf-8

let listed = @moonmime.MediaType::parse("text/html, text/plain")
println(listed is None)                      // true

#Name a download

println(@moonmime.content_disposition("menu.pdf"))
// attachment; filename="menu.pdf"

println(@moonmime.content_disposition("receta \"de la abuela\".pdf"))
// attachment; filename*=utf-8''receta%20%22de%20la%20abuela%22.pdf

let d = @moonmime.Disposition::parse(
  "attachment; filename=\"fallback.txt\"; filename*=utf-8''r%C3%A9sum%C3%A9.txt",
)
println(d.filename().unwrap_or(""))  // résumé.txt

#Guess from a filename

println(@moonmime.guess_type("photo.jpg"))                    // image/jpeg
println(@moonmime.guess_type("archive.tar.gz"))               // application/gzip
println(@moonmime.guess_extension("image/jpeg").unwrap_or(""))  // .jpg

#Split a body, then read it as a form

// `body` is the raw bytes; `boundary` is the delimiter without its leading dashes.
let boundary = "----edge"
let body = b"------edge\r\nContent-Disposition: form-data; name=\"recipe\"\r\n\r\nchiles en nogada\r\n------edge--\r\n"
let parts = @moonmime.multipart(body[:], boundary)
assert_eq(parts.length(), 1)
assert_eq(parts[0].header("content-disposition").unwrap_or(""), "form-data; name=\"recipe\"")

let form = @moonmime.formdata(body[:], boundary)
assert_eq(form.field("recipe"), Some("chiles en nogada"))
assert_eq(form.uploads().length(), 0)

#Write one back

let fields : Array[@moonmime.Field] = [
  { name: "recipe", value: "chiles en nogada" },
  { name: "mood", value: "happy" },
]
let written = @moonmime.Form::new(fields~).encode(boundary="----edge")
assert_eq(written.content_type(), "multipart/form-data; boundary=----edge")
assert_eq(
  @moonmime.formdata(written.body[:], written.boundary).field("mood"),
  Some("happy"),
)

let named = @moonmime.Form::new(
  files=[
    {
      name: "doc",
      filename: "résumé.pdf",
      content_type: "application/pdf",
      content: b"%PDF",
      headers: [],
    },
  ],
).encode(boundary="----edge")
let part = @moonmime.multipart(named.body[:], named.boundary)[0]
assert_eq(
  part.header("content-disposition"),
  Some("form-data; name=\"doc\"; filename*=utf-8''r%C3%A9sum%C3%A9.pdf"),
)

let mixed = @moonmime.Multipart::new([
  { headers: [("content-type", "text/plain")], body: b"hola" },
])
assert_eq(mixed.content_type(), "multipart/mixed; boundary=----moonmime")
assert_eq(@moonmime.multipart(mixed.body[:], mixed.boundary)[0].body, b"hola")

#Read a body as it arrives

let raw = b"------edge\r\nContent-Disposition: form-data; name=\"recipe\"\r\n\r\nchiles en nogada\r\n------edge--\r\n"
let reader = @moonmime.PartsReader::new(@moonmime.Chunks::new(raw[:]), "----edge")
let head = reader.next_part().unwrap()
assert_eq(head.header("content-disposition").unwrap_or(""), "form-data; name=\"recipe\"")
assert_eq(head.disposition().unwrap().param("name"), Some("recipe"))
assert_eq(reader.read().unwrap(), b"chiles en nogada")
assert_eq(reader.next_part() is None, true)

let sink = @moonmime.Gathered::new()
let writer = @moonmime.MultipartWriter::new(
  sink,
  boundary="----edge",
  kind=@moonmime.MultipartKind::FormData,
)
writer.begin_part([("content-disposition", "form-data; name=\"recipe\"")])
writer.body(b"chiles en nogada")
writer.close()
assert_eq(writer.content_type(), "multipart/form-data; boundary=----edge")
assert_eq(
  @moonmime.formdata(sink.bytes()[:], "----edge").field("recipe"),
  Some("chiles en nogada"),
)

#A related body

let related = @moonmime.Related::new(
  [
    {
      headers: [("content-id", "<root>"), ("content-type", "text/html")],
      body: b"<img src=\"cid:logo\">",
    },
    {
      headers: [("content-id", "<logo>"), ("content-type", "image/png")],
      body: b"\x89PNG",
    },
  ],
  boundary="----rel",
  type_="text/html",
  start="<root>",
)
assert_eq(
  related.content_type(),
  "multipart/related; boundary=----rel; type=\"text/html\"; start=\"<root>\"",
)
let read = @moonmime.related(related.content_type(), related.body())
assert_eq(read.root().unwrap().content_id(), Some("root"))
assert_eq(read.root().unwrap().body, b"<img src=\"cid:logo\">")

#Write a header that leaves ASCII, and a body that must stay 7-bit

let subject = @moonmime.encode_words("Grüße aus München")
assert_eq(@moonmime.decode_words(subject), "Grüße aus München")

let qp_bytes = @qp.encode(b"caf\xc3\xa9 = coffee")
assert_eq(@qp.decode(qp_bytes), b"caf\xc3\xa9 = coffee")

assert_eq(@moonmime.encode_charset(name="iso-8859-1", text="é"), b"\xe9")
assert_eq(@moonmime.decode_charset(name="iso-8859-1", data=b"\xe9"), "é")

#Interface

#Bounds

let small = @moonmime.Limits::new(parts=8, part_size=64 * 1024)
assert_eq(@moonmime.formdata(body[:], boundary, limits=small).field("recipe"), Some("chiles en nogada"))

#Examples

• src/examples/lookup — filenames and media types, both directions.
• src/examples/form — read a multipart/form-data upload, then write it back.
• src/examples/stream — read a body a chunk at a time, write one a part at a time.
• src/examples/tour — every call once, end to end.
• src/examples/browser — the same library compiled to JavaScript for the live demos.

moon run src/examples/lookup
moon run src/examples/form
moon run src/examples/stream
moon run src/examples/tour

#Conformance

• mimesniff/sniffing/* and mimesniff/media/* ask what a browser does with a response — whether an <img>, an <iframe>, or a navigation keeps the type it was handed. Answering them needs an HTML parser and a network stack. This library decides the type of a value it is given; it does not sniff content.
• mimesniff/mime-types/charset-parameter.window.js checks which encoding a frame derives from a charset parameter, which is document decoding rather than the header itself.
• resources/mime-groups.json lists the groups a type belongs to for Accept computation; this library has no group API.
• resources/mime-types-minimized.json covers the navigation algorithm's minimized MIME type, which also needs a browsing context.

#The extension table

#Bidirectional interop

• Folded headers. Python's generator folds a long Content-Disposition across lines, so a part's header block arrives folded. Reading unfolds it (RFC 5322 §2.2.3): the break is dropped and the whitespace that opens the continuation stands for it.
• A body with no parts. This library writes one closing delimiter. Python's generator writes an opening delimiter, a blank line and then the closing one, which every reader in reach takes for a single part with no header field and no content. The case says so, and the check requires the disagreement to still be there rather than pass over it.

#Licence