mime

Build MIME messages (multipart, attachments, RFC 5322) and look up media types by file extension. Pure - no capabilities.

ecko get github.com/ecko-lang/mime
import mime

Pure computation: it declares no capabilities, so it cannot touch the network, the filesystem or the environment.

Version 0.56.0 - source - MIT.


table()

The extension-to-type map, keyed by lowercase extension without the dot.

Exposed so a caller can see exactly what is known rather than probing type_for.

Grouped in source order: text, structured data, documents, images, audio and video, archives, fonts, then everything else. The groups are not marked with comments inside the literal on purpose - ecko fmt hoists a comment out of a map literal and then reports the file as unformatted for ever after (core card 34b0992f).

type_for(path)

The media type for a filename or path, from its extension.

Case-insensitive; only the last path component is considered. Anything unrecognised, or with no extension, is application/octet-stream.

errors: bug/bad_argument when path is not a string.

mime.type_for("/srv/Photo.PNG")   # "image/png"

preferred_extensions()

The type-to-extension map extension_for uses.

Written out rather than derived by scanning table(): several types map from more than one extension (image/jpeg from both "jpg" and "jpeg", text/plain from both "txt" and "ecko"), and Ecko maps are unordered, so a scan would pick a different answer run to run.

extension_for(content_type)

The preferred file extension for a media type, or null when none is known.

Parameters are ignored, so "text/plain; charset=utf-8" still answers "txt". application/octet-stream deliberately maps to null: it is the fallback for unknown bytes, not a type with a file extension.

errors: bug/bad_argument when content_type is not a string.

mime.extension_for("image/jpeg")   # "jpg"

trim_type(content_type)

A media type with its parameters removed.

errors: bug/bad_argument when content_type is not a string.

mime.trim_type("text/plain; charset=utf-8")   # "text/plain"

message(spec)

Start a message from spec: { from, to, subject?, date?, headers? }.

to may be one address or a list of them. subject defaults to "". headers is a map of extra headers; it may not set a header render writes itself (From, To, Subject, Date, MIME-Version, Content-Type, Content-Transfer-Encoding, Content-Disposition). CR and LF are stripped from every header value, and non-ASCII text is RFC 2047 encoded when rendered. Parts are added with text, html and attach.

errors: bug/missing_field when from or to is missing; bug/bad_argument when spec is not a map, a field has the wrong type or to is empty; bug/reserved_header when headers sets a generated header.

mime.message({ from: "a@x.test", to: ["b@y.test", "c@z.test"], subject: "Hi" })

text(msg, body)

Add a text/plain part.

Line endings are normalized to CRLF. A body with a line longer than 998 octets is sent quoted-printable instead of 8bit.

errors: bug/bad_argument when msg is not a message or body is not a string.

mime.message({ from: "a@x.test", to: "b@y.test" }) |> mime.text("hello")

html(msg, body)

Add a text/html part.

A message carrying both text and html renders them as multipart/alternative, in the order added, so put the plain text first: a reader picks the last part it understands.

errors: bug/bad_argument when msg is not a message or body is not a string.

msg |> mime.text("hi") |> mime.html("<p>hi</p>")

attach(msg, filename, data)

Attach a file, with the media type inferred from the filename's extension.

Falls back to application/octet-stream for an unknown extension. data may be bytes or a string. A non-ASCII filename is sent as an RFC 2231 filename* parameter.

errors: bug/bad_argument when filename is not a string or data is neither bytes nor a string.

msg |> mime.attach("report.pdf", pdf_bytes)

attach_as(msg, filename, data, content_type)

Attach a file with its media type given explicitly, for content whose extension does not describe it.

errors: bug/bad_argument when filename or content_type is not a string or data is neither bytes nor a string.

msg |> mime.attach_as("data.bin", raw, "application/x-custom")

add_part(msg, part)

Append a prepared part, for a shape this package does not model.

part is { content_type, body, encoding?, filename?, kind? }: body is sent as given (already encoded for encoding, which defaults to "8bit"), and a filename adds a Content-Disposition: attachment. A part whose kind is not "text" or "html" sits beside the attachments in multipart/mixed.

errors: bug/bad_argument when msg is not a message, or part is not a map with string content_type and body.

msg |> mime.add_part({ content_type: "text/calendar; method=REQUEST", body: ics })

boundary_of(msg)

The multipart delimiter render will use at the top level of msg.

It is derived from a hash of the parts rather than randomised. That buys two things: it cannot collide with the content, because content containing the boundary would have hashed differently, and the same message renders byte-identically every time, so rendered messages can be diffed and asserted on.

errors: bug/bad_argument when msg is not a message.

mime.boundary_of(msg)   # "=_ecko_" followed by 32 hex digits

subtype_of(msg)

The top-level multipart subtype: "mixed", "alternative", or null.

null is a single part with no multipart wrapper. Text and html alone are "alternative". Anything with an attachment or a custom part is "mixed", and when it also has both text and html, those two sit together in a nested multipart/alternative as its first member.

errors: bug/bad_argument when msg is not a message.

mime.subtype_of(msg |> mime.text("a") |> mime.html("<p>a</p>"))   # "alternative"

render(msg)

Render to the map smtp_client.send takes: { from, to, subject, headers, body, date? }.

The MIME headers land in headers, so the transport does not have to know anything about multiparts. date is present only when the message has one.

errors: mime/no_parts for a message with no parts - an empty body is almost always a caller bug rather than an intent; bug/bad_argument when msg is not a message.

mime.render(mime.message({ from: "a@x.test", to: "b@y.test" }) |> mime.text("hi")).body   # "hi"

to_string(msg)

The whole message as RFC 5322 text, headers and all.

render is what you hand to a transport; this is for writing a .eml, a fixture, or a test. Headers after From, To, Subject and Date are sorted by name, so the output is stable.

errors: as render.

mime.to_string(mime.message({ from: "a@x.test", to: "b@y.test", subject: "Hi" }) |> mime.text("hello"))