پیکربندی

این‌ها ArgumentError را از همان خطی که مقدار نادرست در آن بوده raise می‌کنند، به‌جای آنکه به‌صورت شکستی گیج‌کننده در نخستین ارسال شما ظاهر شوند. پیام می‌گوید چه چیزی نادرست بوده و به‌جایش چه باید داد، و هرگز اعتبارنامه را تکرار نمی‌کند.

کلاینت را یک بار بسازید و به اشتراک بگذارید. کلاینت تازه برای هر درخواست، بی‌هیچ سودی اتصال‌های باز خود را دور می‌ریزد، و هیچ‌یک از وضعیت‌های روی آن مخصوص یک فراخواننده نیست. کلاینت پس از ساخته شدن منجمد (frozen) می‌شود و استفادهٔ هم‌زمان از آن در چندین ترد بی‌خطر است، پس یک فرایند Puma یا Sidekiq فقط به یکی نیاز دارد، و پس از fork فرایند فرزند اتصال‌های خودش را باز می‌کند.

برای موردی که در غیر این صورت به ازای هر کلید یک کلاینت لازم می‌کرد، مثلاً کاری که از طرف چند فضای کاری ارسال می‌کند، 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: می‌گیرند. پیش از فرستادن درخواست و با همان قاعده‌ای که کلاینت به کار می‌برد بررسی می‌شود، پس یک غلط تایپی به‌جای 401 دربارهٔ اعتبارنامه‌ای که باید بگردید و پیدایش کنید، یک ArgumentError دربارهٔ api_key داده‌شده به این فراخوانی raise می‌کند. فراخوانی‌ای که دوباره تلاش می‌شود همان کلیدی را نگه می‌دارد که به آن داده شده بود.

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. برای هر فراخوانی یک بار صدا زده می‌شود و تلاش‌های دوبارهٔ همان فراخوانی از چیزی که برگردانده استفاده می‌کنند، پس وقتی توکن نزدیک انقضاست آن را درون همان callable تازه کنید تا هرگز لازم نباشد کلاینت را از نو بسازید.

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 را raise می‌کند، یک 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

وقتی نسخهٔ تازه‌تری از gem روی RubyGems باشد، کلاینت این را یک بار در هر فرایند، روی خروجی خطای استاندارد، با خطی مانند ℹ openemail 0.0.2 is available, you are on 0.0.1. و به دنبالش صفحهٔ gem اعلام می‌کند. این بررسی هنگام ساخته شدن نخستین کلاینت، در یک ترد پس‌زمینه با مهلت دو ثانیه، و فقط وقتی خروجی استاندارد یک ترمینال باشد اجرا می‌شود، و ناتوانی در دسترسی به RubyGems نادیده گرفته می‌شود.

آداپتور پیش‌فرض پراکسی خود را با URI#find_proxy خودِ Ruby پیدا می‌کند، پس از همان قواعد بقیهٔ کتابخانهٔ استاندارد پیروی می‌کند: 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 را raise کنید، یا Net::ReadTimeout را که خودش از همین نوع است، تا یک OpenEmail::NetworkError بگیرید که timeout? آن true است. هر StandardError دیگری، مانند Errno::ECONNREFUSED، به یک NetworkError تبدیل می‌شود که timeout? آن false است.
• —NameError، TypeError و ArgumentError که درون آداپتور raise شوند، باگ‌های خود آداپتور به حساب می‌آیند. بی‌تغییر raise می‌شوند و هرگز دوباره تلاش نمی‌شوند.