tempmail_sdk 1.3.3

data/lib/tempmail_sdk/retry.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module TempmailSdk
+  # 通用重试工具
+  # 提供请求重试、超时控制、指数退避等错误恢复机制
+  module Retry
+    # with_retry_with_attempts 的返回值封装
+    class AttemptsResult
+      attr_reader :ok, :attempts, :value, :error
+
+      def initialize(ok:, attempts:, value: nil, error: nil)
+        @ok = ok
+        @attempts = attempts
+        @value = value
+        @error = error
+      end
+
+      def ok?
+        @ok
+      end
+    end
+
+    # 网络级别错误关键字
+    NETWORK_KEYWORDS = [
+      "connection", "timeout", "timed out", "dns", "eof",
+      "broken pipe", "network is unreachable", "refused", "reset"
+    ].freeze
+
+    module_function
+
+    # 判断错误是否应该重试
+    # 触发重试：网络错误、429 限流、HTTP 4xx/5xx；仅参数校验类错误不重试
+    # @param error [Exception]
+    # @return [Boolean]
+    def should_retry?(error)
+      msg = error.message.to_s.downcase
+      return true if NETWORK_KEYWORDS.any? { |kw| msg.include?(kw) }
+      return true if msg.include?("429") || msg.include?("too many requests") || msg.include?("rate limit")
+      return true if msg.include?(": 4") || msg.include?(": 5")
+
+      # Net::HTTP 底层网络异常类型
+      case error
+      when Timeout::Error, Errno::ECONNREFUSED, Errno::ECONNRESET,
+           SocketError, EOFError, IOError
+        true
+      else
+        false
+      end
+    end
+
+    # 带重试的操作执行器（不抛异常版本）
+    # @param config [RetryConfig, nil]
+    # @yield 要执行的操作
+    # @return [AttemptsResult]
+    def with_retry_with_attempts(config = nil)
+      cfg = config || RetryConfig.new
+      logger = Log.logger
+      last_error = nil
+
+      (0..cfg.max_retries).each do |attempt|
+        attempts = attempt + 1
+        begin
+          result = yield
+          logger.info("第 #{attempt + 1} 次尝试成功") if attempt.positive?
+          return AttemptsResult.new(ok: true, attempts: attempts, value: result)
+        rescue StandardError => e
+          last_error = e
+          if attempt >= cfg.max_retries || !should_retry?(e)
+            return AttemptsResult.new(ok: false, attempts: attempts, error: e)
+          end
+
+          delay = [cfg.initial_delay * (2**attempt), cfg.max_delay].min
+          logger.warn("请求失败 (#{e.message})，#{format('%.1f', delay)}s 后第 #{attempt + 2} 次重试...")
+          sleep(delay)
+        end
+      end
+
+      AttemptsResult.new(ok: false, attempts: cfg.max_retries + 1, error: last_error)
+    end
+
+    # 带重试的操作执行器（失败抛异常版本）
+    # @param config [RetryConfig, nil]
+    # @yield 要执行的操作
+    def with_retry(config = nil, &block)
+      r = with_retry_with_attempts(config, &block)
+      return r.value if r.ok?
+
+      raise r.error
+    end
+  end
+end

