tina4ruby 3.13.137 → 3.13.139

data/lib/tina4/session_handlers/database_handler.rb

@@ -1,4 +1,10 @@
 # frozen_string_literal: true
+# Copyright (c) 2026 Code Infinity
+# SPDX-License-Identifier: MPL-2.0
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
 
 require "json"
 
@@ -211,25 +217,49 @@ module Tina4
       # spells "already exists" differently ("There is already an object named",
       # "already exists", SQLSTATE 42S01) and a string match would rot the first
       # time an engine reworded itself or ran under another locale.
+      #
+      # The re-check is RETRIED, a bounded number of times, because the loser
+      # can fail BEFORE the winner has committed. MEASURED on MySQL 8.4: CREATE
+      # TABLE IF NOT EXISTS takes a shared metadata lock on the name, checks,
+      # then upgrades it to exclusive, and two sessions upgrading at once is a
+      # metadata-lock deadlock. MySQL backs the victim off silently only when the
+      # session holds no other metadata lock; otherwise the victim gets 1213
+      # "Deadlock found" while the winner's table is still invisible, and one
+      # immediate re-check turned that lost race into a failed request (tina4-php
+      # CI run 35972320442). Same attempts and delays in all four frameworks.
+      CREATE_ATTEMPTS = 5
+      CREATE_RETRY_DELAY = 0.05
+
       def ensure_table
         return if @table_ready
 
         @table_ready = true
-        begin
-          db.execute(create_table_sql)
-        rescue StandardError
-          # A failed statement leaves PostgreSQL's transaction ABORTED, so
-          # without this the re-check would fail for the wrong reason and report
-          # a missing table that is right there. Best effort: an engine with no
-          # open transaction is entitled to object to being rolled back.
+        attempt = 1
+        until db.table_exists?(TABLE_NAME)
           begin
-            db.rollback
+            db.execute(create_table_sql)
+            return
           rescue StandardError
-            nil
+            # A failed statement leaves PostgreSQL's transaction ABORTED, so
+            # without this the re-check would fail for the wrong reason and
+            # report a missing table that is right there. Best effort: an engine
+            # with no open transaction is entitled to object to being rolled back.
+            begin
+              db.rollback
+            rescue StandardError
+              nil
+            end
+            # Somebody else created it - that is the race, and it is a success.
+            # Still absent after the last attempt is a real failure, re-raised
+            # untouched.
+            if attempt >= CREATE_ATTEMPTS
+              return if db.table_exists?(TABLE_NAME)
+
+              raise
+            end
+            sleep(CREATE_RETRY_DELAY * attempt)
+            attempt += 1
           end
-          # Somebody else created it - that is the race, and it is a success.
-          # Anything else is a real failure and is re-raised untouched.
-          raise unless db.table_exists?(TABLE_NAME)
         end
       end
     end

data/lib/tina4/session_handlers/file_handler.rb

@@ -1,4 +1,10 @@
 # frozen_string_literal: true
+# Copyright (c) 2026 Code Infinity
+# SPDX-License-Identifier: MPL-2.0
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
 require "json"
 require "fileutils"
 require "digest"

data/lib/tina4/session_handlers/memcached_handler.rb

@@ -1,4 +1,10 @@
 # frozen_string_literal: true
+# Copyright (c) 2026 Code Infinity
+# SPDX-License-Identifier: MPL-2.0
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
 
 require "digest"
 require "json"

data/lib/tina4/session_handlers/mongo_handler.rb

@@ -1,4 +1,10 @@
 # frozen_string_literal: true
+# Copyright (c) 2026 Code Infinity
+# SPDX-License-Identifier: MPL-2.0
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
 require "json"
 require_relative "mongo_wire_client"
 
@@ -51,36 +57,90 @@ module Tina4
         @database = options[:database] || ENV["TINA4_SESSION_MONGO_DB"] || "tina4"
         @collection_name = options[:collection] || ENV["TINA4_SESSION_MONGO_COLLECTION"] || "sessions"
         @gem_available = gem_available?
