smtp_server: add smtp_server_get_dynamic_parameters event

This helps to deploy IP-based virtual service.

Author: wez

crates/kumod/src/smtp_server.rs

@@ -276,6 +276,7 @@ impl ConcreteEsmtpListenerParams {
     ) {
         if let Some(hostname) = base.hostname {
             self.hostname = hostname;
+            meta.set_meta("hostname", self.hostname.to_string());
         }
         if let Some(relay_hosts) = base.relay_hosts {
             self.relay_hosts = relay_hosts;
@@ -386,7 +387,7 @@ impl Default for ConcreteEsmtpListenerParams {
     }
 }
 
-#[derive(Deserialize, Clone, Debug, PartialEq)]
+#[derive(Deserialize, Serialize, Clone, Debug, Default, PartialEq)]
 #[serde(deny_unknown_fields)]
 pub struct GenericEsmtpListenerParams {
     #[serde(default)]
@@ -443,6 +444,12 @@ pub struct GenericEsmtpListenerParams {
     line_length_hard_limit: Option<usize>,
 }
 
+impl mlua::FromLua for GenericEsmtpListenerParams {
+    fn from_lua(value: mlua::Value, lua: &mlua::Lua) -> Result<Self, mlua::Error> {
+        config::from_lua_value(lua, value)
+    }
+}
+
 #[derive(Deserialize, Clone, Debug)]
 #[serde(deny_unknown_fields)]
 pub struct EsmtpListenerParams {
@@ -674,10 +681,10 @@ impl SmtpServerSession {
         meta.set_meta("received_from", peer_address.to_string());
 
         let mut concrete_params = ConcreteEsmtpListenerParams::default();
-        concrete_params.apply_generic(params.base, &my_address, &peer_address, &mut meta);
-
         meta.set_meta("hostname", concrete_params.hostname.to_string());
 
+        concrete_params.apply_generic(params.base, &my_address, &peer_address, &mut meta);
+
         let service = format!("esmtp_listener:{my_address}");
 
         let mut server = SmtpServerSession {
@@ -1258,6 +1265,27 @@ impl SmtpServerSession {
             return Ok(());
         }
 
+        match self
+            .call_callback::<GenericEsmtpListenerParams, _, _>(
+                "smtp_server_get_dynamic_parameters",
+                (self.my_address.to_string(), self.meta.clone()),
+            )
+            .await?
+        {
+            Ok(generic) => {
+                self.params.apply_generic(
+                    generic,
+                    &self.my_address,
+                    &self.peer_address,
+                    &mut self.meta,
+                );
+            }
+            Err(rej) => {
+                self.write_response(rej.code, rej.message, None).await?;
+                return Ok(());
+            }
+        }
+
         if let Err(rej) = self
             .call_callback::<(), _, _>("smtp_server_connection_accepted", self.meta.clone())
             .await?

crates/mailparsing/src/conformance.rs

@@ -1,6 +1,6 @@
-use serde::Deserialize;
+use serde::{Deserialize, Serialize};
 
-#[derive(Deserialize, Clone, Copy, Debug, Default, PartialEq, Eq)]
+#[derive(Deserialize, Serialize, Clone, Copy, Debug, Default, PartialEq, Eq)]
 pub enum ConformanceDisposition {
     #[default]
     Deny,

docs/changelog/main.md

@@ -18,6 +18,10 @@
 * SMTP Server: new
   [smtp_server_connection_accepted](../reference/events/smtp_server_connection_accepted.md)
   event allows custom processing prior to returning the banner to the client.
+* SMTP Server: new
+  [smtp_server_get_dynamic_parameters](../reference/events/smtp_server_get_dynamic_parameters.md)
+  event allows dynamically amending listener configuration to support IP-based
+  virtual service.
 
 ## Fixes
 

docs/reference/events/smtp_server_get_dynamic_parameters.md

@@ -0,0 +1,98 @@
+# `kumo.on('smtp_server_get_dynamic_parameters', function(listener, conn_meta))`
+
+{{since('dev')}}
+
+!!! note
+    This option is primarily intended to be used together with
+    a wildcard `listen` value of `0.0.0.0` for an IPv4 listener
+    or `::` for an IPv6 listener where you desire to dynamically
+    configure IP based virtual MTA service.
+
+Called by the ESMTP server when a new server session has accepted
+a connection from a client, and offers a chance to update the
+configuration for the listener dynamically.  This event triggers
+before [smtp_server_connection_accepted](smtp_server_connection_accepted.md).
+
+The parameters are:
+
+* `listener` - the stringified version of the listener address, such as `0.0.0.0:25`
+* `conn_meta` - the [Connection Metadata](../connectionmeta.md) object
+
+The return value must be a table holding ESMTP listener parameter *overrides*
+that you wish to apply to the existing listener parameters for this connection.
+The fields that you specify in the return value will override the fields that
+were already configured.  Almost every field described under
+[kumo.start_esmtp_listener](../kumo/start_esmtp_listener/index.md) can be used;
+those that cannot will indicate it in their individual documentation pages.
+
+The following example is equivalent to the
+[via](../kumo/start_esmtp_listener/via.md) example, except that rather than the
+`via` parameters being statically configured during the `init` event, they are
+computed for every new connection:
+
+```lua
+kumo.on('init', function()
+  kumo.start_esmtp_listener {
+    listen = '0.0.0.0:25',
+  }
+end)
+
+kumo.on('smtp_server_get_dynamic_parameters', function(listener, conn_meta)
+  return {
+    via = {
+      -- When clients connect to this server via its 10.0.0.1 IP
+      -- address, we will use the hostname and TLS parameters
+      -- defined in this block
+      ['10.0.0.1'] = {
+        hostname = 'mx.example-customer.com',
+        tls_certificate = '/path/to/customer1.cert',
+        tls_private_key = '/path/to/customer1.key',
+      },
+      -- When clients connect to this server via its 10.0.0.2 IP
+      -- address, we will use the hostname and TLS parameters
+      -- defined in this block
+      ['10.0.0.2'] = {
+        hostname = 'mx.other-customer.com',
+        tls_certificate = '/path/to/customer2.cert',
+        tls_private_key = '/path/to/customer2.key',
+      },
+    },
+  }
+end)
+```
+
+This late binding of the configuration can be used to aid in dynamically
+updating the set of listeners on a wildcard port.
+
+For example, you could put the listener overrides into a TOML or JSON
+file that has the same shape as the listener parameters:
+
+```toml
+[via.'10.0.0.1']
+hostname = 'mx.example-customer.com'
+tls_certificate = '/path/to/customer1.cert'
+tls_private_key = '/path/to/customer1.key'
+
+[via.'10.0.0.2']
+hostname = 'mx.other-customer.com'
+tls_certificate = '/path/to/customer2.cert'
+tls_private_key = '/path/to/customer2.key'
+```
+
+Then change the policy code to load it:
+
+```lua
+kumo.on('init', function()
+  kumo.start_esmtp_listener {
+    listen = '0.0.0.0:25',
+  }
+end)
+
+kumo.on('smtp_server_get_dynamic_parameters', function(listener, conn_meta)
+  return kumo.serde.toml_load '/opt/kumometa/etc/policy/listener_params.toml'
+end)
+```
+
+Depending upon the size of the data you are loading, and especially if you
+choose to load data from an external service, you should consider using
+[kumo.memoize](../kumo/memoize.md) to cache the data.

docs/reference/kumo/start_esmtp_listener/_index.md

@@ -20,5 +20,13 @@ kumo.on('init', function()
 end)
 ```
 
+!!! note
+    You can also use the
+    [smtp_server_get_dynamic_parameters](../../events/smtp_server_get_dynamic_parameters.md)
+    event to dynamically adjust listener parameters. You cannot bind
+    new ports or IPs that way, but if you are using the "any" address
+    such as `0.0.0.0` or `::`, you can dynamically refine the parameters
+    for IP-based virtual service.
+
 `PARAMS` is a lua table that can accept the keys listed below:
 

docs/reference/kumo/start_esmtp_listener/listen.md

@@ -11,4 +11,9 @@ kumo.start_esmtp_listener {
 }
 ```
 
-
+!!! note
+    This option cannot be used in dynamic listener contexts such as within
+    [via](via.md), [peer](peer.md) or within the parameters returned from
+    [smtp_server_get_dynamic_parameters](../../events/smtp_server_get_dynamic_parameters.md).
+    It can only be used directly at the top level within the
+    `kumo.start_esmtp_listener` call.

docs/reference/kumo/start_esmtp_listener/max_connections.md

@@ -18,4 +18,10 @@ In earlier releases, there was no kumod-controlled upper bound on the
 number of connections, and as many as the kernel allowed would be
 permitted.
 
+!!! note
+    This option cannot be used in dynamic listener contexts such as within
+    [via](via.md), [peer](peer.md) or within the parameters returned from
+    [smtp_server_get_dynamic_parameters](../../events/smtp_server_get_dynamic_parameters.md).
+    It can only be used directly at the top level within the
+    `kumo.start_esmtp_listener` call.
 

docs/reference/kumo/start_esmtp_listener/peer.md

@@ -31,3 +31,6 @@ kumo.start_esmtp_listener {
 }
 ```
 
+See also:
+
+ * [smtp_server_get_dynamic_parameters](../../events/smtp_server_get_dynamic_parameters.md)

docs/reference/kumo/start_esmtp_listener/via.md

@@ -39,3 +39,6 @@ kumo.start_esmtp_listener {
 }
 ```
 
+See also:
+
+ * [smtp_server_get_dynamic_parameters](../../events/smtp_server_get_dynamic_parameters.md)