tempmail_sdk 1.3.3

data/lib/tempmail_sdk/http.rb

@@ -0,0 +1,225 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+require "json"
+require "securerandom"
+
+module TempmailSdk
+  # 共享 HTTP 客户端
+  # 所有 provider 通过此模块发起 HTTP 请求，自动应用全局配置（代理、超时、SSL 等）
+  # 基于标准库 Net::HTTP 实现，无第三方依赖
+  module Http
+    # HTTP 响应的轻量封装，统一暴露状态码/正文/JSON/cookie 等
+    class Response
+      # @return [Integer] HTTP 状态码
+      attr_reader :status_code
+      # @return [String] 响应正文
+      attr_reader :body
+      # @return [Net::HTTPResponse] 原始响应对象
+      attr_reader :raw
+
+      def initialize(raw)
+        @raw = raw
+        @status_code = raw.code.to_i
+        @body = raw.body || ""
+      end
+
+      # @return [Boolean] 状态码是否 2xx
+      def ok?
+        @status_code >= 200 && @status_code < 300
+      end
+
+      # 状态码非 2xx 时抛出异常（错误消息含状态码，便于重试判定）
+      def raise_for_status
+        return self if ok?
+
+        raise "HTTP request failed: #{@status_code}"
+      end
+
+      # 解析 JSON 正文
+      # @return [Object]
+      def json
+        JSON.parse(@body)
+      end
+
+      # 获取单个响应头（大小写不敏感）
+      # @param name [String]
+      # @return [String, nil]
+      def header(name)
+        @raw[name]
+      end
+
+      # 获取全部 Set-Cookie 头
+      # @return [Array<String>]
+      def set_cookies
+        @raw.get_fields("set-cookie") || []
+      end
+
+      # 从 Set-Cookie 中提取指定名称的 cookie 值
+      # @param name [String]
+      # @return [String, nil]
+      def cookie_value(name)
+        set_cookies.each do |line|
+          line.split(";").first.to_s.strip.split("=", 2).then do |k, v|
+            return v if k == name
+          end
+        end
+        nil
+      end
+    end
+
+    # 复用持久连接时，陈旧连接被对端关闭会抛出的错误类型。
+    # 原实现每次新建连接，故对这些错误重建连接重试一次，语义等价且幂等。
+    CONN_RESET_ERRORS = [EOFError, Errno::ECONNRESET, Errno::EPIPE,
+                         Errno::ECONNABORTED, IOError].freeze
+
+    # 持久连接池：key => { http: Net::HTTP|nil, mutex: Mutex }
+    # 按 host/port/scheme/proxy/insecure 归类，复用 keep-alive 连接，避免每次请求重建 TCP+TLS。
+    @pool = {}
+    @pool_mutex = Mutex.new
+    @pool_config_version = -1
+
+    module_function
+
+    # 生成随机 IPv4 地址（每段 1-254），用于伪造来源 IP 请求头
+    def random_ipv4
+      Array.new(4) { rand(1..254) }.join(".")
+    end
+
+    # 生成一组伪造来源 IP 的请求头，所有头使用同一个随机 IP
+    def spoof_ip_headers
+      ip = random_ipv4
+      {
+        "X-Forwarded-For" => ip,
+        "X-Real-IP" => ip,
+        "X-Originating-IP" => ip
+      }
+    end
+
+    # 将伪造来源 IP 请求头合并到用户指定的 headers 中（每次请求生成新的随机 IP）
+    def merge_spoof_headers(headers)
+      merged = spoof_ip_headers
+      merged.merge!(headers) if headers
+      merged
+    end
+
+    # 带全局配置的 GET 请求（自动注入伪造来源 IP 请求头）
+    # @param url [String]
+    # @param headers [Hash, nil]
+    # @param timeout [Integer, nil]
+    # @return [Response]
+    def get(url, headers: nil, timeout: nil)
+      request(:get, url, headers: headers, timeout: timeout)
+    end
+
+    # 带全局配置的 POST 请求
+    # @param json [Object, nil] 作为 JSON 序列化的请求体
+    # @param body [String, nil] 原始请求体
+    def post(url, headers: nil, timeout: nil, json: nil, body: nil)
+      request(:post, url, headers: headers, timeout: timeout, json: json, body: body)
+    end
+
+    # 通用请求执行（复用持久连接池）
+    def request(method, url, headers: nil, timeout: nil, json: nil, body: nil)
+      config = Config.get_config
+      uri = URI.parse(url)
+      effective_timeout = timeout || config.timeout || 15
+      req = build_request(method, uri, config, headers, json, body)
+
+      entry = acquire_entry(uri, config)
+      # 同一连接同一时刻仅允许一个请求，保证 socket 读写不交错
+      entry[:mutex].synchronize do
+        perform_with_reuse(entry, uri, config, effective_timeout, req)
+      end
+    end
+
+    # 获取（或初始化）目标主机的池条目；配置变更时整体重建连接池
+    def acquire_entry(uri, config)
+      key = pool_key(uri)
+      @pool_mutex.synchronize do
+        version = Config.config_version
+        if version != @pool_config_version
+          @pool.each_value { |e| safe_finish(e[:http]) }
+          @pool.clear
+          @pool_config_version = version
+        end
+        @pool[key] ||= { http: nil, mutex: Mutex.new }
+      end
+    end
+
+    # 使用/建立持久连接执行请求；陈旧连接被对端关闭时重建一次
+    def perform_with_reuse(entry, uri, config, timeout, req)
+      http = entry[:http]
+      if http.nil? || !http.started?
+        http = start_http(uri, config, timeout)
+        entry[:http] = http
+      else
+        http.open_timeout = timeout
+        http.read_timeout = timeout
+      end
+
+      begin
+        Response.new(http.request(req))
+      rescue *CONN_RESET_ERRORS
+        safe_finish(http)
+        http = start_http(uri, config, timeout)
+        entry[:http] = http
+        Response.new(http.request(req))
+      end
+    end
+
+    # 池键：区分协议/主机/端口即可（配置变更整体清池）
+    def pool_key(uri)
+      "#{uri.scheme}://#{uri.host}:#{uri.port}"
+    end
+
+    # 建立并启动持久连接（启用 keep-alive）
+    def start_http(uri, config, timeout)
+      http = build_http(uri, config, timeout)
+      http.keep_alive_timeout = 30
+      http.start
+      http
+    end
+
+    # 安全关闭连接，忽略关闭期异常
+    def safe_finish(http)
+      http&.finish if http&.started?
+    rescue StandardError
+      nil
+    end
+
+    # 构造 Net::HTTP 实例（应用代理、TLS、超时）
+    def build_http(uri, config, timeout)
+      http = if config.proxy && !config.proxy.empty?
+               p = URI.parse(config.proxy)
+               Net::HTTP.new(uri.host, uri.port, p.host, p.port, p.user, p.password)
+             else
+               Net::HTTP.new(uri.host, uri.port)
+             end
+      http.use_ssl = (uri.scheme == "https")
+      http.verify_mode = OpenSSL::SSL::VERIFY_NONE if config.insecure && http.use_ssl?
+      http.open_timeout = timeout
+      http.read_timeout = timeout
+      http
+    end
+
+    # 构造请求对象并写入请求头/请求体
+    def build_request(method, uri, config, headers, json, body)
+      klass = method == :post ? Net::HTTP::Post : Net::HTTP::Get
+      req = klass.new(uri.request_uri)
+
+      merged = merge_spoof_headers(headers)
+      config.headers&.each { |k, v| req[k] = v }
+      merged.each { |k, v| req[k] = v }
+
+      if json
+        req.body = JSON.generate(json)
+        req["Content-Type"] ||= "application/json"
+      elsif body
+        req.body = body
+      end
+      req
+    end
+  end
+end