data/lib/tempmail_sdk/telemetry.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "uri"
+
+module TempmailSdk
+  # 匿名用量遥测
+  # 默认开启，可通过配置或环境变量关闭；批量异步上报，失败静默忽略
+  module Telemetry
+    DEFAULT_URL = "https://sdk-1.openel.top/v1/event"
+    MAX_BATCH = 32
+    FLUSH_SEC = 2.0
+    EMAIL_RE = /[^\s@]{1,64}@[^\s@]{1,255}/.freeze
+    # 主机信息在进程内不变，预取为常量避免每次 flush 重复读取 RbConfig
+    HOST_OS = (RbConfig::CONFIG["host_os"] || "unknown").freeze
+    HOST_CPU = (RbConfig::CONFIG["host_cpu"] || "unknown").freeze
+
+    @queue = []
+    @lock = Mutex.new
+    @flush_thread = nil
+
+    class << self
+      # 上报一条遥测事件
+      # rubocop:disable Metrics/ParameterLists
+      def report(operation:, channel:, success:, attempt_count:, channels_tried:, error:)
+        return unless telemetry_on?
+
+        ensure_periodic
+
+        ev = {
+          "operation" => operation,
+          "channel" => channel,
+          "success" => success,
+          "attempt_count" => attempt_count,
+          "ts_ms" => (Time.now.to_f * 1000).to_i
+        }
+        ev["channels_tried"] = channels_tried if channels_tried.positive?
+        err = sanitize(error)
+        ev["error"] = err unless err.empty?
+
+        n = 0
+        @lock.synchronize do
+          @queue << ev
+          n = @queue.size
+        end
+
+        flush_batch if n >= MAX_BATCH
+      end
+      # rubocop:enable Metrics/ParameterLists
+
+      # @return [String] SDK 版本号
+      def sdk_version
+        VERSION
+      end
+
+      private
+
+      # 脱敏：邮箱替换为占位符，截断到 400 字符
+      def sanitize(msg)
+        return "" if msg.nil? || msg.empty?
+
+        msg.gsub(EMAIL_RE, "[redacted]")[0, 400]
+      end
+
+      def resolve_url
+        u = (Config.get_config.telemetry_url || "").strip
+        u.empty? ? DEFAULT_URL : u
+      end
+
+      def telemetry_on?
+        v = Config.get_config.telemetry_enabled
+        v.nil? ? true : !!v
+      end
+
+      # 启动周期性刷新线程（守护线程，进程退出即结束）
+      def ensure_periodic
+        @lock.synchronize do
+          return if @flush_thread&.alive?
+
+          @flush_thread = Thread.new do
+            loop do
+              sleep(FLUSH_SEC)
+              flush_batch
+            end
+          end
+          @flush_thread.abort_on_exception = false
+        end
+      end
+
+      # 刷新队列，异步 POST 上报
+      def flush_batch
+        events = nil
+        @lock.synchronize do
+          return if @queue.empty?
+
+          events = @queue.dup
+          @queue.clear
+        end
+
+        unless telemetry_on?
+          return
+        end
+
+        batch = {
+          "schema_version" => 2,
+          "sdk_language" => "ruby",
+          "sdk_version" => VERSION,
+          "os" => HOST_OS,
+          "arch" => HOST_CPU,
+          "events" => events
+        }
+        body = JSON.generate(batch)
+        Thread.new { post_body(resolve_url, body) }
+      end
+
+      # 实际发送（失败静默）
+      def post_body(url, body)
+        uri = URI.parse(url)
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = (uri.scheme == "https")
+        http.open_timeout = 8
+        http.read_timeout = 8
+        req = Net::HTTP::Post.new(uri.request_uri)
+        req["Content-Type"] = "application/json; charset=utf-8"
+        req["User-Agent"] = "tempmail-sdk-ruby/#{VERSION}"
+        req.body = body
+        http.request(req)
+      rescue StandardError
+        nil
+      end
+    end
+  end
+end

data/lib/tempmail_sdk/types.rb

