thecore_backend_commons 3.2.9 → 3.2.10

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '0648fa1c9a7f76785c830a38e20600d2522815f1dd07711ca43d1b2782a3ab38'
-  data.tar.gz: fba8e620b951232f4eae27fe404de33f6d33e9d1f187fd5ad720add8079d1a01
+  metadata.gz: 8c3ab89916ec1ac0d08617605d32e5ad30b2bc8232df838a29a9b75966f0d653
+  data.tar.gz: 89ea95480895118d1641d964fae91339e3714cb126e3d0ae3343b83e9c18c289
 SHA512:
-  metadata.gz: '088d6301217b6754760bcdb1c52b34cc53f8bff2b83d6cb01c8aea1f360a9cf0adbcdcfab38f21a243f7d6375f27e99befaef7d95be128c0f3022963c0cb2989'
-  data.tar.gz: 12ecc52dddecc25ba063ce0ab52c6d4f0c92742dd7b6d094b32c8fef0b5c503018113c328bd6a4407a24b9c2d3058e4e1524d1748e6033755a1261dd9948d177
+  metadata.gz: 5e11ad2f433fd264b679cd7f77ad77363f75d0c5f4245027ab4b39e85190f45bb78af8624a5621334833a73615846084c5478375f0d7dae4622319c6225ddf9e
+  data.tar.gz: 7fa46bd7592d9d85db5778db94d2130d7c70771aea9118f089dd05822646e9602515b1d1ede8080280be79cf168939fc594a1daf60cec04ff370c501c38829f0

data/README.md

@@ -1 +1,66 @@
 This is part of Thecore framework: https://github.com/gabrieletassoni/thecore/tree/release/3
+
+## Invio email e configurazione SMTP
+
+### Configurazione
+
+Le impostazioni SMTP sono salvate in `ThecoreSettings` (namespace `:smtp`) e vengono caricate automaticamente dai seeds del gem:
+
+| Chiave              | Descrizione                                                                 |
+| ------------------- | --------------------------------------------------------------------------- |
+| `address`           | Indirizzo del server SMTP (obbligatorio per abilitare la consegna)          |
+| `port`              | Porta (default `587`); impostare `465` per SMTPS (SSL implicito)           |
+| `domain`            | Dominio HELO                                                                |
+| `user_name`         | Username per l'autenticazione                                               |
+| `password`          | Password per l'autenticazione                                               |
+| `authentication`    | `plain`, `login`, `cram_md5`, oppure `none`/vuoto per disabilitare l'auth  |
+| `enable_starttls_auto` | Impostare a `false`, `f`, `0` o `no` per disabilitare STARTTLS. Ignorato se `port` è `465` (SMTPS usa TLS implicito). |
+| `from`              | Indirizzo mittente                                                          |
+
+**Nota porta 465 (SMTPS):** la connessione viene wrappata in SSL dal primo byte. Impostare `enable_starttls_auto` a `false` non è sufficiente: occorre usare la porta `465` affinché `SmtpConfig` abiliti automaticamente `tls: true`. Le due modalità (SMTPS e STARTTLS) sono mutuamente esclusive — mescolarle causa un `Net::ReadTimeout`.
+
+### Usare SmtpDeliverable nei mailer
+
+Includere il concern `SmtpDeliverable` in qualsiasi `ActionMailer::Base` per leggere le impostazioni SMTP da `ThecoreSettings` al momento dell'invio (nessun riavvio necessario quando le impostazioni cambiano):
+
+```ruby
+class MyMailer < ApplicationMailer
+  include SmtpDeliverable
+
+  def my_email
+    mail(
+      from: smtp_setting(:from),
+      to: "recipient@example.com",
+      subject: "Hello"
+    )
+  end
+end
+```
+
+Il concern registra automaticamente un `after_action :configure_smtp_delivery` che sovrascrive il delivery method con le impostazioni lette da `ThecoreSettings`. Se `smtp.address` è vuoto, il mailer usa il delivery method configurato nell'ambiente Rails (es. `:test` o `:letter_opener` in sviluppo).
+
+Il metodo helper `smtp_setting(key)` è disponibile in tutta la classe mailer.
+
+### Usare SmtpConfig direttamente
+
+`ThecoreBackendCommons::SmtpConfig` è un modulo Ruby puro utilizzabile anche al di fuori dei mailer (es. script, job, rake task):
+
+```ruby
+opts = ThecoreBackendCommons::SmtpConfig.delivery_options
+# => { address: "smtp.example.com", port: 465, tls: true, ... }
+
+ThecoreBackendCommons::SmtpConfig.setting(:from)
+# => "noreply@example.com"
+```
+
+### Testare la configurazione SMTP
+
+Dall'applicazione Rails che include questo gem, eseguire:
+
+```bash
+bundle exec rails runner script/test_smtp.rb destinatario@example.com
+```
+
+Se non si passa un indirizzo, l'email viene inviata all'indirizzo configurato in `ThecoreSettings mytask.default_email`.
+
+Lo script stampa i parametri SMTP effettivamente usati (inclusi `tls` e `enable_starttls_auto`) prima di tentare la consegna, e restituisce exit code `1` in caso di errore con il messaggio dell'eccezione.

