Adapter nhà cung cấp

Adapter nhà cung cấp email là phần mã làm việc với một nhà cung cấp gửi thư: nó gửi thư, xác minh và chuẩn hóa webhook của nhà cung cấp, và khai báo những gì nhà cung cấp làm được. Lõi của ReputeCast không bao giờ gọi trực tiếp một nhà cung cấp. ReputeCast tìm adapter trong một sổ đăng ký và dùng chúng qua cùng một hợp đồng, nên định tuyến, chuyển dự phòng, Độ sẵn sàng gửi, tự động tạm dừng và danh sách chặn gửi dùng chung hoạt động như nhau với mọi nhà cung cấp.

Cách adapter hoạt động

1. Đăng ký. Mỗi adapter đăng ký dưới một khóa, kèm một descriptor: tên, khả năng, điều khoản của nhà cung cấp và biểu mẫu kết nối. Adapter có sẵn dùng khóa ngắn (ses, postmark); adapter được cài thêm dùng community:<id>. Mọi tiến trình ReputeCast đọc lại danh sách adapter đã cài sau mỗi 15 giây.
2. Danh mục. Danh mục thiết lập, trình hướng dẫn kết nối và Nhà cung cấp gửi thư › , rồi Adapter đều đọc từ sổ đăng ký, nên một adapter mới xuất hiện ở cả ba nơi.
3. Kết nối. Quản trị viên không gian làm việc kết nối một nhà cung cấp qua adapter từ Nhà cung cấp gửi thư › , rồi Thêm nhà cung cấp. Thông tin xác thực được niêm phong khi lưu trữ và không bao giờ được trả về.
4. Gửi. Bộ máy gửi kết xuất và cá nhân hóa từng thư, rồi chuyển cho adapter mỗi lần tối đa bằng kích thước lô của adapter. Adapter trả về một kết quả cho mỗi thư.
5. Sự kiện. Nhà cung cấp gửi webhook đến /hooks/<adapter key>/<token>. ReputeCast xác minh từng yêu cầu qua adapter trước khi lưu, rồi adapter ánh xạ yêu cầu đó thành sự kiện chuẩn hóa. Các trường hợp trả thư vĩnh viễn và khiếu nại được đưa vào danh sách chặn gửi dùng chung.
6. Tình trạng. Tác vụ kiểm tra tình trạng kiểm tra thông tin xác thực hoặc hạn mức của từng nhà cung cấp qua adapter. Lỗi lặp lại sẽ đánh dấu nhà cung cấp là gián đoạn, và định tuyến chuyển dự phòng theo từng luồng (xem tình trạng nhà cung cấp và sự cố).

Ba loại adapter

Loại	Chạy dưới dạng	Do ai viết	Khóa trong sổ đăng ký	Cài đặt bằng
Có sẵn	Mã Go bên trong tệp nhị phân ReputeCast, được kiểm thử bằng bộ kiểm thử hợp đồng dùng chung	HostRepute và những người đóng góp, phát hành cùng ReputeCast	ses, postmark, mailgun, …	Mỗi bản phát hành
HTTP chung	Một ánh xạ JSON tới API HTTP của một nhà cung cấp, chạy bên trong tệp nhị phân	Bất kỳ quản trị viên hệ thống nào, không cần viết mã	httpgeneric, hoặc community:<name> sau khi lưu	Biểu mẫu trên tab Adapter, hoặc một manifest loại http
Cộng đồng	Tiến trình riêng, viết bằng bất kỳ ngôn ngữ nào (TypeScript với SDK)	Bất kỳ ai	community:<id>	reputecast adapter install, hoặc Cài từ kho adapter

Có adapter sẵn cho Amazon SES, Postmark, Postal, Mailgun, SendGrid, Resend, SparkPost, Mailjet, Brevo, Azure Communication Services và mọi máy chủ SMTP; chọn nhà cung cấp gửi thư so sánh các adapter này. Mỗi adapter cộng đồng đã cài hiển thị phiên bản, người duy trì, các khả năng mà manifest của nó khai báo và trạng thái cập nhật. Adapter nào không có bản phát hành mới trong một năm sẽ bị đánh dấu Ngừng duy trì và không còn được đề xuất cho kết nối mới.

Adapter khai báo những gì

Mỗi adapter nêu rõ nhà cung cấp làm được gì. Các khai báo này trở thành các huy hiệu trong danh mục và trên màn hình định tuyến:

• Điều khoản tiếp thị hàng loạt: được phép, chỉ luồng Broadcast, không được phép, hoặc “theo chính sách của bạn” cho máy chủ tự triển khai và API được ánh xạ. Định tuyến và Độ sẵn sàng gửi dùng các điều khoản này.
• Webhook: nhà cung cấp có báo về các lần gửi thành công, thư trả lại và khiếu nại hay không. Không có webhook, ReputeCast không nhận được thư trả lại hay khiếu nại nào từ nhà cung cấp đó (SMTP chung đọc hộp thư nhận thư trả lại để thay thế).
• Thiết lập tên miền: qua API của nhà cung cấp, hoặc bằng bản ghi DNS thêm thủ công.
• Đồng bộ danh sách chặn gửi: hai chiều, chỉ kéo về, hoặc chỉ cục bộ. Với chỉ cục bộ, ReputeCast tự áp dụng danh sách chặn gửi dùng chung trước khi gửi.
• Kích thước lô: số thư riêng biệt đi trong một lệnh gọi API.
• Sandbox, khả năng tự phát hiện hạn mức và tốc độ, IP riêng và giá, cùng việc nhà cung cấp có theo dõi lượt mở và lượt nhấp theo mặc định hay không.

