protocol-smtp 0.1.0

data/lib/protocol/smtp/message.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+module Protocol
+  module SMTP
+    # One message, envelope and all. The envelope (#from, #to) is what the
+    # conversation said; the headers are what the data claims. They disagree
+    # more often than people expect, so both are here and neither is derived
+    # from the other.
+    class Message
+      # @parameter from [String] The envelope sender; "" is the null sender.
+      # @parameter helo [String | Nil] The domain the client introduced itself as.
+      # @parameter peer [String | Nil] Where the client connected from.
+      # @parameter secure [Boolean] Whether the message arrived over TLS.
+      def initialize(from:, helo: nil, peer: nil, secure: false)
+        @from = from
+        @helo = helo
+        @peer = peer
+        @secure = secure
+        @to = []
+        @data = +""
+      end
+
+      # @attribute [String] The envelope sender.
+      attr_reader :from
+
+      # @attribute [Array(String)] The envelope recipients, in the order given.
+      attr_reader :to
+
+      # @attribute [String] The message as it arrived, headers and all.
+      attr_reader :data
+
+      # @attribute [String | Nil] The domain the client introduced itself as.
+      attr_reader :helo
+
+      # @attribute [String | Nil] Where the client connected from.
+      attr_reader :peer
+
+      # @returns [Boolean] Whether the message arrived over TLS.
+      def secure? = @secure
+
+      # The headers, unfolded and downcased.
+      # @returns [Hash(String, String)]
+      def headers = @headers ||= parse_headers
+
+      # @returns [String | Nil]
+      def subject = headers["subject"]
+
+      # Everything after the blank line that ends the headers. A message with
+      # no blank line in it is all headers and no body (RFC 5322 2.1), which
+      # is also what a truncated one looks like.
+      #
+      # @returns [String]
+      def body = split_at_blank_line[1].to_s
+
+      # @returns [Integer] The size of the message, in bytes.
+      def bytesize = data.bytesize
+
+      # Enables `in [from, [to, *]]`
+      def deconstruct = [from, to]
+
+      # Enables `in {to: [/@example\.test\z/, *], subject: /urgent/i}`
+      def deconstruct_keys(_keys) = { from:, to:, data:, helo:, peer:, headers:, subject:, body: }
+
+      def inspect = "#<#{self.class} from=#{from.inspect} to=#{to.inspect} #{bytesize}B>"
+
+      private
+
+        # RFC 5322 2.2.3: a header field continues onto any following line
+        # that starts with whitespace, so unfold those before splitting each
+        # on its first colon. Last value wins for a repeated field — #data is
+        # right there for anything that needs more than that.
+        def parse_headers
+          split_at_blank_line.first.to_s.gsub(/\r?\n[ \t]+/, " ").lines.filter_map do |line|
+            case line.split(":", 2)
+            in [name, value] then [name.strip.downcase, value.strip]
+            else nil
+            end
+          end.to_h
+        end
+
+        def split_at_blank_line = data.split(/\r?\n\r?\n/, 2)
+    end
+  end
+end
+
+__END__
+
+new_message = lambda do |data, **options|
+  Protocol::SMTP::Message.new(from: "me@example.com", helo: "client", peer: "127.0.0.1", **options).tap do |message|
+    message.data << data
+  end
+end
+
+describe "protocol/smtp/message" do
+  it "keeps the envelope separate from what the headers claim" do
+    message = new_message.call("From: someone-else@example.com\r\n\r\nHello\r\n")
+    message.to << "you@example.com"
+
+    message.from.should == "me@example.com"
+    message.headers["from"].should == "someone-else@example.com"
+    message.to.should == ["you@example.com"]
+  end
+
+  it "unfolds a continued header (RFC 5322 2.2.3)" do
+    message = new_message.call("Subject: a very\r\n  long subject\r\nTo: you@example.com\r\n\r\nBody\r\n")
+
+    message.subject.should == "a very long subject"
+    message.headers["to"].should == "you@example.com"
+  end
+
+  it "separates the body at the blank line" do
+    new_message.call("Subject: Hi\r\n\r\nline one\r\nline two\r\n").body.should == "line one\r\nline two\r\n"
+  end
+
+  it "treats a message with no blank line as all headers and no body" do
+    # Which is also what a truncated one looks like:
+    message = new_message.call("just text\r\n")
+
+    message.headers.should == {}
+    message.body.should == ""
+  end
+
+  it "reports its size in bytes" do
+    new_message.call("\u03a9\r\n").bytesize.should == 4
+  end
+
+  it "is not secure unless it arrived over TLS" do
+    new_message.call("").should.not.be.secure
+    new_message.call("", secure: true).should.be.secure
+  end
+
+  it "deconstructs for pattern matching" do
+    message = new_message.call("Subject: URGENT\r\n\r\nnow\r\n")
+    message.to << "you@example.test"
+    urgent = nil
+
+    case message
+    in {to: [/@example\.test\z/, *], subject: /urgent/i}
+      urgent = message.peer
+    end
+
+    urgent.should == "127.0.0.1"
+
+    case message
+    in [from, [recipient]]
+      from.should == "me@example.com"
+      recipient.should == "you@example.test"
+    end
+  end
+end

