Class: Cybertrain::Mailer
- Inherits:
-
Object
- Object
- Cybertrain::Mailer
- Defined in:
- cybertrain/mailer.rb,
cybertrain/mailer.rb,
cybertrain/mailer/later.rb,
cybertrain/mailer/message.rb
Overview
Sends e-mail through an SMTP server: plain text, or with html: a
multipart/alternative message, now (Mailer.deliver) or from a job
(Mailer.deliver_later).
Defined Under Namespace
Modules: Message Classes: ConnectError, Error, InsecureError, ProtocolError, RejectedError, TLSError, TimeoutError
Instance Attribute Summary collapse
-
#mail_deadline ⇒ Float
readonly
Seconds a whole delivery may take.
-
#mail_delivery_method ⇒ Symbol
readonly
:smtp (connect and send) or :test (store in Mailer.deliveries).
-
#mail_from ⇒ String
readonly
The default sender address.
-
#mail_host ⇒ String
readonly
The SMTP server.
-
#mail_port ⇒ Integer
readonly
Its port.
-
#mail_timeout ⇒ Float
readonly
Seconds any one wait may take.
-
#mail_tls ⇒ String
readonly
“starttls”, “tls” or “none”.
-
#mail_user ⇒ String
readonly
The AUTH user, “” for none.
Class Method Summary collapse
-
.default_port(tls) ⇒ Integer
The port a mode uses when none is configured: 587 (submission) for starttls, 465 (submissions) for tls, 25 for none.
-
.deliver(to:, subject:, body:, html: "", from: "") ⇒ String
Sends one message with the settings in Config (
Mailer.new’s defaults). -
.deliver_later(to:, subject:, body:, html: "", from: "") ⇒ Integer
Sends one message later, from a job: enqueues the built-in kind “cybertrain mail” with the five fields as a JSON object (
to,subject,body,html,from), and a job thread (./<app> serveror./<app> worker) delivers it with Mailer.deliver and the settings in Config at that time. -
.deliveries ⇒ Array<MailMessage>
Every message delivered with the delivery method :test, oldest first (Rails’
ActionMailer::Base.deliveries): what a test reads.
Instance Method Summary collapse
-
#deliver(to:, subject:, body:, html: "", from: "") ⇒ String
Sends one message.
-
#initialize(host: Cybertrain.config.smtp_host, port: Cybertrain.config.smtp_port, user: Cybertrain.config.smtp_user, password: Cybertrain.config.smtp_password, from: Cybertrain.config.smtp_from, tls: Cybertrain.config.smtp_tls, timeout: 10, deadline: 60, helo: "localhost", delivery_method: Cybertrain.config.mail_delivery_method) ⇒ Mailer
constructor
Each setting defaults to Config’s (
smtp_host,smtp_port, …, from the CYBERTRAIN_SMTP_* environment variables).
Constructor Details
#initialize(host: Cybertrain.config.smtp_host, port: Cybertrain.config.smtp_port, user: Cybertrain.config.smtp_user, password: Cybertrain.config.smtp_password, from: Cybertrain.config.smtp_from, tls: Cybertrain.config.smtp_tls, timeout: 10, deadline: 60, helo: "localhost", delivery_method: Cybertrain.config.mail_delivery_method) ⇒ Mailer
Each setting defaults to Config’s (smtp_host, smtp_port, …,
from the CYBERTRAIN_SMTP_* environment variables).
284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 |
# File 'cybertrain/mailer.rb', line 284 def initialize(host: Cybertrain.config.smtp_host, port: Cybertrain.config.smtp_port, user: Cybertrain.config.smtp_user, password: Cybertrain.config.smtp_password, from: Cybertrain.config.smtp_from, tls: Cybertrain.config.smtp_tls, timeout: 10, deadline: 60, helo: "localhost", delivery_method: Cybertrain.config.mail_delivery_method) @mail_delivery_method = delivery_method unless delivery_method == :smtp || delivery_method == :test refusal = "delivery_method must be :smtp or :test (got #{delivery_method.inspect})" raise ArgumentError, refusal end @mail_host = host.to_s.downcase @mail_tls = tls.to_s.downcase @mail_user = user.to_s @password = password.to_s @mail_from = from.to_s @mail_timeout = timeout.to_f @mail_deadline = deadline.to_f @helo_name = helo.to_s # :test connects nowhere, so it needs no host (a given one is still # checked). unless @mail_delivery_method == :test && @mail_host.empty? raise ArgumentError, "no SMTP host: set CYBERTRAIN_SMTP_HOST (Config#smtp_host) or pass host:" if @mail_host.empty? raise ArgumentError, "the SMTP host name is malformed" unless Mailer.host_name?(@mail_host) end unless @mail_tls == "starttls" || @mail_tls == "tls" || @mail_tls == "none" raise ArgumentError, "tls must be \"starttls\", \"tls\" or \"none\"" end raise ArgumentError, "the EHLO name is malformed" unless Mailer.host_name?(@helo_name) configured_port = port.to_i raise ArgumentError, "the SMTP port must be from 1 to 65535 (0 for the mode's)" if configured_port < 0 || configured_port > 65_535 @mail_port = configured_port == 0 ? Mailer.default_port(@mail_tls) : configured_port raise ArgumentError, "timeout must be positive" unless @mail_timeout > 0.0 raise ArgumentError, "deadline must be positive" unless @mail_deadline > 0.0 end |
Instance Attribute Details
#mail_deadline ⇒ Float (readonly)
Returns seconds a whole delivery may take.
242 243 244 |
# File 'cybertrain/mailer.rb', line 242 def mail_deadline @mail_deadline end |
#mail_delivery_method ⇒ Symbol (readonly)
Returns :smtp (connect and send) or :test (store in deliveries).
246 247 248 |
# File 'cybertrain/mailer.rb', line 246 def mail_delivery_method @mail_delivery_method end |
#mail_from ⇒ String (readonly)
Returns the default sender address.
233 234 235 |
# File 'cybertrain/mailer.rb', line 233 def mail_from @mail_from end |
#mail_host ⇒ String (readonly)
Returns the SMTP server.
224 225 226 |
# File 'cybertrain/mailer.rb', line 224 def mail_host @mail_host end |
#mail_port ⇒ Integer (readonly)
Returns its port.
227 228 229 |
# File 'cybertrain/mailer.rb', line 227 def mail_port @mail_port end |
#mail_timeout ⇒ Float (readonly)
Returns seconds any one wait may take.
239 240 241 |
# File 'cybertrain/mailer.rb', line 239 def mail_timeout @mail_timeout end |
#mail_tls ⇒ String (readonly)
Returns “starttls”, “tls” or “none”.
236 237 238 |
# File 'cybertrain/mailer.rb', line 236 def mail_tls @mail_tls end |
#mail_user ⇒ String (readonly)
Returns the AUTH user, “” for none.
230 231 232 |
# File 'cybertrain/mailer.rb', line 230 def mail_user @mail_user end |
Class Method Details
.default_port(tls) ⇒ Integer
The port a mode uses when none is configured: 587 (submission) for starttls, 465 (submissions) for tls, 25 for none.
256 257 258 259 260 261 |
# File 'cybertrain/mailer.rb', line 256 def self.default_port(tls) return 465 if tls == "tls" return 25 if tls == "none" 587 end |
.deliver(to:, subject:, body:, html: "", from: "") ⇒ String
Sends one message with the settings in Config (Mailer.new’s
defaults).
337 338 339 |
# File 'cybertrain/mailer.rb', line 337 def self.deliver(to:, subject:, body:, html: "", from: "") Mailer.new.deliver(to: to, subject: subject, body: body, html: html, from: from) end |
.deliver_later(to:, subject:, body:, html: "", from: "") ⇒ Integer
Sends one message later, from a job: enqueues the built-in kind
“cybertrain mail” with the five fields as a JSON object (to,
subject, body, html, from), and a job thread (./<app>
server or ./<app> worker) delivers it with deliver and the
settings in Config at that time. The fields are checked now, as
deliver checks them, so a refused address or subject raises here
and nothing is enqueued. Render the bodies before calling
(Views.render_mail): the job has no view context.
The whole message, body and HTML included, is stored in the
database (the cybertrain_jobs row’s payload, shown on the jobs
page) until the job finishes, and for as long as the finished row is
kept.
The job’s policy:
- a TimeoutError, a ConnectError, or a RejectedError with a 4xx
reply (421, greylisting’s 450 / 451, 452: RFC 5321 calls them
transient) is retried 60 seconds later, until 5 attempts have
failed, when the row is
failed; - a RejectedError with a 5xx reply (a refused address will not become deliverable, a refused login needs the configuration fixed) discards the row;
- an ArgumentError when the job runs (a field the payload can never send: an empty from: with no Config#smtp_from, no Config#smtp_host, a payload changed in the database that fails the checks again) discards the row too, with nothing sent;
- any other error follows the default policy (Job).
One message goes to all the recipients in one SMTP transaction, so when the server refuses one of several recipients with a 5xx, the whole job is discarded and the other recipients do not get the mail either (with a 4xx it is retried for all of them). Enqueue one message per recipient when they should not depend on each other.
68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 |
# File 'cybertrain/mailer/later.rb', line 68 def self.deliver_later(to:, subject:, body:, html: "", from: "") sender = from.to_s recipients = to.to_s title = subject.to_s text = body.to_s markup = html.to_s Mailer.check_address(sender, "from") unless sender.empty? Mailer.split_recipients(recipients) Mailer.check_subject(title) Mailer.normalize_body(text) Mailer.normalize_body(markup) unless markup.empty? fields = { "to" => recipients, "subject" => title, "body" => text, "html" => markup, "from" => sender } payload = JSON.generate(fields) Job.enqueue(JOB_KIND, payload) end |
.deliveries ⇒ Array<MailMessage>
Every message delivered with the delivery method :test, oldest first
(Rails’ ActionMailer::Base.deliveries): what a test reads. The
test harness (cybertrain/test_help) empties it before every test.
Nothing else empties it, so it is for tests: a process that kept
:test while serving would keep every mail in memory (boot logs a
warning then, Config#mail_delivery_warning). Appends take a lock;
reads and clear do not, so read it from the test’s thread while no
job thread runs (a test program starts none).
389 390 391 |
# File 'cybertrain/mailer.rb', line 389 def self.deliveries @deliveries end |
Instance Method Details
#deliver(to:, subject:, body:, html: "", from: "") ⇒ String
Sends one message.
354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 |
# File 'cybertrain/mailer.rb', line 354 def deliver(to:, subject:, body:, html: "", from: "") given = from.to_s sender = given.empty? ? @mail_from : given Mailer.check_address(sender, "from") recipients = Mailer.split_recipients(to.to_s) title = subject.to_s Mailer.check_subject(title) text = Mailer.normalize_body(body.to_s) markup = html.to_s built = "" unless markup.empty? boundary = String.new boundary << "=_cybertrain_" << Crypto.random_token(16) built = Message.build(sender, to.to_s, title, text, markup, boundary) end if @mail_delivery_method == :test stored = MailMessage.new(to: to.to_s, subject: title, body: body.to_s, html: markup, from: sender) return Mailer.store_delivery(stored) end perform(sender, recipients, title, text, built) end |