diff options
Diffstat (limited to 'core/notes/structure.md')
| -rw-r--r-- | core/notes/structure.md | 157 |
1 files changed, 157 insertions, 0 deletions
diff --git a/core/notes/structure.md b/core/notes/structure.md new file mode 100644 index 0000000..775fa47 --- /dev/null +++ b/core/notes/structure.md @@ -0,0 +1,157 @@ +# **Warning: document is not up to date** + +# Naming differences + +(note that `foo/bar` means crate `foo` with feature `bar` enabled) + +- `mail-codec` => `mail-encode` +- `mail-codec-composition` => `mail-encode-compose` +- `mail-codec-composition/smtp` => `mail-tokio-smtp/encode` +- `mail-headers` => `mail-headers/encode` +- `mail-internals` => `mail-core/encode` + + +# Dependency Chart + +(updated) +```ascii + + + mail-smtp mail-templates (maybe at some point)mail-parser +new-tokio-smtp---------/ | | \ | + | | \-handle-bars | + <[mail-core]>----/--------------/-----------------------------------/ + | + | + mail-headers + | + | + mail-internals +``` + +crates marked with a * have both parser and encoder specific parts, +which are opt-in/-out through features. + +# Descriptions + +## Mail-Core + +This crate provides parts used by all other parts using +the `encode`/`parse` features encoding/parsing specific +parts are enabled/disabled. (Currently it's just encoding). + +Parts included are the EncodingBuffer, HeaderMap, Header traits, +encoding traits, bindings to other encoding libraries like +base64, percent-encode and similar. + +## Mail-Headers + +A create providing implementations for the most +mail-internals headers. Like `mail-core` encoding/parsing specific +parts can be enabled/disabled using the `encode`/`decode` +feature. A Header basically consists of a name and a Header component, +which can be encoded and represents the header field. + +Many of those components can be reused at different +points, e.g. `Mailbox`/`MailboxList`/`Email`/`Phrase`/... + + +## Mail-Encode + +This crate provides a basic mechanism to create and +encode mails with includes a Mail types which can +represent any form of mails, from simple text mails +to complex multipart mails. While this API can be +used to represent any mail it is not nessesary the +most convinient to use, as it requires the user to +handle aspects like e.g. which multipart content type +is used, and how they are structured. + +Additional to the Mail struct it provides a mechanism +to encode the Mail struct with the EncodingBuffer provided +by `mail-core` produceing a mail in form of a +string, ascii-string or bytes a required by the consumer. +(the encoder does know about 7bit, 8bit and utf8 i.e. +internationalized mails). + +As a mail can contain all kinds of embedded data (e.g. +atachments, embeded images in a html mail etc.). This +create also provides a way to handle such resources +as part of a mail. + + +## Mail-Encode-Compose + +Is build on-top of `mail-encode` providing traits and mechanism, +to bind in template engines, allowing the API consumer to +create mails based on from, to, subject, template_id and +template_data. The template engine only has to provide +a number of alternate bodies with embeddings/attachments +caused by them. The mail-composition crate takes care of +composing them into a mail multipart tree +(using `multipart/related`,`multipart/mixed`, etc.) + +Currently `mail-composition` does not have explicit support for +e.g. encryption and some other "more special" multipart +bodies. Nevertheless by using the API provided by Mail this +mail can still be created, they do just not jet bind with +the template engine by default. + +The crate also provides a pre-build template engine through a +feature which just needs another template engine to render +mail content bodies (e.g. text/html) and handles all the +other parts, like e.g. providing a logo for an HTML mail +as an embedding (as a side note generation of CID's and +providing them to the template data is already handled) + +# Mail + +A facade for all `mail-*` crates, providing a `encode` +`parse` feature to enable/disable the encoding/parsing +parts, and more fine grained features for more fain +grained control over what is included. This +takes advantage of rust features being additive, e.g. +if one dependency includes `mail/encode` and one `mail/decode` +than rust will only include one time `mail` with both +`encode` and `decode` enabled. + +(this crate does not yet exist) + + +# Mail-Tokio-Smtp + +This crate will provide bindings between the mail +crates and a crate providing tokio-smtp support. +While smtp is mainly a transport protocol this +crate provides bindings to make thinks easy to +use and setup, e.g. the `mail-encode-compose` +library does provide a method `compose_mail(MailSendData) -> Result<Mail>` +(called on a combination of Context and TemplateEngine), +but if you want to use this as a request in a smtp +service to send a mail, there is quite a bit of bind +code doing everything from calling compose_mail, making +it encodable, encoding it and sending the right smtp +commands. + +Currently this functionality lives in `mail-encode-compose` +under the `smtp` feature and use `tokio-smtp` as binding +library and is limited to binding with the mechanism provided +in `mail-encode-compose` but not general `Mail` structs (through +is will change in the future) + + +# Mail-parse + +A crate providing functionality for parsing mails, it +will use a combination of `Arc`/`Rc` and `OwningRef` +to allow a zero-copy parsing of mails, nevertheless +as mail normaly do contain parts further encoded in +e.g. base64 it will provide a mechanism where parts +of the mail can be shadowed by a decoded version +of the part generated on-demand/lazily. + +**This crate currently does not exist, and focus lies +on the encoding based crates** + +Through the crate structure is setup to include parsing +specific parts in the future.
\ No newline at end of file |