@@ -0,0 +1,164 @@
+# frozen_string_literal: true
+
+module TempmailSdk
+  # 创建临时邮箱后返回的邮箱信息
+  # Token 等认证信息由 SDK 内部维护，不对外暴露（token 通过私有读取器访问）
+  class EmailInfo
+    # @return [String] 创建该邮箱所使用的渠道
+    attr_reader :channel
+    # @return [String] 临时邮箱地址
+    attr_accessor :email
+    # @return [Integer, nil] 邮箱过期时间（毫秒时间戳）
+    attr_accessor :expires_at
+    # @return [Object, nil] 邮箱创建时间
+    attr_accessor :created_at
+
+    # @param channel [String] 渠道标识
+    # @param email [String] 邮箱地址
+    # @param token [String, nil] 认证令牌，SDK 内部维护
+    # @param expires_at [Integer, nil] 过期时间（毫秒时间戳）
+    # @param created_at [Object, nil] 创建时间
+    def initialize(channel:, email:, token: nil, expires_at: nil, created_at: nil)
+      @channel = channel
+      @email = email
+      @token = token
+      @expires_at = expires_at
+      @created_at = created_at
+    end
+
+    # 允许在同一 provider 派生多个渠道别名时覆写渠道标识
+    # @param value [String] 新的渠道标识
+    attr_writer :channel
+
+    # SDK 内部使用的令牌读取器（对外语义上不暴露，仅内部 dispatch 使用）
+    # @return [String, nil]
+    def token
+      @token
+    end
+
+    def to_s
+      "#<EmailInfo channel=#{@channel.inspect} email=#{@email.inspect} " \
+        "expires_at=#{@expires_at.inspect} created_at=#{@created_at.inspect}>"
+    end
+    alias inspect to_s
+  end
+
+  # 邮件附件信息
+  class EmailAttachment
+    attr_accessor :filename, :size, :content_type, :url
+
+    def initialize(filename: "", size: nil, content_type: nil, url: nil)
+      @filename = filename
+      @size = size
+      @content_type = content_type
+      @url = url
+    end
+
+    def to_h
+      { filename: @filename, size: @size, content_type: @content_type, url: @url }
+    end
+  end
+
+  # 标准化的邮件对象
+  class Email
+    attr_accessor :id, :from_addr, :to, :subject, :text, :html, :date, :is_read, :attachments
+
+    # rubocop:disable Metrics/ParameterLists
+    def initialize(id: "", from_addr: "", to: "", subject: "", text: "", html: "",
+                   date: "", is_read: false, attachments: nil)
+      @id = id
+      @from_addr = from_addr
+      @to = to
+      @subject = subject
+      @text = text
+      @html = html
+      @date = date
+      @is_read = is_read
+      @attachments = attachments || []
+    end
+    # rubocop:enable Metrics/ParameterLists
+
+    def to_h
+      {
+        id: @id, from_addr: @from_addr, to: @to, subject: @subject,
+        text: @text, html: @html, date: @date, is_read: @is_read,
+        attachments: @attachments.map { |a| a.respond_to?(:to_h) ? a.to_h : a }
+      }
+    end
+  end
+
+  # 获取邮件列表的结果
+  class GetEmailsResult
+    attr_accessor :channel, :email, :emails, :success
+
+    def initialize(channel: "", email: "", emails: nil, success: true)
+      @channel = channel
+      @email = email
+      @emails = emails || []
+      @success = success
+    end
+  end
+
+  # 重试配置
+  class RetryConfig
+    attr_accessor :max_retries, :initial_delay, :max_delay, :timeout
+
+    # @param max_retries [Integer] 最大重试次数（不含首次请求），默认 2
+    # @param initial_delay [Float] 初始重试延迟（秒），默认 1.0
+    # @param max_delay [Float] 最大重试延迟（秒），默认 5.0
+    # @param timeout [Float] 请求超时（秒），默认 15.0
+    def initialize(max_retries: 2, initial_delay: 1.0, max_delay: 5.0, timeout: 15.0)
+      @max_retries = max_retries
+      @initial_delay = initial_delay
+      @max_delay = max_delay
+      @timeout = timeout
+    end
+  end
+
+  # 创建临时邮箱的选项
+  class GenerateEmailOptions
+    attr_accessor :channel, :duration, :domain, :retry_config,
+                  :max_channels_tried, :total_timeout, :suffix, :domains
+
+    # rubocop:disable Metrics/ParameterLists
+    def initialize(channel: nil, duration: 30, domain: nil, retry_config: nil,
+                   max_channels_tried: 20, total_timeout: 60.0, suffix: nil, domains: nil)
+      @channel = channel                     # 指定渠道，不指定则随机选择
+      @duration = duration                   # tempmail 渠道的有效期（分钟）
+      @domain = domain                       # 部分渠道指定接入域名
+      @retry_config = retry_config           # 重试配置
+      @max_channels_tried = max_channels_tried # 最大尝试渠道数
+      @total_timeout = total_timeout         # 整体超时时间（秒）
+      @suffix = suffix                       # 邮箱后缀筛选
+      @domains = domains                     # 多个目标域名
+    end
+    # rubocop:enable Metrics/ParameterLists
+  end
+
+  # 获取邮件的选项（Channel/Email/Token 由 SDK 从 EmailInfo 自动获取）
+  class GetEmailsOptions
+    attr_accessor :retry_config
+
+    def initialize(retry_config: nil)
+      @retry_config = retry_config
+    end
+  end
+
+  # 渠道信息
+  class ChannelInfo
+    attr_accessor :channel, :name, :website
+
+    def initialize(channel: "", name: "", website: "")
+      @channel = channel
+      @name = name
+      @website = website
+    end
+
+    def to_h
+      { channel: @channel, name: @name, website: @website }
+    end
+  end
+
+  # provider 尚未实现真实逻辑时抛出的错误（渠道仍可正常枚举）
+  class NotImplementedProviderError < StandardError; end
+end

data/lib/tempmail_sdk/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module TempmailSdk
+  # SDK 版本号
+  VERSION = "1.3.3"
+end