Pisahkan kedua saluran pipa sebelum mendiagnosis kegagalan
Aplikasi dapat berhenti menyerap peristiwa penyedia sementara penyedia terus mengirimkan email. Itu juga dapat menerima lalu lintas acara yang sehat tentang pesan yang gagal terkirim. Ini adalah jalur pipa yang berbeda dengan kriteria keberhasilan yang berbeda. Jalur email berjalan dari pengiriman melalui penyedia pengirim ke sistem penerima. Jalur data dijalankan dari observasi penyedia melalui API atau webhook ke penyimpanan, transformasi, dan dasbor. Dasbor kosong tidak dapat mengidentifikasi jalur mana yang gagal tanpa bukti tambahan.
Referensi Webhook Acara Twilio SendGrid membedakan peristiwa yang diproses, disampaikan, ditangguhkan, dan dibatalkan. Istilah-istilah tersebut menjelaskan penanganan pesan khusus penyedia. Itu bukan status untuk database penyerapan pelanggan. Naskah ini menggunakan semantik yang terdokumentasi sebagai contoh dan mengusulkan kontrak integrasi; itu tidak mengklaim bahwa EmailAuth memiliki konektor tertentu atau bahwa peristiwa nyata apa pun telah diterima, disimpan, atau hilang.
Definisikan setiap kondisi keberhasilan secara eksplisit
Catat pos pemeriksaan terpisah untuk penerimaan pengiriman, penanganan pesan penyedia, ketersediaan webhook atau API, pengakuan penyerapan, penyimpanan tahan lama, transformasi, dan tampilan. Masing-masing membutuhkan sumber bukti dan stempel waktu. Respons HTTP yang berhasil pada webhook dapat menunjukkan bahwa titik akhir menyetujui permintaan tersebut, namun hal ini tidak dengan sendirinya membuktikan bahwa aplikasi mempertahankan setiap peristiwa dengan benar. Sebaliknya, baris database mungkin sudah lama atau terduplikasi dan tidak boleh dianggap sebagai bukti konektivitas saat ini.
Untuk contoh SendGrid , diproses berarti SendGrid diterima dan dapat mengirimkan pesan; terkirim berarti berhasil mengirimkan pesan ke server penerima. Tidak ada pernyataan yang menjanjikan penempatan kotak masuk atau pembacaan manusia. Ditangguhkan berarti server penerima menolak pesan tersebut untuk sementara. Simpan makna-makna ini dalam kamus data daripada menerjemahkan setiap peristiwa positif menjadi tanda keberhasilan yang umum. Integrasi ini harus mempertahankan jenis peristiwa penyedia asli beserta interpretasi internalnya.
Sematkan API dan kontrak acara
Identifikasi penyedia sebenarnya, format titik akhir atau webhook, versi terdokumentasi jika tersedia, tanggal snapshot skema, dan bidang tempat aplikasi bergantung. Jika penyedia tidak mengekspos versi formal untuk payload webhook, sampaikan demikian dan simpan cuplikan kontrak bertanggal alih-alih membuat nomor versi. Catat bidang wajib dan opsional, unit stempel waktu, pengidentifikasi peristiwa, pengikatan penyewa, dan perilaku untuk jenis peristiwa yang tidak diketahui.
Pagination termasuk dalam kontrak hanya untuk API yang benar-benar mendukung pengambilan paginasi. Batch webhook tidak secara otomatis merupakan respons API yang diberi nomor halaman. Jika konektor menggunakan kedua metode tersebut, dokumentasikan keduanya secara terpisah. Tentukan persistensi kursor, perilaku halaman terminal, dan penanganan sebagian halaman dari dokumentasi API sebenarnya sebelum implementasi. Draf ini tidak menegaskan skema penomoran halaman SendGrid dari sumber webhook, dan belum memanggil API untuk menemukannya.
Perlakukan perilaku coba ulang sebagai perilaku khusus penyedia
Dokumentasi webhook awal SendGrid menyatakan bahwa respons non-2xx menyebabkan percobaan ulang dengan interval yang meningkat hingga 24 jam setelah peristiwa terjadi. Ini menggambarkan batas tersebut sebagai bergulir, sehingga peristiwa baru yang gagal menerima periode percobaan ulangnya sendiri. Ini adalah perilaku SendGrid yang terdokumentasi, bukan jaminan universal bahwa penyedia lain akan mencoba lagi dalam durasi yang sama atau bahwa aplikasi dapat memulihkan setiap peristiwa yang terlewat tanpa batas waktu.
Desain penyerapan harus mengasumsikan bahwa pengulangan terkait percobaan ulang dimungkinkan dan menentukan strategi pemrosesan idempoten menggunakan pengidentifikasi yang didukung oleh kontrak sebenarnya. Jangan berasumsi pengiriman tepat satu kali dari pengakuan HTTP. Pertahankan sumber non-rahasia yang cukup untuk membedakan peristiwa yang berulang dari peristiwa berbeda mengenai pesan yang sama. Pengidentifikasi pesan saja mungkin tidak secara unik mengidentifikasi setiap peristiwa siklus hidup, sehingga kunci deduplikasi harus cocok dengan bidang yang didokumentasikan penyedia dan model penyimpanan aplikasi.
Jadikan kegagalan sebagian terlihat
Sebuah batch mungkin berisi beberapa peristiwa sementara hanya sebagian dari pemrosesan aplikasi yang berhasil. Tentukan apakah pengakuan terjadi sebelum atau setelah penerimaan tahan lama, bagaimana item yang gagal disimpan untuk diputar ulang secara resmi, dan bagaimana sistem mencegah pemrosesan berulang agar tidak menggelembungkan total. Ini adalah keputusan desain yang diusulkan, bukan klaim bahwa penyedia atau EmailAuth mengimplementasikan model transaksi tertentu. Tinjau batasan kegagalan aplikasi sebenarnya sebelum memilih kebijakan.
Pisahkan penolakan skema, kegagalan pemetaan penyewa, kegagalan penyimpanan, dan kegagalan agregasi hilir. Mereka membutuhkan remediasi yang berbeda. Peristiwa yang tidak dapat ditetapkan dengan aman ke penyewa tidak boleh ditempatkan dalam kumpulan data pelanggan default hanya untuk menjaga agar penyerapan tetap berjalan. Bidang opsional yang tidak diketahui seharusnya tidak secara otomatis membuat pesan yang valid tampak tidak terkirim. Pertahankan catatan kesalahan terkontrol dengan data minimal yang diperlukan, hindari rincian penerima atau kredensial dalam log operasional yang luas.
Lembar kerja kontrak dan perlengkapan
Buat lembar kerja dengan sumber penyedia, versi kontrak atau tanggal snapshot, tipe titik akhir, referensi metode autentikasi, pengikatan penyewa, identitas peristiwa, semantik stempel waktu, dan perilaku pengakuan yang diharapkan. Tambahkan perlengkapan untuk acara duplikat, pengamatan yang tidak berurutan, jenis yang tidak diketahui, bidang wajib yang hilang, kegagalan pemrosesan sebagian, dan pemulihan. Untuk API dengan penomoran halaman yang didukung, tambahkan halaman kosong, kursor berulang, dan pengambilan terputus. Tandai penomoran halaman tidak berlaku jika konektor hanya untuk webhook.
Setiap perlengkapan harus menyatakan baris tersimpan yang diharapkan, hasil deduplikasi, catatan kesalahan, dan efek dasbor. Gunakan penerima dan penyewa sintetis, dan nonaktifkan pengiriman jaringan kecuali diizinkan secara terpisah. Jangan memasukkan hasil keberhasilan yang dibuat-buat ke dalam lembar kerja hanya karena desainnya tampak masuk akal. Katalog memerlukan bukti kontrak dan perlengkapan asli; artikel ini memberikan struktur yang diusulkan dan tidak mengklaim pengujian tersebut telah dilaksanakan.
Diagnosis fiktif: dasbor yang sunyi
Tim operasi fiktif tidak melihat peristiwa pengiriman baru di dasbornya dan menyimpulkan bahwa email keluar telah dihentikan. Bukti sisi penyedianya, jika diperoleh melalui penyelidikan resmi, mungkin menunjukkan pengiriman yang berkelanjutan sementara titik akhir webhook mengembalikan kegagalan. Pertanyaan berikutnya yang benar adalah apakah jalur data sedang mencoba ulang, hilang setelah jendela yang didokumentasikan, atau gagal setelah pengakuan. Dasbor saja tidak dapat menyelesaikan alternatif-alternatif tersebut.
Dalam latihan yang diusulkan, tim akan membandingkan waktu observasi penyedia, respons titik akhir, catatan penyerapan yang tahan lama, dan stempel waktu agregasi. Itu tidak akan mengirim ulang pesan pelanggan hanya untuk membuat dasbor terisi. Skenario ini bersifat fiktif: tidak ada akun penyedia, titik akhir, peristiwa, atau pengiriman yang diperiksa. Hal ini menggambarkan mengapa kepemilikan insiden harus memisahkan pengiriman email dari penyerapan telemetri dan menghindari memperlakukan komponen kesehatan tim mana pun sebagai bukti bahwa keseluruhan saluran berfungsi.
Rekonsiliasi observasi tanpa melebih-lebihkan liputan
RFC 9990 mendefinisikan DMARC pelaporan agregat, sumber observasi terpisah dengan proses pelaporan dan penyampaiannya sendiri. Laporan tersebut dapat membantu menilai pola autentikasi domain, namun tidak memperbaiki webhook yang hilang atau membuktikan kelengkapan telemetri pengiriman penyedia. Jaga agar cakupan, jangka waktu, dan pengidentifikasi setiap sumber tetap terlihat saat menggunakannya bersama-sama.
Kontrak dan perlengkapan API yang disematkan versi yang diperlukan untuk penomoran halaman, duplikat, percobaan ulang, dan kegagalan sebagian tetap terbuka. Tidak ada kredensial yang dibuat, titik akhir dikonfigurasi, atau peristiwa nyata diputar ulang. Tinjauan spesialis manusia, penerapan sumber, jalur produksi, aksesibilitas, dan pelepasan pemilik juga tetap terbuka. Publikasi memerlukan tinjauan kontrak resmi dan hasil perlengkapan yang disimpan dari integrasi sebenarnya, dengan kemampuan yang tidak didukung ditandai dengan jelas daripada disimpulkan dari dokumentasi penyedia lain.