valid_email_checker 0.1.0

data/ext/valid_email_checker/vendor/check-if-email-exists/src/util/input_output.rs

@@ -0,0 +1,353 @@
+// check-if-email-exists
+// Copyright (C) 2018-2023 Reacher
+
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as published
+// by the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU Affero General Public License for more details.
+
+// You should have received a copy of the GNU Affero General Public License
+// along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+use crate::misc::{MiscDetails, MiscError};
+use crate::mx::{MxDetails, MxError};
+use crate::smtp::verif_method::VerifMethod;
+use crate::smtp::{SmtpDebug, SmtpDetails, SmtpError, SmtpErrorDesc};
+use crate::syntax::SyntaxDetails;
+use crate::util::ser_with_display::ser_with_display;
+use async_smtp::EmailAddress as AsyncSmtpEmailAddress;
+use chrono::{DateTime, Utc};
+use derive_builder::Builder;
+use serde::{ser::SerializeMap, Deserialize, Serialize, Serializer};
+use std::fmt::Display;
+use std::str::FromStr;
+use std::time::{Duration, SystemTime};
+
+/// Wrapper around the `EmailAddress` from `async_smtp` to allow for
+/// serialization and deserialization.
+#[derive(Debug, Eq, PartialEq, Clone)]
+pub struct EmailAddress(AsyncSmtpEmailAddress);
+
+impl Serialize for EmailAddress {
+	fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
+	where
+		S: Serializer,
+	{
+		ser_with_display(&self.0, serializer)
+	}
+}
+
+impl<'de> Deserialize<'de> for EmailAddress {
+	fn deserialize<D>(deserializer: D) -> Result<EmailAddress, D::Error>
+	where
+		D: serde::Deserializer<'de>,
+	{
+		let s = String::deserialize(deserializer)?;
+		Ok(EmailAddress(
+			AsyncSmtpEmailAddress::from_str(&s).map_err(serde::de::Error::custom)?,
+		))
+	}
+}
+
+impl Display for EmailAddress {
+	fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+		self.0.fmt(f)
+	}
+}
+
+impl FromStr for EmailAddress {
+	type Err = anyhow::Error;
+
+	fn from_str(s: &str) -> Result<Self, Self::Err> {
+		Ok(EmailAddress(AsyncSmtpEmailAddress::from_str(s)?))
+	}
+}
+
+impl EmailAddress {
+	pub fn new(email: String) -> Result<Self, anyhow::Error> {
+		Ok(EmailAddress(AsyncSmtpEmailAddress::new(email)?))
+	}
+
+	pub fn into_inner(self) -> AsyncSmtpEmailAddress {
+		self.0
+	}
+}
+
+impl AsRef<AsyncSmtpEmailAddress> for EmailAddress {
+	fn as_ref(&self) -> &AsyncSmtpEmailAddress {
+		&self.0
+	}
+}
+
+impl AsRef<str> for EmailAddress {
+	fn as_ref(&self) -> &str {
+		self.0.as_ref()
+	}
+}
+
+/// Perform the email verification via a specified proxy. The usage of a proxy
+/// is optional.
+#[derive(Debug, Default, Clone, Deserialize, PartialEq, Serialize)]
+pub struct CheckEmailInputProxy {
+	/// Use the specified SOCKS5 proxy host to perform email verification.
+	pub host: String,
+	/// Use the specified SOCKS5 proxy port to perform email verification.
+	pub port: u16,
+	/// Username to pass to proxy authentication.
+	pub username: Option<String>,
+	/// Password to pass to proxy authentication.
+	pub password: Option<String>,
+	/// The timeout for the connection to the proxy, in ms.
+	pub timeout_ms: Option<u64>,
+}
+
+/// Builder pattern for the input argument into the main `email_exists`
+/// function.
+#[derive(Builder, Debug, Clone, Deserialize, Serialize)]
+#[builder(default)]
+pub struct CheckEmailInput {
+	/// The email to validate.
+	pub to_email: String,
+
+	pub verif_method: VerifMethod,
+
+	/// Whether to check if a gravatar image is existing for the given email.
+	/// Adds a bit of latency to the verification process.
+	///
+	/// Defaults to false.
+	pub check_gravatar: bool,
+	/// Check if a the email address is present in HaveIBeenPwned API.
+	/// If the api_key is filled, HaveIBeenPwned API is checked
+	pub haveibeenpwned_api_key: Option<String>,
+
+	/// The WebDriver address to use for headless verifications.
+	///
+	/// Defaults to http://localhost:9515.
+	pub webdriver_addr: String,
+	/// The WebDriver configuration to use for headless verifications.
+	///
+	/// Defaults to the default WebdriverConfig.
+	pub webdriver_config: WebdriverConfig,
+	/// Identifier for the service currently running Reacher. We recommend
+	/// setting this to an unique identifier of the server where Reacher is
+	/// installed on.
+	///
+	/// Defaults to "backend-dev".
+	pub backend_name: String,
+	/// Sentry DSN to send errors to Sentry.
+	///
+	/// Defaults to None.
+	pub sentry_dsn: Option<String>,
+}
+
+impl Default for CheckEmailInput {
+	fn default() -> Self {
+		CheckEmailInput {
+			to_email: "".into(),
+			verif_method: VerifMethod::default(),
+			check_gravatar: false,
+			haveibeenpwned_api_key: None,
+			webdriver_addr: "http://localhost:9515".into(),
+			webdriver_config: WebdriverConfig::default(),
+			backend_name: "backend-dev".into(),
+			sentry_dsn: None,
+		}
+	}
+}
+
+/// An enum to describe how confident we are that the recipient address is
+/// real.
+#[derive(Debug, Clone, Eq, PartialEq, Deserialize, Serialize)]
+#[serde(rename_all = "lowercase")]
+pub enum Reachable {
+	/// The email is safe to send.
+	Safe,
+	/// The email address appears to exist, but has quality issues that may
+	/// result in low engagement or a bounce. Emails are classified as risky
+	/// when one of the following happens:
+	/// - catch-all email,
+	/// - disposable email,
+	/// - role-based address,
+	/// - full inbox.
+	Risky,
+	/// Emails that don't exist or are syntactically incorrect. Do not send to
+	/// these emails.
+	Invalid,
+	/// We're unable to get a valid response from the recipient's email server.
+	Unknown,
+}
+
+/// Details about the email verification used for debugging.
+#[derive(Debug, Deserialize, Serialize)]
+pub struct DebugDetails {
+	/// Identifier for the service currently running Reacher.
+	pub backend_name: String,
+	/// The time when the email verification started.
+	pub start_time: DateTime<Utc>,
+	/// The time when the email verification ended.
+	pub end_time: DateTime<Utc>,
+	/// The duration of the email verification.
+	pub duration: Duration,
+	/// Details about the email verification used for debugging.
+	pub smtp: SmtpDebug,
+}
+
+impl Default for DebugDetails {
+	fn default() -> Self {
+		Self {
+			start_time: SystemTime::now().into(),
+			end_time: SystemTime::now().into(),
+			duration: Duration::default(),
+			smtp: SmtpDebug::default(),
+			backend_name: "backend-dev".into(),
+		}
+	}
+}
+
+/// The result of the [check_email](check_email) function.
+#[derive(Debug)]
+pub struct CheckEmailOutput {
+	/// Input by the user.
+	pub input: String,
+	pub is_reachable: Reachable,
+	/// Misc details about the email address.
+	pub misc: Result<MiscDetails, MiscError>,
+	/// Details about the MX host.
+	pub mx: Result<MxDetails, MxError>,
+	/// Details about the SMTP responses of the email.
+	pub smtp: Result<SmtpDetails, SmtpError>,
+	/// Details about the email address.
+	pub syntax: SyntaxDetails,
+	/// Details about the email verification used for debugging.
+	pub debug: DebugDetails,
+}
+
+impl Default for CheckEmailOutput {
+	fn default() -> Self {
+		CheckEmailOutput {
+			input: String::default(),
+			is_reachable: Reachable::Unknown,
+			misc: Ok(MiscDetails::default()),
+			mx: Ok(MxDetails::default()),
+			smtp: Ok(SmtpDetails::default()),
+			syntax: SyntaxDetails::default(),
+			debug: DebugDetails::default(),
+		}
+	}
+}
+
+// Implement a custom serialize.
+impl Serialize for CheckEmailOutput {
+	fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
+	where
+		S: Serializer,
+	{
+		// This is just used internally to get the nested error field.
+		#[derive(Serialize)]
+		struct MyError<E> {
+			error: E,
+			// We add an optional "description" field when relevant, given by
+			// the `get_description` on SmtpError.
+			#[serde(skip_serializing_if = "Option::is_none")]
+			description: Option<SmtpErrorDesc>,
+		}
+
+		let mut map = serializer.serialize_map(Some(1))?;
+		map.serialize_entry("input", &self.input)?;
+		map.serialize_entry("is_reachable", &self.is_reachable)?;
+		match &self.misc {
+			Ok(t) => map.serialize_entry("misc", &t)?,
+			Err(error) => map.serialize_entry(
+				"misc",
+				&MyError {
+					error,
+					description: None,
+				},
+			)?,
+		}
+		match &self.mx {
+			Ok(t) => map.serialize_entry("mx", &t)?,
+			Err(error) => map.serialize_entry(
+				"mx",
+				&MyError {
+					error,
+					description: None,
+				},
+			)?,
+		}
+		match &self.smtp {
+			Ok(t) => map.serialize_entry("smtp", &t)?,
+			Err(error) => map.serialize_entry(
+				"smtp",
+				&MyError {
+					error,
+					description: error.get_description(),
+				},
+			)?,
+		}
+		map.serialize_entry("syntax", &self.syntax)?;
+		map.serialize_entry("debug", &self.debug)?;
+		map.end()
+	}
+}
+
+#[derive(Builder, Clone, Debug, Deserialize, Serialize, Default)]
+pub struct WebdriverConfig {
+	pub binary: Option<String>,
+}
+
+#[cfg(test)]
+mod tests {
+	use super::{CheckEmailOutput, DebugDetails};
+	use async_smtp::response::{Category, Code, Detail, Response, Severity};
+
+	#[test]
+	fn should_serialize_correctly() {
+		// create a dummy CheckEmailOutput, with a given message as a transient
+		// SMTP error.
+		fn dummy_response_with_message(m: &str) -> CheckEmailOutput {
+			let r = Response::new(
+				Code {
+					severity: Severity::TransientNegativeCompletion,
+					category: Category::MailSystem,
+					detail: Detail::Zero,
+				},
+				vec![m.to_string(), "8BITMIME".to_string(), "SIZE 42".to_string()],
+			);
+
+			CheckEmailOutput {
+				input: "foo".to_string(),
+				is_reachable: super::Reachable::Unknown,
+				misc: Ok(super::MiscDetails::default()),
+				mx: Ok(super::MxDetails::default()),
+				syntax: super::SyntaxDetails::default(),
+				smtp: Err(super::SmtpError::AsyncSmtpError(r.into())),
+				debug: DebugDetails::default(),
+			}
+		}
+
+		let res = dummy_response_with_message("blacklist");
+		let actual = serde_json::to_string(&res).unwrap();
+		// Make sure the `description` is present with IpBlacklisted.
+		let expected = r#""smtp":{"error":{"type":"AsyncSmtpError","message":"transient: blacklist; 8BITMIME; SIZE 42"},"description":"IpBlacklisted"}"#;
+		assert!(actual.contains(expected));
+
+		let res =
+			dummy_response_with_message("Client host rejected: cannot find your reverse hostname");
+		let actual = serde_json::to_string(&res).unwrap();
+		// Make sure the `description` is present with NeedsRDNs.
+		let expected = r#"smtp":{"error":{"type":"AsyncSmtpError","message":"transient: Client host rejected: cannot find your reverse hostname; 8BITMIME; SIZE 42"},"description":"NeedsRDNS"}"#;
+		assert!(actual.contains(expected));
+
+		let res = dummy_response_with_message("foobar");
+		let actual = serde_json::to_string(&res).unwrap();
+		// Make sure the `description` is NOT present.
+		let expected = r#""smtp":{"error":{"type":"AsyncSmtpError","message":"transient: foobar; 8BITMIME; SIZE 42"}}"#;
+		assert!(actual.contains(expected));
+	}
+}

