thecore_backend_commons 3.2.9 → 3.2.11

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '0648fa1c9a7f76785c830a38e20600d2522815f1dd07711ca43d1b2782a3ab38'
-  data.tar.gz: fba8e620b951232f4eae27fe404de33f6d33e9d1f187fd5ad720add8079d1a01
+  metadata.gz: fe73ef2835e94090bd037724805658c43bb87820a68d2fc86eadd35747ef8e94
+  data.tar.gz: 707da7e03c6f3bad7499c95fa8616e0f43ff75feed46ebe0159ec05a0594f06f
 SHA512:
-  metadata.gz: '088d6301217b6754760bcdb1c52b34cc53f8bff2b83d6cb01c8aea1f360a9cf0adbcdcfab38f21a243f7d6375f27e99befaef7d95be128c0f3022963c0cb2989'
-  data.tar.gz: 12ecc52dddecc25ba063ce0ab52c6d4f0c92742dd7b6d094b32c8fef0b5c503018113c328bd6a4407a24b9c2d3058e4e1524d1748e6033755a1261dd9948d177
+  metadata.gz: 047fff2d4b57e67c7320df0e8d38874603084e91cab99d8e5802807bcf903f75c503360fa5e4845692876906db4118f720457f631c9a51cfbaf65099ed0a8a39
+  data.tar.gz: 10d926f3d871d4adb4ce2cc7a721b930d32a608ceb2505fc37e07f1408c0a96fe7f7e1d23c065a55e35d344d3433e2dc4fc1c7cb2778e5550079eeea56031ce4

data/README.md

@@ -1 +1,74 @@
 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
+
+Il gem espone `ThecoreBackendCommons::SmtpTester` e un rake task, disponibili automaticamente in qualsiasi app che include questo gem.
+
+**Da rake task (shell):**
+
+```bash
+rails thecore_backend_commons:smtp:test[destinatario@example.com]
+```
+
+**Da Rails console:**
+
+```ruby
+ThecoreBackendCommons::SmtpTester.call("destinatario@example.com")
+```
+
+Se non si passa un indirizzo, in entrambi i casi viene usato `ThecoreSettings mytask.default_email`.
+
+Lo tester stampa i parametri SMTP effettivamente usati (inclusi `tls` e `enable_starttls_auto`) prima di tentare la consegna. Restituisce `true`/`false` dal console e exit code `1` dal rake task in caso di errore.

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/tasks/thecore_backend_commons_tasks.rake

@@ -1,4 +1,11 @@
-# desc "Explaining what the task does"
-# task :thecore_backend_commons do
-#   # Task goes here
-# end
+namespace :thecore_backend_commons do
+  namespace :smtp do
+    desc "Send a test email using ThecoreSettings SMTP config. " \
+         "Usage: rails thecore_backend_commons:smtp:test[recipient@example.com] " \
+         "(omit argument to use mytask.default_email)"
+    task :test, [:recipient] => :environment do |_t, args|
+      success = ThecoreBackendCommons::SmtpTester.call(args[:recipient])
+      exit 1 unless success
+    end
+  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/smtp_tester.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module ThecoreBackendCommons
+  # Sends a test email using the SMTP settings from ThecoreSettings.
+  # Usable from the Rails console or via the rake task.
+  #
+  # From rails console:
+  #   ThecoreBackendCommons::SmtpTester.call("you@example.com")
+  #
+  # From the shell:
+  #   rails thecore_backend_commons:smtp:test[you@example.com]
+  class SmtpTester
+    def self.call(recipient = nil)
+      new(recipient).call
+    end
+
+    def initialize(recipient = nil)
+      @recipient = recipient.presence ||
+                   ThecoreSettings::Setting.find_by(ns: :mytask, key: :default_email)&.raw
+    end
+
+    def call
+      validate!
+      print_settings
+      send_mail
+    end
+
+    private
+
+    def validate!
+      raise ArgumentError, "No recipient given and mytask.default_email is not configured." if @recipient.blank?
+      raise ArgumentError, "smtp.address is not configured in ThecoreSettings." if opts[:address].blank?
+    end
+
+    def print_settings
+      puts "SMTP settings:"
+      puts "  address:             #{opts[:address]}"
+      puts "  port:                #{opts[:port]}"
+      puts "  domain:              #{opts[:domain].inspect}"
+      puts "  user_name:           #{opts[:user_name].inspect}"
+      puts "  authentication:      #{opts[:authentication].inspect}"
+      puts "  tls:                 #{opts[:tls]}"
+      puts "  enable_starttls_auto:#{opts[:enable_starttls_auto]}"
+      puts "  from:                #{SmtpConfig.setting(:from).inspect}"
+      puts ""
+      puts "Sending test email to: #{@recipient}"
+    end
+
+    def send_mail
+      from_address = SmtpConfig.setting(:from).presence || "noreply@mytask.local"
+      delivery_opts = opts
+
+      mail = Mail.new do
+        from    from_address
+        to      delivery_opts[:address] # placeholder; overridden below
+        subject "[MyTask] SMTP test — #{Time.current.strftime('%Y-%m-%d %H:%M:%S %Z')}"
+        body    "This is an automated SMTP connectivity test sent from MyTask.\n\n" \
+                "If you received this message, the SMTP configuration is working correctly.\n\n" \
+                "Settings used:\n" \
+                "  address: #{delivery_opts[:address]}\n" \
+                "  port: #{delivery_opts[:port]}\n" \
+                "  tls: #{delivery_opts[:tls]}\n" \
+                "  auth: #{delivery_opts[:authentication].inspect}"
+      end
+      mail.to = @recipient
+      mail.delivery_method(:smtp, delivery_opts)
+      mail.deliver!
+      puts "OK: email delivered successfully."
+      true
+    rescue StandardError => e
+      puts "ERROR: #{e.class}: #{e.message}"
+      false
+    end
+
+    def opts
+      @opts ||= SmtpConfig.delivery_options
+    end
+  end
+end

data/lib/thecore_backend_commons/version.rb

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

data/lib/thecore_backend_commons.rb

@@ -13,7 +13,8 @@ require "seed_dump"
 
 require "thecore_backend_commons/version"
 require "thecore_backend_commons/engine"
+require "thecore_backend_commons/smtp_config"
+require "thecore_backend_commons/smtp_tester"
 
 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.11
 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,8 @@ 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/smtp_tester.rb
 - lib/thecore_backend_commons/version.rb
 homepage: https://github.com/gabrieletassoni/thecore_backend_commons
 licenses: []