Merge pull request #64 from conjoon/dev

dev
conjoon · Nov 9, 2022 · c991463 · c991463
2 parents 10959be + 6889788
commit c991463
Show file tree

Hide file tree

Showing 19 changed files with 530 additions and 88 deletions.
diff --git a/README.md b/README.md
@@ -1,38 +1,62 @@
 # conjoon/lumen-app-email ![MIT](https://img.shields.io/github/license/conjoon/lumen-app-email) ![Tests](https://github.com/conjoon/lumen-app-email/actions/workflows/run.tests.yml/badge.svg)
-Microservice for IMAP operations.
+Laravel/Lumen Microservice for RESTful communication with IMAP/SMTP servers.
 
-## About
+## What is lumen-app-email?
 **conjoon/lumen-app-email** is a PHP application built with [Lumen](https://lumen.laravel.com).
 It provides the REST API implementation according to [conjoon\/rest-api-description\#rest-api-email](conjoon/rest-api-description)
-and serves as a functional webmail-backend for IMAP operations.
+and serves as a lightweight backend providing functionality for reading, writing and sending email messages.
+<br />
+It is a ready-to-use backend for accessing IMAP/SMTP-Servers with minimal setup required.
 
-## Available REST API endpoints
-* **rest-api-email**
-  <br>For the list of endpoints this microservice provides, please refer to the OpenApi-documentation of `rest-api-email`,
-  hosted at [conjoon/rest-api-description](https://github.com/conjoon/rest-api-description).
+## Examples
 
-## Installation
+````http request
+# Return a list of available MailAccounts for the requesting client
+GET /rest-api-email/api/v0/MailAccounts HTTP/1.1
+Content-Type: application/json
+Authorization: Basic Y29uam9vbjpIZWxsb1dvcmxk
+Host: hostname
 
-```shell
-$ git clone https://github.com/conjoon/lumen-app-email
-$ cd ./lumen-app-email
-$ composer i
-```
+# Return the envelope data of the first 50 MessageItems w/o previewText of the INBOX mailbox
+# for the MailAccount identified by "gmail"
+GET /rest-api-email/api/v0/MailAccounts/gmail/MailFolders/INBOX/MessageItems?start=0&limit=50&attributes=*,previewText HTTP/1.1
+Content-Type: application/json
+Authorization: Basic Y29uam9vbjpIZWxsb1dvcmxk
+Host: hostname
+
+# Return the email identified with the uid 4356 of the INBOX mailbox for the MailAccount identified by "gmail"
+GET /rest-api-email/api/v0/MailAccounts/gmail/MailFolders/INBOX/MessageItems/4356 HTTP/1.1
+Content-Type: application/json
+Authorization: Basic Y29uam9vbjpIZWxsb1dvcmxk
+Host: hostname
+````
+
+
+## Use Case
 
-The official [Lumen\-documentation](https://lumen.laravel.com/docs/) has guides 
-on setting up a webservers running a Lumen application.
+**lumen-app-email** follows a service oriented approach. Implementations are easily replacable with the help of upfront DI configurations and related bindings. 
 
-#### Configuration
-Please refer to the official [documentation](./docs) of **lumen-app-email** for further information on
-installation and configuration.
+**Use lumen-app-email, if you...**
+- need a fully functional middleware for communicating with IMAP / SMTP server
+- want to provide webmail solutions with domain-specific sign-in to IMAP accounts
+- are looking for a distribution with minimal footprint and easy setup
+- require a headless, microservice oriented architecture with your infrastructure 
+
+**do not use lumen-app-email, if you...**
+ - are looking for a stateful, session based webmail backend
+ - need baked-in caching
+
+
+## Supported REST API
+* **rest-api-email**
+  <br>For the list of endpoints this microservice provides, please refer to the 
+  [OpenApi-documentation of `rest-api-email`](https://github.com/conjoon/rest-api-description), available as OpenAPI documentation at [conjoon.stoplight.io](https://conjoon.stoplight.io/docs/rest-api-description/)
 
-## Additional Resources
-### Official Docker Container
-[conjoon\/ddev-ms-email](conjoon/ddev-ms-email) provides a `.ddev`/**Docker** configuration for a container
-running **lumen-app-email** out-of-the-box.
+## Installation & Configuration
+Please refer to the official [documentation](./docs) of **lumen-app-email** for further information on installation and configuration.
 
-## Troubleshooting
-### Composer 2.0 - Pear/Horde vows
+## Additional Notes
+#### Composer 2.0 - Pear/Horde vows
 As of **v1.0.1**, **[php-lib-conjoon](conjoon/php-lib-conjoon)** no longer requires _Composer 1.*_ for installation.
 For _Composer 2.*_-compatibility, **php-lib-conjoon** relies on the following private composer
 package repository:

diff --git a/app/bootstrap/bindings.php b/app/bootstrap/bindings.php
@@ -51,7 +51,9 @@
 use Conjoon\Mail\Client\Request\Message\Transformer\MessageBodyDraftJsonTransformer;
 use Conjoon\Mail\Client\Request\Message\Transformer\MessageItemDraftJsonTransformer;
 use Conjoon\Mail\Client\Service\AttachmentService;
+use Conjoon\Mail\Client\Service\AuthService;
 use Conjoon\Mail\Client\Service\DefaultAttachmentService;
+use Conjoon\Mail\Client\Service\DefaultAuthService;
 use Conjoon\Mail\Client\Service\DefaultMailFolderService;
 use Conjoon\Mail\Client\Service\DefaultMessageItemService;
 use Conjoon\Mail\Client\Service\MailFolderService;
@@ -126,6 +128,10 @@
     return new DefaultMessageItemDraftJsonTransformer();
 });
 
+$app->singleton(AuthService::class, function () {
+    return new DefaultAuthService();
+});
+
 $app->singleton(MessageBodyDraftJsonTransformer::class, function () {
     return new DefaultMessageBodyDraftJsonTransformer();
 });

diff --git a/app/config/imapserver.php.example b/app/config/imapserver.php.example
@@ -36,32 +36,155 @@ declare(strict_types=1);
 | of your application can connect to. The "match" entry should be a regular
 | expression that matches an email-address to "this" specific server configuration.
 | This file needs to be renamed to "imapserver.php" once configured.
+|
+| Example configuration:
+|    <?php
+|    return [[
+|        // unique id for this configuration entry
+|        "id"              => "gmail",
+|        "inbox_type"      => "IMAP",
+|        "inbox_address"   => 'imap.gmail.com',
+|        "inbox_port"      => 993,
+|        "inbox_ssl"       => true,
+|        "outbox_address"  => "smtp.gmail.com",
+|        "outbox_port"     => 465,
+|        "outbox_secure"   => "ssl",
+|        // the root mailbox. For most IMAP servers, this will
+|        // be "INBOX". Gmail users can use  "[Gmail]" instead.
+|        // You can also provide a separate mailbox named "conjoon".
+|        // The root folders are the only folders which will be
+|        // queried and displayed in the folder hierarchy for the
+|        // Mail Account, along with its contents, including sub folders.
+|        // leave empty to return all mailboxes
+|        "root"            => ["Gmail"],
+|        // a regular expression that makes sure a user's email-address
+|        // is matched against "this" entry, e.g. a sign-in with the
+|        // username "dev@googlemail.com" would be associated with "this",
+|        // server configuration, but "dev@somemailserver.com" wouldn't
+|        "match"           => ["/\@(googlemail.)(com)$/mi"]
+|    ]}
+|    ?>
 */
 
 return [
 
+    // +-------------------------------------+
+    // |           Google Mail               |
+    // +-------------------------------------+
+    [
+        "id"             => "GMail",
+        "inbox_type"     => "IMAP",
+        "inbox_address"  => 'imap.gmail.com',
+        "inbox_port"     => 993,
+        "inbox_ssl"      => true,
+        "outbox_address" => "smtp.gmail.com",
+        "outbox_port"    => 465,
+        "outbox_secure"  => "ssl",
+        "root"           => ["[Gmail]", "[Google Mail]"],
+        "match"          => ["/\@(googlemail.|gmail.)(com)$/mi"]
+    ],
+
+
+    // +-------------------------------------+
+    // |           Outlook.com               |
+    // +-------------------------------------+
+    [
+        "id"              => "outlook.com",
+        "inbox_type"      => "IMAP",
+        "inbox_address"   => 'outlook.office365.com',
+        "inbox_port"      => 993,
+        "inbox_ssl"       => true,
+        "outbox_address"  => "smtp-mail.outlook.com",
+        "outbox_port"     => 587,
+        "outbox_secure"   => "tls",
+        "root"            => [],
+        "match"           => ["/\@(outlook.)(com)$/mi"]
+    ],
+
+
+    // +-------------------------------------+
+    // |           Yahoo Mail                |
+    // +-------------------------------------+
     [
-        // a unique id for this configuration entry
-        "id"              => "Google_Mail",
+        "id"              => "Yahoo",
         "inbox_type"      => "IMAP",
-        "inbox_address"   => 'imap.gmail.com',
+        "inbox_address"   => 'imap.mail.yahoo.com',
         "inbox_port"      => 993,
         "inbox_ssl"       => true,
-        "outbox_address"  => "smtp.gmail.com",
+        "outbox_address"  => "smtp.mail.yahoo.com",
+        "outbox_port"     => 587,
+        "outbox_secure"   => "ssl",
+        "root"            => ["INBOX"],
+        "match"           => ["/\@(freenet.)(de)$/mi"]
+    ],
+
+
+    // +-------------------------------------+
+    // |           AOL                       |
+    // +-------------------------------------+
+    [
+        "id"              => "AOL",
+        "inbox_type"      => "IMAP",
+        "inbox_address"   => 'imap.aol.com',
+        "inbox_port"      => 993,
+        "inbox_ssl"       => true,
+        "outbox_address"  => "smtp.aol.com",
         "outbox_port"     => 465,
-        "outbox_ssl"      => true,
-        // the root mailbox. For most IMAP servers, this will
-        // be "INBOX". Gmail users can use  "[Gmail]" instead.
-        // You can also provide a separate mailbox named "conjoon".
-        // The root folders are the only folders which will be
-        // queried and displayed in the folder hierarchy for the
-        // Mail Account, along with its contents, including sub folders.
+        "outbox_secure"   => "ssl",
+        "root"            => [],
+        "match"           => ["/\@(aol.)(com)$/mi"]
+    ],
+
+
+    // +-------------------------------------+
+    // |           Freenet                   |
+    // +-------------------------------------+
+    [
+        "id"              => "Freenet",
+        "inbox_type"      => "IMAP",
+        "inbox_address"   => 'mx.freenet.de',
+        "inbox_port"      => 993,
+        "inbox_ssl"       => true,
+        "outbox_address"  => "mx.freenet.de",
+        "outbox_port"     => 587,
+        "outbox_secure"   => "tls",
         "root"            => ["INBOX"],
-        // a regular expression that makes sure a user's email-address
-        // is matched against "this" entry, e.g. a sign-in with the
-        // username "dev@googlemail.com" would be associated with "this",
-        // server configuration, but "dev@somemailserver.com" wouldn't
-        "match"           => ["/\@(googlemail.)(com)$/mi"]
+        "match"           => ["/\@(freenet.)(de)$/mi"]
+    ],
+
+
+    // +-------------------------------------+
+    // |           GMX                       |
+    // +-------------------------------------+
+    [
+        "id"              => "gmx",
+        "inbox_type"      => "IMAP",
+        "inbox_address"   => 'imap.gmx.net',
+        "inbox_port"      => 993,
+        "inbox_ssl"       => true,
+        "outbox_address"  => "mail.gmx.net",
+        "outbox_port"     => 587,
+        "outbox_secure"   => "tls",
+        "root"            => [],
+        "match"           => ["/\@(gmx.)(de|net)$/mi"]
+    ],
+
+
+    // +-------------------------------------+
+    // |           WEB.DE                    |
+    // +-------------------------------------+
+    [
+        "id"              => "web.de",
+        "inbox_type"      => "IMAP",
+        "inbox_address"   => 'imap.web.de',
+        "inbox_port"      => 993,
+        "inbox_ssl"       => true,
+        "outbox_address"  => "smtp.web.de",
+        "outbox_port"     => 587,
+        "outbox_secure"   => "tls",
+        "root"            => [],
+        "match"           => ["/\@(web.)(de)$/mi"]
     ]
 
+
 ];
diff --git a/composer.json b/composer.json
@@ -42,5 +42,11 @@
         "post-root-package-install": [
             "@php -r \"file_exists('.env') || copy('.env.example', '.env');\""
         ]
-    }
+    },
+    "authors": [
+        {
+            "name": "Thorsten Suckow-Homberg",
+            "email": "thorsten@suckow-homberg.de"
+        }
+    ]
 }
diff --git a/docs/README.md b/docs/README.md
@@ -1,10 +1,28 @@
-### conjoon/lumen-app-email Documentation
+# conjoon/lumen-app-email Documentation
 
-#### .env
+# Installation
+
+## Via GIT & composer
+```shell
+$ git clone https://github.com/conjoon/lumen-app-email
+$ cd ./lumen-app-email
+$ composer i
+```
+
+## Via Docker (DDEV)
+For a quick start, we suggest to use a pre-configured container for running the backend: [conjoon\/ddev-ms-email](https://github.com/conjoon/ddev-ms-email) provides a `.**Docker (DDEV)** configuration for a container running **lumen-app-email** out-of-the-box and is easy to install.
+
+## From Scratch
+Since **lumen-app-webmail** is a Lumen/Laravel application, detailed information on how to set up a webserver for it can be found in the official [Lumen\-documentation](https://lumen.laravel.com/docs/).
+
+
+#### .env - Environment Variables
 The root directory of the project contains a [dotenv-configuration](https://github.com/vlucas/phpdotenv) file (`.env.example`).
-Settings may be adjusted on your own to match your desired configuration for the environment the
-microservice runs in. Copy and rename this file to `.env` and configure away!
+Settings may be adjusted on your own to match your desired configuration for the environment the microservice runs in. Copy and rename this file to `.env` and configure away!
+
 
-#### Additional documentation
- 1. [Setting up CORS](./cors.md)
- 2. [Configuring allowed IMAP servers](./serverconfig.md)
+## Further Documentation
+ 1. Configuration
+    1. [Setting up CORS](./cors.md)
+    2. [Configuring allowed IMAP servers](./serverconfig.md)
+ 2. [Troubleshooting & Known Issues](./troubleshooting.md)
diff --git a/docs/cors.md b/docs/cors.md
@@ -1,12 +1,14 @@
-# Configuring CORS
+ # Configuring CORS
 **lumen-app-email** uses [fruitcake/laravel-cors](https://github.com/fruitcake/laravel-cors) for enabling
 [Cross-Origin Resource Sharing](http://enable-cors.org/).
 <br>
-A configuration template can be found in ```config/cors.php.example```. You need to create a file named
-```config/cors.php``` - basically the configuration of ```config/cors.php.example``` should work, but if
-you need to set specific options, this would be the place to do so.
+A configuration template can be found in `app/config/cors.php.example`.
+<br> 
+Copy this file to `app/config/cors.php`, and adjust the settings to your needs. The example configuration works well with development environments, but you might want to add more strict options for production, auch as the settings for `allowed_origins` and `paths`.
+
 
 #### Options
+The options available for the cors configuration are as follows:
 
 | Option                   | Description                                                              | Default value |
 |--------------------------|--------------------------------------------------------------------------|---------------|