Add LMTP as an option for the protocol implementation

README.markdown

@@ -195,6 +195,12 @@ Session options are:
 * `{tls_options, [ssl:server_option()]}` - options to pass to `ssl:handshake/3` (OTP-21+) / `ssl:ssl_accept/3`
   when `STARTTLS` command is sent by the client. Only needed if `STARTTLS` extension
   is enabled
+* `{protocol, smtp | lmtp}` - when `lmtp` is passed, the control flow of the
+  [Local Mail Tranfer Protocol](https://tools.ietf.org/html/rfc2033) is applied.
+  LMTP is derived from SMTP with just a few variations and is used by standard
+  [Mail Transfer Agents (MTA)](https://en.wikipedia.org/wiki/Message_transfer_agent), like Postfix, Exim and OpenSMTPD to
+  send incoming email to local mail-handling applications that usually don't have a delivery queue.
+  The default value of this option is `smtp`.
 * `{callbackoptions, any()}` - value will be passed as 4th argument to callback module's `init/4`
 
 You can connect and test this using the `gen_smtp_client` via something like:
@@ -207,6 +213,12 @@ gen_smtp_client:send(
 
 If you want to listen on IPv6, you can use the `{family, inet6}` and `{address, "::"}` options to enable listening on IPv6.
 
+Please notice that when using the LMTP protocol, the `handle_EHLO` callback will be used
+to handle the `LHLO` command as defined in [RFC2033](https://tools.ietf.org/html/rfc2033),
+due to their similarities. Although not used, the implementation of `handle_HELO` is still
+mandatory for the general `gen_smtp_server_session` behaviour (you can simply
+return a 500 error, e.g. `{error, "500 LMTP server, not SMTP"}`).
+
 ## Dependency on iconv
 
 gen_smtp relies on iconv for text encoding and decoding when parsing is activated.

src/gen_smtp_server.erl

@@ -26,6 +26,8 @@
 
 -define(PORT, 2525).
 
+-include_lib("hut/include/hut.hrl").
+
 %% External API
 -export([
 	start/3, start/2, start/1,
@@ -47,16 +49,24 @@
 			CallbackModule :: module(),
 			Options :: options()) -> {'ok', pid()} | {'error', any()}.
 start(ServerName, CallbackModule, Options) when is_list(Options) ->
-	{ok, Transport, TransportOpts, ProtocolOpts}
-		= convert_options(CallbackModule, Options),
-	ranch:start_listener(
-	  ServerName, Transport, TransportOpts, gen_smtp_server_session, ProtocolOpts).
+	case convert_options(CallbackModule, Options) of
+		{ok, Transport, TransportOpts, ProtocolOpts} ->
+			ranch:start_listener(
+			  ServerName, Transport, TransportOpts, gen_smtp_server_session, ProtocolOpts);
+		{error, Reason} -> {error, Reason}
+	end.
 
 child_spec(ServerName, CallbackModule, Options) ->
-	{ok, Transport, TransportOpts, ProtocolOpts}
-		= convert_options(CallbackModule, Options),
-	ranch:child_spec(
-	  ServerName, Transport, TransportOpts, gen_smtp_server_session, ProtocolOpts).
+	case convert_options(CallbackModule, Options) of
+		{ok, Transport, TransportOpts, ProtocolOpts} ->
+			ranch:child_spec(
+			  ServerName, Transport, TransportOpts, gen_smtp_server_session, ProtocolOpts);
+		{error, Reason} ->
+			% `supervisor:child_spec' is not compatible with ok/error tuples.
+			% This error is likely to occur when starting the application,
+			% so the user can sort out the configuration parameters and try again.
+			erlang:error(Reason)
+	end.
 
 convert_options(CallbackModule, Options) ->
 	Transport = case proplists:get_value(protocol, Options, tcp) of
@@ -68,18 +78,26 @@ convert_options(CallbackModule, Options) ->
 	Port = proplists:get_value(port, Options, ?PORT),
 	Hostname = proplists:get_value(domain, Options, smtp_util:guess_FQDN()),
 	ProtocolOpts = proplists:get_value(sessionoptions, Options, []),
-	ProtocolOpts1 = {CallbackModule, [{hostname, Hostname} | ProtocolOpts]},
-	RanchOpts = proplists:get_value(ranch_opts, Options, #{}),
-	SocketOpts = maps:get(socket_opts, RanchOpts, []),
-	TransportOpts = RanchOpts#{
-							   socket_opts =>
-								   [{port, Port},
-									{ip, Address},
-									{keepalive, true},
-									%% binary, {active, false}, {reuseaddr, true} - ranch defaults
-									Family
-								   | SocketOpts]},
-	{ok, Transport, TransportOpts, ProtocolOpts1}.
+	EmailTransferProtocol = proplists:get_value(protocol, ProtocolOpts, smtp),
+	case {EmailTransferProtocol, Port} of
+		{lmtp, 25} ->
+			?log(error, "LMTP is different from SMTP, it MUST NOT be used on the TCP port 25"),
+			% Error defined in section 5 of https://tools.ietf.org/html/rfc2033
+			{error, invalid_lmtp_port};
+		_ ->
+			ProtocolOpts1 = {CallbackModule, [{hostname, Hostname} | ProtocolOpts]},
+			RanchOpts = proplists:get_value(ranch_opts, Options, #{}),
+			SocketOpts = maps:get(socket_opts, RanchOpts, []),
+			TransportOpts = RanchOpts#{
+									   socket_opts =>
+										   [{port, Port},
+											{ip, Address},
+											{keepalive, true},
+											%% binary, {active, false}, {reuseaddr, true} - ranch defaults
+											Family
+										   | SocketOpts]},
+			{ok, Transport, TransportOpts, ProtocolOpts1}
+	end.
 
 
 %% @doc Start the listener with callback module `Module' with options `Options' linked to no process.