data/lib/tempmail_sdk/logger.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require "logger"
+
+module TempmailSdk
+  # SDK 日志模块
+  # 默认静默不输出，用户可通过 set_log_level 启用
+  module Log
+    LOG_SILENT = 100          # 关闭所有日志
+    LOG_ERROR = Logger::ERROR
+    LOG_WARN = Logger::WARN
+    LOG_INFO = Logger::INFO
+    LOG_DEBUG = Logger::DEBUG
+
+    @logger = Logger.new($stderr)
+    @logger.level = LOG_SILENT
+    @logger.formatter = proc { |severity, _time, _progname, msg| "#{severity} #{msg}\n" }
+
+    class << self
+      # 设置日志级别，默认 LOG_SILENT（不输出）
+      # @param level [Integer]
+      def set_log_level(level)
+        @logger.level = level
+      end
+
+      # 设置自定义 logger 实例
+      # @param logger [Logger]
+      def set_logger(logger)
+        @logger = logger
+      end
+
+      # @return [Logger] 当前 SDK 使用的 logger
+      def logger
+        @logger
+      end
+    end
+  end
+end

data/lib/tempmail_sdk/normalize.rb

@@ -0,0 +1,193 @@
+# frozen_string_literal: true
+
+require "time"
+
+module TempmailSdk
+  # 邮件数据标准化模块
+  # 将各提供商返回的原始邮件数据（Hash，键为字符串）标准化为统一的 Email 格式
+  module Normalize
+    # 各字段的候选键顺序（frozen 常量，避免每次调用重复分配数组）
+    ID_KEYS = %w[id eid _id mailboxId messageId mail_id].freeze
+    FROM_KEYS = %w[from_addr from_address fromAddress mail_sender sender
+                   address_from from_email from messageFrom].freeze
+    TO_KEYS = %w[to to_address toAddress name_to email_address address].freeze
+    SUBJECT_KEYS = %w[subject e_subject mail_title].freeze
+    TEXT_KEYS = %w[text text_body preview_text mail_body_text body content
+                   body_text text_content description].freeze
+    HTML_KEYS = %w[html html_body html_content body_html mail_body_html].freeze
+    DATE_STR_KEYS = %w[received_at receivedAt created_at createdAt date].freeze
+    DATE_NUM_KEYS = %w[timestamp e_date].freeze
+    IS_READ_BOOL_KEYS = %w[seen read isRead].freeze
+    IS_READ_MIXED_KEYS = %w[is_read is_seen].freeze
+
+    # 日期解析用预编译正则（避免方法内每次新建 Regexp）
+    TRAILING_Z_RE = /Z\z/.freeze
+
+    module_function
+
+    # 将各提供商返回的原始邮件数据标准化为统一的 Email 格式
+    # 不同渠道字段名各异，此函数通过多字段候选策略统一映射
+    # @param raw [Hash] 原始邮件数据（字符串键）
+    # @param recipient_email [String] 收件人邮箱（无匹配字段时回退）
+    # @return [Email]
+    def normalize_email(raw, recipient_email = "")
+      raw = stringify_keys(raw)
+      text = normalize_text(raw)
+      html = normalize_html(raw)
+
+      # 修正 text/html 错配
+      if !text.empty? && html.empty? && html_content?(text)
+        html = text
+        text = ""
+      end
+      text = HtmlUtils.html_to_text(html) if text.empty? && !html.empty?
+      html = "<html><body><pre>#{HtmlUtils.escape(text)}</pre></body></html>" if !text.empty? && html.empty?
+
+      Email.new(
+        id: normalize_id(raw),
+        from_addr: normalize_from(raw),
+        to: normalize_to(raw, recipient_email),
+        subject: normalize_subject(raw),
+        text: text,
+        html: html,
+        date: normalize_date(raw),
+        is_read: normalize_is_read(raw),
+        attachments: normalize_attachments(raw["attachments"])
+      )
+    end
+
+    # 将 Hash 的符号键统一转为字符串键（浅层）
+    def stringify_keys(raw)
+      return {} unless raw.is_a?(Hash)
+
+      raw.each_with_object({}) { |(k, v), h| h[k.to_s] = v }
+    end
+
+    # 检测内容是否为 HTML（只取前 200 字符）
+    def html_content?(content)
+      prefix = content[0, 200].to_s.strip.downcase
+      return true if prefix.start_with?("<!doctype html", "<html", "<body")
+
+      trimmed = content.strip.downcase
+      return true if trimmed.include?("<div") && trimmed.include?("</div>")
+      return true if trimmed.include?("<table") && trimmed.include?("</table>")
+      return true if trimmed.include?("<p") && trimmed.include?("</p>") && trimmed.include?("<")
+
+      false
+    end
+
+    # 从 Hash 中按优先级顺序提取字符串值
+    def get_str(raw, *keys)
+      get_str_keys(raw, keys)
+    end
+
+    # 从 Hash 中按给定候选键数组（可复用 frozen 常量）提取字符串值
+    def get_str_keys(raw, keys)
+      keys.each do |key|
+        val = raw[key]
+        return val.to_s unless val.nil?
+      end
+      ""
+    end
+
+    def normalize_id(raw)
+      get_str_keys(raw, ID_KEYS)
+    end
+
+    def normalize_from(raw)
+      get_str_keys(raw, FROM_KEYS)
+    end
+
+    def normalize_to(raw, recipient_email)
+      result = get_str_keys(raw, TO_KEYS)
+      result.empty? ? recipient_email : result
+    end
+
+    def normalize_subject(raw)
+      get_str_keys(raw, SUBJECT_KEYS)
+    end
+
+    def normalize_text(raw)
+      get_str_keys(raw, TEXT_KEYS)
+    end
+
+    def normalize_html(raw)
+      get_str_keys(raw, HTML_KEYS)
+    end
+
+    # 提取并统一日期格式为 ISO 8601
+    def normalize_date(raw)
+      DATE_STR_KEYS.each do |key|
+        val = raw[key]
+        next if val.nil?
+
+        return parse_date_value(val)
+      end
+
+      DATE_NUM_KEYS.each do |key|
+        val = raw[key]
+        next unless val.is_a?(Numeric) && val.positive?
+
+        secs = key == "timestamp" && val < 1e12 ? val : val / 1000.0
+        return Time.at(secs).utc.iso8601
+      end
+
+      ""
+    end
+
+    # 解析单个日期值（字符串/秒/毫秒时间戳）
+    def parse_date_value(val)
+      if val.is_a?(String) && !val.empty?
+        begin
+          return Time.iso8601(val.sub(TRAILING_Z_RE, "+00:00")).iso8601
+        rescue ArgumentError
+          begin
+            return Time.strptime("#{val} UTC", "%Y-%m-%d %H:%M:%S %Z").utc.iso8601
+          rescue ArgumentError
+            return val
+          end
+        end
+      elsif val.is_a?(Numeric) && val.positive?
+        secs = val > 1e12 ? val / 1000.0 : val
+        return Time.at(secs).utc.iso8601
+      end
+      ""
+    end
+
+    # 提取已读状态，支持 bool / int(0|1) / str('0'|'1')
+    def normalize_is_read(raw)
+      IS_READ_BOOL_KEYS.each do |key|
+        val = raw[key]
+        return val if val == true || val == false
+      end
+
+      IS_READ_MIXED_KEYS.each do |key|
+        val = raw[key]
+        next if val.nil?
+
+        return val if [true, false].include?(val)
+        return val.to_i != 0 if val.is_a?(Numeric)
+        return val == "1" if val.is_a?(String)
+      end
+
+      false
+    end
+
+    # 提取并标准化附件列表
+    def normalize_attachments(attachments)
+      return [] unless attachments.is_a?(Array)
+
+      attachments.filter_map do |a|
+        a = stringify_keys(a)
+        next unless a.is_a?(Hash)
+
+        EmailAttachment.new(
+          filename: a["filename"] || a["name"] || "",
+          size: a["size"] || a["filesize"],
+          content_type: a["contentType"] || a["content_type"] || a["mimeType"] || a["mime_type"],
+          url: a["url"] || a["download_url"] || a["downloadUrl"]
+        )
+      end
+    end
+  end
+end