-        @client = nil
-        @wire_client = nil
-        @collection = nil
-        @index_ready = false
       end
 
-      # Release whichever transport was opened.
+      # ONE TRANSPORT PER PROCESS (issue #136, parity with tina4-python #136).
       #
-      # Mongo::Client owns a pool of REAL sockets. Before the client was lazy it
-      # was a local variable in #initialize, reachable only through the
-      # collection, so every construction leaked a pool and nothing could give it
-      # back. Now the handler holds the client, so the handler can close it -
-      # parity with the Python master's MongoDBSessionHandler.close() and with
-      # Tina4::DocStore.close_doc_store, which already closes its Mongo clients
-      # the same way. The zero-dependency transport owns ONE raw socket and is
-      # closed the same way, so neither path leaks. Safe to call on a handler
-      # that never connected.
-      def close
-        # Each close is guarded on its own: a failure on one transport must not
-        # skip the other, and neither may mask the caller's work.
-        [@client, @wire_client].each do |transport|
+      # Every request builds a Session and every Session builds a NEW handler,
+      # so a transport owned by the handler is a transport per REQUEST. The
+      # handler used to open its own Mongo::Client on first use - each with its
+      # own SDAM monitor threads and connection pool - and nothing ever closed
+      # it. MEASURED on the lab: 21 requests left 87 extra threads behind; on the
+      # zero-dependency path 40 sessions left 40 sockets open to MongoDB.
+      #
+      # A Mongo::Client is thread-safe and pools internally, so the driver
+      # expects exactly one per (uri, database) - the same shape
+      # Tina4::DocStore.mongo_client already uses. The zero-dependency
+      # MongoWireClient is bound to one collection and serialises its commands
+      # on its single socket, so it is shared per (uri, database, collection).
+      # Handlers hold no transport of their own: they look it up here on every
+      # operation, so a released transport is simply rebuilt on next use.
+      @shared = {}
+      @index_ready = {}
+      @shared_lock = Mutex.new
+
+      class << self
+        # The shared transport for +key+, built by the block on first use. The
+        # double-checked lock stops two threads racing the first request from
+        # both building a client and orphaning one - the same leak, just rarer.
+        def shared_transport(key)
+          transport = @shared[key]
+          return transport if transport
+
+          @shared_lock.synchronize { @shared[key] ||= yield }
+        end
+
+        # True exactly once per process for +key+ - used so the TTL index round
+        # trip runs once per (store, ttl), not once per request.
+        def claim_index(key)
+          @shared_lock.synchronize do
+            next false if @index_ready[key]
+
+            @index_ready[key] = true
+          end
+        end
+
+        # Close and forget the shared transport for +key+ (MongoHandler#close).
+        def release_shared(key)
+          close_transport(@shared_lock.synchronize { @shared.delete(key) })
+        end
+
+        # Close every shared session transport - process shutdown, or a test
+        # that must leave no connection behind. Safe to call at any time: the
+        # next session operation simply reconnects.
+        def close_shared_clients
+          transports = @shared_lock.synchronize do
+            values = @shared.values
+            @shared.clear
+            @index_ready.clear
+            values
+          end
+          transports.each { |transport| close_transport(transport) }
+          true
+        end
+
+        private
+
+        # A close failure must never mask the caller's work.
+        def close_transport(transport)
           transport&.close
         rescue StandardError
           nil
         end
-      ensure
-        @client = nil
-        @wire_client = nil
-        @collection = nil
-        @index_ready = false
+      end
+
+      # Release the transport this handler's configuration uses.
+      #
+      # The transport is SHARED per process (see .shared_transport), so this
+      # closes it for every handler pointed at the same store - exactly what an
+      # owner that is done with the store wants, and harmless to the rest: they
+      # look the transport up on every operation and reconnect on next use. The
+      # Mongo::Client (a pool of real sockets) and the zero-dependency socket
+      # are both closed this way, so neither path leaks. Safe to call on a
+      # handler that never connected. Parity with the Python master's
+      # MongoDBSessionHandler.close() and Tina4::DocStore.close_doc_store.
+      def close
+        self.class.release_shared(transport_key)
       end
 
       # Decide whether a stored document has expired, FROM THE DOCUMENT ALONE.