data/app/mailers/concerns/smtp_deliverable.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+# Include in any ActionMailer subclass to wire up SMTP delivery from
+# ThecoreSettings at send time (no application restart needed).
+#
+#   class MyMailer < ApplicationMailer
+#     include SmtpDeliverable
+#     ...
+#   end
+#
+# The concern registers an after_action that overwrites the delivery method
+# with settings read from ThecoreSettings (ns: :smtp). If smtp.address is
+# blank the mailer falls back to whatever delivery_method is configured in
+# the Rails environment (e.g. :test or :letter_opener in development).
+module SmtpDeliverable
+  extend ActiveSupport::Concern
+
+  included do
+    after_action :configure_smtp_delivery
+  end
+
+  private
+
+  def configure_smtp_delivery
+    opts = ThecoreBackendCommons::SmtpConfig.delivery_options
+    message.delivery_method(:smtp, opts) if opts[:address].present?
+  end
+
+  def smtp_setting(key)
+    ThecoreBackendCommons::SmtpConfig.setting(key)
+  end
+end

data/lib/thecore_backend_commons/smtp_config.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module ThecoreBackendCommons
+  # Reads SMTP settings from ThecoreSettings (ns: :smtp) and builds the
+  # delivery_options hash for ActionMailer / Net::SMTP.
+  #
+  # Port 465  → SMTPS (implicit TLS from the first byte): tls: true.
+  # Port 587  → STARTTLS (plain connection upgraded after banner): enable_starttls_auto.
+  # The two modes are mutually exclusive; mixing them causes a ReadTimeout.
+  module SmtpConfig
+    FALSY_STRINGS = %w[false f 0 no].freeze
+
+    module_function
+
+    def setting(key)
+      ThecoreSettings::Setting.find_by(ns: :smtp, key: key)&.raw
+    end
+
+    def delivery_options
+      auth = setting(:authentication)
+      auth = nil if auth.blank? || auth == 'none'
+      port = setting(:port)&.to_i || 587
+      smtps = port == 465
+      opts = {
+        address: setting(:address),
+        port: port,
+        domain: setting(:domain),
+        user_name: setting(:user_name),
+        password: setting(:password),
+        authentication: auth&.to_sym,
+        tls: smtps,
+        enable_starttls_auto: !smtps && FALSY_STRINGS.exclude?(setting(:enable_starttls_auto).to_s.downcase.strip)
+      }
+      opts.transform_values! { |v| v.is_a?(String) ? v.strip.presence : v }
+      unless opts[:authentication]
+        opts.delete(:user_name)
+        opts.delete(:password)
+      end
+      opts.compact
+    end
+  end
+end

data/lib/thecore_backend_commons/version.rb

@@ -1,3 +1,3 @@
 module ThecoreBackendCommons
-  VERSION = "3.2.9".freeze
+  VERSION = "3.2.10".freeze
 end

data/lib/thecore_backend_commons.rb

@@ -13,7 +13,7 @@ require "seed_dump"
 
 require "thecore_backend_commons/version"
 require "thecore_backend_commons/engine"
+require "thecore_backend_commons/smtp_config"
 
 module ThecoreBackendCommons
-  # Your code goes here...
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: thecore_backend_commons
 version: !ruby/object:Gem::Version
-  version: 3.2.9
+  version: 3.2.10
 platform: ruby
 authors:
 - Gabriele Tassoni
@@ -188,6 +188,7 @@ files:
 - README.md
 - Rakefile
 - app/channels/activity_log_channel.rb
+- app/mailers/concerns/smtp_deliverable.rb
 - config/initializers/abilities.rb
 - config/initializers/add_to_db_migrations.rb
 - config/initializers/after_initialize.rb
@@ -206,6 +207,7 @@ files:
 - lib/tasks/thecore_backend_commons_tasks.rake
 - lib/thecore_backend_commons.rb
 - lib/thecore_backend_commons/engine.rb
+- lib/thecore_backend_commons/smtp_config.rb
 - lib/thecore_backend_commons/version.rb
 homepage: https://github.com/gabrieletassoni/thecore_backend_commons
 licenses: []