Display mail attachments

Without this, mails might be huge, eating large amount of space in DB or filesystem, without any value at all.

One of the key points with this code is, we should check the resource / memory usage and try to be very friendly.
Inmail could introduce the idea to offload attachments to temporary files when parsing, or skip them at all until they are really accessed.

See the API / Parser level issue: #2805533: META Special treatment for attachment / image parts in parser

See mockup discussion at #2804587-6: Create mail display mock-ups

It would not be the parser that is extended. The parser just identifies the mail standard elements and does this correct following the standard. The missing piece there is adress parsing.

We could introduce a new helper that converts / filters / accesses these elements to be more prepared for display.

But for now i would recommend put this into preprocess and move the logic into a helper with follow-ups. I highly recommend to make the features just work as simple as possible with the first iteration (incl test coverage).

Would be really nice to get a status screenshot if you implement some feature like this with visual elements. It takes quite some steps to setup an environment to test drive it and "see" it to understand if it works for the user or not.

1. +++ b/src/Tests/InmailMessageWebTest.php
   @@ -0,0 +1,64 @@
   +    $this->assertRaw('<img src="" alt="hello.txt" class="inmail-message--attachment-text">');
   ...
   +    $this->assertRaw('<img src="" alt="square.png" class="inmail-message--attachment-image">');
   

   Why an image without source and figcaption?
   What we semantically deliver is more a bullet item than an image with metadata.

2. +++ b/src/Tests/InmailMessageWebTest.php
   @@ -0,0 +1,64 @@
   +    $this->assertRaw('<figcaption>hello.txt</figcaption>');
   ...
   +    $this->assertRaw('<figcaption>square.png</figcaption>');
   

   I'm missing a basic file size indication.

3. +++ b/tests/modules/inmail_test/eml/attachments/simple.eml
   @@ -0,0 +1,40 @@
   +Content-Type: text/plain; charset=US-ASCII; name="hello.txt"
   +Content-Disposition: attachment; filename="hello.txt"
   ...
   +Content-Type: image/png; name="square.png"
   +Content-Disposition: attachment; filename="square.png"
   

   Please test with longer filenames and also special chars.

   And also add other examples such as Content-Disposition: inline.

Cool.

But we don't commit large files just to verify file size asserts. In that case, i trust the code works.
If you really need to pass in large data into the mail, you can pick any file or create dummy data and do base64 encode.

Follow-Up: The special characters will be important and need to be asserted.. Note though that the mail body is in different encoding than the browser, so you need to think properly about both collation and encoding. You might need to inline-base64-encode the filename header...

+++ b/inmail.module
@@ -351,7 +355,90 @@ function inmail_theme() {
+function inmail_preprocess_inmail_multipart_message(&$variables) {
...
+    foreach (InmailMessage::filterMessageParts($message) as $type => $message_parts) {
...
+            $variables['attachments'][] = inmail_message_build_attachment($message_part);
...
+          $variables['unknown'] = [];

+++ b/src/Element/InmailMessage.php
@@ -69,37 +66,48 @@ class InmailMessage extends RenderElement {
+  public static function filterMessageParts(MultipartEntity $multipart_entity) {
...
     foreach ($multipart_entity->getParts() as $message_part) {
...
+            $elements['attachments'][] = $message_part;
...
+            $elements['inline'][] = $message_part;
...
+            $elements['unknown'][] = $message_part;

You should start to track which parts (numeric keys) are used so later code knows about it. Don't drop the numbers because it will no more be possible to return a reference to it. For instance (follow-up), a download filename will need to link to the part for download, which will need the part key.

Committed. More stuff, display adjustment in follow-ups.

+++ b/inmail.module
@@ -351,7 +355,90 @@ function inmail_theme() {
+function inmail_message_get_attachment_file_size($content, $encoding, $precision = 2) {
...
+  $suffixes = ['B', 'KB', 'MB', 'GB', 'TB'];
...
+  return round(pow(1024, $base - floor($base)), $precision) . ' ' . $suffixes[floor($base)];

Follow-Up: This would be the perfect example for a unit test.

Oops, PHPStorm also warns about this piece:
$suffixes[floor($base)]

floor() still returns float and is not save as array key. You need to cast it to (int).

Tested a bit more, did some longer review, testing multipart worked most easily with this:
cat tests/modules/inmail_test/eml/attachments/complex.eml | drush --uri=http://d8.dev/ inmail-process drush

Follow-Up: The headers still don't look like the mockup.
This also applies to the attachment list. That list should also have a semantical title "Attachments".
We should start with some wrappers and reduce the header area. It really needs to start look nice.

Follow-Up: If i accidentally forget to provide the deliverer, i get these error messages:

 [warning] array_flip(): Can only flip STRING and INTEGER values! EntityStorageBase.php:227
 [error]  Deliverer "" not found 

There is no feedback on the terminal about processing.
Follow-Up:
\Drupal\inmail\MessageProcessor::process should return the ProcessorResult... and later processMultiple should return an array of these by preserving the keys.
Then, drush_inmail_process() can check for verbose flag and output feedback.
Also from the Paste email tab, the response is just "The message has been processed.". It should additionally display a link to the log record if logging is enabled.

Follow-Up: Improve logging
The log record created displays two valueless arguments:
DRUPAL\INMAIL\DEFAULTANALYZERRESULT
[contexts] (object):
MODERATORFORWARDHANDLER
[0] (object):
[string] (string): Moderator email address not set
This seems pretty useless to me. There is an issue to build a meaningful context summary for logging.
Funnily, the ForwardHandler doesn't report anything if it forwards the mail. Instead it logs if it is unconfigured... Do we need log severities?

Follow-Up: Download attachments on click
This will need a passthrough route. The element doesn't know where an element is stored. So the element should get an attachment route key from the caller. If not provided, the attachments are not linked.

Follow-Up: Deliver images
First simply deliver them so that they are displayed in a browser. Later also support inline images.

Back to needs-work to create the follow-up issues. Please close when created.