@@ -189,17 +249,25 @@ module Tina4
       # handler takes the other. A per-operation branch is a branch that can be
       # wrong on one path only - which is exactly how a fallback ships untested.
       def collection
-        return @collection if @collection
+        if @gem_available
+          client = self.class.shared_transport(transport_key) { Mongo::Client.new(@uri, database: @database) }
+          collection = client[@collection_name]
+          ensure_ttl_index(collection)
+          collection
+        else
+          self.class.shared_transport(transport_key) { build_wire_client }
+        end
+      end
 
+      # The registry key for this handler's transport: one Mongo::Client per
+      # (uri, database); one wire client per (uri, database, collection), since
+      # a MongoWireClient is bound to a single collection.
+      def transport_key
         if @gem_available
-          @client = Mongo::Client.new(@uri, database: @database)
-          @collection = @client[@collection_name]
-          ensure_ttl_index
+          [:gem, @uri, @database]
         else
-          @wire_client = build_wire_client
-          @collection = @wire_client
+          [:wire, @uri, @database, @collection_name]
         end
-        @collection
       end
 
       # The zero-dependency transport, pointed at the host and port parsed out of
@@ -258,18 +326,19 @@ module Tina4
       # does not exist when the gem is absent, so evaluating them would raise
       # NameError rather than the LoadError anyone would expect.
       #
-      # Runs ONCE per handler (@index_ready), on the first operation. The flag is
-      # set BEFORE the round trip so an unreachable server is not re-probed on
-      # every read - the same ordering the Python master uses for _table_ready.
-      def ensure_ttl_index
-        return if @index_ready
+      # Runs ONCE per process for each (store, collection, ttl), on the first
+      # operation - not once per handler, which is once per REQUEST (issue
+      # #136). The claim is taken BEFORE the round trip so an unreachable server
+      # is not re-probed on every read - the same ordering the Python master
+      # uses for _table_ready.
+      def ensure_ttl_index(collection)
+        return unless self.class.claim_index([@uri, @database, @collection_name, @ttl])
 
-        @index_ready = true
-        @collection.indexes.create_one({ updated_at: 1 }, expire_after_seconds: @ttl)
+        collection.indexes.create_one({ updated_at: 1 }, expire_after_seconds: @ttl)
       rescue Mongo::Error::OperationFailure => e
         raise unless e.code == 85 || e.message.include?("IndexOptionsConflict")
-        @collection.indexes.drop_one("updated_at_1")
-        @collection.indexes.create_one({ updated_at: 1 }, expire_after_seconds: @ttl)
+        collection.indexes.drop_one("updated_at_1")
+        collection.indexes.create_one({ updated_at: 1 }, expire_after_seconds: @ttl)
       rescue Mongo::Error => e
         # The index is the background REAPER, not the expiry authority - #read
         # checks expires_at on the document itself - so failing to create it must

data/lib/tina4/session_handlers/mongo_wire_client.rb

@@ -1,4 +1,10 @@
 # frozen_string_literal: true
+# Copyright (c) 2026 Code Infinity
+# SPDX-License-Identifier: MPL-2.0
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
 
 require "socket"
 
@@ -71,6 +77,10 @@ module Tina4
         @timeout = timeout
         @socket = nil
         @request_id = 0
+        # One socket carries one request/reply at a time. The client is SHARED
+        # by every session in the process (MongoHandler.shared_transport, issue
+        # #136), so concurrent requests must not interleave their frames.
+        @lock = Mutex.new
       end
 
       # Documents matching +filter+, capped at one.
@@ -142,15 +152,19 @@ module Tina4
       # transport failure, so the socket is dropped and the next command
       # reconnects rather than inheriting the damage.
       def exchange(document)