data/lib/protocol/smtp/reply.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+module Protocol
+  module SMTP
+    # What the server says back. A reply is a code and one or more lines; on
+    # the wire every line but the last is joined to its code by a hyphen
+    # rather than a space, which is how the client knows more is coming
+    # (RFC 5321 4.2.1).
+    class Reply
+      CRLF = "\r\n"
+
+      # The replies the state machine itself sends. Anything an application
+      # wants to say is its own Reply.
+      def self.ok(text = "Ok") = new(250, text)
+      def self.rejected(text = "Message rejected") = new(550, text)
+
+      # A CRLF in the text would end the line early and let whatever follows
+      # it pass for a reply of its own. An application that quotes a subject
+      # line or an address back at the client — both of which came from the
+      # client — would otherwise be handing it a reply stream to write.
+      SEPARATORS = /[\r\n]+/
+
+      # @parameter code [Integer] The three digit reply code.
+      # @parameter lines [String | Array(String)] The text of the reply.
+      def initialize(code, lines)
+        @code = Integer(code)
+        @lines = Array(lines).map {|line| line.to_s.gsub(SEPARATORS, " ")}
+
+        case @lines
+        when [] then @lines = [""]
+        end
+      end
+
+      # @attribute [Integer] The three digit reply code.
+      attr_reader :code
+
+      # @attribute [Array(String)] The text of the reply, one entry per line.
+      attr_reader :lines
+
+      # @returns [String] The reply as it goes on the wire, terminator excluded.
+      def to_s
+        lines[0..-2].map { |line| "#{code}-#{line}" }.push("#{code} #{lines.last}").join(CRLF)
+      end
+
+      # @returns [String] The reply's text, lines joined by a space.
+      def text = lines.join(" ")
+
+      # 2xx and 3xx are the codes that let the conversation continue.
+      # @returns [Boolean]
+      def positive? = code < 400
+
+      # A 4xx is worth retrying later; a 5xx is not (RFC 5321 4.2.1).
+      # @returns [Boolean]
+      def transient? = code >= 400 && code < 500
+
+      # @returns [Boolean]
+      def permanent? = code >= 500
+
+      # Enables `in [250, [text, *]]`
+      def deconstruct = [code, lines]
+
+      # Enables `in {code: 250..299}`
+      def deconstruct_keys(_keys) = { code:, lines: }
+
+      def ==(other)
+        other.is_a?(Reply) && other.code == code && other.lines == lines
+      end
+      alias eql? ==
+
+      def hash = [code, lines].hash
+
+      def inspect = "#<#{self.class} #{code} #{text}>"
+    end
+  end
+end
+
+__END__
+
+describe "protocol/smtp/reply" do
+  it "puts a single line reply on one line" do
+    reply = Protocol::SMTP::Reply.new(250, "Ok")
+
+    reply.to_s.should == "250 Ok"
+    reply.should.be.positive
+    reply.should.not.be.transient
+    reply.should.not.be.permanent
+  end
+
+  it "joins every line but the last to its code with a hyphen (RFC 5321 4.2.1)" do
+    reply = Protocol::SMTP::Reply.new(250, ["greets you", "SIZE 100", "8BITMIME"])
+
+    reply.to_s.should == "250-greets you\r\n250-SIZE 100\r\n250 8BITMIME"
+    reply.text.should == "greets you SIZE 100 8BITMIME"
+  end
+
+  it "still produces a valid line with no text at all" do
+    Protocol::SMTP::Reply.new(220, nil).to_s.should == "220 "
+  end
+
+  it "refuses to let the text end the line" do
+    # Whatever an application quotes back at a client came from that client:
+    reply = Protocol::SMTP::Reply.ok("Queued \r\n550 Injected")
+
+    reply.to_s.should == "250 Queued  550 Injected"
+    reply.lines.length.should == 1
+  end
+
+  it "classifies 4xx as transient and 5xx as permanent" do
+    Protocol::SMTP::Reply.new(451, "Try later").should.be.transient
+    Protocol::SMTP::Reply.new(550, "No").should.be.permanent
+    Protocol::SMTP::Reply.new(550, "No").should.not.be.positive
+  end
+
+  it "compares by code and lines" do
+    Protocol::SMTP::Reply.ok.should == Protocol::SMTP::Reply.new(250, "Ok")
+    Protocol::SMTP::Reply.ok.should.not == Protocol::SMTP::Reply.new(250, "Fine")
+    {Protocol::SMTP::Reply.ok => true}[Protocol::SMTP::Reply.new(250, "Ok")].should.be.true
+  end
+
+  it "deconstructs for pattern matching" do
+    matched = nil
+
+    case Protocol::SMTP::Reply.rejected("Spam")
+    in {code: 500.., lines: [text]}
+      matched = text
+    end
+
+    matched.should == "Spam"
+    Protocol::SMTP::Reply.ok.deconstruct.should == [250, ["Ok"]]
+  end
+end