Chọn adapter

• Đã có adapter sẵn cho nhà cung cấp của bạn: hãy dùng adapter đó. Adapter có sẵn bao quát các API tên miền, webhook và danh sách chặn gửi của nhà cung cấp nếu có, và được kiểm thử ở mỗi bản phát hành.
• Nhà cung cấp nhận một yêu cầu HTTP cho mỗi thư và gửi webhook JSON có chữ ký HMAC, Standard Webhooks, basic auth hoặc một header chứa khóa bí mật: hãy ánh xạ nhà cung cấp bằng adapter HTTP chung. Một ánh xạ gửi một thư cho mỗi yêu cầu, dùng DNS thủ công và danh sách chặn gửi chỉ cục bộ, và không tự phát hiện hạn mức. Hướng dẫn thao tác nằm ở kết nối bất kỳ API email HTTP nào.
• Bạn cần gửi theo lô, API tên miền, đồng bộ danh sách chặn gửi, tự phát hiện hạn mức, bắt tay khi đăng ký (subscription handshake) hoặc logic mà ánh xạ không diễn đạt được: viết một adapter cộng đồng. Adapter này chạy trong tiến trình riêng, chỉ kết nối tới các host mà manifest khai báo, và giao tiếp với ReputeCast qua giao thức adapter có ký.
• Nhà cung cấp nên đi kèm ReputeCast cho mọi người: đóng góp một adapter có sẵn bằng Go.

Ai làm gì

• Tác giả adapter viết adapter và phát hành image cùng manifest.json.
• Người vận hành máy chủ ReputeCast chạy tiến trình adapter và cho ReputeCast biết tiến trình đó lắng nghe ở đâu, kèm khóa bí mật để ký.
• Quản trị viên hệ thống cài adapter. Adapter đã cài áp dụng cho mọi không gian làm việc, nên chỉ quản trị viên hệ thống mới cài, cập nhật hoặc gỡ được adapter.
• Quản trị viên không gian làm việc có quyền providers:manage kết nối một nhà cung cấp qua adapter đó, như với mọi adapter có sẵn.

Mặc định và giới hạn

Các giới hạn sau áp dụng cho adapter cộng đồng chạy trong tiến trình riêng:

Thiết lập	Mặc định	Cách thay đổi
Độ lệch đồng hồ cho phép với yêu cầu và phản hồi đã ký	5 minutes (300 s)	Cố định
Khóa bí mật ký trước đó vẫn hoạt động sau reputecast adapter secret	24 hours	Cố định
Cơ chế ngắt mạch (circuit breaker)	Opens after 5 failures in a row; pauses 30 s, doubling up to 5 minutes while probes fail	Cố định
Số lệnh gọi đồng thời mỗi adapter	64	Cố định
Thời gian chờ của từng thao tác	health 5 s, verify 20 s, send 30 s, webhooks/verify 5 s, webhooks/parse 15 s, webhooks/register 30 s, domains 30 s, quota 20 s, suppressions 60 s	Cố định
Số thư mỗi lệnh gọi gửi	1 unless the manifest declares 1–1,000	capabilities.batch trong manifest.json
manifest.json lớn nhất	256 KiB	Cố định
Mọi tiến trình đọc lại các adapter đã cài	Every 15 s	Cố định
SDK adapter ghi nhớ phản hồi thành công theo từng khóa idempotency	15 minutes	serve({ idempotencyTtlMs })
Adapter bị đánh dấu ngừng duy trì	365 days after its manifest's last release; hidden from new connections	Cố định

Khi nào nên thay đổi

• Khai báo capabilities.batch (từ 1 đến 1.000) trong manifest khi API của nhà cung cấp nhận nhiều thư riêng biệt, đã cá nhân hóa trong cùng một lệnh gọi.
• Chỉ bật providers.allow_private_networks khi một tiến trình adapter hoặc một API được ánh xạ chạy trên địa chỉ loopback hoặc địa chỉ riêng, chẳng hạn một container sidecar. Địa chỉ link-local và địa chỉ metadata của đám mây vẫn bị từ chối.
• SDK ghi nhớ các câu trả lời thành công trong 15 phút (serve({ idempotencyTtlMs })). Giao thức yêu cầu tối thiểu 15 phút, nên đừng giảm giá trị này.

Mọi giới hạn khác đều cố định.

Liên quan

• Tham chiếu adapter HTTP chung liệt kê mọi trường của một ánh xạ.
• Viết adapter cộng đồng xây dựng, kiểm thử và cài một adapter từ mẫu.
• Giao thức adapter v1 là tài liệu tham chiếu đường truyền cho adapter cộng đồng.
• Đóng góp adapter có sẵn trình bày hợp đồng Go và bộ kiểm thử hợp đồng.
• Dịch vụ được hỗ trợ liệt kê mọi nhà cung cấp mà ReputeCast làm việc cùng.