-        socket = connection
-        @request_id += 1
-        body = "\x00\x00\x00\x00".b + "\x00".b + encode_document(document) # flagBits(4) + section kind 0
-        header = [16 + body.bytesize, @request_id, 0, OP_MSG].pack("V4")
-        socket.write(header + body)
-        read_reply(socket)
-      rescue StandardError => e
-        close
-        raise MongoWireError, "MongoDB transport failed: #{e.message}"
+        @lock.synchronize do
+          socket = connection
+          @request_id += 1
+          body = "\x00\x00\x00\x00".b + "\x00".b + encode_document(document) # flagBits(4) + section kind 0
+          header = [16 + body.bytesize, @request_id, 0, OP_MSG].pack("V4")
+          socket.write(header + body)
+          read_reply(socket)
+        rescue StandardError => e
+          # Still under the lock: no other session can be mid-exchange on the
+          # socket being dropped. The next command reconnects.
+          close
+          raise MongoWireError, "MongoDB transport failed: #{e.message}"
+        end
       end
 
       def connection

data/lib/tina4/session_handlers/redis_handler.rb

@@ -1,4 +1,10 @@
 # frozen_string_literal: true
+# Copyright (c) 2026 Code Infinity
+# SPDX-License-Identifier: MPL-2.0
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
 require "json"
 require_relative "resp_client"
 

data/lib/tina4/session_handlers/resp_client.rb

@@ -1,4 +1,10 @@
 # frozen_string_literal: true
+# Copyright (c) 2026 Code Infinity
+# SPDX-License-Identifier: MPL-2.0
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
 
 require "socket"
 

data/lib/tina4/session_handlers/valkey_handler.rb

@@ -1,4 +1,10 @@
 # frozen_string_literal: true
+# Copyright (c) 2026 Code Infinity
+# SPDX-License-Identifier: MPL-2.0
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
 require "json"
 require_relative "resp_client"
 

data/lib/tina4/shutdown.rb

@@ -1,4 +1,10 @@
 # frozen_string_literal: true
+# Copyright (c) 2026 Code Infinity
+# SPDX-License-Identifier: MPL-2.0
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
 
 module Tina4
   # Graceful shutdown on SIGTERM / SIGINT.
@@ -80,10 +86,9 @@ module Tina4
         @shutdown_complete = true
         return if drained
 
-        # The deadline expired with requests still in flight. WEBrick's accept
-        # loop joins its worker threads with NO timeout of its own, so simply
-        # returning here would hang the process for as long as the slowest
-        # handler runs - exactly what TINA4_SHUTDOWN_TIMEOUT exists to prevent.
+        # The deadline expired with requests still in flight. Returning here
+        # would let the process live for as long as the slowest handler runs -
+        # exactly what TINA4_SHUTDOWN_TIMEOUT exists to prevent.
         # Flush first: exit! runs no at_exit handlers and does not flush stdio,
         # which would swallow the warning that explains the forced exit.
         $stdout.flush
@@ -107,10 +112,9 @@ module Tina4
 
       # Block until initiate_shutdown has finished every teardown step.
       #
-      # stop_accepting unblocks WEBrick's accept loop immediately, so its #start
-      # returns as soon as the in-flight workers are joined - which can be while
-      # the signal handler's thread is still stopping background tasks and
-      # closing database connections. The server's main thread calls this so the
+      # stop_accepting unblocks the built-in server's accept loop immediately, so
+      # its #start returns while the signal handler's thread is still draining
+      # requests, stopping background tasks and closing database connections. The server's main thread calls this so the
       # process does not exit out from under that teardown.
       def wait_for_completion(timeout = nil)
         return unless @shutting_down
@@ -144,13 +148,12 @@ module Tina4
         DEFAULT_TIMEOUT
       end
 
-      # Close the listening socket BEFORE draining. WEBrick's #shutdown wakes its
-      # accept loop and closes the listeners; it does not touch the worker
-      # threads already running, which the loop's own ensure joins - so new
+      # Close the listening socket BEFORE draining. Tina4::HttpServer#shutdown
+      # closes every listener and every keep-alive connection that is waiting
+      # for its next request; it does not touch a request being served - so new
       # connections are refused while in-flight requests still run to completion