data/ext/valid_email_checker/vendor/check-if-email-exists/src/util/mod.rs

@@ -0,0 +1,20 @@
+// check-if-email-exists
+// Copyright (C) 2018-2023 Reacher
+
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as published
+// by the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU Affero General Public License for more details.
+
+// You should have received a copy of the GNU Affero General Public License
+// along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+pub mod input_output;
+#[cfg(feature = "sentry")]
+pub mod sentry;
+pub mod ser_with_display;

data/ext/valid_email_checker/vendor/check-if-email-exists/src/util/sentry.rs

@@ -0,0 +1,173 @@
+// Reacher - Email Verification
+// Copyright (C) 2018-2023 Reacher
+
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as published
+// by the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU Affero General Public License for more details.
+
+// You should have received a copy of the GNU Affero General Public License
+// along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+//! Helper functions to send events to Sentry.
+//!
+//! This module also contains functions that check if the error's given by
+//! `check-if-email-exists` are known errors, in which case we don't log them
+//! to Sentry.
+
+use crate::misc::MiscError;
+use crate::mx::MxError;
+use crate::LOG_TARGET;
+use crate::{smtp::SmtpError, CheckEmailOutput};
+use async_smtp::error::Error as AsyncSmtpError;
+use sentry::protocol::{Event, Exception, Level, Values};
+use thiserror::Error;
+use tracing::{debug, info};
+
+const CARGO_PKG_VERSION: &str = env!("CARGO_PKG_VERSION");
+
+/// Setup Sentry.
+pub fn setup_sentry(sentry_dsn: &str) -> sentry::ClientInitGuard {
+	// Use an empty string if we don't have any env variable for sentry. Sentry
+	// will just silently ignore.
+	let sentry = sentry::init(sentry_dsn);
+	if sentry.is_enabled() {
+		info!(target: LOG_TARGET, "Sentry is successfully set up.")
+	}
+
+	sentry
+}
+
+#[derive(Debug, Error)]
+enum SentryError<'a> {
+	#[error("MiscError: {0}")]
+	Misc(&'a MiscError),
+	#[error("MxError: {0}")]
+	Mx(&'a MxError),
+	#[error("SmtpError: {0}")]
+	Smtp(&'a SmtpError),
+}
+
+impl<'a> SentryError<'a> {
+	/// Get the error type to be passed into Sentry's Exception `ty` field.
+	fn get_exception_type(&self) -> String {
+		match self {
+			SentryError::Misc(_) => "MiscError".into(),
+			SentryError::Mx(_) => "MxError".into(),
+			SentryError::Smtp(_) => "SmtpError".into(),
+		}
+	}
+}
+
+/// Helper function to send an Error event to Sentry. We redact all sensitive
+/// info before sending to Sentry, by removing all instances of `username`.
+fn error(err: SentryError, result: &CheckEmailOutput, backend_name: &str) {
+	let exception_value = redact(format!("{err:?}").as_str(), &result.syntax.username);
+	debug!(target: LOG_TARGET, "Sending error to Sentry: {}", exception_value);
+
+	let exception = Exception {
+		ty: err.get_exception_type(),
+		value: Some(exception_value),
+		..Default::default()
+	};
+
+	sentry::capture_event(Event {
+		exception: Values {
+			values: vec![exception],
+		},
+		level: Level::Error,
+		environment: Some("production".into()),
+		release: Some(format!("v{}", CARGO_PKG_VERSION).into()),
+		message: Some(format!("{result:#?}")),
+		server_name: Some(backend_name.to_string().into()),
+		transaction: Some(format!("check_email:{}", result.syntax.domain)),
+		..Default::default()
+	});
+}
+
+/// Function to replace all usernames from email, and replace them with
+/// `***@domain.com` for privacy reasons.
+fn redact(input: &str, username: &str) -> String {
+	input.replace(username, "***")
+}
+
+/// Check if the message contains known SMTP Transient errors.
+fn skip_smtp_transient_errors(message: &[String]) -> bool {
+	let first_line = message[0].to_lowercase();
+
+	// 4.3.2 Please try again later
+	first_line.contains("try again") ||
+	// Temporary local problem - please try later
+	first_line.contains("try later")
+}
+
+/// Checks if the output from `check-if-email-exists` has a known error, in
+/// which case we don't log to Sentry to avoid spamming it.
+pub fn log_unknown_errors(result: &CheckEmailOutput, backend_name: &str) {
+	match (&result.misc, &result.mx, &result.smtp) {
+		(Err(err), _, _) => {
+			// We log all misc errors.
+			error(SentryError::Misc(err), result, backend_name);
+		}
+		(_, Err(err), _) => {
+			// We log all mx errors.
+			error(SentryError::Mx(err), result, backend_name);
+		}
+		(_, _, Err(err)) if err.get_description().is_some() => {
+			// If the SMTP error is known, we don't track it in Sentry.
+		}
+		(_, _, Err(SmtpError::AsyncSmtpError(AsyncSmtpError::Transient(response))))
+			if skip_smtp_transient_errors(&response.message) =>
+		{
+			// If the SMTP error is transient and known, we don't track it in
+			// Sentry, just log it locally.
+			debug!(target: LOG_TARGET,
+				"Transient error: {}",
+				redact(
+					response.message[0].as_str(),
+					result.syntax.username.as_str()
+				)
+			);
+		}
+		(_, _, Err(err)) => {
+			// If it's a SMTP error we didn't catch above, we log to
+			// Sentry, to be able to debug them better. We don't want to
+			// spam Sentry and log all instances of the error, hence the
+			// `count` check.
+			error(SentryError::Smtp(err), result, backend_name);
+		}
+		// If everything is ok, we just return the result.
+		(Ok(_), Ok(_), Ok(_)) => {}
+	}
+}
+
+#[cfg(test)]
+mod tests {
+	use super::redact;
+
+	#[test]
+	fn test_redact() {
+		assert_eq!("***@gmail.com", redact("someone@gmail.com", "someone"));
+		assert_eq!(
+			"my email is ***@gmail.com.",
+			redact("my email is someone@gmail.com.", "someone")
+		);
+		assert_eq!(
+			"my email is ***@gmail.com., I repeat, my email is ***@gmail.com.",
+			redact(
+				"my email is someone@gmail.com., I repeat, my email is someone@gmail.com.",
+				"someone"
+			)
+		);
+		assert_eq!(
+			"*** @ gmail . com",
+			redact("someone @ gmail . com", "someone")
+		);
+		assert_eq!("*** is here.", redact("someone is here.", "someone"));
+	}
+}

data/ext/valid_email_checker/vendor/check-if-email-exists/src/util/ser_with_display.rs

@@ -0,0 +1,28 @@
+// check-if-email-exists
+// Copyright (C) 2018-2023 Reacher
+
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as published
+// by the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU Affero General Public License for more details.
+
+// You should have received a copy of the GNU Affero General Public License
+// along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+use serde::Serializer;
+use std::fmt::Display;
+
+/// Implement the `Serialize` trait for types that are `Display`.
+/// https://stackoverflow.com/questions/58103801/serialize-using-the-display-trait
+pub fn ser_with_display<T, S>(value: &T, serializer: S) -> Result<S::Ok, S::Error>
+where
+	T: Display,
+	S: Serializer,
+{
+	serializer.collect_str(value)
+}