Конфигурация

Эти случаи выбрасывают ArgumentError из той строки, где было неверное значение, а не всплывают непонятным сбоем при первой отправке. Сообщение говорит, что было не так и что передать вместо этого, и никогда не повторяет учётные данные.

Соберите клиент один раз и разделяйте его. Новый клиент на каждый запрос впустую выбрасывает свои открытые соединения, а никакая часть его состояния не привязана к вызывающему. После сборки клиент заморожен, и его безопасно использовать из многих потоков одновременно, поэтому процессу Puma или Sidekiq нужен только один, а после форка дочерний процесс открывает собственные соединения.

Для случая, который иначе потребовал бы по клиенту на ключ, например задания, отправляющего от имени нескольких рабочих пространств, передайте api_key: в вызов. Он заменяет заголовок Authorization для этого запроса и ничего не оставляет на клиенте.

message = {from: "[email protected]", to: "[email protected]", subject: "Your invoice", text: "Attached."}workspace_key = ENV.fetch("OPENEMAIL_API_KEY") client.emails.send(message) client.emails.send(message, api_key: workspace_key) client.threads.list(folder: "inbox", api_key: workspace_key)client.webhooks.list(api_key: workspace_key)

Каждый метод вне temp_mail принимает его как именованный аргумент, рядом с фильтрами списка, а методы temp_mail вместо него принимают inbox_token:. Он проверяется до отправки запроса по тому же правилу, что использует клиент, поэтому опечатка выбрасывает ArgumentError про api_key, переданный в этот вызов, а не 401 про учётные данные, которые потом ещё придётся искать. Повторный вызов сохраняет ключ, который ему дали.

client.raw является транспортом, через который проходит каждый метод. client.raw.request вызывает путь, который пока не оборачивает ни один метод, применяя учётные данные клиента, базовый URL, таймаут и политику повторов, и возвращает разобранное тело так же, как это делает метод.

ping = client.raw.request("/ping") label = client.raw.request("/labels", method: :post, body: {name: "Invoices"}) p ping[:ok], label[:id]

OpenEmail.create_temp_mail собирает клиент для одноразовых ящиков, который не несёт API-ключа и не читает его из окружения. Он создаёт ящики анонимно, а каждое чтение отправляет токен ящика, который вернул create, или более новый, который вернул extend: либо в каждом вызове как inbox_token:, либо один раз как OpenEmail.create_temp_mail(inbox_token:).

temp_mail = OpenEmail.create_temp_mail inbox = temp_mail.createpage = temp_mail.list_messages(inbox[:id], inbox_token: inbox[:token]) p page.items.size, page.expires_at

Приложение, которое человек подключил через OAuth, например инструмент командной строки или агент, держит токен доступа вместо API-ключа. Передайте его как access_token:: либо сам токен, либо любой объект, который отвечает на call и возвращает его, например lambda или Method. Он вызывается один раз на каждый вызов, а повторы этого вызова переиспользуют то, что он вернул, поэтому обновляйте токен внутри него, когда срок действия подходит к концу, и клиент никогда не придётся пересобирать.

tokens = {current: "token-from-your-oauth-flow"} oauth_client = OpenEmail::Client.new(access_token: -> { tokens.fetch(:current) }) me = oauth_client.me.get puts me[:clientId], me[:expiresAt] if me[:object] == "oauth_token"

Перед чувствительным изменением, например удалением домена или изменением вебхука, API запрашивает у токена доступа код подтверждения, который веб-приложение запросило бы у человека. Вызов выбрасывает OpenEmail::PermissionError, ошибку 403, у которой step_up_required? равно true, и ничего не изменилось. Запросите код, проверьте тот, который даст вам человек, затем повторите вызов. У API-ключа код никогда не запрашивается.

domain_id = "b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f" begin  client.domains.delete(domain_id)rescue OpenEmail::ApiError => error  raise unless error.step_up_required?   challenge = client.security.begin_step_up   if challenge[:method] == "email"    puts "Enter the code we emailed to #{challenge[:sentTo]}"  else    puts "Enter the code from your authenticator app, or a backup code"  end   client.security.verify_step_up(code: $stdin.gets.to_s.strip)  client.domains.delete(domain_id)end

Когда на RubyGems есть более новая версия гема, клиент сообщает об этом один раз за процесс в стандартный поток ошибок строкой вроде ℹ openemail 0.0.2 is available, you are on 0.0.1., за которой следует страница гема. Проверка запускается при сборке первого клиента в фоновом потоке с таймаутом в две секунды и только когда стандартный вывод является терминалом, а неудачная попытка связаться с RubyGems игнорируется.

Адаптер по умолчанию находит прокси с помощью встроенного в Ruby URI#find_proxy, поэтому следует тем же правилам, что и остальная стандартная библиотека: https_proxy или HTTPS_PROXY называет прокси, а no_proxy или NO_PROXY перечисляет хосты, к которым подключение идёт напрямую. Имя пользователя и пароль из URL прокси отправляются самому прокси, а к серверу на этой машине подключение через прокси никогда не идёт.

adapter: заменяет HTTP-слой. Это любой объект, который отвечает на call(request), включая lambda, и возвращает OpenEmail::HttpResponse с status, headers и body. Запрос является OpenEmail::HttpRequest с method, url, headers, body и timeout, поэтому тест может проверить, что именно ушло бы по сети.

requests = [] adapter = lambda do |request|  requests << request  OpenEmail::HttpResponse.new(    status: 200,    headers: {"content-type" => "application/json"},    body: JSON.generate({id: "msg_test", status: "sent", replayed: false})  )end test_client = OpenEmail::Client.new(api_key: "oe_test_fake", adapter:, max_retries: 0, disable_update_notice: true) sent = test_client.emails.send(from: "[email protected]", to: "[email protected]", subject: "Hi", text: "Hello") p sent[:status], requests.first.method, requests.first.url, requests.first.headers["Idempotency-Key"]p requests.first

При выводе запроса его заголовок Authorization показывается как [redacted], поэтому ключ никогда не попадает в журнал тестов.

• —Верните статус вне диапазона 2xx с конвертом ошибки API в теле, например {"error": {"type": "validation_error", "code": "invalid_parameter", "message": "..."}}, чтобы получить соответствующий подкласс OpenEmail::ApiError.
• —Выбросьте из call исключение Timeout::Error или Net::ReadTimeout, который является его разновидностью, чтобы получить OpenEmail::NetworkError, у которого timeout? равно true. Любой другой StandardError, например Errno::ECONNREFUSED, становится NetworkError, у которого timeout? равно false.
• —NameError, TypeError и ArgumentError, выброшенные внутри адаптера, считаются ошибками в нём самом. Они выбрасываются без изменений и никогда не повторяются.