-      # and write their full response. Measured on webrick 1.9.2 / Ruby 4.0.2:
-      # #shutdown returns in ~0.1ms, a connection attempted 0.3s later is
-      # ECONNREFUSED, and the 2s handler mid-flight still returns a full 200.
+      # and write their full response (spec/graceful_shutdown_spec.rb proves all
+      # three on a real SIGTERM).
       def stop_accepting
         return unless @server.respond_to?(:shutdown)
 

data/lib/tina4/smtp_client.rb

@@ -0,0 +1,222 @@
+# frozen_string_literal: true
+# Copyright (c) 2026 Code Infinity
+# SPDX-License-Identifier: MPL-2.0
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
+
+require "socket"
+require_relative "mail_socket"
+require_relative "base64"
+
+module Tina4
+  class Messenger
+    # Tina4's own SMTP client (RFC 5321), replacing the net-smtp gem. It covers
+    # exactly what Messenger sends with:
+    #
+    #   * transport: plain, STARTTLS, or implicit TLS. Implicit TLS defaults to
+    #     port 465, the rule Python (SMTP_SSL), PHP (ssl://) and Node (tls.connect)
+    #     already follow; the caller may also ask for it on any port (tls: true).
+    #     STARTTLS is REQUIRED when asked for: a server that does not offer it
+    #     fails the send rather than silently getting the message and the
+    #     credentials in clear (Net::SMTP#enable_starttls did the same).
+    #   * AUTH PLAIN, or AUTH LOGIN when that is all the server offers.
+    #   * MAIL FROM / RCPT TO / DATA with CRLF normalisation and dot-stuffing.
+    #
+    #   SmtpClient.start(host: "smtp.example.com", port: 587, starttls: true,
+    #                    username: "u", password: "p") do |smtp|
+    #     smtp.send_message(raw_message, "from@example.com", ["to@example.com"])
+    #   end
+    class SmtpClient
+      # A server reply outside the expected codes; the message is the reply text.
+      class Error < StandardError
+        attr_reader :code
+
+        def initialize(code, message)
+          @code = code
+          super(message)
+        end
+      end
+
+      IMPLICIT_TLS_PORT = 465
+
+      def self.start(**options)
+        client = new(**options)
+        client.connect
+        return client unless block_given?
+
+        begin
+          yield client
+        ensure
+          client.quit
+        end
+      end
+
+      # auth_mechanism forces "PLAIN" or "LOGIN"; nil picks from the server's
+      # EHLO list (PLAIN preferred, as Net::SMTP's :plain always sent).
+      def initialize(host:, port:, tls: nil, starttls: false, username: nil, password: nil,
+                     auth_mechanism: nil, timeout: 30, helo_domain: nil)
+        @host = host
+        @port = port.to_i
+        @implicit_tls = tls.nil? ? @port == IMPLICIT_TLS_PORT : tls
+        @starttls = starttls
+        @username = username
+        @password = password
+        @auth_mechanism = auth_mechanism&.upcase
+        @timeout = timeout
+        @helo_domain = helo_domain || local_host_name
+        @capabilities = []
+        @socket = nil
+      end
+
+      attr_reader :capabilities
+
+      def implicit_tls?
+        @implicit_tls
+      end
+
+      def tls?
+        @socket&.tls? || false
+      end
+
+      def connect
+        @socket = MailSocket.open(@host, @port, tls: implicit_tls?, timeout: @timeout)
+        read_reply(220)
+        greet
+        upgrade_to_tls if @starttls && !implicit_tls?
+        authenticate if @username && @password
+        self
+      rescue StandardError
+        close
+        raise
+      end
+
+      def send_message(message, from, recipients)
+        recipients = Array(recipients).map { |recipient| envelope_address(recipient) }
+        raise ArgumentError, "at least one recipient is required" if recipients.empty?
+
+        command("MAIL FROM:<#{envelope_address(from)}>", 250)
+        recipients.each { |recipient| command("RCPT TO:<#{recipient}>", 250, 251) }
+        command("DATA", 354)
+        @socket.write(self.class.data_block(message))
+        read_reply(250)
+      end
+
+      # QUIT politely, then close. Never raises: the message is already queued.
+      def quit
+        return unless @socket
+
+        begin
+          command("QUIT", 221)
+        rescue StandardError
+          nil
+        end
+        close
+      end
+
+      def close
+        @socket&.close
+        @socket = nil
+      end
+
+      # The DATA payload: every line ending normalised to CRLF, a line starting
+      # with "." doubled (RFC 5321 4.5.2), terminated by CRLF.CRLF.
+      def self.data_block(message)
+        data = message.to_s.b.gsub(/\r\n|\r|\n/n, "\r\n")
+        data << "\r\n" unless data.end_with?("\r\n")
+        data.gsub(/^\./n, "..") + ".\r\n"
+      end
+
+      private
+
+      def greet
+        @capabilities = command("EHLO #{@helo_domain}", 250).drop(1)
+      rescue Error => e
+        raise unless (500..599).cover?(e.code)
+
+        # A server that does not speak ESMTP: plain HELO, no extensions.
+        command("HELO #{@helo_domain}", 250)
+        @capabilities = []
+      end
+
+      def upgrade_to_tls
+        unless capability?("STARTTLS")
+          raise Error.new(0, "STARTTLS was requested but #{@host}:#{@port} does not offer it")
+        end
+
+        command("STARTTLS", 220)
+        @socket.start_tls
+        greet # capabilities change once the channel is encrypted (AUTH often appears)
+      end
+
+      def authenticate
+        case auth_mechanism
+        when "PLAIN"
+          command("AUTH PLAIN #{Tina4::Base64.strict_encode64("\0#{@username}\0#{@password}")}", 235)
+        when "LOGIN"
+          command("AUTH LOGIN", 334)
+          command(Tina4::Base64.strict_encode64(@username.to_s), 334)
+          command(Tina4::Base64.strict_encode64(@password.to_s), 235)
+        end
+      end
+
+      def auth_mechanism
+        return @auth_mechanism if @auth_mechanism
+
+        offered = @capabilities.filter_map { |line| line[/\AAUTH[ =](.*)\z/i, 1] }
+                               .flat_map { |list| list.upcase.split }
+        return "PLAIN" if offered.empty? || offered.include?("PLAIN")
+        return "LOGIN" if offered.include?("LOGIN")
+
+        raise Error.new(0, "#{@host}:#{@port} offers no supported AUTH mechanism (offered: #{offered.join(' ')})")
+      end
+
+      def capability?(name)
+        @capabilities.any? { |line| line.split(/[ =]/, 2).first.casecmp?(name) }
+      end
+
+      # Send one command line and read its reply; returns the reply lines.
+      def command(line, *expected)
+        if line.match?(/[\r\n]/)
+          raise ArgumentError, "SMTP command contains a line break"
+        end
+
+        @socket.write("#{line}\r\n")
+        read_reply(*expected)
+      end
+
+      # A reply is one or more "NNN-text" lines ending with "NNN text".
+      def read_reply(*expected)
+        lines = []
+        code = nil
+        loop do
+          raw = @socket.read_line.force_encoding(Encoding::UTF_8).scrub.chomp
+          code = raw[0, 3].to_i
+          lines << raw[4..].to_s
+          break unless raw[3] == "-"
+        end
+        return lines if expected.empty? || expected.include?(code)
+
+        raise Error.new(code, "#{code} #{lines.join(' ')}".strip)
+      end
+
+      # The bare address for the envelope: "Name <a@b>" -> "a@b". CR, LF and
+      # angle brackets inside it would let a caller inject SMTP commands.
+      def envelope_address(address)
+        text = address.to_s.strip
+        text = Regexp.last_match(1).strip if text =~ /<([^<>]*)>\s*\z/
+        raise ArgumentError, "invalid email address #{address.inspect}" if text.match?(/[\r\n<>]/)
+
+        text
+      end
+
+      def local_host_name
+        name = Socket.gethostname.to_s
+        name.match?(/\A[A-Za-z0-9.\-]+\z/) ? name : "localhost"
+      rescue StandardError
+        "localhost"
+      end
+    end
+  end
+end