data/lib/tempmail_sdk/providers/anonbox.rb

@@ -0,0 +1,248 @@
+# frozen_string_literal: true
+
+module TempmailSdk
+  module Providers
+    # anonbox.net (CCC) — GET /en/ 解析 HTML，HTTP mbox 取信
+    module Anonbox
+      CHANNEL = "anonbox"
+      PAGE_URL = "https://anonbox.net/en/"
+      BASE = "https://anonbox.net"
+
+      MAIL_LINK_RE = %r{<a href="https://anonbox\.net/([a-z0-9-]+)/([A-Za-z0-9._~-]+)">https://anonbox\.net/[^"]+</a>}i
+      DD_RE = /<dd([^>]*)>([\s\S]*?)<\/dd>/mi
+      DISPLAY_NONE_RE = /display\s*:\s*none/i
+      P_RE = /<p>([\s\S]*?)<\/p>/mi
+      SPAN_RE = /<span\b[^>]*>[\s\S]*?<\/span>/mi
+      TAG_RE = /<[^>]+>/
+      EXPIRES_RE = /Your mail address is valid until:<\/dt>\s*<dd><p>([^<]+)<\/p>/mi
+      MBOX_SPLIT_RE = /\r?\n(?=From )/
+
+      HEADERS = {
+        "User-Agent" => "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36",
+        "Accept" => "text/html,application/xhtml+xml"
+      }.freeze
+
+      module_function
+
+      # 去除 HTML 标签并还原常见实体
+      def strip_tags(html_str)
+        s = html_str.gsub(TAG_RE, "")
+        s.gsub("&nbsp;", " ")
+         .gsub("&amp;", "&")
+         .gsub("&lt;", "<")
+         .gsub("&gt;", ">")
+         .strip
+      end
+
+      # 简单哈希，用于生成邮件 ID
+      def simple_hash(s)
+        h = 0
+        s.each_char { |c| h = (h * 31 + c.ord) & 0xFFFFFFFF }
+        return "0" if h == 0
+
+        digits = "0123456789abcdefghijklmnopqrstuvwxyz"
+        out = []
+        n = h
+        while n > 0
+          out.unshift(digits[n % 36])
+          n /= 36
+        end
+        out.join
+      end
+
+      # 从首页 HTML 中解析邮箱地址、token、过期时间
+      def parse_en_page(html_str)
+        m = html_str.match(MAIL_LINK_RE)
+        raise "anonbox: mailbox link not found" unless m
+
+        inbox = m[1]
+        secret = m[2]
+        token = "#{inbox}/#{secret}"
+
+        # 从 <dd> 中提取邮箱地址
+        address_html = nil
+        html_str.scan(DD_RE).each do |attrs, inner|
+          next if attrs.match?(DISPLAY_NONE_RE)
+
+          pm = inner.match(P_RE)
+          next unless pm
+
+          p_inner = pm[1].gsub(SPAN_RE, "")
+          display = strip_tags(p_inner)
+          next unless display.include?("@")
+
+          at = display.rindex("@")
+          local = display[0...at].strip
+          domain = display[(at + 1)..].strip.downcase
+          next if domain == "googlemail.com"
+
+          expected_domain = "#{inbox}.anonbox.net".downcase
+          next if domain != expected_domain
+          next if local.empty?
+
+          address_html = display
+          break
+        end
+
+        raise "anonbox: address paragraph not found" unless address_html
+
+        at = address_html.index("@")
+        raise "anonbox: bad address" unless at
+
+        local = address_html[0...at].strip
+        raise "anonbox: empty local part" if local.empty?
+
+        email = "#{local}@#{inbox}.anonbox.net"
+        em = html_str.match(EXPIRES_RE)
+        exp = em ? em[1].strip : nil
+        [email, token, exp]
+      end
+
+      # 解码 quoted-printable 编码
+      def decode_qp_if_needed(body, header_block)
+        te = header_block.match(/(?i)^content-transfer-encoding:\s*([^\s]+)/m)
+        enc = te ? te[1].downcase.strip : ""
+        return body.rstrip unless enc == "quoted-printable"
+
+        soft = body.gsub(/=\r?\n/, "")
+        result = []
+        bytes = soft.bytes
+        i = 0
+        while i < bytes.length
+          if bytes[i] == 61 && i + 2 < bytes.length # '='
+            hex = [bytes[i + 1], bytes[i + 2]].pack("C*")
+            begin
+              result << hex.to_i(16)
+              i += 3
+              next
+            rescue ArgumentError
+              # 非法十六进制，作为普通字符处理
+            end
+          end
+          result << bytes[i]
+          i += 1
+        end
+        result.pack("C*").force_encoding("UTF-8").rstrip
+      end
+
+      # 解析 mbox 格式单条邮件
+      def mbox_block_to_raw(block, recipient)
+        normalized = block.gsub("\r\n", "\n")
+        lines = normalized.split("\n")
+        i = 0
+        i = 1 if lines.first&.start_with?("From ")
+
+        headers = {}
+        cur_key = ""
+        while i < lines.length
+          line = lines[i]
+          if line == ""
+            i += 1
+            break
+          end
+          if (line[0] == " " || line[0] == "\t") && !cur_key.empty?
+            headers[cur_key] = "#{headers[cur_key]} #{line.strip}"
+          else
+            idx = line.index(":")
+            if idx && idx > 0
+              cur_key = line[0...idx].strip.downcase
+              headers[cur_key] = line[(idx + 1)..].strip
+            end
+          end
+          i += 1
+        end
+
+        body = lines[i..].join("\n")
+        ct = (headers["content-type"] || "").downcase
+        text = ""
+        html = ""
+
+        if ct.include?("multipart/")
+          bm = headers["content-type"]&.match(/(?i)boundary="?([^";\s]+)"?/)
+          if bm
+            boundary = Regexp.escape(bm[1])
+            parts = body.split(/\r?\n--#{boundary}(?:--)?\r?\n/)
+            parts.each do |part|
+              part = part.strip
+              next if part.empty? || part == "--"
+
+              sep = part.index("\n\n")
+              next unless sep
+
+              ph = part[0...sep]
+              pb = part[(sep + 2)..]
+              pct_m = ph.match(/(?i)^content-type:\s*([^\s;]+)/m)
+              pct = pct_m ? pct_m[1].downcase : ""
+
+              if pct == "text/plain"
+                text = decode_qp_if_needed(pb, ph)
+              elsif pct == "text/html"
+                html = decode_qp_if_needed(pb, ph)
+              end
+            end
+          end
+        end
+
+        if text.empty? && html.empty?
+          if ct.include?("text/html")
+            html = decode_qp_if_needed(body, headers["content-type"] || "")
+          else
+            text = decode_qp_if_needed(body, headers["content-type"] || "")
+          end
+        end
+
+        date_str = headers["date"] || ""
+        unless date_str.empty?
+          begin
+            date_str = Time.parse(date_str.strip).iso8601
+          rescue ArgumentError, TypeError
+            # 保持原值
+          end
+        end
+        date_str = Time.now.utc.iso8601 if date_str.empty?
+
+        msg_id = headers["message-id"] || simple_hash(block[0, 512])
+        {
+          "id" => msg_id,
+          "from" => headers["from"] || "",
+          "to" => headers["to"] || recipient,
+          "subject" => headers["subject"] || "",
+          "body_text" => text,
+          "body_html" => html,
+          "date" => date_str,
+          "isRead" => false,
+          "attachments" => []
+        }
+      end
+
+      # 创建 anonbox 临时邮箱
+      # @return [EmailInfo]
+      def generate_email
+        r = Http.get(PAGE_URL, headers: HEADERS, timeout: 15)
+        r.raise_for_status
+        email, token, exp = parse_en_page(r.body)
+        EmailInfo.new(channel: CHANNEL, email: email, token: token, created_at: exp)
+      end
+
+      # 获取邮件列表
+      # @param token [String] inbox/secret 路径
+      # @param email [String]
+      # @return [Array<Email>]
+      def get_emails(token, email)
+        raise "token is required for anonbox channel" if token.nil? || token.to_s.empty?
+
+        path = token.end_with?("/") ? token : "#{token}/"
+        url = "#{BASE}/#{path}"
+        r = Http.get(url, headers: HEADERS.merge("Accept" => "text/plain,*/*"), timeout: 15)
+        return [] if r.status_code == 404
+
+        r.raise_for_status
+        raw = r.body.strip
+        return [] if raw.empty?
+
+        blocks = raw.split(MBOX_SPLIT_RE).map(&:strip).reject(&:empty?)
+        blocks.map { |b| Normalize.normalize_email(mbox_block_to_raw(b, email), email) }
+      end
+    end
+  end
+end