Skip to content

armgit / macro

Public Imported from GitHub
0

Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.

feat(email): hexify gmail client (#5490)

Will Hutchinson65eef90db672
diff --git a/.github/workspace-dep-closures.json b/.github/workspace-dep-closures.json
index 0e2cc0a527..e799d3a780 100644
--- a/.github/workspace-dep-closures.json
+++ b/.github/workspace-dep-closures.json
@@ -2105,6 +2105,17 @@
"crates/unfurl",
"crates/workspace-hack"
],
+ "email_api_client": [
+ "crates/cowlike",
+ "crates/email_api_client",
+ "crates/email_utils",
+ "crates/gmail_client",
+ "crates/macro_user_id",
+ "crates/model-error-response",
+ "crates/models_email",
+ "crates/models_pagination",
+ "crates/workspace-hack"
+ ],
"email_db_client": [
"crates/cowlike",
"crates/email_db_client",
@@ -2286,6 +2297,7 @@
"crates/document_storage_service_client",
"crates/document_sub_type",
"crates/email",
+ "crates/email_api_client",
"crates/email_db_client",
"crates/email_utils",
"crates/entity_access",
diff --git a/.sqlx/query-0cde968437c593137d949d21a4a2165e1f7e99f446be0eaa325d61340b39ab8a.json b/.sqlx/query-0cde968437c593137d949d21a4a2165e1f7e99f446be0eaa325d61340b39ab8a.json
deleted file mode 100644
index 6d70ffff71..0000000000
--- a/.sqlx/query-0cde968437c593137d949d21a4a2165e1f7e99f446be0eaa325d61340b39ab8a.json
+++ /dev/null
@@ -1,38 +0,0 @@
-{
- "db_name": "PostgreSQL",
- "query": "\n SELECT\n outbox.id,\n outbox.backfill_job_id,\n job.link_id AS \"email_link_id!\",\n job.threads_requested_limit IS NULL AS \"priority_pass!\"\n FROM email_backfill_init_outbox outbox\n JOIN email_backfill_jobs job ON job.id = outbox.backfill_job_id\n WHERE outbox.published_at IS NULL\n AND job.status = 'InProgress'\n AND job.initialized_at IS NOT NULL\n ORDER BY outbox.created_at, outbox.id\n FOR UPDATE OF outbox SKIP LOCKED\n LIMIT 1\n ",
- "describe": {
- "columns": [
- {
- "ordinal": 0,
- "name": "id",
- "type_info": "Uuid"
- },
- {
- "ordinal": 1,
- "name": "backfill_job_id",
- "type_info": "Uuid"
- },
- {
- "ordinal": 2,
- "name": "email_link_id!",
- "type_info": "Uuid"
- },
- {
- "ordinal": 3,
- "name": "priority_pass!",
- "type_info": "Bool"
- }
- ],
- "parameters": {
- "Left": []
- },
- "nullable": [
- false,
- false,
- true,
- null
- ]
- },
- "hash": "0cde968437c593137d949d21a4a2165e1f7e99f446be0eaa325d61340b39ab8a"
-}
diff --git a/.sqlx/query-87097a992a2d5274660147d12a865b5717e0acaff30e5361c0d00018eeedece6.json b/.sqlx/query-77de51f18335c68adb05bb94d1c2abf7ea1142c08e0ea56a5b7342de2cd9bfde.json
similarity index 72%
rename from .sqlx/query-87097a992a2d5274660147d12a865b5717e0acaff30e5361c0d00018eeedece6.json
rename to .sqlx/query-77de51f18335c68adb05bb94d1c2abf7ea1142c08e0ea56a5b7342de2cd9bfde.json
index 437242aaa6..41468c2be6 100644
--- a/.sqlx/query-87097a992a2d5274660147d12a865b5717e0acaff30e5361c0d00018eeedece6.json
+++ b/.sqlx/query-77de51f18335c68adb05bb94d1c2abf7ea1142c08e0ea56a5b7342de2cd9bfde.json
@@ -1,6 +1,6 @@
{
"db_name": "PostgreSQL",
- "query": "\n INSERT INTO email_backfill_jobs (id, link_id, fusionauth_user_id, threads_requested_limit, status)\n VALUES ($1, $2, $3, $4, 'Init')\n ON CONFLICT (link_id) WHERE status IN ('Init', 'InProgress') DO NOTHING\n RETURNING\n id,\n link_id,\n fusionauth_user_id,\n threads_requested_limit,\n total_threads,\n threads_retrieved_count,\n status as \"status: db::backfill::BackfillJobStatus\",\n created_at,\n updated_at\n ",
+ "query": "\n INSERT INTO email_backfill_jobs (id, link_id, fusionauth_user_id, threads_requested_limit, status, is_recovery)\n VALUES ($1, $2, $3, $4, 'Init', $5)\n ON CONFLICT (link_id) WHERE status IN ('Init', 'InProgress') DO NOTHING\n RETURNING\n id,\n link_id,\n fusionauth_user_id,\n threads_requested_limit,\n total_threads,\n threads_retrieved_count,\n status as \"status: db::backfill::BackfillJobStatus\",\n created_at,\n updated_at\n ",
"describe": {
"columns": [
{
@@ -67,7 +67,8 @@
"Uuid",
"Uuid",
"Text",
- "Int4"
+ "Int4",
+ "Bool"
]
},
"nullable": [
@@ -82,5 +83,5 @@
false
]
},
- "hash": "87097a992a2d5274660147d12a865b5717e0acaff30e5361c0d00018eeedece6"
+ "hash": "77de51f18335c68adb05bb94d1c2abf7ea1142c08e0ea56a5b7342de2cd9bfde"
}
diff --git a/.sqlx/query-82dfc72e4cb96c08e4dfdf27f13d7c545ca4d89997905a8fae8de3d6f246b5ed.json b/.sqlx/query-82dfc72e4cb96c08e4dfdf27f13d7c545ca4d89997905a8fae8de3d6f246b5ed.json
new file mode 100644
index 0000000000..53fbe21880
--- /dev/null
+++ b/.sqlx/query-82dfc72e4cb96c08e4dfdf27f13d7c545ca4d89997905a8fae8de3d6f246b5ed.json
@@ -0,0 +1,23 @@
+{
+ "db_name": "PostgreSQL",
+ "query": "\n SELECT provider_id AS \"provider_id!\"\n FROM email_messages\n WHERE link_id = $1 AND provider_id = ANY($2)\n ",
+ "describe": {
+ "columns": [
+ {
+ "ordinal": 0,
+ "name": "provider_id!",
+ "type_info": "Text"
+ }
+ ],
+ "parameters": {
+ "Left": [
+ "Uuid",
+ "TextArray"
+ ]
+ },
+ "nullable": [
+ true
+ ]
+ },
+ "hash": "82dfc72e4cb96c08e4dfdf27f13d7c545ca4d89997905a8fae8de3d6f246b5ed"
+}
diff --git a/.sqlx/query-8bc66698f8a3f52a30b893ec5983aed3271d305f6b6df547db530fe34a604f8c.json b/.sqlx/query-8bc66698f8a3f52a30b893ec5983aed3271d305f6b6df547db530fe34a604f8c.json
new file mode 100644
index 0000000000..5a0c927aed
--- /dev/null
+++ b/.sqlx/query-8bc66698f8a3f52a30b893ec5983aed3271d305f6b6df547db530fe34a604f8c.json
@@ -0,0 +1,44 @@
+{
+ "db_name": "PostgreSQL",
+ "query": "\n SELECT\n outbox.id,\n outbox.backfill_job_id,\n job.link_id AS \"email_link_id!\",\n -- Recovery jobs skip the priority pass: the mailbox is already\n -- populated, so there is no cold-start signal to seed.\n (job.threads_requested_limit IS NULL AND NOT job.is_recovery) AS \"priority_pass!\",\n job.is_recovery AS \"refresh_existing!\"\n FROM email_backfill_init_outbox outbox\n JOIN email_backfill_jobs job ON job.id = outbox.backfill_job_id\n WHERE outbox.published_at IS NULL\n AND job.status = 'InProgress'\n AND job.initialized_at IS NOT NULL\n ORDER BY outbox.created_at, outbox.id\n FOR UPDATE OF outbox SKIP LOCKED\n LIMIT 1\n ",
+ "describe": {
+ "columns": [
+ {
+ "ordinal": 0,
+ "name": "id",
+ "type_info": "Uuid"
+ },
+ {
+ "ordinal": 1,
+ "name": "backfill_job_id",
+ "type_info": "Uuid"
+ },
+ {
+ "ordinal": 2,
+ "name": "email_link_id!",
+ "type_info": "Uuid"
+ },
+ {
+ "ordinal": 3,
+ "name": "priority_pass!",
+ "type_info": "Bool"
+ },
+ {
+ "ordinal": 4,
+ "name": "refresh_existing!",
+ "type_info": "Bool"
+ }
+ ],
+ "parameters": {
+ "Left": []
+ },
+ "nullable": [
+ false,
+ false,
+ true,
+ null,
+ false
+ ]
+ },
+ "hash": "8bc66698f8a3f52a30b893ec5983aed3271d305f6b6df547db530fe34a604f8c"
+}
diff --git a/.sqlx/query-fb40c8bb2fd9b7c2777f4b3038a18b9f4ffa685f6810877983169ad815c561a7.json b/.sqlx/query-fb40c8bb2fd9b7c2777f4b3038a18b9f4ffa685f6810877983169ad815c561a7.json
new file mode 100644
index 0000000000..e17b2c8f19
--- /dev/null
+++ b/.sqlx/query-fb40c8bb2fd9b7c2777f4b3038a18b9f4ffa685f6810877983169ad815c561a7.json
@@ -0,0 +1,23 @@
+{
+ "db_name": "PostgreSQL",
+ "query": "\n SELECT EXISTS(\n SELECT 1\n FROM email_messages\n WHERE provider_id = $1 AND link_id = $2\n ) AS \"exists!\"\n ",
+ "describe": {
+ "columns": [
+ {
+ "ordinal": 0,
+ "name": "exists!",
+ "type_info": "Bool"
+ }
+ ],
+ "parameters": {
+ "Left": [
+ "Text",
+ "Uuid"
+ ]
+ },
+ "nullable": [
+ null
+ ]
+ },
+ "hash": "fb40c8bb2fd9b7c2777f4b3038a18b9f4ffa685f6810877983169ad815c561a7"
+}
diff --git a/Cargo.lock b/Cargo.lock
index 59301fe34c..db09cb7ba5 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -693,6 +693,16 @@ dependencies = [
"winnow 0.7.15",
]
+[[package]]
+name = "assert-json-diff"
+version = "2.0.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "47e4f2b81832e72834d7518d8487a0396a28cc408186a2e8854c0f98011faf12"
+dependencies = [
+ "serde",
+ "serde_json",
+]
+
[[package]]
name = "async-channel"
version = "1.9.0"
@@ -3996,6 +4006,24 @@ dependencies = [
"regex",
]
+[[package]]
+name = "deadpool"
+version = "0.12.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0be2b1d1d6ec8d846f05e137292d0b89133caf95ef33695424c09568bdd39b1b"
+dependencies = [
+ "deadpool-runtime",
+ "lazy_static",
+ "num_cpus",
+ "tokio",
+]
+
+[[package]]
+name = "deadpool-runtime"
+version = "0.1.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "092966b41edc516079bdf31ec78a2e0588d1d0c08f78b91d8307215928642b2b"
+
[[package]]
name = "debug-ignore"
version = "1.0.5"
@@ -5033,6 +5061,33 @@ version = "0.2.9"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "e079f19b08ca6239f47f8ba8509c11cf3ea30095831f7fed61441475edd8c449"
+[[package]]
+name = "email_api_client"
+version = "0.1.0"
+dependencies = [
+ "ammonia",
+ "base64 0.22.1",
+ "chrono",
+ "encoding_rs",
+ "gmail_client",
+ "html-escape",
+ "http 1.4.0",
+ "lol_html",
+ "mail-builder",
+ "mailparse",
+ "models_email",
+ "regex",
+ "scraper",
+ "serde",
+ "serde_json",
+ "thiserror 2.0.18",
+ "tokio",
+ "tracing",
+ "uuid",
+ "wiremock",
+ "workspace-hack",
+]
+
[[package]]
name = "email_db_client"
version = "0.1.0"
@@ -5148,6 +5203,7 @@ dependencies = [
"doppler-config",
"ego-tree",
"email",
+ "email_api_client",
"email_db_client",
"email_utils",
"entity_access",
@@ -5178,7 +5234,6 @@ dependencies = [
"macro_service_urls",
"macro_user_id",
"macro_uuid",
- "mailparse",
"mime_guess",
"model",
"model-entity",
@@ -6259,12 +6314,9 @@ checksum = "0cc23270f6e1808e30a928bdc84dea0b9b4136a8bc82338574f23baf47bbd280"
name = "gmail_client"
version = "0.1.0"
dependencies = [
- "anyhow",
"base64 0.22.1",
- "chrono",
+ "httpdate",
"jsonwebtoken 10.3.0",
- "mail-builder",
- "mockall",
"models_email",
"regex",
"reqwest 0.13.4",
@@ -6272,7 +6324,7 @@ dependencies = [
"serde_json",
"tokio",
"tracing",
- "uuid",
+ "wiremock",
"workspace-hack",
]
@@ -10254,6 +10306,16 @@ dependencies = [
"libm",
]
+[[package]]
+name = "num_cpus"
+version = "1.17.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "91df4bbde75afed763b708b7eee1e8e7651e02d97f6d5dd763e89367e957b23b"
+dependencies = [
+ "hermit-abi",
+ "libc",
+]
+
[[package]]
name = "num_enum"
version = "0.7.6"
@@ -16673,6 +16735,29 @@ dependencies = [
"memchr",
]
+[[package]]
+name = "wiremock"
+version = "0.6.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "08db1edfb05d9b3c1542e521aea074442088292f00b5f28e435c714a98f85031"
+dependencies = [
+ "assert-json-diff",
+ "base64 0.22.1",
+ "deadpool",
+ "futures",
+ "http 1.4.0",
+ "http-body-util",
+ "hyper 1.9.0",
+ "hyper-util",
+ "log",
+ "once_cell",
+ "regex",
+ "serde",
+ "serde_json",
+ "tokio",
+ "url",
+]
+
[[package]]
name = "wit-bindgen"
version = "0.51.0"
diff --git a/Cargo.toml b/Cargo.toml
index cd9f485938..89f525ac47 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -20,10 +20,12 @@ members = [
"crates/cowlike",
"crates/crm",
"crates/embedding",
+ "crates/email_api_client",
"crates/entity_mutation",
"crates/favorites",
"crates/foreign_entity",
"crates/generic_email_domains",
+ "crates/gmail_client",
"crates/graphql_channel",
"crates/graphql_common",
"crates/graphql_email",
@@ -159,8 +161,10 @@ glob = "0.3.3"
guppy = "0.17.24"
hex = "0.4.3"
hmac = "0.12.1"
+encoding_rs = "0.8"
http = "1"
http-body-util = "0.1.2"
+httpdate = "1"
image = "0.25"
indexmap = "2"
inquire = "0.7"
@@ -271,6 +275,7 @@ utoipa = { version = "5.4.0", features = [
] }
utoipa-swagger-ui = { version = "9", features = ["axum", "vendored"] }
uuid = { version = "1.15.1", features = ["fast-rng", "serde", "v4", "v5", "v7"] }
+wiremock = "0.6.5"
# worker-build (see services/sync-service/wrangler.toml) refuses to build against
# anything older than 0.2.123, so keep this floor above that.
wasm-bindgen = "0.2.123"
@@ -299,6 +304,8 @@ strum_macros = "0.27.1"
unicode-segmentation = "1.9.0"
url = "2.5.0"
zip = "=2.4.2"
+ammonia = "4.1.4"
+html-escape = "0.2"
# Retain Rust DWARF for local cache profiling while keeping release-level LLVM
# optimization. wasm-pack's custom profile metadata prevents the final
diff --git a/apps/web/src/lib/service-clients/service-email/generated/client.ts b/apps/web/src/lib/service-clients/service-email/generated/client.ts
index 406e1ef0a3..1c8812d668 100644
--- a/apps/web/src/lib/service-clients/service-email/generated/client.ts
+++ b/apps/web/src/lib/service-clients/service-email/generated/client.ts
@@ -469,11 +469,26 @@ export type getAttachmentResponse401 = {
status: 401;
};
+export type getAttachmentResponse403 = {
+ data: ErrorResponse;
+ status: 403;
+};
+
export type getAttachmentResponse404 = {
data: ErrorResponse;
status: 404;
};
+export type getAttachmentResponse409 = {
+ data: ErrorResponse;
+ status: 409;
+};
+
+export type getAttachmentResponse429 = {
+ data: ErrorResponse;
+ status: 429;
+};
+
export type getAttachmentResponse500 = {
data: ErrorResponse;
status: 500;
@@ -485,7 +500,10 @@ export type getAttachmentResponseSuccess = getAttachmentResponse200 & {
export type getAttachmentResponseError = (
| getAttachmentResponse400
| getAttachmentResponse401
+ | getAttachmentResponse403
| getAttachmentResponse404
+ | getAttachmentResponse409
+ | getAttachmentResponse429
| getAttachmentResponse500
) & {
headers: Headers;
@@ -971,6 +989,21 @@ export type listBlockedSendersResponse403 = {
status: 403;
};
+export type listBlockedSendersResponse404 = {
+ data: ErrorResponse;
+ status: 404;
+};
+
+export type listBlockedSendersResponse409 = {
+ data: ErrorResponse;
+ status: 409;
+};
+
+export type listBlockedSendersResponse429 = {
+ data: ErrorResponse;
+ status: 429;
+};
+
export type listBlockedSendersResponse500 = {
data: ErrorResponse;
status: 500;
@@ -983,6 +1016,9 @@ export type listBlockedSendersResponseSuccess =
export type listBlockedSendersResponseError = (
| listBlockedSendersResponse401
| listBlockedSendersResponse403
+ | listBlockedSendersResponse404
+ | listBlockedSendersResponse409
+ | listBlockedSendersResponse429
| listBlockedSendersResponse500
) & {
headers: Headers;
@@ -1892,6 +1928,11 @@ export type initUserResponse409 = {
status: 409;
};
+export type initUserResponse429 = {
+ data: ErrorResponse;
+ status: 429;
+};
+
export type initUserResponse500 = {
data: ErrorResponse;
status: 500;
@@ -1904,6 +1945,7 @@ export type initUserResponseError = (
| initUserResponse400
| initUserResponse401
| initUserResponse409
+ | initUserResponse429
| initUserResponse500
) & {
headers: Headers;
@@ -2014,11 +2056,26 @@ export type createLabelResponse401 = {
status: 401;
};
+export type createLabelResponse403 = {
+ data: ErrorResponse;
+ status: 403;
+};
+
+export type createLabelResponse404 = {
+ data: ErrorResponse;
+ status: 404;
+};
+
export type createLabelResponse409 = {
data: ErrorResponse;
status: 409;
};
+export type createLabelResponse429 = {
+ data: ErrorResponse;
+ status: 429;
+};
+
export type createLabelResponse500 = {
data: ErrorResponse;
status: 500;
@@ -2030,7 +2087,10 @@ export type createLabelResponseSuccess = createLabelResponse201 & {
export type createLabelResponseError = (
| createLabelResponse400
| createLabelResponse401
+ | createLabelResponse403
+ | createLabelResponse404
| createLabelResponse409
+ | createLabelResponse429
| createLabelResponse500
) & {
headers: Headers;
@@ -2201,7 +2261,7 @@ collapse to one refresh per window.
against the auth service and records the result on each link. A grant that died
while the caller was inactive is detected here within minutes instead of waiting on
the daily refresh sweep; the side effects (clearing or setting the reauth flag, and
-the one-time reauth fan-out) are handled by `fetch_token_or_mark_reauth_no_cache`.
+the one-time reauth fan-out) are handled by the email service token source.
*/
export type healthCheckLinksResponse202 = {
data: EmptyResponse;
diff --git a/apps/web/src/lib/service-clients/service-email/openapi.json b/apps/web/src/lib/service-clients/service-email/openapi.json
index d3bd4f5ba9..5ddaf0c9a1 100644
--- a/apps/web/src/lib/service-clients/service-email/openapi.json
+++ b/apps/web/src/lib/service-clients/service-email/openapi.json
@@ -423,6 +423,16 @@
}
}
},
+ "403": {
+ "description": "",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse"
+ }
+ }
+ }
+ },
"404": {
"description": "",
"content": {
@@ -433,6 +443,26 @@
}
}
},
+ "409": {
+ "description": "",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse"
+ }
+ }
+ }
+ },
+ "429": {
+ "description": "",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse"
+ }
+ }
+ }
+ },
"500": {
"description": "",
"content": {
@@ -850,6 +880,36 @@
}
}
},
+ "404": {
+ "description": "",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse"
+ }
+ }
+ }
+ },
+ "409": {
+ "description": "",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse"
+ }
+ }
+ }
+ },
+ "429": {
+ "description": "",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse"
+ }
+ }
+ }
+ },
"500": {
"description": "",
"content": {
@@ -1747,6 +1807,16 @@
}
}
},
+ "429": {
+ "description": "",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse"
+ }
+ }
+ }
+ },
"500": {
"description": "",
"content": {
@@ -1843,6 +1913,26 @@
}
}
},
+ "403": {
+ "description": "",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse"
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse"
+ }
+ }
+ }
+ },
"409": {
"description": "",
"content": {
@@ -1853,6 +1943,16 @@
}
}
},
+ "429": {
+ "description": "",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse"
+ }
+ }
+ }
+ },
"500": {
"description": "",
"content": {
@@ -1989,7 +2089,7 @@
"/email/links/health-check": {
"post": {
"tags": ["Links"],
- "summary": "Probes the live auth state of each of the caller's inboxes (owned and delegated)\nagainst the auth service and records the result on each link. A grant that died\nwhile the caller was inactive is detected here within minutes instead of waiting on\nthe daily refresh sweep; the side effects (clearing or setting the reauth flag, and\nthe one-time reauth fan-out) are handled by `fetch_token_or_mark_reauth_no_cache`.",
+ "summary": "Probes the live auth state of each of the caller's inboxes (owned and delegated)\nagainst the auth service and records the result on each link. A grant that died\nwhile the caller was inactive is detected here within minutes instead of waiting on\nthe daily refresh sweep; the side effects (clearing or setting the reauth flag, and\nthe one-time reauth fan-out) are handled by the email service token source.",
"description": "Probes run in the background and the response returns immediately to stay off the\nload path; each persisted flag is picked up by the next links read. Probes are\nthrottled per link in Redis so frequent calls — and many sharers of a shared inbox —\ncollapse to one refresh per window.",
"operationId": "health_check_links",
"responses": {
diff --git a/crates/email_api_client/Cargo.toml b/crates/email_api_client/Cargo.toml
new file mode 100644
index 0000000000..f46425b908
--- /dev/null
+++ b/crates/email_api_client/Cargo.toml
@@ -0,0 +1,48 @@
+[package]
+edition = "2024"
+name = "email_api_client"
+publish = false
+version = "0.1.0"
+
+[features]
+default = []
+ports = []
+outbound-gmail = [
+ "ports",
+ "dep:ammonia",
+ "dep:base64",
+ "dep:encoding_rs",
+ "dep:gmail_client",
+ "dep:html-escape",
+ "dep:http",
+ "dep:lol_html",
+ "dep:mailparse",
+ "dep:regex",
+ "dep:scraper",
+ "dep:serde_json",
+]
+
+[dependencies]
+ammonia = { workspace = true, optional = true }
+base64 = { workspace = true, optional = true }
+chrono = { workspace = true }
+encoding_rs = { workspace = true, optional = true }
+gmail_client = { path = "../gmail_client", optional = true }
+html-escape = { workspace = true, optional = true }
+http = { workspace = true, optional = true }
+lol_html = { workspace = true, optional = true }
+mail-builder = "0.4.3"
+mailparse = { version = "0.16.1", optional = true }
+models_email = { path = "../models_email" }
+regex = { workspace = true, optional = true }
+scraper = { workspace = true, optional = true }
+serde = { workspace = true }
+serde_json = { workspace = true, optional = true }
+thiserror = { workspace = true }
+tracing = { workspace = true }
+uuid = { workspace = true }
+workspace-hack = { version = "0.1", path = "../workspace-hack" }
+
+[dev-dependencies]
+tokio = { workspace = true }
+wiremock = { workspace = true }
diff --git a/crates/email_api_client/src/domain/mod.rs b/crates/email_api_client/src/domain/mod.rs
new file mode 100644
index 0000000000..1ff795a668
--- /dev/null
+++ b/crates/email_api_client/src/domain/mod.rs
@@ -0,0 +1,12 @@
+//! Domain models and capability boundaries for email provider APIs.
+
+/// Provider-neutral values exchanged across email API boundaries.
+pub mod models;
+
+/// Capability-oriented provider and infrastructure ports.
+#[cfg(feature = "ports")]
+pub mod ports;
+
+/// Provider-neutral email API orchestration.
+#[cfg(feature = "ports")]
+pub mod service;
diff --git a/crates/email_api_client/src/domain/models/auth.rs b/crates/email_api_client/src/domain/models/auth.rs
new file mode 100644
index 0000000000..e2430ada75
--- /dev/null
+++ b/crates/email_api_client/src/domain/models/auth.rs
@@ -0,0 +1,69 @@
+use std::fmt;
+
+use thiserror::Error;
+
+/// An opaque bearer token used to authorize provider API requests.
+#[derive(Clone, PartialEq, Eq)]
+pub struct AccessToken(String);
+
+impl AccessToken {
+ /// Wraps an access token without validating provider-specific syntax.
+ pub fn new(token: impl Into<String>) -> Self {
+ Self(token.into())
+ }
+
+ /// Borrows the token for an outbound provider adapter.
+ pub fn expose_secret(&self) -> &str {
+ &self.0
+ }
+
+ /// Consumes this value and returns the token string.
+ pub fn into_secret(self) -> String {
+ self.0
+ }
+}
+
+impl fmt::Debug for AccessToken {
+ fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+ formatter.write_str("AccessToken([REDACTED])")
+ }
+}
+
+impl From<String> for AccessToken {
+ fn from(token: String) -> Self {
+ Self::new(token)
+ }
+}
+
+/// Controls whether a token may come from a cache or must be refreshed.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
+pub enum TokenFreshness {
+ /// A valid cached token may be returned.
+ #[default]
+ Cached,
+ /// The provider grant must be checked by fetching a fresh token.
+ Fresh,
+}
+
+/// A provider-neutral token acquisition failure.
+#[derive(Debug, Clone, Error, PartialEq, Eq)]
+pub enum TokenError {
+ /// The grant is absent or revoked and the user must reconnect it.
+ #[error("email provider authorization is required")]
+ ReauthRequired,
+ /// Token acquisition failed temporarily and may be retried.
+ #[error("access token acquisition failed temporarily: {message}")]
+ Transient {
+ /// A sanitized diagnostic suitable for logs.
+ message: String,
+ },
+ /// Token acquisition failed permanently for a reason other than reauthorization.
+ #[error("access token acquisition failed: {message}")]
+ Permanent {
+ /// A sanitized diagnostic suitable for logs.
+ message: String,
+ },
+}
+
+#[cfg(test)]
+mod test;
diff --git a/crates/email_api_client/src/domain/models/auth/test.rs b/crates/email_api_client/src/domain/models/auth/test.rs
new file mode 100644
index 0000000000..3ff9d9c278
--- /dev/null
+++ b/crates/email_api_client/src/domain/models/auth/test.rs
@@ -0,0 +1,9 @@
+use super::AccessToken;
+
+#[test]
+fn access_token_debug_output_is_redacted() {
+ let output = format!("{:?}", AccessToken::new("secret-token-value"));
+
+ assert_eq!(output, "AccessToken([REDACTED])");
+ assert!(!output.contains("secret-token-value"));
+}
diff --git a/crates/email_api_client/src/domain/models/changes.rs b/crates/email_api_client/src/domain/models/changes.rs
new file mode 100644
index 0000000000..1d9a674654
--- /dev/null
+++ b/crates/email_api_client/src/domain/models/changes.rs
@@ -0,0 +1,57 @@
+use std::collections::HashSet;
+
+use serde::{Deserialize, Serialize};
+
+/// A provider cursor from which incremental synchronization can continue.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub enum SyncCursor {
+ /// A Gmail history identifier.
+ Gmail(String),
+}
+
+impl SyncCursor {
+ /// Creates a Gmail synchronization cursor.
+ pub fn gmail(history_id: impl Into<String>) -> Self {
+ Self::Gmail(history_id.into())
+ }
+
+ /// Returns the provider cursor's opaque value.
+ pub fn as_str(&self) -> &str {
+ match self {
+ Self::Gmail(history_id) => history_id,
+ }
+ }
+}
+
+/// Provider-neutral inbox mutations discovered during incremental synchronization.
+#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
+pub struct InboxChanges {
+ /// Provider message identifiers that must be inserted or refreshed.
+ pub message_ids_to_upsert: HashSet<String>,
+ /// Provider message identifiers that have been permanently deleted.
+ pub message_ids_to_delete: HashSet<String>,
+ /// Provider message identifiers whose labels must be refreshed.
+ pub labels_to_update: HashSet<String>,
+}
+
+/// A page of inbox changes and the cursor that follows those changes.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct ChangeBatch {
+ /// Changes represented by this batch.
+ pub changes: InboxChanges,
+ /// Cursor to persist after the batch has been accepted.
+ pub next_cursor: SyncCursor,
+}
+
+impl ChangeBatch {
+ /// Creates a change batch ending at `next_cursor`.
+ pub fn new(changes: InboxChanges, next_cursor: SyncCursor) -> Self {
+ Self {
+ changes,
+ next_cursor,
+ }
+ }
+}
+
+#[cfg(test)]
+mod test;
diff --git a/crates/email_api_client/src/domain/models/changes/test.rs b/crates/email_api_client/src/domain/models/changes/test.rs
new file mode 100644
index 0000000000..b2bb54bdbb
--- /dev/null
+++ b/crates/email_api_client/src/domain/models/changes/test.rs
@@ -0,0 +1,9 @@
+use super::SyncCursor;
+
+#[test]
+fn gmail_cursor_preserves_opaque_history_id() {
+ let cursor = SyncCursor::gmail("history-123");
+
+ assert_eq!(cursor, SyncCursor::Gmail("history-123".to_string()));
+ assert_eq!(cursor.as_str(), "history-123");
+}
diff --git a/crates/email_api_client/src/domain/models/error.rs b/crates/email_api_client/src/domain/models/error.rs
new file mode 100644
index 0000000000..e47fd7f897
--- /dev/null
+++ b/crates/email_api_client/src/domain/models/error.rs
@@ -0,0 +1,89 @@
+use std::time::Duration;
+
+use thiserror::Error;
+
+/// A rate-limit decision made before a provider request is attempted.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct RateLimitRefusal {
+ /// Delay suggested before retrying, when one is known.
+ pub retry_after: Option<Duration>,
+}
+
+impl RateLimitRefusal {
+ /// Creates a rate-limit refusal with an optional retry delay.
+ pub fn new(retry_after: Option<Duration>) -> Self {
+ Self { retry_after }
+ }
+}
+
+/// A provider-neutral failure from an email API capability.
+#[derive(Debug, Clone, Error, PartialEq, Eq)]
+pub enum EmailApiError {
+ /// The request was refused by local quota policy or the provider.
+ #[error("email provider rate limit exceeded")]
+ RateLimited {
+ /// Delay suggested before retrying, when one is known.
+ retry_after: Option<Duration>,
+ /// Whether the refusal came from local policy or the provider itself.
+ origin: RateLimitOrigin,
+ },
+ /// The provider grant must be reauthorized.
+ #[error("email provider authorization is required")]
+ AuthRequired,
+ /// The provider refused the operation despite valid authentication.
+ #[error("email provider operation is forbidden")]
+ Forbidden,
+ /// The requested provider resource does not exist.
+ #[error("email provider resource was not found")]
+ NotFound,
+ /// The operation conflicts with existing provider state.
+ #[error("email provider state conflict")]
+ Conflict,
+ /// The incremental synchronization cursor is too old to use.
+ #[error("email synchronization cursor is outdated")]
+ OutdatedCursor,
+ /// A transport or provider failure that may succeed when retried.
+ #[error("transient email provider failure: {message}")]
+ Transient {
+ /// A sanitized diagnostic suitable for logs.
+ message: String,
+ },
+ /// A deterministic failure that should not be retried unchanged.
+ #[error("permanent email provider failure: {message}")]
+ Permanent {
+ /// A sanitized diagnostic suitable for logs.
+ message: String,
+ },
+}
+
+impl EmailApiError {
+ /// Returns whether retrying the same operation may succeed.
+ pub fn is_transient(&self) -> bool {
+ matches!(self, Self::RateLimited { .. } | Self::Transient { .. })
+ }
+}
+
+/// Where a rate-limit refusal originated.
+///
+/// Callers use this to distinguish a local budget refusal (no provider quota
+/// was consumed; a drop-and-wait policy may be appropriate) from the provider
+/// itself throttling the request (retrying preserves delivery guarantees).
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum RateLimitOrigin {
+ /// Refused by local quota policy before any provider call was made.
+ Local,
+ /// The provider itself throttled the request.
+ Provider,
+}
+
+impl From<RateLimitRefusal> for EmailApiError {
+ fn from(refusal: RateLimitRefusal) -> Self {
+ Self::RateLimited {
+ retry_after: refusal.retry_after,
+ origin: RateLimitOrigin::Local,
+ }
+ }
+}
+
+#[cfg(test)]
+mod test;
diff --git a/crates/email_api_client/src/domain/models/error/test.rs b/crates/email_api_client/src/domain/models/error/test.rs
new file mode 100644
index 0000000000..8b176ad8a6
--- /dev/null
+++ b/crates/email_api_client/src/domain/models/error/test.rs
@@ -0,0 +1,25 @@
+use super::{EmailApiError, RateLimitOrigin};
+
+#[test]
+fn email_api_error_identifies_transient_failures() {
+ assert!(
+ EmailApiError::Transient {
+ message: "provider unavailable".to_string(),
+ }
+ .is_transient()
+ );
+ assert!(
+ EmailApiError::RateLimited {
+ retry_after: None,
+ origin: RateLimitOrigin::Local,
+ }
+ .is_transient()
+ );
+ assert!(
+ !EmailApiError::Permanent {
+ message: "invalid message".to_string(),
+ }
+ .is_transient()
+ );
+ assert!(!EmailApiError::OutdatedCursor.is_transient());
+}
diff --git a/crates/email_api_client/src/domain/models/mailbox.rs b/crates/email_api_client/src/domain/models/mailbox.rs
new file mode 100644
index 0000000000..c2884d0d09
--- /dev/null
+++ b/crates/email_api_client/src/domain/models/mailbox.rs
@@ -0,0 +1,59 @@
+use chrono::{DateTime, Utc};
+use models_email::email::service::message::Message;
+use models_email::email::service::thread::ThreadSummary;
+use serde::{Deserialize, Serialize};
+
+use super::SyncCursor;
+
+/// A normalized message paired with the calendar invitation parts discovered
+/// in the same provider fetch.
+///
+/// Surfacing both from one wire read lets callers ingest inline invites
+/// without a second per-message provider fetch (and its quota charge).
+#[derive(Debug, Clone)]
+pub struct MessageWithCalendarParts {
+ /// The normalized provider message.
+ pub message: Message,
+ /// Calendar invitation parts found in the message payload.
+ pub calendar_parts: Vec<CalendarPart>,
+}
+
+/// Provider-neutral calendar invitation part discovered in a message.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct CalendarPart {
+ /// Provider MIME-part identifier, when available.
+ pub part_id: Option<String>,
+ /// Original filename, when supplied by the sender.
+ pub filename: Option<String>,
+ /// Declared media type.
+ pub mime_type: String,
+ /// Decoded inline bytes, if the provider included the part inline.
+ pub inline_data: Option<Vec<u8>>,
+ /// Provider attachment identifier when a separate download is required.
+ pub provider_attachment_id: Option<String>,
+}
+
+/// An active provider notification subscription and its synchronization cursor.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct ProviderSubscription {
+ /// Cursor identifying provider state when the subscription was created.
+ pub cursor: SyncCursor,
+ /// Instant at which the provider expires the subscription.
+ pub expires_at: DateTime<Utc>,
+}
+
+impl ProviderSubscription {
+ /// Creates a provider subscription.
+ pub fn new(cursor: SyncCursor, expires_at: DateTime<Utc>) -> Self {
+ Self { cursor, expires_at }
+ }
+}
+
+/// One provider page of email thread identifiers.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct ThreadListPage {
+ /// Threads returned in this page.
+ pub threads: Vec<ThreadSummary>,
+ /// Opaque token for the next page, or `None` when this is the last page.
+ pub next_page_token: Option<String>,
+}
diff --git a/crates/email_api_client/src/domain/models/mod.rs b/crates/email_api_client/src/domain/models/mod.rs
new file mode 100644
index 0000000000..cf78595be6
--- /dev/null
+++ b/crates/email_api_client/src/domain/models/mod.rs
@@ -0,0 +1,15 @@
+//! Provider-neutral email API models.
+
+mod auth;
+mod changes;
+mod error;
+mod mailbox;
+mod operation;
+mod send;
+
+pub use auth::{AccessToken, TokenError, TokenFreshness};
+pub use changes::{ChangeBatch, InboxChanges, SyncCursor};
+pub use error::{EmailApiError, RateLimitOrigin, RateLimitRefusal};
+pub use mailbox::{CalendarPart, MessageWithCalendarParts, ProviderSubscription, ThreadListPage};
+pub use operation::ApiOperationKind;
+pub use send::{SendRequest, SentIds};
diff --git a/crates/email_api_client/src/domain/models/operation.rs b/crates/email_api_client/src/domain/models/operation.rs
new file mode 100644
index 0000000000..4cc1e6194a
--- /dev/null
+++ b/crates/email_api_client/src/domain/models/operation.rs
@@ -0,0 +1,40 @@
+/// A provider-neutral email API capability used for quota accounting.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub enum ApiOperationKind {
+ /// Fetch the mailbox profile.
+ GetProfile,
+ /// Fetch incremental mailbox changes.
+ ListChanges,
+ /// List mailbox labels.
+ ListLabels,
+ /// Create a mailbox label.
+ CreateLabel,
+ /// Delete a mailbox label.
+ DeleteLabel,
+ /// Fetch one message.
+ GetMessage,
+ /// List messages.
+ ListMessages,
+ /// Modify labels on a message.
+ ModifyMessageLabels,
+ /// Fetch one message attachment.
+ GetAttachment,
+ /// Send a message.
+ SendMessage,
+ /// Fetch one thread.
+ GetThread,
+ /// List threads.
+ ListThreads,
+ /// List provider contacts.
+ ListContacts,
+ /// Create a blocked-sender rule.
+ BlockSender,
+ /// Remove a blocked-sender rule.
+ UnblockSender,
+ /// List blocked senders.
+ ListBlockedSenders,
+ /// Register a mailbox notification subscription.
+ Subscribe,
+ /// Stop a mailbox notification subscription.
+ Unsubscribe,
+}
diff --git a/crates/email_api_client/src/domain/models/send.rs b/crates/email_api_client/src/domain/models/send.rs
new file mode 100644
index 0000000000..ea65e9d790
--- /dev/null
+++ b/crates/email_api_client/src/domain/models/send.rs
@@ -0,0 +1,87 @@
+use mail_builder::MessageBuilder;
+use mail_builder::headers::address::Address;
+use models_email::email::service::address::ContactInfo;
+use models_email::email::service::message::MessageToSend;
+
+use super::EmailApiError;
+
+#[cfg(test)]
+mod test;
+
+/// Provider-neutral content and threading metadata for a message send.
+#[derive(Debug, Clone)]
+pub struct SendRequest {
+ /// Message content prepared by the email service.
+ pub message: MessageToSend,
+ /// Sender shown in the message's `From` header.
+ pub from: ContactInfo,
+ /// Global message identifier of the direct parent message.
+ pub parent_message_id: Option<String>,
+ /// Global message identifiers that describe the reply chain.
+ pub references: Option<Vec<String>>,
+}
+
+impl SendRequest {
+ /// Builds the RFC 5322 MIME representation consumed by provider adapters.
+ pub fn build_mime(&self) -> Result<Vec<u8>, EmailApiError> {
+ let mut builder = MessageBuilder::new()
+ .from(contact_to_address(&self.from))
+ .to(contacts_to_address_list(self.message.to.as_deref()))
+ .cc(contacts_to_address_list(self.message.cc.as_deref()))
+ .bcc(contacts_to_address_list(self.message.bcc.as_deref()))
+ .subject(&self.message.subject);
+
+ if let Some(parent_message_id) = &self.parent_message_id {
+ builder = builder.in_reply_to(parent_message_id.as_str());
+ }
+ if let Some(references) = &self.references {
+ builder = builder.references(references.clone());
+ }
+ if let Some(text_body) = &self.message.body_text {
+ builder = builder.text_body(text_body);
+ }
+ if let Some(html_body) = &self.message.body_html {
+ builder = builder.html_body(html_body);
+ }
+ if let Some(attachments) = &self.message.attachments {
+ for attachment in attachments {
+ // Borrow the attachment buffers: cloning them would double
+ // peak memory for large-attachment sends.
+ builder = builder.attachment(
+ attachment.content_type.as_str(),
+ attachment.file_name.as_str(),
+ &attachment.data[..],
+ );
+ }
+ }
+
+ builder
+ .write_to_vec()
+ .map_err(|error| EmailApiError::Permanent {
+ message: format!("failed to build MIME message: {error}"),
+ })
+ }
+}
+
+fn contact_to_address(contact: &ContactInfo) -> Address<'_> {
+ Address::new_address(contact.name.as_deref(), contact.email.as_str())
+}
+
+fn contacts_to_address_list(contacts: Option<&[ContactInfo]>) -> Address<'_> {
+ Address::new_list(
+ contacts
+ .unwrap_or_default()
+ .iter()
+ .map(contact_to_address)
+ .collect(),
+ )
+}
+
+/// Provider identifiers returned after a message is accepted for sending.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct SentIds {
+ /// Provider identifier assigned to the sent message.
+ pub provider_message_id: String,
+ /// Provider identifier of the containing thread.
+ pub provider_thread_id: String,
+}
diff --git a/crates/email_api_client/src/domain/models/send/test.rs b/crates/email_api_client/src/domain/models/send/test.rs
new file mode 100644
index 0000000000..619b8e7577
--- /dev/null
+++ b/crates/email_api_client/src/domain/models/send/test.rs
@@ -0,0 +1,66 @@
+use models_email::email::service::address::ContactInfo;
+use models_email::email::service::attachment::AttachmentToSend;
+use models_email::email::service::message::MessageToSend;
+use uuid::Uuid;
+
+use super::SendRequest;
+
+fn contact(email: &str, name: &str) -> ContactInfo {
+ ContactInfo {
+ email: email.to_string(),
+ name: Some(name.to_string()),
+ photo_url: None,
+ }
+}
+
+#[test]
+fn mime_contains_recipients_threading_bodies_and_attachments() {
+ let request = SendRequest {
+ message: MessageToSend {
+ db_id: None,
+ provider_id: None,
+ replying_to_id: None,
+ provider_thread_id: Some("provider-thread".to_string()),
+ thread_db_id: None,
+ link_id: Uuid::nil(),
+ subject: "Provider-neutral send".to_string(),
+ to: Some(vec![contact("[email protected]", "To Recipient")]),
+ cc: Some(vec![contact("[email protected]", "Cc Recipient")]),
+ bcc: Some(vec![contact("[email protected]", "Bcc Recipient")]),
+ body_text: Some("Plain body".to_string()),
+ body_html: Some("<strong>HTML body</strong>".to_string()),
+ body_macro: None,
+ attachments: Some(vec![AttachmentToSend {
+ file_name: "notes.txt".to_string(),
+ content_type: "text/plain".to_string(),
+ data: b"attachment contents".to_vec(),
+ }]),
+ headers_json: None,
+ send_time: None,
+ },
+ from: contact("[email protected]", "Sender"),
+ parent_message_id: Some("[email protected]".to_string()),
+ references: Some(vec![
+ "[email protected]".to_string(),
+ "[email protected]".to_string(),
+ ]),
+ };
+
+ let mime = String::from_utf8(request.build_mime().expect("MIME should build"))
+ .expect("generated MIME should be UTF-8 for this fixture");
+
+ assert!(mime.contains("From:"));
+ assert!(mime.contains("[email protected]"));
+ assert!(mime.contains("To:"));
+ assert!(mime.contains("[email protected]"));
+ assert!(mime.contains("Cc:"));
+ assert!(mime.contains("[email protected]"));
+ assert!(mime.contains("Bcc:"));
+ assert!(mime.contains("[email protected]"));
+ assert!(mime.contains("In-Reply-To: <[email protected]>"));
+ assert!(mime.contains("References: <[email protected]> <[email protected]>"));
+ assert!(mime.contains("Plain body"));
+ assert!(mime.contains("<strong>HTML body</strong>"));
+ assert!(mime.contains("filename=\"notes.txt\""));
+ assert!(mime.contains("attachment contents") || mime.contains("YXR0YWNobWVudCBjb250ZW50cw=="));
+}
diff --git a/crates/email_api_client/src/domain/ports.rs b/crates/email_api_client/src/domain/ports.rs
new file mode 100644
index 0000000000..d79af2263d
--- /dev/null
+++ b/crates/email_api_client/src/domain/ports.rs
@@ -0,0 +1,516 @@
+//! Capability-oriented ports for provider email APIs.
+
+use std::future::Future;
+
+use models_email::email::service::label::Label;
+use models_email::email::service::message::Message;
+use models_email::service::contact::{Contact, ContactList};
+use models_email::service::link::Link;
+use uuid::Uuid;
+
+use super::models::{
+ AccessToken, ApiOperationKind, CalendarPart, ChangeBatch, EmailApiError,
+ MessageWithCalendarParts, ProviderSubscription, RateLimitRefusal, SendRequest, SentIds,
+ SyncCursor, ThreadListPage, TokenError, TokenFreshness,
+};
+
+#[cfg(test)]
+mod test;
+
+/// Incremental synchronization and mailbox discovery capabilities.
+pub trait MailboxSyncClient: Send + Sync + 'static {
+ /// Returns the number of threads currently reported by the mailbox.
+ fn get_thread_count(
+ &self,
+ access_token: &AccessToken,
+ ) -> impl Future<Output = Result<u64, EmailApiError>> + Send;
+
+ /// Returns mailbox changes that follow `cursor`.
+ fn list_changes(
+ &self,
+ access_token: &AccessToken,
+ cursor: &SyncCursor,
+ ) -> impl Future<Output = Result<ChangeBatch, EmailApiError>> + Send;
+}
+
+/// Mailbox push-notification subscription capabilities.
+pub trait MailboxSubscriptionClient: Send + Sync + 'static {
+ /// Creates or renews the provider notification subscription.
+ fn subscribe(
+ &self,
+ access_token: &AccessToken,
+ ) -> impl Future<Output = Result<ProviderSubscription, EmailApiError>> + Send;
+
+ /// Stops provider notifications for the mailbox.
+ fn unsubscribe(
+ &self,
+ access_token: &AccessToken,
+ ) -> impl Future<Output = Result<(), EmailApiError>> + Send;
+}
+
+/// Message and thread read/write capabilities, excluding message sending.
+pub trait MailboxMessageClient: Send + Sync + 'static {
+ /// Fetches and normalizes one provider message, surfacing any calendar
+ /// invitation parts found in the same wire fetch.
+ fn get_message(
+ &self,
+ access_token: &AccessToken,
+ link_id: Uuid,
+ provider_message_id: &str,
+ ) -> impl Future<Output = Result<Option<MessageWithCalendarParts>, EmailApiError>> + Send;
+
+ /// Fetches the provider label identifiers currently attached to a message.
+ fn get_message_label_ids(
+ &self,
+ access_token: &AccessToken,
+ provider_message_id: &str,
+ ) -> impl Future<Output = Result<Option<Vec<String>>, EmailApiError>> + Send;
+
+ /// Lists message identifiers carrying all requested provider labels.
+ fn list_messages(
+ &self,
+ access_token: &AccessToken,
+ limit: u32,
+ label_ids: &[&str],
+ ) -> impl Future<Output = Result<Vec<String>, EmailApiError>> + Send;
+
+ /// Lists the message identifiers belonging to a provider thread.
+ fn get_message_ids_for_thread(
+ &self,
+ access_token: &AccessToken,
+ provider_thread_id: &str,
+ ) -> impl Future<Output = Result<Vec<String>, EmailApiError>> + Send;
+
+ /// Fetches and normalizes every message in a provider thread.
+ fn get_thread(
+ &self,
+ access_token: &AccessToken,
+ link_id: Uuid,
+ provider_thread_id: &str,
+ ) -> impl Future<Output = Result<Vec<Message>, EmailApiError>> + Send;
+
+ /// Lists one page of provider threads.
+ fn list_threads(
+ &self,
+ access_token: &AccessToken,
+ limit: u32,
+ next_page_token: Option<&str>,
+ label_ids: &[&str],
+ ) -> impl Future<Output = Result<ThreadListPage, EmailApiError>> + Send;
+
+ /// Adds and removes provider labels from one message.
+ fn modify_message_labels(
+ &self,
+ access_token: &AccessToken,
+ provider_message_id: &str,
+ label_ids_to_add: &[String],
+ label_ids_to_remove: &[String],
+ ) -> impl Future<Output = Result<(), EmailApiError>> + Send;
+}
+
+/// Message sending capability.
+pub trait MailboxSendClient: Send + Sync + 'static {
+ /// Builds and sends a message, optionally in an existing provider thread.
+ fn send_message(
+ &self,
+ access_token: &AccessToken,
+ request: &SendRequest,
+ provider_thread_id: Option<&str>,
+ ) -> impl Future<Output = Result<SentIds, EmailApiError>> + Send;
+}
+
+/// Mailbox label management capabilities.
+pub trait MailboxLabelClient: Send + Sync + 'static {
+ /// Lists and normalizes all mailbox labels.
+ fn list_labels(
+ &self,
+ access_token: &AccessToken,
+ link_id: Uuid,
+ ) -> impl Future<Output = Result<Vec<Label>, EmailApiError>> + Send;
+
+ /// Creates and normalizes a user label.
+ fn create_label(
+ &self,
+ access_token: &AccessToken,
+ link_id: Uuid,
+ name: &str,
+ ) -> impl Future<Output = Result<Label, EmailApiError>> + Send;
+
+ /// Deletes a provider label.
+ fn delete_label(
+ &self,
+ access_token: &AccessToken,
+ provider_label_id: &str,
+ ) -> impl Future<Output = Result<(), EmailApiError>> + Send;
+}
+
+/// Calendar invitation discovery capability.
+///
+/// This id-based lookup issues a fresh provider fetch (and pays its quota
+/// charge). Ingest paths that already hold the fetched message should use the
+/// calendar parts surfaced by [`MailboxMessageClient::get_message`] instead;
+/// this port exists for durable re-extraction jobs where a fresh fetch is
+/// correct.
+pub trait MailboxCalendarClient: Send + Sync + 'static {
+ /// Finds provider-neutral calendar parts in one message.
+ fn get_calendar_parts(
+ &self,
+ access_token: &AccessToken,
+ provider_message_id: &str,
+ ) -> impl Future<Output = Result<Vec<CalendarPart>, EmailApiError>> + Send;
+}
+
+/// Message attachment download capability.
+pub trait MailboxAttachmentClient: Send + Sync + 'static {
+ /// Downloads the decoded bytes of a provider attachment.
+ fn get_attachment(
+ &self,
+ access_token: &AccessToken,
+ provider_message_id: &str,
+ provider_attachment_id: &str,
+ ) -> impl Future<Output = Result<Vec<u8>, EmailApiError>> + Send;
+}
+
+/// Mailbox contact synchronization capabilities.
+pub trait MailboxContactsClient: Send + Sync + 'static {
+ /// Fetches and normalizes the mailbox owner's contact record.
+ fn get_self_contact(
+ &self,
+ access_token: &AccessToken,
+ link_id: Uuid,
+ ) -> impl Future<Output = Result<Contact, EmailApiError>> + Send;
+
+ /// Fetches and normalizes primary contacts from an optional synchronization token.
+ fn list_contacts(
+ &self,
+ access_token: &AccessToken,
+ link_id: Uuid,
+ sync_token: Option<&str>,
+ ) -> impl Future<Output = Result<ContactList, EmailApiError>> + Send;
+
+ /// Fetches and normalizes automatically collected contacts.
+ fn list_other_contacts(
+ &self,
+ access_token: &AccessToken,
+ link_id: Uuid,
+ sync_token: Option<&str>,
+ ) -> impl Future<Output = Result<ContactList, EmailApiError>> + Send;
+}
+
+/// Blocked-sender management capabilities.
+pub trait MailboxBlocklistClient: Send + Sync + 'static {
+ /// Ensures messages from `email_address` are sent to trash.
+ fn block_sender(
+ &self,
+ access_token: &AccessToken,
+ email_address: &str,
+ ) -> impl Future<Output = Result<(), EmailApiError>> + Send;
+
+ /// Removes the blocked-sender rule for `email_address`, when present.
+ fn unblock_sender(
+ &self,
+ access_token: &AccessToken,
+ email_address: &str,
+ ) -> impl Future<Output = Result<(), EmailApiError>> + Send;
+
+ /// Lists email addresses covered by blocked-sender rules.
+ fn list_blocked_senders(
+ &self,
+ access_token: &AccessToken,
+ ) -> impl Future<Output = Result<Vec<String>, EmailApiError>> + Send;
+}
+
+/// Provider repository assembled from the eight core mailbox capabilities.
+///
+/// [`MailboxCalendarClient`] is deliberately not part of this bound: calendar
+/// part discovery is optional and composed separately where needed.
+pub trait EmailApiClientRepository:
+ MailboxSyncClient
+ + MailboxSubscriptionClient
+ + MailboxMessageClient
+ + MailboxSendClient
+ + MailboxLabelClient
+ + MailboxAttachmentClient
+ + MailboxContactsClient
+ + MailboxBlocklistClient
+{
+}
+
+impl<T> EmailApiClientRepository for T where
+ T: MailboxSyncClient
+ + MailboxSubscriptionClient
+ + MailboxMessageClient
+ + MailboxSendClient
+ + MailboxLabelClient
+ + MailboxAttachmentClient
+ + MailboxContactsClient
+ + MailboxBlocklistClient
+{
+}
+
+/// Acquires provider access tokens for a linked mailbox.
+pub trait ProviderTokenSource: Send + Sync + 'static {
+ /// Returns an access token with the requested freshness.
+ fn get_access_token(
+ &self,
+ link_id: Uuid,
+ freshness: TokenFreshness,
+ ) -> impl Future<Output = Result<AccessToken, TokenError>> + Send;
+
+ /// Returns an access token for a link that may not have been persisted yet.
+ ///
+ /// Required (no default): a default delegating to the id-based lookup
+ /// would contradict this method's purpose — the link's row may not exist
+ /// yet — and an implementor silently relying on it would break mailbox
+ /// initialization.
+ fn get_access_token_for_link(
+ &self,
+ link: &Link,
+ freshness: TokenFreshness,
+ ) -> impl Future<Output = Result<AccessToken, TokenError>> + Send;
+
+ /// Returns an access token without recording token-health side effects.
+ ///
+ /// Teardown flows use this: a failed acquisition while deleting a link
+ /// must not mark the link as needing reauthorization or notify the user
+ /// about an inbox that is being intentionally removed.
+ fn get_access_token_health_neutral(
+ &self,
+ link: &Link,
+ freshness: TokenFreshness,
+ ) -> impl Future<Output = Result<AccessToken, TokenError>> + Send;
+}
+
+/// Applies provider quota policy before an outbound request.
+pub trait ProviderRateLimiter: Send + Sync + 'static {
+ /// Allows or refuses an operation for a linked mailbox.
+ fn check_rate_limit(
+ &self,
+ link_id: Uuid,
+ operation: ApiOperationKind,
+ ) -> impl Future<Output = Result<(), RateLimitRefusal>> + Send;
+}
+
+/// Mailbox adapter used when provider capabilities are intentionally unavailable.
+#[derive(Debug, Clone, Copy, Default)]
+pub struct NoOpMailboxClient;
+
+/// Token source used when provider token acquisition is intentionally unavailable.
+#[derive(Debug, Clone, Copy, Default)]
+pub struct NoOpProviderTokenSource;
+
+/// Rate limiter that permits every operation.
+#[derive(Debug, Clone, Copy, Default)]
+pub struct AlwaysAllowRateLimiter;
+
+fn unavailable() -> EmailApiError {
+ EmailApiError::Permanent {
+ message: "email provider capability is not configured".to_string(),
+ }
+}
+
+impl MailboxSyncClient for NoOpMailboxClient {
+ async fn get_thread_count(&self, _: &AccessToken) -> Result<u64, EmailApiError> {
+ Err(unavailable())
+ }
+
+ async fn list_changes(
+ &self,
+ _: &AccessToken,
+ _: &SyncCursor,
+ ) -> Result<ChangeBatch, EmailApiError> {
+ Err(unavailable())
+ }
+}
+
+impl MailboxSubscriptionClient for NoOpMailboxClient {
+ async fn subscribe(&self, _: &AccessToken) -> Result<ProviderSubscription, EmailApiError> {
+ Err(unavailable())
+ }
+
+ async fn unsubscribe(&self, _: &AccessToken) -> Result<(), EmailApiError> {
+ Err(unavailable())
+ }
+}
+
+impl MailboxMessageClient for NoOpMailboxClient {
+ async fn get_message(
+ &self,
+ _: &AccessToken,
+ _: Uuid,
+ _: &str,
+ ) -> Result<Option<MessageWithCalendarParts>, EmailApiError> {
+ Err(unavailable())
+ }
+
+ async fn get_message_label_ids(
+ &self,
+ _: &AccessToken,
+ _: &str,
+ ) -> Result<Option<Vec<String>>, EmailApiError> {
+ Err(unavailable())
+ }
+
+ async fn list_messages(
+ &self,
+ _: &AccessToken,
+ _: u32,
+ _: &[&str],
+ ) -> Result<Vec<String>, EmailApiError> {
+ Err(unavailable())
+ }
+
+ async fn get_message_ids_for_thread(
+ &self,
+ _: &AccessToken,
+ _: &str,
+ ) -> Result<Vec<String>, EmailApiError> {
+ Err(unavailable())
+ }
+
+ async fn get_thread(
+ &self,
+ _: &AccessToken,
+ _: Uuid,
+ _: &str,
+ ) -> Result<Vec<Message>, EmailApiError> {
+ Err(unavailable())
+ }
+
+ async fn list_threads(
+ &self,
+ _: &AccessToken,
+ _: u32,
+ _: Option<&str>,
+ _: &[&str],
+ ) -> Result<ThreadListPage, EmailApiError> {
+ Err(unavailable())
+ }
+
+ async fn modify_message_labels(
+ &self,
+ _: &AccessToken,
+ _: &str,
+ _: &[String],
+ _: &[String],
+ ) -> Result<(), EmailApiError> {
+ Err(unavailable())
+ }
+}
+
+impl MailboxSendClient for NoOpMailboxClient {
+ async fn send_message(
+ &self,
+ _: &AccessToken,
+ _: &SendRequest,
+ _: Option<&str>,
+ ) -> Result<SentIds, EmailApiError> {
+ Err(unavailable())
+ }
+}
+
+impl MailboxLabelClient for NoOpMailboxClient {
+ async fn list_labels(&self, _: &AccessToken, _: Uuid) -> Result<Vec<Label>, EmailApiError> {
+ Err(unavailable())
+ }
+
+ async fn create_label(
+ &self,
+ _: &AccessToken,
+ _: Uuid,
+ _: &str,
+ ) -> Result<Label, EmailApiError> {
+ Err(unavailable())
+ }
+
+ async fn delete_label(&self, _: &AccessToken, _: &str) -> Result<(), EmailApiError> {
+ Err(unavailable())
+ }
+}
+
+impl MailboxAttachmentClient for NoOpMailboxClient {
+ async fn get_attachment(
+ &self,
+ _: &AccessToken,
+ _: &str,
+ _: &str,
+ ) -> Result<Vec<u8>, EmailApiError> {
+ Err(unavailable())
+ }
+}
+
+impl MailboxContactsClient for NoOpMailboxClient {
+ async fn get_self_contact(&self, _: &AccessToken, _: Uuid) -> Result<Contact, EmailApiError> {
+ Err(unavailable())
+ }
+
+ async fn list_contacts(
+ &self,
+ _: &AccessToken,
+ _: Uuid,
+ _: Option<&str>,
+ ) -> Result<ContactList, EmailApiError> {
+ Err(unavailable())
+ }
+
+ async fn list_other_contacts(
+ &self,
+ _: &AccessToken,
+ _: Uuid,
+ _: Option<&str>,
+ ) -> Result<ContactList, EmailApiError> {
+ Err(unavailable())
+ }
+}
+
+impl MailboxBlocklistClient for NoOpMailboxClient {
+ async fn block_sender(&self, _: &AccessToken, _: &str) -> Result<(), EmailApiError> {
+ Err(unavailable())
+ }
+
+ async fn unblock_sender(&self, _: &AccessToken, _: &str) -> Result<(), EmailApiError> {
+ Err(unavailable())
+ }
+
+ async fn list_blocked_senders(&self, _: &AccessToken) -> Result<Vec<String>, EmailApiError> {
+ Err(unavailable())
+ }
+}
+
+impl ProviderTokenSource for NoOpProviderTokenSource {
+ async fn get_access_token(
+ &self,
+ _: Uuid,
+ _: TokenFreshness,
+ ) -> Result<AccessToken, TokenError> {
+ Err(TokenError::Permanent {
+ message: "email provider token source is not configured".to_string(),
+ })
+ }
+
+ async fn get_access_token_for_link(
+ &self,
+ _: &Link,
+ _: TokenFreshness,
+ ) -> Result<AccessToken, TokenError> {
+ Err(TokenError::Permanent {
+ message: "email provider token source is not configured".to_string(),
+ })
+ }
+
+ async fn get_access_token_health_neutral(
+ &self,
+ _: &Link,
+ _: TokenFreshness,
+ ) -> Result<AccessToken, TokenError> {
+ Err(TokenError::Permanent {
+ message: "email provider token source is not configured".to_string(),
+ })
+ }
+}
+
+impl ProviderRateLimiter for AlwaysAllowRateLimiter {
+ async fn check_rate_limit(&self, _: Uuid, _: ApiOperationKind) -> Result<(), RateLimitRefusal> {
+ Ok(())
+ }
+}
diff --git a/crates/email_api_client/src/domain/ports/test.rs b/crates/email_api_client/src/domain/ports/test.rs
new file mode 100644
index 0000000000..303a5afe29
--- /dev/null
+++ b/crates/email_api_client/src/domain/ports/test.rs
@@ -0,0 +1,36 @@
+use super::*;
+
+fn assert_sync_client<T: MailboxSyncClient>() {}
+fn assert_subscription_client<T: MailboxSubscriptionClient>() {}
+fn assert_message_client<T: MailboxMessageClient>() {}
+fn assert_send_client<T: MailboxSendClient>() {}
+fn assert_label_client<T: MailboxLabelClient>() {}
+fn assert_attachment_client<T: MailboxAttachmentClient>() {}
+fn assert_contacts_client<T: MailboxContactsClient>() {}
+fn assert_blocklist_client<T: MailboxBlocklistClient>() {}
+fn assert_repository<T: EmailApiClientRepository>() {}
+fn assert_token_source<T: ProviderTokenSource>() {}
+fn assert_rate_limiter<T: ProviderRateLimiter>() {}
+fn assert_send_sync_static<T: Send + Sync + 'static>() {}
+
+#[test]
+fn no_op_mailbox_implements_every_capability_and_repository() {
+ assert_sync_client::<NoOpMailboxClient>();
+ assert_subscription_client::<NoOpMailboxClient>();
+ assert_message_client::<NoOpMailboxClient>();
+ assert_send_client::<NoOpMailboxClient>();
+ assert_label_client::<NoOpMailboxClient>();
+ assert_attachment_client::<NoOpMailboxClient>();
+ assert_contacts_client::<NoOpMailboxClient>();
+ assert_blocklist_client::<NoOpMailboxClient>();
+ assert_repository::<NoOpMailboxClient>();
+ assert_send_sync_static::<NoOpMailboxClient>();
+}
+
+#[test]
+fn no_op_infrastructure_adapters_implement_their_ports() {
+ assert_token_source::<NoOpProviderTokenSource>();
+ assert_rate_limiter::<AlwaysAllowRateLimiter>();
+ assert_send_sync_static::<NoOpProviderTokenSource>();
+ assert_send_sync_static::<AlwaysAllowRateLimiter>();
+}
diff --git a/crates/email_api_client/src/domain/service/attachments.rs b/crates/email_api_client/src/domain/service/attachments.rs
new file mode 100644
index 0000000000..22a8fe7d1f
--- /dev/null
+++ b/crates/email_api_client/src/domain/service/attachments.rs
@@ -0,0 +1,32 @@
+use uuid::Uuid;
+
+use super::super::models::EmailApiError;
+use super::super::ports::{MailboxAttachmentClient, ProviderRateLimiter, ProviderTokenSource};
+use super::{ApiOperationKind, EmailApiClientServiceImpl};
+
+impl<R, T, L> EmailApiClientServiceImpl<R, T, L>
+where
+ R: MailboxAttachmentClient,
+ T: ProviderTokenSource,
+ L: ProviderRateLimiter,
+{
+ /// Downloads an attachment from a provider message.
+ #[tracing::instrument(skip(self), err)]
+ pub async fn get_attachment(
+ &self,
+ link_id: Uuid,
+ provider_message_id: &str,
+ provider_attachment_id: &str,
+ ) -> Result<Vec<u8>, EmailApiError> {
+ let access_token = self
+ .prepare(link_id, ApiOperationKind::GetAttachment)
+ .await?;
+
+ self.repository
+ .get_attachment(&access_token, provider_message_id, provider_attachment_id)
+ .await
+ }
+}
+
+#[cfg(test)]
+mod test;
diff --git a/crates/email_api_client/src/domain/service/attachments/test.rs b/crates/email_api_client/src/domain/service/attachments/test.rs
new file mode 100644
index 0000000000..3bfe8f65dc
--- /dev/null
+++ b/crates/email_api_client/src/domain/service/attachments/test.rs
@@ -0,0 +1,58 @@
+use std::sync::{Arc, Mutex};
+
+use uuid::Uuid;
+
+use super::super::test_support::{Call, FakeRateLimiter, FakeTokenSource, call_log};
+use super::*;
+use crate::domain::models::{AccessToken, TokenFreshness};
+
+#[derive(Clone, Default)]
+struct AttachmentClient {
+ arguments: Arc<Mutex<Option<(String, String, String)>>>,
+}
+
+impl MailboxAttachmentClient for AttachmentClient {
+ async fn get_attachment(
+ &self,
+ access_token: &AccessToken,
+ message_id: &str,
+ attachment_id: &str,
+ ) -> Result<Vec<u8>, EmailApiError> {
+ *self.arguments.lock().unwrap() = Some((
+ access_token.expose_secret().to_string(),
+ message_id.to_string(),
+ attachment_id.to_string(),
+ ));
+ Ok(vec![1, 2, 3])
+ }
+}
+
+#[tokio::test]
+async fn get_attachment_uses_attachment_quota_and_forwards_identifiers() {
+ let calls = call_log();
+ let repository = AttachmentClient::default();
+ let arguments = repository.arguments.clone();
+ let link_id = Uuid::new_v4();
+ let service = EmailApiClientServiceImpl::new(
+ repository,
+ FakeTokenSource::new(calls.clone(), Ok(AccessToken::new("token"))),
+ FakeRateLimiter::new(calls.clone(), Ok(())),
+ );
+
+ let result = service
+ .get_attachment(link_id, "message", "attachment")
+ .await;
+
+ assert_eq!(result.unwrap(), vec![1, 2, 3]);
+ assert_eq!(
+ *arguments.lock().unwrap(),
+ Some(("token".into(), "message".into(), "attachment".into()))
+ );
+ assert_eq!(
+ *calls.lock().unwrap(),
+ vec![
+ Call::RateLimit(link_id, ApiOperationKind::GetAttachment),
+ Call::Token(link_id, TokenFreshness::Cached),
+ ]
+ );
+}
diff --git a/crates/email_api_client/src/domain/service/blocklist.rs b/crates/email_api_client/src/domain/service/blocklist.rs
new file mode 100644
index 0000000000..dbbdc690bd
--- /dev/null
+++ b/crates/email_api_client/src/domain/service/blocklist.rs
@@ -0,0 +1,55 @@
+use uuid::Uuid;
+
+use super::super::models::EmailApiError;
+use super::super::ports::{MailboxBlocklistClient, ProviderRateLimiter, ProviderTokenSource};
+use super::{ApiOperationKind, EmailApiClientServiceImpl};
+
+impl<R, T, L> EmailApiClientServiceImpl<R, T, L>
+where
+ R: MailboxBlocklistClient,
+ T: ProviderTokenSource,
+ L: ProviderRateLimiter,
+{
+ /// Ensures messages from an email address are sent to trash.
+ #[tracing::instrument(skip(self, email_address), err)]
+ pub async fn block_sender(
+ &self,
+ link_id: Uuid,
+ email_address: &str,
+ ) -> Result<(), EmailApiError> {
+ let access_token = self.prepare(link_id, ApiOperationKind::BlockSender).await?;
+
+ self.repository
+ .block_sender(&access_token, email_address)
+ .await
+ }
+
+ /// Removes the blocked-sender rule for an email address, when present.
+ #[tracing::instrument(skip(self, email_address), err)]
+ pub async fn unblock_sender(
+ &self,
+ link_id: Uuid,
+ email_address: &str,
+ ) -> Result<(), EmailApiError> {
+ let access_token = self
+ .prepare(link_id, ApiOperationKind::UnblockSender)
+ .await?;
+
+ self.repository
+ .unblock_sender(&access_token, email_address)
+ .await
+ }
+
+ /// Lists email addresses covered by blocked-sender rules.
+ #[tracing::instrument(skip(self), err)]
+ pub async fn list_blocked_senders(&self, link_id: Uuid) -> Result<Vec<String>, EmailApiError> {
+ let access_token = self
+ .prepare(link_id, ApiOperationKind::ListBlockedSenders)
+ .await?;
+
+ self.repository.list_blocked_senders(&access_token).await
+ }
+}
+
+#[cfg(test)]
+mod test;
diff --git a/crates/email_api_client/src/domain/service/blocklist/test.rs b/crates/email_api_client/src/domain/service/blocklist/test.rs
new file mode 100644
index 0000000000..d2da5a5f7e
--- /dev/null
+++ b/crates/email_api_client/src/domain/service/blocklist/test.rs
@@ -0,0 +1,98 @@
+use uuid::Uuid;
+
+use super::super::super::models::{AccessToken, EmailApiError, TokenFreshness};
+use super::super::super::ports::MailboxBlocklistClient;
+use super::super::test_support::{Call, FakeRateLimiter, FakeTokenSource, call_log};
+use super::EmailApiClientServiceImpl;
+
+#[derive(Clone)]
+struct BlocklistClient {
+ calls: super::super::test_support::CallLog,
+}
+
+impl MailboxBlocklistClient for BlocklistClient {
+ async fn block_sender(
+ &self,
+ _: &AccessToken,
+ email_address: &str,
+ ) -> Result<(), EmailApiError> {
+ assert_eq!(email_address, "[email protected]");
+ self.record("block_sender");
+ Ok(())
+ }
+
+ async fn unblock_sender(
+ &self,
+ _: &AccessToken,
+ email_address: &str,
+ ) -> Result<(), EmailApiError> {
+ assert_eq!(email_address, "[email protected]");
+ self.record("unblock_sender");
+ Ok(())
+ }
+
+ async fn list_blocked_senders(&self, _: &AccessToken) -> Result<Vec<String>, EmailApiError> {
+ self.record("list_blocked_senders");
+ Ok(vec!["[email protected]".to_string()])
+ }
+}
+
+impl BlocklistClient {
+ fn record(&self, method: &'static str) {
+ self.calls.lock().unwrap().push(Call::Repository(method));
+ }
+}
+
+#[tokio::test]
+async fn blocklist_methods_use_their_matching_costs_and_operations() {
+ for (operation, repository_call) in [
+ (super::ApiOperationKind::BlockSender, "block_sender"),
+ (super::ApiOperationKind::UnblockSender, "unblock_sender"),
+ (
+ super::ApiOperationKind::ListBlockedSenders,
+ "list_blocked_senders",
+ ),
+ ] {
+ let calls = call_log();
+ let service = service(calls.clone());
+
+ match operation {
+ super::ApiOperationKind::BlockSender => service
+ .block_sender(Uuid::nil(), "[email protected]")
+ .await
+ .unwrap(),
+ super::ApiOperationKind::UnblockSender => service
+ .unblock_sender(Uuid::nil(), "[email protected]")
+ .await
+ .unwrap(),
+ super::ApiOperationKind::ListBlockedSenders => {
+ assert_eq!(
+ service.list_blocked_senders(Uuid::nil()).await.unwrap(),
+ );
+ }
+ _ => unreachable!(),
+ }
+
+ assert_eq!(
+ *calls.lock().unwrap(),
+ vec![
+ Call::RateLimit(Uuid::nil(), operation),
+ Call::Token(Uuid::nil(), TokenFreshness::Cached),
+ Call::Repository(repository_call),
+ ]
+ );
+ }
+}
+
+fn service(
+ calls: super::super::test_support::CallLog,
+) -> EmailApiClientServiceImpl<BlocklistClient, FakeTokenSource, FakeRateLimiter> {
+ EmailApiClientServiceImpl::new(
+ BlocklistClient {
+ calls: calls.clone(),
+ },
+ FakeTokenSource::new(calls.clone(), Ok(AccessToken::new("access-token"))),
+ FakeRateLimiter::new(calls, Ok(())),
+ )
+}
diff --git a/crates/email_api_client/src/domain/service/contacts.rs b/crates/email_api_client/src/domain/service/contacts.rs
new file mode 100644
index 0000000000..458911d297
--- /dev/null
+++ b/crates/email_api_client/src/domain/service/contacts.rs
@@ -0,0 +1,60 @@
+use models_email::service::contact::{Contact, ContactList};
+use uuid::Uuid;
+
+use super::super::models::EmailApiError;
+use super::super::ports::{MailboxContactsClient, ProviderRateLimiter, ProviderTokenSource};
+use super::{ApiOperationKind, EmailApiClientServiceImpl};
+
+impl<R, T, L> EmailApiClientServiceImpl<R, T, L>
+where
+ R: MailboxContactsClient,
+ T: ProviderTokenSource,
+ L: ProviderRateLimiter,
+{
+ /// Fetches the linked mailbox owner's contact record.
+ #[tracing::instrument(skip(self), err)]
+ pub async fn get_self_contact(&self, link_id: Uuid) -> Result<Contact, EmailApiError> {
+ let access_token = self
+ .prepare(link_id, ApiOperationKind::ListContacts)
+ .await?;
+
+ self.repository
+ .get_self_contact(&access_token, link_id)
+ .await
+ }
+
+ /// Lists primary contacts, optionally continuing an incremental synchronization.
+ #[tracing::instrument(skip(self, sync_token), err)]
+ pub async fn list_contacts(
+ &self,
+ link_id: Uuid,
+ sync_token: Option<&str>,
+ ) -> Result<ContactList, EmailApiError> {
+ let access_token = self
+ .prepare(link_id, ApiOperationKind::ListContacts)
+ .await?;
+
+ self.repository
+ .list_contacts(&access_token, link_id, sync_token)
+ .await
+ }
+
+ /// Lists automatically collected contacts, optionally continuing a synchronization.
+ #[tracing::instrument(skip(self, sync_token), err)]
+ pub async fn list_other_contacts(
+ &self,
+ link_id: Uuid,
+ sync_token: Option<&str>,
+ ) -> Result<ContactList, EmailApiError> {
+ let access_token = self
+ .prepare(link_id, ApiOperationKind::ListContacts)
+ .await?;
+
+ self.repository
+ .list_other_contacts(&access_token, link_id, sync_token)
+ .await
+ }
+}
+
+#[cfg(test)]
+mod test;
diff --git a/crates/email_api_client/src/domain/service/contacts/test.rs b/crates/email_api_client/src/domain/service/contacts/test.rs
new file mode 100644
index 0000000000..50a184308b
--- /dev/null
+++ b/crates/email_api_client/src/domain/service/contacts/test.rs
@@ -0,0 +1,132 @@
+use std::sync::{Arc, Mutex};
+
+use models_email::service::contact::{Contact, ContactList};
+use uuid::Uuid;
+
+use super::super::test_support::{Call, FakeRateLimiter, FakeTokenSource, call_log};
+use super::*;
+use crate::domain::models::{AccessToken, TokenFreshness};
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+enum ContactCall {
+ SelfContact(Uuid),
+ Contacts(Uuid, Option<String>),
+ OtherContacts(Uuid, Option<String>),
+}
+
+#[derive(Clone, Default)]
+struct ContactsClient {
+ call: Arc<Mutex<Option<ContactCall>>>,
+}
+
+impl MailboxContactsClient for ContactsClient {
+ async fn get_self_contact(
+ &self,
+ access_token: &AccessToken,
+ link_id: Uuid,
+ ) -> Result<Contact, EmailApiError> {
+ assert_eq!(access_token.expose_secret(), "token");
+ *self.call.lock().unwrap() = Some(ContactCall::SelfContact(link_id));
+ Err(expected_error())
+ }
+
+ async fn list_contacts(
+ &self,
+ access_token: &AccessToken,
+ link_id: Uuid,
+ sync_token: Option<&str>,
+ ) -> Result<ContactList, EmailApiError> {
+ assert_eq!(access_token.expose_secret(), "token");
+ *self.call.lock().unwrap() = Some(ContactCall::Contacts(
+ link_id,
+ sync_token.map(str::to_string),
+ ));
+ Err(expected_error())
+ }
+
+ async fn list_other_contacts(
+ &self,
+ access_token: &AccessToken,
+ link_id: Uuid,
+ sync_token: Option<&str>,
+ ) -> Result<ContactList, EmailApiError> {
+ assert_eq!(access_token.expose_secret(), "token");
+ *self.call.lock().unwrap() = Some(ContactCall::OtherContacts(
+ link_id,
+ sync_token.map(str::to_string),
+ ));
+ Err(expected_error())
+ }
+}
+
+fn expected_error() -> EmailApiError {
+ EmailApiError::Permanent {
+ message: "provider error".to_string(),
+ }
+}
+
+async fn assert_call<F, E>(operation: ApiOperationKind, expected_repository_call: E, invoke: F)
+where
+ E: FnOnce(Uuid) -> ContactCall,
+ F: AsyncFnOnce(
+ &EmailApiClientServiceImpl<ContactsClient, FakeTokenSource, FakeRateLimiter>,
+ Uuid,
+ ) -> Result<(), EmailApiError>,
+{
+ let calls = call_log();
+ let repository = ContactsClient::default();
+ let repository_call = repository.call.clone();
+ let link_id = Uuid::new_v4();
+ let service = EmailApiClientServiceImpl::new(
+ repository,
+ FakeTokenSource::new(calls.clone(), Ok(AccessToken::new("token"))),
+ FakeRateLimiter::new(calls.clone(), Ok(())),
+ );
+
+ assert_eq!(invoke(&service, link_id).await, Err(expected_error()));
+ assert_eq!(
+ *repository_call.lock().unwrap(),
+ Some(expected_repository_call(link_id))
+ );
+ assert_eq!(
+ *calls.lock().unwrap(),
+ vec![
+ Call::RateLimit(link_id, operation),
+ Call::Token(link_id, TokenFreshness::Cached),
+ ]
+ );
+}
+
+#[tokio::test]
+async fn contact_reads_use_correct_operation_kinds_and_forward_sync_tokens() {
+ assert_call(
+ ApiOperationKind::ListContacts,
+ ContactCall::SelfContact,
+ async |service, link_id| service.get_self_contact(link_id).await.map(|_| ()),
+ )
+ .await;
+
+ assert_call(
+ ApiOperationKind::ListContacts,
+ |link_id| ContactCall::Contacts(link_id, Some("primary-token".into())),
+ async |service, link_id| {
+ service
+ .list_contacts(link_id, Some("primary-token"))
+ .await
+ .map(|_| ())
+ },
+ )
+ .await;
+
+ assert_call(
+ ApiOperationKind::ListContacts,
+ |link_id| ContactCall::OtherContacts(link_id, Some("other-token".into())),
+ async |service, link_id| {
+ service
+ .list_other_contacts(link_id, Some("other-token"))
+ .await
+ .map(|_| ())
+ },
+ )
+ .await;
+}
diff --git a/crates/email_api_client/src/domain/service/labels.rs b/crates/email_api_client/src/domain/service/labels.rs
new file mode 100644
index 0000000000..b6689284b0
--- /dev/null
+++ b/crates/email_api_client/src/domain/service/labels.rs
@@ -0,0 +1,52 @@
+use models_email::email::service::label::Label;
+use uuid::Uuid;
+
+use super::super::models::EmailApiError;
+use super::super::ports::{MailboxLabelClient, ProviderRateLimiter, ProviderTokenSource};
+use super::{ApiOperationKind, EmailApiClientServiceImpl};
+
+impl<R, T, L> EmailApiClientServiceImpl<R, T, L>
+where
+ R: MailboxLabelClient,
+ T: ProviderTokenSource,
+ L: ProviderRateLimiter,
+{
+ /// Lists all labels for a linked mailbox.
+ #[tracing::instrument(skip(self), err)]
+ pub async fn list_labels(&self, link_id: Uuid) -> Result<Vec<Label>, EmailApiError> {
+ let access_token = self.prepare(link_id, ApiOperationKind::ListLabels).await?;
+
+ self.repository.list_labels(&access_token, link_id).await
+ }
+
+ /// Creates a user label.
+ #[tracing::instrument(skip(self), err)]
+ pub async fn create_label(
+ &self,
+ link_id: Uuid,
+ label_name: &str,
+ ) -> Result<Label, EmailApiError> {
+ let access_token = self.prepare(link_id, ApiOperationKind::CreateLabel).await?;
+
+ self.repository
+ .create_label(&access_token, link_id, label_name)
+ .await
+ }
+
+ /// Deletes a provider label.
+ #[tracing::instrument(skip(self), err)]
+ pub async fn delete_label(
+ &self,
+ link_id: Uuid,
+ provider_label_id: &str,
+ ) -> Result<(), EmailApiError> {
+ let access_token = self.prepare(link_id, ApiOperationKind::DeleteLabel).await?;
+
+ self.repository
+ .delete_label(&access_token, provider_label_id)
+ .await
+ }
+}
+
+#[cfg(test)]
+mod test;
diff --git a/crates/email_api_client/src/domain/service/labels/test.rs b/crates/email_api_client/src/domain/service/labels/test.rs
new file mode 100644
index 0000000000..5a56a12b8a
--- /dev/null
+++ b/crates/email_api_client/src/domain/service/labels/test.rs
@@ -0,0 +1,129 @@
+use std::sync::{Arc, Mutex};
+
+use models_email::email::service::label::Label;
+use uuid::Uuid;
+
+use super::super::test_support::{Call, FakeRateLimiter, FakeTokenSource, call_log};
+use super::*;
+use crate::domain::models::{AccessToken, TokenFreshness};
+
+#[derive(Clone, Default)]
+struct LabelClient {
+ arguments: Arc<Mutex<Option<(String, Uuid)>>>,
+ created_label_name: Arc<Mutex<Option<String>>>,
+ deleted_label_id: Arc<Mutex<Option<String>>>,
+}
+
+impl MailboxLabelClient for LabelClient {
+ async fn list_labels(
+ &self,
+ access_token: &AccessToken,
+ link_id: Uuid,
+ ) -> Result<Vec<Label>, EmailApiError> {
+ *self.arguments.lock().unwrap() = Some((access_token.expose_secret().to_string(), link_id));
+ Err(expected_error())
+ }
+
+ async fn create_label(
+ &self,
+ _: &AccessToken,
+ _: Uuid,
+ label_name: &str,
+ ) -> Result<Label, EmailApiError> {
+ *self.created_label_name.lock().unwrap() = Some(label_name.to_string());
+ Err(expected_error())
+ }
+
+ async fn delete_label(
+ &self,
+ _: &AccessToken,
+ provider_label_id: &str,
+ ) -> Result<(), EmailApiError> {
+ *self.deleted_label_id.lock().unwrap() = Some(provider_label_id.to_string());
+ Err(expected_error())
+ }
+}
+
+fn expected_error() -> EmailApiError {
+ EmailApiError::Permanent {
+ message: "provider error".to_string(),
+ }
+}
+
+#[tokio::test]
+async fn list_labels_uses_list_labels_quota_and_forwards_link_id() {
+ let calls = call_log();
+ let repository = LabelClient::default();
+ let arguments = repository.arguments.clone();
+ let link_id = Uuid::new_v4();
+ let service = EmailApiClientServiceImpl::new(
+ repository,
+ FakeTokenSource::new(calls.clone(), Ok(AccessToken::new("token"))),
+ FakeRateLimiter::new(calls.clone(), Ok(())),
+ );
+
+ assert!(matches!(
+ service.list_labels(link_id).await,
+ Err(error) if error == expected_error()
+ ));
+ assert_eq!(*arguments.lock().unwrap(), Some(("token".into(), link_id)));
+ assert_eq!(
+ *calls.lock().unwrap(),
+ vec![
+ Call::RateLimit(link_id, ApiOperationKind::ListLabels),
+ Call::Token(link_id, TokenFreshness::Cached),
+ ]
+ );
+}
+
+#[tokio::test]
+async fn create_label_uses_create_quota_and_forwards_name() {
+ let calls = call_log();
+ let repository = LabelClient::default();
+ let created_label_name = repository.created_label_name.clone();
+ let link_id = Uuid::new_v4();
+ let service = EmailApiClientServiceImpl::new(
+ repository,
+ FakeTokenSource::new(calls.clone(), Ok(AccessToken::new("token"))),
+ FakeRateLimiter::new(calls.clone(), Ok(())),
+ );
+
+ assert!(matches!(
+ service.create_label(link_id, "Projects").await,
+ Err(error) if error == expected_error()
+ ));
+ assert_eq!(*created_label_name.lock().unwrap(), Some("Projects".into()));
+ assert_eq!(
+ *calls.lock().unwrap(),
+ vec![
+ Call::RateLimit(link_id, ApiOperationKind::CreateLabel),
+ Call::Token(link_id, TokenFreshness::Cached),
+ ]
+ );
+}
+
+#[tokio::test]
+async fn delete_label_uses_delete_quota_and_forwards_provider_id() {
+ let calls = call_log();
+ let repository = LabelClient::default();
+ let deleted_label_id = repository.deleted_label_id.clone();
+ let link_id = Uuid::new_v4();
+ let service = EmailApiClientServiceImpl::new(
+ repository,
+ FakeTokenSource::new(calls.clone(), Ok(AccessToken::new("token"))),
+ FakeRateLimiter::new(calls.clone(), Ok(())),
+ );
+
+ assert_eq!(
+ service.delete_label(link_id, "label").await,
+ Err(expected_error())
+ );
+ assert_eq!(*deleted_label_id.lock().unwrap(), Some("label".into()));
+ assert_eq!(
+ *calls.lock().unwrap(),
+ vec![
+ Call::RateLimit(link_id, ApiOperationKind::DeleteLabel),
+ Call::Token(link_id, TokenFreshness::Cached),
+ ]
+ );
+}
diff --git a/crates/email_api_client/src/domain/service/messages.rs b/crates/email_api_client/src/domain/service/messages.rs
new file mode 100644
index 0000000000..8141541525
--- /dev/null
+++ b/crates/email_api_client/src/domain/service/messages.rs
@@ -0,0 +1,156 @@
+use models_email::email::service::message::Message;
+use uuid::Uuid;
+
+use super::super::models::{CalendarPart, EmailApiError, MessageWithCalendarParts, ThreadListPage};
+use super::super::ports::{
+ MailboxCalendarClient, MailboxMessageClient, ProviderRateLimiter, ProviderTokenSource,
+};
+use super::{ApiOperationKind, EmailApiClientServiceImpl};
+
+impl<R, T, L> EmailApiClientServiceImpl<R, T, L>
+where
+ R: MailboxMessageClient,
+ T: ProviderTokenSource,
+ L: ProviderRateLimiter,
+{
+ /// Fetches and normalizes one provider message, including any calendar
+ /// invitation parts, in a single provider read.
+ #[tracing::instrument(skip(self), err)]
+ pub async fn get_message(
+ &self,
+ link_id: Uuid,
+ provider_message_id: &str,
+ ) -> Result<Option<MessageWithCalendarParts>, EmailApiError> {
+ let access_token = self.prepare(link_id, ApiOperationKind::GetMessage).await?;
+
+ self.repository
+ .get_message(&access_token, link_id, provider_message_id)
+ .await
+ }
+
+ /// Fetches the provider label identifiers attached to one message.
+ #[tracing::instrument(skip(self), err)]
+ pub async fn get_message_label_ids(
+ &self,
+ link_id: Uuid,
+ provider_message_id: &str,
+ ) -> Result<Option<Vec<String>>, EmailApiError> {
+ let access_token = self.prepare(link_id, ApiOperationKind::GetMessage).await?;
+
+ self.repository
+ .get_message_label_ids(&access_token, provider_message_id)
+ .await
+ }
+
+ /// Lists message identifiers carrying all requested provider labels.
+ #[tracing::instrument(skip(self), err)]
+ pub async fn list_messages(
+ &self,
+ link_id: Uuid,
+ limit: u32,
+ label_ids: &[&str],
+ ) -> Result<Vec<String>, EmailApiError> {
+ let access_token = self
+ .prepare(link_id, ApiOperationKind::ListMessages)
+ .await?;
+
+ self.repository
+ .list_messages(&access_token, limit, label_ids)
+ .await
+ }
+
+ /// Lists message identifiers belonging to one provider thread.
+ #[tracing::instrument(skip(self), err)]
+ pub async fn get_message_ids_for_thread(
+ &self,
+ link_id: Uuid,
+ provider_thread_id: &str,
+ ) -> Result<Vec<String>, EmailApiError> {
+ let access_token = self.prepare(link_id, ApiOperationKind::GetThread).await?;
+
+ self.repository
+ .get_message_ids_for_thread(&access_token, provider_thread_id)
+ .await
+ }
+
+ /// Fetches and normalizes every message in one provider thread.
+ #[tracing::instrument(skip(self), err)]
+ pub async fn get_thread(
+ &self,
+ link_id: Uuid,
+ provider_thread_id: &str,
+ ) -> Result<Vec<Message>, EmailApiError> {
+ let access_token = self.prepare(link_id, ApiOperationKind::GetThread).await?;
+
+ self.repository
+ .get_thread(&access_token, link_id, provider_thread_id)
+ .await
+ }
+
+ /// Lists one page of provider threads.
+ #[tracing::instrument(skip(self), err)]
+ pub async fn list_threads(
+ &self,
+ link_id: Uuid,
+ limit: u32,
+ next_page_token: Option<&str>,
+ label_ids: &[&str],
+ ) -> Result<ThreadListPage, EmailApiError> {
+ let access_token = self.prepare(link_id, ApiOperationKind::ListThreads).await?;
+
+ self.repository
+ .list_threads(&access_token, limit, next_page_token, label_ids)
+ .await
+ }
+
+ /// Applies provider label additions and removals to one message.
+ #[tracing::instrument(skip(self), err)]
+ pub async fn modify_message_labels(
+ &self,
+ link_id: Uuid,
+ provider_message_id: &str,
+ labels_to_add: &[String],
+ labels_to_remove: &[String],
+ ) -> Result<(), EmailApiError> {
+ let access_token = self
+ .prepare(link_id, ApiOperationKind::ModifyMessageLabels)
+ .await?;
+
+ self.repository
+ .modify_message_labels(
+ &access_token,
+ provider_message_id,
+ labels_to_add,
+ labels_to_remove,
+ )
+ .await
+ }
+}
+
+impl<R, T, L> EmailApiClientServiceImpl<R, T, L>
+where
+ R: MailboxCalendarClient,
+ T: ProviderTokenSource,
+ L: ProviderRateLimiter,
+{
+ /// Finds calendar invitation parts in one provider message via a fresh
+ /// provider fetch.
+ ///
+ /// This charges a full message read; ingest paths that already fetched the
+ /// message should consume [`MessageWithCalendarParts::calendar_parts`]
+ /// instead. This lookup exists for durable re-extraction jobs.
+ #[tracing::instrument(skip(self), err)]
+ pub async fn get_calendar_parts(
+ &self,
+ link_id: Uuid,
+ provider_message_id: &str,
+ ) -> Result<Vec<CalendarPart>, EmailApiError> {
+ let access_token = self.prepare(link_id, ApiOperationKind::GetMessage).await?;
+ self.repository
+ .get_calendar_parts(&access_token, provider_message_id)
+ .await
+ }
+}
+
+#[cfg(test)]
+mod test;
diff --git a/crates/email_api_client/src/domain/service/messages/test.rs b/crates/email_api_client/src/domain/service/messages/test.rs
new file mode 100644
index 0000000000..1efc48a741
--- /dev/null
+++ b/crates/email_api_client/src/domain/service/messages/test.rs
@@ -0,0 +1,249 @@
+use std::sync::{Arc, Mutex};
+
+use models_email::email::service::message::Message;
+use uuid::Uuid;
+
+use super::super::test_support::{Call, FakeRateLimiter, FakeTokenSource, call_log};
+use super::*;
+use crate::domain::models::{AccessToken, TokenFreshness};
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+enum MessageCall {
+ Message(Uuid, String),
+ MessageLabels(String),
+ Messages(u32, Vec<String>),
+ MessageIdsForThread(String),
+ Thread(Uuid, String),
+ Threads(u32, Option<String>, Vec<String>),
+ ModifyLabels(String, Vec<String>, Vec<String>),
+}
+
+#[derive(Clone, Default)]
+struct MessageClient {
+ call: Arc<Mutex<Option<MessageCall>>>,
+}
+
+impl MessageClient {
+ fn record(&self, access_token: &AccessToken, call: MessageCall) -> EmailApiError {
+ assert_eq!(access_token.expose_secret(), "token");
+ *self.call.lock().unwrap() = Some(call);
+ expected_error()
+ }
+}
+
+impl MailboxMessageClient for MessageClient {
+ async fn get_message(
+ &self,
+ access_token: &AccessToken,
+ link_id: Uuid,
+ message_id: &str,
+ ) -> Result<Option<crate::domain::models::MessageWithCalendarParts>, EmailApiError> {
+ Err(self.record(
+ access_token,
+ MessageCall::Message(link_id, message_id.to_string()),
+ ))
+ }
+
+ async fn get_message_label_ids(
+ &self,
+ access_token: &AccessToken,
+ message_id: &str,
+ ) -> Result<Option<Vec<String>>, EmailApiError> {
+ Err(self.record(
+ access_token,
+ MessageCall::MessageLabels(message_id.to_string()),
+ ))
+ }
+
+ async fn list_messages(
+ &self,
+ access_token: &AccessToken,
+ limit: u32,
+ label_ids: &[&str],
+ ) -> Result<Vec<String>, EmailApiError> {
+ Err(self.record(
+ access_token,
+ MessageCall::Messages(
+ limit,
+ label_ids.iter().map(|label| (*label).to_string()).collect(),
+ ),
+ ))
+ }
+
+ async fn get_message_ids_for_thread(
+ &self,
+ access_token: &AccessToken,
+ thread_id: &str,
+ ) -> Result<Vec<String>, EmailApiError> {
+ Err(self.record(
+ access_token,
+ MessageCall::MessageIdsForThread(thread_id.to_string()),
+ ))
+ }
+
+ async fn get_thread(
+ &self,
+ access_token: &AccessToken,
+ link_id: Uuid,
+ thread_id: &str,
+ ) -> Result<Vec<Message>, EmailApiError> {
+ Err(self.record(
+ access_token,
+ MessageCall::Thread(link_id, thread_id.to_string()),
+ ))
+ }
+
+ async fn list_threads(
+ &self,
+ access_token: &AccessToken,
+ limit: u32,
+ page_token: Option<&str>,
+ label_ids: &[&str],
+ ) -> Result<ThreadListPage, EmailApiError> {
+ Err(self.record(
+ access_token,
+ MessageCall::Threads(
+ limit,
+ page_token.map(str::to_string),
+ label_ids.iter().map(|label| (*label).to_string()).collect(),
+ ),
+ ))
+ }
+
+ async fn modify_message_labels(
+ &self,
+ access_token: &AccessToken,
+ message_id: &str,
+ labels_to_add: &[String],
+ labels_to_remove: &[String],
+ ) -> Result<(), EmailApiError> {
+ Err(self.record(
+ access_token,
+ MessageCall::ModifyLabels(
+ message_id.to_string(),
+ labels_to_add.to_vec(),
+ labels_to_remove.to_vec(),
+ ),
+ ))
+ }
+}
+
+fn expected_error() -> EmailApiError {
+ EmailApiError::Permanent {
+ message: "provider error".to_string(),
+ }
+}
+
+async fn assert_call<F, E>(operation: ApiOperationKind, expected_repository_call: E, invoke: F)
+where
+ E: FnOnce(Uuid) -> MessageCall,
+ F: AsyncFnOnce(
+ &EmailApiClientServiceImpl<MessageClient, FakeTokenSource, FakeRateLimiter>,
+ Uuid,
+ ) -> Result<(), EmailApiError>,
+{
+ let calls = call_log();
+ let repository = MessageClient::default();
+ let repository_call = repository.call.clone();
+ let link_id = Uuid::new_v4();
+ let service = EmailApiClientServiceImpl::new(
+ repository,
+ FakeTokenSource::new(calls.clone(), Ok(AccessToken::new("token"))),
+ FakeRateLimiter::new(calls.clone(), Ok(())),
+ );
+
+ assert_eq!(invoke(&service, link_id).await, Err(expected_error()));
+ assert_eq!(
+ *repository_call.lock().unwrap(),
+ Some(expected_repository_call(link_id))
+ );
+ assert_eq!(
+ *calls.lock().unwrap(),
+ vec![
+ Call::RateLimit(link_id, operation),
+ Call::Token(link_id, TokenFreshness::Cached),
+ ]
+ );
+}
+
+#[tokio::test]
+async fn message_reads_use_correct_operation_kinds_and_forward_parameters() {
+ assert_call(
+ ApiOperationKind::GetMessage,
+ |link_id| MessageCall::Message(link_id, "message".into()),
+ async |service, link_id| service.get_message(link_id, "message").await.map(|_| ()),
+ )
+ .await;
+ assert_call(
+ ApiOperationKind::GetMessage,
+ |_| MessageCall::MessageLabels("message".into()),
+ async |service, link_id| {
+ service
+ .get_message_label_ids(link_id, "message")
+ .await
+ .map(|_| ())
+ },
+ )
+ .await;
+ assert_call(
+ ApiOperationKind::ListMessages,
+ |_| MessageCall::Messages(25, vec!["inbox".into(), "unread".into()]),
+ async |service, link_id| {
+ service
+ .list_messages(link_id, 25, &["inbox", "unread"])
+ .await
+ .map(|_| ())
+ },
+ )
+ .await;
+ assert_call(
+ ApiOperationKind::GetThread,
+ |_| MessageCall::MessageIdsForThread("thread".into()),
+ async |service, link_id| {
+ service
+ .get_message_ids_for_thread(link_id, "thread")
+ .await
+ .map(|_| ())
+ },
+ )
+ .await;
+ assert_call(
+ ApiOperationKind::GetThread,
+ |link_id| MessageCall::Thread(link_id, "thread".into()),
+ async |service, link_id| service.get_thread(link_id, "thread").await.map(|_| ()),
+ )
+ .await;
+ assert_call(
+ ApiOperationKind::ListThreads,
+ |_| {
+ MessageCall::Threads(
+ 50,
+ Some("next-page".into()),
+ vec!["inbox".into(), "starred".into()],
+ )
+ },
+ async |service, link_id| {
+ service
+ .list_threads(link_id, 50, Some("next-page"), &["inbox", "starred"])
+ .await
+ .map(|_| ())
+ },
+ )
+ .await;
+ assert_call(
+ ApiOperationKind::ModifyMessageLabels,
+ |_| {
+ MessageCall::ModifyLabels(
+ "message".into(),
+ vec!["starred".into()],
+ vec!["unread".into()],
+ )
+ },
+ async |service, link_id| {
+ service
+ .modify_message_labels(link_id, "message", &["starred".into()], &["unread".into()])
+ .await
+ },
+ )
+ .await;
+}
diff --git a/crates/email_api_client/src/domain/service/mod.rs b/crates/email_api_client/src/domain/service/mod.rs
new file mode 100644
index 0000000000..a8d6908afc
--- /dev/null
+++ b/crates/email_api_client/src/domain/service/mod.rs
@@ -0,0 +1,87 @@
+//! Provider-neutral email API orchestration.
+
+use uuid::Uuid;
+
+use super::models::{AccessToken, ApiOperationKind, EmailApiError, TokenError, TokenFreshness};
+use super::ports::{ProviderRateLimiter, ProviderTokenSource};
+
+mod attachments;
+mod blocklist;
+mod contacts;
+mod labels;
+mod messages;
+mod send;
+mod subscription;
+mod sync;
+
+#[cfg(test)]
+mod test;
+#[cfg(test)]
+mod test_support;
+
+/// Orchestrates provider-neutral email operations over capability ports.
+#[derive(Clone)]
+pub struct EmailApiClientServiceImpl<R, T, L> {
+ repository: R,
+ token_source: T,
+ rate_limiter: L,
+}
+
+impl<R, T, L> EmailApiClientServiceImpl<R, T, L> {
+ /// Creates an email API service from its provider and infrastructure ports.
+ pub fn new(repository: R, token_source: T, rate_limiter: L) -> Self {
+ Self {
+ repository,
+ token_source,
+ rate_limiter,
+ }
+ }
+}
+
+impl<R, T, L> EmailApiClientServiceImpl<R, T, L>
+where
+ T: ProviderTokenSource,
+ L: ProviderRateLimiter,
+{
+ /// Acquires an access token for health probes or provider-adjacent work.
+ ///
+ /// Normal email operations acquire tokens internally. This explicit escape
+ /// hatch supports callers that need to verify a grant or use the same grant
+ /// with another Google API.
+ #[tracing::instrument(skip(self), err)]
+ pub async fn get_access_token(
+ &self,
+ link_id: Uuid,
+ freshness: TokenFreshness,
+ ) -> Result<AccessToken, EmailApiError> {
+ self.token_source
+ .get_access_token(link_id, freshness)
+ .await
+ .map_err(map_token_error)
+ }
+
+ async fn prepare(
+ &self,
+ link_id: Uuid,
+ operation: ApiOperationKind,
+ ) -> Result<AccessToken, EmailApiError> {
+ // Check the cheap local limiter first: under throttling this avoids
+ // paying the full token dance (SELECT + Redis + possible auth-service
+ // refresh + health write) per refused attempt. The limiter does not
+ // consume provider quota on denial.
+ self.rate_limiter
+ .check_rate_limit(link_id, operation)
+ .await
+ .map_err(EmailApiError::from)?;
+
+ self.get_access_token(link_id, TokenFreshness::Cached).await
+ }
+}
+
+fn map_token_error(error: TokenError) -> EmailApiError {
+ match error {
+ TokenError::ReauthRequired => EmailApiError::AuthRequired,
+ TokenError::Transient { message } => EmailApiError::Transient { message },
+ TokenError::Permanent { message } => EmailApiError::Permanent { message },
+ }
+}
diff --git a/crates/email_api_client/src/domain/service/send.rs b/crates/email_api_client/src/domain/service/send.rs
new file mode 100644
index 0000000000..b6c870c5dc
--- /dev/null
+++ b/crates/email_api_client/src/domain/service/send.rs
@@ -0,0 +1,30 @@
+use uuid::Uuid;
+
+use super::super::models::{EmailApiError, SendRequest, SentIds};
+use super::super::ports::{MailboxSendClient, ProviderRateLimiter, ProviderTokenSource};
+use super::{ApiOperationKind, EmailApiClientServiceImpl};
+
+impl<R, T, L> EmailApiClientServiceImpl<R, T, L>
+where
+ R: MailboxSendClient,
+ T: ProviderTokenSource,
+ L: ProviderRateLimiter,
+{
+ /// Sends a message through the linked mailbox.
+ #[tracing::instrument(skip(self, request), err)]
+ pub async fn send_message(
+ &self,
+ link_id: Uuid,
+ request: &SendRequest,
+ provider_thread_id: Option<&str>,
+ ) -> Result<SentIds, EmailApiError> {
+ let access_token = self.prepare(link_id, ApiOperationKind::SendMessage).await?;
+
+ self.repository
+ .send_message(&access_token, request, provider_thread_id)
+ .await
+ }
+}
+
+#[cfg(test)]
+mod test;
diff --git a/crates/email_api_client/src/domain/service/send/test.rs b/crates/email_api_client/src/domain/service/send/test.rs
new file mode 100644
index 0000000000..1741c62a36
--- /dev/null
+++ b/crates/email_api_client/src/domain/service/send/test.rs
@@ -0,0 +1,96 @@
+use models_email::email::service::address::ContactInfo;
+use models_email::email::service::message::MessageToSend;
+use uuid::Uuid;
+
+use super::super::super::models::{AccessToken, SendRequest, SentIds, TokenFreshness};
+use super::super::super::ports::MailboxSendClient;
+use super::super::test_support::{Call, FakeRateLimiter, FakeTokenSource, call_log};
+use super::EmailApiClientServiceImpl;
+
+#[derive(Clone)]
+struct SendClient {
+ calls: super::super::test_support::CallLog,
+}
+
+impl MailboxSendClient for SendClient {
+ async fn send_message(
+ &self,
+ access_token: &AccessToken,
+ request: &SendRequest,
+ provider_thread_id: Option<&str>,
+ ) -> Result<SentIds, super::super::super::models::EmailApiError> {
+ assert_eq!(access_token.expose_secret(), "access-token");
+ assert_eq!(request.message.subject, "subject");
+ assert_eq!(provider_thread_id, Some("thread-1"));
+ self.calls
+ .lock()
+ .unwrap()
+ .push(Call::Repository("send_message"));
+ Ok(SentIds {
+ provider_message_id: "message-1".to_string(),
+ provider_thread_id: "thread-1".to_string(),
+ })
+ }
+}
+
+#[tokio::test]
+async fn send_uses_send_cost_and_returns_ids_without_mutating_message() {
+ let calls = call_log();
+ let service = EmailApiClientServiceImpl::new(
+ SendClient {
+ calls: calls.clone(),
+ },
+ FakeTokenSource::new(calls.clone(), Ok(AccessToken::new("access-token"))),
+ FakeRateLimiter::new(calls.clone(), Ok(())),
+ );
+ let request = send_request();
+
+ let sent_ids = service
+ .send_message(Uuid::nil(), &request, Some("thread-1"))
+ .await
+ .unwrap();
+
+ assert_eq!(sent_ids.provider_message_id, "message-1");
+ assert_eq!(sent_ids.provider_thread_id, "thread-1");
+ assert_eq!(request.message.provider_id, None);
+ assert_eq!(request.message.provider_thread_id, None);
+ assert_eq!(request.message.subject, "subject");
+ assert_eq!(
+ *calls.lock().unwrap(),
+ vec![
+ Call::RateLimit(Uuid::nil(), super::ApiOperationKind::SendMessage),
+ Call::Token(Uuid::nil(), TokenFreshness::Cached),
+ Call::Repository("send_message"),
+ ]
+ );
+}
+
+fn send_request() -> SendRequest {
+ SendRequest {
+ message: MessageToSend {
+ db_id: None,
+ provider_id: None,
+ replying_to_id: None,
+ provider_thread_id: None,
+ thread_db_id: None,
+ link_id: Uuid::nil(),
+ subject: "subject".to_string(),
+ to: None,
+ cc: None,
+ bcc: None,
+ body_text: Some("body".to_string()),
+ body_html: None,
+ body_macro: None,
+ attachments: None,
+ headers_json: None,
+ send_time: None,
+ },
+ from: ContactInfo {
+ email: "[email protected]".to_string(),
+ name: None,
+ photo_url: None,
+ },
+ parent_message_id: None,
+ references: None,
+ }
+}
diff --git a/crates/email_api_client/src/domain/service/subscription.rs b/crates/email_api_client/src/domain/service/subscription.rs
new file mode 100644
index 0000000000..e9338c1630
--- /dev/null
+++ b/crates/email_api_client/src/domain/service/subscription.rs
@@ -0,0 +1,75 @@
+use models_email::service::link::Link;
+use uuid::Uuid;
+
+use super::super::models::{EmailApiError, ProviderSubscription, TokenFreshness};
+use super::super::ports::{MailboxSubscriptionClient, ProviderRateLimiter, ProviderTokenSource};
+use super::{ApiOperationKind, EmailApiClientServiceImpl};
+
+impl<R, T, L> EmailApiClientServiceImpl<R, T, L>
+where
+ R: MailboxSubscriptionClient,
+ T: ProviderTokenSource,
+ L: ProviderRateLimiter,
+{
+ /// Registers or renews the linked mailbox's notification subscription.
+ #[tracing::instrument(skip(self), err)]
+ pub async fn register_subscription(
+ &self,
+ link_id: Uuid,
+ ) -> Result<ProviderSubscription, EmailApiError> {
+ let access_token = self.prepare(link_id, ApiOperationKind::Subscribe).await?;
+ self.repository.subscribe(&access_token).await
+ }
+
+ /// Registers a subscription using a freshly fetched token.
+ ///
+ /// This is intended for mailbox initialization, where a cached access token
+ /// could outlive a revoked provider grant.
+ #[tracing::instrument(skip(self, link), fields(link_id = %link.id), err)]
+ pub async fn register_subscription_without_cache(
+ &self,
+ link: &Link,
+ ) -> Result<ProviderSubscription, EmailApiError> {
+ self.rate_limiter
+ .check_rate_limit(link.id, ApiOperationKind::Subscribe)
+ .await
+ .map_err(EmailApiError::from)?;
+ let access_token = self
+ .token_source
+ .get_access_token_for_link(link, TokenFreshness::Fresh)
+ .await
+ .map_err(super::map_token_error)?;
+
+ self.repository.subscribe(&access_token).await
+ }
+
+ /// Stops the linked mailbox's notification subscription.
+ #[tracing::instrument(skip(self), err)]
+ pub async fn stop_subscription(&self, link_id: Uuid) -> Result<(), EmailApiError> {
+ let access_token = self.prepare(link_id, ApiOperationKind::Unsubscribe).await?;
+ self.repository.unsubscribe(&access_token).await
+ }
+
+ /// Stops the mailbox's subscription without token-health side effects.
+ ///
+ /// This is intended for link teardown: a grant that died since the last
+ /// probe must not set `needs_reauth` or fan out a reauthorization
+ /// notification for an inbox that is being intentionally removed.
+ #[tracing::instrument(skip(self, link), fields(link_id = %link.id), err)]
+ pub async fn stop_subscription_for_link(&self, link: &Link) -> Result<(), EmailApiError> {
+ self.rate_limiter
+ .check_rate_limit(link.id, ApiOperationKind::Unsubscribe)
+ .await
+ .map_err(EmailApiError::from)?;
+ let access_token = self
+ .token_source
+ .get_access_token_health_neutral(link, TokenFreshness::Cached)
+ .await
+ .map_err(super::map_token_error)?;
+
+ self.repository.unsubscribe(&access_token).await
+ }
+}
+
+#[cfg(test)]
+mod test;
diff --git a/crates/email_api_client/src/domain/service/subscription/test.rs b/crates/email_api_client/src/domain/service/subscription/test.rs
new file mode 100644
index 0000000000..037669385d
--- /dev/null
+++ b/crates/email_api_client/src/domain/service/subscription/test.rs
@@ -0,0 +1,128 @@
+use chrono::{TimeZone, Utc};
+use models_email::service::link::{Link, UserProvider};
+use uuid::Uuid;
+
+use super::super::super::models::{
+ AccessToken, EmailApiError, ProviderSubscription, SyncCursor, TokenFreshness,
+};
+use super::super::super::ports::MailboxSubscriptionClient;
+use super::super::test_support::{Call, FakeRateLimiter, FakeTokenSource, call_log};
+use super::EmailApiClientServiceImpl;
+
+#[derive(Clone)]
+struct SubscriptionClient {
+ calls: super::super::test_support::CallLog,
+}
+
+impl MailboxSubscriptionClient for SubscriptionClient {
+ async fn subscribe(&self, _: &AccessToken) -> Result<ProviderSubscription, EmailApiError> {
+ self.record("subscribe");
+ Ok(ProviderSubscription::new(
+ SyncCursor::gmail("cursor-1"),
+ Utc.timestamp_opt(1_800_000_000, 0).unwrap(),
+ ))
+ }
+
+ async fn unsubscribe(&self, _: &AccessToken) -> Result<(), EmailApiError> {
+ self.record("unsubscribe");
+ Ok(())
+ }
+}
+
+impl SubscriptionClient {
+ fn record(&self, method: &'static str) {
+ self.calls.lock().unwrap().push(Call::Repository(method));
+ }
+}
+
+#[tokio::test]
+async fn registration_and_stop_use_matching_costs_and_operations() {
+ for (register, operation, repository_call) in [
+ (true, super::ApiOperationKind::Subscribe, "subscribe"),
+ (false, super::ApiOperationKind::Unsubscribe, "unsubscribe"),
+ ] {
+ let calls = call_log();
+ let service = service(calls.clone());
+
+ if register {
+ let subscription = service.register_subscription(Uuid::nil()).await.unwrap();
+ assert_eq!(subscription.cursor, SyncCursor::gmail("cursor-1"));
+ } else {
+ service.stop_subscription(Uuid::nil()).await.unwrap();
+ }
+
+ assert_eq!(
+ *calls.lock().unwrap(),
+ vec![
+ Call::RateLimit(Uuid::nil(), operation),
+ Call::Token(Uuid::nil(), TokenFreshness::Cached),
+ Call::Repository(repository_call),
+ ]
+ );
+ }
+}
+
+#[tokio::test]
+async fn registration_can_bypass_the_token_cache_for_initialization() {
+ let calls = call_log();
+ let service = service(calls.clone());
+
+ service
+ .register_subscription_without_cache(&link())
+ .await
+ .unwrap();
+
+ assert_eq!(
+ *calls.lock().unwrap(),
+ vec![
+ Call::RateLimit(Uuid::nil(), super::ApiOperationKind::Subscribe),
+ Call::Token(Uuid::nil(), TokenFreshness::Fresh),
+ Call::Repository("subscribe"),
+ ]
+ );
+}
+
+#[tokio::test]
+async fn teardown_stop_uses_the_health_neutral_token_path() {
+ let calls = call_log();
+ let service = service(calls.clone());
+
+ service.stop_subscription_for_link(&link()).await.unwrap();
+
+ assert_eq!(
+ *calls.lock().unwrap(),
+ vec![
+ Call::RateLimit(Uuid::nil(), super::ApiOperationKind::Unsubscribe),
+ Call::HealthNeutralToken(Uuid::nil(), TokenFreshness::Cached),
+ Call::Repository("unsubscribe"),
+ ]
+ );
+}
+
+fn link() -> Link {
+ Link {
+ id: Uuid::nil(),
+ macro_id: "macro|[email protected]".to_string().try_into().unwrap(),
+ fusionauth_user_id: "fusion-user-id".to_string(),
+ email_address: "[email protected]".to_string().try_into().unwrap(),
+ provider: UserProvider::Gmail,
+ is_sync_active: true,
+ is_primary: true,
+ needs_reauth: false,
+ last_sync_error_at: None,
+ created_at: Default::default(),
+ updated_at: Default::default(),
+ }
+}
+
+fn service(
+ calls: super::super::test_support::CallLog,
+) -> EmailApiClientServiceImpl<SubscriptionClient, FakeTokenSource, FakeRateLimiter> {
+ EmailApiClientServiceImpl::new(
+ SubscriptionClient {
+ calls: calls.clone(),
+ },
+ FakeTokenSource::new(calls.clone(), Ok(AccessToken::new("access-token"))),
+ FakeRateLimiter::new(calls, Ok(())),
+ )
+}
diff --git a/crates/email_api_client/src/domain/service/sync.rs b/crates/email_api_client/src/domain/service/sync.rs
new file mode 100644
index 0000000000..92750574e6
--- /dev/null
+++ b/crates/email_api_client/src/domain/service/sync.rs
@@ -0,0 +1,35 @@
+use uuid::Uuid;
+
+use super::super::models::{ChangeBatch, EmailApiError, SyncCursor};
+use super::super::ports::{MailboxSyncClient, ProviderRateLimiter, ProviderTokenSource};
+use super::{ApiOperationKind, EmailApiClientServiceImpl};
+
+impl<R, T, L> EmailApiClientServiceImpl<R, T, L>
+where
+ R: MailboxSyncClient,
+ T: ProviderTokenSource,
+ L: ProviderRateLimiter,
+{
+ /// Returns the number of threads reported by a linked mailbox.
+ #[tracing::instrument(skip(self), err)]
+ pub async fn get_thread_count(&self, link_id: Uuid) -> Result<u64, EmailApiError> {
+ let access_token = self.prepare(link_id, ApiOperationKind::GetProfile).await?;
+
+ self.repository.get_thread_count(&access_token).await
+ }
+
+ /// Lists mailbox changes following `cursor`.
+ #[tracing::instrument(skip(self), err)]
+ pub async fn list_changes(
+ &self,
+ link_id: Uuid,
+ cursor: &SyncCursor,
+ ) -> Result<ChangeBatch, EmailApiError> {
+ let access_token = self.prepare(link_id, ApiOperationKind::ListChanges).await?;
+
+ self.repository.list_changes(&access_token, cursor).await
+ }
+}
+
+#[cfg(test)]
+mod test;
diff --git a/crates/email_api_client/src/domain/service/sync/test.rs b/crates/email_api_client/src/domain/service/sync/test.rs
new file mode 100644
index 0000000000..57feb42077
--- /dev/null
+++ b/crates/email_api_client/src/domain/service/sync/test.rs
@@ -0,0 +1,86 @@
+use std::sync::{Arc, Mutex};
+
+use uuid::Uuid;
+
+use super::super::test_support::{Call, FakeRateLimiter, FakeTokenSource, call_log};
+use super::*;
+use crate::domain::models::{AccessToken, InboxChanges, TokenFreshness};
+
+#[derive(Clone, Default)]
+struct SyncClient {
+ cursor: Arc<Mutex<Option<String>>>,
+}
+
+impl MailboxSyncClient for SyncClient {
+ async fn get_thread_count(&self, access_token: &AccessToken) -> Result<u64, EmailApiError> {
+ assert_eq!(access_token.expose_secret(), "token");
+ Ok(42)
+ }
+
+ async fn list_changes(
+ &self,
+ access_token: &AccessToken,
+ cursor: &SyncCursor,
+ ) -> Result<ChangeBatch, EmailApiError> {
+ assert_eq!(access_token.expose_secret(), "token");
+ *self.cursor.lock().unwrap() = Some(cursor.as_str().to_string());
+ Ok(ChangeBatch::new(
+ InboxChanges::default(),
+ SyncCursor::gmail("next"),
+ ))
+ }
+}
+
+fn service(
+ repository: SyncClient,
+ calls: &super::super::test_support::CallLog,
+) -> EmailApiClientServiceImpl<SyncClient, FakeTokenSource, FakeRateLimiter> {
+ EmailApiClientServiceImpl::new(
+ repository,
+ FakeTokenSource::new(calls.clone(), Ok(AccessToken::new("token"))),
+ FakeRateLimiter::new(calls.clone(), Ok(())),
+ )
+}
+
+#[tokio::test]
+async fn get_thread_count_uses_profile_quota_and_forwards_link_id() {
+ let calls = call_log();
+ let link_id = Uuid::new_v4();
+
+ assert_eq!(
+ service(SyncClient::default(), &calls)
+ .get_thread_count(link_id)
+ .await,
+ Ok(42)
+ );
+ assert_eq!(
+ *calls.lock().unwrap(),
+ vec![
+ Call::RateLimit(link_id, ApiOperationKind::GetProfile),
+ Call::Token(link_id, TokenFreshness::Cached),
+ ]
+ );
+}
+
+#[tokio::test]
+async fn list_changes_uses_changes_quota_and_forwards_cursor() {
+ let calls = call_log();
+ let repository = SyncClient::default();
+ let captured_cursor = repository.cursor.clone();
+ let link_id = Uuid::new_v4();
+ let cursor = SyncCursor::gmail("cursor");
+
+ let result = service(repository, &calls)
+ .list_changes(link_id, &cursor)
+ .await;
+
+ assert_eq!(result.unwrap().next_cursor, SyncCursor::gmail("next"));
+ assert_eq!(*captured_cursor.lock().unwrap(), Some("cursor".into()));
+ assert_eq!(
+ *calls.lock().unwrap(),
+ vec![
+ Call::RateLimit(link_id, ApiOperationKind::ListChanges),
+ Call::Token(link_id, TokenFreshness::Cached),
+ ]
+ );
+}
diff --git a/crates/email_api_client/src/domain/service/test.rs b/crates/email_api_client/src/domain/service/test.rs
new file mode 100644
index 0000000000..cf44d8a664
--- /dev/null
+++ b/crates/email_api_client/src/domain/service/test.rs
@@ -0,0 +1,117 @@
+use std::time::Duration;
+
+use uuid::Uuid;
+
+use super::super::models::{
+ AccessToken, ApiOperationKind, EmailApiError, RateLimitRefusal, TokenError, TokenFreshness,
+};
+use super::EmailApiClientServiceImpl;
+use super::test_support::{Call, FakeRateLimiter, FakeRepository, FakeTokenSource, call_log};
+
+#[tokio::test]
+async fn token_failure_stops_before_repository_after_the_quota_check() {
+ let calls = call_log();
+ let service = EmailApiClientServiceImpl::new(
+ FakeRepository::new(calls.clone()),
+ FakeTokenSource::new(calls.clone(), Err(TokenError::ReauthRequired)),
+ FakeRateLimiter::new(calls.clone(), Ok(())),
+ );
+
+ let result = service
+ .prepare(Uuid::nil(), ApiOperationKind::GetMessage)
+ .await;
+
+ assert_eq!(result, Err(EmailApiError::AuthRequired));
+ assert_eq!(
+ *calls.lock().unwrap(),
+ vec![
+ Call::RateLimit(Uuid::nil(), ApiOperationKind::GetMessage),
+ Call::Token(Uuid::nil(), TokenFreshness::Cached),
+ ]
+ );
+}
+
+#[tokio::test]
+async fn rate_limit_refusal_stops_before_the_token_dance_and_repository() {
+ let calls = call_log();
+ let retry_after = Duration::from_secs(17);
+ let service = EmailApiClientServiceImpl::new(
+ FakeRepository::new(calls.clone()),
+ FakeTokenSource::new(calls.clone(), Ok(AccessToken::new("access-token"))),
+ FakeRateLimiter::new(calls.clone(), Err(RateLimitRefusal::new(Some(retry_after)))),
+ );
+
+ let result = service
+ .prepare(Uuid::nil(), ApiOperationKind::SendMessage)
+ .await;
+
+ assert_eq!(
+ result,
+ Err(EmailApiError::RateLimited {
+ retry_after: Some(retry_after),
+ origin: crate::domain::models::RateLimitOrigin::Local,
+ })
+ );
+ // A refused attempt must not pay the token acquisition (SELECT + Redis +
+ // possible auth-service refresh + health write).
+ assert_eq!(
+ *calls.lock().unwrap(),
+ vec![Call::RateLimit(Uuid::nil(), ApiOperationKind::SendMessage)]
+ );
+}
+
+#[tokio::test]
+async fn explicit_token_probe_honors_requested_freshness_without_quota_check() {
+ let calls = call_log();
+ let service = EmailApiClientServiceImpl::new(
+ FakeRepository::new(calls.clone()),
+ FakeTokenSource::new(calls.clone(), Ok(AccessToken::new("access-token"))),
+ FakeRateLimiter::new(calls.clone(), Ok(())),
+ );
+
+ let result = service
+ .get_access_token(Uuid::nil(), TokenFreshness::Fresh)
+ .await;
+
+ assert_eq!(result.unwrap().expose_secret(), "access-token");
+ assert_eq!(
+ *calls.lock().unwrap(),
+ vec![Call::Token(Uuid::nil(), TokenFreshness::Fresh)]
+ );
+}
+
+#[tokio::test]
+async fn token_errors_preserve_transient_and_permanent_classification() {
+ for (token_error, expected) in [
+ (
+ TokenError::Transient {
+ message: "temporarily unavailable".to_string(),
+ },
+ EmailApiError::Transient {
+ message: "temporarily unavailable".to_string(),
+ },
+ ),
+ (
+ TokenError::Permanent {
+ message: "invalid token configuration".to_string(),
+ },
+ EmailApiError::Permanent {
+ message: "invalid token configuration".to_string(),
+ },
+ ),
+ ] {
+ let calls = call_log();
+ let service = EmailApiClientServiceImpl::new(
+ FakeRepository::new(calls.clone()),
+ FakeTokenSource::new(calls.clone(), Err(token_error)),
+ FakeRateLimiter::new(calls, Ok(())),
+ );
+
+ assert_eq!(
+ service
+ .get_access_token(Uuid::nil(), TokenFreshness::Cached)
+ .await,
+ Err(expected)
+ );
+ }
+}
diff --git a/crates/email_api_client/src/domain/service/test_support.rs b/crates/email_api_client/src/domain/service/test_support.rs
new file mode 100644
index 0000000000..15d9be3420
--- /dev/null
+++ b/crates/email_api_client/src/domain/service/test_support.rs
@@ -0,0 +1,292 @@
+use std::sync::{Arc, Mutex};
+
+use models_email::email::service::label::Label;
+use models_email::email::service::message::Message;
+use models_email::service::contact::{Contact, ContactList};
+use uuid::Uuid;
+
+use super::super::models::{
+ AccessToken, ApiOperationKind, ChangeBatch, EmailApiError, ProviderSubscription,
+ RateLimitRefusal, SendRequest, SentIds, SyncCursor, ThreadListPage, TokenError, TokenFreshness,
+};
+use super::super::ports::{
+ MailboxAttachmentClient, MailboxBlocklistClient, MailboxContactsClient, MailboxLabelClient,
+ MailboxMessageClient, MailboxSendClient, MailboxSubscriptionClient, MailboxSyncClient,
+ ProviderRateLimiter, ProviderTokenSource,
+};
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub(super) enum Call {
+ Token(Uuid, TokenFreshness),
+ HealthNeutralToken(Uuid, TokenFreshness),
+ RateLimit(Uuid, ApiOperationKind),
+ Repository(&'static str),
+}
+
+pub(super) type CallLog = Arc<Mutex<Vec<Call>>>;
+
+pub(super) fn call_log() -> CallLog {
+ Arc::new(Mutex::new(Vec::new()))
+}
+
+#[derive(Clone)]
+pub(super) struct FakeTokenSource {
+ calls: CallLog,
+ result: Result<AccessToken, TokenError>,
+}
+
+impl FakeTokenSource {
+ pub(super) fn new(calls: CallLog, result: Result<AccessToken, TokenError>) -> Self {
+ Self { calls, result }
+ }
+}
+
+impl ProviderTokenSource for FakeTokenSource {
+ async fn get_access_token(
+ &self,
+ link_id: Uuid,
+ freshness: TokenFreshness,
+ ) -> Result<AccessToken, TokenError> {
+ self.calls
+ .lock()
+ .unwrap()
+ .push(Call::Token(link_id, freshness));
+ self.result.clone()
+ }
+
+ async fn get_access_token_for_link(
+ &self,
+ link: &models_email::service::link::Link,
+ freshness: TokenFreshness,
+ ) -> Result<AccessToken, TokenError> {
+ self.calls
+ .lock()
+ .unwrap()
+ .push(Call::Token(link.id, freshness));
+ self.result.clone()
+ }
+
+ async fn get_access_token_health_neutral(
+ &self,
+ link: &models_email::service::link::Link,
+ freshness: TokenFreshness,
+ ) -> Result<AccessToken, TokenError> {
+ self.calls
+ .lock()
+ .unwrap()
+ .push(Call::HealthNeutralToken(link.id, freshness));
+ self.result.clone()
+ }
+}
+
+#[derive(Clone)]
+pub(super) struct FakeRateLimiter {
+ calls: CallLog,
+ result: Result<(), RateLimitRefusal>,
+}
+
+impl FakeRateLimiter {
+ pub(super) fn new(calls: CallLog, result: Result<(), RateLimitRefusal>) -> Self {
+ Self { calls, result }
+ }
+}
+
+impl ProviderRateLimiter for FakeRateLimiter {
+ async fn check_rate_limit(
+ &self,
+ link_id: Uuid,
+ operation: ApiOperationKind,
+ ) -> Result<(), RateLimitRefusal> {
+ self.calls
+ .lock()
+ .unwrap()
+ .push(Call::RateLimit(link_id, operation));
+ self.result.clone()
+ }
+}
+
+#[derive(Clone)]
+pub(super) struct FakeRepository {
+ calls: CallLog,
+}
+
+impl FakeRepository {
+ pub(super) fn new(calls: CallLog) -> Self {
+ Self { calls }
+ }
+
+ fn unavailable<T>(&self, method: &'static str) -> Result<T, EmailApiError> {
+ self.calls.lock().unwrap().push(Call::Repository(method));
+ Err(EmailApiError::Permanent {
+ message: "fake repository response is not configured".to_string(),
+ })
+ }
+}
+
+impl MailboxSyncClient for FakeRepository {
+ async fn get_thread_count(&self, _: &AccessToken) -> Result<u64, EmailApiError> {
+ self.unavailable("get_thread_count")
+ }
+
+ async fn list_changes(
+ &self,
+ _: &AccessToken,
+ _: &SyncCursor,
+ ) -> Result<ChangeBatch, EmailApiError> {
+ self.unavailable("list_changes")
+ }
+}
+
+impl MailboxSubscriptionClient for FakeRepository {
+ async fn subscribe(&self, _: &AccessToken) -> Result<ProviderSubscription, EmailApiError> {
+ self.unavailable("subscribe")
+ }
+
+ async fn unsubscribe(&self, _: &AccessToken) -> Result<(), EmailApiError> {
+ self.unavailable("unsubscribe")
+ }
+}
+
+impl MailboxMessageClient for FakeRepository {
+ async fn get_message(
+ &self,
+ _: &AccessToken,
+ _: Uuid,
+ _: &str,
+ ) -> Result<Option<crate::domain::models::MessageWithCalendarParts>, EmailApiError> {
+ self.unavailable("get_message")
+ }
+
+ async fn get_message_label_ids(
+ &self,
+ _: &AccessToken,
+ _: &str,
+ ) -> Result<Option<Vec<String>>, EmailApiError> {
+ self.unavailable("get_message_label_ids")
+ }
+
+ async fn list_messages(
+ &self,
+ _: &AccessToken,
+ _: u32,
+ _: &[&str],
+ ) -> Result<Vec<String>, EmailApiError> {
+ self.unavailable("list_messages")
+ }
+
+ async fn get_message_ids_for_thread(
+ &self,
+ _: &AccessToken,
+ _: &str,
+ ) -> Result<Vec<String>, EmailApiError> {
+ self.unavailable("get_message_ids_for_thread")
+ }
+
+ async fn get_thread(
+ &self,
+ _: &AccessToken,
+ _: Uuid,
+ _: &str,
+ ) -> Result<Vec<Message>, EmailApiError> {
+ self.unavailable("get_thread")
+ }
+
+ async fn list_threads(
+ &self,
+ _: &AccessToken,
+ _: u32,
+ _: Option<&str>,
+ _: &[&str],
+ ) -> Result<ThreadListPage, EmailApiError> {
+ self.unavailable("list_threads")
+ }
+
+ async fn modify_message_labels(
+ &self,
+ _: &AccessToken,
+ _: &str,
+ _: &[String],
+ _: &[String],
+ ) -> Result<(), EmailApiError> {
+ self.unavailable("modify_message_labels")
+ }
+}
+
+impl MailboxSendClient for FakeRepository {
+ async fn send_message(
+ &self,
+ _: &AccessToken,
+ _: &SendRequest,
+ _: Option<&str>,
+ ) -> Result<SentIds, EmailApiError> {
+ self.unavailable("send_message")
+ }
+}
+
+impl MailboxLabelClient for FakeRepository {
+ async fn list_labels(&self, _: &AccessToken, _: Uuid) -> Result<Vec<Label>, EmailApiError> {
+ self.unavailable("list_labels")
+ }
+
+ async fn create_label(
+ &self,
+ _: &AccessToken,
+ _: Uuid,
+ _: &str,
+ ) -> Result<Label, EmailApiError> {
+ self.unavailable("create_label")
+ }
+
+ async fn delete_label(&self, _: &AccessToken, _: &str) -> Result<(), EmailApiError> {
+ self.unavailable("delete_label")
+ }
+}
+
+impl MailboxAttachmentClient for FakeRepository {
+ async fn get_attachment(
+ &self,
+ _: &AccessToken,
+ _: &str,
+ _: &str,
+ ) -> Result<Vec<u8>, EmailApiError> {
+ self.unavailable("get_attachment")
+ }
+}
+
+impl MailboxContactsClient for FakeRepository {
+ async fn get_self_contact(&self, _: &AccessToken, _: Uuid) -> Result<Contact, EmailApiError> {
+ self.unavailable("get_self_contact")
+ }
+
+ async fn list_contacts(
+ &self,
+ _: &AccessToken,
+ _: Uuid,
+ _: Option<&str>,
+ ) -> Result<ContactList, EmailApiError> {
+ self.unavailable("list_contacts")
+ }
+
+ async fn list_other_contacts(
+ &self,
+ _: &AccessToken,
+ _: Uuid,
+ _: Option<&str>,
+ ) -> Result<ContactList, EmailApiError> {
+ self.unavailable("list_other_contacts")
+ }
+}
+
+impl MailboxBlocklistClient for FakeRepository {
+ async fn block_sender(&self, _: &AccessToken, _: &str) -> Result<(), EmailApiError> {
+ self.unavailable("block_sender")
+ }
+
+ async fn unblock_sender(&self, _: &AccessToken, _: &str) -> Result<(), EmailApiError> {
+ self.unavailable("unblock_sender")
+ }
+
+ async fn list_blocked_senders(&self, _: &AccessToken) -> Result<Vec<String>, EmailApiError> {
+ self.unavailable("list_blocked_senders")
+ }
+}
diff --git a/crates/email_api_client/src/lib.rs b/crates/email_api_client/src/lib.rs
new file mode 100644
index 0000000000..a42ee6b5aa
--- /dev/null
+++ b/crates/email_api_client/src/lib.rs
@@ -0,0 +1,13 @@
+#![deny(missing_docs)]
+
+//! Provider-neutral contracts and models for email provider integrations.
+
+/// Provider-neutral domain types and, when enabled, capability ports.
+pub mod domain;
+
+/// Provider-specific outbound adapters.
+#[cfg(feature = "outbound-gmail")]
+pub mod outbound;
+
+#[cfg(feature = "outbound-gmail")]
+pub use outbound::gmail::GmailApiClientRepository;
diff --git a/crates/email_api_client/src/outbound/gmail/attachments.rs b/crates/email_api_client/src/outbound/gmail/attachments.rs
new file mode 100644
index 0000000000..961f16d2b5
--- /dev/null
+++ b/crates/email_api_client/src/outbound/gmail/attachments.rs
@@ -0,0 +1,24 @@
+//! Gmail attachment capability implementation.
+
+use crate::domain::models::{AccessToken, EmailApiError};
+use crate::domain::ports::MailboxAttachmentClient;
+
+use super::{GmailApiClientRepository, map_gmail_error};
+
+impl MailboxAttachmentClient for GmailApiClientRepository {
+ async fn get_attachment(
+ &self,
+ access_token: &AccessToken,
+ provider_message_id: &str,
+ provider_attachment_id: &str,
+ ) -> Result<Vec<u8>, EmailApiError> {
+ self.client
+ .get_attachment_data(
+ access_token.expose_secret(),
+ provider_message_id,
+ provider_attachment_id,
+ )
+ .await
+ .map_err(map_gmail_error)
+ }
+}
diff --git a/crates/email_api_client/src/outbound/gmail/blocklist.rs b/crates/email_api_client/src/outbound/gmail/blocklist.rs
new file mode 100644
index 0000000000..796f48263b
--- /dev/null
+++ b/crates/email_api_client/src/outbound/gmail/blocklist.rs
@@ -0,0 +1,132 @@
+//! Gmail blocked-sender capability implementation.
+
+use models_email::gmail::filters::{Filter, FilterAction, FilterCriteria};
+
+use crate::domain::models::{AccessToken, EmailApiError};
+use crate::domain::ports::MailboxBlocklistClient;
+
+use super::{GmailApiClientRepository, map_gmail_error};
+
+const TRASH_LABEL_ID: &str = "TRASH";
+
+impl MailboxBlocklistClient for GmailApiClientRepository {
+ async fn block_sender(
+ &self,
+ access_token: &AccessToken,
+ email_address: &str,
+ ) -> Result<(), EmailApiError> {
+ let token = access_token.expose_secret();
+ let filters = self
+ .client
+ .list_filters(token)
+ .await
+ .map_err(map_gmail_error)?;
+ if find_block_filters(&filters, email_address).next().is_some() {
+ return Ok(());
+ }
+
+ self.client
+ .create_filter(token, block_filter(email_address))
+ .await
+ .map_err(map_gmail_error)?;
+ Ok(())
+ }
+
+ async fn unblock_sender(
+ &self,
+ access_token: &AccessToken,
+ email_address: &str,
+ ) -> Result<(), EmailApiError> {
+ let token = access_token.expose_secret();
+ let filters = self
+ .client
+ .list_filters(token)
+ .await
+ .map_err(map_gmail_error)?;
+ // Delete every matching filter: blocking with different casing used to
+ // create duplicates, and removing them all heals those legacy states.
+ let mut found = false;
+ for filter in find_block_filters(&filters, email_address) {
+ found = true;
+ let Some(filter_id) = filter.id.as_deref() else {
+ return Err(EmailApiError::Permanent {
+ message: "Gmail blocked-sender filter is missing its provider ID".to_string(),
+ });
+ };
+
+ self.client
+ .delete_filter(token, filter_id)
+ .await
+ .map_err(map_gmail_error)?;
+ }
+
+ if !found {
+ tracing::warn!("no blocked-sender filter found to delete for the requested address");
+ }
+
+ Ok(())
+ }
+
+ async fn list_blocked_senders(
+ &self,
+ access_token: &AccessToken,
+ ) -> Result<Vec<String>, EmailApiError> {
+ let filters = self
+ .client
+ .list_filters(access_token.expose_secret())
+ .await
+ .map_err(map_gmail_error)?;
+
+ Ok(filters
+ .iter()
+ .filter(|filter| is_block_filter(filter))
+ .filter_map(|filter| filter.criteria.from.clone())
+ .collect())
+ }
+}
+
+fn block_filter(email_address: &str) -> Filter {
+ Filter {
+ id: None,
+ criteria: FilterCriteria {
+ from: Some(email_address.to_string()),
+ to: None,
+ subject: None,
+ query: None,
+ negated_query: None,
+ has_attachment: None,
+ exclude_chats: None,
+ },
+ action: FilterAction {
+ add_label_ids: Some(vec![TRASH_LABEL_ID.to_string()]),
+ remove_label_ids: None,
+ forward: None,
+ },
+ }
+}
+
+/// Finds every block filter for `email_address`, ignoring ASCII case: Gmail
+/// treats addresses case-insensitively and stored filters may differ in
+/// casing from the request.
+fn find_block_filters<'a>(
+ filters: &'a [Filter],
+ email_address: &'a str,
+) -> impl Iterator<Item = &'a Filter> {
+ filters.iter().filter(move |filter| {
+ is_block_filter(filter)
+ && filter
+ .criteria
+ .from
+ .as_deref()
+ .is_some_and(|from| from.eq_ignore_ascii_case(email_address))
+ })
+}
+
+fn is_block_filter(filter: &Filter) -> bool {
+ filter.criteria.from.is_some()
+ && filter
+ .action
+ .add_label_ids
+ .as_ref()
+ .is_some_and(|label_ids| label_ids.iter().any(|label_id| label_id == TRASH_LABEL_ID))
+}
diff --git a/crates/email_api_client/src/outbound/gmail/contacts.rs b/crates/email_api_client/src/outbound/gmail/contacts.rs
new file mode 100644
index 0000000000..65ea815913
--- /dev/null
+++ b/crates/email_api_client/src/outbound/gmail/contacts.rs
@@ -0,0 +1,67 @@
+//! Gmail contact capability implementation.
+
+use models_email::service::contact::{Contact, ContactList};
+use uuid::Uuid;
+
+use crate::domain::models::{AccessToken, EmailApiError};
+use crate::domain::ports::MailboxContactsClient;
+
+use super::convert::map_person_to_contact;
+use super::{GmailApiClientRepository, map_contacts_error, map_gmail_error};
+
+impl MailboxContactsClient for GmailApiClientRepository {
+ async fn get_self_contact(
+ &self,
+ access_token: &AccessToken,
+ link_id: Uuid,
+ ) -> Result<Contact, EmailApiError> {
+ let person = self
+ .client
+ .get_self_contact(access_token.expose_secret())
+ .await
+ .map_err(map_gmail_error)?;
+ Ok(map_person_to_contact(link_id, person))
+ }
+
+ async fn list_contacts(
+ &self,
+ access_token: &AccessToken,
+ link_id: Uuid,
+ sync_token: Option<&str>,
+ ) -> Result<ContactList, EmailApiError> {
+ let (people, next_sync_token) = self
+ .client
+ .get_contacts(access_token.expose_secret(), sync_token)
+ .await
+ .map_err(map_contacts_error)?;
+ Ok(contact_list(link_id, people, next_sync_token))
+ }
+
+ async fn list_other_contacts(
+ &self,
+ access_token: &AccessToken,
+ link_id: Uuid,
+ sync_token: Option<&str>,
+ ) -> Result<ContactList, EmailApiError> {
+ let (people, next_sync_token) = self
+ .client
+ .get_other_contacts(access_token.expose_secret(), sync_token)
+ .await
+ .map_err(map_contacts_error)?;
+ Ok(contact_list(link_id, people, next_sync_token))
+ }
+}
+
+fn contact_list(
+ link_id: Uuid,
+ people: Vec<models_email::gmail::contacts::PersonResource>,
+ next_sync_token: String,
+) -> ContactList {
+ ContactList {
+ contacts: people
+ .into_iter()
+ .map(|person| map_person_to_contact(link_id, person))
+ .collect(),
+ next_sync_token,
+ }
+}
diff --git a/crates/email_api_client/src/outbound/gmail/convert/contact.rs b/crates/email_api_client/src/outbound/gmail/convert/contact.rs
new file mode 100644
index 0000000000..3fb4d7708c
--- /dev/null
+++ b/crates/email_api_client/src/outbound/gmail/convert/contact.rs
@@ -0,0 +1,36 @@
+use models_email::gmail::contacts::PersonResource;
+use models_email::service::contact::Contact;
+use uuid::Uuid;
+
+pub(crate) fn map_person_to_contact(link_id: Uuid, person: PersonResource) -> Contact {
+ let name = person.names.into_iter().find_map(|name| name.display_name);
+ let email_address = person
+ .email_addresses
+ .into_iter()
+ .find_map(|email| email.value);
+ let original_photo_url = person
+ .photos
+ .into_iter()
+ .find(|photo| photo.url.is_some() && photo.default != Some(true))
+ .and_then(|photo| photo.url)
+ .map(normalize_google_photo_url);
+
+ Contact {
+ id: Uuid::now_v7(),
+ link_id,
+ name,
+ email_address,
+ original_photo_url,
+ sfs_photo_url: None,
+ }
+}
+
+fn normalize_google_photo_url(photo_url: String) -> String {
+ match photo_url.strip_suffix("s100") {
+ Some(prefix) => format!("{prefix}s128"),
+ None => photo_url,
+ }
+}
+
+#[cfg(test)]
+mod test;
diff --git a/crates/email_api_client/src/outbound/gmail/convert/contact/test.rs b/crates/email_api_client/src/outbound/gmail/convert/contact/test.rs
new file mode 100644
index 0000000000..e5df3633d7
--- /dev/null
+++ b/crates/email_api_client/src/outbound/gmail/convert/contact/test.rs
@@ -0,0 +1,59 @@
+use models_email::gmail::contacts::{EmailAddress, Name, PersonResource, Photo};
+use uuid::Uuid;
+
+use super::map_person_to_contact;
+
+#[test]
+fn maps_first_available_fields_and_resizes_google_photo() {
+ let link_id = Uuid::now_v7();
+ let person = PersonResource {
+ names: vec![
+ Name { display_name: None },
+ Name {
+ display_name: Some("Ada".into()),
+ },
+ ],
+ email_addresses: vec![EmailAddress {
+ value: Some("[email protected]".into()),
+ }],
+ photos: vec![
+ Photo {
+ url: Some("https://example.com/default=s100".into()),
+ default: Some(true),
+ },
+ Photo {
+ url: Some("https://example.com/photo=s100".into()),
+ default: Some(false),
+ },
+ ],
+ };
+
+ let contact = map_person_to_contact(link_id, person);
+
+ assert_eq!(contact.link_id, link_id);
+ assert_eq!(contact.name.as_deref(), Some("Ada"));
+ assert_eq!(contact.email_address.as_deref(), Some("[email protected]"));
+ assert_eq!(
+ contact.original_photo_url.as_deref(),
+ Some("https://example.com/photo=s128")
+ );
+}
+
+#[test]
+fn leaves_non_google_size_suffix_unchanged() {
+ let person = PersonResource {
+ names: vec![],
+ email_addresses: vec![],
+ photos: vec![Photo {
+ url: Some("https://example.com/photo=s96".into()),
+ default: None,
+ }],
+ };
+
+ let contact = map_person_to_contact(Uuid::now_v7(), person);
+
+ assert_eq!(
+ contact.original_photo_url.as_deref(),
+ Some("https://example.com/photo=s96")
+ );
+}
diff --git a/crates/email_api_client/src/outbound/gmail/convert/history.rs b/crates/email_api_client/src/outbound/gmail/convert/history.rs
new file mode 100644
index 0000000000..7f75690751
--- /dev/null
+++ b/crates/email_api_client/src/outbound/gmail/convert/history.rs
@@ -0,0 +1,84 @@
+use models_email::gmail::{HistoryListResponse, HistoryRecord};
+
+use crate::domain::models::{ChangeBatch, InboxChanges, SyncCursor};
+
+pub(crate) fn map_history_list_response_to_changes(response: HistoryListResponse) -> ChangeBatch {
+ let mut changes = InboxChanges::default();
+
+ for record in response.history.unwrap_or_default() {
+ apply_history_record(&mut changes, &record);
+ }
+
+ ChangeBatch::new(changes, SyncCursor::gmail(response.history_id))
+}
+
+fn apply_history_record(changes: &mut InboxChanges, record: &HistoryRecord) {
+ for message in record.messages.iter().flatten() {
+ let explicitly_handled = record
+ .messages_added
+ .iter()
+ .flatten()
+ .any(|item| item.message.id == message.id)
+ || record
+ .messages_deleted
+ .iter()
+ .flatten()
+ .any(|item| item.message.id == message.id)
+ || record
+ .labels_added
+ .iter()
+ .flatten()
+ .any(|item| item.message.id == message.id)
+ || record
+ .labels_removed
+ .iter()
+ .flatten()
+ .any(|item| item.message.id == message.id);
+
+ if !explicitly_handled && !changes.message_ids_to_delete.contains(&message.id) {
+ mark_for_upsert(changes, &message.id);
+ }
+ }
+
+ for added in record.messages_added.iter().flatten() {
+ if !changes.message_ids_to_delete.contains(&added.message.id) {
+ mark_for_upsert(changes, &added.message.id);
+ }
+ }
+
+ for deleted in record.messages_deleted.iter().flatten() {
+ changes
+ .message_ids_to_delete
+ .insert(deleted.message.id.clone());
+ changes.message_ids_to_upsert.remove(&deleted.message.id);
+ changes.labels_to_update.remove(&deleted.message.id);
+ }
+
+ for message_id in record
+ .labels_added
+ .iter()
+ .flatten()
+ .map(|item| &item.message.id)
+ .chain(
+ record
+ .labels_removed
+ .iter()
+ .flatten()
+ .map(|item| &item.message.id),
+ )
+ {
+ if !changes.message_ids_to_upsert.contains(message_id)
+ && !changes.message_ids_to_delete.contains(message_id)
+ {
+ changes.labels_to_update.insert(message_id.clone());
+ }
+ }
+}
+
+fn mark_for_upsert(changes: &mut InboxChanges, message_id: &str) {
+ changes.message_ids_to_upsert.insert(message_id.to_owned());
+ changes.labels_to_update.remove(message_id);
+}
+
+#[cfg(test)]
+mod test;
diff --git a/crates/email_api_client/src/outbound/gmail/convert/history/test.rs b/crates/email_api_client/src/outbound/gmail/convert/history/test.rs
new file mode 100644
index 0000000000..e74be161c4
--- /dev/null
+++ b/crates/email_api_client/src/outbound/gmail/convert/history/test.rs
@@ -0,0 +1,56 @@
+use models_email::gmail::{
+ HistoryListResponse, HistoryMessage, HistoryRecord, LabelAdded, MessageAdded, MessageDeleted,
+};
+
+use super::map_history_list_response_to_changes;
+use crate::domain::models::SyncCursor;
+
+fn message(id: &str) -> HistoryMessage {
+ HistoryMessage {
+ id: id.into(),
+ thread_id: "thread".into(),
+ }
+}
+
+#[test]
+fn resolves_overlapping_changes_with_deletion_precedence() {
+ let response = HistoryListResponse {
+ history_id: "cursor-2".into(),
+ next_page_token: None,
+ history: Some(vec![HistoryRecord {
+ id: "1".into(),
+ messages: Some(vec![message("implicit")]),
+ messages_added: Some(vec![MessageAdded {
+ message: message("deleted"),
+ }]),
+ messages_deleted: Some(vec![MessageDeleted {
+ message: message("deleted"),
+ }]),
+ labels_added: Some(vec![LabelAdded {
+ message: message("labels"),
+ label_ids: vec!["STARRED".into()],
+ }]),
+ labels_removed: None,
+ }]),
+ };
+
+ let batch = map_history_list_response_to_changes(response);
+
+ assert_eq!(batch.next_cursor, SyncCursor::gmail("cursor-2"));
+ assert!(batch.changes.message_ids_to_upsert.contains("implicit"));
+ assert!(batch.changes.message_ids_to_delete.contains("deleted"));
+ assert!(!batch.changes.message_ids_to_upsert.contains("deleted"));
+ assert!(batch.changes.labels_to_update.contains("labels"));
+}
+
+#[test]
+fn handles_an_empty_history_page() {
+ let batch = map_history_list_response_to_changes(HistoryListResponse {
+ history: None,
+ next_page_token: None,
+ history_id: "cursor".into(),
+ });
+
+ assert!(batch.changes.message_ids_to_upsert.is_empty());
+ assert_eq!(batch.next_cursor.as_str(), "cursor");
+}
diff --git a/crates/email_api_client/src/outbound/gmail/convert/label.rs b/crates/email_api_client/src/outbound/gmail/convert/label.rs
new file mode 100644
index 0000000000..b54b3dcf82
--- /dev/null
+++ b/crates/email_api_client/src/outbound/gmail/convert/label.rs
@@ -0,0 +1,61 @@
+use models_email::gmail::labels::{GmailLabel, GmailLabelsResponse};
+use models_email::service::label::{Label, LabelListVisibility, LabelType, MessageListVisibility};
+use uuid::Uuid;
+
+use crate::domain::models::EmailApiError;
+
+pub(crate) fn map_label_to_service(
+ gmail_label: &GmailLabel,
+ link_id: Uuid,
+) -> Result<Label, EmailApiError> {
+ let message_list_visibility = gmail_label
+ .message_list_visibility
+ .as_deref()
+ .map(MessageListVisibility::from_str)
+ .transpose()
+ .map_err(permanent)?
+ .unwrap_or(MessageListVisibility::Show);
+ let label_list_visibility = gmail_label
+ .label_list_visibility
+ .as_deref()
+ .map(LabelListVisibility::from_str)
+ .transpose()
+ .map_err(permanent)?
+ .unwrap_or(LabelListVisibility::LabelShow);
+ let label_type = gmail_label
+ .type_
+ .as_deref()
+ .map(LabelType::from_str)
+ .transpose()
+ .map_err(permanent)?
+ .unwrap_or(LabelType::User);
+
+ Ok(Label {
+ id: None,
+ link_id,
+ provider_label_id: gmail_label.id.clone().unwrap_or_default(),
+ name: Some(gmail_label.name.clone()),
+ created_at: chrono::Utc::now(),
+ message_list_visibility: Some(message_list_visibility),
+ label_list_visibility: Some(label_list_visibility),
+ type_: Some(label_type),
+ })
+}
+
+pub(crate) fn map_labels_to_service(
+ response: &GmailLabelsResponse,
+ link_id: Uuid,
+) -> Result<Vec<Label>, EmailApiError> {
+ response
+ .labels
+ .iter()
+ .map(|label| map_label_to_service(label, link_id))
+ .collect()
+}
+
+fn permanent(message: String) -> EmailApiError {
+ EmailApiError::Permanent { message }
+}
+
+#[cfg(test)]
+mod test;
diff --git a/crates/email_api_client/src/outbound/gmail/convert/label/test.rs b/crates/email_api_client/src/outbound/gmail/convert/label/test.rs
new file mode 100644
index 0000000000..d029b109f1
--- /dev/null
+++ b/crates/email_api_client/src/outbound/gmail/convert/label/test.rs
@@ -0,0 +1,48 @@
+use models_email::gmail::labels::{GmailLabel, GmailLabelsResponse};
+use models_email::service::label::{LabelListVisibility, LabelType, MessageListVisibility};
+use uuid::Uuid;
+
+use super::{map_label_to_service, map_labels_to_service};
+use crate::domain::models::EmailApiError;
+
+fn label() -> GmailLabel {
+ GmailLabel {
+ id: Some("Label_1".into()),
+ name: "Projects".into(),
+ message_list_visibility: None,
+ label_list_visibility: None,
+ type_: None,
+ color: None,
+ }
+}
+
+#[test]
+fn applies_gmail_label_defaults() {
+ let mapped = map_label_to_service(&label(), Uuid::now_v7()).unwrap();
+
+ assert_eq!(
+ mapped.message_list_visibility,
+ Some(MessageListVisibility::Show)
+ );
+ assert_eq!(
+ mapped.label_list_visibility,
+ Some(LabelListVisibility::LabelShow)
+ );
+ assert_eq!(mapped.type_, Some(LabelType::User));
+}
+
+#[test]
+fn invalid_wire_values_are_permanent_failures() {
+ let mut invalid = label();
+ invalid.type_ = Some("invalid".into());
+
+ assert!(matches!(
+ map_labels_to_service(
+ &GmailLabelsResponse {
+ labels: vec![invalid]
+ },
+ Uuid::now_v7()
+ ),
+ Err(EmailApiError::Permanent { .. })
+ ));
+}
diff --git a/crates/email_api_client/src/outbound/gmail/convert/message.rs b/crates/email_api_client/src/outbound/gmail/convert/message.rs
new file mode 100644
index 0000000000..5f346b04b1
--- /dev/null
+++ b/crates/email_api_client/src/outbound/gmail/convert/message.rs
@@ -0,0 +1,149 @@
+use chrono::{TimeZone, Utc};
+use mailparse::{MailAddr, MailAddrList, addrparse};
+use models_email::email::service;
+use models_email::gmail::{Header, MessageResource};
+use uuid::Uuid;
+
+use super::payload::parse_gmail_payload;
+use crate::domain::models::EmailApiError;
+
+pub(crate) fn map_message_resource_to_service(
+ message: MessageResource,
+ link_id: Uuid,
+) -> Result<service::message::Message, EmailApiError> {
+ let parsed = parse_gmail_payload(&message.payload, &message.id)?;
+ let internal_date_ts = message
+ .internal_date
+ .parse::<i64>()
+ .ok()
+ .and_then(|milliseconds| Utc.timestamp_millis_opt(milliseconds).single());
+ let has_label = |label: &str| message.label_ids.iter().any(|id| id == label);
+ let is_read = !has_label(service::label::system_labels::UNREAD);
+ let is_starred = has_label(service::label::system_labels::STARRED);
+ let is_sent = has_label(service::label::system_labels::SENT);
+ let is_draft = has_label(service::label::system_labels::DRAFT);
+ let labels = message
+ .label_ids
+ .iter()
+ .map(|id| service::label::Label {
+ id: None,
+ link_id,
+ provider_label_id: id.clone(),
+ name: None,
+ created_at: Default::default(),
+ message_list_visibility: None,
+ label_list_visibility: None,
+ type_: None,
+ })
+ .collect();
+ let attachments = parsed
+ .attachments_metadata
+ .into_iter()
+ .map(|metadata| service::attachment::Attachment {
+ db_id: Uuid::now_v7(),
+ provider_id: metadata.provider_attachment_id,
+ data_url: None,
+ filename: metadata.filename,
+ mime_type: metadata.mime_type,
+ size_bytes: metadata.size_bytes,
+ content_id: metadata.content_id,
+ sfs_id: None,
+ })
+ .collect();
+ let headers_json =
+ serde_json::to_value(parsed.all_headers).map_err(|error| EmailApiError::Permanent {
+ message: format!("failed to encode Gmail message headers: {error}"),
+ })?;
+
+ Ok(service::message::Message {
+ db_id: Uuid::now_v7(),
+ provider_id: Some(message.id),
+ thread_db_id: Uuid::now_v7(),
+ provider_thread_id: Some(message.thread_id),
+ replying_to_id: None,
+ global_id: Some(parsed.global_id),
+ link_id,
+ subject: parsed.subject,
+ snippet: Some(message.snippet),
+ provider_history_id: Some(message.history_id),
+ internal_date_ts,
+ sent_at: parsed.sent_at.or(internal_date_ts),
+ size_estimate: Some(message.size_estimate as i64),
+ is_read,
+ is_starred,
+ is_sent,
+ is_draft,
+ scheduled_send_time: None,
+ has_attachments: parsed.has_attachments,
+ from: parsed.from,
+ to: parsed.to,
+ cc: parsed.cc,
+ bcc: parsed.bcc,
+ labels,
+ body_text: parsed.body_text,
+ body_html_sanitized: parsed.body_html_sanitized,
+ body_macro: None,
+ attachments,
+ attachments_draft: Vec::new(),
+ attachments_forwarded: Vec::new(),
+ headers_json: Some(headers_json),
+ created_at: Utc::now(),
+ updated_at: Utc::now(),
+ })
+}
+
+pub(super) fn parse_address_header(header_value: &str) -> Vec<(Option<String>, String)> {
+ match addrparse(header_value) {
+ Ok(addresses) => process_parsed_addresses(&addresses),
+ Err(error) if header_value.contains(">,") => {
+ let Some(index) = header_value.rfind(">,") else {
+ return Vec::new();
+ };
+ addrparse(&header_value[..=index])
+ .map(|addresses| process_parsed_addresses(&addresses))
+ .unwrap_or_else(|salvage_error| {
+ // From/To information is silently lost past this point, so
+ // leave a trace. The raw header stays out of the log (PII).
+ tracing::warn!(
+ error = %salvage_error,
+ original_error = %error,
+ header_len = header_value.len(),
+ "address header failed to parse even after truncation salvage"
+ );
+ Vec::new()
+ })
+ }
+ Err(error) => {
+ tracing::warn!(
+ error = %error,
+ header_len = header_value.len(),
+ "address header failed to parse; sender/recipient will be missing"
+ );
+ Vec::new()
+ }
+ }
+}
+
+fn process_parsed_addresses(addresses: &MailAddrList) -> Vec<(Option<String>, String)> {
+ addresses
+ .iter()
+ .flat_map(|address| match address {
+ MailAddr::Single(info) => vec![(info.display_name.clone(), info.addr.clone())],
+ MailAddr::Group(group) => group
+ .addrs
+ .iter()
+ .map(|info| (info.display_name.clone(), info.addr.clone()))
+ .collect(),
+ })
+ .collect()
+}
+
+pub(super) fn find_header<'a>(headers: &'a [Header], name: &str) -> Option<&'a str> {
+ headers
+ .iter()
+ .find(|header| header.name.eq_ignore_ascii_case(name))
+ .map(|header| header.value.as_str())
+}
+
+#[cfg(test)]
+mod test;
diff --git a/crates/email_api_client/src/outbound/gmail/convert/message/test.rs b/crates/email_api_client/src/outbound/gmail/convert/message/test.rs
new file mode 100644
index 0000000000..d2730ad553
--- /dev/null
+++ b/crates/email_api_client/src/outbound/gmail/convert/message/test.rs
@@ -0,0 +1,116 @@
+use base64::{Engine as _, engine::general_purpose::URL_SAFE};
+use models_email::gmail::{Header, MessagePart, MessagePartBody, MessageResource};
+use uuid::Uuid;
+
+use super::{map_message_resource_to_service, parse_address_header};
+
+fn message() -> MessageResource {
+ MessageResource {
+ id: "message".into(),
+ thread_id: "thread".into(),
+ label_ids: vec!["UNREAD".into(), "STARRED".into()],
+ snippet: "snippet".into(),
+ size_estimate: 12,
+ history_id: "history".into(),
+ internal_date: "1700000000000".into(),
+ payload: MessagePart {
+ part_id: "part".into(),
+ mime_type: "text/plain".into(),
+ filename: String::new(),
+ headers: vec![Header {
+ name: "Message-ID".into(),
+ value: "global".into(),
+ }],
+ body: Some(MessagePartBody {
+ attachment_id: None,
+ size: 4,
+ data_base64: Some(URL_SAFE.encode("body")),
+ }),
+ parts: None,
+ },
+ }
+}
+
+#[test]
+fn maps_message_flags_and_payload() {
+ let mapped = map_message_resource_to_service(message(), Uuid::now_v7()).unwrap();
+
+ assert!(!mapped.is_read);
+ assert!(mapped.is_starred);
+ assert!(!mapped.is_sent);
+ assert_eq!(mapped.body_text.as_deref(), Some("body"));
+ assert_eq!(mapped.global_id.as_deref(), Some("global"));
+}
+
+#[test]
+fn parses_groups_and_salvages_truncated_address_lists() {
+ assert_eq!(
+ parse_address_header("Group: Ada <[email protected]>, Bob <[email protected]>;"),
+ vec![
+ (Some("Ada".into()), "[email protected]".into()),
+ (Some("Bob".into()), "[email protected]".into()),
+ ]
+ );
+ assert_eq!(
+ parse_address_header("Ada <[email protected]>, Broken <broken@example"),
+ vec![(Some("Ada".into()), "[email protected]".into())]
+ );
+ // Missing '>' at the end.
+ assert_eq!(
+ parse_address_header("John <[email protected]>, Partial <email@domain"),
+ vec![(Some("John".into()), "[email protected]".into())]
+ );
+}
+
+#[test]
+fn parses_quoted_display_names_containing_commas() {
+ assert_eq!(
+ parse_address_header(r#""Asdf, Fdsa" <[email protected]>, "aaa, ddd" <aaa.ddd@ff"#),
+ vec![(Some("Asdf, Fdsa".into()), "[email protected]".into())]
+ );
+ assert_eq!(
+ parse_address_header(
+ r#""First, Last" <[email protected]>, "Second, Name" <[email protected]>, "Third, Complex, Name" <third@incomplete"#
+ ),
+ vec![
+ (Some("First, Last".into()), "[email protected]".into()),
+ (Some("Second, Name".into()), "[email protected]".into()),
+ ]
+ );
+ assert_eq!(
+ parse_address_header(r#""Initial, With, Commas" <[email protected]>"#),
+ vec![(
+ Some("Initial, With, Commas".into()),
+ )]
+ );
+}
+
+#[test]
+fn unparseable_headers_yield_no_addresses() {
+ // Providers substitute this placeholder when recipients are hidden.
+ assert!(parse_address_header("(withheld recipients)").is_empty());
+ assert!(parse_address_header("This is not an email address").is_empty());
+ assert!(parse_address_header("").is_empty());
+ // Still invalid even after the truncation salvage.
+ assert!(parse_address_header("Invalid <not-an-email@, Another <not-an-email@").is_empty());
+}
+
+#[test]
+fn parses_the_real_world_truncated_recipient_header() {
+ let header = "Evan Macrotest <[email protected]>, evanmacrotest <[email protected]>, Recipient Name <evan.hutnik@gm";
+
+ assert_eq!(
+ parse_address_header(header),
+ vec![
+ (
+ Some("Evan Macrotest".into()),
+ ),
+ (
+ Some("evanmacrotest".into()),
+ ),
+ ]
+ );
+}
diff --git a/crates/email_api_client/src/outbound/gmail/convert/mod.rs b/crates/email_api_client/src/outbound/gmail/convert/mod.rs
new file mode 100644
index 0000000000..6cfebd13e0
--- /dev/null
+++ b/crates/email_api_client/src/outbound/gmail/convert/mod.rs
@@ -0,0 +1,15 @@
+//! Conversion from Gmail wire resources into provider-neutral domain data.
+
+mod contact;
+mod history;
+mod label;
+mod message;
+mod payload;
+pub(crate) mod sanitizer;
+mod thread;
+
+pub(crate) use contact::map_person_to_contact;
+pub(crate) use history::map_history_list_response_to_changes;
+pub(crate) use label::{map_label_to_service, map_labels_to_service};
+pub(crate) use message::map_message_resource_to_service;
+pub(crate) use thread::map_thread_resource_to_service;
diff --git a/crates/email_api_client/src/outbound/gmail/convert/payload.rs b/crates/email_api_client/src/outbound/gmail/convert/payload.rs
new file mode 100644
index 0000000000..88023cc6c5
--- /dev/null
+++ b/crates/email_api_client/src/outbound/gmail/convert/payload.rs
@@ -0,0 +1,193 @@
+use base64::{
+ Engine as _,
+ engine::general_purpose::{URL_SAFE, URL_SAFE_NO_PAD},
+};
+use chrono::{DateTime, TimeZone, Utc};
+use models_email::email::service;
+use models_email::gmail::{Header, MessagePart};
+
+use super::message::{find_header, parse_address_header};
+use super::sanitizer::sanitize_email_html;
+use crate::domain::models::EmailApiError;
+
+#[derive(Debug, Default)]
+pub(super) struct ParsedGmailPayload {
+ pub(super) global_id: String,
+ pub(super) from: Option<service::address::ContactInfo>,
+ pub(super) to: Vec<service::address::ContactInfo>,
+ pub(super) cc: Vec<service::address::ContactInfo>,
+ pub(super) bcc: Vec<service::address::ContactInfo>,
+ pub(super) subject: Option<String>,
+ pub(super) sent_at: Option<DateTime<Utc>>,
+ pub(super) body_text: Option<String>,
+ pub(super) body_html_sanitized: Option<String>,
+ pub(super) attachments_metadata: Vec<AttachmentMetadata>,
+ pub(super) has_attachments: bool,
+ pub(super) all_headers: Vec<Header>,
+}
+
+#[derive(Debug, Clone)]
+pub(super) struct AttachmentMetadata {
+ pub(super) provider_attachment_id: Option<String>,
+ pub(super) filename: Option<String>,
+ pub(super) mime_type: Option<String>,
+ pub(super) size_bytes: Option<i64>,
+ pub(super) content_id: Option<String>,
+}
+
+pub(super) fn parse_gmail_payload(
+ message_payload: &MessagePart,
+ message_id: &str,
+) -> Result<ParsedGmailPayload, EmailApiError> {
+ let all_headers = message_payload.headers.clone();
+ let mut parsed = ParsedGmailPayload {
+ global_id: find_header(&all_headers, "Message-ID")
+ .unwrap_or_default()
+ .to_owned(),
+ subject: find_header(&all_headers, "Subject").map(str::to_owned),
+ sent_at: find_header(&all_headers, "Date")
+ .and_then(|date| mailparse::dateparse(date).ok())
+ .and_then(|timestamp| Utc.timestamp_opt(timestamp, 0).single()),
+ all_headers,
+ ..Default::default()
+ };
+
+ if let Some(from) = find_header(&parsed.all_headers, "From")
+ && let Some((name, email)) = parse_address_header(from).first()
+ {
+ parsed.from = Some(contact_info(name.clone(), email.clone()));
+ }
+
+ for (header_name, recipients) in [
+ ("To", &mut parsed.to),
+ ("Cc", &mut parsed.cc),
+ ("Bcc", &mut parsed.bcc),
+ ] {
+ if let Some(value) = find_header(&parsed.all_headers, header_name) {
+ recipients.extend(
+ parse_address_header(value)
+ .into_iter()
+ .map(|(name, email)| contact_info(name, email)),
+ );
+ }
+ }
+
+ let mut part_stack = vec![message_payload];
+ while let Some(part) = part_stack.pop() {
+ parse_part(part, message_id, &mut parsed);
+ if let Some(parts) = &part.parts {
+ part_stack.extend(parts.iter().rev());
+ }
+ }
+
+ Ok(parsed)
+}
+
+fn parse_part(part: &MessagePart, message_id: &str, parsed: &mut ParsedGmailPayload) {
+ let mime_type = part.mime_type.to_lowercase();
+ let is_multipart = mime_type.starts_with("multipart/alternative")
+ || mime_type.starts_with("multipart/related")
+ || mime_type.starts_with("multipart/mixed");
+ let disposition = find_header(&part.headers, "Content-Disposition")
+ .and_then(|value| value.split(';').next())
+ .map(str::trim)
+ .map(str::to_lowercase)
+ .unwrap_or_default();
+ let is_attachment = disposition == "attachment"
+ || (disposition == "inline" && !mime_type.starts_with("text/"))
+ || (!part.filename.is_empty() && !is_multipart && !mime_type.starts_with("text/"));
+
+ let Some(body) = &part.body else {
+ return;
+ };
+
+ if let Some(encoded) = &body.data_base64 {
+ let wants_text = mime_type == "text/plain" && parsed.body_text.is_none();
+ let wants_html = mime_type == "text/html" && parsed.body_html_sanitized.is_none();
+ if wants_text || wants_html {
+ // Gmail emits both padded and unpadded base64url in practice.
+ match URL_SAFE_NO_PAD
+ .decode(encoded)
+ .or_else(|_| URL_SAFE.decode(encoded))
+ {
+ Ok(bytes) if wants_text => {
+ parsed.body_text = Some(decode_part_text(&bytes, part));
+ }
+ Ok(bytes) => {
+ parsed.body_html_sanitized =
+ Some(sanitize_email_html(&decode_part_text(&bytes, part)));
+ }
+ // A single undecodable part must not sink the message (or its
+ // whole thread): keep the rest of the message and move on.
+ Err(error) => {
+ tracing::warn!(
+ message_id = %message_id,
+ part_id = %part.part_id,
+ mime = %part.mime_type,
+ error = %error,
+ "failed to decode base64 body data"
+ );
+ }
+ }
+ }
+ }
+
+ if is_attachment && body.attachment_id.is_some() {
+ parsed.has_attachments = true;
+ parsed.attachments_metadata.push(AttachmentMetadata {
+ provider_attachment_id: body.attachment_id.clone(),
+ filename: normalized_filename(&part.filename),
+ mime_type: Some(part.mime_type.clone()),
+ size_bytes: Some(body.size),
+ content_id: find_header(&part.headers, "Content-ID").map(str::to_owned),
+ });
+ }
+}
+
+/// Decodes part bytes honoring the part's declared `charset`, so non-UTF-8
+/// bodies (e.g. ISO-8859-1, Windows-1252, Shift_JIS) are not mangled by a
+/// blind lossy UTF-8 conversion. Unknown or missing charsets fall back to
+/// lossy UTF-8.
+fn decode_part_text(bytes: &[u8], part: &MessagePart) -> String {
+ let encoding = find_header(&part.headers, "Content-Type")
+ .and_then(content_type_charset)
+ .and_then(|label| encoding_rs::Encoding::for_label(label.as_bytes()));
+
+ match encoding {
+ Some(encoding) => encoding.decode(bytes).0.into_owned(),
+ None => String::from_utf8_lossy(bytes).into_owned(),
+ }
+}
+
+fn content_type_charset(content_type: &str) -> Option<&str> {
+ content_type.split(';').skip(1).find_map(|parameter| {
+ let (key, value) = parameter.split_once('=')?;
+ key.trim()
+ .eq_ignore_ascii_case("charset")
+ .then(|| value.trim().trim_matches('"'))
+ })
+}
+
+fn contact_info(name: Option<String>, email: String) -> service::address::ContactInfo {
+ service::address::ContactInfo {
+ email,
+ name,
+ photo_url: None,
+ }
+}
+
+fn normalized_filename(filename: &str) -> Option<String> {
+ if filename.is_empty() {
+ return None;
+ }
+
+ Some(match filename.rsplit_once('.') {
+ Some((base, extension)) if !extension.is_empty() => {
+ format!("{base}.{}", extension.to_lowercase())
+ }
+ _ => filename.to_owned(),
+ })
+}
+
+#[cfg(test)]
+mod test;
diff --git a/crates/email_api_client/src/outbound/gmail/convert/payload/test.rs b/crates/email_api_client/src/outbound/gmail/convert/payload/test.rs
new file mode 100644
index 0000000000..72b5221559
--- /dev/null
+++ b/crates/email_api_client/src/outbound/gmail/convert/payload/test.rs
@@ -0,0 +1,130 @@
+use base64::{
+ Engine as _,
+ engine::general_purpose::{URL_SAFE, URL_SAFE_NO_PAD},
+};
+use models_email::gmail::{Header, MessagePart, MessagePartBody};
+
+use super::parse_gmail_payload;
+
+fn payload(mime_type: &str, data: &str) -> MessagePart {
+ MessagePart {
+ part_id: "part".into(),
+ mime_type: mime_type.into(),
+ filename: String::new(),
+ headers: vec![
+ Header {
+ name: "From".into(),
+ value: "Ada <[email protected]>".into(),
+ },
+ Header {
+ name: "Message-ID".into(),
+ value: "global-id".into(),
+ },
+ ],
+ body: Some(MessagePartBody {
+ attachment_id: None,
+ size: data.len() as i64,
+ data_base64: Some(data.into()),
+ }),
+ parts: None,
+ }
+}
+
+#[test]
+fn decodes_headers_and_text_body() {
+ let encoded = URL_SAFE.encode("Hello");
+ let parsed = parse_gmail_payload(&payload("text/plain", &encoded), "message").unwrap();
+
+ assert_eq!(parsed.global_id, "global-id");
+ assert_eq!(parsed.from.unwrap().email, "[email protected]");
+ assert_eq!(parsed.body_text.as_deref(), Some("Hello"));
+}
+
+#[test]
+fn skips_undecodable_body_data_but_keeps_the_message() {
+ let parsed = parse_gmail_payload(&payload("text/plain", "%%%"), "message").unwrap();
+
+ assert_eq!(parsed.body_text, None);
+ assert_eq!(parsed.global_id, "global-id");
+ assert_eq!(parsed.from.unwrap().email, "[email protected]");
+}
+
+#[test]
+fn accepts_unpadded_base64url_bodies() {
+ let encoded = URL_SAFE_NO_PAD.encode("Hello");
+ assert!(
+ encoded.len() % 4 != 0,
+ "fixture must exercise unpadded input"
+ );
+
+ let parsed = parse_gmail_payload(&payload("text/plain", &encoded), "message").unwrap();
+
+ assert_eq!(parsed.body_text.as_deref(), Some("Hello"));
+}
+
+#[test]
+fn honors_declared_non_utf8_charsets() {
+ // "café" in ISO-8859-1: the 0xE9 byte is invalid UTF-8 and would become
+ // U+FFFD under a blind lossy conversion.
+ let encoded = URL_SAFE.encode([b'c', b'a', b'f', 0xE9]);
+ let mut part = payload("text/plain", &encoded);
+ part.headers.push(Header {
+ name: "Content-Type".into(),
+ value: "text/plain; charset=\"ISO-8859-1\"".into(),
+ });
+
+ let parsed = parse_gmail_payload(&part, "message").unwrap();
+
+ assert_eq!(parsed.body_text.as_deref(), Some("café"));
+}
+
+#[test]
+fn unknown_charsets_fall_back_to_lossy_utf8() {
+ let encoded = URL_SAFE.encode("Hello");
+ let mut part = payload("text/plain", &encoded);
+ part.headers.push(Header {
+ name: "Content-Type".into(),
+ value: "text/plain; charset=not-a-real-charset".into(),
+ });
+
+ let parsed = parse_gmail_payload(&part, "message").unwrap();
+
+ assert_eq!(parsed.body_text.as_deref(), Some("Hello"));
+}
+
+#[test]
+fn one_bad_part_does_not_sink_sibling_parts() {
+ let mut root = payload("multipart/alternative", "");
+ root.body = None;
+
+ let mut bad = payload("text/plain", "%%%");
+ bad.headers.clear();
+ bad.part_id = "bad-part".into();
+
+ let mut good = payload("text/html", &URL_SAFE.encode("<p>Hello</p>"));
+ good.headers.clear();
+ good.part_id = "good-part".into();
+
+ root.parts = Some(vec![bad, good]);
+
+ let parsed = parse_gmail_payload(&root, "message").unwrap();
+
+ assert_eq!(parsed.body_text, None);
+ assert!(
+ parsed
+ .body_html_sanitized
+ .as_deref()
+ .unwrap()
+ .contains("<p>Hello</p>")
+ );
+}
+
+#[test]
+fn sanitizes_full_html_messages() {
+ let encoded = URL_SAFE.encode("<html><body><p>Hello</p><script>bad()</script></body></html>");
+ let parsed = parse_gmail_payload(&payload("text/html", &encoded), "message").unwrap();
+ let html = parsed.body_html_sanitized.unwrap();
+
+ assert!(html.contains("<p>Hello</p>"));
+ assert!(!html.contains("script"));
+}
diff --git a/services/email_service/src/util/sanitizer.rs b/crates/email_api_client/src/outbound/gmail/convert/sanitizer.rs
similarity index 68%
rename from services/email_service/src/util/sanitizer.rs
rename to crates/email_api_client/src/outbound/gmail/convert/sanitizer.rs
index bd6ab4811a..e52151654c 100644
--- a/services/email_service/src/util/sanitizer.rs
+++ b/crates/email_api_client/src/outbound/gmail/convert/sanitizer.rs
@@ -1,8 +1,17 @@
use ammonia::Builder;
-use once_cell::sync::Lazy;
+use regex::Regex;
use scraper::{Html, Selector};
use std::collections::HashSet;
+use std::sync::LazyLock;
+#[cfg(test)]
+mod test;
+
+/// Sanitizes a full email HTML document against the shared allowlist.
+///
+/// Extracts `<style>` and `<body>` content from (possibly malformed)
+/// documents, cleans the markup with ammonia, and scrubs `<style>` element
+/// text of external references and non-allowlisted properties.
pub fn sanitize_email_html(raw_html: &str) -> String {
// Attempt 1: Parse as a full document. This is best for well-formed emails.
let document = Html::parse_document(raw_html);
@@ -21,7 +30,7 @@ pub fn sanitize_email_html(raw_html: &str) -> String {
}
};
- CLEANER.clean(&content_to_clean).to_string()
+ sanitize_style_blocks(&CLEANER.clean(&content_to_clean).to_string())
}
/// Sanitizes a user-supplied HTML fragment (e.g. an email signature) with the
@@ -29,7 +38,7 @@ pub fn sanitize_email_html(raw_html: &str) -> String {
/// reconstruction `sanitize_email_html` applies to whole messages — a fragment
/// has no `<head>`/`<body>` to extract, so we just clean it in place.
pub fn sanitize_html_fragment(raw_html: &str) -> String {
- CLEANER.clean(raw_html).to_string()
+ sanitize_style_blocks(&CLEANER.clean(raw_html).to_string())
}
/// Extracts all <style> tags and the <body> tag from a parsed document,
@@ -56,11 +65,82 @@ fn find_and_reconstruct(document: &Html) -> Option<String> {
}
}
+/// Innermost `{ ... }` declaration blocks. Nested at-rules (`@media { a { … } }`)
+/// keep their structure: only the inner declaration lists match.
+static CSS_DECLARATION_BLOCK: LazyLock<Regex> =
+ LazyLock::new(|| Regex::new(r"\{([^{}]*)\}").expect("static regex is valid"));
+static CSS_COMMENT: LazyLock<Regex> =
+ LazyLock::new(|| Regex::new(r"(?s)/\*.*?\*/").expect("static regex is valid"));
+/// `@import …` up to its terminating semicolon (or end of block/input).
+static CSS_IMPORT: LazyLock<Regex> =
+ LazyLock::new(|| Regex::new(r"(?i)@import[^;{}]*(;|$)").expect("static regex is valid"));
+/// `<style …> … </style>` in ammonia's already-normalized output.
+static STYLE_BLOCK: LazyLock<Regex> = LazyLock::new(|| {
+ Regex::new(r"(?is)(<style\b[^>]*>)(.*?)(</style>)").expect("static regex is valid")
+});
+
+/// Scrubs the text content of every `<style>` element in sanitized HTML.
+///
+/// Ammonia's built-in CSS filter applies only to `style` *attributes*;
+/// `<style>` element content passes through verbatim, which would allow CSS
+/// overlay phishing and `@import`/`url()` exfiltration or tracking. This pass
+/// removes comments and `@import` rules and keeps only allowlisted,
+/// externally-inert declarations.
+fn sanitize_style_blocks(html: &str) -> String {
+ if !html.contains("<style") {
+ return html.to_string();
+ }
+
+ STYLE_BLOCK
+ .replace_all(html, |caps: &regex::Captures<'_>| {
+ format!(
+ "{}{}{}",
+ &caps[1],
+ sanitize_style_content(&caps[2]),
+ &caps[3]
+ )
+ })
+ .into_owned()
+}
+
+fn sanitize_style_content(css: &str) -> String {
+ let css = CSS_COMMENT.replace_all(css, "");
+ let css = CSS_IMPORT.replace_all(&css, "");
+
+ CSS_DECLARATION_BLOCK
+ .replace_all(&css, |caps: &regex::Captures<'_>| {
+ format!("{{{}}}", filter_css_declarations(&caps[1]))
+ })
+ .into_owned()
+}
+
+fn filter_css_declarations(declarations: &str) -> String {
+ let safe_properties = get_safe_css_properties();
+
+ declarations
+ .split(';')
+ .filter_map(|declaration| {
+ let (property, value) = declaration.split_once(':')?;
+ let property = property.trim().to_ascii_lowercase();
+ let value_lower = value.to_ascii_lowercase();
+ // Escapes (`\75 rl(`) could smuggle url() past a substring check,
+ // so any backslash disqualifies the declaration outright.
+ let value_is_inert = !value_lower.contains("url(")
+ && !value_lower.contains("expression(")
+ && !value_lower.contains('\\');
+ (safe_properties.contains(property.as_str()) && value_is_inert)
+ .then(|| format!("{}:{};", property, value.trim()))
+ })
+ .collect()
+}
+
// create a single time
-static CLEANER: Lazy<Builder<'static>> = Lazy::new(|| {
+static CLEANER: LazyLock<Builder<'static>> = LazyLock::new(|| {
let mut cleaner = Builder::default();
- // we are allowing style tags. ammonia has built-in css sanitization
+ // Keep <style> elements and their text. NOTE: ammonia's CSS filtering
+ // applies only to `style` attributes; element content is emitted verbatim,
+ // so sanitize_style_blocks scrubs it after cleaning.
cleaner.rm_clean_content_tags(&["style"]);
// Basic and layout tags
@@ -139,11 +219,13 @@ static CLEANER: Lazy<Builder<'static>> = Lazy::new(|| {
// Tag-specific attributes
// 'name' is used for anchor links within the email (e.g., Table of Contents)
cleaner.add_tag_attributes("a", &["href", "title", "target", "name"]);
+ // NOTE: `srcset` is deliberately absent — ammonia scheme-filters `src`
+ // but not the URL list inside `srcset`, so allowing it would let
+ // non-allowlisted schemes through. Images still render via `src`.
cleaner.add_tag_attributes(
"img",
&[
"src", "alt", "title", "width", "height", "border", "align", "vspace", "hspace",
- "srcset", "sizes",
],
);
cleaner.add_tag_attributes("font", &["color", "size", "face"]);
diff --git a/crates/email_api_client/src/outbound/gmail/convert/sanitizer/test.rs b/crates/email_api_client/src/outbound/gmail/convert/sanitizer/test.rs
new file mode 100644
index 0000000000..ab1831f149
--- /dev/null
+++ b/crates/email_api_client/src/outbound/gmail/convert/sanitizer/test.rs
@@ -0,0 +1,105 @@
+use super::*;
+
+#[test]
+fn strips_script_svg_math_and_foreign_object_vectors() {
+ let html = r#"<html><body>
+ <p>hello</p>
+ <script>steal()</script>
+ <svg><foreignObject><iframe src="https://evil.test"></iframe></foreignObject></svg>
+ <math><mtext><script>steal()</script></mtext></math>
+ </body></html>"#;
+
+ let sanitized = sanitize_email_html(html);
+
+ assert!(sanitized.contains("<p>hello</p>"));
+ for vector in [
+ "<script",
+ "<svg",
+ "<foreignObject",
+ "<math",
+ "<iframe",
+ "steal()",
+ ] {
+ assert!(!sanitized.contains(vector), "{vector} must be removed");
+ }
+}
+
+#[test]
+fn strips_dangerous_url_schemes_and_event_handlers() {
+ let html = r#"<body>
+ <a href="javascript:alert(1)">js</a>
+ <a href="data:text/html,<script>alert(1)</script>">data</a>
+ <a href="https://ok.example/">ok</a>
+ <img src="https://ok.example/pic.png" onerror="alert(1)" onload="alert(2)">
+ <div onclick="alert(3)">text</div>
+ </body>"#;
+
+ let sanitized = sanitize_email_html(html);
+
+ assert!(!sanitized.contains("javascript:"));
+ assert!(!sanitized.contains("data:"));
+ assert!(sanitized.contains(r#"href="https://ok.example/""#));
+ assert!(sanitized.contains(r#"src="https://ok.example/pic.png""#));
+ assert!(!sanitized.to_ascii_lowercase().contains("onerror"));
+ assert!(!sanitized.to_ascii_lowercase().contains("onload"));
+ assert!(!sanitized.to_ascii_lowercase().contains("onclick"));
+}
+
+#[test]
+fn style_element_content_loses_imports_and_external_references() {
+ let html = r#"<html><head><style>
+ @import url("https://tracker.test/steal.css");
+ .a { color: red; background-image: url("https://tracker.test/pixel.png"); }
+ .b { width: expression(alert(1)); margin: 4px; }
+ .c { font-size: \75 rl(https://tracker.test); }
+ </style></head><body><p>hi</p></body></html>"#;
+
+ let sanitized = sanitize_email_html(html);
+
+ assert!(sanitized.contains("<style>"));
+ assert!(!sanitized.to_ascii_lowercase().contains("@import"));
+ assert!(!sanitized.to_ascii_lowercase().contains("url("));
+ assert!(!sanitized.to_ascii_lowercase().contains("expression("));
+ assert!(!sanitized.contains("tracker.test"));
+ assert!(sanitized.contains("color:red;"));
+ assert!(sanitized.contains("margin:4px;"));
+}
+
+#[test]
+fn style_element_drops_non_allowlisted_overlay_properties() {
+ let html = r#"<body><style>
+ .overlay { position: fixed; z-index: 99999; color: blue; }
+ </style><p>content</p></body>"#;
+
+ let sanitized = sanitize_email_html(html);
+
+ assert!(!sanitized.contains("position"));
+ assert!(!sanitized.contains("z-index"));
+ assert!(sanitized.contains("color:blue;"));
+}
+
+#[test]
+fn media_query_structure_survives_declaration_filtering() {
+ let html = r#"<body><style>
+ @media (max-width: 600px) { .a { color: green; position: absolute; } }
+ </style><p>content</p></body>"#;
+
+ let sanitized = sanitize_email_html(html);
+
+ assert!(sanitized.contains("@media"));
+ assert!(sanitized.contains("color:green;"));
+ assert!(!sanitized.contains("position"));
+}
+
+#[test]
+fn fragments_are_cleaned_without_body_reconstruction() {
+ let fragment = r#"<p onclick="alert(1)">Sig</p><script>x()</script><style>.s{color:red;position:fixed}</style>"#;
+
+ let sanitized = sanitize_html_fragment(fragment);
+
+ assert!(sanitized.contains("Sig"));
+ assert!(!sanitized.contains("onclick"));
+ assert!(!sanitized.contains("<script"));
+ assert!(sanitized.contains("color:red;"));
+ assert!(!sanitized.contains("position"));
+}
diff --git a/crates/email_api_client/src/outbound/gmail/convert/thread.rs b/crates/email_api_client/src/outbound/gmail/convert/thread.rs
new file mode 100644
index 0000000000..3923a17fa7
--- /dev/null
+++ b/crates/email_api_client/src/outbound/gmail/convert/thread.rs
@@ -0,0 +1,67 @@
+use chrono::Utc;
+use models_email::email::service;
+use models_email::email::service::message::{is_inbound, is_outbound, is_spam_or_trash};
+use models_email::gmail::ThreadResource;
+use uuid::Uuid;
+
+use super::message::map_message_resource_to_service;
+use crate::domain::models::EmailApiError;
+
+pub(crate) fn map_thread_resource_to_service(
+ resource: ThreadResource,
+ link_id: Uuid,
+) -> Result<service::thread::Thread, EmailApiError> {
+ // Accepted trade-off: messages convert sequentially (main spawned a task
+ // per message). Conversion is dominated by ammonia sanitization, which is
+ // fast relative to the surrounding provider fetch; if profiling ever shows
+ // large threads stalling runtime workers, batch the conversions through
+ // spawn_blocking rather than reintroducing spawn-per-message.
+ let mut messages = resource
+ .messages
+ .into_iter()
+ .map(|message| map_message_resource_to_service(message, link_id))
+ .collect::<Result<Vec<_>, _>>()?;
+ messages.sort_by_key(|message| message.internal_date_ts);
+
+ let inbox_visible = messages.iter().any(|message| {
+ message
+ .labels
+ .iter()
+ .any(|label| label.provider_label_id == service::label::system_labels::INBOX)
+ });
+ let is_read = messages.iter().all(|message| message.is_read);
+ let latest_inbound_message_ts = messages
+ .iter()
+ .rfind(|message| is_inbound(message))
+ .and_then(|message| message.internal_date_ts);
+ let latest_outbound_message_ts = messages
+ .iter()
+ .rfind(|message| is_outbound(message))
+ .and_then(|message| message.internal_date_ts);
+ let latest_non_spam_message_ts = messages
+ .iter()
+ .rfind(|message| !is_spam_or_trash(message))
+ .and_then(|message| message.internal_date_ts);
+
+ let thread_db_id = Uuid::now_v7();
+ for message in &mut messages {
+ message.thread_db_id = thread_db_id;
+ }
+
+ Ok(service::thread::Thread {
+ db_id: thread_db_id,
+ provider_id: Some(resource.id),
+ link_id,
+ inbox_visible,
+ is_read,
+ latest_inbound_message_ts,
+ latest_outbound_message_ts,
+ latest_non_spam_message_ts,
+ created_at: Utc::now(),
+ updated_at: Utc::now(),
+ messages,
+ })
+}
+
+#[cfg(test)]
+mod test;
diff --git a/crates/email_api_client/src/outbound/gmail/convert/thread/test.rs b/crates/email_api_client/src/outbound/gmail/convert/thread/test.rs
new file mode 100644
index 0000000000..36acf09bbf
--- /dev/null
+++ b/crates/email_api_client/src/outbound/gmail/convert/thread/test.rs
@@ -0,0 +1,81 @@
+use base64::{Engine as _, engine::general_purpose::URL_SAFE};
+use models_email::gmail::{Header, MessagePart, MessagePartBody, MessageResource, ThreadResource};
+use uuid::Uuid;
+
+use super::map_thread_resource_to_service;
+
+fn message(id: &str, timestamp: i64, labels: Vec<String>) -> MessageResource {
+ MessageResource {
+ id: id.into(),
+ thread_id: "thread".into(),
+ label_ids: labels,
+ snippet: String::new(),
+ size_estimate: 1,
+ history_id: "history".into(),
+ internal_date: timestamp.to_string(),
+ payload: MessagePart {
+ part_id: String::new(),
+ mime_type: "text/plain".into(),
+ filename: String::new(),
+ headers: vec![
+ Header {
+ name: "Message-ID".into(),
+ value: id.into(),
+ },
+ Header {
+ name: "From".into(),
+ value: "[email protected]".into(),
+ },
+ ],
+ body: Some(MessagePartBody {
+ attachment_id: None,
+ size: 0,
+ data_base64: Some(URL_SAFE.encode("")),
+ }),
+ parts: None,
+ },
+ }
+}
+
+#[test]
+fn thread_with_an_undecodable_message_body_still_converts() {
+ let mut broken = message("broken", 1_000, vec!["INBOX".into()]);
+ broken.payload.body = Some(MessagePartBody {
+ attachment_id: None,
+ size: 3,
+ data_base64: Some("%%%".into()),
+ });
+ let resource = ThreadResource {
+ id: "thread".into(),
+ messages: vec![broken, message("fine", 2_000, vec![])],
+ };
+
+ let thread = map_thread_resource_to_service(resource, Uuid::now_v7()).unwrap();
+
+ assert_eq!(thread.messages.len(), 2);
+ assert_eq!(thread.messages[0].provider_id.as_deref(), Some("broken"));
+ assert_eq!(thread.messages[0].body_text, None);
+}
+
+#[test]
+fn sorts_messages_and_derives_thread_state() {
+ let resource = ThreadResource {
+ id: "thread".into(),
+ messages: vec![
+ message("later", 2_000, vec!["INBOX".into()]),
+ message("earlier", 1_000, vec!["UNREAD".into()]),
+ ],
+ };
+
+ let thread = map_thread_resource_to_service(resource, Uuid::now_v7()).unwrap();
+
+ assert_eq!(thread.messages[0].provider_id.as_deref(), Some("earlier"));
+ assert!(thread.inbox_visible);
+ assert!(!thread.is_read);
+ assert!(
+ thread
+ .messages
+ .iter()
+ .all(|message| message.thread_db_id == thread.db_id)
+ );
+}
diff --git a/crates/email_api_client/src/outbound/gmail/labels.rs b/crates/email_api_client/src/outbound/gmail/labels.rs
new file mode 100644
index 0000000000..eeb981b212
--- /dev/null
+++ b/crates/email_api_client/src/outbound/gmail/labels.rs
@@ -0,0 +1,64 @@
+//! Gmail label capability implementation.
+
+use models_email::gmail::labels::{GmailLabel, GmailLabelsResponse};
+use models_email::service::label::Label;
+use uuid::Uuid;
+
+use crate::domain::models::{AccessToken, EmailApiError};
+use crate::domain::ports::MailboxLabelClient;
+
+use super::convert::{map_label_to_service, map_labels_to_service};
+use super::{GmailApiClientRepository, map_gmail_error};
+
+impl MailboxLabelClient for GmailApiClientRepository {
+ async fn list_labels(
+ &self,
+ access_token: &AccessToken,
+ link_id: Uuid,
+ ) -> Result<Vec<Label>, EmailApiError> {
+ let labels = self
+ .client
+ .fetch_user_labels(access_token.expose_secret())
+ .await
+ .map_err(map_gmail_error)?;
+ map_labels_to_service(&GmailLabelsResponse { labels }, link_id)
+ }
+
+ async fn create_label(
+ &self,
+ access_token: &AccessToken,
+ link_id: Uuid,
+ name: &str,
+ ) -> Result<Label, EmailApiError> {
+ let request = GmailLabel {
+ id: None,
+ name: name.to_owned(),
+ message_list_visibility: Some("show".to_string()),
+ label_list_visibility: Some("labelShow".to_string()),
+ type_: Some("user".to_string()),
+ color: None,
+ };
+ let label = self
+ .client
+ .create_label(access_token.expose_secret(), &request)
+ .await
+ .map_err(map_gmail_error)?;
+ map_label_to_service(&label, link_id)
+ }
+
+ async fn delete_label(
+ &self,
+ access_token: &AccessToken,
+ provider_label_id: &str,
+ ) -> Result<(), EmailApiError> {
+ match self
+ .client
+ .delete_label(access_token.expose_secret(), provider_label_id)
+ .await
+ {
+ Ok(()) => Ok(()),
+ Err(error) if error.status().is_some_and(|status| status.as_u16() == 404) => Ok(()),
+ Err(error) => Err(map_gmail_error(error)),
+ }
+ }
+}
diff --git a/crates/email_api_client/src/outbound/gmail/messages.rs b/crates/email_api_client/src/outbound/gmail/messages.rs
new file mode 100644
index 0000000000..16df92e566
--- /dev/null
+++ b/crates/email_api_client/src/outbound/gmail/messages.rs
@@ -0,0 +1,194 @@
+//! Gmail message capability implementation.
+
+use base64::{
+ Engine as _,
+ engine::general_purpose::{URL_SAFE, URL_SAFE_NO_PAD},
+};
+use models_email::email::service::message::Message;
+use models_email::email::service::thread::ThreadSummary;
+use models_email::gmail::MessagePart;
+use uuid::Uuid;
+
+use crate::domain::models::{
+ AccessToken, CalendarPart, EmailApiError, MessageWithCalendarParts, ThreadListPage,
+};
+use crate::domain::ports::{MailboxCalendarClient, MailboxMessageClient};
+
+use super::convert::{map_message_resource_to_service, map_thread_resource_to_service};
+use super::{GmailApiClientRepository, map_gmail_error};
+
+impl MailboxCalendarClient for GmailApiClientRepository {
+ async fn get_calendar_parts(
+ &self,
+ access_token: &AccessToken,
+ provider_message_id: &str,
+ ) -> Result<Vec<CalendarPart>, EmailApiError> {
+ let Some(message) = self
+ .client
+ .get_message(access_token.expose_secret(), provider_message_id)
+ .await
+ .map_err(map_gmail_error)?
+ else {
+ return Ok(Vec::new());
+ };
+
+ collect_calendar_parts(&message.payload)
+ }
+}
+
+fn collect_calendar_parts(root: &MessagePart) -> Result<Vec<CalendarPart>, EmailApiError> {
+ let mut result = Vec::new();
+ let mut stack = vec![root];
+ while let Some(part) = stack.pop() {
+ let mime_type = part.mime_type.split(';').next().unwrap_or_default().trim();
+ let is_calendar = mime_type.eq_ignore_ascii_case("text/calendar")
+ || mime_type.eq_ignore_ascii_case("application/ics")
+ || part.filename.to_ascii_lowercase().ends_with(".ics");
+ if is_calendar {
+ let body = part.body.as_ref();
+ let inline_data =
+ body.and_then(|body| body.data_base64.as_deref())
+ .and_then(|encoded| {
+ URL_SAFE_NO_PAD
+ .decode(encoded)
+ .or_else(|_| URL_SAFE.decode(encoded))
+ .ok()
+ });
+ result.push(CalendarPart {
+ part_id: (!part.part_id.is_empty()).then(|| part.part_id.clone()),
+ filename: (!part.filename.is_empty()).then(|| part.filename.clone()),
+ mime_type: part.mime_type.clone(),
+ inline_data,
+ provider_attachment_id: body.and_then(|body| body.attachment_id.clone()),
+ });
+ }
+ if let Some(children) = &part.parts {
+ stack.extend(children);
+ }
+ }
+ Ok(result)
+}
+
+impl MailboxMessageClient for GmailApiClientRepository {
+ async fn get_message(
+ &self,
+ access_token: &AccessToken,
+ link_id: Uuid,
+ provider_message_id: &str,
+ ) -> Result<Option<MessageWithCalendarParts>, EmailApiError> {
+ let Some(resource) = self
+ .client
+ .get_message(access_token.expose_secret(), provider_message_id)
+ .await
+ .map_err(map_gmail_error)?
+ else {
+ return Ok(None);
+ };
+
+ // Extract calendar parts from the wire resource we already hold so
+ // ingest never needs a second messages.get for the same message.
+ let calendar_parts = collect_calendar_parts(&resource.payload)?;
+ let message = map_message_resource_to_service(resource, link_id)?;
+
+ Ok(Some(MessageWithCalendarParts {
+ message,
+ calendar_parts,
+ }))
+ }
+
+ async fn get_message_label_ids(
+ &self,
+ access_token: &AccessToken,
+ provider_message_id: &str,
+ ) -> Result<Option<Vec<String>>, EmailApiError> {
+ self.client
+ .get_message_label_ids(access_token.expose_secret(), provider_message_id)
+ .await
+ .map_err(map_gmail_error)
+ }
+
+ async fn list_messages(
+ &self,
+ access_token: &AccessToken,
+ limit: u32,
+ label_ids: &[&str],
+ ) -> Result<Vec<String>, EmailApiError> {
+ self.client
+ .list_messages(access_token.expose_secret(), limit, label_ids)
+ .await
+ .map_err(map_gmail_error)
+ }
+
+ async fn get_message_ids_for_thread(
+ &self,
+ access_token: &AccessToken,
+ provider_thread_id: &str,
+ ) -> Result<Vec<String>, EmailApiError> {
+ self.client
+ .get_message_ids_for_thread(access_token.expose_secret(), provider_thread_id)
+ .await
+ .map_err(map_gmail_error)
+ }
+
+ async fn get_thread(
+ &self,
+ access_token: &AccessToken,
+ link_id: Uuid,
+ provider_thread_id: &str,
+ ) -> Result<Vec<Message>, EmailApiError> {
+ let resource = self
+ .client
+ .get_thread(access_token.expose_secret(), provider_thread_id)
+ .await
+ .map_err(map_gmail_error)?;
+ Ok(map_thread_resource_to_service(resource, link_id)?.messages)
+ }
+
+ async fn list_threads(
+ &self,
+ access_token: &AccessToken,
+ limit: u32,
+ next_page_token: Option<&str>,
+ label_ids: &[&str],
+ ) -> Result<ThreadListPage, EmailApiError> {
+ let response = self
+ .client
+ .list_threads(
+ access_token.expose_secret(),
+ limit,
+ next_page_token,
+ label_ids,
+ )
+ .await
+ .map_err(map_gmail_error)?;
+ Ok(ThreadListPage {
+ threads: response
+ .threads
+ .unwrap_or_default()
+ .into_iter()
+ .map(|thread| ThreadSummary {
+ provider_id: thread.id,
+ })
+ .collect(),
+ next_page_token: response.next_page_token,
+ })
+ }
+
+ async fn modify_message_labels(
+ &self,
+ access_token: &AccessToken,
+ provider_message_id: &str,
+ label_ids_to_add: &[String],
+ label_ids_to_remove: &[String],
+ ) -> Result<(), EmailApiError> {
+ self.client
+ .modify_message_labels(
+ access_token.expose_secret(),
+ provider_message_id,
+ label_ids_to_add,
+ label_ids_to_remove,
+ )
+ .await
+ .map_err(map_gmail_error)
+ }
+}
diff --git a/crates/email_api_client/src/outbound/gmail/mod.rs b/crates/email_api_client/src/outbound/gmail/mod.rs
new file mode 100644
index 0000000000..553d31ae85
--- /dev/null
+++ b/crates/email_api_client/src/outbound/gmail/mod.rs
@@ -0,0 +1,161 @@
+//! Gmail implementation of the provider-neutral email API capabilities.
+
+mod attachments;
+mod blocklist;
+mod contacts;
+pub(crate) mod convert;
+
+pub use convert::sanitizer::{sanitize_email_html, sanitize_html_fragment};
+mod labels;
+mod messages;
+mod send;
+mod subscription;
+mod sync;
+
+#[cfg(test)]
+mod test;
+
+use gmail_client::{GmailApiHttpError, GmailClient};
+use models_email::gmail::inbox_sync::{
+ GoogleJwtClaims, GooglePublicKeys, JwtVerificationError, KeyMap,
+};
+
+use crate::domain::models::{EmailApiError, RateLimitOrigin};
+
+const WATCH_CONFLICT_BODY_FRAGMENT: &str = "push notification client allowed";
+
+/// Gmail-backed implementation of the email API capability ports.
+///
+/// The raw Gmail client remains encapsulated by this adapter. Composition roots
+/// that only need email capabilities can construct the repository directly from
+/// a subscription topic.
+#[derive(Clone, Debug)]
+pub struct GmailApiClientRepository {
+ client: GmailClient,
+}
+
+impl GmailApiClientRepository {
+ /// Creates a repository from an existing Gmail wire client.
+ pub fn new(client: GmailClient) -> Self {
+ Self { client }
+ }
+
+ /// Creates a repository configured to publish watch events to `subscription_topic`.
+ pub fn from_subscription_topic(subscription_topic: impl Into<String>) -> Self {
+ Self::new(GmailClient::new(subscription_topic.into()))
+ }
+
+ /// Fetches Google's public keys used to verify Gmail webhook JWTs.
+ ///
+ /// Webhook authentication is intentionally exposed as an inherent adapter
+ /// operation rather than as a provider-neutral mailbox capability.
+ pub async fn get_google_public_keys(&self) -> Result<GooglePublicKeys, EmailApiError> {
+ self.client
+ .get_google_public_keys()
+ .await
+ .map_err(map_gmail_error)
+ }
+
+ /// Verifies a Gmail webhook JWT with previously fetched Google public keys.
+ ///
+ /// This provider-specific authentication operation does not belong to the
+ /// neutral email capability traits.
+ pub fn verify_google_token(
+ &self,
+ token: &str,
+ public_keys: KeyMap,
+ ) -> Result<GoogleJwtClaims, JwtVerificationError> {
+ self.client.verify_google_token(token, public_keys)
+ }
+}
+
+/// Gmail signals per-user quota exhaustion as HTTP 403 with one of these
+/// `reason` strings; 429 is only one of its rate-limit forms.
+const QUOTA_403_REASONS: [&str; 4] = [
+ "userRateLimitExceeded",
+ "rateLimitExceeded",
+ "dailyLimitExceeded",
+ "quotaExceeded",
+];
+
+fn is_quota_403_body(body: &str) -> bool {
+ QUOTA_403_REASONS.iter().any(|reason| body.contains(reason))
+}
+
+pub(crate) fn map_gmail_error(error: GmailApiHttpError) -> EmailApiError {
+ match error {
+ GmailApiHttpError::Http {
+ status,
+ body,
+ retry_after,
+ } => match status.as_u16() {
+ 401 => EmailApiError::AuthRequired,
+ 403 if is_quota_403_body(&body) => EmailApiError::RateLimited {
+ retry_after,
+ origin: RateLimitOrigin::Provider,
+ },
+ 403 => EmailApiError::Forbidden,
+ 404 => EmailApiError::NotFound,
+ 409 => EmailApiError::Conflict,
+ 429 => EmailApiError::RateLimited {
+ retry_after,
+ origin: RateLimitOrigin::Provider,
+ },
+ 500..=599 => EmailApiError::Transient {
+ message: format!("Gmail API returned {status}: {body}"),
+ },
+ _ => EmailApiError::Permanent {
+ message: format!("Gmail API returned {status}: {body}"),
+ },
+ },
+ GmailApiHttpError::Transport(error) => EmailApiError::Transient {
+ message: format!("Gmail API transport error: {error}"),
+ },
+ GmailApiHttpError::Decode(error) => EmailApiError::Permanent {
+ message: format!("Gmail API response decode error: {error}"),
+ },
+ GmailApiHttpError::InvalidResponse(message) => EmailApiError::Permanent {
+ message: format!("Gmail API returned an invalid response: {message}"),
+ },
+ }
+}
+
+pub(crate) fn map_history_error(error: GmailApiHttpError) -> EmailApiError {
+ if error.status().is_some_and(|status| status.as_u16() == 404) {
+ return EmailApiError::OutdatedCursor;
+ }
+
+ map_gmail_error(error)
+}
+
+pub(crate) fn is_watch_conflict(error: &GmailApiHttpError) -> bool {
+ error.status().is_some_and(|status| status.as_u16() == 400)
+ && error.body().is_some_and(|body| {
+ body.to_ascii_lowercase()
+ .contains(WATCH_CONFLICT_BODY_FRAGMENT)
+ })
+}
+
+/// People API reports an expired contacts sync token (~7-day expiry) as
+/// HTTP 400 with this reason; it is a stale cursor, not a permanent failure.
+const EXPIRED_SYNC_TOKEN_FRAGMENT: &str = "EXPIRED_SYNC_TOKEN";
+
+pub(crate) fn map_contacts_error(error: GmailApiHttpError) -> EmailApiError {
+ if error.status().is_some_and(|status| status.as_u16() == 400)
+ && error
+ .body()
+ .is_some_and(|body| body.contains(EXPIRED_SYNC_TOKEN_FRAGMENT))
+ {
+ return EmailApiError::OutdatedCursor;
+ }
+
+ map_gmail_error(error)
+}
+
+pub(crate) fn map_watch_error(error: GmailApiHttpError) -> EmailApiError {
+ if is_watch_conflict(&error) {
+ return EmailApiError::Conflict;
+ }
+
+ map_gmail_error(error)
+}
diff --git a/crates/email_api_client/src/outbound/gmail/send.rs b/crates/email_api_client/src/outbound/gmail/send.rs
new file mode 100644
index 0000000000..9908bea3bc
--- /dev/null
+++ b/crates/email_api_client/src/outbound/gmail/send.rs
@@ -0,0 +1,27 @@
+//! Gmail send capability implementation.
+
+use crate::domain::models::{AccessToken, EmailApiError, SendRequest, SentIds};
+use crate::domain::ports::MailboxSendClient;
+
+use super::{GmailApiClientRepository, map_gmail_error};
+
+impl MailboxSendClient for GmailApiClientRepository {
+ async fn send_message(
+ &self,
+ access_token: &AccessToken,
+ request: &SendRequest,
+ provider_thread_id: Option<&str>,
+ ) -> Result<SentIds, EmailApiError> {
+ let mime = request.build_mime()?;
+ let sent = self
+ .client
+ .send_message(access_token.expose_secret(), &mime, provider_thread_id)
+ .await
+ .map_err(map_gmail_error)?;
+
+ Ok(SentIds {
+ provider_message_id: sent.id,
+ provider_thread_id: sent.thread_id,
+ })
+ }
+}
diff --git a/crates/email_api_client/src/outbound/gmail/subscription.rs b/crates/email_api_client/src/outbound/gmail/subscription.rs
new file mode 100644
index 0000000000..0ca805b38b
--- /dev/null
+++ b/crates/email_api_client/src/outbound/gmail/subscription.rs
@@ -0,0 +1,61 @@
+//! Gmail mailbox-subscription capability implementation.
+
+use chrono::{TimeZone, Utc};
+
+use crate::domain::models::{AccessToken, EmailApiError, ProviderSubscription, SyncCursor};
+use crate::domain::ports::MailboxSubscriptionClient;
+
+use super::{GmailApiClientRepository, is_watch_conflict, map_gmail_error, map_watch_error};
+
+impl MailboxSubscriptionClient for GmailApiClientRepository {
+ async fn subscribe(
+ &self,
+ access_token: &AccessToken,
+ ) -> Result<ProviderSubscription, EmailApiError> {
+ let token = access_token.expose_secret();
+ let watch = match self.client.register_watch(token).await {
+ Ok(watch) => watch,
+ Err(error) if is_watch_conflict(&error) => {
+ tracing::warn!(
+ error = %error,
+ "Gmail watch conflict; stopping the existing watch and retrying once"
+ );
+ self.client
+ .stop_watch(token)
+ .await
+ .map_err(map_gmail_error)?;
+ self.client
+ .register_watch(token)
+ .await
+ .map_err(map_watch_error)?
+ }
+ Err(error) => return Err(map_watch_error(error)),
+ };
+
+ let expiration =
+ watch
+ .expiration
+ .parse::<i64>()
+ .map_err(|error| EmailApiError::Permanent {
+ message: format!("Gmail watch returned an invalid expiration: {error}"),
+ })?;
+ let expires_at = Utc
+ .timestamp_millis_opt(expiration)
+ .single()
+ .ok_or_else(|| EmailApiError::Permanent {
+ message: "Gmail watch returned an out-of-range expiration".to_string(),
+ })?;
+
+ Ok(ProviderSubscription::new(
+ SyncCursor::gmail(watch.history_id),
+ expires_at,
+ ))
+ }
+
+ async fn unsubscribe(&self, access_token: &AccessToken) -> Result<(), EmailApiError> {
+ self.client
+ .stop_watch(access_token.expose_secret())
+ .await
+ .map_err(map_gmail_error)
+ }
+}
diff --git a/crates/email_api_client/src/outbound/gmail/sync.rs b/crates/email_api_client/src/outbound/gmail/sync.rs
new file mode 100644
index 0000000000..772a2dd789
--- /dev/null
+++ b/crates/email_api_client/src/outbound/gmail/sync.rs
@@ -0,0 +1,36 @@
+//! Gmail mailbox-sync capability implementation.
+
+use crate::domain::models::{AccessToken, ChangeBatch, EmailApiError, SyncCursor};
+use crate::domain::ports::MailboxSyncClient;
+
+use super::convert::map_history_list_response_to_changes;
+use super::{GmailApiClientRepository, map_gmail_error, map_history_error};
+
+impl MailboxSyncClient for GmailApiClientRepository {
+ async fn get_thread_count(&self, access_token: &AccessToken) -> Result<u64, EmailApiError> {
+ let profile = self
+ .client
+ .get_profile(access_token.expose_secret())
+ .await
+ .map_err(map_gmail_error)?;
+ u64::try_from(profile.threads_total).map_err(|_| EmailApiError::Permanent {
+ message: format!(
+ "Gmail profile returned a negative thread count: {}",
+ profile.threads_total
+ ),
+ })
+ }
+
+ async fn list_changes(
+ &self,
+ access_token: &AccessToken,
+ cursor: &SyncCursor,
+ ) -> Result<ChangeBatch, EmailApiError> {
+ let history = self
+ .client
+ .get_history(access_token.expose_secret(), cursor.as_str())
+ .await
+ .map_err(map_history_error)?;
+ Ok(map_history_list_response_to_changes(history))
+ }
+}
diff --git a/crates/email_api_client/src/outbound/gmail/test/attachments.rs b/crates/email_api_client/src/outbound/gmail/test/attachments.rs
new file mode 100644
index 0000000000..ef54ab050d
--- /dev/null
+++ b/crates/email_api_client/src/outbound/gmail/test/attachments.rs
@@ -0,0 +1,48 @@
+use wiremock::matchers::{method, path};
+use wiremock::{Mock, ResponseTemplate};
+
+use super::repository;
+use crate::domain::models::{AccessToken, EmailApiError};
+use crate::domain::ports::MailboxAttachmentClient;
+
+#[tokio::test]
+async fn downloads_and_decodes_base64url_attachments() {
+ let (server, repository) = repository().await;
+ Mock::given(method("GET"))
+ .and(path(
+ "/users/me/messages/message-1/attachments/attachment-1",
+ ))
+ .respond_with(
+ ResponseTemplate::new(200)
+ .set_body_raw(include_str!("fixtures/attachment.json"), "application/json"),
+ )
+ .mount(&server)
+ .await;
+
+ assert_eq!(
+ repository
+ .get_attachment(&AccessToken::new("token"), "message-1", "attachment-1",)
+ .await
+ .unwrap(),
+ b"Hello"
+ );
+}
+
+#[tokio::test]
+async fn invalid_attachment_data_is_permanent() {
+ let (server, repository) = repository().await;
+ Mock::given(method("GET"))
+ .and(path("/users/me/messages/message-1/attachments/invalid"))
+ .respond_with(
+ ResponseTemplate::new(200).set_body_json(serde_json::json!({"size": 1, "data": "!"})),
+ )
+ .mount(&server)
+ .await;
+
+ assert!(matches!(
+ repository
+ .get_attachment(&AccessToken::new("token"), "message-1", "invalid")
+ .await,
+ Err(EmailApiError::Permanent { .. })
+ ));
+}
diff --git a/crates/email_api_client/src/outbound/gmail/test/blocklist.rs b/crates/email_api_client/src/outbound/gmail/test/blocklist.rs
new file mode 100644
index 0000000000..5aa05a2b17
--- /dev/null
+++ b/crates/email_api_client/src/outbound/gmail/test/blocklist.rs
@@ -0,0 +1,193 @@
+use gmail_client::GmailClient;
+use serde_json::{Value, json};
+use wiremock::matchers::{body_json, method, path};
+use wiremock::{Mock, MockServer, ResponseTemplate};
+
+use crate::domain::models::AccessToken;
+use crate::domain::ports::MailboxBlocklistClient;
+use crate::outbound::gmail::GmailApiClientRepository;
+
+fn repository(server: &MockServer) -> GmailApiClientRepository {
+ GmailApiClientRepository::new(GmailClient::new_with_urls(
+ "projects/p/topics/mail".to_string(),
+ server.uri(),
+ server.uri(),
+ server.uri(),
+ "audience".to_string(),
+ ))
+}
+
+async fn mount_filters(server: &MockServer, filters: Value) {
+ Mock::given(method("GET"))
+ .and(path("/users/me/settings/filters"))
+ .respond_with(ResponseTemplate::new(200).set_body_json(filters))
+ .mount(server)
+ .await;
+}
+
+#[tokio::test]
+async fn list_returns_only_sender_filters_that_add_trash() {
+ let server = MockServer::start().await;
+ mount_filters(
+ &server,
+ serde_json::from_str(include_str!("fixtures/filters.json")).unwrap(),
+ )
+ .await;
+
+ let blocked = repository(&server)
+ .list_blocked_senders(&AccessToken::new("token"))
+ .await
+ .unwrap();
+
+ assert_eq!(blocked, vec!["[email protected]"]);
+}
+
+#[tokio::test]
+async fn blocking_an_existing_sender_is_idempotent() {
+ let server = MockServer::start().await;
+ mount_filters(
+ &server,
+ serde_json::from_str(include_str!("fixtures/filters.json")).unwrap(),
+ )
+ .await;
+
+ repository(&server)
+ .block_sender(&AccessToken::new("token"), "[email protected]")
+ .await
+ .unwrap();
+
+ let requests = server.received_requests().await.unwrap();
+ assert_eq!(requests.len(), 1);
+ assert_eq!(requests[0].method.as_str(), "GET");
+}
+
+#[tokio::test]
+async fn block_creates_a_sender_to_trash_filter() {
+ let server = MockServer::start().await;
+ mount_filters(&server, json!({ "filter": [] })).await;
+ let expected = json!({
+ "criteria": { "from": "[email protected]" },
+ "action": { "addLabelIds": ["TRASH"] }
+ });
+ Mock::given(method("POST"))
+ .and(path("/users/me/settings/filters"))
+ .and(body_json(expected.clone()))
+ .respond_with(ResponseTemplate::new(200).set_body_json(expected))
+ .expect(1)
+ .mount(&server)
+ .await;
+
+ repository(&server)
+ .block_sender(&AccessToken::new("token"), "[email protected]")
+ .await
+ .unwrap();
+}
+
+#[tokio::test]
+async fn blocking_is_idempotent_across_address_casing() {
+ let server = MockServer::start().await;
+ mount_filters(
+ &server,
+ json!({
+ "filter": [{
+ "id": "blocked-cased",
+ "criteria": { "from": "[email protected]" },
+ "action": { "addLabelIds": ["TRASH"] }
+ }]
+ }),
+ )
+ .await;
+
+ repository(&server)
+ .block_sender(&AccessToken::new("token"), "[email protected]")
+ .await
+ .unwrap();
+
+ let requests = server.received_requests().await.unwrap();
+ assert_eq!(requests.len(), 1, "no duplicate filter may be created");
+ assert_eq!(requests[0].method.as_str(), "GET");
+}
+
+#[tokio::test]
+async fn unblock_matches_filters_case_insensitively_and_deletes_all_duplicates() {
+ let server = MockServer::start().await;
+ mount_filters(
+ &server,
+ json!({
+ "filter": [
+ {
+ "id": "blocked-upper",
+ "criteria": { "from": "[email protected]" },
+ "action": { "addLabelIds": ["TRASH"] }
+ },
+ {
+ "id": "other",
+ "criteria": { "from": "[email protected]" },
+ "action": { "addLabelIds": ["TRASH"] }
+ },
+ {
+ "id": "blocked-lower",
+ "criteria": { "from": "[email protected]" },
+ "action": { "addLabelIds": ["TRASH"] }
+ }
+ ]
+ }),
+ )
+ .await;
+ Mock::given(method("DELETE"))
+ .and(path("/users/me/settings/filters/blocked-upper"))
+ .respond_with(ResponseTemplate::new(204))
+ .expect(1)
+ .mount(&server)
+ .await;
+ Mock::given(method("DELETE"))
+ .and(path("/users/me/settings/filters/blocked-lower"))
+ .respond_with(ResponseTemplate::new(204))
+ .expect(1)
+ .mount(&server)
+ .await;
+
+ repository(&server)
+ .unblock_sender(&AccessToken::new("token"), "[email protected]")
+ .await
+ .unwrap();
+
+ let requests = server.received_requests().await.unwrap();
+ assert_eq!(requests.len(), 3, "one list plus exactly two deletes");
+}
+
+#[tokio::test]
+async fn unblocking_a_missing_sender_is_idempotent() {
+ let server = MockServer::start().await;
+ mount_filters(&server, json!({ "filter": [] })).await;
+
+ repository(&server)
+ .unblock_sender(&AccessToken::new("token"), "[email protected]")
+ .await
+ .unwrap();
+
+ let requests = server.received_requests().await.unwrap();
+ assert_eq!(requests.len(), 1);
+ assert_eq!(requests[0].method.as_str(), "GET");
+}
+
+#[tokio::test]
+async fn unblock_deletes_the_matching_block_filter() {
+ let server = MockServer::start().await;
+ mount_filters(
+ &server,
+ serde_json::from_str(include_str!("fixtures/filters.json")).unwrap(),
+ )
+ .await;
+ Mock::given(method("DELETE"))
+ .and(path("/users/me/settings/filters/blocked-1"))
+ .respond_with(ResponseTemplate::new(204))
+ .expect(1)
+ .mount(&server)
+ .await;
+
+ repository(&server)
+ .unblock_sender(&AccessToken::new("token"), "[email protected]")
+ .await
+ .unwrap();
+}
diff --git a/crates/email_api_client/src/outbound/gmail/test/contacts.rs b/crates/email_api_client/src/outbound/gmail/test/contacts.rs
new file mode 100644
index 0000000000..f8a4da0582
--- /dev/null
+++ b/crates/email_api_client/src/outbound/gmail/test/contacts.rs
@@ -0,0 +1,82 @@
+use uuid::Uuid;
+use wiremock::matchers::{method, path, query_param};
+use wiremock::{Mock, ResponseTemplate};
+
+use super::repository;
+use crate::domain::models::AccessToken;
+use crate::domain::ports::MailboxContactsClient;
+
+#[tokio::test]
+async fn paginates_contacts_and_returns_the_final_sync_token() {
+ let (server, repository) = repository().await;
+ Mock::given(method("GET"))
+ .and(path("/people/me/connections"))
+ .and(query_param("requestSyncToken", "true"))
+ .respond_with(ResponseTemplate::new(200).set_body_raw(
+ include_str!("fixtures/contacts_page_1.json"),
+ "application/json",
+ ))
+ .up_to_n_times(1)
+ .mount(&server)
+ .await;
+ Mock::given(method("GET"))
+ .and(path("/people/me/connections"))
+ .and(query_param("pageToken", "contacts-next"))
+ .respond_with(ResponseTemplate::new(200).set_body_raw(
+ include_str!("fixtures/contacts_page_2.json"),
+ "application/json",
+ ))
+ .mount(&server)
+ .await;
+
+ let contacts = repository
+ .list_contacts(&AccessToken::new("token"), Uuid::now_v7(), None)
+ .await
+ .unwrap();
+ assert_eq!(contacts.contacts.len(), 2);
+ assert_eq!(contacts.next_sync_token, "contacts-sync-final");
+ assert_eq!(
+ contacts.contacts[1].original_photo_url.as_deref(),
+ Some("https://lh3.googleusercontent.test/second=s128")
+ );
+}
+
+#[tokio::test]
+async fn normalizes_self_and_other_contacts() {
+ let (server, repository) = repository().await;
+ Mock::given(method("GET"))
+ .and(path("/people/me"))
+ .respond_with(
+ ResponseTemplate::new(200)
+ .set_body_raw(include_str!("fixtures/person.json"), "application/json"),
+ )
+ .mount(&server)
+ .await;
+ Mock::given(method("GET"))
+ .and(path("/otherContacts"))
+ .and(query_param("syncToken", "previous"))
+ .respond_with(ResponseTemplate::new(200).set_body_raw(
+ include_str!("fixtures/other_contacts.json"),
+ "application/json",
+ ))
+ .mount(&server)
+ .await;
+
+ let link_id = Uuid::now_v7();
+ let own = repository
+ .get_self_contact(&AccessToken::new("token"), link_id)
+ .await
+ .unwrap();
+ assert_eq!(own.name.as_deref(), Some("Mailbox User"));
+ assert_eq!(
+ own.original_photo_url.as_deref(),
+ Some("https://lh3.googleusercontent.test/photo=s128")
+ );
+
+ let other = repository
+ .list_other_contacts(&AccessToken::new("token"), link_id, Some("previous"))
+ .await
+ .unwrap();
+ assert_eq!(other.next_sync_token, "other-sync-final");
+ assert_eq!(other.contacts[0].link_id, link_id);
+}
diff --git a/crates/email_api_client/src/outbound/gmail/test/error.rs b/crates/email_api_client/src/outbound/gmail/test/error.rs
new file mode 100644
index 0000000000..3b26196c4e
--- /dev/null
+++ b/crates/email_api_client/src/outbound/gmail/test/error.rs
@@ -0,0 +1,191 @@
+use std::time::Duration;
+
+use gmail_client::GmailApiHttpError;
+use http::StatusCode;
+
+use crate::domain::models::{EmailApiError, RateLimitOrigin};
+use crate::outbound::gmail::{
+ GmailApiClientRepository, map_contacts_error, map_gmail_error, map_history_error,
+ map_watch_error,
+};
+
+fn http_error(
+ status: StatusCode,
+ body: impl Into<String>,
+ retry_after: Option<Duration>,
+) -> GmailApiHttpError {
+ GmailApiHttpError::Http {
+ status,
+ body: body.into(),
+ retry_after,
+ }
+}
+
+#[test]
+fn maps_provider_statuses_centrally() {
+ assert_eq!(
+ map_gmail_error(http_error(StatusCode::UNAUTHORIZED, "auth", None)),
+ EmailApiError::AuthRequired
+ );
+ assert_eq!(
+ map_gmail_error(http_error(StatusCode::FORBIDDEN, "scope", None)),
+ EmailApiError::Forbidden
+ );
+ assert_eq!(
+ map_gmail_error(http_error(StatusCode::NOT_FOUND, "missing", None)),
+ EmailApiError::NotFound
+ );
+ assert_eq!(
+ map_gmail_error(http_error(StatusCode::CONFLICT, "conflict", None)),
+ EmailApiError::Conflict
+ );
+
+ let retry_after = Duration::from_secs(30);
+ assert_eq!(
+ map_gmail_error(http_error(
+ StatusCode::TOO_MANY_REQUESTS,
+ "quota",
+ Some(retry_after),
+ )),
+ EmailApiError::RateLimited {
+ retry_after: Some(retry_after),
+ origin: RateLimitOrigin::Provider,
+ }
+ );
+}
+
+#[test]
+fn quota_403s_are_rate_limited_and_plain_403s_stay_forbidden() {
+ assert_eq!(
+ map_gmail_error(http_error(
+ StatusCode::FORBIDDEN,
+ r#"{"error":{"errors":[{"reason":"userRateLimitExceeded"}]}}"#,
+ None,
+ )),
+ EmailApiError::RateLimited {
+ retry_after: None,
+ origin: RateLimitOrigin::Provider,
+ }
+ );
+
+ let retry_after = Duration::from_secs(12);
+ assert_eq!(
+ map_gmail_error(http_error(
+ StatusCode::FORBIDDEN,
+ r#"{"error":{"errors":[{"reason":"rateLimitExceeded"}]}}"#,
+ Some(retry_after),
+ )),
+ EmailApiError::RateLimited {
+ retry_after: Some(retry_after),
+ origin: RateLimitOrigin::Provider,
+ }
+ );
+
+ for reason in ["dailyLimitExceeded", "quotaExceeded"] {
+ assert_eq!(
+ map_gmail_error(http_error(
+ StatusCode::FORBIDDEN,
+ format!(r#"{{"error":{{"errors":[{{"reason":"{reason}"}}]}}}}"#),
+ None,
+ )),
+ EmailApiError::RateLimited {
+ retry_after: None,
+ origin: RateLimitOrigin::Provider,
+ },
+ "reason {reason} should map to RateLimited",
+ );
+ }
+
+ assert_eq!(
+ map_gmail_error(http_error(
+ StatusCode::FORBIDDEN,
+ "Request had insufficient authentication scopes.",
+ None,
+ )),
+ EmailApiError::Forbidden
+ );
+}
+
+#[test]
+fn maps_server_errors_as_transient_and_other_http_errors_as_permanent() {
+ assert!(matches!(
+ map_gmail_error(http_error(
+ StatusCode::SERVICE_UNAVAILABLE,
+ "try later",
+ None,
+ )),
+ EmailApiError::Transient { message } if message.contains("try later")
+ ));
+ assert!(matches!(
+ map_gmail_error(http_error(StatusCode::BAD_REQUEST, "invalid", None)),
+ EmailApiError::Permanent { message } if message.contains("invalid")
+ ));
+}
+
+#[test]
+fn maps_invalid_responses_as_permanent() {
+ assert!(matches!(
+ map_gmail_error(GmailApiHttpError::InvalidResponse(
+ "missing required field".to_string(),
+ )),
+ EmailApiError::Permanent { message } if message.contains("missing required field")
+ ));
+}
+
+#[test]
+fn history_not_found_is_an_outdated_cursor() {
+ assert_eq!(
+ map_history_error(http_error(StatusCode::NOT_FOUND, "stale history", None)),
+ EmailApiError::OutdatedCursor
+ );
+ assert_eq!(
+ map_history_error(http_error(StatusCode::FORBIDDEN, "scope", None)),
+ EmailApiError::Forbidden
+ );
+}
+
+#[test]
+fn expired_contacts_sync_token_is_an_outdated_cursor() {
+ assert_eq!(
+ map_contacts_error(http_error(
+ StatusCode::BAD_REQUEST,
+ r#"{"error":{"status":"FAILED_PRECONDITION","details":[{"reason":"EXPIRED_SYNC_TOKEN"}]}}"#,
+ None,
+ )),
+ EmailApiError::OutdatedCursor
+ );
+ assert!(matches!(
+ map_contacts_error(http_error(StatusCode::BAD_REQUEST, "invalid request", None)),
+ EmailApiError::Permanent { .. }
+ ));
+}
+
+#[test]
+fn watch_conflict_requires_gmails_status_and_body() {
+ assert_eq!(
+ map_watch_error(http_error(
+ StatusCode::BAD_REQUEST,
+ "Only one user push notification client allowed",
+ None,
+ )),
+ EmailApiError::Conflict
+ );
+ assert!(matches!(
+ map_watch_error(http_error(
+ StatusCode::BAD_REQUEST,
+ "another bad request",
+ None,
+ )),
+ EmailApiError::Permanent { .. }
+ ));
+ assert_eq!(
+ map_watch_error(http_error(StatusCode::CONFLICT, "ordinary conflict", None,)),
+ EmailApiError::Conflict
+ );
+}
+
+#[test]
+fn repository_can_be_composed_from_a_topic_and_cloned() {
+ let repository = GmailApiClientRepository::from_subscription_topic("projects/p/topics/mail");
+ let _clone = repository.clone();
+}
diff --git a/crates/email_api_client/src/outbound/gmail/test/fixtures/attachment.json b/crates/email_api_client/src/outbound/gmail/test/fixtures/attachment.json
new file mode 100644
index 0000000000..0fbb9077f2
--- /dev/null
+++ b/crates/email_api_client/src/outbound/gmail/test/fixtures/attachment.json
@@ -0,0 +1 @@
+{"size":5,"data":"SGVsbG8"}
diff --git a/crates/email_api_client/src/outbound/gmail/test/fixtures/contacts_page_1.json b/crates/email_api_client/src/outbound/gmail/test/fixtures/contacts_page_1.json
new file mode 100644
index 0000000000..dd75ac03e7
--- /dev/null
+++ b/crates/email_api_client/src/outbound/gmail/test/fixtures/contacts_page_1.json
@@ -0,0 +1 @@
+{"connections":[{"names":[{"displayName":"First Contact"}],"emailAddresses":[{"value":"[email protected]"}]}],"nextPageToken":"contacts-next"}
diff --git a/crates/email_api_client/src/outbound/gmail/test/fixtures/contacts_page_2.json b/crates/email_api_client/src/outbound/gmail/test/fixtures/contacts_page_2.json
new file mode 100644
index 0000000000..8e392c68d1
--- /dev/null
+++ b/crates/email_api_client/src/outbound/gmail/test/fixtures/contacts_page_2.json
@@ -0,0 +1 @@
+{"connections":[{"names":[{"displayName":"Second Contact"}],"emailAddresses":[{"value":"[email protected]"}],"photos":[{"url":"https://lh3.googleusercontent.test/second=s100","default":false}]}],"nextSyncToken":"contacts-sync-final"}
diff --git a/crates/email_api_client/src/outbound/gmail/test/fixtures/filters.json b/crates/email_api_client/src/outbound/gmail/test/fixtures/filters.json
new file mode 100644
index 0000000000..1e5668b57b
--- /dev/null
+++ b/crates/email_api_client/src/outbound/gmail/test/fixtures/filters.json
@@ -0,0 +1,19 @@
+{
+ "filter": [
+ {
+ "id": "blocked-1",
+ "criteria": { "from": "[email protected]" },
+ "action": { "addLabelIds": ["TRASH"] }
+ },
+ {
+ "id": "label-only",
+ "criteria": { "from": "[email protected]" },
+ "action": { "addLabelIds": ["Label_123"] }
+ },
+ {
+ "id": "trash-without-sender",
+ "criteria": { "subject": "discard" },
+ "action": { "addLabelIds": ["TRASH"] }
+ }
+ ]
+}
diff --git a/crates/email_api_client/src/outbound/gmail/test/fixtures/history_page_1.json b/crates/email_api_client/src/outbound/gmail/test/fixtures/history_page_1.json
new file mode 100644
index 0000000000..1dc9ded950
--- /dev/null
+++ b/crates/email_api_client/src/outbound/gmail/test/fixtures/history_page_1.json
@@ -0,0 +1,8 @@
+{
+ "history": [
+ {"id":"101","messagesAdded":[{"message":{"id":"added","threadId":"thread-1"}}]},
+ {"id":"101","messagesDeleted":[{"message":{"id":"deleted","threadId":"thread-2"}}]}
+ ],
+ "nextPageToken":"next-page",
+ "historyId":"101"
+}
diff --git a/crates/email_api_client/src/outbound/gmail/test/fixtures/history_page_2.json b/crates/email_api_client/src/outbound/gmail/test/fixtures/history_page_2.json
new file mode 100644
index 0000000000..ab2092be23
--- /dev/null
+++ b/crates/email_api_client/src/outbound/gmail/test/fixtures/history_page_2.json
@@ -0,0 +1,6 @@
+{
+ "history": [
+ {"id":"102","labelsAdded":[{"message":{"id":"labels","threadId":"thread-3"},"labelIds":["STARRED"]}]}
+ ],
+ "historyId":"102"
+}
diff --git a/crates/email_api_client/src/outbound/gmail/test/fixtures/labels.json b/crates/email_api_client/src/outbound/gmail/test/fixtures/labels.json
new file mode 100644
index 0000000000..0565185346
--- /dev/null
+++ b/crates/email_api_client/src/outbound/gmail/test/fixtures/labels.json
@@ -0,0 +1 @@
+{"labels":[{"id":"INBOX","name":"INBOX","type":"system"},{"id":"Label_1","name":"Projects","messageListVisibility":"show","labelListVisibility":"labelShow","type":"user"}]}
diff --git a/crates/email_api_client/src/outbound/gmail/test/fixtures/message_full.json b/crates/email_api_client/src/outbound/gmail/test/fixtures/message_full.json
new file mode 100644
index 0000000000..a2404447e9
--- /dev/null
+++ b/crates/email_api_client/src/outbound/gmail/test/fixtures/message_full.json
@@ -0,0 +1,10 @@
+{
+ "id":"message-1","threadId":"thread-1","labelIds":["INBOX","UNREAD"],
+ "snippet":"Hello","sizeEstimate":12,"historyId":"101","internalDate":"1700000000000",
+ "payload":{"partId":"","mimeType":"text/plain","filename":"","headers":[
+ {"name":"Message-ID","value":"<[email protected]>"},
+ {"name":"From","value":"Sender <[email protected]>"},
+ {"name":"To","value":"User <[email protected]>"},
+ {"name":"Subject","value":"Fixture message"}
+ ],"body":{"size":5,"data":"SGVsbG8="}}
+}
diff --git a/crates/email_api_client/src/outbound/gmail/test/fixtures/other_contacts.json b/crates/email_api_client/src/outbound/gmail/test/fixtures/other_contacts.json
new file mode 100644
index 0000000000..70da2e3213
--- /dev/null
+++ b/crates/email_api_client/src/outbound/gmail/test/fixtures/other_contacts.json
@@ -0,0 +1 @@
+{"otherContacts":[{"names":[{"displayName":"Other Contact"}],"emailAddresses":[{"value":"[email protected]"}]}],"nextSyncToken":"other-sync-final"}
diff --git a/crates/email_api_client/src/outbound/gmail/test/fixtures/person.json b/crates/email_api_client/src/outbound/gmail/test/fixtures/person.json
new file mode 100644
index 0000000000..305066faa5
--- /dev/null
+++ b/crates/email_api_client/src/outbound/gmail/test/fixtures/person.json
@@ -0,0 +1 @@
+{"names":[{"displayName":"Mailbox User"}],"emailAddresses":[{"value":"[email protected]"}],"photos":[{"url":"https://lh3.googleusercontent.test/photo=s100","default":false}]}
diff --git a/crates/email_api_client/src/outbound/gmail/test/fixtures/profile.json b/crates/email_api_client/src/outbound/gmail/test/fixtures/profile.json
new file mode 100644
index 0000000000..402296ae44
--- /dev/null
+++ b/crates/email_api_client/src/outbound/gmail/test/fixtures/profile.json
@@ -0,0 +1 @@
+{"emailAddress":"[email protected]","messagesTotal":100,"threadsTotal":42,"historyId":"100"}
diff --git a/crates/email_api_client/src/outbound/gmail/test/fixtures/sent_message.json b/crates/email_api_client/src/outbound/gmail/test/fixtures/sent_message.json
new file mode 100644
index 0000000000..a1983696ee
--- /dev/null
+++ b/crates/email_api_client/src/outbound/gmail/test/fixtures/sent_message.json
@@ -0,0 +1,5 @@
+{
+ "id": "gmail-message-123",
+ "threadId": "gmail-thread-456",
+ "labelIds": ["SENT"]
+}
diff --git a/crates/email_api_client/src/outbound/gmail/test/fixtures/stale_history_error.json b/crates/email_api_client/src/outbound/gmail/test/fixtures/stale_history_error.json
new file mode 100644
index 0000000000..ddd8e6af4c
--- /dev/null
+++ b/crates/email_api_client/src/outbound/gmail/test/fixtures/stale_history_error.json
@@ -0,0 +1 @@
+{"error":{"code":404,"message":"Requested historyId is too old"}}
diff --git a/crates/email_api_client/src/outbound/gmail/test/fixtures/thread_full.json b/crates/email_api_client/src/outbound/gmail/test/fixtures/thread_full.json
new file mode 100644
index 0000000000..400dcb4942
--- /dev/null
+++ b/crates/email_api_client/src/outbound/gmail/test/fixtures/thread_full.json
@@ -0,0 +1,6 @@
+{"id":"thread-1","messages":[
+ {
+ "id":"message-1","threadId":"thread-1","labelIds":["INBOX"],"snippet":"Hello","sizeEstimate":12,"historyId":"101","internalDate":"1700000000000",
+ "payload":{"mimeType":"text/plain","headers":[{"name":"Message-ID","value":"<[email protected]>"}],"body":{"size":5,"data":"SGVsbG8="}}
+ }
+]}
diff --git a/crates/email_api_client/src/outbound/gmail/test/fixtures/watch_conflict.json b/crates/email_api_client/src/outbound/gmail/test/fixtures/watch_conflict.json
new file mode 100644
index 0000000000..f48a8a5e7f
--- /dev/null
+++ b/crates/email_api_client/src/outbound/gmail/test/fixtures/watch_conflict.json
@@ -0,0 +1,6 @@
+{
+ "error": {
+ "code": 400,
+ "message": "Only one user push notification client allowed per developer project"
+ }
+}
diff --git a/crates/email_api_client/src/outbound/gmail/test/fixtures/watch_success.json b/crates/email_api_client/src/outbound/gmail/test/fixtures/watch_success.json
new file mode 100644
index 0000000000..b24848c8e0
--- /dev/null
+++ b/crates/email_api_client/src/outbound/gmail/test/fixtures/watch_success.json
@@ -0,0 +1,4 @@
+{
+ "historyId": "987654321",
+ "expiration": "1893456000000"
+}
diff --git a/crates/email_api_client/src/outbound/gmail/test/labels.rs b/crates/email_api_client/src/outbound/gmail/test/labels.rs
new file mode 100644
index 0000000000..41e2193fab
--- /dev/null
+++ b/crates/email_api_client/src/outbound/gmail/test/labels.rs
@@ -0,0 +1,64 @@
+use uuid::Uuid;
+use wiremock::matchers::{body_json, method, path};
+use wiremock::{Mock, ResponseTemplate};
+
+use super::repository;
+use crate::domain::models::AccessToken;
+use crate::domain::ports::MailboxLabelClient;
+
+#[tokio::test]
+async fn lists_and_creates_normalized_labels() {
+ let (server, repository) = repository().await;
+ Mock::given(method("GET"))
+ .and(path("/users/me/labels"))
+ .respond_with(
+ ResponseTemplate::new(200)
+ .set_body_raw(include_str!("fixtures/labels.json"), "application/json"),
+ )
+ .mount(&server)
+ .await;
+ Mock::given(method("POST"))
+ .and(path("/users/me/labels"))
+ .and(body_json(serde_json::json!({
+ "id": null,
+ "name": "Projects",
+ "messageListVisibility": "show",
+ "labelListVisibility": "labelShow",
+ "type": "user",
+ "color": null
+ })))
+ .respond_with(ResponseTemplate::new(200).set_body_json(serde_json::json!({
+ "id": "Label_1", "name": "Projects", "type": "user"
+ })))
+ .mount(&server)
+ .await;
+
+ let link_id = Uuid::now_v7();
+ let labels = repository
+ .list_labels(&AccessToken::new("token"), link_id)
+ .await
+ .unwrap();
+ assert_eq!(labels.len(), 2);
+ assert!(labels.iter().all(|label| label.link_id == link_id));
+
+ let created = repository
+ .create_label(&AccessToken::new("token"), link_id, "Projects")
+ .await
+ .unwrap();
+ assert_eq!(created.provider_label_id, "Label_1");
+}
+
+#[tokio::test]
+async fn deletion_is_idempotent_when_a_label_races_deletion() {
+ let (server, repository) = repository().await;
+ Mock::given(method("DELETE"))
+ .and(path("/users/me/labels/deleted"))
+ .respond_with(ResponseTemplate::new(404))
+ .mount(&server)
+ .await;
+
+ repository
+ .delete_label(&AccessToken::new("token"), "deleted")
+ .await
+ .unwrap();
+}
diff --git a/crates/email_api_client/src/outbound/gmail/test/messages.rs b/crates/email_api_client/src/outbound/gmail/test/messages.rs
new file mode 100644
index 0000000000..81cd2454b0
--- /dev/null
+++ b/crates/email_api_client/src/outbound/gmail/test/messages.rs
@@ -0,0 +1,221 @@
+use uuid::Uuid;
+use wiremock::matchers::{body_json, method, path, query_param};
+use wiremock::{Mock, ResponseTemplate};
+
+use super::repository;
+use crate::domain::models::{AccessToken, EmailApiError};
+use crate::domain::ports::{MailboxCalendarClient, MailboxMessageClient};
+
+#[tokio::test]
+async fn normalizes_messages_and_preserves_deletion_races() {
+ let (server, repository) = repository().await;
+ Mock::given(method("GET"))
+ .and(path("/users/me/messages/message-1"))
+ .respond_with(ResponseTemplate::new(200).set_body_raw(
+ include_str!("fixtures/message_full.json"),
+ "application/json",
+ ))
+ .mount(&server)
+ .await;
+ Mock::given(method("GET"))
+ .and(path("/users/me/messages/deleted"))
+ .respond_with(ResponseTemplate::new(404))
+ .mount(&server)
+ .await;
+
+ let link_id = Uuid::now_v7();
+ let fetched = repository
+ .get_message(&AccessToken::new("token"), link_id, "message-1")
+ .await
+ .unwrap()
+ .unwrap();
+ assert_eq!(fetched.message.link_id, link_id);
+ assert_eq!(fetched.message.subject.as_deref(), Some("Fixture message"));
+ assert!(!fetched.message.is_read);
+ assert!(fetched.calendar_parts.is_empty());
+ assert!(
+ repository
+ .get_message(&AccessToken::new("token"), link_id, "deleted")
+ .await
+ .unwrap()
+ .is_none()
+ );
+}
+
+fn calendar_message_body() -> serde_json::Value {
+ serde_json::json!({
+ "id": "calendar",
+ "threadId": "thread",
+ "historyId": "1",
+ "internalDate": "1",
+ "labelIds": [],
+ "snippet": "",
+ "sizeEstimate": 0,
+ "payload": {
+ "partId": "",
+ "mimeType": "multipart/mixed",
+ "filename": "",
+ "headers": [],
+ "parts": [
+ {
+ "partId": "inline",
+ "mimeType": "text/calendar; method=REQUEST",
+ "filename": "",
+ "headers": [],
+ "body": {"size": 5, "data": "aGVsbG8"}
+ },
+ {
+ "partId": "attachment",
+ "mimeType": "application/octet-stream",
+ "filename": "invite.ics",
+ "headers": [],
+ "body": {"size": 10, "attachmentId": "attachment-id"}
+ }
+ ]
+ }
+ })
+}
+
+fn assert_calendar_parts(parts: &[crate::domain::models::CalendarPart]) {
+ assert_eq!(parts.len(), 2);
+ assert!(
+ parts
+ .iter()
+ .any(|part| part.inline_data.as_deref() == Some(b"hello".as_slice()))
+ );
+ assert!(
+ parts
+ .iter()
+ .any(|part| part.provider_attachment_id.as_deref() == Some("attachment-id"))
+ );
+}
+
+#[tokio::test]
+async fn discovers_inline_and_attachment_calendar_parts() {
+ let (server, repository) = repository().await;
+ Mock::given(method("GET"))
+ .and(path("/users/me/messages/calendar"))
+ .respond_with(ResponseTemplate::new(200).set_body_json(calendar_message_body()))
+ .mount(&server)
+ .await;
+
+ let parts = repository
+ .get_calendar_parts(&AccessToken::new("token"), "calendar")
+ .await
+ .unwrap();
+ assert_calendar_parts(&parts);
+}
+
+#[tokio::test]
+async fn get_message_surfaces_calendar_parts_from_a_single_wire_fetch() {
+ let (server, repository) = repository().await;
+ Mock::given(method("GET"))
+ .and(path("/users/me/messages/calendar"))
+ .respond_with(ResponseTemplate::new(200).set_body_json(calendar_message_body()))
+ .expect(1)
+ .mount(&server)
+ .await;
+
+ let fetched = repository
+ .get_message(&AccessToken::new("token"), Uuid::now_v7(), "calendar")
+ .await
+ .unwrap()
+ .unwrap();
+
+ assert_calendar_parts(&fetched.calendar_parts);
+ // Dropping the server verifies the .expect(1) call count: the calendar
+ // parts came from the same messages.get as the normalized message.
+}
+
+#[tokio::test]
+async fn normalizes_full_threads() {
+ let (server, repository) = repository().await;
+ Mock::given(method("GET"))
+ .and(path("/users/me/threads/thread-1"))
+ .and(query_param("format", "full"))
+ .respond_with(ResponseTemplate::new(200).set_body_raw(
+ include_str!("fixtures/thread_full.json"),
+ "application/json",
+ ))
+ .mount(&server)
+ .await;
+
+ let messages = repository
+ .get_thread(&AccessToken::new("token"), Uuid::now_v7(), "thread-1")
+ .await
+ .unwrap();
+ assert_eq!(messages.len(), 1);
+ assert_eq!(messages[0].provider_thread_id.as_deref(), Some("thread-1"));
+}
+
+#[tokio::test]
+async fn lists_threads_and_messages_with_provider_pagination() {
+ let (server, repository) = repository().await;
+ Mock::given(method("GET"))
+ .and(path("/users/me/threads"))
+ .and(query_param("pageToken", "next"))
+ .and(query_param("labelIds", "INBOX"))
+ .respond_with(ResponseTemplate::new(200).set_body_json(serde_json::json!({
+ "threads": [{"id": "thread-1"}],
+ "nextPageToken": "after"
+ })))
+ .mount(&server)
+ .await;
+ Mock::given(method("GET"))
+ .and(path("/users/me/messages"))
+ .and(query_param("labelIds", "SENT"))
+ .respond_with(ResponseTemplate::new(200).set_body_json(serde_json::json!({
+ "messages": [{"id": "message-1"}]
+ })))
+ .mount(&server)
+ .await;
+
+ let threads = repository
+ .list_threads(&AccessToken::new("token"), 10, Some("next"), &["INBOX"])
+ .await
+ .unwrap();
+ assert_eq!(threads.threads[0].provider_id, "thread-1");
+ assert_eq!(threads.next_page_token.as_deref(), Some("after"));
+ assert_eq!(
+ repository
+ .list_messages(&AccessToken::new("token"), 10, &["SENT"])
+ .await
+ .unwrap(),
+ ["message-1"]
+ );
+}
+
+#[tokio::test]
+async fn modifies_labels_and_maps_conversion_errors_as_permanent() {
+ let (server, repository) = repository().await;
+ Mock::given(method("POST"))
+ .and(path("/users/me/messages/message-1/modify"))
+ .and(body_json(serde_json::json!({
+ "addLabelIds": ["STARRED"],
+ "removeLabelIds": ["UNREAD"]
+ })))
+ .respond_with(ResponseTemplate::new(200))
+ .mount(&server)
+ .await;
+ repository
+ .modify_message_labels(
+ &AccessToken::new("token"),
+ "message-1",
+ &["STARRED".to_string()],
+ &["UNREAD".to_string()],
+ )
+ .await
+ .unwrap();
+
+ Mock::given(method("GET"))
+ .and(path("/users/me/messages/malformed"))
+ .respond_with(ResponseTemplate::new(200).set_body_json(serde_json::json!({})))
+ .mount(&server)
+ .await;
+ assert!(matches!(
+ repository
+ .get_message(&AccessToken::new("token"), Uuid::now_v7(), "malformed")
+ .await,
+ Err(EmailApiError::Permanent { .. })
+ ));
+}
diff --git a/crates/email_api_client/src/outbound/gmail/test/mod.rs b/crates/email_api_client/src/outbound/gmail/test/mod.rs
new file mode 100644
index 0000000000..bd164a932d
--- /dev/null
+++ b/crates/email_api_client/src/outbound/gmail/test/mod.rs
@@ -0,0 +1,27 @@
+mod attachments;
+mod blocklist;
+mod contacts;
+mod error;
+mod labels;
+mod messages;
+mod send;
+mod subscription;
+mod sync;
+
+use gmail_client::GmailClient;
+use wiremock::MockServer;
+
+use super::GmailApiClientRepository;
+
+async fn repository() -> (MockServer, GmailApiClientRepository) {
+ let server = MockServer::start().await;
+ let url = server.uri();
+ let client = GmailClient::new_with_urls(
+ "topic".to_string(),
+ url.clone(),
+ url.clone(),
+ format!("{url}/certs"),
+ "audience".to_string(),
+ );
+ (server, GmailApiClientRepository::new(client))
+}
diff --git a/crates/email_api_client/src/outbound/gmail/test/send.rs b/crates/email_api_client/src/outbound/gmail/test/send.rs
new file mode 100644
index 0000000000..6e8368e96c
--- /dev/null
+++ b/crates/email_api_client/src/outbound/gmail/test/send.rs
@@ -0,0 +1,93 @@
+use base64::Engine;
+use base64::engine::general_purpose::URL_SAFE_NO_PAD;
+use gmail_client::GmailClient;
+use models_email::email::service::address::ContactInfo;
+use models_email::email::service::message::MessageToSend;
+use serde_json::Value;
+use uuid::Uuid;
+use wiremock::matchers::{header, method, path};
+use wiremock::{Mock, MockServer, ResponseTemplate};
+
+use crate::domain::models::{AccessToken, SendRequest};
+use crate::domain::ports::MailboxSendClient;
+use crate::outbound::gmail::GmailApiClientRepository;
+
+fn repository(server: &MockServer) -> GmailApiClientRepository {
+ GmailApiClientRepository::new(GmailClient::new_with_urls(
+ "projects/p/topics/mail".to_string(),
+ server.uri(),
+ server.uri(),
+ server.uri(),
+ "audience".to_string(),
+ ))
+}
+
+#[tokio::test]
+async fn builds_posts_and_returns_provider_ids() {
+ let server = MockServer::start().await;
+ Mock::given(method("POST"))
+ .and(path("/users/me/messages/send"))
+ .and(header("authorization", "Bearer access-token"))
+ .respond_with(ResponseTemplate::new(200).set_body_raw(
+ include_str!("fixtures/sent_message.json"),
+ "application/json",
+ ))
+ .mount(&server)
+ .await;
+
+ let request = SendRequest {
+ message: MessageToSend {
+ db_id: None,
+ provider_id: None,
+ replying_to_id: None,
+ provider_thread_id: None,
+ thread_db_id: None,
+ link_id: Uuid::nil(),
+ subject: "Adapter subject".to_string(),
+ to: Some(vec![ContactInfo {
+ email: "[email protected]".to_string(),
+ name: Some("Recipient".to_string()),
+ photo_url: None,
+ }]),
+ cc: None,
+ bcc: None,
+ body_text: Some("Adapter body".to_string()),
+ body_html: None,
+ body_macro: None,
+ attachments: None,
+ headers_json: None,
+ send_time: None,
+ },
+ from: ContactInfo {
+ email: "[email protected]".to_string(),
+ name: Some("Sender".to_string()),
+ photo_url: None,
+ },
+ parent_message_id: Some("[email protected]".to_string()),
+ references: Some(vec!["[email protected]".to_string()]),
+ };
+
+ let sent = repository(&server)
+ .send_message(
+ &AccessToken::new("access-token"),
+ &request,
+ Some("thread-1"),
+ )
+ .await
+ .unwrap();
+
+ assert_eq!(sent.provider_message_id, "gmail-message-123");
+ assert_eq!(sent.provider_thread_id, "gmail-thread-456");
+
+ let requests = server.received_requests().await.unwrap();
+ let payload: Value = serde_json::from_slice(&requests[0].body).unwrap();
+ assert_eq!(payload["threadId"], "thread-1");
+ let mime = URL_SAFE_NO_PAD
+ .decode(payload["raw"].as_str().unwrap())
+ .unwrap();
+ let mime = String::from_utf8(mime).unwrap();
+ assert!(mime.contains("Subject: Adapter subject"));
+ assert!(mime.contains("Adapter body"));
+ assert!(mime.contains("In-Reply-To:"));
+ assert!(mime.contains("[email protected]"));
+}
diff --git a/crates/email_api_client/src/outbound/gmail/test/subscription.rs b/crates/email_api_client/src/outbound/gmail/test/subscription.rs
new file mode 100644
index 0000000000..bce329e095
--- /dev/null
+++ b/crates/email_api_client/src/outbound/gmail/test/subscription.rs
@@ -0,0 +1,128 @@
+use std::sync::Arc;
+use std::sync::atomic::{AtomicUsize, Ordering};
+
+use chrono::{TimeZone, Utc};
+use gmail_client::GmailClient;
+use wiremock::matchers::{method, path};
+use wiremock::{Mock, MockServer, Request, Respond, ResponseTemplate};
+
+use crate::domain::models::{AccessToken, EmailApiError, SyncCursor};
+use crate::domain::ports::MailboxSubscriptionClient;
+use crate::outbound::gmail::GmailApiClientRepository;
+
+fn repository(server: &MockServer) -> GmailApiClientRepository {
+ GmailApiClientRepository::new(GmailClient::new_with_urls(
+ "projects/p/topics/mail".to_string(),
+ server.uri(),
+ server.uri(),
+ server.uri(),
+ "audience".to_string(),
+ ))
+}
+
+#[derive(Clone)]
+struct WatchSequence {
+ calls: Arc<AtomicUsize>,
+ retry_status: u16,
+}
+
+impl Respond for WatchSequence {
+ fn respond(&self, _: &Request) -> ResponseTemplate {
+ if self.calls.fetch_add(1, Ordering::SeqCst) == 0 {
+ return ResponseTemplate::new(400).set_body_raw(
+ include_str!("fixtures/watch_conflict.json"),
+ "application/json",
+ );
+ }
+
+ if self.retry_status == 200 {
+ ResponseTemplate::new(200).set_body_raw(
+ include_str!("fixtures/watch_success.json"),
+ "application/json",
+ )
+ } else {
+ ResponseTemplate::new(self.retry_status)
+ }
+ }
+}
+
+#[tokio::test]
+async fn maps_successful_watch_to_subscription() {
+ let server = MockServer::start().await;
+ Mock::given(method("POST"))
+ .and(path("/users/me/watch"))
+ .respond_with(ResponseTemplate::new(200).set_body_raw(
+ include_str!("fixtures/watch_success.json"),
+ "application/json",
+ ))
+ .mount(&server)
+ .await;
+
+ let subscription = repository(&server)
+ .subscribe(&AccessToken::new("token"))
+ .await
+ .unwrap();
+
+ assert_eq!(subscription.cursor, SyncCursor::gmail("987654321"));
+ assert_eq!(
+ subscription.expires_at,
+ Utc.timestamp_millis_opt(1_893_456_000_000)
+ .single()
+ .unwrap()
+ );
+}
+
+#[tokio::test]
+async fn conflict_stops_and_retries_exactly_once() {
+ let server = MockServer::start().await;
+ let calls = Arc::new(AtomicUsize::new(0));
+ Mock::given(method("POST"))
+ .and(path("/users/me/watch"))
+ .respond_with(WatchSequence {
+ calls: calls.clone(),
+ retry_status: 200,
+ })
+ .mount(&server)
+ .await;
+ Mock::given(method("POST"))
+ .and(path("/users/me/stop"))
+ .respond_with(ResponseTemplate::new(204))
+ .expect(1)
+ .mount(&server)
+ .await;
+
+ repository(&server)
+ .subscribe(&AccessToken::new("token"))
+ .await
+ .unwrap();
+
+ assert_eq!(calls.load(Ordering::SeqCst), 2);
+}
+
+#[tokio::test]
+async fn retry_failure_is_returned_without_another_recovery_attempt() {
+ let server = MockServer::start().await;
+ let calls = Arc::new(AtomicUsize::new(0));
+ Mock::given(method("POST"))
+ .and(path("/users/me/watch"))
+ .respond_with(WatchSequence {
+ calls: calls.clone(),
+ retry_status: 503,
+ })
+ .mount(&server)
+ .await;
+ Mock::given(method("POST"))
+ .and(path("/users/me/stop"))
+ .respond_with(ResponseTemplate::new(204))
+ .expect(1)
+ .mount(&server)
+ .await;
+
+ let error = repository(&server)
+ .subscribe(&AccessToken::new("token"))
+ .await
+ .unwrap_err();
+
+ assert!(matches!(error, EmailApiError::Transient { .. }));
+ assert_eq!(calls.load(Ordering::SeqCst), 2);
+}
diff --git a/crates/email_api_client/src/outbound/gmail/test/sync.rs b/crates/email_api_client/src/outbound/gmail/test/sync.rs
new file mode 100644
index 0000000000..e767e3b6c7
--- /dev/null
+++ b/crates/email_api_client/src/outbound/gmail/test/sync.rs
@@ -0,0 +1,81 @@
+use wiremock::matchers::{method, path, query_param};
+use wiremock::{Mock, ResponseTemplate};
+
+use super::repository;
+use crate::domain::models::{AccessToken, EmailApiError, SyncCursor};
+use crate::domain::ports::MailboxSyncClient;
+
+#[tokio::test]
+async fn reads_profile_thread_count() {
+ let (server, repository) = repository().await;
+ Mock::given(method("GET"))
+ .and(path("/users/me/profile"))
+ .respond_with(
+ ResponseTemplate::new(200)
+ .set_body_raw(include_str!("fixtures/profile.json"), "application/json"),
+ )
+ .mount(&server)
+ .await;
+
+ assert_eq!(
+ repository
+ .get_thread_count(&AccessToken::new("token"))
+ .await
+ .unwrap(),
+ 42
+ );
+}
+
+#[tokio::test]
+async fn paginates_and_partitions_history() {
+ let (server, repository) = repository().await;
+ Mock::given(method("GET"))
+ .and(path("/users/me/history"))
+ .and(query_param("startHistoryId", "100"))
+ .respond_with(ResponseTemplate::new(200).set_body_raw(
+ include_str!("fixtures/history_page_1.json"),
+ "application/json",
+ ))
+ .up_to_n_times(1)
+ .mount(&server)
+ .await;
+ Mock::given(method("GET"))
+ .and(path("/users/me/history"))
+ .and(query_param("pageToken", "next-page"))
+ .respond_with(ResponseTemplate::new(200).set_body_raw(
+ include_str!("fixtures/history_page_2.json"),
+ "application/json",
+ ))
+ .mount(&server)
+ .await;
+
+ let batch = repository
+ .list_changes(&AccessToken::new("token"), &SyncCursor::gmail("100"))
+ .await
+ .unwrap();
+
+ assert_eq!(batch.next_cursor.as_str(), "102");
+ assert!(batch.changes.message_ids_to_upsert.contains("added"));
+ assert!(batch.changes.message_ids_to_delete.contains("deleted"));
+ assert!(batch.changes.labels_to_update.contains("labels"));
+}
+
+#[tokio::test]
+async fn only_history_not_found_is_an_outdated_cursor() {
+ let (server, repository) = repository().await;
+ Mock::given(method("GET"))
+ .and(path("/users/me/history"))
+ .respond_with(ResponseTemplate::new(404).set_body_raw(
+ include_str!("fixtures/stale_history_error.json"),
+ "application/json",
+ ))
+ .mount(&server)
+ .await;
+
+ assert_eq!(
+ repository
+ .list_changes(&AccessToken::new("token"), &SyncCursor::gmail("stale"))
+ .await,
+ Err(EmailApiError::OutdatedCursor)
+ );
+}
diff --git a/crates/email_api_client/src/outbound/mod.rs b/crates/email_api_client/src/outbound/mod.rs
new file mode 100644
index 0000000000..138196246e
--- /dev/null
+++ b/crates/email_api_client/src/outbound/mod.rs
@@ -0,0 +1,4 @@
+//! Provider-specific outbound email API adapters.
+
+/// Gmail outbound adapter implementation.
+pub mod gmail;
diff --git a/crates/email_db_client/src/backfill/job/insert.rs b/crates/email_db_client/src/backfill/job/insert.rs
index aa5f9e1c9a..54424e508a 100644
--- a/crates/email_db_client/src/backfill/job/insert.rs
+++ b/crates/email_db_client/src/backfill/job/insert.rs
@@ -6,20 +6,24 @@ use sqlx::types::Uuid;
/// Creates an `Init` backfill job for a link. Returns `None` when an active
/// (`Init`/`InProgress`) job already exists for the link — the `uq_active_backfill_job_per_link`
/// partial unique index makes this atomic, so concurrent callers don't create duplicates.
+///
+/// `is_recovery` marks stale-cursor recovery jobs: they skip the priority pass
+/// and refresh existing threads instead of skipping them.
#[tracing::instrument(skip(pool), err)]
pub async fn create_backfill_job(
pool: &PgPool,
link_id: Uuid,
fusionauth_user_id: &str,
num_threads: Option<i32>,
+ is_recovery: bool,
) -> anyhow::Result<Option<service::backfill::BackfillJob>> {
let id = macro_uuid::generate_uuid_v7();
let record = sqlx::query_as!(
db::backfill::BackfillJob,
r#"
- INSERT INTO email_backfill_jobs (id, link_id, fusionauth_user_id, threads_requested_limit, status)
- VALUES ($1, $2, $3, $4, 'Init')
+ INSERT INTO email_backfill_jobs (id, link_id, fusionauth_user_id, threads_requested_limit, status, is_recovery)
+ VALUES ($1, $2, $3, $4, 'Init', $5)
ON CONFLICT (link_id) WHERE status IN ('Init', 'InProgress') DO NOTHING
RETURNING
id,
@@ -35,7 +39,8 @@ pub async fn create_backfill_job(
id,
link_id,
fusionauth_user_id,
- num_threads
+ num_threads,
+ is_recovery
)
.fetch_optional(pool)
.await?;
diff --git a/crates/email_db_client/src/backfill/job/insert/test.rs b/crates/email_db_client/src/backfill/job/insert/test.rs
index 1a89ff420b..351e0f6d73 100644
--- a/crates/email_db_client/src/backfill/job/insert/test.rs
+++ b/crates/email_db_client/src/backfill/job/insert/test.rs
@@ -22,11 +22,11 @@ async fn create_backfill_job_dedupes_active_job(pool: Pool<Postgres>) -> anyhow:
let link_id = Uuid::new_v4();
insert_link(&pool, link_id).await;
- let first = create_backfill_job(&pool, link_id, "fusion-x", None).await?;
+ let first = create_backfill_job(&pool, link_id, "fusion-x", None, false).await?;
assert!(first.is_some(), "first create should insert a job");
// A second create while one is active no-ops (partial unique index) and returns None.
- let second = create_backfill_job(&pool, link_id, "fusion-x", None).await?;
+ let second = create_backfill_job(&pool, link_id, "fusion-x", None, false).await?;
assert!(
second.is_none(),
"second create should no-op while a job is active"
diff --git a/crates/email_db_client/src/messages/get.rs b/crates/email_db_client/src/messages/get.rs
index 880efc2b10..9dc226983f 100644
--- a/crates/email_db_client/src/messages/get.rs
+++ b/crates/email_db_client/src/messages/get.rs
@@ -95,22 +95,44 @@ pub async fn get_message_and_thread_id_by_provider_id(
/// Returns `true` if a message already exists for this (provider_id, link_id), else `false`.
#[tracing::instrument(skip(pool), err)]
#[allow(clippy::disallowed_methods, reason = "legacy code. fix later")]
+/// Returns which of `provider_message_ids` already exist for the link.
+#[tracing::instrument(skip(pool, provider_message_ids), err)]
+pub async fn filter_existing_provider_message_ids(
+ pool: &PgPool,
+ link_id: Uuid,
+ provider_message_ids: &[String],
+) -> anyhow::Result<std::collections::HashSet<String>> {
+ let rows = sqlx::query_scalar!(
+ r#"
+ SELECT provider_id AS "provider_id!"
+ FROM email_messages
+ WHERE link_id = $1 AND provider_id = ANY($2)
+ "#,
+ link_id,
+ provider_message_ids,
+ )
+ .fetch_all(pool)
+ .await?;
+
+ Ok(rows.into_iter().collect())
+}
+
pub async fn message_exists_by_provider_id(
pool: &PgPool,
provider_id: &str,
link_id: Uuid,
) -> anyhow::Result<bool> {
- let exists: bool = sqlx::query_scalar(
+ let exists = sqlx::query_scalar!(
r#"
SELECT EXISTS(
SELECT 1
FROM email_messages
WHERE provider_id = $1 AND link_id = $2
- )
+ ) AS "exists!"
"#,
+ provider_id,
+ link_id,
)
- .bind(provider_id)
- .bind(link_id)
.fetch_one(pool)
.await?;
diff --git a/crates/email_db_client/src/messages/test.rs b/crates/email_db_client/src/messages/test.rs
index 8af79539d5..9e6f6e80cc 100644
--- a/crates/email_db_client/src/messages/test.rs
+++ b/crates/email_db_client/src/messages/test.rs
@@ -1,4 +1,4 @@
-use crate::messages::get::draft_exists_with_id;
+use crate::messages::get::{draft_exists_with_id, filter_existing_provider_message_ids};
use crate::messages::scheduled::get::get_scheduled_db_messages_by_link_id;
use macro_db_migrator::MACRO_DB_MIGRATIONS;
use sqlx::types::Uuid;
@@ -463,3 +463,32 @@ async fn update_message_read_status_ignores_wrong_link(pool: Pool<Postgres>) ->
Ok(())
}
+
+#[sqlx::test(
+ migrator = "MACRO_DB_MIGRATIONS",
+ fixtures(path = "../../fixtures", scripts("draft_exists_with_id"))
+)]
+async fn filter_existing_provider_message_ids_partitions_known_and_missing(
+ pool: Pool<Postgres>,
+) -> anyhow::Result<()> {
+ let link_id = Uuid::parse_str("00000000-0000-0000-0000-000000000e01")?;
+ let other_link_id = Uuid::parse_str("00000000-0000-0000-0000-000000000e02")?;
+
+ let requested = vec![
+ "provider-msg-e501".to_string(),
+ "provider-msg-e502".to_string(),
+ "provider-msg-missing".to_string(),
+ ];
+
+ let existing = filter_existing_provider_message_ids(&pool, link_id, &requested).await?;
+ assert!(existing.contains("provider-msg-e501"));
+ assert!(existing.contains("provider-msg-e502"));
+ assert!(!existing.contains("provider-msg-missing"));
+ assert_eq!(existing.len(), 2);
+
+ // Messages belong to the first link only.
+ let cross_link = filter_existing_provider_message_ids(&pool, other_link_id, &requested).await?;
+ assert!(cross_link.is_empty());
+
+ Ok(())
+}
diff --git a/crates/gmail_client/Cargo.toml b/crates/gmail_client/Cargo.toml
index ae348f7bb3..5a839e4183 100644
--- a/crates/gmail_client/Cargo.toml
+++ b/crates/gmail_client/Cargo.toml
@@ -4,22 +4,18 @@ name = "gmail_client"
publish = false
version = "0.1.0"
-[features]
-gmail_test = []
-
[dependencies]
-anyhow = { workspace = true }
base64 = { workspace = true }
-chrono = { workspace = true }
+httpdate = { workspace = true }
jsonwebtoken = { workspace = true }
-mail-builder = "0.4.3"
-mockall = { workspace = true }
models_email = { path = "../models_email" }
regex = { workspace = true }
-reqwest = { workspace = true, features = ["stream"] }
+reqwest = { workspace = true }
serde = { workspace = true }
-serde_json = { workspace = true }
-tokio = { workspace = true }
tracing = { workspace = true }
-uuid = { workspace = true }
workspace-hack = { version = "0.1", path = "../workspace-hack" }
+
+[dev-dependencies]
+serde_json = { workspace = true }
+tokio = { workspace = true }
+wiremock = { workspace = true }
diff --git a/crates/gmail_client/src/attachments.rs b/crates/gmail_client/src/attachments.rs
index 954ff6a40a..cf4ee33c44 100644
--- a/crates/gmail_client/src/attachments.rs
+++ b/crates/gmail_client/src/attachments.rs
@@ -1,53 +1,48 @@
-use crate::GmailClient;
-use anyhow::{Context, anyhow};
use base64::Engine;
-use base64::engine::general_purpose::URL_SAFE;
+use base64::engine::general_purpose::{URL_SAFE, URL_SAFE_NO_PAD};
use models_email::gmail::AttachmentGetResponse;
+use crate::error::{decode_json_response, unsuccessful_response};
+use crate::{GmailApiHttpError, GmailClient};
+
#[tracing::instrument(skip(client, access_token), err)]
-pub async fn get_attachment_data(
+pub(crate) async fn get_attachment_data(
client: &GmailClient,
access_token: &str,
message_id: &str,
attachment_id: &str,
-) -> anyhow::Result<Vec<u8>> {
- let url = format!(
- "{}/users/me/messages/{}/attachments/{}",
- client.base_url, message_id, attachment_id
- );
-
- let http_client = client.inner.clone();
-
- let response = http_client
- .get(&url)
+) -> Result<Vec<u8>, GmailApiHttpError> {
+ let response = client
+ .inner
+ .get(format!(
+ "{}/users/me/messages/{message_id}/attachments/{attachment_id}",
+ client.base_url
+ ))
.bearer_auth(access_token)
.send()
.await
- .context("Failed to send request to Gmail API (get attachment)")?;
+ .map_err(GmailApiHttpError::transport)?;
- let status = response.status();
- let body_text = response
- .text()
- .await
- .context("Failed to get response body")?;
- if !status.is_success() {
- anyhow::bail!(
- "Gmail API returned an error status: {} (get attachment): {}",
- status,
- body_text
- );
+ if !response.status().is_success() {
+ return Err(unsuccessful_response(response).await);
}
- let attachment_response: AttachmentGetResponse = serde_json::from_str(&body_text)
- .context("Failed to parse JSON response from Gmail API (get attachment)")?;
-
- let base64_data = attachment_response
- .data
- .ok_or_else(|| anyhow!("Gmail API response for attachment did not contain data field"))?;
-
- let decoded_bytes = URL_SAFE
- .decode(base64_data)
- .map_err(|e| anyhow!("Failed to decode base64 body data: {}", e))?;
-
- Ok(decoded_bytes)
+ let attachment: AttachmentGetResponse = decode_json_response(response).await?;
+ let data = attachment.data.ok_or_else(|| {
+ GmailApiHttpError::InvalidResponse(
+ "attachment response did not contain a data field".to_string(),
+ )
+ })?;
+
+ URL_SAFE
+ .decode(&data)
+ .or_else(|_| URL_SAFE_NO_PAD.decode(&data))
+ .map_err(|error| {
+ GmailApiHttpError::InvalidResponse(format!(
+ "attachment data was not valid base64url: {error}"
+ ))
+ })
}
+
+#[cfg(test)]
+mod test;
diff --git a/crates/gmail_client/src/attachments/test.rs b/crates/gmail_client/src/attachments/test.rs
new file mode 100644
index 0000000000..699012eb25
--- /dev/null
+++ b/crates/gmail_client/src/attachments/test.rs
@@ -0,0 +1,55 @@
+use wiremock::matchers::{method, path};
+use wiremock::{Mock, MockServer, ResponseTemplate};
+
+use super::*;
+
+fn client(server: &MockServer) -> GmailClient {
+ GmailClient::new_with_urls(
+ String::new(),
+ server.uri(),
+ server.uri(),
+ server.uri(),
+ String::new(),
+ )
+}
+
+#[tokio::test]
+async fn attachment_decodes_unpadded_base64url_data() {
+ let server = MockServer::start().await;
+ Mock::given(method("GET"))
+ .and(path(
+ "/users/me/messages/message-1/attachments/attachment-1",
+ ))
+ .respond_with(ResponseTemplate::new(200).set_body_json(serde_json::json!({
+ "size": 2,
+ "data": "-_8"
+ })))
+ .mount(&server)
+ .await;
+
+ let data = get_attachment_data(&client(&server), "token", "message-1", "attachment-1")
+ .await
+ .expect("attachment should decode");
+
+ assert_eq!(data, [251, 255]);
+}
+
+#[tokio::test]
+async fn attachment_without_data_is_an_invalid_response() {
+ let server = MockServer::start().await;
+ Mock::given(method("GET"))
+ .and(path(
+ "/users/me/messages/message-1/attachments/attachment-1",
+ ))
+ .respond_with(ResponseTemplate::new(200).set_body_json(serde_json::json!({
+ "size": 0
+ })))
+ .mount(&server)
+ .await;
+
+ let error = get_attachment_data(&client(&server), "token", "message-1", "attachment-1")
+ .await
+ .expect_err("missing data should fail");
+
+ assert!(matches!(error, GmailApiHttpError::InvalidResponse(_)));
+}
diff --git a/crates/gmail_client/src/auth.rs b/crates/gmail_client/src/auth.rs
index 35ef8ca127..50fc777b2f 100644
--- a/crates/gmail_client/src/auth.rs
+++ b/crates/gmail_client/src/auth.rs
@@ -1,59 +1,59 @@
-use crate::GmailClient;
-use anyhow::Context;
+use std::collections::HashMap;
+
use jsonwebtoken::{Algorithm, DecodingKey, Validation, decode};
use models_email::gmail::inbox_sync::{
GoogleJwtClaims, GooglePublicKeys, JwksResponse, JwtVerificationError, KeyMap,
};
-use std::collections::HashMap;
+
+use crate::error::{decode_json_response, unsuccessful_response};
+use crate::{GmailApiHttpError, GmailClient};
pub(crate) async fn fetch_google_public_keys(
client: &GmailClient,
-) -> anyhow::Result<GooglePublicKeys> {
+) -> Result<GooglePublicKeys, GmailApiHttpError> {
let response = client
.inner
.get(&client.certs_url)
.send()
.await
- .context("Failed to send request to Google certificates endpoint")?;
+ .map_err(GmailApiHttpError::transport)?;
- let response = response
- .error_for_status()
- .context("Google certificates endpoint returned an error status")?;
+ if !response.status().is_success() {
+ return Err(unsuccessful_response(response).await);
+ }
- // Extract the Cache-Control header and parse max-age
let max_age_seconds = response
.headers()
- .get("Cache-Control")
+ .get(reqwest::header::CACHE_CONTROL)
.and_then(|value| value.to_str().ok())
- .and_then(|cc| {
- cc.split(',')
- .map(|s| s.trim())
- .find(|s| s.starts_with("max-age="))
- .and_then(|max_age_str| {
- max_age_str
- .strip_prefix("max-age=")
- .and_then(|age| age.parse::<u64>().ok())
- })
- })
- .unwrap_or(0); // Default to 0 if header is missing or invalid
-
- let jwks_response = response
- .json::<JwksResponse>()
- .await
- .context("Failed to parse JWKS response from Google certificates endpoint")?;
-
- let mut keys_map = HashMap::new();
- for key in jwks_response.keys {
- keys_map.insert(key.kid.clone(), key);
- }
-
- if keys_map.is_empty() {
- anyhow::bail!("No valid RSA keys found in Google JWKS response");
+ .and_then(parse_cache_max_age)
+ .unwrap_or(0);
+ let jwks: JwksResponse = decode_json_response(response).await?;
+
+ let keys = jwks
+ .keys
+ .into_iter()
+ .map(|key| (key.kid.clone(), key))
+ .collect::<HashMap<_, _>>();
+ if keys.is_empty() {
+ return Err(GmailApiHttpError::InvalidResponse(
+ "Google JWKS response did not contain any RSA keys".to_string(),
+ ));
}
Ok(GooglePublicKeys {
max_age_seconds,
- keys: keys_map,
+ keys,
+ })
+}
+
+fn parse_cache_max_age(cache_control: &str) -> Option<u64> {
+ cache_control.split(',').find_map(|directive| {
+ let (name, value) = directive.trim().split_once('=')?;
+ if !name.trim().eq_ignore_ascii_case("max-age") {
+ return None;
+ }
+ value.trim().trim_matches('"').parse().ok()
})
}
@@ -62,13 +62,9 @@ pub(crate) fn verify_google_jwt(
token: &str,
public_keys: KeyMap,
) -> Result<GoogleJwtClaims, JwtVerificationError> {
- // Extract the key ID from the JWT header
let header = jsonwebtoken::decode_header(token)
- .map_err(|e| JwtVerificationError::HeaderDecodeError(e.into()))?;
-
- let kid = header.kid.ok_or_else(|| JwtVerificationError::MissingKid)?;
-
- // Find the corresponding public key
+ .map_err(|error| JwtVerificationError::HeaderDecodeError(error.into()))?;
+ let kid = header.kid.ok_or(JwtVerificationError::MissingKid)?;
let public_key = public_keys
.get(&kid)
.ok_or_else(|| JwtVerificationError::KeyNotFound(kid))?;
@@ -80,78 +76,24 @@ pub(crate) fn verify_google_jwt(
}
let decoding_key = DecodingKey::from_rsa_components(&public_key.n, &public_key.e)
- .map_err(|e| JwtVerificationError::DecodingKeyCreationError(e.into()))?;
-
- // Set up validation parameters
+ .map_err(|error| JwtVerificationError::DecodingKeyCreationError(error.into()))?;
let mut validation = Validation::new(Algorithm::RS256);
validation.set_audience(&[&client.audience]);
validation.set_issuer(&["accounts.google.com", "https://accounts.google.com"]);
- // Verify and decode the token
- let token_data = match decode::<GoogleJwtClaims>(token, &decoding_key, &validation) {
- Ok(data) => data,
- Err(err) => {
- // Provide more specific error information based on the JWT error
- return Err(match &err.kind() {
- jsonwebtoken::errors::ErrorKind::InvalidSignature => {
- JwtVerificationError::InvalidSignature
- }
- jsonwebtoken::errors::ErrorKind::InvalidAudience => {
- JwtVerificationError::InvalidAudience
- }
- jsonwebtoken::errors::ErrorKind::InvalidIssuer => {
- JwtVerificationError::InvalidIssuer
- }
- _ => JwtVerificationError::ValidationError(err.into()),
- });
- }
- };
-
- Ok(token_data.claims)
+ decode::<GoogleJwtClaims>(token, &decoding_key, &validation)
+ .map(|token_data| token_data.claims)
+ .map_err(|error| match error.kind() {
+ jsonwebtoken::errors::ErrorKind::InvalidSignature => {
+ JwtVerificationError::InvalidSignature
+ }
+ jsonwebtoken::errors::ErrorKind::InvalidAudience => {
+ JwtVerificationError::InvalidAudience
+ }
+ jsonwebtoken::errors::ErrorKind::InvalidIssuer => JwtVerificationError::InvalidIssuer,
+ _ => JwtVerificationError::ValidationError(error.into()),
+ })
}
-#[cfg(feature = "gmail_test")]
#[cfg(test)]
-mod tests {
- use super::*;
- use anyhow::Context;
-
- #[tokio::test]
- #[ignore = "Jwt env var is not available in CI"]
- async fn test_verify_real_google_jwt() -> anyhow::Result<()> {
- let gmail_client = super::GmailClient::new("hello".to_string());
-
- let public_keys = fetch_google_public_keys(&gmail_client).await?;
-
- let jwt = std::env::var("GOOGLE_TEST_JWT")
- .context("GOOGLE_TEST_JWT environment variable not set")?;
-
- let claims = verify_google_jwt(&gmail_client, &jwt, public_keys.keys)?;
-
- assert_eq!(
- claims.iss, "https://accounts.google.com",
- "Issuer should be accounts.google.com"
- );
- assert!(!claims.sub.is_empty(), "Subject should not be empty");
- assert!(!claims.email.is_empty(), "Email should not be empty");
- assert!(claims.email_verified, "Email should be verified");
- assert!(
- claims.exp > claims.iat,
- "Expiration time should be after issued at time"
- );
-
- println!("✅ Successfully verified Google JWT");
- println!("Email: {}", claims.email);
- println!("Subject: {}", claims.sub);
- println!(
- "Issued at: {}",
- chrono::DateTime::from_timestamp(claims.iat as i64, 0).unwrap()
- );
- println!(
- "Expires at: {}",
- chrono::DateTime::from_timestamp(claims.exp as i64, 0).unwrap()
- );
-
- Ok(())
- }
-}
+mod test;
diff --git a/crates/gmail_client/src/auth/test.rs b/crates/gmail_client/src/auth/test.rs
new file mode 100644
index 0000000000..b021cad225
--- /dev/null
+++ b/crates/gmail_client/src/auth/test.rs
@@ -0,0 +1,64 @@
+use wiremock::matchers::{method, path};
+use wiremock::{Mock, MockServer, ResponseTemplate};
+
+use super::*;
+
+fn client(server: &MockServer) -> GmailClient {
+ GmailClient::new_with_urls(
+ String::new(),
+ server.uri(),
+ server.uri(),
+ format!("{}/certs", server.uri()),
+ String::new(),
+ )
+}
+
+#[tokio::test]
+async fn jwks_parses_quoted_case_insensitive_cache_max_age() {
+ let server = MockServer::start().await;
+ Mock::given(method("GET"))
+ .and(path("/certs"))
+ .respond_with(
+ ResponseTemplate::new(200)
+ .insert_header("Cache-Control", "public, MAX-AGE=\"3600\", must-revalidate")
+ .set_body_json(serde_json::json!({
+ "keys": [{
+ "kid": "key-1", "alg": "RS256", "kty": "RSA",
+ "n": "modulus", "e": "AQAB"
+ }]
+ })),
+ )
+ .mount(&server)
+ .await;
+
+ let keys = fetch_google_public_keys(&client(&server))
+ .await
+ .expect("JWKS should decode");
+
+ assert_eq!(keys.max_age_seconds, 3600);
+ assert_eq!(keys.keys["key-1"].kid, "key-1");
+}
+
+#[tokio::test]
+async fn jwks_defaults_to_zero_for_invalid_cache_control() {
+ let server = MockServer::start().await;
+ Mock::given(method("GET"))
+ .and(path("/certs"))
+ .respond_with(
+ ResponseTemplate::new(200)
+ .insert_header("Cache-Control", "max-age=invalid")
+ .set_body_json(serde_json::json!({
+ "keys": [{
+ "kid": "key-1", "alg": "RS256", "kty": "RSA",
+ "n": "modulus", "e": "AQAB"
+ }]
+ })),
+ )
+ .mount(&server)
+ .await;
+
+ let keys = fetch_google_public_keys(&client(&server))
+ .await
+ .expect("JWKS should decode");
+ assert_eq!(keys.max_age_seconds, 0);
+}
diff --git a/crates/gmail_client/src/contacts.rs b/crates/gmail_client/src/contacts.rs
index 3651087675..7d71163d24 100644
--- a/crates/gmail_client/src/contacts.rs
+++ b/crates/gmail_client/src/contacts.rs
@@ -1,184 +1,140 @@
-use crate::GmailClient;
-use anyhow::Context;
+use crate::error::{decode_json_response, unsuccessful_response};
+use crate::{GmailApiHttpError, GmailClient};
use models_email::gmail::contacts::{ConnectionsResponse, OtherContactsResponse, PersonResource};
-/// Get the user's own connection.
-/// Returns raw Gmail PersonResource - callers should map to service layer Contact.
+const PERSON_FIELDS: &str = "names,emailAddresses,photos";
+
+/// Gets the user's own connection as a raw People API resource.
#[tracing::instrument(skip(client, access_token), err)]
pub(crate) async fn get_self_connection(
client: &GmailClient,
access_token: &str,
-) -> anyhow::Result<PersonResource> {
- let http_client = client.inner.clone();
-
- let url = format!(
- "{}/people/me?personFields=names,emailAddresses,photos",
- client.contacts_url
- );
-
- let response = http_client
- .get(&url)
+) -> Result<PersonResource, GmailApiHttpError> {
+ let response = client
+ .inner
+ .get(format!("{}/people/me", client.contacts_url))
.bearer_auth(access_token)
+ .query(&[("personFields", PERSON_FIELDS)])
.send()
.await
- .context("Failed to send request to People API (get self connection)")?;
+ .map_err(GmailApiHttpError::transport)?;
- let response = response
- .error_for_status()
- .context("People API returned an error status (get self connection)")?;
-
- let person_resource = response
- .json::<PersonResource>()
- .await
- .context("Failed to parse JSON response from People API (get self connection)")?;
+ if !response.status().is_success() {
+ return Err(unsuccessful_response(response).await);
+ }
- Ok(person_resource)
+ decode_json_response(response).await
}
-/// Fetches contacts from the People API.
-/// If a sync_token is provided, it fetches only the changes since the last sync.
-/// Otherwise, it performs a full sync of all contacts.
-/// Returns raw Gmail PersonResource objects and the next sync token - callers should map to service layer Contacts.
+/// Fetches all pages of the user's contacts and returns raw People resources.
#[tracing::instrument(skip(client, access_token, sync_token), err)]
pub(crate) async fn list_connections(
client: &GmailClient,
access_token: &str,
sync_token: Option<&str>,
-) -> anyhow::Result<(Vec<PersonResource>, String)> {
- let mut all_persons: Vec<PersonResource> = Vec::new();
- let mut next_page_token: Option<String> = None;
- let mut final_sync_token: Option<String> = None;
-
- let http_client = client.inner.clone();
-
- // Determine the base URL based on whether this is a full or incremental sync.
- let base_url = if let Some(token) = sync_token {
- // Incremental sync: Use syncToken, omit pageSize
- format!(
- "{}/people/me/connections?personFields=names,emailAddresses,photos&requestSyncToken=true&syncToken={}",
- client.contacts_url, token
- )
- } else {
- // Full sync: Use pageSize
- format!(
- "{}/people/me/connections?personFields=names,emailAddresses,photos&pageSize=1000&requestSyncToken=true",
- client.contacts_url
- )
- };
+) -> Result<(Vec<PersonResource>, String), GmailApiHttpError> {
+ let mut people = Vec::new();
+ let mut page_token: Option<String> = None;
+ let mut next_sync_token: Option<String> = None;
loop {
- let mut url = base_url.clone();
- if let Some(token) = &next_page_token {
- url.push_str(&format!("&pageToken={}", token));
- }
-
- let response = http_client
- .get(&url)
+ let mut request = client
+ .inner
+ .get(format!("{}/people/me/connections", client.contacts_url))
.bearer_auth(access_token)
- .send()
- .await
- .context("Failed to send request to People API (list connections)")?;
-
- let response = response
- .error_for_status()
- .context("People API returned an error status (list connections)")?;
-
- let connection_response = response
- .json::<ConnectionsResponse>()
- .await
- .context("Failed to parse JSON response from People API (list connections)")?;
+ .query(&[
+ ("personFields", PERSON_FIELDS),
+ ("requestSyncToken", "true"),
+ ]);
+ if let Some(token) = sync_token {
+ request = request.query(&[("syncToken", token)]);
+ } else {
+ request = request.query(&[("pageSize", "1000")]);
+ }
+ if let Some(token) = page_token.as_deref() {
+ request = request.query(&[("pageToken", token)]);
+ }
- all_persons.extend(connection_response.connections);
+ let response = request.send().await.map_err(GmailApiHttpError::transport)?;
+ if !response.status().is_success() {
+ return Err(unsuccessful_response(response).await);
+ }
- // Keep the latest sync token returned by the API.
- if let Some(sync_token) = connection_response.next_sync_token {
- final_sync_token = Some(sync_token);
+ let page: ConnectionsResponse = decode_json_response(response).await?;
+ people.extend(page.connections);
+ if page.next_sync_token.is_some() {
+ next_sync_token = page.next_sync_token;
}
+ page_token = page.next_page_token;
- // Handle pagination.
- if let Some(page_token) = connection_response.next_page_token {
- next_page_token = Some(page_token);
- } else {
+ if page_token.is_none() {
break;
}
}
- let next_sync_token = final_sync_token.context("People API did not return a nextSyncToken")?;
-
- Ok((all_persons, next_sync_token))
+ let next_sync_token = next_sync_token.ok_or_else(|| {
+ GmailApiHttpError::InvalidResponse(
+ "People API did not return a nextSyncToken for connections".to_string(),
+ )
+ })?;
+ Ok((people, next_sync_token))
}
-/// Fetches "Other Contacts" from the People API.
-/// If a sync_token is provided, it fetches only the changes since the last sync.
-/// Otherwise, it performs a full sync of all "Other Contacts".
-/// Returns raw Gmail PersonResource objects and the next sync token - callers should map to service layer Contacts.
+/// Fetches all pages of "Other Contacts" and returns raw People resources.
#[tracing::instrument(skip(client, access_token, sync_token), err)]
pub(crate) async fn list_other_contacts(
client: &GmailClient,
access_token: &str,
sync_token: Option<&str>,
-) -> anyhow::Result<(Vec<PersonResource>, String)> {
- let mut all_persons: Vec<PersonResource> = Vec::new();
- let mut next_page_token: Option<String> = None;
- let mut final_sync_token: Option<String> = None;
-
- let http_client = client.inner.clone();
-
- // Determine the base URL based on whether this is a full or incremental sync.
- // Request the PROFILE source alongside CONTACT: the default CONTACT-only source
- // returns no photos for "other contacts", so profile photos require PROFILE.
- let base_url = if let Some(token) = sync_token {
- // Incremental sync: Use syncToken, omit pageSize
- format!(
- "{}/otherContacts?readMask=names,emailAddresses,photos&sources=READ_SOURCE_TYPE_CONTACT&sources=READ_SOURCE_TYPE_PROFILE&requestSyncToken=true&syncToken={}",
- client.contacts_url, token
- )
- } else {
- // Full sync: Use pageSize
- format!(
- "{}/otherContacts?readMask=names,emailAddresses,photos&sources=READ_SOURCE_TYPE_CONTACT&sources=READ_SOURCE_TYPE_PROFILE&pageSize=1000&requestSyncToken=true",
- client.contacts_url
- )
- };
+) -> Result<(Vec<PersonResource>, String), GmailApiHttpError> {
+ let mut people = Vec::new();
+ let mut page_token: Option<String> = None;
+ let mut next_sync_token: Option<String> = None;
loop {
- let mut url = base_url.clone();
- if let Some(token) = &next_page_token {
- url.push_str(&format!("&pageToken={}", token));
- }
-
- let response = http_client
- .get(&url)
+ let mut request = client
+ .inner
+ .get(format!("{}/otherContacts", client.contacts_url))
.bearer_auth(access_token)
- .send()
- .await
- .context("Failed to send request to People API (list other contacts)")?;
-
- let response = response
- .error_for_status()
- .context("People API returned an error status (list other contacts)")?;
-
- let other_contacts_response = response
- .json::<OtherContactsResponse>()
- .await
- .context("Failed to parse JSON response from People API (list other contacts)")?;
+ .query(&[
+ ("readMask", PERSON_FIELDS),
+ ("sources", "READ_SOURCE_TYPE_CONTACT"),
+ ("sources", "READ_SOURCE_TYPE_PROFILE"),
+ ("requestSyncToken", "true"),
+ ]);
+ if let Some(token) = sync_token {
+ request = request.query(&[("syncToken", token)]);
+ } else {
+ request = request.query(&[("pageSize", "1000")]);
+ }
+ if let Some(token) = page_token.as_deref() {
+ request = request.query(&[("pageToken", token)]);
+ }
- all_persons.extend(other_contacts_response.other_contacts);
+ let response = request.send().await.map_err(GmailApiHttpError::transport)?;
+ if !response.status().is_success() {
+ return Err(unsuccessful_response(response).await);
+ }
- // Keep the latest sync token returned by the API.
- if let Some(sync_token) = other_contacts_response.next_sync_token {
- final_sync_token = Some(sync_token);
+ let page: OtherContactsResponse = decode_json_response(response).await?;
+ people.extend(page.other_contacts);
+ if page.next_sync_token.is_some() {
+ next_sync_token = page.next_sync_token;
}
+ page_token = page.next_page_token;
- // Handle pagination.
- if let Some(page_token) = other_contacts_response.next_page_token {
- next_page_token = Some(page_token);
- } else {
+ if page_token.is_none() {
break;
}
}
- let next_sync_token = final_sync_token.context("People API did not return a nextSyncToken")?;
-
- Ok((all_persons, next_sync_token))
+ let next_sync_token = next_sync_token.ok_or_else(|| {
+ GmailApiHttpError::InvalidResponse(
+ "People API did not return a nextSyncToken for other contacts".to_string(),
+ )
+ })?;
+ Ok((people, next_sync_token))
}
+
+#[cfg(test)]
+mod test;
diff --git a/crates/gmail_client/src/contacts/test.rs b/crates/gmail_client/src/contacts/test.rs
new file mode 100644
index 0000000000..abed4c4b34
--- /dev/null
+++ b/crates/gmail_client/src/contacts/test.rs
@@ -0,0 +1,139 @@
+use wiremock::matchers::{method, path, query_param, query_param_is_missing};
+use wiremock::{Mock, MockServer, ResponseTemplate};
+
+use super::*;
+
+fn client(server: &MockServer) -> GmailClient {
+ GmailClient::new_with_urls(
+ String::new(),
+ server.uri(),
+ server.uri(),
+ server.uri(),
+ String::new(),
+ )
+}
+
+#[tokio::test]
+async fn connections_paginate_and_return_the_final_sync_token() {
+ let server = MockServer::start().await;
+ Mock::given(method("GET"))
+ .and(path("/people/me/connections"))
+ .and(query_param("pageSize", "1000"))
+ .and(query_param("requestSyncToken", "true"))
+ .and(query_param_is_missing("pageToken"))
+ .respond_with(ResponseTemplate::new(200).set_body_json(serde_json::json!({
+ "connections": [{}],
+ "nextPageToken": "page-2"
+ })))
+ .expect(1)
+ .mount(&server)
+ .await;
+ Mock::given(method("GET"))
+ .and(path("/people/me/connections"))
+ .and(query_param("pageToken", "page-2"))
+ .respond_with(ResponseTemplate::new(200).set_body_json(serde_json::json!({
+ "connections": [{}],
+ "nextSyncToken": "sync-final"
+ })))
+ .expect(1)
+ .mount(&server)
+ .await;
+
+ let (people, sync_token) = list_connections(&client(&server), "token", None)
+ .await
+ .expect("connections should decode");
+
+ assert_eq!(people.len(), 2);
+ assert_eq!(sync_token, "sync-final");
+}
+
+#[tokio::test]
+async fn other_contacts_incremental_sync_paginates() {
+ let server = MockServer::start().await;
+ Mock::given(method("GET"))
+ .and(path("/otherContacts"))
+ .and(query_param("syncToken", "old-sync"))
+ .and(query_param_is_missing("pageSize"))
+ .and(query_param_is_missing("pageToken"))
+ .respond_with(ResponseTemplate::new(200).set_body_json(serde_json::json!({
+ "otherContacts": [{}],
+ "nextPageToken": "page-2"
+ })))
+ .expect(1)
+ .mount(&server)
+ .await;
+ Mock::given(method("GET"))
+ .and(path("/otherContacts"))
+ .and(query_param("syncToken", "old-sync"))
+ .and(query_param("pageToken", "page-2"))
+ .respond_with(ResponseTemplate::new(200).set_body_json(serde_json::json!({
+ "otherContacts": [{}],
+ "nextSyncToken": "new-sync"
+ })))
+ .expect(1)
+ .mount(&server)
+ .await;
+
+ let (people, sync_token) = list_other_contacts(&client(&server), "token", Some("old-sync"))
+ .await
+ .expect("other contacts should decode");
+
+ assert_eq!(people.len(), 2);
+ assert_eq!(sync_token, "new-sync");
+}
+
+#[tokio::test]
+async fn missing_connections_sync_token_is_an_invalid_response() {
+ let server = MockServer::start().await;
+ Mock::given(method("GET"))
+ .and(path("/people/me/connections"))
+ .respond_with(ResponseTemplate::new(200).set_body_json(serde_json::json!({
+ "connections": []
+ })))
+ .mount(&server)
+ .await;
+
+ let error = list_connections(&client(&server), "token", None)
+ .await
+ .expect_err("missing sync token should fail");
+
+ assert!(matches!(error, GmailApiHttpError::InvalidResponse(_)));
+}
+
+#[tokio::test]
+async fn missing_other_contacts_sync_token_is_an_invalid_response() {
+ let server = MockServer::start().await;
+ Mock::given(method("GET"))
+ .and(path("/otherContacts"))
+ .respond_with(ResponseTemplate::new(200).set_body_json(serde_json::json!({
+ "otherContacts": []
+ })))
+ .mount(&server)
+ .await;
+
+ let error = list_other_contacts(&client(&server), "token", None)
+ .await
+ .expect_err("missing sync token should fail");
+
+ assert!(matches!(error, GmailApiHttpError::InvalidResponse(_)));
+}
+
+#[tokio::test]
+async fn self_contact_preserves_the_raw_person_resource() {
+ let server = MockServer::start().await;
+ Mock::given(method("GET"))
+ .and(path("/people/me"))
+ .and(query_param("personFields", "names,emailAddresses,photos"))
+ .respond_with(ResponseTemplate::new(200).set_body_json(serde_json::json!({
+ "names": [{ "displayName": "Ada" }],
+ "emailAddresses": [{ "value": "[email protected]" }],
+ "photos": []
+ })))
+ .mount(&server)
+ .await;
+
+ let person = get_self_connection(&client(&server), "token")
+ .await
+ .expect("person should decode");
+ assert_eq!(person.names[0].display_name.as_deref(), Some("Ada"));
+}
diff --git a/crates/gmail_client/src/error.rs b/crates/gmail_client/src/error.rs
new file mode 100644
index 0000000000..fbe99bc082
--- /dev/null
+++ b/crates/gmail_client/src/error.rs
@@ -0,0 +1,167 @@
+use reqwest::StatusCode;
+use serde::de::DeserializeOwned;
+use std::error::Error;
+use std::fmt::{Display, Formatter};
+use std::time::Duration;
+
+use crate::sanitize_error_body;
+
+/// An error produced while communicating with a Gmail-related HTTP endpoint.
+#[derive(Debug)]
+pub enum GmailApiHttpError {
+ /// The remote endpoint returned an unsuccessful HTTP status.
+ Http {
+ /// The HTTP status returned by the endpoint.
+ status: StatusCode,
+ /// The sanitized response body.
+ body: String,
+ /// The delay requested by the endpoint's `Retry-After` header, when present.
+ retry_after: Option<Duration>,
+ },
+ /// The request could not be sent or the response could not be received.
+ Transport(reqwest::Error),
+ /// A successful HTTP response could not be decoded.
+ Decode(reqwest::Error),
+ /// The response was syntactically valid but omitted required data.
+ InvalidResponse(String),
+}
+
+impl GmailApiHttpError {
+ /// Wraps a send failure, stripping the request URL so query parameters
+ /// (e.g. People-API `syncToken`s) cannot leak into logs via `Display`.
+ pub(crate) fn transport(error: reqwest::Error) -> Self {
+ Self::Transport(error.without_url())
+ }
+
+ /// Wraps a decode failure, stripping the request URL so query parameters
+ /// cannot leak into logs via `Display`.
+ pub(crate) fn decode(error: reqwest::Error) -> Self {
+ Self::Decode(error.without_url())
+ }
+
+ /// Returns the HTTP status when the endpoint returned an unsuccessful response.
+ pub fn status(&self) -> Option<StatusCode> {
+ match self {
+ Self::Http { status, .. } => Some(*status),
+ _ => None,
+ }
+ }
+
+ /// Returns the sanitized response body for an unsuccessful response.
+ pub fn body(&self) -> Option<&str> {
+ match self {
+ Self::Http { body, .. } => Some(body),
+ _ => None,
+ }
+ }
+
+ /// Returns the server-requested retry delay for an unsuccessful response.
+ pub fn retry_after(&self) -> Option<Duration> {
+ match self {
+ Self::Http { retry_after, .. } => *retry_after,
+ _ => None,
+ }
+ }
+}
+
+impl Display for GmailApiHttpError {
+ fn fmt(&self, formatter: &mut Formatter<'_>) -> std::fmt::Result {
+ match self {
+ Self::Http { status, body, .. } => {
+ write!(formatter, "Gmail API returned {status}: {body}")
+ }
+ Self::Transport(error) => write!(formatter, "Gmail API transport error: {error}"),
+ Self::Decode(error) => write!(formatter, "Gmail API response decode error: {error}"),
+ Self::InvalidResponse(message) => {
+ write!(
+ formatter,
+ "Gmail API returned an invalid response: {message}"
+ )
+ }
+ }
+ }
+}
+
+impl Error for GmailApiHttpError {
+ fn source(&self) -> Option<&(dyn Error + 'static)> {
+ match self {
+ Self::Transport(error) | Self::Decode(error) => Some(error),
+ Self::Http { .. } | Self::InvalidResponse(_) => None,
+ }
+ }
+}
+
+/// Converts an unsuccessful response into the crate's typed HTTP error.
+///
+/// Error response bodies are always read and sanitized here so provider methods
+/// cannot accidentally expose response data through ad-hoc error handling.
+pub(crate) async fn unsuccessful_response(response: reqwest::Response) -> GmailApiHttpError {
+ let status = response.status();
+ let retry_after = response
+ .headers()
+ .get(reqwest::header::RETRY_AFTER)
+ .and_then(|value| value.to_str().ok())
+ .and_then(parse_retry_after);
+
+ let body = sanitize_error_body(&read_error_body_capped(response).await);
+
+ GmailApiHttpError::Http {
+ status,
+ body,
+ retry_after,
+ }
+}
+
+/// The most we will *read* of an error body (not just retain after
+/// truncation): a hostile or misbehaving endpoint must not make us buffer an
+/// arbitrarily large response just to report a failure.
+const MAX_ERROR_BODY_READ_BYTES: usize = 8 * 1024;
+
+async fn read_error_body_capped(mut response: reqwest::Response) -> String {
+ let mut collected: Vec<u8> = Vec::new();
+ loop {
+ match response.chunk().await {
+ Ok(Some(chunk)) => {
+ let remaining = MAX_ERROR_BODY_READ_BYTES - collected.len();
+ collected.extend_from_slice(&chunk[..chunk.len().min(remaining)]);
+ if collected.len() >= MAX_ERROR_BODY_READ_BYTES {
+ break;
+ }
+ }
+ Ok(None) => break,
+ Err(error) => return format!("Unable to read response body: {error}"),
+ }
+ }
+
+ String::from_utf8_lossy(&collected).into_owned()
+}
+
+/// Parses a `Retry-After` header value in either of its RFC 9110 forms:
+/// delta-seconds or an HTTP-date (clamped at zero when already past).
+fn parse_retry_after(value: &str) -> Option<Duration> {
+ let value = value.trim();
+ if let Ok(seconds) = value.parse::<u64>() {
+ return Some(Duration::from_secs(seconds));
+ }
+
+ let when = httpdate::parse_http_date(value).ok()?;
+ Some(
+ when.duration_since(std::time::SystemTime::now())
+ .unwrap_or(Duration::ZERO),
+ )
+}
+
+pub(crate) async fn decode_json_response<T>(
+ response: reqwest::Response,
+) -> Result<T, GmailApiHttpError>
+where
+ T: DeserializeOwned,
+{
+ response
+ .json::<T>()
+ .await
+ .map_err(GmailApiHttpError::decode)
+}
+
+#[cfg(test)]
+mod test;
diff --git a/crates/gmail_client/src/error/test.rs b/crates/gmail_client/src/error/test.rs
new file mode 100644
index 0000000000..2404cb27c2
--- /dev/null
+++ b/crates/gmail_client/src/error/test.rs
@@ -0,0 +1,103 @@
+use std::time::Duration;
+
+use reqwest::StatusCode;
+use wiremock::matchers::{method, path};
+use wiremock::{Mock, MockServer, ResponseTemplate};
+
+use super::*;
+
+#[tokio::test]
+async fn preserves_status_sanitized_body_and_retry_after() {
+ let server = MockServer::start().await;
+ Mock::given(method("GET"))
+ .and(path("/failure"))
+ .respond_with(
+ ResponseTemplate::new(StatusCode::TOO_MANY_REQUESTS.as_u16())
+ .insert_header("Retry-After", "37")
+ .set_body_string(" contact [email protected] for details "),
+ )
+ .mount(&server)
+ .await;
+
+ let response = reqwest::Client::new()
+ .get(format!("{}/failure", server.uri()))
+ .send()
+ .await
+ .expect("request should complete");
+ let error = unsuccessful_response(response).await;
+
+ assert_eq!(error.status(), Some(StatusCode::TOO_MANY_REQUESTS));
+ assert_eq!(error.body(), Some("contact [REDACTED_EMAIL] for details"));
+ assert_eq!(error.retry_after(), Some(Duration::from_secs(37)));
+}
+
+#[tokio::test]
+async fn transport_and_decode_errors_do_not_leak_request_urls() {
+ // Transport failure against a URL carrying a sensitive query parameter.
+ let transport_error = reqwest::Client::new()
+ .get("http://127.0.0.1:1/people?syncToken=SECRET-TOKEN")
+ .send()
+ .await
+ .expect_err("connection to a closed port should fail");
+ let error = GmailApiHttpError::transport(transport_error);
+ let rendered = error.to_string();
+ assert!(matches!(error, GmailApiHttpError::Transport(_)));
+ assert!(
+ !rendered.contains("SECRET-TOKEN") && !rendered.contains("127.0.0.1"),
+ "transport errors must not render the request URL: {rendered}"
+ );
+
+ // Decode failure through the shared decoder, same URL-hygiene requirement.
+ let server = MockServer::start().await;
+ Mock::given(method("GET"))
+ .and(path("/malformed"))
+ .respond_with(ResponseTemplate::new(200).set_body_string("not json"))
+ .mount(&server)
+ .await;
+ let response = reqwest::Client::new()
+ .get(format!("{}/malformed?syncToken=SECRET-TOKEN", server.uri()))
+ .send()
+ .await
+ .expect("request should complete");
+ let decode_error = decode_json_response::<serde_json::Value>(response)
+ .await
+ .expect_err("malformed JSON should fail decoding");
+ let rendered = decode_error.to_string();
+ assert!(matches!(decode_error, GmailApiHttpError::Decode(_)));
+ assert!(
+ !rendered.contains("SECRET-TOKEN") && !rendered.contains(&server.uri()),
+ "decode errors must not render the request URL: {rendered}"
+ );
+}
+
+#[test]
+fn retry_after_parses_delta_seconds_and_http_dates() {
+ assert_eq!(parse_retry_after("37"), Some(Duration::from_secs(37)));
+ assert_eq!(parse_retry_after(" 37 "), Some(Duration::from_secs(37)));
+
+ let future = std::time::SystemTime::now() + Duration::from_secs(120);
+ let parsed =
+ parse_retry_after(&httpdate::fmt_http_date(future)).expect("http-date form should parse");
+ assert!(
+ parsed <= Duration::from_secs(120) && parsed >= Duration::from_secs(110),
+ "expected roughly two minutes, got {parsed:?}"
+ );
+
+ // A date in the past clamps to zero instead of failing or underflowing.
+ assert_eq!(
+ parse_retry_after("Sun, 06 Nov 1994 08:49:37 GMT"),
+ Some(Duration::ZERO)
+ );
+
+ assert_eq!(parse_retry_after("not-a-date"), None);
+}
+
+#[test]
+fn sanitization_truncates_unicode_only_at_character_boundaries() {
+ let body = format!("{} [email protected]", "界".repeat(400));
+ let sanitized = sanitize_error_body(&body);
+
+ assert!(sanitized.ends_with("… (truncated)"));
+ assert!(!sanitized.contains("[email protected]"));
+ assert!(sanitized.is_char_boundary(sanitized.len()));
+}
diff --git a/crates/gmail_client/src/filters.rs b/crates/gmail_client/src/filters.rs
index 0875d4cdc7..ab00af9d73 100644
--- a/crates/gmail_client/src/filters.rs
+++ b/crates/gmail_client/src/filters.rs
@@ -1,245 +1,76 @@
-use crate::GmailClient;
-use models_email::gmail::error::GmailError;
-use models_email::gmail::filters::{Filter, FilterAction, FilterCriteria, ListFiltersResponse};
+use crate::error::{decode_json_response, unsuccessful_response};
+use crate::{GmailApiHttpError, GmailClient};
+use models_email::gmail::filters::{Filter, ListFiltersResponse};
-/// Creates a filter to block a user by sending their emails to TRASH.
-/// This replicates the "Block Sender" functionality in the Superhuman UI.
-#[tracing::instrument(skip(client, access_token), err)]
-pub(crate) async fn block_sender(
- client: &GmailClient,
- access_token: &str,
- email_to_block: &str,
-) -> Result<Filter, GmailError> {
- let filter = Filter {
- id: None,
- criteria: FilterCriteria {
- from: Some(email_to_block.to_string()),
- to: None,
- subject: None,
- query: None,
- negated_query: None,
- has_attachment: None,
- exclude_chats: None,
- },
-
- action: FilterAction {
- add_label_ids: Some(vec!["TRASH".to_string()]),
- remove_label_ids: None,
- forward: None,
- },
- };
-
- create_filter(client, access_token, filter).await
-}
-
-/// Creates a new Gmail filter.
+/// Creates a Gmail filter from the supplied wire request.
#[tracing::instrument(skip(client, access_token), err)]
pub(crate) async fn create_filter(
client: &GmailClient,
access_token: &str,
filter: Filter,
-) -> Result<Filter, GmailError> {
- let url = format!("{}/users/me/settings/filters", client.base_url);
-
- let http_client = client.inner.clone();
-
- let response = http_client
- .post(&url)
+) -> Result<Filter, GmailApiHttpError> {
+ let response = client
+ .inner
+ .post(format!("{}/users/me/settings/filters", client.base_url))
.bearer_auth(access_token)
.json(&filter)
.send()
.await
- .map_err(|e| GmailError::HttpRequest(e.to_string()))?;
+ .map_err(GmailApiHttpError::transport)?;
- let response = response.error_for_status().map_err(|e| match e.status() {
- Some(status) if status.as_u16() == 401 => GmailError::Unauthorized,
- Some(status) if status.as_u16() == 403 => GmailError::Forbidden,
- Some(status) if status.as_u16() == 429 => GmailError::RateLimitExceeded,
- Some(status) if status.as_u16() == 409 => {
- GmailError::Conflict("Filter already exists".to_string())
- }
- _ => GmailError::ApiError(e.to_string()),
- })?;
-
- let created_filter = response
- .json::<Filter>()
- .await
- .map_err(|e| GmailError::BodyReadError(e.to_string()))?;
+ if !response.status().is_success() {
+ return Err(unsuccessful_response(response).await);
+ }
- Ok(created_filter)
+ decode_json_response(response).await
}
-/// Lists all filters for the user.
+/// Lists all raw Gmail filters for the user.
#[tracing::instrument(skip(client, access_token), err)]
pub(crate) async fn list_filters(
client: &GmailClient,
access_token: &str,
-) -> Result<Vec<Filter>, GmailError> {
- let url = format!("{}/users/me/settings/filters", client.base_url);
-
- let http_client = client.inner.clone();
-
- let response = http_client
- .get(&url)
- .bearer_auth(access_token)
- .send()
- .await
- .map_err(|e| GmailError::HttpRequest(e.to_string()))?;
-
- let response = response.error_for_status().map_err(|e| match e.status() {
- Some(status) if status.as_u16() == 401 => GmailError::Unauthorized,
- Some(status) if status.as_u16() == 403 => GmailError::Forbidden,
- Some(status) if status.as_u16() == 429 => GmailError::RateLimitExceeded,
- _ => GmailError::ApiError(e.to_string()),
- })?;
-
- let filters_response = response
- .json::<ListFiltersResponse>()
- .await
- .map_err(|e| GmailError::BodyReadError(e.to_string()))?;
-
- Ok(filters_response.filter)
-}
-
-/// Gets a specific filter by ID.
-#[tracing::instrument(skip(client, access_token), err)]
-pub(crate) async fn get_filter(
- client: &GmailClient,
- access_token: &str,
- filter_id: &str,
-) -> Result<Filter, GmailError> {
- let url = format!(
- "{}/users/me/settings/filters/{}",
- client.base_url, filter_id
- );
-
- let http_client = client.inner.clone();
-
- let response = http_client
- .get(&url)
+) -> Result<Vec<Filter>, GmailApiHttpError> {
+ let response = client
+ .inner
+ .get(format!("{}/users/me/settings/filters", client.base_url))
.bearer_auth(access_token)
.send()
.await
- .map_err(|e| GmailError::HttpRequest(e.to_string()))?;
+ .map_err(GmailApiHttpError::transport)?;
- let response = response.error_for_status().map_err(|e| match e.status() {
- Some(status) if status.as_u16() == 401 => GmailError::Unauthorized,
- Some(status) if status.as_u16() == 403 => GmailError::Forbidden,
- Some(status) if status.as_u16() == 429 => GmailError::RateLimitExceeded,
- Some(status) if status.as_u16() == 404 => {
- GmailError::NotFound(format!("Filter {} not found", filter_id))
- }
- _ => GmailError::ApiError(e.to_string()),
- })?;
-
- let filter = response
- .json::<Filter>()
- .await
- .map_err(|e| GmailError::BodyReadError(e.to_string()))?;
+ if !response.status().is_success() {
+ return Err(unsuccessful_response(response).await);
+ }
- Ok(filter)
+ let response = decode_json_response::<ListFiltersResponse>(response).await?;
+ Ok(response.filter)
}
-/// Deletes a filter by ID (can be used to "unblock" a user).
+/// Deletes a Gmail filter by provider ID.
#[tracing::instrument(skip(client, access_token), err)]
pub(crate) async fn delete_filter(
client: &GmailClient,
access_token: &str,
filter_id: &str,
-) -> Result<(), GmailError> {
- let url = format!(
- "{}/users/me/settings/filters/{}",
- client.base_url, filter_id
- );
-
- let http_client = client.inner.clone();
-
- let response = http_client
- .delete(&url)
+) -> Result<(), GmailApiHttpError> {
+ let response = client
+ .inner
+ .delete(format!(
+ "{}/users/me/settings/filters/{filter_id}",
+ client.base_url
+ ))
.bearer_auth(access_token)
.send()
.await
- .map_err(|e| GmailError::HttpRequest(e.to_string()))?;
+ .map_err(GmailApiHttpError::transport)?;
- response.error_for_status().map_err(|e| match e.status() {
- Some(status) if status.as_u16() == 401 => GmailError::Unauthorized,
- Some(status) if status.as_u16() == 403 => GmailError::Forbidden,
- Some(status) if status.as_u16() == 429 => GmailError::RateLimitExceeded,
- Some(status) if status.as_u16() == 404 => {
- GmailError::NotFound(format!("Filter {} not found", filter_id))
- }
- _ => GmailError::ApiError(e.to_string()),
- })?;
+ if !response.status().is_success() {
+ return Err(unsuccessful_response(response).await);
+ }
Ok(())
}
-/// Finds and returns any existing "block" filters for a specific email address.
-/// This can be used to check if a user is already blocked.
-#[tracing::instrument(skip(client, access_token), err)]
-pub(crate) async fn find_block_filter_for_sender(
- client: &GmailClient,
- access_token: &str,
- email_address: &str,
-) -> Result<Option<Filter>, GmailError> {
- let filters = list_filters(client, access_token).await?;
-
- let block_filter = filters.into_iter().find(|f| {
- if let Some(from) = &f.criteria.from
- && from.eq_ignore_ascii_case(email_address)
- {
- // Check if add_label_ids contains TRASH
- return f
- .action
- .add_label_ids
- .as_ref()
- .map(|labels| labels.contains(&"TRASH".to_string()))
- .unwrap_or(false);
- }
- false
- });
-
- Ok(block_filter)
-}
-
-/// Unblocks a sender by finding and deleting their block filter.
-/// Returns true if a filter was found and deleted, false if no filter existed.
-#[tracing::instrument(skip(client, access_token), err)]
-pub(crate) async fn unblock_sender(
- client: &GmailClient,
- access_token: &str,
- email_address: &str,
-) -> Result<bool, GmailError> {
- if let Some(filter) = find_block_filter_for_sender(client, access_token, email_address).await?
- && let Some(filter_id) = filter.id
- {
- delete_filter(client, access_token, &filter_id).await?;
- return Ok(true);
- }
- Ok(false)
-}
-
-/// Lists all blocked senders by finding filters that send emails to TRASH.
-/// Returns a list of email addresses that are currently blocked.
-#[tracing::instrument(skip(client, access_token), err)]
-pub(crate) async fn list_blocked_senders(
- client: &GmailClient,
- access_token: &str,
-) -> Result<Vec<String>, GmailError> {
- let filters = list_filters(client, access_token).await?;
-
- let blocked_emails = filters
- .into_iter()
- .filter(|f| {
- // Check if add_label_ids contains TRASH
- f.action
- .add_label_ids
- .as_ref()
- .map(|labels| labels.contains(&"TRASH".to_string()))
- .unwrap_or(false)
- })
- .filter_map(|f| f.criteria.from)
- .collect();
-
- Ok(blocked_emails)
-}
+#[cfg(test)]
+mod test;
diff --git a/crates/gmail_client/src/filters/test.rs b/crates/gmail_client/src/filters/test.rs
new file mode 100644
index 0000000000..3b2e5a4c1f
--- /dev/null
+++ b/crates/gmail_client/src/filters/test.rs
@@ -0,0 +1,93 @@
+use reqwest::StatusCode;
+use serde_json::json;
+use wiremock::matchers::{body_json, method, path};
+use wiremock::{Mock, MockServer, ResponseTemplate};
+
+use super::*;
+use models_email::gmail::filters::{FilterAction, FilterCriteria};
+
+fn client(server: &MockServer) -> GmailClient {
+ GmailClient::new_with_urls(
+ String::new(),
+ server.uri(),
+ server.uri(),
+ server.uri(),
+ String::new(),
+ )
+}
+
+fn filter() -> Filter {
+ Filter {
+ id: None,
+ criteria: FilterCriteria {
+ from: Some("[email protected]".to_string()),
+ to: None,
+ subject: None,
+ query: None,
+ negated_query: None,
+ has_attachment: None,
+ exclude_chats: None,
+ },
+ action: FilterAction {
+ add_label_ids: Some(vec!["TRASH".to_string()]),
+ remove_label_ids: None,
+ forward: None,
+ },
+ }
+}
+
+#[tokio::test]
+async fn creates_a_generic_filter() {
+ let server = MockServer::start().await;
+ Mock::given(method("POST"))
+ .and(path("/users/me/settings/filters"))
+ .and(body_json(json!({
+ "criteria": {"from": "[email protected]"},
+ "action": {"addLabelIds": ["TRASH"]}
+ })))
+ .respond_with(ResponseTemplate::new(200).set_body_json(json!({
+ "id": "filter-1",
+ "criteria": {"from": "[email protected]"},
+ "action": {"addLabelIds": ["TRASH"]}
+ })))
+ .mount(&server)
+ .await;
+
+ let created = create_filter(&client(&server), "token", filter())
+ .await
+ .unwrap();
+ assert_eq!(created.id.as_deref(), Some("filter-1"));
+}
+
+#[tokio::test]
+async fn lists_generic_filters() {
+ let server = MockServer::start().await;
+ Mock::given(method("GET"))
+ .and(path("/users/me/settings/filters"))
+ .respond_with(ResponseTemplate::new(200).set_body_json(json!({
+ "filter": [{
+ "id": "filter-1", "criteria": {}, "action": {}
+ }]
+ })))
+ .mount(&server)
+ .await;
+
+ let filters = list_filters(&client(&server), "token").await.unwrap();
+ assert_eq!(filters[0].id.as_deref(), Some("filter-1"));
+}
+
+#[tokio::test]
+async fn delete_preserves_http_errors() {
+ let server = MockServer::start().await;
+ Mock::given(method("DELETE"))
+ .and(path("/users/me/settings/filters/missing"))
+ .respond_with(ResponseTemplate::new(404).set_body_string("missing"))
+ .mount(&server)
+ .await;
+
+ let error = delete_filter(&client(&server), "token", "missing")
+ .await
+ .unwrap_err();
+ assert_eq!(error.status(), Some(StatusCode::NOT_FOUND));
+ assert_eq!(error.body(), Some("missing"));
+}
diff --git a/crates/gmail_client/src/history.rs b/crates/gmail_client/src/history.rs
index 92531d0713..141bcb5a5e 100644
--- a/crates/gmail_client/src/history.rs
+++ b/crates/gmail_client/src/history.rs
@@ -1,124 +1,57 @@
-use crate::GmailClient;
-use anyhow::Context;
-use models_email::gmail::{HistoryListResponse, UserProfileResponse};
+use crate::error::{decode_json_response, unsuccessful_response};
+use crate::{GmailApiHttpError, GmailClient};
+use models_email::gmail::HistoryListResponse;
const MAX_RESULTS: usize = 500;
-/// Gets the changes to a user's inbox that have occurred since start_history_id.
-/// Returns raw HistoryListResponse - callers should map to InboxChanges using convert module.
+/// Gets the changes to a user's inbox that have occurred since `start_history_id`.
+/// Returns the raw Gmail response for conversion by the caller.
#[tracing::instrument(skip(client, access_token), err)]
pub(crate) async fn get_history(
client: &GmailClient,
access_token: &str,
start_history_id: &str,
-) -> anyhow::Result<HistoryListResponse> {
- let url = format!(
- "{}/users/me/history?startHistoryId={}&maxResults={}",
- client.base_url, start_history_id, MAX_RESULTS
- );
-
- let http_client = client.inner.clone();
-
- let mut history_list_response = HistoryListResponse {
- history: Some(Vec::new()),
- history_id: String::new(),
- next_page_token: None,
- };
+) -> Result<HistoryListResponse, GmailApiHttpError> {
+ let mut history = Vec::new();
+ let mut history_id = String::new();
+ let mut page_token: Option<String> = None;
loop {
- let mut request_url = url.clone();
- if let Some(token) = &history_list_response.next_page_token {
- request_url = format!("{}&pageToken={}", request_url, token);
- }
-
- let response = http_client
- .get(&request_url)
+ let mut request = client
+ .inner
+ .get(format!("{}/users/me/history", client.base_url))
.bearer_auth(access_token)
- .send()
- .await
- .with_context(|| {
- format!(
- "Failed to send request to Gmail API (list history), start_history_id: {}",
- start_history_id
- )
- })?;
-
- let status = response.status();
- if !status.is_success() {
- let error_body = response
- .text()
- .await
- .unwrap_or_else(|_| "Failed to read error body".to_string());
- anyhow::bail!(
- "Gmail API error {} (list history) for start_history_id: {}: {}",
- status,
- start_history_id,
- error_body
- );
+ .query(&[
+ ("startHistoryId", start_history_id),
+ ("maxResults", &MAX_RESULTS.to_string()),
+ ]);
+ if let Some(token) = page_token.as_deref() {
+ request = request.query(&[("pageToken", token)]);
}
- let page_response = response.json::<HistoryListResponse>()
- .await
- .with_context(|| format!("Failed to parse JSON response from Gmail API (list history), start_history_id: {}",
- start_history_id))?;
-
- // Accumulate history items
- if let Some(history) = page_response.history {
- if let Some(existing_history) = &mut history_list_response.history {
- existing_history.extend(history);
- } else {
- history_list_response.history = Some(history);
- }
+ let response = request.send().await.map_err(GmailApiHttpError::transport)?;
+ if !response.status().is_success() {
+ return Err(unsuccessful_response(response).await);
}
- if !page_response.history_id.is_empty() {
- history_list_response.history_id = page_response.history_id;
+ let page: HistoryListResponse = decode_json_response(response).await?;
+ if let Some(page_history) = page.history {
+ history.extend(page_history);
}
-
- history_list_response.next_page_token = page_response.next_page_token;
-
- if history_list_response.next_page_token.is_none() {
- break;
+ if !page.history_id.is_empty() {
+ history_id = page.history_id;
+ }
+ page_token = page.next_page_token;
+
+ if page_token.is_none() {
+ return Ok(HistoryListResponse {
+ history: Some(history),
+ next_page_token: None,
+ history_id,
+ });
}
}
-
- Ok(history_list_response)
}
-/// returns the current history id for the user's inbox using the /profile endpoint
-#[tracing::instrument(skip(client, access_token), err)]
-pub async fn get_current_history_id(
- client: &GmailClient,
- access_token: &str,
-) -> anyhow::Result<String> {
- let url = format!("{}/users/me/profile", client.base_url);
-
- let http_client = client.inner.clone();
-
- let response = http_client
- .get(&url)
- .bearer_auth(access_token)
- .send()
- .await
- .context("Failed to send request to Gmail API (get profile)")?;
-
- let status = response.status();
- if !status.is_success() {
- let error_body = response
- .text()
- .await
- .unwrap_or_else(|_| "Failed to read error body".to_string());
- anyhow::bail!(
- "Gmail API error {} (get current history id): {}",
- status,
- error_body
- );
- }
-
- let profile_response = response
- .json::<UserProfileResponse>()
- .await
- .context("Failed to parse JSON response from Gmail API (get profile)")?;
-
- Ok(profile_response.history_id)
-}
+#[cfg(test)]
+mod test;
diff --git a/crates/gmail_client/src/history/test.rs b/crates/gmail_client/src/history/test.rs
new file mode 100644
index 0000000000..3cf371fb50
--- /dev/null
+++ b/crates/gmail_client/src/history/test.rs
@@ -0,0 +1,80 @@
+use reqwest::StatusCode;
+use wiremock::matchers::{method, path, query_param, query_param_is_missing};
+use wiremock::{Mock, MockServer, ResponseTemplate};
+
+use super::*;
+
+fn client(server: &MockServer) -> GmailClient {
+ GmailClient::new_with_urls(
+ String::new(),
+ server.uri(),
+ server.uri(),
+ server.uri(),
+ String::new(),
+ )
+}
+
+#[tokio::test]
+async fn history_paginates_and_advances_to_the_latest_cursor() {
+ let server = MockServer::start().await;
+ Mock::given(method("GET"))
+ .and(path("/users/me/history"))
+ .and(query_param("startHistoryId", "100"))
+ .and(query_param("maxResults", "500"))
+ .and(query_param_is_missing("pageToken"))
+ .respond_with(ResponseTemplate::new(200).set_body_json(serde_json::json!({
+ "history": [{
+ "id": "101", "messages": null, "messagesAdded": null,
+ "messagesDeleted": null, "labelsAdded": null, "labelsRemoved": null
+ }],
+ "historyId": "101",
+ "nextPageToken": "next"
+ })))
+ .expect(1)
+ .mount(&server)
+ .await;
+ Mock::given(method("GET"))
+ .and(path("/users/me/history"))
+ .and(query_param("pageToken", "next"))
+ .respond_with(ResponseTemplate::new(200).set_body_json(serde_json::json!({
+ "history": [{
+ "id": "102", "messages": null, "messagesAdded": null,
+ "messagesDeleted": null, "labelsAdded": null, "labelsRemoved": null
+ }],
+ "historyId": "102"
+ })))
+ .expect(1)
+ .mount(&server)
+ .await;
+
+ let response = get_history(&client(&server), "token", "100")
+ .await
+ .expect("history should decode");
+
+ assert_eq!(response.history_id, "102");
+ assert_eq!(response.history.unwrap().len(), 2);
+ assert!(response.next_page_token.is_none());
+}
+
+#[tokio::test]
+async fn stale_history_not_found_status_is_preserved() {
+ let server = MockServer::start().await;
+ Mock::given(method("GET"))
+ .and(path("/users/me/history"))
+ .respond_with(
+ ResponseTemplate::new(StatusCode::NOT_FOUND.as_u16())
+ .set_body_string("History cursor for [email protected] is stale"),
+ )
+ .mount(&server)
+ .await;
+
+ let error = get_history(&client(&server), "token", "stale")
+ .await
+ .expect_err("stale history should fail");
+
+ assert_eq!(error.status(), Some(StatusCode::NOT_FOUND));
+ assert_eq!(
+ error.body(),
+ Some("History cursor for [REDACTED_EMAIL] is stale")
+ );
+}
diff --git a/crates/gmail_client/src/labels.rs b/crates/gmail_client/src/labels.rs
index f62511fd23..79622e2963 100644
--- a/crates/gmail_client/src/labels.rs
+++ b/crates/gmail_client/src/labels.rs
@@ -1,13 +1,9 @@
-use crate::GmailClient;
-use anyhow::Context;
-use models_email::email::service;
+use crate::error::{decode_json_response, unsuccessful_response};
+use crate::{GmailApiHttpError, GmailClient};
use models_email::gmail::ModifyLabelsRequest;
-use models_email::gmail::error::GmailError;
-use models_email::gmail::labels::GmailLabelsResponse;
-use uuid::Uuid;
+use models_email::gmail::labels::{GmailLabel, GmailLabelsResponse};
-/// Modifies the labels for a specific message in Gmail
-/// Adds and removes labels according to the provided lists
+/// Modifies the labels for a specific message in Gmail.
#[tracing::instrument(
skip(client, access_token),
fields(provider_message_id = %provider_message_id),
@@ -19,183 +15,97 @@ pub async fn modify_message_labels(
provider_message_id: &str,
label_ids_to_add: &[String],
label_ids_to_remove: &[String],
-) -> Result<(), GmailError> {
+) -> Result<(), GmailApiHttpError> {
let url = format!(
"{}/users/me/messages/{}/modify",
client.base_url, provider_message_id
);
-
- let http_client = client.inner.clone();
-
let payload = ModifyLabelsRequest {
add_label_ids: label_ids_to_add.to_vec(),
remove_label_ids: label_ids_to_remove.to_vec(),
};
-
- let response = http_client
- .post(&url)
+ let response = client
+ .inner
+ .post(url)
.bearer_auth(access_token)
.json(&payload)
.send()
.await
- .map_err(|e| GmailError::HttpRequest(e.to_string()))?;
-
- let status = response.status();
- if !status.is_success() {
- let error_body = response
- .text()
- .await
- .unwrap_or_else(|_| "Failed to read error body".to_string());
+ .map_err(GmailApiHttpError::transport)?;
- return Err(match status.as_u16() {
- 401 => GmailError::Unauthorized,
- 403 => GmailError::Forbidden,
- 404 => GmailError::NotFound(error_body),
- 429 => GmailError::RateLimitExceeded,
- s if s >= 500 => GmailError::ServerError(s, error_body),
- _ => GmailError::ApiError(format!(
- "Gmail API error {} (modify message labels): {}",
- status, error_body
- )),
- });
+ if !response.status().is_success() {
+ return Err(unsuccessful_response(response).await);
}
Ok(())
}
+/// Fetches the user's raw Gmail labels.
#[tracing::instrument(skip(client, access_token), err)]
pub async fn fetch_user_labels(
client: &GmailClient,
access_token: &str,
- link_id: uuid::Uuid,
-) -> anyhow::Result<Vec<service::label::Label>> {
- let url = format!("{}/users/me/labels", client.base_url);
-
- let http_client = client.inner.clone();
-
- let response = http_client
- .get(&url)
+) -> Result<Vec<GmailLabel>, GmailApiHttpError> {
+ let response = client
+ .inner
+ .get(format!("{}/users/me/labels", client.base_url))
.bearer_auth(access_token)
.send()
.await
- .context("Failed to send request to Gmail API (fetch labels)")?;
+ .map_err(GmailApiHttpError::transport)?;
- let status = response.status();
- if !status.is_success() {
- let error_body = response
- .text()
- .await
- .unwrap_or_else(|_| "Failed to read error body".to_string());
- anyhow::bail!("Gmail API error {} (fetch labels): {}", status, error_body);
+ if !response.status().is_success() {
+ return Err(unsuccessful_response(response).await);
}
- let labels_response = response
- .json::<GmailLabelsResponse>()
- .await
- .context("Failed to parse JSON response from Gmail API (fetch labels)")?;
-
- // Convert Gmail API labels to service labels
- let service_labels = labels_response
- .to_service_labels(link_id)
- .map_err(|e| anyhow::anyhow!("Failed to convert Gmail labels to service labels: {}", e))?;
-
- Ok(service_labels)
+ let response = decode_json_response::<GmailLabelsResponse>(response).await?;
+ Ok(response.labels)
}
+/// Creates a Gmail label from the supplied wire request.
#[tracing::instrument(skip(client, access_token), err)]
pub async fn create_label(
client: &GmailClient,
access_token: &str,
- link_id: Uuid,
- label_name: &str,
-) -> Result<service::label::Label, GmailError> {
- let url = format!("{}/users/me/labels", client.base_url);
-
- let http_client = client.inner.clone();
-
- let request_label = models_email::gmail::labels::GmailLabel {
- id: None,
- name: label_name.to_string(),
- message_list_visibility: Some("show".to_string()),
- label_list_visibility: Some("labelShow".to_string()),
- type_: Some("user".to_string()),
- color: None,
- };
-
- let response = http_client
- .post(&url)
+ request: &GmailLabel,
+) -> Result<GmailLabel, GmailApiHttpError> {
+ let response = client
+ .inner
+ .post(format!("{}/users/me/labels", client.base_url))
.bearer_auth(access_token)
- .json(&request_label)
+ .json(request)
.send()
.await
- .map_err(|e| GmailError::HttpRequest(e.to_string()))?;
-
- let response = match response.error_for_status() {
- Ok(r) => r,
- Err(e) => {
- if e.status() == Some(reqwest::StatusCode::CONFLICT) {
- return Err(GmailError::Conflict("Label already exists".to_string()));
- }
- return Err(GmailError::ApiError(e.to_string()));
- }
- };
-
- let created_label = response
- .json::<models_email::gmail::labels::GmailLabel>()
- .await
- .map_err(|e| GmailError::BodyReadError(e.to_string()))?;
+ .map_err(GmailApiHttpError::transport)?;
- // Convert Gmail API label to service label
- let service_label = created_label
- .to_service_label(link_id)
- .map_err(|e| GmailError::BodyReadError(e.to_string()))?;
+ if !response.status().is_success() {
+ return Err(unsuccessful_response(response).await);
+ }
- Ok(service_label)
+ decode_json_response(response).await
}
-#[tracing::instrument(
- skip(client, access_token),
- fields(label_id = %label_id),
- err
-)]
+/// Deletes a Gmail label by provider ID.
+#[tracing::instrument(skip(client, access_token), fields(label_id = %label_id), err)]
pub async fn delete_gmail_label(
client: &GmailClient,
access_token: &str,
label_id: &str,
-) -> Result<(), GmailError> {
- let url = format!("{}/users/me/labels/{}", client.base_url, label_id);
-
- let http_client = client.inner.clone();
-
- let response = http_client
- .delete(&url)
+) -> Result<(), GmailApiHttpError> {
+ let response = client
+ .inner
+ .delete(format!("{}/users/me/labels/{label_id}", client.base_url))
.bearer_auth(access_token)
.send()
.await
- .map_err(|e| GmailError::HttpRequest(e.to_string()))?;
-
- match response.status() {
- status if status.is_success() => Ok(()),
- reqwest::StatusCode::NOT_FOUND => {
- tracing::warn!(
- label_id = %label_id,
- "Label not found in Gmail when attempting to delete"
- );
- Err(GmailError::NotFound(format!(
- "Label {} not found",
- label_id
- )))
- }
- status => {
- let error_body = response
- .text()
- .await
- .unwrap_or_else(|_| "Failed to read error body".to_string());
+ .map_err(GmailApiHttpError::transport)?;
- Err(GmailError::ApiError(format!(
- "Failed to delete label. Status: {}. Error: {}",
- status, error_body
- )))
- }
+ if !response.status().is_success() {
+ return Err(unsuccessful_response(response).await);
}
+
+ Ok(())
}
+
+#[cfg(test)]
+mod test;
diff --git a/crates/gmail_client/src/labels/test.rs b/crates/gmail_client/src/labels/test.rs
new file mode 100644
index 0000000000..c569ed255c
--- /dev/null
+++ b/crates/gmail_client/src/labels/test.rs
@@ -0,0 +1,109 @@
+use reqwest::StatusCode;
+use serde_json::json;
+use wiremock::matchers::{body_json, method, path};
+use wiremock::{Mock, MockServer, ResponseTemplate};
+
+use super::*;
+
+fn client(server: &MockServer) -> GmailClient {
+ GmailClient::new_with_urls(
+ String::new(),
+ server.uri(),
+ server.uri(),
+ server.uri(),
+ String::new(),
+ )
+}
+
+fn label(name: &str) -> GmailLabel {
+ GmailLabel {
+ id: None,
+ name: name.to_string(),
+ message_list_visibility: None,
+ label_list_visibility: None,
+ type_: None,
+ color: None,
+ }
+}
+
+#[tokio::test]
+async fn lists_raw_gmail_labels() {
+ let server = MockServer::start().await;
+ Mock::given(method("GET"))
+ .and(path("/users/me/labels"))
+ .respond_with(ResponseTemplate::new(200).set_body_json(json!({
+ "labels": [{"id": "label-1", "name": "Projects"}]
+ })))
+ .mount(&server)
+ .await;
+
+ let labels = fetch_user_labels(&client(&server), "token").await.unwrap();
+ assert_eq!(labels[0].id.as_deref(), Some("label-1"));
+ assert_eq!(labels[0].name, "Projects");
+}
+
+#[tokio::test]
+async fn creates_the_supplied_raw_label_without_adding_defaults() {
+ let server = MockServer::start().await;
+ let request = label("Projects");
+ Mock::given(method("POST"))
+ .and(path("/users/me/labels"))
+ .and(body_json(json!({
+ "id": null,
+ "name": "Projects",
+ "messageListVisibility": null,
+ "labelListVisibility": null,
+ "type": null,
+ "color": null
+ })))
+ .respond_with(ResponseTemplate::new(200).set_body_json(json!({
+ "id": "label-1", "name": "Projects"
+ })))
+ .mount(&server)
+ .await;
+
+ let created = create_label(&client(&server), "token", &request)
+ .await
+ .unwrap();
+ assert_eq!(created.id.as_deref(), Some("label-1"));
+}
+
+#[tokio::test]
+async fn delete_preserves_not_found_body() {
+ let server = MockServer::start().await;
+ Mock::given(method("DELETE"))
+ .and(path("/users/me/labels/missing"))
+ .respond_with(ResponseTemplate::new(404).set_body_string("missing [email protected]"))
+ .mount(&server)
+ .await;
+
+ let error = delete_gmail_label(&client(&server), "token", "missing")
+ .await
+ .unwrap_err();
+ assert_eq!(error.status(), Some(StatusCode::NOT_FOUND));
+ assert_eq!(error.body(), Some("missing [REDACTED_EMAIL]"));
+}
+
+#[tokio::test]
+async fn modifies_message_labels_with_the_wire_request() {
+ let server = MockServer::start().await;
+ Mock::given(method("POST"))
+ .and(path("/users/me/messages/message-1/modify"))
+ .and(body_json(json!({
+ "addLabelIds": ["STARRED"],
+ "removeLabelIds": ["UNREAD"]
+ })))
+ .respond_with(ResponseTemplate::new(200))
+ .mount(&server)
+ .await;
+
+ modify_message_labels(
+ &client(&server),
+ "token",
+ "message-1",
+ &["STARRED".to_string()],
+ &["UNREAD".to_string()],
+ )
+ .await
+ .unwrap();
+}
diff --git a/crates/gmail_client/src/lib.rs b/crates/gmail_client/src/lib.rs
index 062ba69e4d..2085bcd93c 100644
--- a/crates/gmail_client/src/lib.rs
+++ b/crates/gmail_client/src/lib.rs
@@ -1,6 +1,7 @@
pub(crate) mod attachments;
pub(crate) mod auth;
pub(crate) mod contacts;
+mod error;
pub(crate) mod filters;
pub(crate) mod history;
pub(crate) mod labels;
@@ -9,7 +10,9 @@ pub(crate) mod profile;
pub(crate) mod threads;
pub(crate) mod watch;
-use crate::labels::delete_gmail_label;
+#[cfg(test)]
+mod test;
+
use regex::Regex;
use std::sync::LazyLock;
@@ -23,30 +26,32 @@ pub(crate) fn sanitize_error_body(body: &str) -> String {
let redacted = EMAIL_REGEX.replace_all(body, "[REDACTED_EMAIL]");
let trimmed = redacted.trim();
if trimmed.len() <= MAX_ERROR_BODY_LEN {
- trimmed.to_string()
- } else {
- format!("{}… (truncated)", &trimmed[..MAX_ERROR_BODY_LEN])
+ return trimmed.to_string();
}
+
+ let truncate_at = trimmed
+ .char_indices()
+ .map(|(index, _)| index)
+ .take_while(|index| *index <= MAX_ERROR_BODY_LEN)
+ .last()
+ .unwrap_or(0);
+ format!("{}… (truncated)", &trimmed[..truncate_at])
}
use crate::auth::{fetch_google_public_keys, verify_google_jwt};
use crate::contacts::get_self_connection;
-use crate::messages::{get_message, get_message_label_ids, get_message_thread_id, list_messages};
+use crate::messages::{get_message, get_message_label_ids, list_messages};
use crate::threads::get_thread;
-#[allow(unused_imports)]
-use mockall::automock;
-use models_email::email::service;
-use models_email::email::service::address::ContactInfo;
-use models_email::email::service::message;
-use models_email::email::service::thread::ThreadList as ServiceThreadList;
+pub use error::GmailApiHttpError;
use models_email::gmail::contacts::PersonResource;
-pub use models_email::gmail::error::GmailError;
pub use models_email::gmail::filters::Filter;
use models_email::gmail::inbox_sync::{
GoogleJwtClaims, GooglePublicKeys, JwtVerificationError, KeyMap,
};
-use models_email::gmail::{HistoryListResponse, MessageResource, ThreadResource};
-use uuid::Uuid;
+use models_email::gmail::labels::GmailLabel;
+use models_email::gmail::{
+ GmailUserProfile, HistoryListResponse, ListThreadsResponse, MessageResource, ThreadResource,
+};
#[derive(Clone, Debug)]
pub struct GmailClient {
@@ -66,12 +71,33 @@ pub struct GmailClient {
impl GmailClient {
pub fn new(subscription_topic: String) -> Self {
+ Self::new_with_urls(
+ subscription_topic,
+ "https://www.googleapis.com/gmail/v1".to_string(),
+ "https://people.googleapis.com/v1".to_string(),
+ "https://www.googleapis.com/oauth2/v3/certs".to_string(),
+ "macro-gmail-webhook".to_string(),
+ )
+ }
+
+ /// Creates a client with injectable Gmail, People, and JWKS URLs.
+ ///
+ /// This constructor supports deterministic tests and Gmail-compatible
+ /// endpoints. HTTP transport details and endpoint values remain private to
+ /// this crate.
+ pub fn new_with_urls(
+ subscription_topic: String,
+ gmail_url: String,
+ people_url: String,
+ jwks_url: String,
+ audience: String,
+ ) -> Self {
Self {
inner: reqwest::Client::new(),
- base_url: String::from("https://www.googleapis.com/gmail/v1"),
- certs_url: String::from("https://www.googleapis.com/oauth2/v3/certs"),
- contacts_url: String::from("https://people.googleapis.com/v1"),
- audience: "macro-gmail-webhook".to_string(),
+ base_url: gmail_url.trim_end_matches('/').to_string(),
+ certs_url: jwks_url,
+ contacts_url: people_url.trim_end_matches('/').to_string(),
+ audience,
subscription_topic,
}
}
@@ -86,7 +112,7 @@ impl GmailClient {
num_threads: u32,
next_page_token: Option<&str>,
label_ids: &[&str],
- ) -> anyhow::Result<ServiceThreadList> {
+ ) -> Result<ListThreadsResponse, GmailApiHttpError> {
threads::list_threads(self, access_token, num_threads, next_page_token, label_ids).await
}
@@ -99,7 +125,7 @@ impl GmailClient {
access_token: &str,
num_messages: u32,
label_ids: &[&str],
- ) -> anyhow::Result<Vec<String>> {
+ ) -> Result<Vec<String>, GmailApiHttpError> {
list_messages(self, access_token, num_messages, label_ids).await
}
@@ -109,7 +135,7 @@ impl GmailClient {
&self,
access_token: &str,
thread_id: &str,
- ) -> anyhow::Result<Vec<String>> {
+ ) -> Result<Vec<String>, GmailApiHttpError> {
threads::get_message_ids_for_thread(self, access_token, thread_id).await
}
@@ -120,7 +146,7 @@ impl GmailClient {
&self,
access_token: &str,
thread_id: &str,
- ) -> anyhow::Result<ThreadResource> {
+ ) -> Result<ThreadResource, GmailApiHttpError> {
get_thread(self, access_token, thread_id).await
}
@@ -131,19 +157,22 @@ impl GmailClient {
&self,
access_token: &str,
start_history_id: &str,
- ) -> anyhow::Result<HistoryListResponse> {
+ ) -> Result<HistoryListResponse, GmailApiHttpError> {
history::get_history(self, access_token, start_history_id).await
}
- /// Returns the current history id for the user's inbox
+ /// Fetches the user's raw Gmail profile.
#[tracing::instrument(skip(self, access_token), err)]
- pub async fn get_current_history_id(&self, access_token: &str) -> anyhow::Result<String> {
- history::get_current_history_id(self, access_token).await
+ pub async fn get_profile(
+ &self,
+ access_token: &str,
+ ) -> Result<GmailUserProfile, GmailApiHttpError> {
+ profile::get_profile(self, access_token).await
}
- /// Fetches Google's public JWKS keys used for verifying OAuth 2.0 tokens
+ /// Fetches Google's public JWKS keys used for verifying OAuth 2.0 tokens.
#[tracing::instrument(skip(self), err)]
- pub async fn get_google_public_keys(&self) -> anyhow::Result<GooglePublicKeys> {
+ pub async fn get_google_public_keys(&self) -> Result<GooglePublicKeys, GmailApiHttpError> {
fetch_google_public_keys(self).await
}
@@ -164,13 +193,13 @@ impl GmailClient {
pub async fn register_watch(
&self,
access_token: &str,
- ) -> Result<models_email::gmail::history::WatchResponse, GmailError> {
+ ) -> Result<models_email::gmail::history::WatchResponse, GmailApiHttpError> {
watch::register_watch(self, access_token).await
}
/// Stops push notifications by revoking the notification watch
#[tracing::instrument(skip(self, access_token), err)]
- pub async fn stop_watch(&self, access_token: &str) -> anyhow::Result<()> {
+ pub async fn stop_watch(&self, access_token: &str) -> Result<(), GmailApiHttpError> {
watch::stop_watch(self, access_token).await
}
@@ -186,7 +215,7 @@ impl GmailClient {
provider_message_id: &str,
label_ids_to_add: &[String],
label_ids_to_remove: &[String],
- ) -> Result<(), GmailError> {
+ ) -> Result<(), GmailApiHttpError> {
labels::modify_message_labels(
self,
access_token,
@@ -197,8 +226,6 @@ impl GmailClient {
.await
}
- // Batch adds and removes Gmail labels from multiple messages
- /// Returns a tuple of (successful_message_ids, failed_message_ids)
/// Fetches a specific message from Gmail by its provider ID.
/// Returns raw Gmail MessageResource - callers should map to service layer structs.
#[tracing::instrument(skip(self, access_token), err)]
@@ -206,53 +233,28 @@ impl GmailClient {
&self,
access_token: &str,
message_provider_id: &str,
- ) -> anyhow::Result<Option<MessageResource>> {
+ ) -> Result<Option<MessageResource>, GmailApiHttpError> {
get_message(self, access_token, message_provider_id).await
}
- /// Fetches a specific message's thread ID from Gmail by its provider ID
- #[tracing::instrument(skip(self, access_token), err)]
- pub async fn get_message_thread_id(
- &self,
- access_token: &str,
- message_provider_id: &str,
- ) -> anyhow::Result<Option<String>> {
- get_message_thread_id(self, access_token, message_provider_id).await
- }
-
#[tracing::instrument(skip(self, access_token), err)]
pub async fn get_message_label_ids(
&self,
access_token: &str,
message_provider_id: &str,
- ) -> anyhow::Result<Option<Vec<String>>> {
+ ) -> Result<Option<Vec<String>>, GmailApiHttpError> {
get_message_label_ids(self, access_token, message_provider_id).await
}
- /// Sends a new email message
- #[tracing::instrument(skip(self, access_token, message), err)]
+ /// Sends prepared MIME bytes and returns Gmail's provider identifiers.
+ #[tracing::instrument(skip(self, access_token, mime), err)]
pub async fn send_message(
&self,
access_token: &str,
- message: &mut message::MessageToSend,
- from_contact: &ContactInfo,
- parent_message_id: Option<String>,
- references: Option<Vec<String>>,
- ) -> anyhow::Result<()> {
- messages::send_message(
- self,
- access_token,
- message,
- from_contact,
- parent_message_id,
- references,
- )
- .await
- }
-
- #[tracing::instrument(skip(self, access_token), err)]
- pub async fn get_profile_threads_total(&self, access_token: &str) -> anyhow::Result<i32> {
- profile::get_profile_threads_total(self, access_token).await
+ mime: &[u8],
+ thread_id: Option<&str>,
+ ) -> Result<models_email::gmail::SentMessageResource, GmailApiHttpError> {
+ messages::send_message(self, access_token, mime, thread_id).await
}
/// Fetches an attachment from Gmail by its provider ID
@@ -262,7 +264,7 @@ impl GmailClient {
access_token: &str,
message_id: &str,
attachment_id: &str,
- ) -> anyhow::Result<Vec<u8>> {
+ ) -> Result<Vec<u8>, GmailApiHttpError> {
attachments::get_attachment_data(self, access_token, message_id, attachment_id).await
}
@@ -271,32 +273,37 @@ impl GmailClient {
pub async fn fetch_user_labels(
&self,
access_token: &str,
- link_id: uuid::Uuid,
- ) -> anyhow::Result<Vec<service::label::Label>> {
- labels::fetch_user_labels(self, access_token, link_id).await
+ ) -> Result<Vec<GmailLabel>, GmailApiHttpError> {
+ labels::fetch_user_labels(self, access_token).await
}
- /// Creates a new Gmail label for the user
+ /// Creates a new Gmail label from a raw Gmail label request.
#[tracing::instrument(skip(self, access_token), err)]
pub async fn create_label(
&self,
access_token: &str,
- link_id: Uuid,
- label_name: &str,
- ) -> Result<service::label::Label, GmailError> {
- labels::create_label(self, access_token, link_id, label_name).await
+ request: &GmailLabel,
+ ) -> Result<GmailLabel, GmailApiHttpError> {
+ labels::create_label(self, access_token, request).await
}
- /// Deletes a Gmail label by its ID
+ /// Deletes a Gmail label by its ID.
#[tracing::instrument(skip(self, access_token), err)]
- pub async fn delete_label(&self, access_token: &str, label_id: &str) -> Result<(), GmailError> {
- delete_gmail_label(self, access_token, label_id).await
+ pub async fn delete_label(
+ &self,
+ access_token: &str,
+ label_id: &str,
+ ) -> Result<(), GmailApiHttpError> {
+ labels::delete_gmail_label(self, access_token, label_id).await
}
/// Fetches the user's own contact information.
/// Returns raw Gmail PersonResource - callers should map to service layer Contact.
#[tracing::instrument(skip(self, access_token), err)]
- pub async fn get_self_contact(&self, access_token: &str) -> anyhow::Result<PersonResource> {
+ pub async fn get_self_contact(
+ &self,
+ access_token: &str,
+ ) -> Result<PersonResource, GmailApiHttpError> {
get_self_connection(self, access_token).await
}
@@ -308,7 +315,7 @@ impl GmailClient {
&self,
access_token: &str,
sync_token: Option<&str>,
- ) -> anyhow::Result<(Vec<PersonResource>, String)> {
+ ) -> Result<(Vec<PersonResource>, String), GmailApiHttpError> {
contacts::list_connections(self, access_token, sync_token).await
}
@@ -321,86 +328,33 @@ impl GmailClient {
&self,
access_token: &str,
sync_token: Option<&str>,
- ) -> anyhow::Result<(Vec<PersonResource>, String)> {
+ ) -> Result<(Vec<PersonResource>, String), GmailApiHttpError> {
contacts::list_other_contacts(self, access_token, sync_token).await
}
- /// Blocks a sender by creating a filter that sends their emails to SPAM.
- /// This replicates the "Block Sender" functionality in the Gmail UI.
- #[tracing::instrument(skip(self, access_token), err)]
- pub async fn block_sender(
- &self,
- access_token: &str,
- email_to_block: &str,
- ) -> Result<Filter, GmailError> {
- filters::block_sender(self, access_token, email_to_block).await
- }
-
/// Creates a new Gmail filter.
#[tracing::instrument(skip(self, access_token), err)]
pub async fn create_filter(
&self,
access_token: &str,
filter: Filter,
- ) -> Result<Filter, GmailError> {
+ ) -> Result<Filter, GmailApiHttpError> {
filters::create_filter(self, access_token, filter).await
}
/// Lists all filters for the user.
#[tracing::instrument(skip(self, access_token), err)]
- pub async fn list_filters(&self, access_token: &str) -> Result<Vec<Filter>, GmailError> {
+ pub async fn list_filters(&self, access_token: &str) -> Result<Vec<Filter>, GmailApiHttpError> {
filters::list_filters(self, access_token).await
}
- /// Gets a specific filter by ID.
- #[tracing::instrument(skip(self, access_token), err)]
- pub async fn get_filter(
- &self,
- access_token: &str,
- filter_id: &str,
- ) -> Result<Filter, GmailError> {
- filters::get_filter(self, access_token, filter_id).await
- }
-
/// Deletes a filter by ID.
#[tracing::instrument(skip(self, access_token), err)]
pub async fn delete_filter(
&self,
access_token: &str,
filter_id: &str,
- ) -> Result<(), GmailError> {
+ ) -> Result<(), GmailApiHttpError> {
filters::delete_filter(self, access_token, filter_id).await
}
-
- /// Finds and returns any existing "block" filters for a specific email address.
- /// This can be used to check if a user is already blocked.
- #[tracing::instrument(skip(self, access_token), err)]
- pub async fn find_block_filter_for_sender(
- &self,
- access_token: &str,
- email_address: &str,
- ) -> Result<Option<Filter>, GmailError> {
- filters::find_block_filter_for_sender(self, access_token, email_address).await
- }
-
- /// Unblocks a sender by finding and deleting their block filter.
- /// Returns true if a filter was found and deleted, false if no filter existed.
- #[tracing::instrument(skip(self, access_token), err)]
- pub async fn unblock_sender(
- &self,
- access_token: &str,
- email_address: &str,
- ) -> Result<bool, GmailError> {
- filters::unblock_sender(self, access_token, email_address).await
- }
-
- /// Lists all blocked senders by finding filters that send emails to TRASH.
- /// Returns a list of email addresses that are currently blocked.
- #[tracing::instrument(skip(self, access_token), err)]
- pub async fn list_blocked_senders(
- &self,
- access_token: &str,
- ) -> Result<Vec<String>, GmailError> {
- filters::list_blocked_senders(self, access_token).await
- }
}
diff --git a/crates/gmail_client/src/messages.rs b/crates/gmail_client/src/messages.rs
index d3dda633ea..481b45b2e1 100644
--- a/crates/gmail_client/src/messages.rs
+++ b/crates/gmail_client/src/messages.rs
@@ -1,15 +1,17 @@
-use crate::{GmailClient, sanitize_error_body};
-use anyhow::Context;
+use std::cmp::min;
+
use base64::Engine;
use base64::engine::general_purpose::URL_SAFE_NO_PAD;
-use mail_builder::headers::address::Address;
-use models_email::email::service::address::ContactInfo;
-use models_email::email::service::message;
use models_email::gmail::{
ListMessagesResponse, MessageResource, MinimalMessageResource, SendMessagePayload,
SentMessageResource,
};
-use std::cmp::min;
+
+use crate::error::{decode_json_response, unsuccessful_response};
+use crate::{GmailApiHttpError, GmailClient};
+
+#[cfg(test)]
+mod test;
// 500 is the max allowed by the gmail api
pub const LIST_MESSAGES_BATCH_SIZE: u32 = 500;
@@ -23,55 +25,39 @@ pub(crate) async fn list_messages(
access_token: &str,
num_messages: u32,
label_ids: &[&str],
-) -> anyhow::Result<Vec<String>> {
+) -> Result<Vec<String>, GmailApiHttpError> {
if num_messages == 0 {
return Ok(Vec::new());
}
- // The Gmail API's `maxResults` parameter is capped at 500.
let batch_size = min(num_messages, LIST_MESSAGES_BATCH_SIZE);
-
- let http_client = client.inner.clone();
let url = format!("{}/users/me/messages", client.base_url);
-
let mut query_params = vec![("maxResults", batch_size.to_string())];
- // `labelIds` is a repeatable param; a message matches if it carries all of them.
for label_id in label_ids {
query_params.push(("labelIds", label_id.to_string()));
}
- let response = http_client
- .get(&url)
+ let response = client
+ .inner
+ .get(url)
.bearer_auth(access_token)
.query(&query_params)
.send()
.await
- .context("Failed to send request to Gmail API (list messages)")?;
+ .map_err(GmailApiHttpError::transport)?;
- let status = response.status();
- if !status.is_success() {
- let error_body = response
- .text()
- .await
- .unwrap_or_else(|_| "Failed to read error body".to_string());
- let sanitized = sanitize_error_body(&error_body);
- anyhow::bail!("Gmail API error {} (list messages): {}", status, sanitized);
+ if !response.status().is_success() {
+ return Err(unsuccessful_response(response).await);
}
- let gmail_response = response
- .json::<ListMessagesResponse>()
- .await
- .context("Failed to parse JSON response from Gmail API (list messages)")?;
-
- let message_ids = gmail_response
+ let gmail_response: ListMessagesResponse = decode_json_response(response).await?;
+ Ok(gmail_response
.messages
.unwrap_or_default()
.into_iter()
- .map(|m| m.id)
- .collect();
-
- Ok(message_ids)
+ .map(|message| message.id)
+ .collect())
}
#[tracing::instrument(skip(client, access_token), err)]
@@ -79,259 +65,86 @@ pub(crate) async fn get_message(
client: &GmailClient,
access_token: &str,
message_provider_id: &str,
-) -> anyhow::Result<Option<MessageResource>> {
+) -> Result<Option<MessageResource>, GmailApiHttpError> {
let url = format!(
"{}/users/me/messages/{}",
client.base_url, message_provider_id
);
-
- let http_client = client.inner.clone();
-
- let response = http_client
- .get(&url)
- .bearer_auth(access_token)
- .send()
- .await
- .with_context(|| {
- format!(
- "Failed to send request to Gmail API (get message) for message_provider_id: {}",
- message_provider_id
- )
- })?;
-
- if response.status() == reqwest::StatusCode::NOT_FOUND {
- return Ok(None);
- }
-
- let status = response.status();
- if !status.is_success() {
- let error_body = response
- .text()
- .await
- .unwrap_or_else(|_| "Failed to read error body".to_string());
- anyhow::bail!(
- "Gmail API error {} (get message) for message_provider_id: {}: {}",
- status,
- message_provider_id,
- error_body
- );
- }
-
- let message_response = response
- .json::<MessageResource>()
- .await
- .with_context(|| format!("Failed to parse JSON response from Gmail API (get message) for message_provider_id: {}",
- message_provider_id))?;
-
- Ok(Some(message_response))
-}
-
-// gets a message without the body using ?format=minimal in the gmail api call
-#[tracing::instrument(skip(client, access_token), err)]
-pub(crate) async fn get_message_thread_id(
- client: &GmailClient,
- access_token: &str,
- message_provider_id: &str,
-) -> anyhow::Result<Option<String>> {
- let url = format!(
- "{}/users/me/messages/{}?format=minimal",
- client.base_url, message_provider_id
- );
-
- let http_client = client.inner.clone();
-
- let response = http_client
- .get(&url)
+ let response = client
+ .inner
+ .get(url)
.bearer_auth(access_token)
.send()
.await
- .with_context(|| {
- format!(
- "Failed to send request to Gmail API (get message) for message_provider_id: {}",
- message_provider_id
- )
- })?;
+ .map_err(GmailApiHttpError::transport)?;
if response.status() == reqwest::StatusCode::NOT_FOUND {
return Ok(None);
}
-
- let status = response.status();
- if !status.is_success() {
- let error_body = response
- .text()
- .await
- .unwrap_or_else(|_| "Failed to read error body".to_string());
- anyhow::bail!(
- "Gmail API error {} (get message thread_id) for message_provider_id: {}: {}",
- status,
- message_provider_id,
- error_body
- );
+ if !response.status().is_success() {
+ return Err(unsuccessful_response(response).await);
}
- let message_response = response
- .json::<MinimalMessageResource>()
- .await
- .with_context(|| format!("Failed to parse JSON response from Gmail API (get message) for message_provider_id: {}", message_provider_id))?;
-
- Ok(Some(message_response.thread_id))
+ decode_json_response(response).await.map(Some)
}
-// gets a message without the body using ?format=minimal in the gmail api call
+// Gets a message without the body using `format=minimal`.
#[tracing::instrument(skip(client, access_token), err)]
pub(crate) async fn get_message_label_ids(
client: &GmailClient,
access_token: &str,
message_provider_id: &str,
-) -> anyhow::Result<Option<Vec<String>>> {
+) -> Result<Option<Vec<String>>, GmailApiHttpError> {
let url = format!(
- "{}/users/me/messages/{}?format=minimal",
+ "{}/users/me/messages/{}",
client.base_url, message_provider_id
);
-
- let http_client = client.inner.clone();
-
- let response = http_client
- .get(&url)
+ let response = client
+ .inner
+ .get(url)
.bearer_auth(access_token)
+ .query(&[("format", "minimal")])
.send()
.await
- .with_context(|| {
- format!(
- "Failed to send request to Gmail API (get message) for message_provider_id: {}",
- message_provider_id
- )
- })?;
+ .map_err(GmailApiHttpError::transport)?;
if response.status() == reqwest::StatusCode::NOT_FOUND {
return Ok(None);
}
-
- let status = response.status();
- if !status.is_success() {
- let error_body = response
- .text()
- .await
- .unwrap_or_else(|_| "Failed to read error body".to_string());
- anyhow::bail!(
- "Gmail API error {} (get message label_ids) for message_provider_id: {}: {}",
- status,
- message_provider_id,
- error_body
- );
+ if !response.status().is_success() {
+ return Err(unsuccessful_response(response).await);
}
- let message_response = response
- .json::<MinimalMessageResource>()
- .await
- .with_context(|| format!("Failed to parse JSON response from Gmail API (get message) for message_provider_id: {}", message_provider_id))?;
-
- Ok(Some(message_response.label_ids))
+ let message: MinimalMessageResource = decode_json_response(response).await?;
+ Ok(Some(message.label_ids))
}
-/// sends a message
-#[tracing::instrument(skip(client, access_token, message), fields(link_id=%message.link_id), err)]
+/// Sends prepared MIME bytes through the Gmail API.
+#[tracing::instrument(skip(client, access_token, mime), err)]
pub(crate) async fn send_message(
client: &GmailClient,
access_token: &str,
- message: &mut message::MessageToSend,
- from_contact: &ContactInfo,
- parent_message_id: Option<String>,
- references: Option<Vec<String>>,
-) -> anyhow::Result<()> {
+ mime: &[u8],
+ thread_id: Option<&str>,
+) -> Result<SentMessageResource, GmailApiHttpError> {
let url = format!("{}/users/me/messages/send", client.base_url);
-
- let mut builder = mail_builder::MessageBuilder::new()
- .from(contact_to_address(from_contact))
- .to(contacts_to_address_list(&message.to))
- .cc(contacts_to_address_list(&message.cc))
- .bcc(contacts_to_address_list(&message.bcc))
- .subject(&message.subject);
-
- // Set threading headers, if existing
- if let Some(parent_message_id) = parent_message_id {
- builder = builder.in_reply_to(parent_message_id);
- }
-
- if let Some(references) = references {
- builder = builder.references(references);
- }
-
- if let Some(text_body) = &message.body_text {
- builder = builder.text_body(text_body);
- }
-
- if let Some(html_body) = &message.body_html {
- builder = builder.html_body(html_body);
- }
-
- if let Some(attachments) = message.attachments.take() {
- for att in attachments {
- builder = builder.attachment(att.content_type, att.file_name, att.data);
- }
- }
-
- let email_bytes = builder.write_to_vec().context("building message error")?;
-
- let base64_email_content = URL_SAFE_NO_PAD.encode(email_bytes);
-
let payload = SendMessagePayload {
- raw: base64_email_content,
- thread_id: message.provider_thread_id.clone(),
+ raw: URL_SAFE_NO_PAD.encode(mime),
+ thread_id: thread_id.map(str::to_owned),
};
- let http_client = client.inner.clone();
-
- let response = http_client
- .post(&url)
+ let response = client
+ .inner
+ .post(url)
.bearer_auth(access_token)
.json(&payload)
.send()
.await
- .with_context(|| {
- format!(
- "Failed to send request to Gmail API (send message) for link_id: {}",
- message.link_id
- )
- })?;
+ .map_err(GmailApiHttpError::transport)?;
- let status = response.status();
- let body_text = response
- .text()
- .await
- .context("Failed to get response body")?;
- if !status.is_success() {
- anyhow::bail!(
- "Gmail API returned an error status: {} (send message): {}",
- status,
- body_text
- );
+ if !response.status().is_success() {
+ return Err(unsuccessful_response(response).await);
}
- let message_response: SentMessageResource = serde_json::from_str(&body_text)
- .context("Failed to parse JSON response from Gmail API (get attachment)")?;
-
- message.provider_id = Some(message_response.id);
- message.provider_thread_id = Some(message_response.thread_id);
-
- Ok(())
-}
-
-fn contact_to_address(contact: &ContactInfo) -> Address<'_> {
- match &contact.name {
- Some(name) => Address::new_address(Some(name.as_str()), contact.email.as_str()),
- None => Address::new_address(None::<&str>, contact.email.as_str()),
- }
-}
-
-fn contacts_to_address_list(contacts: &Option<Vec<ContactInfo>>) -> Address<'_> {
- let contacts = contacts.as_ref();
- if contacts.is_none_or(|c| c.is_empty()) {
- return Address::new_list(Vec::new());
- }
-
- let addresses: Vec<Address> = contacts.unwrap().iter().map(contact_to_address).collect();
-
- Address::new_list(addresses)
+ decode_json_response(response).await
}
diff --git a/crates/gmail_client/src/messages/test.rs b/crates/gmail_client/src/messages/test.rs
new file mode 100644
index 0000000000..af16d00b59
--- /dev/null
+++ b/crates/gmail_client/src/messages/test.rs
@@ -0,0 +1,210 @@
+use base64::Engine;
+use base64::engine::general_purpose::URL_SAFE_NO_PAD;
+use reqwest::StatusCode;
+use wiremock::matchers::{body_json, header, method, path, query_param};
+use wiremock::{Mock, MockServer, ResponseTemplate};
+
+use super::*;
+
+fn client(server: &MockServer) -> GmailClient {
+ GmailClient::new_with_urls(
+ String::new(),
+ server.uri(),
+ server.uri(),
+ server.uri(),
+ String::new(),
+ )
+}
+
+#[tokio::test]
+async fn list_messages_uses_path_repeated_labels_and_limit() {
+ let server = MockServer::start().await;
+ Mock::given(method("GET"))
+ .and(path("/users/me/messages"))
+ .and(query_param("maxResults", "500"))
+ .and(query_param("labelIds", "INBOX"))
+ .and(query_param("labelIds", "IMPORTANT"))
+ .respond_with(ResponseTemplate::new(200).set_body_json(serde_json::json!({
+ "messages": [{ "id": "message-1" }, { "id": "message-2" }]
+ })))
+ .expect(1)
+ .mount(&server)
+ .await;
+
+ let ids = list_messages(&client(&server), "token", 900, &["INBOX", "IMPORTANT"])
+ .await
+ .expect("message list should decode");
+
+ assert_eq!(ids, ["message-1", "message-2"]);
+}
+
+#[tokio::test]
+async fn zero_message_limit_does_not_make_a_request() {
+ let server = MockServer::start().await;
+ let ids = list_messages(&client(&server), "token", 0, &[])
+ .await
+ .expect("zero limit should succeed");
+
+ assert!(ids.is_empty());
+ assert!(server.received_requests().await.unwrap().is_empty());
+}
+
+#[tokio::test]
+async fn get_message_maps_not_found_to_none() {
+ let server = MockServer::start().await;
+ Mock::given(method("GET"))
+ .and(path("/users/me/messages/missing"))
+ .respond_with(ResponseTemplate::new(StatusCode::NOT_FOUND.as_u16()))
+ .mount(&server)
+ .await;
+
+ let message = get_message(&client(&server), "token", "missing")
+ .await
+ .expect("404 should not be an error");
+ assert!(message.is_none());
+}
+
+#[tokio::test]
+async fn get_message_label_ids_requests_minimal_format() {
+ let server = MockServer::start().await;
+ Mock::given(method("GET"))
+ .and(path("/users/me/messages/message-1"))
+ .and(query_param("format", "minimal"))
+ .respond_with(ResponseTemplate::new(200).set_body_json(serde_json::json!({
+ "id": "message-1",
+ "threadId": "thread-1",
+ "labelIds": ["INBOX", "UNREAD"]
+ })))
+ .mount(&server)
+ .await;
+
+ let labels = get_message_label_ids(&client(&server), "token", "message-1")
+ .await
+ .expect("minimal message should decode");
+ assert_eq!(labels.unwrap(), ["INBOX", "UNREAD"]);
+}
+
+#[tokio::test]
+async fn message_errors_are_typed_and_sanitized() {
+ let server = MockServer::start().await;
+ Mock::given(method("GET"))
+ .and(path("/users/me/messages"))
+ .respond_with(
+ ResponseTemplate::new(StatusCode::INTERNAL_SERVER_ERROR.as_u16())
+ .set_body_string("failure for [email protected]"),
+ )
+ .mount(&server)
+ .await;
+
+ let error = list_messages(&client(&server), "token", 1, &[])
+ .await
+ .expect_err("error status should fail");
+ assert_eq!(error.status(), Some(StatusCode::INTERNAL_SERVER_ERROR));
+ assert_eq!(error.body(), Some("failure for [REDACTED_EMAIL]"));
+}
+
+#[tokio::test]
+async fn send_message_posts_unpadded_base64url_mime_and_returns_provider_ids() {
+ let server = MockServer::start().await;
+ let mime = b"From: [email protected]\r\n\r\nbody with ? and /";
+ let encoded_mime = URL_SAFE_NO_PAD.encode(mime);
+ assert!(!encoded_mime.contains('='));
+
+ Mock::given(method("POST"))
+ .and(path("/users/me/messages/send"))
+ .and(header("authorization", "Bearer token"))
+ .and(body_json(serde_json::json!({
+ "raw": encoded_mime,
+ "threadId": "thread-existing"
+ })))
+ .respond_with(ResponseTemplate::new(200).set_body_json(serde_json::json!({
+ "id": "message-sent",
+ "threadId": "thread-sent"
+ })))
+ .expect(1)
+ .mount(&server)
+ .await;
+
+ let sent = send_message(&client(&server), "token", mime, Some("thread-existing"))
+ .await
+ .expect("message should send");
+
+ assert_eq!(sent.id, "message-sent");
+ assert_eq!(sent.thread_id, "thread-sent");
+}
+
+#[tokio::test]
+async fn send_message_omits_absent_thread_id() {
+ let server = MockServer::start().await;
+ Mock::given(method("POST"))
+ .and(path("/users/me/messages/send"))
+ .and(body_json(serde_json::json!({
+ "raw": URL_SAFE_NO_PAD.encode(b"mime")
+ })))
+ .respond_with(ResponseTemplate::new(200).set_body_json(serde_json::json!({
+ "id": "message-sent",
+ "threadId": "thread-new"
+ })))
+ .expect(1)
+ .mount(&server)
+ .await;
+
+ send_message(&client(&server), "token", b"mime", None)
+ .await
+ .expect("message should send without a thread id");
+}
+
+#[tokio::test]
+async fn send_message_classifies_http_errors() {
+ let server = MockServer::start().await;
+ Mock::given(method("POST"))
+ .and(path("/users/me/messages/send"))
+ .respond_with(
+ ResponseTemplate::new(StatusCode::TOO_MANY_REQUESTS.as_u16())
+ .insert_header("Retry-After", "17")
+ .set_body_string("quota exceeded for [email protected]"),
+ )
+ .mount(&server)
+ .await;
+
+ let error = send_message(&client(&server), "token", b"mime", None)
+ .await
+ .expect_err("error status should fail");
+
+ assert_eq!(error.status(), Some(StatusCode::TOO_MANY_REQUESTS));
+ assert_eq!(error.body(), Some("quota exceeded for [REDACTED_EMAIL]"));
+ assert_eq!(
+ error.retry_after(),
+ Some(std::time::Duration::from_secs(17))
+ );
+}
+
+#[tokio::test]
+async fn malformed_send_response_is_a_decode_error() {
+ let server = MockServer::start().await;
+ Mock::given(method("POST"))
+ .and(path("/users/me/messages/send"))
+ .respond_with(ResponseTemplate::new(200).set_body_string("not-json"))
+ .mount(&server)
+ .await;
+
+ let error = send_message(&client(&server), "token", b"mime", None)
+ .await
+ .expect_err("malformed JSON should fail");
+ assert!(matches!(error, GmailApiHttpError::Decode(_)));
+}
+
+#[tokio::test]
+async fn malformed_message_json_is_a_decode_error() {
+ let server = MockServer::start().await;
+ Mock::given(method("GET"))
+ .and(path("/users/me/messages"))
+ .respond_with(ResponseTemplate::new(200).set_body_string("not-json"))
+ .mount(&server)
+ .await;
+
+ let error = list_messages(&client(&server), "token", 1, &[])
+ .await
+ .expect_err("malformed JSON should fail");
+ assert!(matches!(error, GmailApiHttpError::Decode(_)));
+}
diff --git a/crates/gmail_client/src/profile.rs b/crates/gmail_client/src/profile.rs
index 20629e8c10..a6a977e58d 100644
--- a/crates/gmail_client/src/profile.rs
+++ b/crates/gmail_client/src/profile.rs
@@ -1,40 +1,26 @@
-use crate::GmailClient;
-use anyhow::Context;
+use crate::error::{decode_json_response, unsuccessful_response};
+use crate::{GmailApiHttpError, GmailClient};
use models_email::gmail::GmailUserProfile;
#[tracing::instrument(skip(client, access_token), err)]
-pub async fn get_profile_threads_total(
+pub(crate) async fn get_profile(
client: &GmailClient,
access_token: &str,
-) -> anyhow::Result<i32> {
- let url = format!("{}/users/me/profile", client.base_url);
- let http_client = client.inner.clone();
-
- let response = http_client
- .get(&url)
+) -> Result<GmailUserProfile, GmailApiHttpError> {
+ let response = client
+ .inner
+ .get(format!("{}/users/me/profile", client.base_url))
.bearer_auth(access_token)
.send()
.await
- .context("Failed to send request to Gmail API (get user profile)")?;
+ .map_err(GmailApiHttpError::transport)?;
- let status = response.status();
- if !status.is_success() {
- let error_body = response
- .text()
- .await
- .unwrap_or_else(|_| "Failed to read error body".to_string());
- anyhow::bail!(
- "Gmail API error {} (get user profile): {}",
- status,
- error_body
- );
+ if !response.status().is_success() {
+ return Err(unsuccessful_response(response).await);
}
- // Parse the response directly into our GmailUserProfile structure
- let user_profile = response
- .json::<GmailUserProfile>()
- .await
- .context("Failed to parse Gmail API response into user profile")?;
-
- Ok(user_profile.threads_total)
+ decode_json_response(response).await
}
+
+#[cfg(test)]
+mod test;
diff --git a/crates/gmail_client/src/profile/test.rs b/crates/gmail_client/src/profile/test.rs
new file mode 100644
index 0000000000..14a75e0d5d
--- /dev/null
+++ b/crates/gmail_client/src/profile/test.rs
@@ -0,0 +1,38 @@
+use wiremock::matchers::{method, path};
+use wiremock::{Mock, MockServer, ResponseTemplate};
+
+use super::*;
+
+fn client(server: &MockServer) -> GmailClient {
+ GmailClient::new_with_urls(
+ String::new(),
+ server.uri(),
+ server.uri(),
+ server.uri(),
+ String::new(),
+ )
+}
+
+#[tokio::test]
+async fn profile_decodes_the_complete_wire_response() {
+ let server = MockServer::start().await;
+ Mock::given(method("GET"))
+ .and(path("/users/me/profile"))
+ .respond_with(ResponseTemplate::new(200).set_body_json(serde_json::json!({
+ "emailAddress": "[email protected]",
+ "messagesTotal": 42,
+ "threadsTotal": 21,
+ "historyId": "1234"
+ })))
+ .mount(&server)
+ .await;
+
+ let profile = get_profile(&client(&server), "token")
+ .await
+ .expect("profile should decode");
+
+ assert_eq!(profile.email_address, "[email protected]");
+ assert_eq!(profile.messages_total, 42);
+ assert_eq!(profile.threads_total, 21);
+ assert_eq!(profile.history_id, "1234");
+}
diff --git a/crates/gmail_client/src/test.rs b/crates/gmail_client/src/test.rs
new file mode 100644
index 0000000000..7f6c258ebd
--- /dev/null
+++ b/crates/gmail_client/src/test.rs
@@ -0,0 +1,38 @@
+use wiremock::matchers::{header, method, path, query_param};
+use wiremock::{Mock, MockServer, ResponseTemplate};
+
+use super::*;
+
+#[tokio::test]
+async fn injectable_urls_route_requests_to_the_configured_endpoint() {
+ let server = MockServer::start().await;
+ Mock::given(method("GET"))
+ .and(path("/gmail/users/me/messages"))
+ .and(header("authorization", "Bearer test-token"))
+ .and(query_param("maxResults", "1"))
+ .respond_with(ResponseTemplate::new(200).set_body_json(serde_json::json!({
+ "messages": [{ "id": "message-1", "threadId": "thread-1" }]
+ })))
+ .expect(1)
+ .mount(&server)
+ .await;
+
+ let client = GmailClient::new_with_urls(
+ "projects/test/topics/gmail".to_string(),
+ format!("{}/gmail/", server.uri()),
+ format!("{}/people/", server.uri()),
+ format!("{}/jwks", server.uri()),
+ "test-audience".to_string(),
+ );
+
+ let message_ids = client
+ .list_messages("test-token", 1, &[])
+ .await
+ .expect("configured Gmail endpoint should be used");
+
+ assert_eq!(message_ids, vec!["message-1"]);
+ assert_eq!(client.contacts_url, format!("{}/people", server.uri()));
+ assert_eq!(client.certs_url, format!("{}/jwks", server.uri()));
+ assert_eq!(client.audience, "test-audience");
+ assert_eq!(client.subscription_topic, "projects/test/topics/gmail");
+}
diff --git a/crates/gmail_client/src/testdata/sanitizer/body-only/expected.html b/crates/gmail_client/src/testdata/sanitizer/body-only/expected.html
deleted file mode 100644
index 04e88eb05e..0000000000
--- a/crates/gmail_client/src/testdata/sanitizer/body-only/expected.html
+++ /dev/null
@@ -1,132 +0,0 @@
-<table>
- <tbody>
- <tr>
- <td></td>
- <td width="640">
- <table>
- <tbody>
- <tr>
- <td style="padding:10px 24px"><img style="border:none"></td>
- </tr>
- <tr>
- <td style="padding:0px 24px 30px 24px">
- <table>
- <tbody>
- <tr>
- <td
- style="padding:28px 10px 36px 10px;border-radius:2px;background-color:#260559;color:#FFFFFF;font-size:16px;font-family:Helvetica , Arial , Sans Serif;width:100%;text-align:center">
- <img width="75">
- <table>
- <tbody>
- <tr>
- <td
- style="padding-top:24px;font-size:16px;font-family:Helvetica , Arial , Sans Serif;border:none;text-align:center;color:#FFFFFF">
- Your document has been completed
- </td>
- </tr>
- </tbody>
- </table>
- <table>
- <tbody>
- <tr>
- <td align="center">
- <div>
- <table cellspacing="0">
- <tbody>
- <tr>
- <td align="center">
- <a href="https://fakelink.com" rel="noopener noreferrer"><span style="line-height:44px"> VIEW COMPLETED DOCUMENT
- </span></a></td>
- </tr>
- </tbody>
- </table>
- </div>
- </td>
- </tr>
- </tbody>
- </table>
- </td>
- </tr>
- </tbody>
- </table>
- </td>
- </tr>
- <tr>
- <td
- style="padding:0px 24px 24px 24px;color:#000000;font-size:16px;font-family:Helvetica , Arial , Sans Serif;background-color:white">
- <table>
- <tbody>
- <tr>
- <td style="padding-bottom:20px">
- <div
- style="font-family:Helvetica , Arial , Sans Serif;font-weight:bold;line-height:18px;font-size:15px;color:#333333">
- Cool Guy
- </div>
- <div style="font-family:Helvetica , Arial , Sans Serif;line-height:18px;font-size:15px;color:#666666">
- </div>
- </td>
- </tr>
- </tbody>
- </table>
- <p style="font-size:15px;color:#333333;font-family:Helvetica , Arial , Sans Serif;line-height:20px">All parties
- have
- completed Complete with Docusign: File.docx.</p></td>
- </tr>
- <tr>
- <td
- style="padding:0px 24px 12px 24px;background-color:#ffffff;font-family:Helvetica , Arial , Sans Serif;font-size:11px;color:#666666"></td>
- </tr>
- <tr>
- <td style="padding:30px 24px 45px 24px;background-color:#EAEAEA"><p
- style="margin-bottom:1em;font-family:Helvetica , Arial , Sans Serif;font-size:13px;color:#666666;line-height:18px">
- <b>Do Not Share This Email</b><br> This email contains a secure link to Docusign.
- Please do not share this email, link, or access code with others.<br></p>
- <p
- style="margin-bottom:1em;font-family:Helvetica , Arial , Sans Serif;font-size:13px;color:#666666;line-height:18px">
- <b>Alternate Signing Method</b><br> Visit Docusign.com, click 'Access Documents',
- and enter the security code:<br> 07826FB5028B4D6E98A68F62154436596 </p>
- <p
- style="margin-bottom:1em;font-family:Helvetica , Arial , Sans Serif;font-size:13px;color:#666666;line-height:18px">
- <b>About Docusign</b><br> Sign documents electronically in just minutes. It's
- safe, secure, and legally binding. Whether you're in an office, at home, on-the-go -- or even across the globe --
- Docusign provides a professional trusted solution for Digital Transaction Management™. </p>
- <p
- style="margin-bottom:1em;font-family:Helvetica , Arial , Sans Serif;font-size:13px;color:#666666;line-height:18px">
- <b>Questions about the Document?</b><br> If you need to modify the document or
- have questions about the details in the document, please reach out to the sender by emailing them
- directly.<br><br><b>Stop receiving this email</b><br><a href="https://notareallink.com"
- rel="noopener noreferrer">Report
- this email</a> or read more about <a
- href="https://support.docusign.com/en/guides/Declining-to-sign-DocuSign-Signer-Guide" rel="noopener noreferrer">Declining
- to sign</a> and <a href="https://support.docusign.com/en/articles/How-do-I-manage-my-email-notifications"
- rel="noopener noreferrer">Managing
- notifications</a>.<br><br> If you have trouble signing,
- visit "<a
- href="https://support.docusign.com/s/articles/How-do-I-sign-a-DocuSign-document-Basic-Signing?language=en_US&amp;utm_campaign=GBL_XX_DBU_UPS_2211_SignNotificationEmailFooter&amp;utm_medium=product&amp;utm_source=postsend"
- rel="noopener noreferrer">How
- to Sign a Document</a>" on our <a href="https://support.docusign.com/" rel="noopener noreferrer">Docusign Support
- Center</a>,
- or become part of the <a
- href="https://community.docusign.com/new-member-guide-142?utm_campaign=GBL_US_PRD_AWA_2405_CommunityCTA&amp;utm_medium=email&amp;utm_source=postsend"
- rel="noopener noreferrer">Docusign
- Community</a> to access tips and guidance from peers.<br><br></p>
- <p
- style="margin-bottom:1em;font-family:Helvetica , Arial , Sans Serif;font-size:13px;color:#666666;line-height:18px">
- <a
- href="https://www.docusign.com/features-and-benefits/mobile?utm_campaign=GBL_XX_DBU_UPS_2211_SignNotificationEmailFooter&amp;utm_medium=product&amp;utm_source=postsend"
- rel="noopener noreferrer"><img style="margin-right:7px;border:none;vertical-align:middle">Download the Docusign
- App </a></p>
- <p
- style="margin-bottom:1em;font-family:Helvetica , Arial , Sans Serif;font-size:13px;color:#666666;line-height:18px;font-size:10px;line-height:14px">
- This message was sent to you by Cool Guy who is using the Docusign Electronic Signature Service. If you
- would rather not receive email from this sender you may contact the sender with your request.</p></td>
- </tr>
- </tbody>
- </table>
- </td>
- <td></td>
- </tr>
- </tbody>
-</table>
-<span></span>
diff --git a/crates/gmail_client/src/testdata/sanitizer/body-only/original.html b/crates/gmail_client/src/testdata/sanitizer/body-only/original.html
deleted file mode 100644
index 6ca81ab4e3..0000000000
--- a/crates/gmail_client/src/testdata/sanitizer/body-only/original.html
+++ /dev/null
@@ -1,119 +0,0 @@
-<html lang="en">
-<head>
- <meta http-equiv="Content-Type"/>
- <meta name="viewport"/>
- <meta name="format-detection"/>
- <title>RecipientEnvelopeComplete</title></head>
-<body style="background-color:#EAEAEA;padding:2%;font-family:Helvetica,Arial,Sans Serif;">
-<table role='presentation'>
- <tr>
- <td></td>
- <td width="640">
- <table role="presentation">
- <tr>
- <td style="padding:10px 24px;"><img style="border:none;"/></td>
- </tr>
- <tr>
- <td style="padding:0px 24px 30px 24px;">
- <table role='presentation'>
- <tr>
- <td
- style="padding:28px 10px 36px 10px;border-radius:2px;background-color:#260559;color:#FFFFFF;font-size:16px;font-family:Helvetica,Arial,Sans Serif;width:100%;text-align:center;">
- <img width="75"/>
- <table role='presentation'>
- <tr>
- <td
- style="padding-top:24px;font-size:16px;font-family:Helvetica,Arial,Sans Serif;border:none;text-align:center;color:#FFFFFF">
- Your document has been completed
- </td>
- </tr>
- </table>
- <table role='presentation'>
- <tr>
- <td align="center">
- <div>
- <table cellspacing="0">
- <tr>
- <td align="center">
- <a href="https://fakelink.com"><span style="line-height:44px;"><!--[if mso]>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<![endif]--> VIEW COMPLETED DOCUMENT
- <!--[if mso]>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<![endif]--></span></a></td>
- </tr>
- </table>
- </div>
- </td>
- </tr>
- </table>
- </td>
- </tr>
- </table>
- </td>
- </tr>
- <tr>
- <td
- style="padding:0px 24px 24px 24px;color:#000000;font-size:16px;font-family:Helvetica,Arial,Sans Serif;background-color:white;">
- <table role='presentation'>
- <tr>
- <td style="padding-bottom:20px;">
- <div
- style="font-family:Helvetica,Arial,Sans Serif;font-weight:bold;line-height:18px;font-size:15px;color:#333333;">
- Cool Guy
- </div>
- <div style="font-family:Helvetica,Arial,Sans Serif;line-height:18px;font-size:15px;color:#666666;">
- </div>
- </td>
- </tr>
- </table>
- <p style="font-size:15px;color:#333333;font-family:Helvetica,Arial,Sans Serif;line-height:20px;">All parties have
- completed Complete with Docusign: File.docx.</p></td>
- </tr>
- <tr>
- <td
- style="padding:0px 24px 12px 24px;background-color:#ffffff;font-family:Helvetica,Arial,Sans Serif;font-size:11px;color:#666666;"></td>
- </tr>
- <tr>
- <td style="padding:30px 24px 45px 24px;background-color:#EAEAEA;"><p
- style="margin-bottom:1em;font-family:Helvetica,Arial,Sans Serif;font-size:13px;color:#666666;line-height:18px;">
- <b aria-level="3">Do Not Share This Email</b><br/> This email contains a secure link to Docusign.
- Please do not share this email, link, or access code with others.<br/></p>
- <p
- style="margin-bottom:1em;font-family:Helvetica,Arial,Sans Serif;font-size:13px;color:#666666;line-height:18px;">
- <b aria-level="3">Alternate Signing Method</b><br/> Visit Docusign.com, click 'Access Documents',
- and enter the security code:<br/> 07826FB5028B4D6E98A68F62154436596 </p>
- <p
- style="margin-bottom:1em;font-family:Helvetica,Arial,Sans Serif;font-size:13px;color:#666666;line-height:18px;">
- <b aria-level="3">About Docusign</b><br/> Sign documents electronically in just minutes. It's
- safe, secure, and legally binding. Whether you're in an office, at home, on-the-go -- or even across the globe --
- Docusign provides a professional trusted solution for Digital Transaction Management™. </p>
- <p
- style="margin-bottom:1em;font-family:Helvetica,Arial,Sans Serif;font-size:13px;color:#666666;line-height:18px;">
- <b aria-level="3">Questions about the Document?</b><br/> If you need to modify the document or
- have questions about the details in the document, please reach out to the sender by emailing them
- directly.<br/><br/><b aria-level="3">Stop receiving this email</b><br/><a href='https://notareallink.com'>Report
- this email</a> or read more about <a
- href='https://support.docusign.com/en/guides/Declining-to-sign-DocuSign-Signer-Guide'>Declining
- to sign</a> and <a href='https://support.docusign.com/en/articles/How-do-I-manage-my-email-notifications'>Managing
- notifications</a>.<br/><br/> If you have trouble signing,
- visit "<a
- href='https://support.docusign.com/s/articles/How-do-I-sign-a-DocuSign-document-Basic-Signing?language=en_US&#38;utm_campaign=GBL_XX_DBU_UPS_2211_SignNotificationEmailFooter&#38;utm_medium=product&#38;utm_source=postsend'>How
- to Sign a Document</a>" on our <a href='https://support.docusign.com/'>Docusign Support Center</a>,
- or become part of the <a
- href='https://community.docusign.com/new-member-guide-142?utm_campaign=GBL_US_PRD_AWA_2405_CommunityCTA&#38;utm_medium=email&#38;utm_source=postsend'>Docusign
- Community</a> to access tips and guidance from peers.<br/><br/></p>
- <p
- style="margin-bottom:1em;font-family:Helvetica,Arial,Sans Serif;font-size:13px;color:#666666;line-height:18px;">
- <a
- href="https://www.docusign.com/features-and-benefits/mobile?utm_campaign=GBL_XX_DBU_UPS_2211_SignNotificationEmailFooter&#38;utm_medium=product&#38;utm_source=postsend"><img
- style="margin-right:7px;border:none;vertical-align:middle;"/>Download the Docusign App </a></p>
- <p
- style="margin-bottom:1em;font-family:Helvetica,Arial,Sans Serif;font-size:13px;color:#666666;line-height:18px;font-size:10px;line-height:14px;">
- This message was sent to you by Cool Guy who is using the Docusign Electronic Signature Service. If you
- would rather not receive email from this sender you may contact the sender with your request.</p></td>
- </tr>
- </table>
- </td>
- <td></td>
- </tr>
-</table>
-<span itemscope=""></span></body>
-</html>
\ No newline at end of file
diff --git a/crates/gmail_client/src/threads.rs b/crates/gmail_client/src/threads.rs
index b1bbcb1dc9..cf0a6e7548 100644
--- a/crates/gmail_client/src/threads.rs
+++ b/crates/gmail_client/src/threads.rs
@@ -1,14 +1,18 @@
-use crate::{GmailClient, sanitize_error_body};
-use anyhow::Context;
-use models_email::email::service::thread::{ThreadList, ThreadSummary};
+use std::cmp::min;
+
use models_email::gmail::{ListThreadsResponse, MinimalThreadResource, ThreadResource};
use serde::de::DeserializeOwned;
-use std::cmp::min;
+
+use crate::error::{decode_json_response, unsuccessful_response};
+use crate::{GmailApiHttpError, GmailClient};
+
+#[cfg(test)]
+mod test;
// 500 is max allowed by gmail api
pub const LIST_THREADS_BATCH_SIZE: u32 = 500;
-/// lists thread provider ids up to the requested number, or all if none specified.
+/// Lists thread provider ids up to the requested number, or all if none specified.
/// `label_ids` restricts the result to threads carrying all of the given Gmail
/// label ids; an empty slice applies no label filter.
#[tracing::instrument(skip(client, access_token, next_page_token), err)]
@@ -18,70 +22,40 @@ pub(crate) async fn list_threads(
num_threads: u32,
next_page_token: Option<&str>,
label_ids: &[&str],
-) -> anyhow::Result<ThreadList> {
+) -> Result<ListThreadsResponse, GmailApiHttpError> {
if num_threads == 0 {
- return Ok(ThreadList {
- threads: Vec::new(),
+ return Ok(ListThreadsResponse {
+ threads: Some(Vec::new()),
next_page_token: None,
});
}
- // The Gmail API's `maxResults` parameter is capped at 500.
let batch_size = min(num_threads, LIST_THREADS_BATCH_SIZE);
-
- let http_client = client.inner.clone();
let url = format!("{}/users/me/threads", client.base_url);
-
let mut query_params = vec![("maxResults", batch_size.to_string())];
- // If a page token is provided, add it to the list of parameters.
if let Some(token) = next_page_token {
query_params.push(("pageToken", token.to_string()));
}
- // `labelIds` is a repeatable param; a thread matches if it carries all of them.
for label_id in label_ids {
query_params.push(("labelIds", label_id.to_string()));
}
- let response = http_client
- .get(&url)
+ let response = client
+ .inner
+ .get(url)
.bearer_auth(access_token)
- .query(&query_params) // Pass the dynamically built query params
+ .query(&query_params)
.send()
.await
- .context("Failed to send request to Gmail API (list threads)")?;
-
- let status = response.status();
- if !status.is_success() {
- let error_body = response
- .text()
- .await
- .unwrap_or_else(|_| "Failed to read error body".to_string());
- let sanitized = sanitize_error_body(&error_body);
- anyhow::bail!("Gmail API error {} (list threads): {}", status, sanitized);
- }
+ .map_err(GmailApiHttpError::transport)?;
- let gmail_response = response
- .json::<ListThreadsResponse>()
- .await
- .context("Failed to parse JSON response from Gmail API (list threads)")?;
-
- let thread_summaries = gmail_response
- .threads
- .unwrap_or_default()
- .into_iter()
- .map(|api_thread| ThreadSummary {
- provider_id: api_thread.id,
- })
- .collect();
-
- let result = ThreadList {
- threads: thread_summaries,
- next_page_token: gmail_response.next_page_token,
- };
+ if !response.status().is_success() {
+ return Err(unsuccessful_response(response).await);
+ }
- Ok(result)
+ decode_json_response(response).await
}
/// Fetches a thread from the Gmail API with the given format and deserializes the response.
@@ -90,43 +64,22 @@ async fn fetch_thread<T: DeserializeOwned>(
access_token: &str,
thread_id: &str,
format: &str,
-) -> anyhow::Result<T> {
- let url = format!(
- "{}/users/me/threads/{}?format={}",
- client.base_url, thread_id, format
- );
-
+) -> Result<T, GmailApiHttpError> {
+ let url = format!("{}/users/me/threads/{thread_id}", client.base_url);
let response = client
.inner
- .get(&url)
+ .get(url)
.bearer_auth(access_token)
+ .query(&[("format", format)])
.send()
.await
- .context(format!(
- "Failed to send request to Gmail API for thread {}",
- thread_id
- ))?;
-
- let status = response.status();
- if !status.is_success() {
- let error_body = response
- .text()
- .await
- .unwrap_or_else(|_| "Failed to read error body".to_string());
- let sanitized = sanitize_error_body(&error_body);
- anyhow::bail!(
- "Gmail API error {} (get thread, format={}) for thread_id {}: {}",
- status,
- format,
- thread_id,
- sanitized
- );
+ .map_err(GmailApiHttpError::transport)?;
+
+ if !response.status().is_success() {
+ return Err(unsuccessful_response(response).await);
}
- response.json::<T>().await.context(format!(
- "Failed to parse JSON response from Gmail API for thread {}",
- thread_id
- ))
+ decode_json_response(response).await
}
/// Fetches a single email thread with full message content from the Gmail API.
@@ -135,26 +88,24 @@ pub(crate) async fn get_thread(
client: &GmailClient,
access_token: &str,
thread_id: &str,
-) -> anyhow::Result<ThreadResource> {
+) -> Result<ThreadResource, GmailApiHttpError> {
fetch_thread(client, access_token, thread_id, "full").await
}
/// Gets all message IDs for a specific thread using the minimal format
-/// to reduce data transfer and processing time
+/// to reduce data transfer and processing time.
#[tracing::instrument(skip(client, access_token), err)]
pub(crate) async fn get_message_ids_for_thread(
client: &GmailClient,
access_token: &str,
thread_id: &str,
-) -> anyhow::Result<Vec<String>> {
+) -> Result<Vec<String>, GmailApiHttpError> {
let thread_resource: MinimalThreadResource =
fetch_thread(client, access_token, thread_id, "minimal").await?;
- let message_ids = thread_resource
+ Ok(thread_resource
.messages
- .iter()
- .map(|message| message.id.clone())
- .collect();
-
- Ok(message_ids)
+ .into_iter()
+ .map(|message| message.id)
+ .collect())
}
diff --git a/crates/gmail_client/src/threads/test.rs b/crates/gmail_client/src/threads/test.rs
new file mode 100644
index 0000000000..c6210562d1
--- /dev/null
+++ b/crates/gmail_client/src/threads/test.rs
@@ -0,0 +1,115 @@
+use reqwest::StatusCode;
+use wiremock::matchers::{method, path, query_param};
+use wiremock::{Mock, MockServer, ResponseTemplate};
+
+use super::*;
+
+fn client(server: &MockServer) -> GmailClient {
+ GmailClient::new_with_urls(
+ String::new(),
+ server.uri(),
+ server.uri(),
+ server.uri(),
+ String::new(),
+ )
+}
+
+#[tokio::test]
+async fn list_threads_preserves_wire_response_and_query_parameters() {
+ let server = MockServer::start().await;
+ Mock::given(method("GET"))
+ .and(path("/users/me/threads"))
+ .and(query_param("maxResults", "500"))
+ .and(query_param("pageToken", "next page"))
+ .and(query_param("labelIds", "INBOX"))
+ .and(query_param("labelIds", "IMPORTANT"))
+ .respond_with(ResponseTemplate::new(200).set_body_json(serde_json::json!({
+ "threads": [{ "id": "thread-1" }],
+ "nextPageToken": "following-page"
+ })))
+ .expect(1)
+ .mount(&server)
+ .await;
+
+ let response = list_threads(
+ &client(&server),
+ "token",
+ 700,
+ Some("next page"),
+ &["INBOX", "IMPORTANT"],
+ )
+ .await
+ .expect("thread list should decode");
+
+ assert_eq!(response.threads.unwrap()[0].id, "thread-1");
+ assert_eq!(response.next_page_token.as_deref(), Some("following-page"));
+}
+
+#[tokio::test]
+async fn zero_thread_limit_does_not_make_a_request() {
+ let server = MockServer::start().await;
+ let response = list_threads(&client(&server), "token", 0, Some("unused"), &[])
+ .await
+ .expect("zero limit should succeed");
+
+ assert!(response.threads.unwrap().is_empty());
+ assert!(response.next_page_token.is_none());
+ assert!(server.received_requests().await.unwrap().is_empty());
+}
+
+#[tokio::test]
+async fn get_message_ids_requests_minimal_thread() {
+ let server = MockServer::start().await;
+ Mock::given(method("GET"))
+ .and(path("/users/me/threads/thread-1"))
+ .and(query_param("format", "minimal"))
+ .respond_with(ResponseTemplate::new(200).set_body_json(serde_json::json!({
+ "id": "thread-1",
+ "messages": [
+ { "id": "message-1", "threadId": "thread-1" },
+ { "id": "message-2", "threadId": "thread-1" }
+ ]
+ })))
+ .mount(&server)
+ .await;
+
+ let ids = get_message_ids_for_thread(&client(&server), "token", "thread-1")
+ .await
+ .expect("minimal thread should decode");
+ assert_eq!(ids, ["message-1", "message-2"]);
+}
+
+#[tokio::test]
+async fn get_thread_requests_full_format_and_sanitizes_errors() {
+ let server = MockServer::start().await;
+ Mock::given(method("GET"))
+ .and(path("/users/me/threads/thread-1"))
+ .and(query_param("format", "full"))
+ .respond_with(
+ ResponseTemplate::new(StatusCode::FORBIDDEN.as_u16())
+ .set_body_string("denied for [email protected]"),
+ )
+ .mount(&server)
+ .await;
+
+ let error = get_thread(&client(&server), "token", "thread-1")
+ .await
+ .expect_err("error status should fail");
+ assert_eq!(error.status(), Some(StatusCode::FORBIDDEN));
+ assert_eq!(error.body(), Some("denied for [REDACTED_EMAIL]"));
+}
+
+#[tokio::test]
+async fn malformed_thread_json_is_a_decode_error() {
+ let server = MockServer::start().await;
+ Mock::given(method("GET"))
+ .and(path("/users/me/threads"))
+ .respond_with(ResponseTemplate::new(200).set_body_string("not-json"))
+ .mount(&server)
+ .await;
+
+ let error = list_threads(&client(&server), "token", 1, None, &[])
+ .await
+ .expect_err("malformed JSON should fail");
+ assert!(matches!(error, GmailApiHttpError::Decode(_)));
+}
diff --git a/crates/gmail_client/src/watch.rs b/crates/gmail_client/src/watch.rs
index bf531d40c0..4ee52b9710 100644
--- a/crates/gmail_client/src/watch.rs
+++ b/crates/gmail_client/src/watch.rs
@@ -1,100 +1,54 @@
-use crate::GmailClient;
-use anyhow::Context;
+use crate::error::{decode_json_response, unsuccessful_response};
+use crate::{GmailApiHttpError, GmailClient};
use models_email::gmail::WatchRequest;
-use models_email::gmail::error::GmailError;
use models_email::gmail::history::WatchResponse;
-/// Registers a user for Gmail push notifications to the specified Pub/Sub topic
+/// Registers a user for Gmail push notifications.
#[tracing::instrument(skip(client, access_token), err)]
pub(crate) async fn register_watch(
client: &GmailClient,
access_token: &str,
-) -> Result<WatchResponse, GmailError> {
- let url = format!("{}/users/me/watch", client.base_url);
-
- let http_client = client.inner.clone();
-
- // Prepare the request body with the topic name
- let request_body = WatchRequest {
+) -> Result<WatchResponse, GmailApiHttpError> {
+ let request = WatchRequest {
topic_name: client.subscription_topic.clone(),
};
-
- let response = http_client
- .post(&url)
+ let response = client
+ .inner
+ .post(format!("{}/users/me/watch", client.base_url))
.bearer_auth(access_token)
- .json(&request_body)
+ .json(&request)
.send()
.await
- .map_err(|e| GmailError::HttpRequest(e.to_string()))?;
-
- // Check specifically for 401 Unauthorized
- if response.status() == reqwest::StatusCode::UNAUTHORIZED {
- tracing::warn!("Gmail API returned 401 Unauthorized - access token might be expired");
- return Err(GmailError::Unauthorized);
- }
+ .map_err(GmailApiHttpError::transport)?;
- // Handle other error status codes
if !response.status().is_success() {
- let status = response.status();
- let error_body = response
- .text()
- .await
- .unwrap_or_else(|_| "Failed to read error body".to_string());
-
- // Gmail permits only one active push channel per mailbox; a watch left over from a
- // prior registration makes a fresh watch fail with a 400 carrying this message. Map
- // it to a typed Conflict so callers can stop the stale watch and retry rather than
- // matching the response body themselves.
- if status == reqwest::StatusCode::BAD_REQUEST
- && error_body.contains("push notification client allowed")
- {
- return Err(GmailError::Conflict(error_body));
- }
-
- // An access token minted from a grant without the Gmail scope is rejected
- // with a 403. Typed so callers can treat it as a missing grant, matching
- // the 403 mapping elsewhere in this client.
- if status == reqwest::StatusCode::FORBIDDEN {
- return Err(GmailError::Forbidden);
- }
-
- return Err(GmailError::ApiError(format!(
- "({}): {}",
- status, error_body
- )));
+ return Err(unsuccessful_response(response).await);
}
- let watch_response = response
- .json::<WatchResponse>()
- .await
- .map_err(|e| GmailError::BodyReadError(e.to_string()))?;
-
- Ok(watch_response)
+ decode_json_response(response).await
}
-/// Stops push notifications for a user's Gmail inbox
+/// Stops push notifications for a user's Gmail inbox.
#[tracing::instrument(skip(client, access_token), err)]
-pub(crate) async fn stop_watch(client: &GmailClient, access_token: &str) -> anyhow::Result<()> {
- let url = format!("{}/users/me/stop", client.base_url);
-
- let http_client = client.inner.clone();
-
- let response = http_client
- .post(&url)
+pub(crate) async fn stop_watch(
+ client: &GmailClient,
+ access_token: &str,
+) -> Result<(), GmailApiHttpError> {
+ let response = client
+ .inner
+ .post(format!("{}/users/me/stop", client.base_url))
.header("Content-Length", "0")
.bearer_auth(access_token)
.send()
.await
- .context("Failed to send request to Gmail API (stop watch)")?;
+ .map_err(GmailApiHttpError::transport)?;
- let status = response.status();
- if !status.is_success() {
- let error_body = response
- .text()
- .await
- .unwrap_or_else(|_| "Failed to read error body".to_string());
- anyhow::bail!("Gmail API error {} (stop watch): {}", status, error_body);
+ if !response.status().is_success() {
+ return Err(unsuccessful_response(response).await);
}
Ok(())
}
+
+#[cfg(test)]
+mod test;
diff --git a/crates/gmail_client/src/watch/test.rs b/crates/gmail_client/src/watch/test.rs
new file mode 100644
index 0000000000..de527e0055
--- /dev/null
+++ b/crates/gmail_client/src/watch/test.rs
@@ -0,0 +1,66 @@
+use reqwest::StatusCode;
+use serde_json::json;
+use wiremock::matchers::{body_json, header, method, path};
+use wiremock::{Mock, MockServer, ResponseTemplate};
+
+use super::*;
+
+fn client(server: &MockServer) -> GmailClient {
+ GmailClient::new_with_urls(
+ "projects/project/topics/gmail".to_string(),
+ server.uri(),
+ server.uri(),
+ server.uri(),
+ String::new(),
+ )
+}
+
+#[tokio::test]
+async fn registers_watch_with_the_configured_topic() {
+ let server = MockServer::start().await;
+ Mock::given(method("POST"))
+ .and(path("/users/me/watch"))
+ .and(body_json(
+ json!({"topicName": "projects/project/topics/gmail"}),
+ ))
+ .respond_with(ResponseTemplate::new(200).set_body_json(json!({
+ "historyId": "123", "expiration": "456"
+ })))
+ .mount(&server)
+ .await;
+
+ let response = register_watch(&client(&server), "token").await.unwrap();
+ assert_eq!(response.history_id, "123");
+}
+
+#[tokio::test]
+async fn watch_preserves_conflict_status_and_body_without_classifying_it() {
+ let server = MockServer::start().await;
+ Mock::given(method("POST"))
+ .and(path("/users/me/watch"))
+ .respond_with(ResponseTemplate::new(400).set_body_string(
+ "Only one user push notification client allowed for [email protected]",
+ ))
+ .mount(&server)
+ .await;
+
+ let error = register_watch(&client(&server), "token").await.unwrap_err();
+ assert_eq!(error.status(), Some(StatusCode::BAD_REQUEST));
+ assert_eq!(
+ error.body(),
+ Some("Only one user push notification client allowed for [REDACTED_EMAIL]")
+ );
+}
+
+#[tokio::test]
+async fn stops_watch_with_an_empty_body() {
+ let server = MockServer::start().await;
+ Mock::given(method("POST"))
+ .and(path("/users/me/stop"))
+ .and(header("content-length", "0"))
+ .respond_with(ResponseTemplate::new(204))
+ .mount(&server)
+ .await;
+
+ stop_watch(&client(&server), "token").await.unwrap();
+}
diff --git a/crates/macro_db_client/migrations/20260807181503_email_backfill_jobs_is_recovery.sql b/crates/macro_db_client/migrations/20260807181503_email_backfill_jobs_is_recovery.sql
new file mode 100644
index 0000000000..a01b2bf29a
--- /dev/null
+++ b/crates/macro_db_client/migrations/20260807181503_email_backfill_jobs_is_recovery.sql
@@ -0,0 +1,6 @@
+-- Marks backfill jobs created by the stale-cursor recovery path. Recovery
+-- jobs skip the priority pass and refresh existing threads (fetching message
+-- ids and backfilling any missing messages) so the sync-gap window's replies
+-- in already-known threads are actually recovered.
+ALTER TABLE email_backfill_jobs
+ ADD COLUMN is_recovery boolean NOT NULL DEFAULT false;
diff --git a/crates/models_email/src/email/service/backfill.rs b/crates/models_email/src/email/service/backfill.rs
index 8c0222c4df..9a6c3baedb 100644
--- a/crates/models_email/src/email/service/backfill.rs
+++ b/crates/models_email/src/email/service/backfill.rs
@@ -12,6 +12,10 @@ use uuid::Uuid;
#[derive(Debug, Deserialize, Serialize, Clone, PartialEq, Eq)]
pub struct BackfillThreadPayload {
pub thread_provider_id: String,
+ /// When true (stale-cursor recovery jobs), an already-known thread is
+ /// refreshed — missing messages are backfilled — instead of skipped.
+ #[serde(default)]
+ pub refresh_existing: bool,
}
#[derive(Debug, Deserialize, Serialize, Clone, PartialEq, Eq)]
diff --git a/crates/models_email/src/email/service/pubsub.rs b/crates/models_email/src/email/service/pubsub.rs
index 3f3e7dcc90..d51b07175b 100644
--- a/crates/models_email/src/email/service/pubsub.rs
+++ b/crates/models_email/src/email/service/pubsub.rs
@@ -4,6 +4,14 @@ use strum::{Display, EnumString};
use thiserror::Error;
use uuid::Uuid;
+/// A worker failure with its queue-routing classification.
+///
+/// Style exception (CS-46): the email worker error plumbing stays on
+/// `anyhow::Error` rather than `rootcause`. Every queue operation, policy
+/// module, and DLQ path across email_service composes through this
+/// `source` field, so migrating is an all-or-nothing cross-crate change —
+/// recorded here as the accepted exception rather than mixing the two
+/// error stacks module by module.
#[derive(Debug, Error)]
#[error("{reason}: {source}")]
pub struct DetailedError {
diff --git a/crates/models_email/src/email/service/thread.rs b/crates/models_email/src/email/service/thread.rs
index 4be0d327ea..e0d726b36a 100644
--- a/crates/models_email/src/email/service/thread.rs
+++ b/crates/models_email/src/email/service/thread.rs
@@ -186,6 +186,11 @@ pub struct ListThreadsPayload {
/// off to the normal most-recent-to-least sweep.
#[serde(default)]
pub priority_pass: bool,
+ /// When true (stale-cursor recovery jobs), threads that already exist in
+ /// the database are refreshed — their message ids are fetched and missing
+ /// messages backfilled — instead of being skipped.
+ #[serde(default)]
+ pub refresh_existing: bool,
}
/// A mapping from provider IDs to thread IDs
diff --git a/crates/models_email/src/gmail/error.rs b/crates/models_email/src/gmail/error.rs
deleted file mode 100644
index 5e403787b1..0000000000
--- a/crates/models_email/src/gmail/error.rs
+++ /dev/null
@@ -1,37 +0,0 @@
-use thiserror::Error;
-
-#[derive(Error, Debug)]
-pub enum GmailError {
- #[error("API Rate Limit Exceeded (429)")]
- RateLimitExceeded,
-
- #[error("Unauthorized: The access token is invalid or expired (401)")]
- Unauthorized,
-
- #[error("Forbidden: Insufficient permissions (403)")]
- Forbidden,
-
- #[error("Server Error ({0}): {1}")]
- ServerError(u16, String),
-
- #[error("HTTP Request Error: {0}")]
- HttpRequest(String),
-
- #[error("API Error: {0}")]
- ApiError(String),
-
- #[error("Multipart Parsing Error: {0}")]
- MultipartParse(String),
-
- #[error("Failed to read response body: {0}")]
- BodyReadError(String),
-
- #[error("Conflict: {0}")]
- Conflict(String),
-
- #[error("Not found: {0}")]
- NotFound(String),
-
- #[error("Internal Error: {0}")]
- GenericError(String),
-}
diff --git a/crates/models_email/src/gmail/labels.rs b/crates/models_email/src/gmail/labels.rs
index 34c4bbb62e..ba0b759a17 100644
--- a/crates/models_email/src/gmail/labels.rs
+++ b/crates/models_email/src/gmail/labels.rs
@@ -100,6 +100,7 @@ impl fmt::Display for SystemLabelID {
/// Represents the color information for a Gmail label
#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
pub struct GmailLabelColor {
pub text_color: Option<String>,
pub background_color: Option<String>,
@@ -124,67 +125,3 @@ pub struct GmailLabel {
pub struct GmailLabelsResponse {
pub labels: Vec<GmailLabel>,
}
-
-impl GmailLabel {
- /// Convert a GmailLabel to a service::Label
- pub fn to_service_label(
- &self,
- link_id: uuid::Uuid,
- ) -> Result<crate::email::service::label::Label, String> {
- // Default values for optional fields
- let message_list_visibility = match self.message_list_visibility.as_deref() {
- Some(visibility) => {
- crate::email::service::label::MessageListVisibility::from_str(visibility)?
- }
- None => crate::email::service::label::MessageListVisibility::Show, // Default to Show
- };
-
- let label_list_visibility = match self.label_list_visibility.as_deref() {
- Some(visibility) => {
- crate::email::service::label::LabelListVisibility::from_str(visibility)?
- }
- None => crate::email::service::label::LabelListVisibility::LabelShow, // Default to LabelShow
- };
-
- let type_ = match self.type_.as_deref() {
- Some(type_str) => crate::email::service::label::LabelType::from_str(type_str)?,
- None => crate::email::service::label::LabelType::User, // Default to User
- };
-
- Ok(crate::email::service::label::Label {
- id: None, // Generated at insert
- link_id,
- provider_label_id: self.id.clone().unwrap_or_default(),
- name: Some(self.name.clone()),
- created_at: chrono::Utc::now(),
- message_list_visibility: Some(message_list_visibility),
- label_list_visibility: Some(label_list_visibility),
- type_: Some(type_),
- })
- }
-}
-
-impl GmailLabelsResponse {
- /// Convert all Gmail labels to service labels
- pub fn to_service_labels(
- &self,
- link_id: uuid::Uuid,
- ) -> Result<Vec<crate::email::service::label::Label>, String> {
- let mut service_labels = Vec::with_capacity(self.labels.len());
-
- for gmail_label in &self.labels {
- match gmail_label.to_service_label(link_id) {
- Ok(service_label) => service_labels.push(service_label),
- Err(e) => {
- return Err(format!(
- "Error converting label {}: {}",
- gmail_label.id.clone().unwrap_or_default(),
- e
- ));
- }
- }
- }
-
- Ok(service_labels)
- }
-}
diff --git a/crates/models_email/src/gmail/mod.rs b/crates/models_email/src/gmail/mod.rs
index 6bd573e527..e04b29684f 100644
--- a/crates/models_email/src/gmail/mod.rs
+++ b/crates/models_email/src/gmail/mod.rs
@@ -1,5 +1,4 @@
pub mod contacts;
-pub mod error;
pub mod filters;
pub mod gmail_ops;
pub mod history;
@@ -218,6 +217,7 @@ pub struct HistoryMessage {
/// Request body for registering a watch notification
#[derive(Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
pub struct WatchRequest {
pub topic_name: String,
}
diff --git a/crates/workspace-hack/Cargo.toml b/crates/workspace-hack/Cargo.toml
index 705fde723f..e010670815 100644
--- a/crates/workspace-hack/Cargo.toml
+++ b/crates/workspace-hack/Cargo.toml
@@ -64,7 +64,7 @@ hashbrown-9067fe90e8c1f593 = { package = "hashbrown", version = "0.17" }
hashbrown-986da7b5efc2b80e = { package = "hashbrown", version = "0.16" }
hmac = { version = "0.12", default-features = false, features = ["reset"] }
hyper-582f2526e08bb6a0 = { package = "hyper", version = "0.14", default-features = false, features = ["client", "http1", "http2", "runtime", "server", "stream"] }
-hyper-dff4ba8e3ae991db = { package = "hyper", version = "1", features = ["client", "http1", "http2", "server"] }
+hyper-dff4ba8e3ae991db = { package = "hyper", version = "1", features = ["full"] }
hyper-rustls-adf3d7031871b0af = { package = "hyper-rustls", version = "0.24", default-features = false, features = ["acceptor", "http1", "http2", "logging", "tls12", "webpki-tokio"] }
hyper-util = { version = "0.1", features = ["client-legacy", "client-proxy", "http1", "http2", "server", "service"] }
idna = { version = "1" }
@@ -191,7 +191,7 @@ hashbrown-9067fe90e8c1f593 = { package = "hashbrown", version = "0.17" }
hashbrown-986da7b5efc2b80e = { package = "hashbrown", version = "0.16" }
hmac = { version = "0.12", default-features = false, features = ["reset"] }
hyper-582f2526e08bb6a0 = { package = "hyper", version = "0.14", default-features = false, features = ["client", "http1", "http2", "runtime", "server", "stream"] }
-hyper-dff4ba8e3ae991db = { package = "hyper", version = "1", features = ["client", "http1", "http2", "server"] }
+hyper-dff4ba8e3ae991db = { package = "hyper", version = "1", features = ["full"] }
hyper-rustls-adf3d7031871b0af = { package = "hyper-rustls", version = "0.24", default-features = false, features = ["acceptor", "http1", "http2", "logging", "tls12", "webpki-tokio"] }
hyper-util = { version = "0.1", features = ["client-legacy", "client-proxy", "http1", "http2", "server", "service"] }
idna = { version = "1" }
diff --git a/packages/sdk/generated/email/sdk.gen.ts b/packages/sdk/generated/email/sdk.gen.ts
index 6943c54780..69966d4219 100644
--- a/packages/sdk/generated/email/sdk.gen.ts
+++ b/packages/sdk/generated/email/sdk.gen.ts
@@ -374,7 +374,7 @@ export class Sdk extends HeyApiClient {
* against the auth service and records the result on each link. A grant that died
* while the caller was inactive is detected here within minutes instead of waiting on
* the daily refresh sweep; the side effects (clearing or setting the reauth flag, and
- * the one-time reauth fan-out) are handled by `fetch_token_or_mark_reauth_no_cache`.
+ * the one-time reauth fan-out) are handled by the email service token source.
*
* Probes run in the background and the response returns immediately to stay off the
* load path; each persisted flag is picked up by the next links read. Probes are
diff --git a/packages/sdk/generated/email/types.gen.ts b/packages/sdk/generated/email/types.gen.ts
index a4d84423dd..e81b95fea0 100644
--- a/packages/sdk/generated/email/types.gen.ts
+++ b/packages/sdk/generated/email/types.gen.ts
@@ -1771,7 +1771,10 @@ export type GetAttachmentData = {
export type GetAttachmentErrors = {
400: ErrorResponse;
401: ErrorResponse;
+ 403: ErrorResponse;
404: ErrorResponse;
+ 409: ErrorResponse;
+ 429: ErrorResponse;
500: ErrorResponse;
};
@@ -1947,6 +1950,9 @@ export type ListBlockedSendersData = {
export type ListBlockedSendersErrors = {
401: ErrorResponse;
403: ErrorResponse;
+ 404: ErrorResponse;
+ 409: ErrorResponse;
+ 429: ErrorResponse;
500: ErrorResponse;
};
@@ -2312,6 +2318,7 @@ export type InitUserErrors = {
400: InitErrorCodeResponse;
401: ErrorResponse;
409: SharedInboxConflictResponse;
+ 429: ErrorResponse;
500: ErrorResponse;
};
@@ -2353,7 +2360,10 @@ export type CreateLabelData = {
export type CreateLabelErrors = {
400: ErrorResponse;
401: ErrorResponse;
+ 403: ErrorResponse;
+ 404: ErrorResponse;
409: ErrorResponse;
+ 429: ErrorResponse;
500: ErrorResponse;
};
diff --git a/packages/sdk/specs/email.json b/packages/sdk/specs/email.json
index d3bd4f5ba9..5ddaf0c9a1 100644
--- a/packages/sdk/specs/email.json
+++ b/packages/sdk/specs/email.json
@@ -423,6 +423,16 @@
}
}
},
+ "403": {
+ "description": "",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse"
+ }
+ }
+ }
+ },
"404": {
"description": "",
"content": {
@@ -433,6 +443,26 @@
}
}
},
+ "409": {
+ "description": "",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse"
+ }
+ }
+ }
+ },
+ "429": {
+ "description": "",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse"
+ }
+ }
+ }
+ },
"500": {
"description": "",
"content": {
@@ -850,6 +880,36 @@
}
}
},
+ "404": {
+ "description": "",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse"
+ }
+ }
+ }
+ },
+ "409": {
+ "description": "",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse"
+ }
+ }
+ }
+ },
+ "429": {
+ "description": "",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse"
+ }
+ }
+ }
+ },
"500": {
"description": "",
"content": {
@@ -1747,6 +1807,16 @@
}
}
},
+ "429": {
+ "description": "",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse"
+ }
+ }
+ }
+ },
"500": {
"description": "",
"content": {
@@ -1843,6 +1913,26 @@
}
}
},
+ "403": {
+ "description": "",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse"
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse"
+ }
+ }
+ }
+ },
"409": {
"description": "",
"content": {
@@ -1853,6 +1943,16 @@
}
}
},
+ "429": {
+ "description": "",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse"
+ }
+ }
+ }
+ },
"500": {
"description": "",
"content": {
@@ -1989,7 +2089,7 @@
"/email/links/health-check": {
"post": {
"tags": ["Links"],
- "summary": "Probes the live auth state of each of the caller's inboxes (owned and delegated)\nagainst the auth service and records the result on each link. A grant that died\nwhile the caller was inactive is detected here within minutes instead of waiting on\nthe daily refresh sweep; the side effects (clearing or setting the reauth flag, and\nthe one-time reauth fan-out) are handled by `fetch_token_or_mark_reauth_no_cache`.",
+ "summary": "Probes the live auth state of each of the caller's inboxes (owned and delegated)\nagainst the auth service and records the result on each link. A grant that died\nwhile the caller was inactive is detected here within minutes instead of waiting on\nthe daily refresh sweep; the side effects (clearing or setting the reauth flag, and\nthe one-time reauth fan-out) are handled by the email service token source.",
"description": "Probes run in the background and the response returns immediately to stay off the\nload path; each persisted flag is picked up by the next links read. Probes are\nthrottled per link in Redis so frequent calls — and many sharers of a shared inbox —\ncollapse to one refresh per window.",
"operationId": "health_check_links",
"responses": {
diff --git a/services/email_service/Cargo.toml b/services/email_service/Cargo.toml
index f3c5cc418e..20788a13d7 100644
--- a/services/email_service/Cargo.toml
+++ b/services/email_service/Cargo.toml
@@ -77,7 +77,7 @@ sfs_delete = []
[dependencies]
calendar_events = { path = "../../crates/calendar_events", features = ["google", "inbound", "postgres"] }
-ammonia = "4.1.4"
+ammonia = { workspace = true }
anyhow = { workspace = true }
authentication_service_client = { path = "../../crates/authentication_service_client" }
macro_aws_config = { path = "../../crates/macro_aws_config", features = ["s3", "sqs"] }
@@ -100,13 +100,14 @@ ego-tree = { workspace = true }
email = { path = "../../crates/email", features = ["axum", "gmail_token", "inbound", "outbound"] }
entity_access = { path = "../../crates/entity_access", default-features = false, features = ["outbound"] }
entity_access_management = { path = "../../crates/entity_access_management" }
+email_api_client = { path = "../../crates/email_api_client", features = ["ports", "outbound-gmail"] }
email_db_client = { path = "../../crates/email_db_client" }
email_utils = { path = "../../crates/email_utils" }
filter_ast = { path = "../../crates/filter_ast" }
frecency = { path = "../../crates/frecency", features = ["postgres"] }
futures = { workspace = true }
gmail_client = { path = "../../crates/gmail_client" }
-html-escape = "0.2"
+html-escape = { workspace = true }
http-body-util = { workspace = true }
infer = "0.19.0"
item_filters = { path = "../../crates/item_filters" }
@@ -119,7 +120,6 @@ macro_db_client = { path = "../../crates/macro_db_client" }
macro_entrypoint = { path = "../../crates/macro_entrypoint" }
macro_env = { path = "../../crates/macro_env" }
macro_event_broker = { path = "../../crates/macro_event_broker" }
-mailparse = "0.16.1"
macro_env_var = { path = "../../crates/macro_env_var" }
macro_queues = { path = "../../crates/macro_queues" }
macro_middleware = { path = "../../crates/macro_middleware", default-features = false }
diff --git a/services/email_service/src/api/context.rs b/services/email_service/src/api/context.rs
index 3c12214df4..12e67848b7 100644
--- a/services/email_service/src/api/context.rs
+++ b/services/email_service/src/api/context.rs
@@ -16,6 +16,7 @@ use email_service::calendar_tokens::CalendarTokenProviderAdapter;
use email_service::pubsub::calendar_backfill_adapters::RedisCalendarRequestGate;
use email_service::config::Config;
+use email_service::outbound::email_api::GmailApi;
use email_service::util::redis::RedisClient;
use entity_access::{domain::service::EntityAccessServiceImpl, outbound::PgAccessRepository};
use entity_access_management::domain::service::EntityAccessManagementServiceImpl;
@@ -58,7 +59,9 @@ pub(crate) type EmailSvc = EmailServiceImpl<
pub(crate) struct ApiContext {
pub db: sqlx::Pool<sqlx::Postgres>,
pub auth_service_client: Arc<authentication_service_client::AuthServiceClient>,
+ // The raw client is retained only for Gmail webhook JWKS/JWT authentication.
pub gmail_client: Arc<gmail_client::GmailClient>,
+ pub email_api: GmailApi,
pub redis_client: Arc<RedisClient>,
pub sqs_client: Arc<sqs_client::SQS>,
pub s3_client: Arc<s3_client::S3>,
diff --git a/services/email_service/src/api/email/attachments/get.rs b/services/email_service/src/api/email/attachments/get.rs
index 6601f2ccbe..14eb0a8120 100644
--- a/services/email_service/src/api/email/attachments/get.rs
+++ b/services/email_service/src/api/email/attachments/get.rs
@@ -32,7 +32,10 @@ pub struct GetAttachmentResponse {
(status = 200, body=GetAttachmentResponse),
(status = 400, body=ErrorResponse),
(status = 401, body=ErrorResponse),
+ (status = 403, body=ErrorResponse),
(status = 404, body=ErrorResponse),
+ (status = 409, body=ErrorResponse),
+ (status = 429, body=ErrorResponse),
(status = 500, body=ErrorResponse),
)
)]
@@ -130,25 +133,7 @@ pub async fn handler(
})?;
presigned_request.to_string()
} else {
- // Object doesn't exist, need to fetch from Gmail and upload.
- // Use the owning inbox's own token, not the caller's primary inbox token.
- let gmail_token = email_service::util::gmail::auth::fetch_gmail_access_token_from_link(
- &link,
- &ctx.redis_client,
- &ctx.auth_service_client,
- )
- .await
- .map_err(|e| {
- tracing::warn!(error=?e, "error fetching gmail token for attachment inbox");
- (
- StatusCode::INTERNAL_SERVER_ERROR,
- Json(ErrorResponse {
- message: "error fetching attachment".into(),
- }),
- )
- .into_response()
- })?;
-
+ // Object doesn't exist, need to fetch it from the owning inbox and upload it.
let provider_attachment_id = db_attachment.provider_id.as_ref().ok_or_else(|| {
tracing::warn!(attachment_id=%attachment_id, "attachment is missing a provider_id");
(
@@ -160,19 +145,15 @@ pub async fn handler(
.into_response()
})?;
- // fetch attachment data from gmail api
let attachment_data = ctx
- .gmail_client
- .get_attachment_data(
- gmail_token.as_str(),
- &message_provider_id,
- provider_attachment_id,
- )
+ .email_api
+ .get_attachment(link.id, &message_provider_id, provider_attachment_id)
.await
.map_err(|e| {
- tracing::warn!(error=?e, "error fetching attachment from Gmail API");
+ tracing::warn!(error=?e, "error fetching attachment from email provider");
(
- StatusCode::INTERNAL_SERVER_ERROR,
+ crate::api::email::provider_error::provider_error_status(&e),
+ crate::api::email::provider_error::provider_error_headers(&e),
Json(ErrorResponse {
message: "error fetching attachment".into(),
}),
@@ -216,7 +197,7 @@ pub async fn handler(
/// Uploads the data for a single attachment to S3, updates the attachment's metadata,
/// and returns a presigned URL for accessing the attachment
-#[tracing::instrument(skip(state, attachment_data), level = "info", err)]
+#[tracing::instrument(skip(state, attachment_data), err)]
pub async fn upload_single_attachment(
state: &ApiContext,
bucket: &str,
diff --git a/services/email_service/src/api/email/attachments/get_document_id.rs b/services/email_service/src/api/email/attachments/get_document_id.rs
index e57174d2ab..664b517022 100644
--- a/services/email_service/src/api/email/attachments/get_document_id.rs
+++ b/services/email_service/src/api/email/attachments/get_document_id.rs
@@ -3,7 +3,6 @@ use axum::extract::{Path, State};
use axum::http::StatusCode;
use axum::response::{IntoResponse, Response};
use axum::{Extension, Json};
-use email_service::util::gmail::auth::fetch_gmail_access_token_from_link;
use email_service::util::upload_attachment::{
UploadAttachmentContext, UploadAttachmentError, upload_attachment,
};
@@ -40,6 +39,14 @@ impl IntoResponse for GetAttachmentDocumentIdError {
let status_code = match &self {
GetAttachmentDocumentIdError::AttachmentNotFound => StatusCode::NOT_FOUND,
GetAttachmentDocumentIdError::AccessDenied => StatusCode::FORBIDDEN,
+ GetAttachmentDocumentIdError::UploadError(UploadAttachmentError::RateLimited) => {
+ StatusCode::TOO_MANY_REQUESTS
+ }
+ // Provider failures keep their meaning (401/403/404/409/429)
+ // instead of collapsing to 500.
+ GetAttachmentDocumentIdError::UploadError(UploadAttachmentError::GmailFetchFailed(
+ provider_error,
+ )) => crate::api::email::provider_error::provider_error_status(provider_error),
GetAttachmentDocumentIdError::DatabaseError(_)
| GetAttachmentDocumentIdError::UploadError(_) => StatusCode::INTERNAL_SERVER_ERROR,
};
@@ -76,7 +83,6 @@ pub struct GetAttachmentDocumentIDResponse {
pub async fn handler(
State(ctx): State<ApiContext>,
link: Extension<Link>,
- gmail_token: Extension<String>,
Path(attachment_id): Path<Uuid>,
) -> Result<Json<GetAttachmentDocumentIDResponse>, GetAttachmentDocumentIdError> {
// Fast path: return ID if attachment already exists in Macro
@@ -111,14 +117,12 @@ pub async fn handler(
}));
}
- // Verify access and get owner's link and token
- let (owner_link, access_token) =
- verify_access_and_get_owner(&ctx, &link, gmail_token.0, attachment_id).await?;
+ // Verify access and resolve the owner's link.
+ let owner_link = verify_access_and_get_owner(&ctx, &link, attachment_id).await?;
// Prepare and execute upload to owner's macro account
let upload_args = prepare_upload_args(&ctx, attachment_id).await?;
- let document_id =
- upload_and_get_document_id(&ctx, &owner_link, &access_token, &upload_args).await?;
+ let document_id = upload_and_get_document_id(&ctx, &owner_link, &upload_args).await?;
// _lock released on drop
@@ -128,15 +132,14 @@ pub async fn handler(
}))
}
-/// Verifies access and returns the owner's link and Gmail access token.
-/// If the user is the owner, returns their link and token. Otherwise, verifies shared access
-/// and returns the owner's link and token.
+/// Verifies access and returns the owner's link.
+/// If the user is the owner, returns their link. Otherwise, verifies shared access and resolves
+/// the owner's link.
async fn verify_access_and_get_owner(
ctx: &ApiContext,
link: &Link,
- user_token: String,
attachment_id: Uuid,
-) -> Result<(Link, String), GetAttachmentDocumentIdError> {
+) -> Result<Link, GetAttachmentDocumentIdError> {
let (thread_id, owner_link_id) =
email_db_client::attachments::provider::get_thread_id_for_attachment(
&ctx.db,
@@ -146,9 +149,9 @@ async fn verify_access_and_get_owner(
.map_err(GetAttachmentDocumentIdError::DatabaseError)?
.ok_or(GetAttachmentDocumentIdError::AttachmentNotFound)?;
- // User is the owner, use their link and token directly
+ // User is the owner, use their link directly.
if owner_link_id == link.id {
- return Ok((link.clone(), user_token));
+ return Ok(link.clone());
}
// Verify shared access to the thread
@@ -164,21 +167,10 @@ async fn verify_access_and_get_owner(
.map_err(|e| GetAttachmentDocumentIdError::DatabaseError(anyhow::anyhow!(e)))?
.ok_or(GetAttachmentDocumentIdError::AccessDenied)?;
- // Fetch owner's link and access token
- let owner_link = email_db_client::links::get::fetch_link_by_id(&ctx.db, owner_link_id)
+ email_db_client::links::get::fetch_link_by_id(&ctx.db, owner_link_id)
.await
.map_err(GetAttachmentDocumentIdError::DatabaseError)?
- .ok_or(GetAttachmentDocumentIdError::AttachmentNotFound)?;
-
- let owner_token = fetch_gmail_access_token_from_link(
- &owner_link,
- &ctx.redis_client,
- &ctx.auth_service_client,
- )
- .await
- .map_err(GetAttachmentDocumentIdError::DatabaseError)?;
-
- Ok((owner_link, owner_token))
+ .ok_or(GetAttachmentDocumentIdError::AttachmentNotFound)
}
/// Prepares the upload arguments for an attachment.
@@ -222,17 +214,14 @@ async fn prepare_upload_args(
async fn upload_and_get_document_id(
ctx: &ApiContext,
link: &Link,
- access_token: &str,
upload_args: &AttachmentUploadArgs,
) -> Result<String, GetAttachmentDocumentIdError> {
let ctx_upload = UploadAttachmentContext {
db: &ctx.db,
- redis_client: &ctx.redis_client,
- gmail_client: &ctx.gmail_client,
+ email_api: &ctx.email_api,
dss_client: &ctx.dss_client,
sfs_client: &ctx.sfs_client,
system_properties_service: &ctx.system_properties_service,
- access_token,
link,
};
diff --git a/services/email_service/src/api/email/attachments/mod.rs b/services/email_service/src/api/email/attachments/mod.rs
index 0ef65315c0..369f751de0 100644
--- a/services/email_service/src/api/email/attachments/mod.rs
+++ b/services/email_service/src/api/email/attachments/mod.rs
@@ -16,15 +16,10 @@ pub fn router(state: ApiContext) -> Router<ApiContext> {
let single_inbox_routes = Router::new()
.route("/{id}/document_id", get(get_document_id::handler))
.layer(
- ServiceBuilder::new()
- .layer(axum::middleware::from_fn_with_state(
- state.clone(),
- crate::api::middleware::link::attach_link_context,
- ))
- .layer(axum::middleware::from_fn_with_state(
- state.clone(),
- crate::api::middleware::gmail_token::attach_gmail_token,
- )),
+ ServiceBuilder::new().layer(axum::middleware::from_fn_with_state(
+ state.clone(),
+ crate::api::middleware::link::attach_link_context,
+ )),
);
Router::new()
diff --git a/services/email_service/src/api/email/contacts/list_blocked.rs b/services/email_service/src/api/email/contacts/list_blocked.rs
index d970fb791b..6b44a0638c 100644
--- a/services/email_service/src/api/email/contacts/list_blocked.rs
+++ b/services/email_service/src/api/email/contacts/list_blocked.rs
@@ -3,19 +3,19 @@ use axum::extract::State;
use axum::http::StatusCode;
use axum::response::{IntoResponse, Response};
use axum::{Extension, Json};
-use gmail_client::GmailError;
+use email_api_client::domain::models::EmailApiError;
use model::response::ErrorResponse;
-use strum_macros::AsRefStr;
+use models_email::service::link::Link;
use thiserror::Error;
use utoipa::ToSchema;
-#[derive(Debug, Error, AsRefStr)]
+#[derive(Debug, Error)]
pub enum ListBlockedError {
#[error("Insufficient Gmail permissions. Please re-authenticate to grant the required scope.")]
Forbidden,
- #[error("Gmail API error: {0}")]
- GmailError(String),
+ #[error("Email provider error: {0}")]
+ Provider(EmailApiError),
#[error("Internal error")]
InternalError(#[from] anyhow::Error),
@@ -23,15 +23,20 @@ pub enum ListBlockedError {
impl IntoResponse for ListBlockedError {
fn into_response(self) -> Response {
- let status_code = match &self {
- ListBlockedError::Forbidden => StatusCode::FORBIDDEN,
- ListBlockedError::GmailError(_) | ListBlockedError::InternalError(_) => {
- StatusCode::INTERNAL_SERVER_ERROR
+ let (status_code, headers) = match &self {
+ ListBlockedError::Forbidden => (StatusCode::FORBIDDEN, Default::default()),
+ ListBlockedError::Provider(error) => (
+ crate::api::email::provider_error::provider_error_status(error),
+ crate::api::email::provider_error::provider_error_headers(error),
+ ),
+ ListBlockedError::InternalError(_) => {
+ (StatusCode::INTERNAL_SERVER_ERROR, Default::default())
}
};
(
status_code,
+ headers,
Json(ErrorResponse {
message: self.to_string().into(),
}),
@@ -40,12 +45,12 @@ impl IntoResponse for ListBlockedError {
}
}
-impl From<GmailError> for ListBlockedError {
- fn from(e: GmailError) -> Self {
- match e {
- GmailError::Forbidden => ListBlockedError::Forbidden,
- _ => ListBlockedError::GmailError(e.to_string()),
+impl From<EmailApiError> for ListBlockedError {
+ fn from(error: EmailApiError) -> Self {
+ if matches!(error, EmailApiError::Forbidden) {
+ return ListBlockedError::Forbidden;
}
+ ListBlockedError::Provider(error)
}
}
@@ -66,15 +71,18 @@ pub struct ListBlockedResponse {
(status = 200, body = ListBlockedResponse),
(status = 401, body = ErrorResponse),
(status = 403, body = ErrorResponse),
+ (status = 404, body = ErrorResponse),
+ (status = 409, body = ErrorResponse),
+ (status = 429, body = ErrorResponse),
(status = 500, body = ErrorResponse),
)
)]
-#[tracing::instrument(skip(ctx, gmail_token), err)]
+#[tracing::instrument(skip(ctx, link), fields(link_id = %link.id), err)]
pub async fn handler(
State(ctx): State<ApiContext>,
- gmail_token: Extension<String>,
+ link: Extension<Link>,
) -> Result<Json<ListBlockedResponse>, ListBlockedError> {
- let blocked_emails = ctx.gmail_client.list_blocked_senders(&gmail_token).await?;
+ let blocked_emails = ctx.email_api.list_blocked_senders(link.id).await?;
Ok(Json(ListBlockedResponse { blocked_emails }))
}
diff --git a/services/email_service/src/api/email/contacts/mod.rs b/services/email_service/src/api/email/contacts/mod.rs
index f9d3fa89c9..9eb1b39086 100644
--- a/services/email_service/src/api/email/contacts/mod.rs
+++ b/services/email_service/src/api/email/contacts/mod.rs
@@ -1,7 +1,6 @@
use crate::api::ApiContext;
use axum::Router;
use axum::routing::{get, post};
-use tower::ServiceBuilder;
pub(crate) mod block_sender;
pub(crate) mod list;
@@ -27,11 +26,9 @@ pub fn router(state: ApiContext) -> Router<ApiContext> {
)
.route(
"/blocked",
- get(list_blocked::handler).layer(ServiceBuilder::new().layer(
- axum::middleware::from_fn_with_state(
- state,
- crate::api::middleware::gmail_token::attach_gmail_token,
- ),
+ get(list_blocked::handler).layer(axum::middleware::from_fn_with_state(
+ state,
+ crate::api::middleware::link::attach_link_context,
)),
)
}
diff --git a/services/email_service/src/api/email/init.rs b/services/email_service/src/api/email/init.rs
index c987688da0..82fc9a2759 100644
--- a/services/email_service/src/api/email/init.rs
+++ b/services/email_service/src/api/email/init.rs
@@ -2,7 +2,6 @@ use crate::api::ApiContext;
use crate::api::context::{AuthorizationService, CalendarGrantService};
use crate::utils::extract_email_with_response;
use anyhow::Context;
-use authentication_service_client::error::AuthServiceClientError;
use axum::{
extract::{Query, State},
http::StatusCode,
@@ -13,8 +12,8 @@ use email::domain::events::{EmailMacroEvent, LinkConnectedMetadata};
use email::domain::models::UserProvider;
use email::domain::ports::EmailRepo;
use email::outbound::EmailPgRepo;
+use email_api_client::domain::models::{EmailApiError, TokenFreshness};
use email_service::pubsub::publish_email_event;
-use email_utils::token_cache_key::TokenCacheKey;
use macro_authorization::{MacroAuthorizationExtractor, UserOrInternal};
use macro_user_id::email::EmailStr;
use macro_user_id::user_id::MacroUserIdStr;
@@ -22,7 +21,6 @@ use model::response::ErrorResponse;
use models_email::email::service::backfill::{
BackfillOperation, BackfillPubsubMessage, InitPayload, JobScopedPayload,
};
-use models_email::gmail::error::GmailError;
use models_email::service::link;
use models_email::service::link::Link;
use strum_macros::AsRefStr;
@@ -47,8 +45,8 @@ pub enum InitError {
#[error("Database query error")]
DatabaseError(#[from] anyhow::Error),
- #[error("Gmail API error")]
- GmailError(#[from] models_email::gmail::error::GmailError),
+ #[error("Email provider operation failed")]
+ ProviderError(EmailApiError),
#[error("Bad request")]
BadRequest(String),
@@ -87,7 +85,10 @@ impl InitError {
| InitError::NoGmailGrant
| InitError::BadRequest(_)
| InitError::Parse(_) => StatusCode::BAD_REQUEST,
- InitError::EnqueueError | InitError::DatabaseError(_) | InitError::GmailError(_) => {
+ InitError::ProviderError(EmailApiError::RateLimited { .. }) => {
+ StatusCode::TOO_MANY_REQUESTS
+ }
+ InitError::EnqueueError | InitError::DatabaseError(_) | InitError::ProviderError(_) => {
StatusCode::INTERNAL_SERVER_ERROR
}
InitError::SharedInboxConflict { .. } => StatusCode::CONFLICT,
@@ -186,6 +187,7 @@ pub struct InitParams {
(status = 400, body=InitErrorCodeResponse),
(status = 401, body=ErrorResponse),
(status = 409, body=SharedInboxConflictResponse),
+ (status = 429, body=ErrorResponse),
(status = 500, body=ErrorResponse),
)
)]
@@ -367,9 +369,13 @@ async fn init_user(
.context("child macro user disappeared before self-link bootstrap")?
.to_string();
- let gmail_token =
- fetch_gmail_token_for_email(&ctx, &child_fusion_id, &linked_email).await?;
- let watch_response = register_watch_recovering(&ctx.gmail_client, &gmail_token).await?;
+ let provisional_link =
+ new_gmail_link(child_fusion_id, child_macro_id_owned, linked_email.clone())?;
+ let subscription = ctx
+ .email_api
+ .register_subscription_without_cache(&provisional_link)
+ .await
+ .map_err(classify_provider_init_error)?;
// The link and delegation edge commit atomically. The in-progress grant is
// consumed only after the calendar grant and outbox work are durable.
@@ -379,14 +385,9 @@ async fn init_user(
.await
.context("Failed to begin self-link bootstrap transaction")?;
- let link = enable_gmail_sync_for(
- tx.as_mut(),
- &child_fusion_id,
- child_macro_id_owned,
- &linked_email,
- &watch_response.history_id,
- )
- .await?;
+ let link =
+ enable_gmail_sync_for(tx.as_mut(), provisional_link, subscription.cursor.as_str())
+ .await?;
macro_db_client::macro_user_links::insert_edge(
&mut *tx,
@@ -559,10 +560,16 @@ async fn init_user(
.into_response());
}
- let gmail_token =
- fetch_gmail_token_for_email(&ctx, &user_context.fusion_user_id, &linked_email)
- .await?;
- let watch_response = register_watch_recovering(&ctx.gmail_client, &gmail_token).await?;
+ let provisional_link = new_gmail_link(
+ user_context.fusion_user_id.clone(),
+ macro_user_id.clone(),
+ linked_email.clone(),
+ )?;
+ let subscription = ctx
+ .email_api
+ .register_subscription_without_cache(&provisional_link)
+ .await
+ .map_err(classify_provider_init_error)?;
let mut tx = ctx
.db
@@ -570,14 +577,9 @@ async fn init_user(
.await
.context("Failed to begin link transaction")?;
- let link = enable_gmail_sync_for(
- tx.as_mut(),
- &user_context.fusion_user_id,
- macro_user_id.clone(),
- &linked_email,
- &watch_response.history_id,
- )
- .await?;
+ let link =
+ enable_gmail_sync_for(tx.as_mut(), provisional_link, subscription.cursor.as_str())
+ .await?;
tx.commit()
.await
@@ -602,10 +604,16 @@ async fn init_user(
let email = extract_email_with_response(&user_context.user_id)
.map_err(|_| InitError::BadRequest("Failed to extract email".to_string()))?;
- let gmail_token =
- fetch_gmail_token_for_email(&ctx, &user_context.fusion_user_id, &email).await?;
-
- let watch_response = register_watch_recovering(&ctx.gmail_client, &gmail_token).await?;
+ let provisional_link = new_gmail_link(
+ user_context.fusion_user_id.clone(),
+ macro_user_id.clone(),
+ email,
+ )?;
+ let subscription = ctx
+ .email_api
+ .register_subscription_without_cache(&provisional_link)
+ .await
+ .map_err(classify_provider_init_error)?;
let mut tx = ctx
.db
@@ -613,14 +621,10 @@ async fn init_user(
.await
.context("Failed to begin link transaction")?;
- let link = enable_gmail_sync_for(
- tx.as_mut(),
- &user_context.fusion_user_id,
- macro_user_id.clone(),
- &email,
- &watch_response.history_id,
- )
- .await?;
+ let link =
+ enable_gmail_sync_for(tx.as_mut(), provisional_link, subscription.cursor.as_str())
+ .await?;
+ let email = link.email_address.0.as_ref().to_string();
tx.commit()
.await
@@ -660,6 +664,7 @@ async fn init_user(
link.id,
link.fusionauth_user_id.as_str(),
None,
+ false,
)
.await
.context("Failed to create backfill job")?
@@ -770,12 +775,10 @@ async fn apply_grant_discovered_from_token(ctx: &ApiContext, link: &link::Link)
if !has_unrecorded_google_grant(&ctx.db, link.id).await {
return;
}
- let token = match fetch_gmail_token_for_email(
- ctx,
- &link.fusionauth_user_id,
- link.email_address.0.as_ref(),
- )
- .await
+ let token = match ctx
+ .email_api
+ .get_access_token(link.id, TokenFreshness::Fresh)
+ .await
{
Ok(token) => token,
Err(error) => {
@@ -783,7 +786,7 @@ async fn apply_grant_discovered_from_token(ctx: &ApiContext, link: &link::Link)
return;
}
};
- match fetch_token_scopes(&token).await {
+ match fetch_token_scopes(token.expose_secret()).await {
Ok(scopes) => {
apply_calendar_grant(ctx.calendar_service.as_ref(), link.id, &scopes)
.await
@@ -863,101 +866,27 @@ async fn apply_and_consume_calendar_grant(
Ok(applied)
}
-/// Registers a Gmail watch, recovering from the one-watch-per-mailbox limit. A watch
-/// left over from a prior connect (e.g. a disconnect that could not reach Gmail to stop
-/// it) makes a fresh registration fail with 400 "Only one user push notification client
-/// allowed ... call /stop then try again". On that error we stop the stale watch and
-/// retry once.
-async fn register_watch_recovering(
- client: &gmail_client::GmailClient,
- access_token: &str,
-) -> Result<models_email::gmail::history::WatchResponse, InitError> {
- match client.register_watch(access_token).await {
- Ok(response) => Ok(response),
- Err(GmailError::Conflict(_)) => {
- tracing::warn!("Stale Gmail watch blocks registration; stopping it and retrying");
- client
- .stop_watch(access_token)
- .await
- .context("Failed to stop stale Gmail watch before retry")?;
- client
- .register_watch(access_token)
- .await
- .map_err(classify_watch_error)
+fn classify_provider_init_error(error: EmailApiError) -> InitError {
+ match error {
+ EmailApiError::AuthRequired | EmailApiError::Forbidden => {
+ tracing::debug!("no usable Gmail grant for requested inbox");
+ InitError::NoGmailGrant
}
- Err(e) => Err(classify_watch_error(e)),
- }
-}
-
-/// Maps a watch-registration failure to its init error. Google refreshes tokens
-/// regardless of granted scopes, so a grant missing the Gmail scope passes the
-/// token fetch and is first rejected here with a 403 — an expected outcome
-/// (scope declined at consent), logged at debug so it doesn't page.
-fn classify_watch_error(e: GmailError) -> InitError {
- if matches!(e, GmailError::Forbidden) {
- tracing::debug!("gmail watch rejected for insufficient scope, no usable gmail grant");
- return InitError::NoGmailGrant;
- }
- e.into()
-}
-
-/// Fetches a Gmail access token scoped to a specific linked email. Use this instead
-/// of going through the `UserContext`-keyed path when the target inbox is not the
-/// JWT subject's primary email.
-async fn fetch_gmail_token_for_email(
- ctx: &ApiContext,
- fusion_user_id: &str,
- linked_email: &str,
-) -> Result<String, InitError> {
- let key = TokenCacheKey::new(fusion_user_id, linked_email, UserProvider::Gmail.as_str());
-
- let conn = ctx
- .redis_client
- .inner
- .get_multiplexed_async_connection()
- .await
- .context("unable to connect to redis")?;
-
- email::outbound::fetch_gmail_access_token_no_cache(&key, &conn, &ctx.auth_service_client)
- .await
- .map_err(classify_token_fetch_error)
-}
-
-/// Maps a token-fetch failure to its init error. A 404 from the auth service
-/// means no Gmail grant exists for the requested inbox — an expected outcome
-/// (scope declined or grant removed), logged at debug so it doesn't page.
-fn classify_token_fetch_error(e: anyhow::Error) -> InitError {
- if matches!(
- e.downcast_ref::<AuthServiceClientError>(),
- Some(AuthServiceClientError::NotFound)
- ) {
- tracing::debug!(error=?e, "no gmail grant for requested inbox");
- return InitError::NoGmailGrant;
+ error => InitError::ProviderError(error),
}
- tracing::error!(error=?e, "unable to fetch gmail token for requested inbox");
- InitError::BadRequest("Failed to fetch Gmail token".to_string())
}
-/// Upserts the `email_links` row and seeds the gmail history entry for an already-registered
-/// Gmail watch. Runs on a caller-provided connection so the writes can join a wider
-/// transaction; callers register the watch (external IO) beforehand and pass its `history_id`.
-/// Caller-provided identifiers let this serve the JWT-driven new-user signup, the
-/// `link_id`-driven add-inbox flow, and the self-link bootstrap (where both `macro_id`
-/// and `fusion_user_id` are the child's — the grant lives with the mailbox's own account).
-#[tracing::instrument(skip(conn), err)]
-async fn enable_gmail_sync_for(
- conn: &mut sqlx::PgConnection,
- fusion_user_id: &str,
+fn new_gmail_link(
+ fusion_user_id: String,
macro_id: MacroUserIdStr<'static>,
- email_address: &str,
- history_id: &str,
+ email_address: String,
) -> Result<Link, InitError> {
- let email_address = EmailStr::try_from(email_address.to_string())?;
- let is_primary = link::Link::derive_is_primary(&macro_id, &email_address);
- let link = link::Link {
+ let email_address = EmailStr::try_from(email_address)?;
+ let is_primary = Link::derive_is_primary(&macro_id, &email_address);
+ Ok(Link {
id: macro_uuid::generate_uuid_v7(),
macro_id,
- fusionauth_user_id: fusion_user_id.to_string(),
+ fusionauth_user_id: fusion_user_id,
email_address,
provider: link::UserProvider::Gmail,
is_sync_active: true,
@@ -966,8 +895,16 @@ async fn enable_gmail_sync_for(
last_sync_error_at: None,
created_at: Default::default(),
updated_at: Default::default(),
- };
+ })
+}
+/// Persists a provisionally registered link and its initial provider cursor atomically.
+#[tracing::instrument(skip(conn), err)]
+async fn enable_gmail_sync_for(
+ conn: &mut sqlx::PgConnection,
+ link: Link,
+ history_id: &str,
+) -> Result<Link, InitError> {
let link = email_db_client::links::insert::upsert_link(&mut *conn, link)
.await
.context("Failed to upsert link")?;
diff --git a/services/email_service/src/api/email/init/test.rs b/services/email_service/src/api/email/init/test.rs
index 9903ffa605..53904fac93 100644
--- a/services/email_service/src/api/email/init/test.rs
+++ b/services/email_service/src/api/email/init/test.rs
@@ -1,5 +1,4 @@
use super::*;
-use anyhow::anyhow;
use macro_db_migrator::MACRO_DB_MIGRATIONS;
use sqlx::PgPool;
@@ -87,48 +86,34 @@ async fn already_initialized_is_a_coded_400() {
}
#[test]
-fn auth_service_not_found_classifies_as_no_gmail_grant() {
- let err = anyhow::Error::new(AuthServiceClientError::NotFound)
- .context("Failed to get Google access token from auth service");
- assert!(matches!(
- classify_token_fetch_error(err),
- InitError::NoGmailGrant
- ));
-}
-
-#[test]
-fn other_token_fetch_failures_stay_bad_request() {
- for err in [
- anyhow!("connection refused"),
- anyhow::Error::new(AuthServiceClientError::Unauthorized),
- ] {
+fn unusable_provider_grants_classify_as_no_gmail_grant() {
+ for error in [EmailApiError::AuthRequired, EmailApiError::Forbidden] {
assert!(matches!(
- classify_token_fetch_error(err),
- InitError::BadRequest(_)
+ classify_provider_init_error(error),
+ InitError::NoGmailGrant
));
}
}
#[test]
-fn watch_forbidden_classifies_as_no_gmail_grant() {
- assert!(matches!(
- classify_watch_error(GmailError::Forbidden),
- InitError::NoGmailGrant
- ));
+fn rate_limiting_classifies_as_http_429() {
+ let error = classify_provider_init_error(EmailApiError::RateLimited {
+ retry_after: None,
+ origin: email_api_client::domain::models::RateLimitOrigin::Provider,
+ });
+ assert_eq!(error.status_code(), StatusCode::TOO_MANY_REQUESTS);
}
-#[test]
-fn other_watch_failures_stay_gmail_errors() {
- for err in [
- GmailError::Unauthorized,
- GmailError::RateLimitExceeded,
- GmailError::ApiError("(500): boom".to_string()),
- ] {
- assert!(matches!(
- classify_watch_error(err),
- InitError::GmailError(_)
- ));
- }
+#[tokio::test]
+async fn provider_diagnostics_are_not_returned_to_clients() {
+ let response = InitError::ProviderError(EmailApiError::Permanent {
+ message: "sanitized provider body".to_string(),
+ })
+ .into_response();
+ let bytes = axum::body::to_bytes(response.into_body(), usize::MAX)
+ .await
+ .unwrap();
+ assert_eq!(bytes, "Email provider operation failed");
}
#[test]
@@ -150,7 +135,7 @@ fn only_shared_inbox_conflict_keeps_the_in_progress_link() {
InitError::NoGmailGrant,
InitError::EnqueueError,
InitError::BadRequest("bad".to_string()),
- InitError::GmailError(GmailError::Unauthorized),
+ InitError::ProviderError(EmailApiError::AuthRequired),
] {
assert!(
should_clean_up_in_progress_link(&err),
diff --git a/services/email_service/src/api/email/labels/create.rs b/services/email_service/src/api/email/labels/create.rs
index 3d8065c369..596d60efeb 100644
--- a/services/email_service/src/api/email/labels/create.rs
+++ b/services/email_service/src/api/email/labels/create.rs
@@ -32,39 +32,40 @@ pub struct CreateLabelResponse {
(status = 201, body=CreateLabelResponse),
(status = 400, body=ErrorResponse),
(status = 401, body=ErrorResponse),
+ (status = 403, body=ErrorResponse),
+ (status = 404, body=ErrorResponse),
(status = 409, body=ErrorResponse),
+ (status = 429, body=ErrorResponse),
(status = 500, body=ErrorResponse),
)
)]
-#[tracing::instrument(skip(ctx, authorization, link, gmail_token), fields(user_id=authorization.authorization.user.user_context.user_id, fusionauth_user_id=authorization.authorization.user.user_context.fusion_user_id))]
+#[tracing::instrument(skip(ctx, authorization, link), fields(user_id=authorization.authorization.user.user_context.user_id, fusionauth_user_id=authorization.authorization.user.user_context.fusion_user_id))]
pub async fn handler(
State(ctx): State<ApiContext>,
authorization: MacroAuthorizationExtractor<AuthorizationService, UserOrInternal>,
link: Extension<Link>,
- gmail_token: Extension<String>,
Json(request_body): Json<CreateLabelRequest>,
) -> Result<Response, Response> {
let created_label = ctx
- .gmail_client
- .create_label(gmail_token.as_str(), link.id, &request_body.label_name)
+ .email_api
+ .create_label(link.id, &request_body.label_name)
.await
.map_err(|e| {
- tracing::error!(error=?e, "gmail call to create label failed");
- match e {
- gmail_client::GmailError::Conflict(_) => (
- StatusCode::CONFLICT,
- Json(ErrorResponse {
- message: "label with that name already exists".into(),
- }),
- ),
- _ => (
- StatusCode::INTERNAL_SERVER_ERROR,
- Json(ErrorResponse {
- message: "create label call failed".into(),
- }),
- ),
- }
- .into_response()
+ tracing::error!(error=?e, "email provider call to create label failed");
+ let status = crate::api::email::provider_error::provider_error_status(&e);
+ let message = if status == StatusCode::CONFLICT {
+ "label with that name already exists"
+ } else {
+ "create label call failed"
+ };
+ (
+ status,
+ crate::api::email::provider_error::provider_error_headers(&e),
+ Json(ErrorResponse {
+ message: message.into(),
+ }),
+ )
+ .into_response()
})?;
let inserted_label = email_db_client::labels::insert::insert_label(&ctx.db, created_label)
diff --git a/services/email_service/src/api/email/labels/mod.rs b/services/email_service/src/api/email/labels/mod.rs
index 9c7a760dbd..cc1afe49a4 100644
--- a/services/email_service/src/api/email/labels/mod.rs
+++ b/services/email_service/src/api/email/labels/mod.rs
@@ -14,13 +14,7 @@ pub fn router(state: ApiContext) -> Router<ApiContext> {
>();
Router::new()
- .route(
- "/",
- post(create::handler).layer(axum::middleware::from_fn_with_state(
- state.clone(),
- crate::api::middleware::gmail_token::attach_gmail_token,
- )),
- )
+ .route("/", post(create::handler))
.route("/{id}", delete(delete::handler))
.layer(axum::middleware::from_fn_with_state(
state.clone(),
diff --git a/services/email_service/src/api/email/links/health_check.rs b/services/email_service/src/api/email/links/health_check.rs
index 972ea0fd9c..29bc54cde5 100644
--- a/services/email_service/src/api/email/links/health_check.rs
+++ b/services/email_service/src/api/email/links/health_check.rs
@@ -2,9 +2,7 @@ use crate::api::context::{ApiContext, AuthorizationService};
use axum::extract::State;
use axum::http::StatusCode;
use axum::response::{IntoResponse, Json, Response};
-use email_service::util::gmail::auth::{
- fetch_token_or_mark_reauth_no_cache, is_reauth_required_error,
-};
+use email_api_client::domain::models::{EmailApiError, TokenFreshness};
use macro_authorization::{MacroAuthorizationExtractor, UserOrInternal};
use model::response::{EmptyResponse, ErrorResponse};
use models_email::email::service::pubsub::LinkManagerMessage;
@@ -38,7 +36,7 @@ impl IntoResponse for HealthCheckError {
/// against the auth service and records the result on each link. A grant that died
/// while the caller was inactive is detected here within minutes instead of waiting on
/// the daily refresh sweep; the side effects (clearing or setting the reauth flag, and
-/// the one-time reauth fan-out) are handled by `fetch_token_or_mark_reauth_no_cache`.
+/// the one-time reauth fan-out) are handled by the email service token source.
///
/// Probes run in the background and the response returns immediately to stay off the
/// load path; each persisted flag is picked up by the next links read. Probes are
@@ -82,19 +80,15 @@ pub async fn health_check_handler(
return;
}
- let probe = fetch_token_or_mark_reauth_no_cache(
- &link,
- &ctx.db,
- &ctx.redis_client,
- &ctx.auth_service_client,
- &ctx.sqs_client,
- )
- .await;
+ let probe = ctx
+ .email_api
+ .get_access_token(link.id, TokenFreshness::Fresh)
+ .await;
- let Err(e) = probe else { return };
+ let Err(error) = probe else { return };
- if !is_reauth_required_error(&e) {
- tracing::debug!(error=?e, link_id=%link.id, "Health probe token fetch failed");
+ if !matches!(error, EmailApiError::AuthRequired) {
+ tracing::debug!(error=?error, link_id=%link.id, "Health probe token fetch failed");
return;
}
diff --git a/services/email_service/src/api/email/links/resync.rs b/services/email_service/src/api/email/links/resync.rs
index 9f0ac326be..8254b4b107 100644
--- a/services/email_service/src/api/email/links/resync.rs
+++ b/services/email_service/src/api/email/links/resync.rs
@@ -71,6 +71,7 @@ pub async fn resync_link_handler(
link.id,
link.fusionauth_user_id.as_str(),
None,
+ false,
)
.await
.context("failed to create backfill job")?
diff --git a/services/email_service/src/api/email/mod.rs b/services/email_service/src/api/email/mod.rs
index 1f5a7a8f7e..242a8a49d1 100644
--- a/services/email_service/src/api/email/mod.rs
+++ b/services/email_service/src/api/email/mod.rs
@@ -12,6 +12,7 @@ pub(crate) mod init;
pub(crate) mod labels;
pub(crate) mod links;
pub(crate) mod messages;
+pub(crate) mod provider_error;
pub(crate) mod settings;
pub(crate) mod sync;
pub(crate) mod threads;
diff --git a/services/email_service/src/api/email/provider_error.rs b/services/email_service/src/api/email/provider_error.rs
new file mode 100644
index 0000000000..7f2a6f50cb
--- /dev/null
+++ b/services/email_service/src/api/email/provider_error.rs
@@ -0,0 +1,34 @@
+use axum::http::header::RETRY_AFTER;
+use axum::http::{HeaderMap, HeaderValue, StatusCode};
+use email_api_client::domain::models::EmailApiError;
+
+#[cfg(test)]
+mod test;
+
+/// Response headers implied by a provider error: rate-limited requests carry
+/// the provider's suggested delay as a `Retry-After` header when known.
+pub(crate) fn provider_error_headers(error: &EmailApiError) -> HeaderMap {
+ let mut headers = HeaderMap::new();
+ if let EmailApiError::RateLimited {
+ retry_after: Some(delay),
+ ..
+ } = error
+ && let Ok(value) = HeaderValue::from_str(&delay.as_secs().to_string())
+ {
+ headers.insert(RETRY_AFTER, value);
+ }
+ headers
+}
+
+pub(crate) fn provider_error_status(error: &EmailApiError) -> StatusCode {
+ match error {
+ EmailApiError::RateLimited { .. } => StatusCode::TOO_MANY_REQUESTS,
+ EmailApiError::AuthRequired => StatusCode::UNAUTHORIZED,
+ EmailApiError::Forbidden => StatusCode::FORBIDDEN,
+ EmailApiError::NotFound => StatusCode::NOT_FOUND,
+ EmailApiError::Conflict | EmailApiError::OutdatedCursor => StatusCode::CONFLICT,
+ EmailApiError::Transient { .. } | EmailApiError::Permanent { .. } => {
+ StatusCode::INTERNAL_SERVER_ERROR
+ }
+ }
+}
diff --git a/services/email_service/src/api/email/provider_error/test.rs b/services/email_service/src/api/email/provider_error/test.rs
new file mode 100644
index 0000000000..c35e9683c2
--- /dev/null
+++ b/services/email_service/src/api/email/provider_error/test.rs
@@ -0,0 +1,67 @@
+use std::time::Duration;
+
+use email_api_client::domain::models::RateLimitOrigin;
+
+use super::*;
+
+#[test]
+fn maps_provider_errors_to_api_statuses() {
+ let cases = [
+ (
+ EmailApiError::RateLimited {
+ retry_after: Some(Duration::from_secs(10)),
+ origin: RateLimitOrigin::Provider,
+ },
+ StatusCode::TOO_MANY_REQUESTS,
+ ),
+ (EmailApiError::AuthRequired, StatusCode::UNAUTHORIZED),
+ (EmailApiError::Forbidden, StatusCode::FORBIDDEN),
+ (EmailApiError::NotFound, StatusCode::NOT_FOUND),
+ (EmailApiError::Conflict, StatusCode::CONFLICT),
+ (
+ EmailApiError::Transient {
+ message: "provider unavailable".to_string(),
+ },
+ StatusCode::INTERNAL_SERVER_ERROR,
+ ),
+ (
+ EmailApiError::Permanent {
+ message: "invalid provider response".to_string(),
+ },
+ StatusCode::INTERNAL_SERVER_ERROR,
+ ),
+ ];
+
+ for (error, expected_status) in cases {
+ assert_eq!(provider_error_status(&error), expected_status);
+ }
+}
+
+#[test]
+fn maps_outdated_cursor_to_conflict() {
+ assert_eq!(
+ provider_error_status(&EmailApiError::OutdatedCursor),
+ StatusCode::CONFLICT
+ );
+}
+
+#[test]
+fn rate_limited_responses_carry_a_retry_after_header_when_known() {
+ let headers = provider_error_headers(&EmailApiError::RateLimited {
+ retry_after: Some(Duration::from_secs(42)),
+ origin: RateLimitOrigin::Provider,
+ });
+ assert_eq!(
+ headers.get(RETRY_AFTER).and_then(|v| v.to_str().ok()),
+ Some("42")
+ );
+
+ assert!(
+ provider_error_headers(&EmailApiError::RateLimited {
+ retry_after: None,
+ origin: RateLimitOrigin::Provider,
+ })
+ .is_empty()
+ );
+ assert!(provider_error_headers(&EmailApiError::NotFound).is_empty());
+}
diff --git a/services/email_service/src/api/email/settings/patch.rs b/services/email_service/src/api/email/settings/patch.rs
index 473c3fe07e..eea85fd010 100644
--- a/services/email_service/src/api/email/settings/patch.rs
+++ b/services/email_service/src/api/email/settings/patch.rs
@@ -3,8 +3,8 @@ use axum::extract::State;
use axum::http::StatusCode;
use axum::response::{IntoResponse, Response};
use axum::{Extension, Json};
+use email_api_client::outbound::gmail::sanitize_html_fragment;
use email_service::util::process_pre_insert::sfs_map;
-use email_service::util::sanitizer::sanitize_html_fragment;
use model::response::ErrorResponse;
use models_email::service::link::Link;
use models_email::{api, service};
diff --git a/services/email_service/src/api/email/sync/mod.rs b/services/email_service/src/api/email/sync/mod.rs
index e28f3538e7..60d0141121 100644
--- a/services/email_service/src/api/email/sync/mod.rs
+++ b/services/email_service/src/api/email/sync/mod.rs
@@ -2,23 +2,15 @@ use crate::api::ApiContext;
use crate::api::email::sync::disable::disable_handler;
use axum::Router;
use axum::routing::delete;
-use tower::ServiceBuilder;
pub(crate) mod disable;
pub fn router(state: ApiContext) -> Router<ApiContext> {
Router::new().route(
"/",
- delete(disable_handler).layer(
- ServiceBuilder::new()
- .layer(axum::middleware::from_fn_with_state(
- state.clone(),
- crate::api::middleware::gmail_token::attach_gmail_token,
- ))
- .layer(axum::middleware::from_fn_with_state(
- state.clone(),
- crate::api::middleware::link::attach_link_context,
- )),
- ),
+ delete(disable_handler).layer(axum::middleware::from_fn_with_state(
+ state,
+ crate::api::middleware::link::attach_link_context,
+ )),
)
}
diff --git a/services/email_service/src/api/internal/gmail/create.rs b/services/email_service/src/api/internal/gmail/create.rs
index 843a0e5327..2e83369ee4 100644
--- a/services/email_service/src/api/internal/gmail/create.rs
+++ b/services/email_service/src/api/internal/gmail/create.rs
@@ -77,6 +77,7 @@ pub async fn handler(
link.id,
link.fusionauth_user_id.as_str(),
req_body.num_threads,
+ false,
)
.await
.map_err(|e| {
diff --git a/services/email_service/src/api/middleware/gmail_token.rs b/services/email_service/src/api/middleware/gmail_token.rs
deleted file mode 100644
index 9c8fb3f6d0..0000000000
--- a/services/email_service/src/api/middleware/gmail_token.rs
+++ /dev/null
@@ -1,23 +0,0 @@
-use axum::extract::State;
-use axum::{extract::Request, middleware::Next, response::Response};
-use macro_authorization::{MacroAuthorizationExtractor, UserOrInternal};
-
-use crate::api::context::{ApiContext, AuthorizationService};
-use email_service::util::gmail::auth::fetch_gmail_token_usercontext_response;
-
-pub(in crate::api) async fn attach_gmail_token(
- State(ctx): State<ApiContext>,
- authorization: MacroAuthorizationExtractor<AuthorizationService, UserOrInternal>,
- mut req: Request,
- next: Next,
-) -> Result<Response, Response> {
- let gmail_token = fetch_gmail_token_usercontext_response(
- &authorization.authorization.user.user_context,
- &ctx.redis_client,
- &ctx.auth_service_client,
- )
- .await?;
-
- req.extensions_mut().insert(gmail_token);
- Ok(next.run(req).await)
-}
diff --git a/services/email_service/src/api/middleware/mod.rs b/services/email_service/src/api/middleware/mod.rs
index ef44aa4b3e..92bc13e7cd 100644
--- a/services/email_service/src/api/middleware/mod.rs
+++ b/services/email_service/src/api/middleware/mod.rs
@@ -1,2 +1 @@
-pub mod gmail_token;
pub mod link;
diff --git a/services/email_service/src/backfill_init_service.rs b/services/email_service/src/backfill_init_service.rs
index 426ae22cef..1bdb81ad8e 100644
--- a/services/email_service/src/backfill_init_service.rs
+++ b/services/email_service/src/backfill_init_service.rs
@@ -1,22 +1,20 @@
use crate::backfill_completion_service;
+use crate::pubsub::backfill::email_api_error::map_email_api_error;
use crate::pubsub::context::PubSubContext;
-use crate::pubsub::util::{CheckGmailRateLimitArgs, check_gmail_rate_limit};
use crate::util::process_pre_insert::sync_labels::sync_labels;
use crate::util::sync_contacts::sync_contacts;
use email_db_client::backfill::job::update::{InitLeaseClaim, InitLeaseRenewal};
use models_email::email::service::backfill::{InitPayload, JobScopedPayload};
use models_email::email::service::pubsub::{DetailedError, FailureReason, ProcessingError};
use models_email::email::service::{backfill, link};
-use models_email::gmail::operations::GmailApiOperation;
use std::cmp::min;
use uuid::Uuid;
/// This step is invoked via the API when a new job is created.
/// Populates total_threads value in backfill_job row, and sends the first ListThreads message.
-#[tracing::instrument(skip(ctx, access_token))]
+#[tracing::instrument(skip(ctx))]
pub async fn init_backfill(
ctx: &PubSubContext,
- access_token: &str,
scope: &JobScopedPayload<InitPayload>,
link: &link::Link,
backfill_job: &backfill::BackfillJob,
@@ -37,8 +35,7 @@ pub async fn init_backfill(
}
};
- let initialization =
- initialize_backfill(ctx, access_token, scope, link, backfill_job, lease_token);
+ let initialization = initialize_backfill(ctx, scope, link, backfill_job, lease_token);
tokio::pin!(initialization);
let heartbeat = maintain_init_lease(ctx.db.clone(), scope.job_id, lease_token);
tokio::pin!(heartbeat);
@@ -68,7 +65,6 @@ pub async fn init_backfill(
async fn initialize_backfill(
ctx: &PubSubContext,
- access_token: &str,
scope: &JobScopedPayload<InitPayload>,
link: &link::Link,
backfill_job: &backfill::BackfillJob,
@@ -77,22 +73,24 @@ async fn initialize_backfill(
tracing::info!("Initializing backfill job");
// ensure we have the user's labels in the db
- sync_labels(&ctx.db, &ctx.gmail_client, access_token, link.id)
+ let labels = ctx
+ .email_api
+ .list_labels(link.id)
.await
- .map_err(|e| {
- ProcessingError::Retryable(DetailedError {
- reason: FailureReason::DatabaseQueryFailed,
- source: e.context("Failed to sync labels"),
- })
- })?;
+ .map_err(|error| map_email_api_error(error, "Failed to list provider labels"))?;
+ sync_labels(&ctx.db, link.id, &labels).await.map_err(|e| {
+ ProcessingError::Retryable(DetailedError {
+ reason: FailureReason::DatabaseQueryFailed,
+ source: e.context("Failed to reconcile labels"),
+ })
+ })?;
if let Err(e) = sync_contacts(
link,
&ctx.db,
- &ctx.gmail_client,
+ &ctx.email_api,
&ctx.sqs_client,
&ctx.macro_event_broker,
- access_token,
)
.await
{
@@ -101,29 +99,18 @@ async fn initialize_backfill(
let threads_requested_limit = backfill_job.threads_requested_limit;
- check_gmail_rate_limit(CheckGmailRateLimitArgs {
- redis_client: &ctx.redis_client,
- link_id: link.id,
- gmail_operation: GmailApiOperation::UsersGetProfile,
- retryable: true,
- is_backfill: true,
- })
- .await?;
// get the total number of threads the user has in their account
- let total_threads = match ctx
- .gmail_client
- .get_profile_threads_total(access_token)
+ let total_threads = ctx
+ .email_api
+ .get_thread_count(link.id)
.await
- {
- Ok(list) => list,
- Err(e) => {
- // Construct the structured Retryable error and return immediately.
- return Err(ProcessingError::Retryable(DetailedError {
- reason: FailureReason::GmailApiFailed,
- source: e.context("Failed to get total threads from Gmail API"),
- }));
- }
- };
+ .map_err(|error| map_email_api_error(error, "Failed to get provider thread count"))?;
+ let total_threads = i32::try_from(total_threads).map_err(|error| {
+ ProcessingError::NonRetryable(DetailedError {
+ reason: FailureReason::InvalidData,
+ source: anyhow::Error::new(error).context("Provider thread count exceeds i32"),
+ })
+ })?;
// If thread count is not specified, populate all available threads. Otherwise,
// populate up to the requested number or total available, whichever is smaller
diff --git a/services/email_service/src/bin/backfill_gmail_attachments/backfill_gmail_attachments.rs b/services/email_service/src/bin/backfill_gmail_attachments/backfill_gmail_attachments.rs
index f66e11446c..d9a6c9bf85 100644
--- a/services/email_service/src/bin/backfill_gmail_attachments/backfill_gmail_attachments.rs
+++ b/services/email_service/src/bin/backfill_gmail_attachments/backfill_gmail_attachments.rs
@@ -39,7 +39,8 @@ async fn main() -> anyhow::Result<()> {
config.internal_auth_key.clone(),
config.dss_url.clone(),
);
- let gmail_client = gmail_client::GmailClient::new("unused".to_string());
+ let email_api_repository =
+ email_api_client::GmailApiClientRepository::from_subscription_topic("unused");
let macro_ids: Vec<String> = config
.macro_ids
@@ -57,8 +58,14 @@ async fn main() -> anyhow::Result<()> {
macro_ids.len()
);
- match process::process_macro_id(&config, &db_pool, &dss_client, &gmail_client, macro_id)
- .await
+ match process::process_macro_id(
+ &config,
+ &db_pool,
+ &dss_client,
+ &email_api_repository,
+ macro_id,
+ )
+ .await
{
Ok((success_count, total_attachments)) => {
println!(
diff --git a/services/email_service/src/bin/backfill_gmail_attachments/process.rs b/services/email_service/src/bin/backfill_gmail_attachments/process.rs
index 1fa91ea8a4..c16df39bfb 100644
--- a/services/email_service/src/bin/backfill_gmail_attachments/process.rs
+++ b/services/email_service/src/bin/backfill_gmail_attachments/process.rs
@@ -1,6 +1,10 @@
use crate::upload::AttachmentProcessor;
use crate::{auth, config, database, upload};
use anyhow::Context;
+use email_api_client::GmailApiClientRepository;
+use email_api_client::domain::ports::AlwaysAllowRateLimiter;
+use email_api_client::domain::service::EmailApiClientServiceImpl;
+use email_service::outbound::email_api::StaticTokenSource;
use futures::{StreamExt, stream};
use std::sync::Arc;
use std::sync::atomic::{AtomicUsize, Ordering};
@@ -10,25 +14,24 @@ pub async fn process_macro_id(
config: &config::Config,
db_pool: &sqlx::PgPool,
dss_client: &document_storage_service_client::DocumentStorageServiceClient,
- gmail_client: &gmail_client::GmailClient,
+ email_api_repository: &GmailApiClientRepository,
macro_id: &str,
) -> anyhow::Result<(usize, usize)> {
// Get fresh Gmail access token for this macro ID
let gmail_access_token = auth::get_gmail_access_token(config, macro_id).await?;
println!("Successfully obtained Gmail access token for {}", macro_id);
- // Fetch the link_id associated with the user's account.
- let link_id = email_db_client::links::get::fetch_link_by_macro_id(db_pool, macro_id)
+ // Fetch the link associated with the user's account.
+ let link = email_db_client::links::get::fetch_link_by_macro_id(db_pool, macro_id)
.await?
- .ok_or_else(|| anyhow::anyhow!("No link found for macro ID: {}", macro_id))?
- .id;
+ .ok_or_else(|| anyhow::anyhow!("No link found for macro ID: {}", macro_id))?;
// Fetch all relevant attachment metadata from the database.
println!(
"Fetching unique attachment metadata from database for {}...",
macro_id
);
- let attachments = database::fetch_unique_attachments(db_pool, link_id)
+ let attachments = database::fetch_unique_attachments(db_pool, link.id)
.await
.context("Failed to fetch attachment metadata")?;
println!(
@@ -42,11 +45,15 @@ pub async fn process_macro_id(
}
// Process and upload each attachment.
+ let email_api = EmailApiClientServiceImpl::new(
+ email_api_repository.clone(),
+ StaticTokenSource::new(gmail_access_token),
+ AlwaysAllowRateLimiter,
+ );
let processor = Arc::new(upload::AttachmentProcessor::new(
db_pool.clone(),
dss_client.clone(),
- gmail_client.clone(),
- gmail_access_token,
+ email_api,
macro_id.to_string(),
));
@@ -60,9 +67,10 @@ pub async fn process_macro_id(
let processor: Arc<AttachmentProcessor> = Arc::clone(&processor);
let success_count = Arc::clone(&success_count);
let macro_id = macro_id.to_string();
+ let link = link.clone();
async move {
- match processor.upload(link_id, &attachment).await {
+ match processor.upload(&link, &attachment).await {
Ok(_) => {
success_count.fetch_add(1, Ordering::Relaxed);
println!("Successfully uploaded '{}' (index: {}) for {}", attachment.filename.unwrap_or("N/A".to_string()), index, macro_id);
diff --git a/services/email_service/src/bin/backfill_gmail_attachments/upload.rs b/services/email_service/src/bin/backfill_gmail_attachments/upload.rs
index abe207c7cb..fe0cc77320 100644
--- a/services/email_service/src/bin/backfill_gmail_attachments/upload.rs
+++ b/services/email_service/src/bin/backfill_gmail_attachments/upload.rs
@@ -1,18 +1,25 @@
use anyhow::{Context, bail};
use base64::{Engine as _, engine::general_purpose::STANDARD};
+use email_api_client::GmailApiClientRepository;
+use email_api_client::domain::ports::AlwaysAllowRateLimiter;
+use email_api_client::domain::service::EmailApiClientServiceImpl;
+use email_service::outbound::email_api::StaticTokenSource;
use model::document::response::CreateDocumentRequest;
+use models_email::email::service::link::Link;
use models_email::service::attachment::AttachmentUploadMetadata;
use sha2::{Digest, Sha256};
use sqlx::PgPool;
use tracing::instrument;
-use uuid::Uuid;
/// A helper struct to manage clients and tokens required for processing.
pub struct AttachmentProcessor {
db: PgPool,
dss_client: document_storage_service_client::DocumentStorageServiceClient,
- gmail_client: gmail_client::GmailClient,
- gmail_access_token: String,
+ email_api: EmailApiClientServiceImpl<
+ GmailApiClientRepository,
+ StaticTokenSource,
+ AlwaysAllowRateLimiter,
+ >,
macro_id_destination: String,
}
@@ -20,15 +27,17 @@ impl AttachmentProcessor {
pub fn new(
db: PgPool,
dss_client: document_storage_service_client::DocumentStorageServiceClient,
- gmail_client: gmail_client::GmailClient,
- gmail_access_token: String,
+ email_api: EmailApiClientServiceImpl<
+ GmailApiClientRepository,
+ StaticTokenSource,
+ AlwaysAllowRateLimiter,
+ >,
macro_id_destination: String,
) -> Self {
Self {
db,
dss_client,
- gmail_client,
- gmail_access_token,
+ email_api,
macro_id_destination,
}
}
@@ -37,12 +46,12 @@ impl AttachmentProcessor {
#[instrument(skip(self), fields(file_name = ?attachment.filename, mime_type = %attachment.mime_type))]
pub async fn upload(
&self,
- link_id: Uuid,
+ link: &Link,
attachment: &AttachmentUploadMetadata,
) -> anyhow::Result<()> {
let exists = email_db_client::attachments::provider::get_document_id_by_att_id_and_link(
&self.db,
- link_id,
+ link.id,
attachment.attachment_db_id,
)
.await?
@@ -56,7 +65,7 @@ impl AttachmentProcessor {
}
// 1. Fetch attachment data from Gmail.
- let data = self.fetch_gmail_data(attachment).await?;
+ let data = self.fetch_attachment(link, attachment).await?;
// 2. Calculate hashes required for validation.
let (sha256_hex, sha256_base64) = Self::calculate_hashes(&data);
@@ -71,19 +80,20 @@ impl AttachmentProcessor {
Ok(())
}
- /// Fetches the raw attachment data from the Gmail API.
- async fn fetch_gmail_data(
+ /// Fetches the raw attachment data from the email provider.
+ async fn fetch_attachment(
&self,
+ link: &Link,
attachment: &AttachmentUploadMetadata,
) -> anyhow::Result<Vec<u8>> {
- self.gmail_client
- .get_attachment_data(
- &self.gmail_access_token,
+ self.email_api
+ .get_attachment(
+ link.id,
&attachment.email_provider_id,
&attachment.provider_attachment_id,
)
.await
- .context("Failed to get attachment data from Gmail")
+ .context("Failed to get attachment data from email provider")
}
/// Calculates the hex and base64 encoded SHA256 hash of the attachment data.
diff --git a/services/email_service/src/bin/backfill_sfs_attachments/backfill_sfs_attachments.rs b/services/email_service/src/bin/backfill_sfs_attachments/backfill_sfs_attachments.rs
index 51f28c38a4..1d9a69a900 100644
--- a/services/email_service/src/bin/backfill_sfs_attachments/backfill_sfs_attachments.rs
+++ b/services/email_service/src/bin/backfill_sfs_attachments/backfill_sfs_attachments.rs
@@ -41,7 +41,8 @@ async fn main() -> anyhow::Result<()> {
config.sfs_url.clone(),
);
- let gmail_client = gmail_client::GmailClient::new("unused".to_string());
+ let email_api_repository =
+ email_api_client::GmailApiClientRepository::from_subscription_topic("unused");
let macro_ids: Vec<String> = config
.macro_ids
@@ -60,8 +61,14 @@ async fn main() -> anyhow::Result<()> {
chrono::Local::now().format("%Y-%m-%d %H:%M:%S")
);
- match process::process_macro_id(&config, &db_pool, &sfs_client, &gmail_client, macro_id)
- .await
+ match process::process_macro_id(
+ &config,
+ &db_pool,
+ &sfs_client,
+ &email_api_repository,
+ macro_id,
+ )
+ .await
{
Ok((success_count, total_attachments)) => {
println!(
diff --git a/services/email_service/src/bin/backfill_sfs_attachments/process.rs b/services/email_service/src/bin/backfill_sfs_attachments/process.rs
index 6e7b91c7f4..4ab17786e6 100644
--- a/services/email_service/src/bin/backfill_sfs_attachments/process.rs
+++ b/services/email_service/src/bin/backfill_sfs_attachments/process.rs
@@ -1,6 +1,10 @@
use crate::upload::AttachmentProcessor;
use crate::{auth, config, database, upload};
use anyhow::Context;
+use email_api_client::GmailApiClientRepository;
+use email_api_client::domain::ports::AlwaysAllowRateLimiter;
+use email_api_client::domain::service::EmailApiClientServiceImpl;
+use email_service::outbound::email_api::StaticTokenSource;
use futures::{StreamExt, stream};
use std::sync::Arc;
use std::sync::atomic::{AtomicUsize, Ordering};
@@ -10,7 +14,7 @@ pub async fn process_macro_id(
config: &config::Config,
db_pool: &sqlx::PgPool,
sfs_client: &static_file_service_client::StaticFileServiceClient,
- gmail_client: &gmail_client::GmailClient,
+ email_api_repository: &GmailApiClientRepository,
macro_id: &str,
) -> anyhow::Result<(usize, usize)> {
// Fetch all relevant attachment metadata from the database.
@@ -35,12 +39,20 @@ pub async fn process_macro_id(
let gmail_access_token = auth::get_gmail_access_token(config, macro_id).await?;
println!("Successfully obtained Gmail access token for {}", macro_id);
+ let link = email_db_client::links::get::fetch_link_by_macro_id(db_pool, macro_id)
+ .await?
+ .ok_or_else(|| anyhow::anyhow!("No link found for macro ID: {}", macro_id))?;
+
// Process and upload each attachment.
+ let email_api = EmailApiClientServiceImpl::new(
+ email_api_repository.clone(),
+ StaticTokenSource::new(gmail_access_token),
+ AlwaysAllowRateLimiter,
+ );
let processor = Arc::new(upload::AttachmentProcessor::new(
db_pool.clone(),
sfs_client.clone(),
- gmail_client.clone(),
- gmail_access_token,
+ email_api,
));
let success_count = Arc::new(AtomicUsize::new(0));
@@ -53,9 +65,10 @@ pub async fn process_macro_id(
let processor: Arc<AttachmentProcessor> = Arc::clone(&processor);
let success_count = Arc::clone(&success_count);
let macro_id = macro_id.to_string();
+ let link = link.clone();
async move {
- match processor.upload(&attachment).await {
+ match processor.upload(&link, &attachment).await {
Ok(_) => {
success_count.fetch_add(1, Ordering::Relaxed);
println!("Successfully uploaded '{}' (index: {}) for {}", attachment.filename.unwrap_or("N/A".to_string()), index, macro_id);
diff --git a/services/email_service/src/bin/backfill_sfs_attachments/upload.rs b/services/email_service/src/bin/backfill_sfs_attachments/upload.rs
index 2d6e330701..870b9976a6 100644
--- a/services/email_service/src/bin/backfill_sfs_attachments/upload.rs
+++ b/services/email_service/src/bin/backfill_sfs_attachments/upload.rs
@@ -1,4 +1,9 @@
use anyhow::Context;
+use email_api_client::GmailApiClientRepository;
+use email_api_client::domain::ports::AlwaysAllowRateLimiter;
+use email_api_client::domain::service::EmailApiClientServiceImpl;
+use email_service::outbound::email_api::StaticTokenSource;
+use models_email::email::service::link::Link;
use models_email::service::attachment::{AttachmentSfs, AttachmentUploadMetadata};
use sqlx::PgPool;
use static_file_service_client::put_file::PutFileResponse;
@@ -10,38 +15,44 @@ use uuid::Uuid;
pub struct AttachmentProcessor {
db: PgPool,
sfs_client: static_file_service_client::StaticFileServiceClient,
- gmail_client: gmail_client::GmailClient,
- gmail_access_token: String,
+ email_api: EmailApiClientServiceImpl<
+ GmailApiClientRepository,
+ StaticTokenSource,
+ AlwaysAllowRateLimiter,
+ >,
}
impl AttachmentProcessor {
pub fn new(
db: PgPool,
sfs_client: static_file_service_client::StaticFileServiceClient,
- gmail_client: gmail_client::GmailClient,
- gmail_access_token: String,
+ email_api: EmailApiClientServiceImpl<
+ GmailApiClientRepository,
+ StaticTokenSource,
+ AlwaysAllowRateLimiter,
+ >,
) -> Self {
Self {
db,
sfs_client,
- gmail_client,
- gmail_access_token,
+ email_api,
}
}
- async fn download_attachment_bytes(
+ async fn fetch_attachment(
&self,
+ link: &Link,
attachment: &AttachmentUploadMetadata,
) -> anyhow::Result<bytes::Bytes> {
let attachment_data = self
- .gmail_client
- .get_attachment_data(
- &self.gmail_access_token,
+ .email_api
+ .get_attachment(
+ link.id,
&attachment.email_provider_id,
&attachment.provider_attachment_id,
)
.await
- .context("Failed to get attachment data from Gmail")?;
+ .context("Failed to get attachment data from email provider")?;
println!(
"Successfully downloaded attachment data for {} ({} bytes)",
@@ -115,8 +126,12 @@ impl AttachmentProcessor {
/// Orchestrates the full upload process for a single attachment.
#[instrument(skip(self), fields(file_name = ?attachment.filename, mime_type = %attachment.mime_type))]
- pub async fn upload(&self, attachment: &AttachmentUploadMetadata) -> anyhow::Result<()> {
- let bytes = self.download_attachment_bytes(attachment).await?;
+ pub async fn upload(
+ &self,
+ link: &Link,
+ attachment: &AttachmentUploadMetadata,
+ ) -> anyhow::Result<()> {
+ let bytes = self.fetch_attachment(link, attachment).await?;
let sfs_response = self
.upload_to_sfs_with_retry(bytes, attachment.mime_type.clone())
diff --git a/services/email_service/src/bin/pubsub_workers/pubsub_workers.rs b/services/email_service/src/bin/pubsub_workers/pubsub_workers.rs
index 1652033d18..37a7ff1d29 100644
--- a/services/email_service/src/bin/pubsub_workers/pubsub_workers.rs
+++ b/services/email_service/src/bin/pubsub_workers/pubsub_workers.rs
@@ -1,8 +1,13 @@
#![recursion_limit = "256"]
use anyhow::Context;
use document_storage_service_client::DocumentStorageServiceClient;
+use email_api_client::GmailApiClientRepository;
use email_service::config::Config;
+use email_service::outbound::email_api::{
+ EmailServiceTokenSource, GmailApi, RateBudget, RedisProviderRateLimiter,
+};
use email_service::pubsub::CrmMetadataResolver;
+use email_service::util::redis::RedisClient;
use macro_entrypoint::{MacroEntrypoint, shutdown_signal};
use macro_env::Environment;
use macro_event_broker::{KafkaEventPublisher, MacroEventBrokerService};
@@ -11,6 +16,7 @@ use macro_service_urls::{
};
use notification::domain::service::SqsNotificationIngress;
use notification::outbound::queue::SqsQueue;
+use sqlx::PgPool;
use sqlx::postgres::PgPoolOptions;
use static_file_service_client::StaticFileServiceClient;
use std::sync::Arc;
@@ -20,6 +26,22 @@ use tokio_util::{sync::CancellationToken, task::TaskTracker};
const EVENT_BROKER_DRAIN_TIMEOUT: Duration = Duration::from_secs(10);
+fn compose_email_api(
+ db: PgPool,
+ subscription_topic: String,
+ auth_service_client: authentication_service_client::AuthServiceClient,
+ redis_client: RedisClient,
+ redis_conn: redis::aio::MultiplexedConnection,
+ sqs_client: sqs_client::SQS,
+ rate_budget: RateBudget,
+) -> GmailApi {
+ GmailApi::new(
+ GmailApiClientRepository::from_subscription_topic(subscription_topic),
+ EmailServiceTokenSource::new(db, redis_conn, auth_service_client, sqs_client),
+ RedisProviderRateLimiter::new(redis_client, rate_budget),
+ )
+}
+
#[tokio::main]
#[tracing::instrument(err)]
async fn main() -> anyhow::Result<()> {
@@ -230,8 +252,6 @@ async fn main() -> anyhow::Result<()> {
AuthServiceUrl::new()?.to_string(),
);
- let gmail_client = gmail_client::GmailClient::new(config.gmail_gcp_queue.to_string());
-
let redis_inner_client = redis::Client::open(config.redis_uri.as_ref())
.inspect(|client| {
client
@@ -252,13 +272,40 @@ async fn main() -> anyhow::Result<()> {
queue: ingress_queue,
});
- let redis_client = email_service::util::redis::RedisClient::new(
+ let redis_client = RedisClient::new(
redis_inner_client,
config.redis_rate_limit_reqs,
config.redis_rate_limit_reqs_backfill,
config.redis_rate_limit_window_secs,
);
+ // One long-lived multiplexed connection shared by both token sources;
+ // cloning it is an Arc bump, not a new TCP dial per provider call.
+ let redis_conn = redis_client
+ .inner
+ .get_multiplexed_async_connection()
+ .await
+ .context("failed to get multiplexed redis connection for token sources")?;
+
+ let email_api_live = compose_email_api(
+ db.clone(),
+ config.gmail_gcp_queue.to_string(),
+ auth_service_client.clone(),
+ redis_client.clone(),
+ redis_conn.clone(),
+ sqs_client.clone(),
+ RateBudget::Live,
+ );
+ let email_api_backfill = compose_email_api(
+ db_backfill.clone(),
+ config.gmail_gcp_queue.to_string(),
+ auth_service_client.clone(),
+ redis_client.clone(),
+ redis_conn,
+ sqs_client.clone(),
+ RateBudget::Backfill,
+ );
+
let sfs_client = StaticFileServiceClient::new(
config.internal_api_key.to_string(),
StaticFileServiceUrl::new()?.to_string(),
@@ -331,8 +378,7 @@ async fn main() -> anyhow::Result<()> {
let db_inbox_sync = db.clone();
let sqs_client_inbox_sync = sqs_client.clone();
let contacts_ingress_inbox_sync = contacts_ingress.clone();
- let gmail_client_inbox_sync = gmail_client.clone();
- let auth_service_client_inbox_sync = auth_service_client.clone();
+ let email_api_inbox_sync = email_api_live.clone();
let redis_client_inbox_sync = redis_client.clone();
let notification_ingress_service_inbox_sync = notification_ingress_service.clone();
let sfs_client_inbox_sync = sfs_client.clone();
@@ -348,8 +394,7 @@ async fn main() -> anyhow::Result<()> {
worker,
sqs_client_inbox_sync,
contacts_ingress_inbox_sync,
- gmail_client_inbox_sync,
- auth_service_client_inbox_sync,
+ email_api_inbox_sync,
redis_client_inbox_sync,
notification_ingress_service_inbox_sync,
sfs_client_inbox_sync,
@@ -376,8 +421,7 @@ async fn main() -> anyhow::Result<()> {
let db_inbox_sync = db.clone();
let sqs_client_inbox_sync = sqs_client.clone();
let contacts_ingress_inbox_sync = contacts_ingress.clone();
- let gmail_client_inbox_sync = gmail_client.clone();
- let auth_service_client_inbox_sync = auth_service_client.clone();
+ let email_api_inbox_sync = email_api_live.clone();
let redis_client_inbox_sync = redis_client.clone();
let notification_ingress_service_inbox_sync = notification_ingress_service.clone();
let sfs_client_inbox_sync = sfs_client.clone();
@@ -393,8 +437,7 @@ async fn main() -> anyhow::Result<()> {
worker,
sqs_client_inbox_sync,
contacts_ingress_inbox_sync,
- gmail_client_inbox_sync,
- auth_service_client_inbox_sync,
+ email_api_inbox_sync,
redis_client_inbox_sync,
notification_ingress_service_inbox_sync,
sfs_client_inbox_sync,
@@ -420,18 +463,14 @@ async fn main() -> anyhow::Result<()> {
for worker in gmail_ops_workers {
let db_gmail_ops = db.clone();
let sqs_client_gmail_ops = sqs_client.clone();
- let gmail_client_gmail_ops = gmail_client.clone();
- let auth_service_client_gmail_ops = auth_service_client.clone();
- let redis_client_gmail_ops = redis_client.clone();
+ let email_api_gmail_ops = email_api_live.clone();
let cancellation_token = worker_cancellation_token.clone();
worker_tracker.spawn(async move {
email_service::pubsub::gmail_ops::worker::run_worker_with_cancellation(
db_gmail_ops,
worker,
sqs_client_gmail_ops,
- gmail_client_gmail_ops,
- auth_service_client_gmail_ops,
- redis_client_gmail_ops,
+ email_api_gmail_ops,
false,
cancellation_token,
)
@@ -447,18 +486,14 @@ async fn main() -> anyhow::Result<()> {
for worker in gmail_ops_retry_workers {
let db_gmail_ops = db.clone();
let sqs_client_gmail_ops = sqs_client.clone();
- let gmail_client_gmail_ops = gmail_client.clone();
- let auth_service_client_gmail_ops = auth_service_client.clone();
- let redis_client_gmail_ops = redis_client.clone();
+ let email_api_gmail_ops = email_api_live.clone();
let cancellation_token = worker_cancellation_token.clone();
worker_tracker.spawn(async move {
email_service::pubsub::gmail_ops::worker::run_worker_with_cancellation(
db_gmail_ops,
worker,
sqs_client_gmail_ops,
- gmail_client_gmail_ops,
- auth_service_client_gmail_ops,
- redis_client_gmail_ops,
+ email_api_gmail_ops,
true,
cancellation_token,
)
@@ -475,8 +510,7 @@ async fn main() -> anyhow::Result<()> {
let db_backfill = db_backfill.clone();
let sqs_client_backfill = sqs_client.clone();
let contacts_ingress_backfill = contacts_ingress.clone();
- let gmail_client_backfill = gmail_client.clone();
- let auth_service_client_backfill = auth_service_client.clone();
+ let email_api_backfill = email_api_backfill.clone();
let redis_client_backfill = redis_client.clone();
let notification_ingress_service_backfill = notification_ingress_service.clone();
let sfs_client_backfill = sfs_client.clone();
@@ -492,8 +526,7 @@ async fn main() -> anyhow::Result<()> {
worker,
sqs_client_backfill,
contacts_ingress_backfill,
- gmail_client_backfill,
- auth_service_client_backfill,
+ email_api_backfill,
redis_client_backfill,
notification_ingress_service_backfill,
sfs_client_backfill,
@@ -538,7 +571,7 @@ async fn main() -> anyhow::Result<()> {
);
let db_link_manager = db.clone();
- let gmail_client_link_manager = gmail_client.clone();
+ let email_api_link_manager = email_api_live.clone();
let auth_service_client_link_manager = auth_service_client.clone();
let redis_client_link_manager = redis_client.clone();
let sqs_client_link_manager = sqs_client.clone();
@@ -552,7 +585,7 @@ async fn main() -> anyhow::Result<()> {
email_service::pubsub::link_manager::worker::run_worker_with_cancellation(
link_manager_worker,
db_link_manager,
- gmail_client_link_manager,
+ email_api_link_manager,
auth_service_client_link_manager,
redis_client_link_manager,
sqs_client_link_manager,
@@ -566,9 +599,7 @@ async fn main() -> anyhow::Result<()> {
});
let db_scheduled = db.clone();
- let gmail_client_scheduled = gmail_client.clone();
- let auth_service_client_scheduled = auth_service_client.clone();
- let redis_client_scheduled = redis_client.clone();
+ let email_api_scheduled = email_api_live;
let s3_client_scheduled = s3_client.clone();
let attachment_bucket_scheduled = config.attachment_bucket.to_string();
let macro_event_broker_scheduled = macro_event_broker.clone();
@@ -578,9 +609,7 @@ async fn main() -> anyhow::Result<()> {
email_service::pubsub::scheduled::worker::run_worker_with_cancellation(
scheduled_worker,
db_scheduled,
- gmail_client_scheduled,
- auth_service_client_scheduled,
- redis_client_scheduled,
+ email_api_scheduled,
s3_client_scheduled,
attachment_bucket_scheduled,
macro_event_broker_scheduled,
diff --git a/services/email_service/src/calendar_outbox.rs b/services/email_service/src/calendar_outbox.rs
index 843fd05df7..d7226f814a 100644
--- a/services/email_service/src/calendar_outbox.rs
+++ b/services/email_service/src/calendar_outbox.rs
@@ -23,6 +23,7 @@ struct EmailInitOutboxRow {
backfill_job_id: Uuid,
email_link_id: Uuid,
priority_pass: bool,
+ refresh_existing: bool,
}
struct EmailCompletionOutboxRow {
@@ -245,7 +246,10 @@ async fn drain_email_init(db: &PgPool, sqs: &SQS) -> anyhow::Result<usize> {
outbox.id,
outbox.backfill_job_id,
job.link_id AS "email_link_id!",
- job.threads_requested_limit IS NULL AS "priority_pass!"
+ -- Recovery jobs skip the priority pass: the mailbox is already
+ -- populated, so there is no cold-start signal to seed.
+ (job.threads_requested_limit IS NULL AND NOT job.is_recovery) AS "priority_pass!",
+ job.is_recovery AS "refresh_existing!"
FROM email_backfill_init_outbox outbox
JOIN email_backfill_jobs job ON job.id = outbox.backfill_job_id
WHERE outbox.published_at IS NULL
@@ -270,6 +274,7 @@ async fn drain_email_init(db: &PgPool, sqs: &SQS) -> anyhow::Result<usize> {
payload: ListThreadsPayload {
next_page_token: None,
priority_pass: row.priority_pass,
+ refresh_existing: row.refresh_existing,
},
}),
};
diff --git a/services/email_service/src/convert/contact.rs b/services/email_service/src/convert/contact.rs
deleted file mode 100644
index 251a5f6bef..0000000000
--- a/services/email_service/src/convert/contact.rs
+++ /dev/null
@@ -1,34 +0,0 @@
-use macro_uuid::generate_uuid_v7;
-use models_email::gmail::contacts::PersonResource;
-use models_email::service::contact::Contact;
-use uuid::Uuid;
-
-pub fn map_person_to_contact(link_id: Uuid, person: PersonResource) -> Contact {
- let display_name = person
- .names
- .into_iter()
- .find(|n| n.display_name.is_some())
- .and_then(|n| n.display_name);
-
- let email_address = person
- .email_addresses
- .into_iter()
- .find(|e| e.value.is_some())
- .and_then(|e| e.value);
-
- // return first photo that isn't a default photo
- let original_photo_url = person
- .photos
- .into_iter()
- .find(|p| p.url.is_some() && p.default.is_none_or(|d| !d))
- .and_then(|p| p.url);
-
- Contact {
- id: generate_uuid_v7(),
- link_id,
- name: display_name,
- email_address,
- original_photo_url,
- sfs_photo_url: None,
- }
-}
diff --git a/services/email_service/src/convert/history.rs b/services/email_service/src/convert/history.rs
deleted file mode 100644
index f3675988b4..0000000000
--- a/services/email_service/src/convert/history.rs
+++ /dev/null
@@ -1,101 +0,0 @@
-use models_email::gmail;
-use std::collections::HashSet;
-
-pub fn map_history_list_response_to_history(
- response: gmail::HistoryListResponse,
-) -> gmail::history::InboxChanges {
- let mut message_ids_to_upsert: HashSet<String> = HashSet::new();
- let mut message_ids_to_delete: HashSet<String> = HashSet::new();
- let mut labels_to_update: HashSet<String> = HashSet::new();
-
- // in summary: if a message needs to be upserted or deleted, we don't need to worry about updating
- // labels for it. if a message is in the "messages" list but no other lists, we need to upsert it.
- if let Some(history_records) = response.history {
- for history_record in history_records {
- // if the record has a message in the messages attribute that isn't in any of the other attributes,
- // this mean _something_ changed about the message, so we have to upsert it. add it to
- // message_ids_to_upsert to perform a full refresh of the message.
- if let Some(messages) = &history_record.messages {
- for m_item in messages {
- let is_explicitly_handled_in_record = history_record
- .messages_added
- .as_ref()
- .is_some_and(|msgs| msgs.iter().any(|x| x.message.id == m_item.id))
- || history_record
- .messages_deleted
- .as_ref()
- .is_some_and(|msgs| msgs.iter().any(|x| x.message.id == m_item.id))
- || history_record
- .labels_added
- .as_ref()
- .is_some_and(|labels| labels.iter().any(|x| x.message.id == m_item.id))
- || history_record
- .labels_removed
- .as_ref()
- .is_some_and(|labels| labels.iter().any(|x| x.message.id == m_item.id));
-
- if !is_explicitly_handled_in_record
- && !message_ids_to_delete.contains(&m_item.id)
- {
- message_ids_to_upsert.insert(m_item.id.clone());
- labels_to_update.remove(&m_item.id);
- }
- }
- }
-
- // if the record has message(s) in the messages_added attribute, that we aren't deleting already
- // add them to message_ids_to_upsert, and wipe labels_to_add and labels_to_remove
- if let Some(messages_added) = &history_record.messages_added {
- for message in messages_added {
- if !message_ids_to_delete.contains(&message.message.id) {
- message_ids_to_upsert.insert(message.message.id.clone());
- labels_to_update.remove(&message.message.id);
- }
- }
- }
-
- // if the record has message(s) in the messages_deleted attribute, add them to message_ids_to_delete
- // and wipe the other lists
- if let Some(messages_deleted) = &history_record.messages_deleted {
- for message in messages_deleted {
- message_ids_to_delete.insert(message.message.id.clone());
- message_ids_to_upsert.remove(&message.message.id);
- labels_to_update.remove(&message.message.id);
- }
- }
-
- if let Some(labels_added) = &history_record.labels_added {
- for label_added in labels_added {
- let msg_id = &label_added.message.id;
- // ignore if we are already upserting/deleting/updating labels for the message
- if !message_ids_to_upsert.contains(msg_id)
- && !message_ids_to_delete.contains(msg_id)
- && !labels_to_update.contains(msg_id)
- {
- labels_to_update.insert(msg_id.clone());
- }
- }
- }
-
- if let Some(labels_removed) = &history_record.labels_removed {
- for label_removed in labels_removed {
- let msg_id = &label_removed.message.id;
- // ignore if we are already upserting/deleting/updating labels for the message
- if !message_ids_to_upsert.contains(msg_id)
- && !message_ids_to_delete.contains(msg_id)
- && !labels_to_update.contains(msg_id)
- {
- labels_to_update.insert(msg_id.clone());
- }
- }
- }
- }
- }
-
- gmail::history::InboxChanges {
- message_ids_to_upsert,
- message_ids_to_delete,
- labels_to_update,
- current_history_id: response.history_id,
- }
-}
diff --git a/services/email_service/src/convert/message.rs b/services/email_service/src/convert/message.rs
deleted file mode 100644
index 613ac75d2c..0000000000
--- a/services/email_service/src/convert/message.rs
+++ /dev/null
@@ -1,365 +0,0 @@
-use super::payload::parse_gmail_payload;
-use anyhow::{Context, Result};
-use chrono::{TimeZone, Utc};
-use macro_uuid::generate_uuid_v7;
-use mailparse::{MailAddr, MailAddrList, addrparse};
-use models_email::email::service;
-use models_email::gmail::labels::SystemLabelID;
-use models_email::gmail::{Header, MessageResource};
-use uuid::Uuid;
-
-#[tracing::instrument(skip(message), level = "debug")]
-pub fn map_message_resource_to_service(
- message: MessageResource,
- link_id: Uuid,
-) -> Result<service::message::Message> {
- let parsed_payload = parse_gmail_payload(&message.payload, &message.id)
- .context("Failed parsing message payload")?;
-
- let internal_date_ts = message
- .internal_date
- .parse::<i64>()
- .ok()
- .and_then(|ms| Utc.timestamp_millis_opt(ms).single());
-
- let is_read = !message
- .label_ids
- .iter()
- .any(|l| l == SystemLabelID::Unread.as_str());
- let is_starred = message
- .label_ids
- .iter()
- .any(|l| l == SystemLabelID::Starred.as_str());
- let is_sent = message
- .label_ids
- .iter()
- .any(|l| l == SystemLabelID::Sent.as_str());
- let is_draft = message
- .label_ids
- .iter()
- .any(|l| l == SystemLabelID::Draft.as_str());
-
- let labels: Vec<service::label::Label> = message
- .label_ids
- .iter()
- .map(|id| service::label::Label {
- id: None,
- link_id,
- provider_label_id: id.clone(),
- name: None,
- created_at: Default::default(),
- message_list_visibility: None,
- label_list_visibility: None,
- type_: None,
- })
- .collect();
-
- let attachments = parsed_payload
- .attachments_metadata
- .into_iter()
- .map(|meta| service::attachment::Attachment {
- db_id: generate_uuid_v7(),
- provider_id: meta.provider_attachment_id,
- data_url: None,
- filename: meta.filename,
- mime_type: meta.mime_type,
- size_bytes: meta.size_bytes,
- content_id: meta.content_id,
- sfs_id: None,
- })
- .collect();
-
- Ok(service::message::Message {
- db_id: generate_uuid_v7(),
- provider_id: Some(message.id),
- thread_db_id: generate_uuid_v7(),
- provider_thread_id: Some(message.thread_id),
- replying_to_id: None, // gets generated later, once message has been inserted
- global_id: Some(parsed_payload.global_id),
- link_id, // From argument
- subject: parsed_payload.subject,
- snippet: Some(message.snippet),
- provider_history_id: Some(message.history_id),
- internal_date_ts,
- sent_at: parsed_payload.sent_at.or(internal_date_ts),
- size_estimate: Some(message.size_estimate as i64),
- is_read,
- is_starred,
- is_sent,
- is_draft,
- scheduled_send_time: None,
- has_attachments: parsed_payload.has_attachments,
- from: parsed_payload.from,
- to: parsed_payload.to,
- cc: parsed_payload.cc,
- bcc: parsed_payload.bcc,
- labels,
- body_text: parsed_payload.body_text,
- body_html_sanitized: parsed_payload.body_html_sanitized,
- body_macro: None,
- attachments,
- attachments_draft: Vec::new(),
- attachments_forwarded: Vec::new(),
- headers_json: Some(serde_json::to_value(parsed_payload.all_headers)?),
- created_at: Utc::now(), // Omitted - set default/ignored
- updated_at: Utc::now(), // Omitted - set default/ignored
- })
-}
-
-pub fn parse_address_header(header_value: &str) -> Vec<(Option<String>, String)> {
- // First try with the full header value
- match addrparse(header_value) {
- Ok(addrs) => process_parsed_addresses(&addrs),
- Err(e) => {
- // only retry addresses that unexpectedly terminated due to reaching length limit
- let is_retryable = header_value.contains(">,");
- if is_retryable {
- // Try to salvage by removing everything after the last occurrence of ">, "
- // First check for the pattern ">,"
- let idx = header_value.rfind(">,");
- // Include the ">" in the truncated string, so add 1 to the index
- let truncated_value = &header_value[..(idx.unwrap() + 1)];
- match addrparse(truncated_value) {
- Ok(addrs) => {
- return process_parsed_addresses(&addrs);
- }
- Err(e2) => {
- tracing::warn!(
- error = %e,
- retried_error = %e2,
- header = header_value,
- truncated = truncated_value,
- "Failed to parse address header even after truncation"
- );
- }
- }
- }
- Vec::new()
- }
- }
-}
-
-/// Helper function to process successfully parsed mail addresses
-fn process_parsed_addresses(addrs: &MailAddrList) -> Vec<(Option<String>, String)> {
- let mut results = Vec::new();
- for mail_addr in addrs.iter() {
- match mail_addr {
- MailAddr::Single(info) => {
- results.push((info.display_name.clone(), info.addr.clone()));
- }
- MailAddr::Group(info) => {
- for single_info in info.addrs.iter() {
- results.push((single_info.display_name.clone(), single_info.addr.clone()));
- }
- }
- }
- }
- results
-}
-
-/// Find header value by name (case-insensitive)
-pub fn find_header<'a>(headers: &'a [Header], name: &str) -> Option<&'a str> {
- headers
- .iter()
- .find(|h| h.name.eq_ignore_ascii_case(name))
- .map(|h| h.value.as_str())
-}
-
-#[cfg(test)]
-mod tests {
- use super::*;
-
- #[test]
- fn test_parse_address_header_valid() {
- // Test with a single address
- let header = "John Doe <[email protected]>";
- let result = parse_address_header(header);
- assert_eq!(result.len(), 1);
- assert_eq!(
- result[0],
- (Some("John Doe".to_string()), "[email protected]".to_string())
- );
-
- // Test with multiple addresses
- let header = "John Doe <[email protected]>, Jane Smith <[email protected]>";
- let result = parse_address_header(header);
- assert_eq!(result.len(), 2);
- assert_eq!(
- result[0],
- (Some("John Doe".to_string()), "[email protected]".to_string())
- );
- assert_eq!(
- result[1],
- (
- Some("Jane Smith".to_string()),
- "[email protected]".to_string()
- )
- );
-
- // Test with no display name
- let header = "<[email protected]>";
- let result = parse_address_header(header);
- assert_eq!(result.len(), 1);
- assert_eq!(result[0], (None, "[email protected]".to_string()));
-
- // Test with group address format
- let header = "Group: John <[email protected]>, Jane <[email protected]>;";
- let result = parse_address_header(header);
- assert_eq!(result.len(), 2);
- assert_eq!(
- result[0],
- (Some("John".to_string()), "[email protected]".to_string())
- );
- assert_eq!(
- result[1],
- (Some("Jane".to_string()), "[email protected]".to_string())
- );
- }
-
- #[test]
- fn test_parse_address_header_with_truncation() {
- // Test with truncated email that would fail normal parsing
- let header = "John Doe <[email protected]>, Jane Smith <[email protected]>, Incomplete <partial@example";
- let result = parse_address_header(header);
-
- // Should successfully parse the first two addresses by truncating at the last comma
- assert_eq!(result.len(), 2);
- assert_eq!(
- result[0],
- (Some("John Doe".to_string()), "[email protected]".to_string())
- );
- assert_eq!(
- result[1],
- (
- Some("Jane Smith".to_string()),
- "[email protected]".to_string()
- )
- );
-
- // Another example with missing '>' at the end
- let header = "John <[email protected]>, Partial <email@domain";
- let result = parse_address_header(header);
- assert_eq!(result.len(), 1);
- assert_eq!(
- result[0],
- (Some("John".to_string()), "[email protected]".to_string())
- );
- }
-
- #[test]
- fn test_parse_address_header_with_invalid_format() {
- // Test with invalid format but contains withheld (should return empty)
- let header = "(withheld recipients)";
- let result = parse_address_header(header);
- assert!(result.is_empty());
-
- // Test with completely invalid format (no comma to truncate)
- let header = "This is not an email address";
- let result = parse_address_header(header);
- assert!(result.is_empty());
-
- // Test with empty string
- let header = "";
- let result = parse_address_header(header);
- assert!(result.is_empty());
- }
-
- #[test]
- fn test_parse_address_header_real_world_example() {
- // The example from the problem description
- let header = "Evan Macrotest <[email protected]>, evanmacrotest <[email protected]>, Recipient Name <evan.hutnik@gm";
- let result = parse_address_header(header);
-
- // Should successfully parse the first two addresses
- assert_eq!(result.len(), 2);
- assert_eq!(
- result[0],
- (
- Some("Evan Macrotest".to_string()),
- "[email protected]".to_string()
- )
- );
- assert_eq!(
- result[1],
- (
- Some("evanmacrotest".to_string()),
- "[email protected]".to_string()
- )
- );
- }
-
- #[test]
- fn test_parse_address_header_still_invalid_after_truncation() {
- // Test case where even after truncation, the format is still invalid
- let header = "Invalid <not-an-email@, Another <not-an-email@";
- let result = parse_address_header(header);
- assert!(result.is_empty());
- }
-
- #[test]
- fn test_process_parsed_addresses() {
- // This test requires creating mock MailAddrList objects
- // We can test this indirectly through the parse_address_header function
- // with valid inputs, which will call process_parsed_addresses internally
-
- let header = "John <[email protected]>, Jane <[email protected]>";
- let result = parse_address_header(header);
- assert_eq!(result.len(), 2);
- assert_eq!(
- result[0],
- (Some("John".to_string()), "[email protected]".to_string())
- );
- assert_eq!(
- result[1],
- (Some("Jane".to_string()), "[email protected]".to_string())
- );
- }
-
- #[test]
- fn test_parse_address_header_with_quoted_display_names_and_commas() {
- // Test case with quotes and commas in display names and a truncated email at the end
- let header = "\"Asdf, Fdsa\" <[email protected]>, \"aaa, ddd\" <aaa.ddd@ff";
- let result = parse_address_header(header);
-
- // Should successfully parse the first address by truncating at the last comma
- assert_eq!(result.len(), 1);
- assert_eq!(
- result[0],
- (
- Some("Asdf, Fdsa".to_string()),
- "[email protected]".to_string()
- )
- );
-
- // Another similar case but with three addresses
- let header = "\"First, Last\" <[email protected]>, \"Second, Name\" <[email protected]>, \"Third, Complex, Name\" <third@incomplete";
- let result = parse_address_header(header);
- assert_eq!(result.len(), 2);
- assert_eq!(
- result[0],
- (
- Some("First, Last".to_string()),
- "[email protected]".to_string()
- )
- );
- assert_eq!(
- result[1],
- (
- Some("Second, Name".to_string()),
- "[email protected]".to_string()
- )
- );
-
- // Case where a quoted comma appears at the beginning of the string
- let header = "\"Initial, With, Commas\" <[email protected]>";
- let result = parse_address_header(header);
- assert_eq!(result.len(), 1);
- assert_eq!(
- result[0],
- (
- Some("Initial, With, Commas".to_string()),
- "[email protected]".to_string()
- )
- );
- }
-}
diff --git a/services/email_service/src/convert/mod.rs b/services/email_service/src/convert/mod.rs
deleted file mode 100644
index d962905be1..0000000000
--- a/services/email_service/src/convert/mod.rs
+++ /dev/null
@@ -1,14 +0,0 @@
-//! Conversion utilities for mapping Gmail API responses to service layer models.
-
-mod payload;
-
-pub mod contact;
-pub mod history;
-pub mod message;
-pub mod thread;
-
-// Re-export commonly used functions from the public API
-pub use contact::map_person_to_contact;
-pub use history::map_history_list_response_to_history;
-pub use message::map_message_resource_to_service;
-pub use thread::map_thread_resources_to_service;
diff --git a/services/email_service/src/convert/payload.rs b/services/email_service/src/convert/payload.rs
deleted file mode 100644
index b1c87b08c3..0000000000
--- a/services/email_service/src/convert/payload.rs
+++ /dev/null
@@ -1,164 +0,0 @@
-use anyhow::Result;
-use base64::{Engine as _, engine::general_purpose::URL_SAFE};
-use chrono::{DateTime, TimeZone, Utc};
-use models_email::email::service;
-use models_email::gmail::{Header, MessagePart};
-
-use crate::convert::message::find_header;
-use crate::convert::message::parse_address_header;
-use crate::util::sanitizer::sanitize_email_html;
-
-#[derive(Debug, Default)]
-pub struct ParsedGmailPayload {
- pub global_id: String,
- pub from: Option<service::address::ContactInfo>,
- pub to: Vec<service::address::ContactInfo>,
- pub cc: Vec<service::address::ContactInfo>,
- pub bcc: Vec<service::address::ContactInfo>,
- pub subject: Option<String>,
- pub sent_at: Option<DateTime<Utc>>,
- pub body_text: Option<String>,
- pub body_html_sanitized: Option<String>,
- pub attachments_metadata: Vec<AttachmentMetadataIntermediate>,
- pub has_attachments: bool,
- pub all_headers: Vec<Header>,
-}
-
-#[derive(Debug, Clone)]
-pub struct AttachmentMetadataIntermediate {
- pub provider_attachment_id: Option<String>,
- pub filename: Option<String>,
- pub mime_type: Option<String>,
- pub size_bytes: Option<i64>,
- pub content_id: Option<String>,
-}
-
-#[tracing::instrument(skip(message_payload))]
-pub fn parse_gmail_payload(
- message_payload: &MessagePart,
- message_id_for_log: &str,
-) -> Result<ParsedGmailPayload> {
- let mut parsed = ParsedGmailPayload::default();
- parsed.all_headers = message_payload.headers.clone();
-
- // should always exist
- parsed.global_id = find_header(&parsed.all_headers, "Message-ID")
- .unwrap_or_default()
- .to_string();
-
- parsed.subject = find_header(&parsed.all_headers, "Subject").map(String::from);
- if let Some(date_str) = find_header(&parsed.all_headers, "Date")
- && let Ok(timestamp) = mailparse::dateparse(date_str)
- {
- parsed.sent_at = Utc.timestamp_opt(timestamp, 0).single();
- // we set the service message's sent_at value to internal_date_ts if we can't parse it
- }
- if let Some(from_str) = find_header(&parsed.all_headers, "From")
- && let Some((name, email)) = parse_address_header(from_str).first()
- {
- parsed.from = Some(service::address::ContactInfo {
- email: email.clone(),
- name: name.clone(),
- photo_url: None,
- });
- }
- for header_name in ["To", "Cc", "Bcc"].iter() {
- if let Some(header_str) = find_header(&parsed.all_headers, header_name) {
- let addresses = parse_address_header(header_str);
- let target_list = match *header_name {
- "To" => &mut parsed.to,
- "Cc" => &mut parsed.cc,
- "Bcc" => &mut parsed.bcc,
- _ => continue,
- };
- for (name, email) in addresses {
- target_list.push(service::address::ContactInfo {
- email,
- name,
- photo_url: None,
- });
- }
- }
- }
-
- let mut text_body: Option<String> = None;
- let mut html_body: Option<String> = None;
- let mut attachments: Vec<AttachmentMetadataIntermediate> = Vec::new();
- let mut has_attachments_flag = false;
- let mut part_stack: Vec<&MessagePart> = vec![message_payload];
-
- while let Some(part) = part_stack.pop() {
- let mime_type = part.mime_type.to_lowercase();
- let is_alternative = mime_type.starts_with("multipart/alternative");
- let is_related = mime_type.starts_with("multipart/related");
- let is_mixed = mime_type.starts_with("multipart/mixed");
- let is_multipart = is_alternative || is_related || is_mixed;
-
- let disposition = find_header(&part.headers, "Content-Disposition")
- .map(|d| d.split(';').next().unwrap_or("").trim().to_lowercase())
- .unwrap_or_default();
-
- let is_inline_non_text = disposition == "inline" && !mime_type.starts_with("text/");
- let is_regular_attachment = disposition == "attachment"
- || (!part.filename.is_empty() && !is_multipart && !mime_type.starts_with("text/"));
-
- if let Some(body) = &part.body {
- // process plaintext/html data
- if let Some(data_b64) = &body.data_base64 {
- match URL_SAFE.decode(data_b64) {
- Ok(decoded_bytes) => {
- if mime_type == "text/plain" && text_body.is_none() {
- text_body = Some(String::from_utf8_lossy(&decoded_bytes).to_string());
- } else if mime_type == "text/html" && html_body.is_none() {
- let raw_html = String::from_utf8_lossy(&decoded_bytes);
- let sanitized_html = sanitize_email_html(&raw_html);
- html_body = Some(sanitized_html);
- }
- }
- Err(e) => {
- tracing::warn!(message_id=%message_id_for_log, part_id=%part.part_id, mime=%part.mime_type, error=%e, "Failed to decode base64 body data")
- }
- }
- }
-
- // process attachment data
- if (is_inline_non_text || is_regular_attachment) && body.attachment_id.is_some() {
- has_attachments_flag = true;
- let content_id = find_header(&part.headers, "Content-ID").map(String::from);
-
- // extension in filename as lowercase
- let filename = Some(part.filename.clone())
- .filter(|s| !s.is_empty())
- .map(|f| {
- if let Some((base, ext)) = f.rsplit_once('.')
- && !ext.is_empty()
- {
- return format!("{}.{}", base, ext.to_lowercase());
- }
- f
- });
-
- attachments.push(AttachmentMetadataIntermediate {
- provider_attachment_id: body.attachment_id.clone(),
- filename,
- mime_type: Some(part.mime_type.clone()),
- size_bytes: Some(body.size),
- content_id,
- });
- }
- }
-
- if let Some(sub_parts) = &part.parts {
- for sub_part in sub_parts.iter().rev() {
- part_stack.push(sub_part);
- }
- }
- }
-
- parsed.body_text = text_body;
- parsed.body_html_sanitized = html_body;
- parsed.attachments_metadata = attachments;
- parsed.has_attachments = has_attachments_flag;
-
- Ok(parsed)
-}
diff --git a/services/email_service/src/convert/thread.rs b/services/email_service/src/convert/thread.rs
deleted file mode 100644
index 5cd52f1db8..0000000000
--- a/services/email_service/src/convert/thread.rs
+++ /dev/null
@@ -1,109 +0,0 @@
-use anyhow::{Context, Result};
-use chrono::Utc;
-use futures::future::try_join_all;
-use macro_uuid::generate_uuid_v7;
-use models_email::email::service;
-use models_email::email::service::message::{is_inbound, is_outbound, is_spam_or_trash};
-use models_email::gmail::ThreadResource;
-use models_email::gmail::error::GmailError;
-use uuid::Uuid;
-
-use super::message::map_message_resource_to_service;
-
-/// calls map_thread_resource_to_service concurrently on the list of threads
-#[tracing::instrument(skip(ordered_responses), level = "debug")]
-pub async fn map_thread_resources_to_service(
- ordered_responses: Vec<ThreadResource>,
- link_id: Uuid,
-) -> Result<Vec<service::thread::Thread>, GmailError> {
- let mapping_futures = ordered_responses
- .into_iter()
- .map(|r| tokio::spawn(async move { map_thread_resource_to_service(r, link_id).await }))
- .collect::<Vec<_>>();
-
- let results_from_tasks = try_join_all(mapping_futures)
- .await
- .map_err(|join_error| GmailError::GenericError(join_error.to_string()))?;
-
- let service_threads: Result<Vec<service::thread::Thread>, _> =
- results_from_tasks.into_iter().collect();
-
- service_threads.map_err(|mapping_error| GmailError::GenericError(mapping_error.to_string()))
-}
-
-#[tracing::instrument(skip(thread_resource), level = "info")]
-pub async fn map_thread_resource_to_service(
- thread_resource: ThreadResource,
- link_id: Uuid,
-) -> Result<service::thread::Thread> {
- let message_mapping_futures = thread_resource
- .messages
- .into_iter()
- .map(|message| {
- tokio::spawn(async move { map_message_resource_to_service(message, link_id) })
- })
- .collect::<Vec<_>>();
-
- let results_from_tasks = try_join_all(message_mapping_futures)
- .await
- .map_err(|join_error| {
- anyhow::anyhow!("Task failed during message mapping: {}", join_error)
- })?;
-
- let mut service_messages: Vec<service::message::Message> = results_from_tasks
- .into_iter()
- .collect::<Result<Vec<_>, _>>()
- .context("Mapping one or more messages failed")?;
-
- service_messages.sort_by_key(|a| a.internal_date_ts);
-
- // if any messages in the thread are in the inbox, the thread is visible in the inbox.
- let inbox_visible = service_messages.iter().any(|msg| {
- msg.labels
- .iter()
- .any(|label| label.provider_label_id == service::label::system_labels::INBOX)
- });
-
- // if any message in the thread is unread, the thread is considered unread in the FE
- let is_read = !service_messages.iter().any(|msg| !msg.is_read);
-
- // get the latest timestamp of incoming messages for thread.
- let latest_inbound_message_ts = service_messages
- .iter()
- .rfind(|msg| is_inbound(msg))
- .map(|msg| msg.internal_date_ts)
- .unwrap_or_else(|| None);
-
- // get the latest timestamp of outgoing messages for thread.
- let latest_outbound_message_ts = service_messages
- .iter()
- .rfind(|msg| is_outbound(msg))
- .map(|msg| msg.internal_date_ts)
- .unwrap_or_else(|| None);
-
- let latest_non_spam_message_ts = service_messages
- .iter()
- .rfind(|msg| !is_spam_or_trash(msg))
- .map(|msg| msg.internal_date_ts)
- .unwrap_or_else(|| None);
-
- // Generate the thread ID and update all messages to reference it
- let thread_db_id = generate_uuid_v7();
- for msg in service_messages.iter_mut() {
- msg.thread_db_id = thread_db_id;
- }
-
- Ok(service::thread::Thread {
- db_id: thread_db_id,
- provider_id: Some(thread_resource.id),
- link_id, // From argument
- inbox_visible,
- is_read,
- latest_inbound_message_ts,
- latest_outbound_message_ts,
- latest_non_spam_message_ts,
- created_at: Utc::now(), // Omitted - set default/ignored
- updated_at: Utc::now(), // Omitted - set default/ignored
- messages: service_messages,
- })
-}
diff --git a/services/email_service/src/lib.rs b/services/email_service/src/lib.rs
index f9b1b6557d..4ae82fa2fc 100644
--- a/services/email_service/src/lib.rs
+++ b/services/email_service/src/lib.rs
@@ -7,6 +7,7 @@ pub mod calendar_outbox;
/// Access-token adapter for user-initiated calendar mutations.
pub mod calendar_tokens;
pub mod config;
-pub mod convert;
+/// Outbound infrastructure adapters for email provider capabilities.
+pub mod outbound;
pub mod pubsub;
pub mod util;
diff --git a/services/email_service/src/main.rs b/services/email_service/src/main.rs
index 8e90a69af7..d493a59af2 100644
--- a/services/email_service/src/main.rs
+++ b/services/email_service/src/main.rs
@@ -14,7 +14,11 @@ use email::{
},
outbound::{EmailPgRepo, GmailTokenProviderImpl},
};
+use email_api_client::GmailApiClientRepository;
use email_service::calendar_tokens::CalendarTokenProviderAdapter;
+use email_service::outbound::email_api::{
+ EmailServiceTokenSource, GmailApi, RateBudget, RedisProviderRateLimiter,
+};
use email_service::pubsub::calendar_backfill_adapters::RedisCalendarRequestGate;
use entity_access::{domain::service::EntityAccessServiceImpl, outbound::PgAccessRepository};
use frecency::{domain::services::FrecencyQueryServiceImpl, outbound::postgres::FrecencyPgStorage};
@@ -93,6 +97,7 @@ async fn main() -> anyhow::Result<()> {
);
let gmail_client = gmail_client::GmailClient::new(config.gmail_gcp_queue.as_ref().to_string());
+ let gmail_api_repository = GmailApiClientRepository::new(gmail_client.clone());
let redis_inner_client = redis::Client::open(config.redis_uri.as_ref())
.inspect(|client| {
@@ -181,6 +186,16 @@ async fn main() -> anyhow::Result<()> {
.get_multiplexed_async_connection()
.await
.context("failed to get multiplexed redis connection for gmail token provider")?;
+ let email_api = GmailApi::new(
+ gmail_api_repository,
+ EmailServiceTokenSource::new(
+ db.clone(),
+ redis_conn.clone(),
+ auth_service_client.as_ref().clone(),
+ sqs_client.as_ref().clone(),
+ ),
+ RedisProviderRateLimiter::new(redis_client.clone(), RateBudget::Live),
+ );
let redis_client = Arc::new(redis_client);
let gmail_token_state = GmailTokenState::new(GmailTokenProviderImpl::new(
redis_conn.clone(),
@@ -207,6 +222,7 @@ async fn main() -> anyhow::Result<()> {
sqs_client,
sfs_client: Arc::new(sfs_client),
gmail_client: gmail_client.clone(),
+ email_api,
s3_client: Arc::new(s3_client),
dss_client: Arc::new(dss_client),
system_properties_service,
diff --git a/services/email_service/src/openapi.rs b/services/email_service/src/openapi.rs
index 29b528694e..e0460e3524 100644
--- a/services/email_service/src/openapi.rs
+++ b/services/email_service/src/openapi.rs
@@ -5,7 +5,7 @@ mod backfill_completion_service;
mod backfill_init_service;
mod calendar_outbox;
mod config;
-mod convert;
+mod outbound;
mod pubsub;
mod util;
mod utils;
diff --git a/services/email_service/src/outbound.rs b/services/email_service/src/outbound.rs
new file mode 100644
index 0000000000..23de65b836
--- /dev/null
+++ b/services/email_service/src/outbound.rs
@@ -0,0 +1,4 @@
+//! Outbound infrastructure adapters.
+
+/// Email provider API adapters and composition types.
+pub mod email_api;
diff --git a/services/email_service/src/outbound/email_api/mod.rs b/services/email_service/src/outbound/email_api/mod.rs
new file mode 100644
index 0000000000..0c97286e9a
--- /dev/null
+++ b/services/email_service/src/outbound/email_api/mod.rs
@@ -0,0 +1,17 @@
+//! Email API infrastructure adapters.
+
+mod rate_limiter;
+mod token_source;
+
+pub use rate_limiter::{RateBudget, RedisProviderRateLimiter};
+pub use token_source::{EmailServiceTokenSource, StaticTokenSource};
+
+use email_api_client::GmailApiClientRepository;
+use email_api_client::domain::service::EmailApiClientServiceImpl;
+
+/// Gmail API service composed with email-service infrastructure adapters.
+pub type GmailApi = EmailApiClientServiceImpl<
+ GmailApiClientRepository,
+ EmailServiceTokenSource,
+ RedisProviderRateLimiter,
+>;
diff --git a/services/email_service/src/outbound/email_api/rate_limiter.rs b/services/email_service/src/outbound/email_api/rate_limiter.rs
new file mode 100644
index 0000000000..a07f7bf62b
--- /dev/null
+++ b/services/email_service/src/outbound/email_api/rate_limiter.rs
@@ -0,0 +1,114 @@
+//! Redis-backed provider rate-limiter adapter.
+
+#[cfg(test)]
+mod test;
+
+use email_api_client::domain::models::{ApiOperationKind, RateLimitRefusal};
+use email_api_client::domain::ports::ProviderRateLimiter;
+use models_email::gmail::operations::GmailApiOperation;
+use uuid::Uuid;
+
+use crate::util::redis::RedisClient;
+use crate::util::redis::rate_limit::RateLimitArgs;
+
+/// Selects the shared provider quota budget used by a service instance.
+///
+/// `Live` and `Backfill` are two *thresholds over one shared Redis window*,
+/// not two counters: every operation charges the same per-user key, and the
+/// budget only decides the limit that charge is compared against. Splitting
+/// the Redis key per budget would let live + backfill together exceed Gmail's
+/// per-user quota — and would silently reset quota state already deployed
+/// under the shared key. Don't "fix" the key sharing.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum RateBudget {
+ /// The normal threshold used by interactive and incremental operations.
+ Live,
+ /// The lower threshold reserved for mailbox backfills, leaving headroom
+ /// for live operations while a backfill runs.
+ Backfill,
+}
+
+impl RateBudget {
+ fn is_backfill(self) -> bool {
+ matches!(self, Self::Backfill)
+ }
+}
+
+/// Applies Gmail quota policy through the email service's Redis rate limiter.
+///
+/// Redis failures remain fail-open because [`RedisClient::is_rate_limited`]
+/// reports them as an allowed request.
+#[derive(Clone)]
+pub struct RedisProviderRateLimiter {
+ redis_client: RedisClient,
+ budget: RateBudget,
+}
+
+impl RedisProviderRateLimiter {
+ /// Creates a provider rate limiter using the selected quota budget.
+ pub fn new(redis_client: RedisClient, budget: RateBudget) -> Self {
+ Self {
+ redis_client,
+ budget,
+ }
+ }
+}
+
+impl ProviderRateLimiter for RedisProviderRateLimiter {
+ async fn check_rate_limit(
+ &self,
+ link_id: Uuid,
+ operation: ApiOperationKind,
+ ) -> Result<(), RateLimitRefusal> {
+ let args = rate_limit_args(link_id, operation, self.budget);
+
+ rate_limit_result(self.redis_client.is_rate_limited(args).await)
+ }
+}
+
+fn rate_limit_result(is_limited: bool) -> Result<(), RateLimitRefusal> {
+ if is_limited {
+ return Err(RateLimitRefusal::new(None));
+ }
+
+ Ok(())
+}
+
+fn rate_limit_args(
+ link_id: Uuid,
+ operation: ApiOperationKind,
+ budget: RateBudget,
+) -> RateLimitArgs {
+ RateLimitArgs {
+ user_id: link_id,
+ operation: gmail_operation(operation),
+ is_backfill: budget.is_backfill(),
+ }
+}
+
+fn gmail_operation(operation: ApiOperationKind) -> GmailApiOperation {
+ match operation {
+ ApiOperationKind::GetProfile => GmailApiOperation::UsersGetProfile,
+ ApiOperationKind::ListChanges => GmailApiOperation::HistoryList,
+ ApiOperationKind::ListLabels => GmailApiOperation::LabelsList,
+ ApiOperationKind::CreateLabel => GmailApiOperation::LabelsCreate,
+ ApiOperationKind::DeleteLabel => GmailApiOperation::LabelsDelete,
+ ApiOperationKind::GetMessage => GmailApiOperation::MessagesGet,
+ ApiOperationKind::ListMessages => GmailApiOperation::MessagesList,
+ ApiOperationKind::ModifyMessageLabels => GmailApiOperation::MessagesModify,
+ ApiOperationKind::GetAttachment => GmailApiOperation::MessagesAttachmentsGet,
+ ApiOperationKind::SendMessage => GmailApiOperation::MessagesSend,
+ ApiOperationKind::GetThread => GmailApiOperation::ThreadsGet,
+ ApiOperationKind::ListThreads => GmailApiOperation::ThreadsList,
+ // People API calls share this budget in v1. Gmail has no corresponding
+ // quota operation, so use a one-unit operation as the accounting proxy.
+ ApiOperationKind::ListContacts => GmailApiOperation::UsersGetProfile,
+ // Block and unblock are composite filter operations. One preflight
+ // check charges the dominant write operation rather than every request.
+ ApiOperationKind::BlockSender => GmailApiOperation::SettingsFiltersCreate,
+ ApiOperationKind::UnblockSender => GmailApiOperation::SettingsFiltersDelete,
+ ApiOperationKind::ListBlockedSenders => GmailApiOperation::SettingsFiltersList,
+ ApiOperationKind::Subscribe => GmailApiOperation::Watch,
+ ApiOperationKind::Unsubscribe => GmailApiOperation::Stop,
+ }
+}
diff --git a/services/email_service/src/outbound/email_api/rate_limiter/test.rs b/services/email_service/src/outbound/email_api/rate_limiter/test.rs
new file mode 100644
index 0000000000..8c43bf81d6
--- /dev/null
+++ b/services/email_service/src/outbound/email_api/rate_limiter/test.rs
@@ -0,0 +1,66 @@
+use email_api_client::domain::models::ApiOperationKind;
+use models_email::gmail::operations::GmailApiOperation;
+use uuid::Uuid;
+
+use super::{
+ RateBudget, RedisProviderRateLimiter, gmail_operation, rate_limit_args, rate_limit_result,
+};
+
+/// Redis being unreachable must fail open: quota accounting degrades, mail
+/// flow does not.
+#[tokio::test]
+async fn unreachable_redis_fails_open() {
+ let redis_client = crate::util::redis::RedisClient::new(
+ redis::Client::open("redis://127.0.0.1:1/").expect("client construction is offline"),
+ 100,
+ 50,
+ 60,
+ );
+ let limiter = RedisProviderRateLimiter::new(redis_client, RateBudget::Live);
+
+ let result = email_api_client::domain::ports::ProviderRateLimiter::check_rate_limit(
+ &limiter,
+ Uuid::new_v4(),
+ ApiOperationKind::GetMessage,
+ )
+ .await;
+
+ assert!(
+ result.is_ok(),
+ "redis outage must not refuse provider calls"
+ );
+}
+
+#[test]
+fn contacts_use_a_one_unit_shared_budget_proxy() {
+ assert_eq!(gmail_operation(ApiOperationKind::ListContacts).cost(), 1);
+}
+
+#[test]
+fn composite_blocklist_operations_use_the_dominant_filter_write_cost() {
+ assert_eq!(gmail_operation(ApiOperationKind::BlockSender).cost(), 5);
+ assert_eq!(gmail_operation(ApiOperationKind::UnblockSender).cost(), 5);
+}
+
+#[test]
+fn refusal_is_returned_only_for_a_denied_preflight_check() {
+ assert!(rate_limit_result(false).is_ok());
+
+ let refusal = rate_limit_result(true).expect_err("denied request should be refused");
+ assert_eq!(refusal.retry_after, None);
+}
+
+#[test]
+fn rate_budget_selects_live_or_backfill_limit() {
+ let link_id = Uuid::new_v4();
+
+ let live = rate_limit_args(link_id, ApiOperationKind::GetMessage, RateBudget::Live);
+ assert_eq!(live.user_id, link_id);
+ assert_eq!(live.operation, GmailApiOperation::MessagesGet);
+ assert!(!live.is_backfill);
+
+ let backfill = rate_limit_args(link_id, ApiOperationKind::GetMessage, RateBudget::Backfill);
+ assert_eq!(backfill.user_id, link_id);
+ assert_eq!(backfill.operation, GmailApiOperation::MessagesGet);
+ assert!(backfill.is_backfill);
+}
diff --git a/services/email_service/src/outbound/email_api/token_source.rs b/services/email_service/src/outbound/email_api/token_source.rs
new file mode 100644
index 0000000000..8d4ea7fbcd
--- /dev/null
+++ b/services/email_service/src/outbound/email_api/token_source.rs
@@ -0,0 +1,295 @@
+//! Access-token sources backed by email-service infrastructure.
+
+#[cfg(test)]
+mod test;
+
+use authentication_service_client::{AuthServiceClient, error::AuthServiceClientError};
+use email_api_client::domain::models::{AccessToken, TokenError, TokenFreshness};
+use email_api_client::domain::ports::ProviderTokenSource;
+use models_email::email::service::cache::TokenCacheKey;
+use models_email::email::service::pubsub::LinkManagerMessage;
+use models_email::service::link::Link;
+use redis::aio::MultiplexedConnection;
+use sqlx::PgPool;
+use sqs_client::SQS;
+use uuid::Uuid;
+
+/// Token source that resolves linked mailboxes through the email database and
+/// acquires Gmail grants through Redis and the authentication service.
+///
+/// Successful fetches clear stale reauthorization health. Revoked or missing
+/// grants mark the link for reauthorization and enqueue a notification only on
+/// the first health transition.
+#[derive(Clone)]
+pub struct EmailServiceTokenSource {
+ db: PgPool,
+ redis_conn: MultiplexedConnection,
+ auth_service_client: AuthServiceClient,
+ sqs_client: SQS,
+}
+
+impl EmailServiceTokenSource {
+ /// Creates an email-service token source from its infrastructure clients.
+ ///
+ /// The [`MultiplexedConnection`] is cheap to clone and designed to be
+ /// shared, so token acquisition never dials a new Redis TCP connection
+ /// per provider call.
+ pub fn new(
+ db: PgPool,
+ redis_conn: MultiplexedConnection,
+ auth_service_client: AuthServiceClient,
+ sqs_client: SQS,
+ ) -> Self {
+ Self {
+ db,
+ redis_conn,
+ auth_service_client,
+ sqs_client,
+ }
+ }
+}
+
+impl ProviderTokenSource for EmailServiceTokenSource {
+ #[tracing::instrument(skip(self), err)]
+ async fn get_access_token(
+ &self,
+ link_id: Uuid,
+ freshness: TokenFreshness,
+ ) -> Result<AccessToken, TokenError> {
+ let link = email_db_client::links::get::fetch_link_by_id(&self.db, link_id)
+ .await
+ .inspect_err(|error| {
+ tracing::warn!(error=?error, %link_id, "Failed to load link for access-token acquisition");
+ })
+ .map_err(|_| transient_error("unable to load the linked mailbox"))?
+ // A missing link is a deleted mailbox, not an infrastructure blip:
+ // retrying would only redeliver the message until the DLQ.
+ .ok_or_else(|| TokenError::Permanent {
+ message: "linked mailbox was not found".to_string(),
+ })?;
+
+ // The row was just read, so the health-clear UPDATE can be gated on
+ // its needs_reauth value instead of running unconditionally per call.
+ self.acquire(&link, freshness, link.needs_reauth).await
+ }
+
+ async fn get_access_token_for_link(
+ &self,
+ link: &Link,
+ freshness: TokenFreshness,
+ ) -> Result<AccessToken, TokenError> {
+ // Caller-supplied Link values cannot gate the health clear: callers
+ // like attach_link_context hardcode needs_reauth: false, which would
+ // wrongly skip the UPDATE. Always attempt the clear on this path.
+ self.acquire(link, freshness, true).await
+ }
+
+ async fn get_access_token_health_neutral(
+ &self,
+ link: &Link,
+ freshness: TokenFreshness,
+ ) -> Result<AccessToken, TokenError> {
+ // Deliberately bypasses record_token_health: teardown must neither
+ // set needs_reauth nor enqueue a reauth notification.
+ self.fetch_token(link, freshness)
+ .await
+ .map(AccessToken::new)
+ .map_err(map_token_acquisition_error)
+ }
+}
+
+impl EmailServiceTokenSource {
+ async fn acquire(
+ &self,
+ link: &Link,
+ freshness: TokenFreshness,
+ row_may_need_reauth: bool,
+ ) -> Result<AccessToken, TokenError> {
+ let result = self.fetch_token(link, freshness).await;
+ let result = self
+ .record_token_health(link, result, row_may_need_reauth)
+ .await;
+
+ result
+ .map(AccessToken::new)
+ .map_err(map_token_acquisition_error)
+ }
+
+ async fn fetch_token(&self, link: &Link, freshness: TokenFreshness) -> anyhow::Result<String> {
+ let key = TokenCacheKey::new(
+ &link.fusionauth_user_id,
+ link.email_address.0.as_ref(),
+ link.provider.as_str(),
+ );
+
+ match freshness {
+ TokenFreshness::Cached => {
+ email::outbound::fetch_gmail_access_token(
+ &key,
+ &self.redis_conn,
+ &self.auth_service_client,
+ )
+ .await
+ }
+ TokenFreshness::Fresh => {
+ email::outbound::fetch_gmail_access_token_no_cache(
+ &key,
+ &self.redis_conn,
+ &self.auth_service_client,
+ )
+ .await
+ }
+ }
+ }
+
+ async fn record_token_health(
+ &self,
+ link: &Link,
+ result: anyhow::Result<String>,
+ row_may_need_reauth: bool,
+ ) -> anyhow::Result<String> {
+ match token_health_action(&result, row_may_need_reauth) {
+ TokenHealthAction::None => result,
+ TokenHealthAction::ClearReauth => {
+ clear_stale_reauth_flag(&self.db, link.id).await;
+ result
+ }
+ TokenHealthAction::MarkReauth => {
+ tracing::warn!(
+ link_id=%link.id,
+ fusionauth_user_id=%link.fusionauth_user_id,
+ "Gmail grant no longer yields a token - marking link as needing reauth"
+ );
+ match email_db_client::links::update::set_link_needs_reauth(&self.db, link.id).await
+ {
+ // Edge-triggered: the notification fans out only on the
+ // false→true transition, so repeat failures don't re-notify.
+ Ok(true) => {
+ self.sqs_client
+ .enqueue_link_manager_notification(
+ LinkManagerMessage::NotifyReauthRequired { link_id: link.id },
+ )
+ .await
+ .inspect_err(|enqueue_error| {
+ tracing::error!(error=?enqueue_error, link_id=%link.id, "Failed to enqueue reauth notification");
+ })
+ .ok();
+ }
+ Ok(false) => {}
+ Err(update_error) => {
+ tracing::error!(error=?update_error, link_id=%link.id, "Failed to mark link as needing reauth");
+ }
+ }
+ result
+ }
+ }
+ }
+}
+
+/// The health side effect implied by a token acquisition outcome.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+enum TokenHealthAction {
+ /// No health write: transient failures leave health untouched, and a
+ /// success against a known-healthy row skips the redundant UPDATE.
+ None,
+ /// Clear a possibly-set `needs_reauth` flag after a successful fetch.
+ ClearReauth,
+ /// Mark the link as needing reauthorization (revoked/missing grant).
+ MarkReauth,
+}
+
+fn token_health_action(
+ result: &anyhow::Result<String>,
+ row_may_need_reauth: bool,
+) -> TokenHealthAction {
+ match result {
+ Ok(_) if row_may_need_reauth => TokenHealthAction::ClearReauth,
+ Ok(_) => TokenHealthAction::None,
+ Err(error) if is_reauth_required_error(error) => TokenHealthAction::MarkReauth,
+ Err(_) => TokenHealthAction::None,
+ }
+}
+
+/// Clears the link's reauth flag after a successful token fetch.
+///
+/// A failed clear is logged and swallowed: the next acquisition retries it.
+async fn clear_stale_reauth_flag(db: &PgPool, link_id: Uuid) {
+ email_db_client::links::update::clear_link_needs_reauth(db, link_id)
+ .await
+ .inspect_err(|error| {
+ tracing::warn!(error=?error, %link_id, "Failed to clear needs_reauth after successful token fetch");
+ })
+ .ok();
+}
+
+/// Token source that returns one preconfigured access token.
+///
+/// This is intended for command-line jobs that acquire a token before composing
+/// the provider service and do not need email-service token health side effects.
+#[derive(Clone, Debug)]
+pub struct StaticTokenSource {
+ token: AccessToken,
+}
+
+impl StaticTokenSource {
+ /// Creates a static token source.
+ pub fn new(token: impl Into<String>) -> Self {
+ Self {
+ token: AccessToken::new(token),
+ }
+ }
+}
+
+impl ProviderTokenSource for StaticTokenSource {
+ async fn get_access_token(
+ &self,
+ _link_id: Uuid,
+ _freshness: TokenFreshness,
+ ) -> Result<AccessToken, TokenError> {
+ Ok(self.token.clone())
+ }
+
+ async fn get_access_token_for_link(
+ &self,
+ _link: &Link,
+ _freshness: TokenFreshness,
+ ) -> Result<AccessToken, TokenError> {
+ Ok(self.token.clone())
+ }
+
+ async fn get_access_token_health_neutral(
+ &self,
+ _link: &Link,
+ _freshness: TokenFreshness,
+ ) -> Result<AccessToken, TokenError> {
+ Ok(self.token.clone())
+ }
+}
+
+fn map_token_acquisition_error(error: anyhow::Error) -> TokenError {
+ if is_reauth_required_error(&error) {
+ return TokenError::ReauthRequired;
+ }
+
+ tracing::warn!(error=?error, "Transient access-token acquisition failure");
+ transient_error("email provider access token is temporarily unavailable")
+}
+
+fn is_reauth_required_error(error: &anyhow::Error) -> bool {
+ error.chain().any(|cause| {
+ cause
+ .downcast_ref::<AuthServiceClientError>()
+ .is_some_and(|error| {
+ matches!(
+ error,
+ AuthServiceClientError::Forbidden | AuthServiceClientError::NotFound
+ )
+ })
+ })
+}
+
+fn transient_error(message: impl Into<String>) -> TokenError {
+ TokenError::Transient {
+ message: message.into(),
+ }
+}
diff --git a/services/email_service/src/outbound/email_api/token_source/test.rs b/services/email_service/src/outbound/email_api/token_source/test.rs
new file mode 100644
index 0000000000..5922a9ff43
--- /dev/null
+++ b/services/email_service/src/outbound/email_api/token_source/test.rs
@@ -0,0 +1,135 @@
+use authentication_service_client::error::AuthServiceClientError;
+use email_api_client::domain::models::{TokenError, TokenFreshness};
+use email_api_client::domain::ports::ProviderTokenSource;
+use macro_db_migrator::MACRO_DB_MIGRATIONS;
+use sqlx::PgPool;
+use uuid::Uuid;
+
+use super::{
+ StaticTokenSource, TokenHealthAction, clear_stale_reauth_flag, map_token_acquisition_error,
+ token_health_action,
+};
+
+async fn insert_link_needing_reauth(pool: &PgPool) -> Uuid {
+ let link_id = Uuid::now_v7();
+ sqlx::query!(
+ r#"
+ INSERT INTO email_links (
+ id, macro_id, fusionauth_user_id, email_address, provider, needs_reauth
+ )
+ VALUES ($1, $2, $2, $3, 'GMAIL', true)
+ "#,
+ link_id,
+ format!("token-health-{link_id}@example.com"),
+ )
+ .execute(pool)
+ .await
+ .unwrap();
+ link_id
+}
+
+async fn needs_reauth(pool: &PgPool, link_id: Uuid) -> bool {
+ sqlx::query_scalar!(
+ r#"SELECT needs_reauth FROM email_links WHERE id = $1"#,
+ link_id,
+ )
+ .fetch_one(pool)
+ .await
+ .unwrap()
+}
+
+#[sqlx::test(migrator = "MACRO_DB_MIGRATIONS")]
+async fn reauth_flagged_row_is_cleared_after_a_successful_fetch(pool: PgPool) {
+ let link_id = insert_link_needing_reauth(&pool).await;
+
+ clear_stale_reauth_flag(&pool, link_id).await;
+
+ assert!(!needs_reauth(&pool, link_id).await);
+}
+
+/// Pins the full token-health decision table. The DB effects of each action
+/// are covered by `clear_stale_reauth_flag` above and by email_db_client's
+/// `set_needs_reauth_is_edge_triggered` (notify fires only on the false→true
+/// transition, so repeat failures never re-enqueue).
+#[test]
+fn token_health_actions_cover_success_reauth_and_transient_outcomes() {
+ // Success against a row that may be flagged clears the flag.
+ assert_eq!(
+ token_health_action(&Ok("token".to_string()), true),
+ TokenHealthAction::ClearReauth
+ );
+ // Success against a known-healthy row skips the redundant UPDATE.
+ assert_eq!(
+ token_health_action(&Ok("token".to_string()), false),
+ TokenHealthAction::None
+ );
+ // A revoked or missing grant marks the link for reauthorization.
+ assert_eq!(
+ token_health_action(
+ &Err(anyhow::Error::new(AuthServiceClientError::Forbidden)),
+ true,
+ ),
+ TokenHealthAction::MarkReauth
+ );
+ assert_eq!(
+ token_health_action(
+ &Err(anyhow::Error::new(AuthServiceClientError::NotFound)),
+ false,
+ ),
+ TokenHealthAction::MarkReauth
+ );
+ // Transient infrastructure failures leave health untouched.
+ assert_eq!(
+ token_health_action(&Err(anyhow::anyhow!("redis unavailable")), true),
+ TokenHealthAction::None
+ );
+}
+
+#[test]
+fn forbidden_auth_service_response_requires_reauthorization() {
+ let error = anyhow::Error::new(AuthServiceClientError::Forbidden)
+ .context("failed to acquire provider token");
+
+ assert_eq!(
+ map_token_acquisition_error(error),
+ TokenError::ReauthRequired
+ );
+}
+
+#[test]
+fn missing_auth_service_grant_requires_reauthorization() {
+ let error = anyhow::Error::new(AuthServiceClientError::NotFound)
+ .context("failed to acquire provider token");
+
+ assert_eq!(
+ map_token_acquisition_error(error),
+ TokenError::ReauthRequired
+ );
+}
+
+#[test]
+fn infrastructure_failure_is_transient_and_sanitized() {
+ let error = anyhow::anyhow!("redis unavailable at redis://user:[email protected]");
+
+ assert_eq!(
+ map_token_acquisition_error(error),
+ TokenError::Transient {
+ message: "email provider access token is temporarily unavailable".to_string(),
+ }
+ );
+}
+
+#[tokio::test]
+async fn static_source_returns_token_for_both_freshness_modes() {
+ let source = StaticTokenSource::new("access-token");
+ let link_id = Uuid::new_v4();
+
+ for freshness in [TokenFreshness::Cached, TokenFreshness::Fresh] {
+ let token = source
+ .get_access_token(link_id, freshness)
+ .await
+ .expect("static token should be available");
+ assert_eq!(token.expose_secret(), "access-token");
+ }
+}
diff --git a/services/email_service/src/pubsub/backfill/backfill_attachment.rs b/services/email_service/src/pubsub/backfill/backfill_attachment.rs
index 0370c55540..ab5febe94e 100644
--- a/services/email_service/src/pubsub/backfill/backfill_attachment.rs
+++ b/services/email_service/src/pubsub/backfill/backfill_attachment.rs
@@ -10,10 +10,9 @@ use uuid::Uuid;
/// this step is invoked by the UpdateMetadata step. it uploads the specified attachment as a
/// Macro document for the user. first checks the attachment doesn't already exist by querying
/// document_email table before fetching and uploading the attachment data.
-#[tracing::instrument(skip(ctx, access_token))]
+#[tracing::instrument(skip(ctx))]
pub async fn backfill_attachment(
ctx: &PubSubContext,
- access_token: &str,
link: &link::Link,
p: &BackfillAttachmentPayload,
) -> Result<(), ProcessingError> {
@@ -30,12 +29,10 @@ pub async fn backfill_attachment(
let ctx_upload = UploadAttachmentContext {
db: &ctx.db,
- redis_client: &ctx.redis_client,
- gmail_client: &ctx.gmail_client,
+ email_api: &ctx.email_api,
dss_client: &ctx.dss_client,
sfs_client: &ctx.sfs_client,
system_properties_service: &ctx.system_properties_service,
- access_token,
link,
};
@@ -44,12 +41,10 @@ pub async fn backfill_attachment(
upload_attachment(ctx_upload, &attachment_args)
.await
.map_err(|e| match e {
- UploadAttachmentError::RateLimitCheckFailed(_) => {
- ProcessingError::Retryable(DetailedError {
- reason: FailureReason::GmailApiRateLimited,
- source: anyhow::Error::new(e).context("Failed to upload attachment"),
- })
- }
+ UploadAttachmentError::RateLimited => ProcessingError::Retryable(DetailedError {
+ reason: FailureReason::GmailApiRateLimited,
+ source: anyhow::Error::new(e).context("Failed to upload attachment"),
+ }),
_ => ProcessingError::NonRetryable(DetailedError {
reason: FailureReason::GmailApiFailed,
source: anyhow::Error::new(e).context("Failed to upload attachment"),
diff --git a/services/email_service/src/pubsub/backfill/backfill_message.rs b/services/email_service/src/pubsub/backfill/backfill_message.rs
index c40cb8f27a..4f27bd60ed 100644
--- a/services/email_service/src/pubsub/backfill/backfill_message.rs
+++ b/services/email_service/src/pubsub/backfill/backfill_message.rs
@@ -1,67 +1,34 @@
-use crate::convert::map_message_resource_to_service;
+use crate::pubsub::backfill::email_api_error::map_email_api_error;
use crate::pubsub::backfill::increment_counters;
use crate::pubsub::context::PubSubContext;
-use crate::pubsub::util::{
- CheckGmailRateLimitArgs, CrmContactRecipient, check_gmail_rate_limit,
- enqueue_populate_crm_contacts,
-};
+use crate::pubsub::util::{CrmContactRecipient, enqueue_populate_crm_contacts};
use crate::util::process_pre_insert::process_message_pre_insert;
-use anyhow::Context;
use models_email::email::service::backfill::{BackfillMessagePayload, JobScopedPayload};
use models_email::email::service::link;
use models_email::email::service::pubsub::{DetailedError, FailureReason, ProcessingError};
-use models_email::gmail::operations::GmailApiOperation;
/// This step is invoked by BackfillThread once for each message in the thread.
/// Creates a message object in the database. If the message is the last message in
/// the thread to be processed, it sends an UpdateThreadMetadata message for the thread.
-#[tracing::instrument(skip(ctx, access_token))]
+#[tracing::instrument(skip(ctx))]
pub async fn backfill_message(
ctx: &PubSubContext,
- access_token: &str,
scope: &JobScopedPayload<BackfillMessagePayload>,
link: &link::Link,
) -> Result<(), ProcessingError> {
let p = &scope.payload;
- check_gmail_rate_limit(CheckGmailRateLimitArgs {
- redis_client: &ctx.redis_client,
- link_id: link.id,
- gmail_operation: GmailApiOperation::MessagesGet,
- retryable: true,
- is_backfill: true,
- })
- .await?;
-
- // get message from gmail
- let message_resource = match ctx
- .gmail_client
- .get_message(access_token, &p.message_provider_id)
+ let fetched = ctx
+ .email_api
+ .get_message(link.id, &p.message_provider_id)
.await
- {
- Ok(Some(message)) => message,
- Ok(None) => {
- return Err(ProcessingError::NonRetryable(DetailedError {
- reason: FailureReason::MessageNotFoundInProvider,
- source: anyhow::anyhow!("Message {} not found in Gmail", p.message_provider_id),
- }));
- }
- Err(e) => {
- return Err(ProcessingError::Retryable(DetailedError {
- reason: FailureReason::GmailApiFailed,
- source: e.context("Gmail API failed to get message"),
- }));
- }
- };
-
- // Map Gmail resource to service model (IDs are generated in the parse function)
- let mut message = map_message_resource_to_service(message_resource, link.id)
- .context("Failed to map message resource to service")
- .map_err(|e| {
+ .map_err(|error| map_email_api_error(error, "Failed to get provider message"))?
+ .ok_or_else(|| {
ProcessingError::NonRetryable(DetailedError {
- reason: FailureReason::GmailApiFailed,
- source: e,
+ reason: FailureReason::MessageNotFoundInProvider,
+ source: anyhow::anyhow!("Message {} not found in provider", p.message_provider_id),
})
})?;
+ let mut message = fetched.message;
process_message_pre_insert(&mut message).await;
diff --git a/services/email_service/src/pubsub/backfill/backfill_thread.rs b/services/email_service/src/pubsub/backfill/backfill_thread.rs
index 19a4c060e3..bfd1e29c89 100644
--- a/services/email_service/src/pubsub/backfill/backfill_thread.rs
+++ b/services/email_service/src/pubsub/backfill/backfill_thread.rs
@@ -1,22 +1,20 @@
+use crate::pubsub::backfill::email_api_error::map_email_api_error;
use crate::pubsub::backfill::increment_counters::incr_completed_threads;
use crate::pubsub::context::PubSubContext;
-use crate::pubsub::util::{CheckGmailRateLimitArgs, check_gmail_rate_limit};
use models_email::email::service::backfill::{
BackfillMessagePayload, BackfillOperation, BackfillPubsubMessage, BackfillThreadPayload,
JobScopedPayload,
};
use models_email::email::service::link;
use models_email::email::service::pubsub::{DetailedError, FailureReason, ProcessingError};
-use models_email::gmail::operations::GmailApiOperation;
use std::collections::HashSet;
/// This step is invoked by ListThreads for each thread being backfilled.
/// Creates the thread object in the database, fetches the message ids for the thread
/// from the gmail api, and sends a BackfillMessage message for each message_id.
-#[tracing::instrument(skip(ctx, access_token))]
+#[tracing::instrument(skip(ctx))]
pub async fn backfill_thread(
ctx: &PubSubContext,
- access_token: &str,
scope: &JobScopedPayload<BackfillThreadPayload>,
link: &link::Link,
) -> Result<(), ProcessingError> {
@@ -39,50 +37,23 @@ pub async fn backfill_thread(
})
})?;
- // if the thread already exists, skip backfilling and update redis counters
- if !existing_threads.is_empty() {
+ // If the thread already exists: recovery jobs refresh it (backfilling any
+ // messages that arrived in the sync gap), other jobs skip it and update
+ // redis counters.
+ if let Some(existing_thread_db_id) = existing_threads.get(&thread_provider_id) {
+ if p.refresh_existing {
+ return refresh_existing_thread(ctx, scope, link, *existing_thread_db_id).await;
+ }
incr_completed_threads(ctx, link, scope.job_id).await?;
return Ok(());
}
- check_gmail_rate_limit(CheckGmailRateLimitArgs {
- redis_client: &ctx.redis_client,
- link_id: link.id,
- gmail_operation: GmailApiOperation::ThreadsGet,
- retryable: true,
- is_backfill: true,
- })
- .await?;
// fetch all message_ids of the thread
- let message_ids = match ctx
- .gmail_client
- .get_message_ids_for_thread(access_token, &thread_provider_id)
- .await
- {
- Ok(ids) => ids,
- Err(e) => {
- return Err(ProcessingError::Retryable(DetailedError {
- reason: FailureReason::GmailApiFailed,
- source: e.context(format!(
- "Gmail API failed to get message IDs for thread {}",
- thread_provider_id
- )),
- }));
- }
- };
-
- ctx.redis_client
- .init_backfill_thread_progress(scope.job_id, &thread_provider_id, message_ids.len() as i32)
+ let message_ids = ctx
+ .email_api
+ .get_message_ids_for_thread(link.id, &thread_provider_id)
.await
- .map_err(|e| {
- ProcessingError::Retryable(DetailedError {
- reason: FailureReason::RedisQueryFailed,
- source: e.context(format!(
- "Failed to create entry in redis for thread {}",
- &thread_provider_id
- )),
- })
- })?;
+ .map_err(|error| map_email_api_error(error, "Failed to get provider thread message IDs"))?;
// insert thread object
let thread_db_id = email_db_client::threads::insert::insert_blank_thread(
@@ -102,7 +73,89 @@ pub async fn backfill_thread(
})?;
// create backfill pubsub message for each email message
- for message_id in message_ids.clone() {
+ enqueue_backfill_messages(ctx, scope, link, thread_db_id, message_ids).await
+}
+
+/// Recovery-job path for a thread that is already in the database: fetch the
+/// provider's message ids and backfill only the messages we are missing, so
+/// replies that arrived during a sync gap are recovered.
+///
+/// Job accounting matches the fresh-thread path: with nothing missing the
+/// thread completes immediately (like the skip path); otherwise its redis
+/// progress counter is initialized to the missing count and the enqueued
+/// messages complete it.
+async fn refresh_existing_thread(
+ ctx: &PubSubContext,
+ scope: &JobScopedPayload<BackfillThreadPayload>,
+ link: &link::Link,
+ thread_db_id: uuid::Uuid,
+) -> Result<(), ProcessingError> {
+ let p = &scope.payload;
+
+ let message_ids = ctx
+ .email_api
+ .get_message_ids_for_thread(link.id, &p.thread_provider_id)
+ .await
+ .map_err(|error| map_email_api_error(error, "Failed to get provider thread message IDs"))?;
+
+ let existing_message_ids =
+ email_db_client::messages::get::filter_existing_provider_message_ids(
+ &ctx.db,
+ link.id,
+ &message_ids,
+ )
+ .await
+ .map_err(|e| {
+ ProcessingError::Retryable(DetailedError {
+ reason: FailureReason::DatabaseQueryFailed,
+ source: e.context(format!(
+ "DB check for existing messages of thread {} failed",
+ p.thread_provider_id
+ )),
+ })
+ })?;
+
+ let missing_message_ids: Vec<String> = message_ids
+ .into_iter()
+ .filter(|message_id| !existing_message_ids.contains(message_id))
+ .collect();
+
+ if missing_message_ids.is_empty() {
+ return incr_completed_threads(ctx, link, scope.job_id).await;
+ }
+
+ enqueue_backfill_messages(ctx, scope, link, thread_db_id, missing_message_ids).await
+}
+
+/// Initializes the thread's redis progress counter and enqueues one
+/// BackfillMessage per message id.
+async fn enqueue_backfill_messages(
+ ctx: &PubSubContext,
+ scope: &JobScopedPayload<BackfillThreadPayload>,
+ link: &link::Link,
+ thread_db_id: uuid::Uuid,
+ message_ids: Vec<String>,
+) -> Result<(), ProcessingError> {
+ let p = &scope.payload;
+
+ ctx.redis_client
+ .init_backfill_thread_progress(
+ scope.job_id,
+ &p.thread_provider_id,
+ message_ids.len() as i32,
+ )
+ .await
+ .map_err(|e| {
+ ProcessingError::Retryable(DetailedError {
+ reason: FailureReason::RedisQueryFailed,
+ source: e.context(format!(
+ "Failed to create entry in redis for thread {}",
+ &p.thread_provider_id
+ )),
+ })
+ })?;
+
+ for message_id in message_ids {
let new_payload = BackfillMessagePayload {
thread_provider_id: p.thread_provider_id.clone(),
thread_db_id,
diff --git a/services/email_service/src/pubsub/backfill/email_api_error.rs b/services/email_service/src/pubsub/backfill/email_api_error.rs
new file mode 100644
index 0000000000..080499cf06
--- /dev/null
+++ b/services/email_service/src/pubsub/backfill/email_api_error.rs
@@ -0,0 +1,31 @@
+use email_api_client::domain::models::EmailApiError;
+use models_email::email::service::pubsub::{DetailedError, FailureReason, ProcessingError};
+
+#[cfg(test)]
+mod test;
+
+pub(crate) fn map_email_api_error(error: EmailApiError, context: &'static str) -> ProcessingError {
+ // Exhaustive: a new EmailApiError variant must force a policy decision
+ // here rather than silently falling into a catch-all.
+ let reason = match &error {
+ EmailApiError::RateLimited { .. } => FailureReason::GmailApiRateLimited,
+ EmailApiError::AuthRequired => FailureReason::AccessTokenFetchFailed,
+ EmailApiError::OutdatedCursor => FailureReason::OutdatedHistoryId,
+ EmailApiError::Forbidden
+ | EmailApiError::NotFound
+ | EmailApiError::Conflict
+ | EmailApiError::Transient { .. }
+ | EmailApiError::Permanent { .. } => FailureReason::GmailApiFailed,
+ };
+ let is_retryable = error.is_transient();
+ let detail = DetailedError {
+ reason,
+ source: anyhow::Error::new(error).context(context),
+ };
+
+ if is_retryable {
+ ProcessingError::Retryable(detail)
+ } else {
+ ProcessingError::NonRetryable(detail)
+ }
+}
diff --git a/services/email_service/src/pubsub/backfill/email_api_error/test.rs b/services/email_service/src/pubsub/backfill/email_api_error/test.rs
new file mode 100644
index 0000000000..b0259a5037
--- /dev/null
+++ b/services/email_service/src/pubsub/backfill/email_api_error/test.rs
@@ -0,0 +1,75 @@
+use std::time::Duration;
+
+use super::*;
+
+fn assert_mapping(error: EmailApiError, retryable: bool, reason: FailureReason) {
+ let mapped = map_email_api_error(error, "backfill provider operation failed");
+ let detail = match mapped {
+ ProcessingError::Retryable(detail) if retryable => detail,
+ ProcessingError::NonRetryable(detail) if !retryable => detail,
+ other => panic!("unexpected retry classification: {other:?}"),
+ };
+
+ assert_eq!(detail.reason, reason);
+ assert!(
+ detail
+ .source
+ .to_string()
+ .contains("backfill provider operation failed")
+ );
+}
+
+#[test]
+fn maps_rate_limits_to_retryable_rate_limit_failures() {
+ assert_mapping(
+ EmailApiError::RateLimited {
+ retry_after: Some(Duration::from_secs(5)),
+ origin: email_api_client::domain::models::RateLimitOrigin::Provider,
+ },
+ true,
+ FailureReason::GmailApiRateLimited,
+ );
+}
+
+#[test]
+fn maps_transient_provider_failures_to_retryable_api_failures() {
+ assert_mapping(
+ EmailApiError::Transient {
+ message: "provider unavailable".to_string(),
+ },
+ true,
+ FailureReason::GmailApiFailed,
+ );
+}
+
+#[test]
+fn maps_auth_failures_to_terminal_token_failures() {
+ assert_mapping(
+ EmailApiError::AuthRequired,
+ false,
+ FailureReason::AccessTokenFetchFailed,
+ );
+}
+
+#[test]
+fn maps_outdated_cursors_to_terminal_history_failures() {
+ assert_mapping(
+ EmailApiError::OutdatedCursor,
+ false,
+ FailureReason::OutdatedHistoryId,
+ );
+}
+
+#[test]
+fn maps_deterministic_provider_failures_to_terminal_api_failures() {
+ for error in [
+ EmailApiError::Forbidden,
+ EmailApiError::NotFound,
+ EmailApiError::Conflict,
+ EmailApiError::Permanent {
+ message: "invalid response".to_string(),
+ },
+ ] {
+ assert_mapping(error, false, FailureReason::GmailApiFailed);
+ }
+}
diff --git a/services/email_service/src/pubsub/backfill/init.rs b/services/email_service/src/pubsub/backfill/init.rs
index b839f598aa..25d323fab2 100644
--- a/services/email_service/src/pubsub/backfill/init.rs
+++ b/services/email_service/src/pubsub/backfill/init.rs
@@ -7,16 +7,15 @@ use models_email::email::service::{
/// Map one initialization queue delivery into the email-backfill application service.
#[tracing::instrument(
- skip(ctx, access_token, link, backfill_job),
+ skip(ctx, link, backfill_job),
fields(link_id = %link.id, job_id = %backfill_job.id),
err
)]
pub async fn init_backfill(
ctx: &PubSubContext,
- access_token: &str,
scope: &JobScopedPayload<InitPayload>,
link: &Link,
backfill_job: &BackfillJob,
) -> Result<(), ProcessingError> {
- backfill_init_service::init_backfill(ctx, access_token, scope, link, backfill_job).await
+ backfill_init_service::init_backfill(ctx, scope, link, backfill_job).await
}
diff --git a/services/email_service/src/pubsub/backfill/list_threads.rs b/services/email_service/src/pubsub/backfill/list_threads.rs
index 4ebebf74db..70a493a476 100644
--- a/services/email_service/src/pubsub/backfill/list_threads.rs
+++ b/services/email_service/src/pubsub/backfill/list_threads.rs
@@ -1,6 +1,6 @@
+use super::email_api_error::map_email_api_error;
use super::increment_counters;
use crate::pubsub::context::PubSubContext;
-use crate::pubsub::util::{CheckGmailRateLimitArgs, check_gmail_rate_limit};
use models_email::email::service::backfill::{
BackfillJob, BackfillOperation, BackfillPubsubMessage, BackfillThreadPayload, JobScopedPayload,
};
@@ -8,7 +8,6 @@ use models_email::email::service::link;
use models_email::email::service::pubsub::{DetailedError, FailureReason, ProcessingError};
use models_email::email::service::thread::ListThreadsPayload;
use models_email::gmail::labels::SystemLabelID;
-use models_email::gmail::operations::GmailApiOperation;
use std::cmp::min;
// the max size allowed by the gmail api
@@ -34,13 +33,12 @@ const SENT_CONTACT_SEED_LIMIT: u32 = 200;
/// most-recent-to-least sweep.
pub async fn list_threads(
ctx: &PubSubContext,
- access_token: &str,
scope: &JobScopedPayload<ListThreadsPayload>,
link: &link::Link,
job: &BackfillJob,
) -> Result<(), ProcessingError> {
if scope.payload.priority_pass {
- return list_priority_threads(ctx, access_token, scope, link, job).await;
+ return list_priority_threads(ctx, scope, link, job).await;
}
let p = &scope.payload;
@@ -52,34 +50,17 @@ pub async fn list_threads(
total_threads - threads_retrieved_count,
);
- check_gmail_rate_limit(CheckGmailRateLimitArgs {
- redis_client: &ctx.redis_client,
- link_id: link.id,
- gmail_operation: GmailApiOperation::ThreadsList,
- retryable: true,
- is_backfill: true,
- })
- .await?;
// get batch of thread ids
- let thread_list = match ctx
- .gmail_client
+ let thread_list = ctx
+ .email_api
.list_threads(
- access_token,
+ link.id,
num_threads_to_list as u32,
p.next_page_token.as_deref(),
&[],
)
.await
- {
- Ok(list) => list,
- Err(e) => {
- // Construct the structured Retryable error and return immediately.
- return Err(ProcessingError::Retryable(DetailedError {
- reason: FailureReason::GmailApiFailed,
- source: e.context("Failed to list threads from Gmail API"),
- }));
- }
- };
+ .map_err(|error| map_email_api_error(error, "Failed to list provider threads"))?;
// pass along token if it exists for fetching next batch of thread_ids
let next_page_token = thread_list.next_page_token.clone();
@@ -107,6 +88,7 @@ pub async fn list_threads(
job_id: scope.job_id,
payload: BackfillThreadPayload {
thread_provider_id: thread.provider_id.clone(),
+ refresh_existing: p.refresh_existing,
},
}),
};
@@ -131,6 +113,7 @@ pub async fn list_threads(
payload: ListThreadsPayload {
next_page_token,
priority_pass: false,
+ refresh_existing: p.refresh_existing,
},
}),
};
@@ -170,7 +153,6 @@ pub async fn list_threads(
/// batch math and must stay equal to the real mailbox count).
async fn list_priority_threads(
ctx: &PubSubContext,
- access_token: &str,
scope: &JobScopedPayload<ListThreadsPayload>,
link: &link::Link,
job: &BackfillJob,
@@ -180,35 +162,20 @@ async fn list_priority_threads(
let num_threads_to_list = min(PRIORITY_PASS_THREAD_LIMIT as i32, job.total_threads);
if num_threads_to_list > 0 {
- check_gmail_rate_limit(CheckGmailRateLimitArgs {
- redis_client: &ctx.redis_client,
- link_id: link.id,
- gmail_operation: GmailApiOperation::ThreadsList,
- retryable: true,
- is_backfill: true,
- })
- .await?;
-
// CATEGORY_PERSONAL is Gmail's "important to a human" bucket; seeding
// these first means a brand-new user sees signal immediately.
- let thread_list = match ctx
- .gmail_client
+ let thread_list = ctx
+ .email_api
.list_threads(
- access_token,
+ link.id,
num_threads_to_list as u32,
None,
&[SystemLabelID::CategoryPersonal.as_str()],
)
.await
- {
- Ok(list) => list,
- Err(e) => {
- return Err(ProcessingError::Retryable(DetailedError {
- reason: FailureReason::GmailApiFailed,
- source: e.context("Failed to list priority threads from Gmail API"),
- }));
- }
- };
+ .map_err(|error| {
+ map_email_api_error(error, "Failed to list priority provider threads")
+ })?;
let threads = thread_list.threads;
@@ -238,6 +205,7 @@ async fn list_priority_threads(
job_id: scope.job_id,
payload: BackfillThreadPayload {
thread_provider_id: thread.provider_id.clone(),
+ refresh_existing: false,
},
}),
};
@@ -262,7 +230,7 @@ async fn list_priority_threads(
// the priority-pass total_threads bump, so it must never return a retryable
// error (that would re-run the pass and double-bump the counter).
#[cfg(feature = "contacts_sync")]
- enqueue_sent_contact_seeds(ctx, access_token, scope, link).await;
+ enqueue_sent_contact_seeds(ctx, scope, link).await;
// Hand off to the normal most-recent-to-least sweep from the beginning. This
// runs regardless of how many priority threads were found.
@@ -273,6 +241,7 @@ async fn list_priority_threads(
payload: ListThreadsPayload {
next_page_token: None,
priority_pass: false,
+ refresh_existing: scope.payload.refresh_existing,
},
}),
};
@@ -303,29 +272,15 @@ async fn list_priority_threads(
#[cfg(feature = "contacts_sync")]
async fn enqueue_sent_contact_seeds(
ctx: &PubSubContext,
- access_token: &str,
scope: &JobScopedPayload<ListThreadsPayload>,
link: &link::Link,
) {
use models_email::email::service::backfill::SeedSentContactPayload;
- if let Err(e) = check_gmail_rate_limit(CheckGmailRateLimitArgs {
- redis_client: &ctx.redis_client,
- link_id: link.id,
- gmail_operation: GmailApiOperation::MessagesList,
- retryable: true,
- is_backfill: true,
- })
- .await
- {
- tracing::warn!(error = ?e, link_id = %link.id, "Skipping sent-contact seed: gmail rate limited");
- return;
- }
-
let message_ids = match ctx
- .gmail_client
+ .email_api
.list_messages(
- access_token,
+ link.id,
SENT_CONTACT_SEED_LIMIT,
&[SystemLabelID::Sent.as_str()],
)
@@ -333,7 +288,7 @@ async fn enqueue_sent_contact_seeds(
{
Ok(ids) => ids,
Err(e) => {
- tracing::error!(error = ?e, link_id = %link.id, "Skipping sent-contact seed: failed to list sent messages");
+ tracing::error!(error = ?e, link_id = %link.id, "Skipping sent-contact seed: failed to list provider sent messages");
return;
}
};
diff --git a/services/email_service/src/pubsub/backfill/mod.rs b/services/email_service/src/pubsub/backfill/mod.rs
index 6967e0a6a8..16d0607322 100644
--- a/services/email_service/src/pubsub/backfill/mod.rs
+++ b/services/email_service/src/pubsub/backfill/mod.rs
@@ -4,6 +4,7 @@ mod backfill_thread;
mod calendar_google_backfill;
mod depopulate_crm_contact;
mod depopulate_crm_for_user;
+pub(crate) mod email_api_error;
mod error_handlers;
mod increment_counters;
mod init;
diff --git a/services/email_service/src/pubsub/backfill/process.rs b/services/email_service/src/pubsub/backfill/process.rs
index 55698956db..4e565714dc 100644
--- a/services/email_service/src/pubsub/backfill/process.rs
+++ b/services/email_service/src/pubsub/backfill/process.rs
@@ -4,10 +4,8 @@ use crate::pubsub::backfill::{
list_threads, populate_crm_contact, populate_crm_for_user, seed_sent_contact, update_metadata,
};
use crate::pubsub::context::PubSubContext;
-use crate::util::gmail::auth::{
- fetch_token_or_mark_reauth, fetch_token_or_mark_reauth_no_cache, is_reauth_required_error,
-};
use anyhow::Context;
+use email_api_client::domain::models::{EmailApiError, TokenFreshness};
use models_email::email::service::backfill::{
BackfillJob, BackfillJobStatus, BackfillOperation, BackfillPubsubMessage, JobScopedPayload,
};
@@ -85,40 +83,32 @@ async fn inner_process_message(
) -> Result<(), ProcessingError> {
match &data.backfill_operation {
BackfillOperation::Init(scope) => {
- let Some(JobContext {
- link,
- backfill_job,
- access_token,
- }) = fetch_job_context(ctx, scope, false).await?
+ let Some(JobContextNoToken { link, backfill_job }) =
+ fetch_job_context_no_token(ctx, scope, false).await?
else {
return Ok(());
};
- init::init_backfill(ctx, &access_token, scope, &link, &backfill_job).await
+ init::init_backfill(ctx, scope, &link, &backfill_job).await
}
BackfillOperation::ListThreads(scope) => {
- let Some(JobContext {
- link,
- backfill_job,
- access_token,
- }) = fetch_job_context(ctx, scope, false).await?
+ let Some(JobContextNoToken { link, backfill_job }) =
+ fetch_job_context_no_token(ctx, scope, false).await?
else {
return Ok(());
};
- list_threads::list_threads(ctx, &access_token, scope, &link, &backfill_job).await
+ list_threads::list_threads(ctx, scope, &link, &backfill_job).await
}
BackfillOperation::BackfillThread(scope) => {
- let Some(JobContext {
- link, access_token, ..
- }) = fetch_job_context(ctx, scope, false).await?
+ let Some(JobContextNoToken { link, .. }) =
+ fetch_job_context_no_token(ctx, scope, false).await?
else {
return Ok(());
};
- backfill_thread::backfill_thread(ctx, &access_token, scope, &link).await
+ backfill_thread::backfill_thread(ctx, scope, &link).await
}
BackfillOperation::BackfillMessage(scope) => {
- let Some(JobContext {
- link, access_token, ..
- }) = fetch_job_context(ctx, scope, false).await?
+ let Some(JobContextNoToken { link, .. }) =
+ fetch_job_context_no_token(ctx, scope, false).await?
else {
// BackfillMessage owns per-thread progress in addition to
// the job-level progress that fetch_job_context already
@@ -133,7 +123,7 @@ async fn inner_process_message(
.await;
return Ok(());
};
- backfill_message::backfill_message(ctx, &access_token, scope, &link).await
+ backfill_message::backfill_message(ctx, scope, &link).await
}
BackfillOperation::UpdateThreadMetadata(scope) => {
// UpdateThreadMetadata is a DB-only step; skip the Gmail token
@@ -147,14 +137,12 @@ async fn inner_process_message(
update_metadata::update_thread_metadata(ctx, scope, &link).await
}
BackfillOperation::BackfillAttachment(scope) => {
- let Some(JobContext {
- link, access_token, ..
- }) = fetch_job_context(ctx, scope, true).await?
+ let Some(JobContextNoToken { link, .. }) =
+ fetch_job_context_no_token(ctx, scope, true).await?
else {
return Ok(());
};
- backfill_attachment::backfill_attachment(ctx, &access_token, &link, &scope.payload)
- .await
+ backfill_attachment::backfill_attachment(ctx, &link, &scope.payload).await
}
BackfillOperation::CalendarGoogleBackfill(scope) => {
if let Some(parked) = park_calendar_delivery(ctx, scope.payload.calendar_job_id).await {
@@ -164,28 +152,26 @@ async fn inner_process_message(
// Calendar jobs can be created immediately after an incremental
// Google scope grant. Bypass the Gmail token cache so this job does
// not reuse a pre-consent access token that lacks calendar scopes.
- let access_token = fetch_token_or_mark_reauth_no_cache(
- &link,
- &ctx.db,
- &ctx.redis_client,
- &ctx.auth_service_client,
- &ctx.sqs_client,
- )
- .await
- .map_err(|e| {
- let detail = DetailedError {
- reason: FailureReason::AccessTokenFetchFailed,
- source: e.context("failed to fetch token for Google Calendar backfill"),
- };
- if is_reauth_required_error(&detail.source) {
- ProcessingError::NonRetryable(detail)
- } else {
- ProcessingError::Retryable(detail)
- }
- })?;
+ let access_token = ctx
+ .email_api
+ .get_access_token(link.id, TokenFreshness::Fresh)
+ .await
+ .map_err(|error| {
+ let is_auth_required = matches!(error, EmailApiError::AuthRequired);
+ let detail = DetailedError {
+ reason: FailureReason::AccessTokenFetchFailed,
+ source: anyhow::anyhow!(error)
+ .context("failed to fetch token for Google Calendar backfill"),
+ };
+ if is_auth_required {
+ ProcessingError::NonRetryable(detail)
+ } else {
+ ProcessingError::Retryable(detail)
+ }
+ })?;
calendar_google_backfill::calendar_google_backfill(
ctx,
- &access_token,
+ access_token.expose_secret(),
&link,
&scope.payload,
)
@@ -195,13 +181,12 @@ async fn inner_process_message(
increment_counters::finalize_backfill(ctx, scope.link_id, scope.job_id).await
}
BackfillOperation::SeedSentContact(scope) => {
- let Some(JobContext {
- link, access_token, ..
- }) = fetch_job_context(ctx, scope, false).await?
+ let Some(JobContextNoToken { link, .. }) =
+ fetch_job_context_no_token(ctx, scope, false).await?
else {
return Ok(());
};
- seed_sent_contact::seed_sent_contact(ctx, &access_token, scope, &link).await
+ seed_sent_contact::seed_sent_contact(ctx, scope, &link).await
}
BackfillOperation::PopulateCrmContact(scope) => {
let link = fetch_link(ctx, scope.link_id).await?;
@@ -220,20 +205,9 @@ async fn inner_process_message(
}
}
-/// The pre-fetched context every job-scoped handler used to receive from
-/// the top-level dispatcher: the link the operation targets, the backfill
-/// job it belongs to, and a fresh Gmail access token for the link. Used by
-/// handlers that talk to Gmail.
-struct JobContext {
- link: link::Link,
- backfill_job: BackfillJob,
- access_token: String,
-}
-
/// Same as [`JobContext`] but without a Gmail access token. Used by
-/// handlers that only talk to the database (e.g. UpdateThreadMetadata) so
-/// they don't fail with `AccessTokenFetchFailed` when a user's token is
-/// revoked or temporarily unavailable.
+/// handlers that do not require a raw Gmail access token. Provider operations
+/// can still fetch tokens through `email_api`.
struct JobContextNoToken {
link: link::Link,
backfill_job: BackfillJob,
@@ -283,44 +257,6 @@ async fn fetch_job_context_no_token<P>(
Ok(Some(JobContextNoToken { link, backfill_job }))
}
-/// As [`fetch_job_context_no_token`], plus a fresh Gmail access token for
-/// the link. For handlers that need to talk to Gmail (Init, ListThreads,
-/// BackfillThread, BackfillMessage, BackfillAttachment). The attachment
-/// finalization path opts into completed jobs because those messages are
-/// intentionally produced by [`BackfillOperation::FinalizeBackfill`].
-async fn fetch_job_context<P>(
- ctx: &PubSubContext,
- scope: &JobScopedPayload<P>,
- allow_complete: bool,
-) -> Result<Option<JobContext>, ProcessingError> {
- let Some(JobContextNoToken { link, backfill_job }) =
- fetch_job_context_no_token(ctx, scope, allow_complete).await?
- else {
- return Ok(None);
- };
-
- let access_token = fetch_token_or_mark_reauth(
- &link,
- &ctx.db,
- &ctx.redis_client,
- &ctx.auth_service_client,
- &ctx.sqs_client,
- )
- .await
- .map_err(|e| {
- ProcessingError::NonRetryable(DetailedError {
- reason: FailureReason::AccessTokenFetchFailed,
- source: e.context("Failed to fetch access token from link"),
- })
- })?;
-
- Ok(Some(JobContext {
- link,
- backfill_job,
- access_token,
- }))
-}
-
/// Looks up a link by id, mapping the absence into a NonRetryable error
/// (the message names a link that doesn't exist; retrying won't help).
async fn fetch_link(ctx: &PubSubContext, link_id: Uuid) -> Result<link::Link, ProcessingError> {
diff --git a/services/email_service/src/pubsub/backfill/seed_sent_contact.rs b/services/email_service/src/pubsub/backfill/seed_sent_contact.rs
index 36d3628a51..3d35dd0636 100644
--- a/services/email_service/src/pubsub/backfill/seed_sent_contact.rs
+++ b/services/email_service/src/pubsub/backfill/seed_sent_contact.rs
@@ -1,14 +1,12 @@
use std::collections::HashSet;
-use crate::convert::map_message_resource_to_service;
+use crate::pubsub::backfill::email_api_error::map_email_api_error;
use crate::pubsub::context::PubSubContext;
-use crate::pubsub::util::{CheckGmailRateLimitArgs, check_gmail_rate_limit};
use contacts::domain::ports::ContactsIngress;
use macro_user_id::user_id::MacroUserIdStr;
use models_email::email::service::backfill::{JobScopedPayload, SeedSentContactPayload};
use models_email::email::service::link;
use models_email::email::service::pubsub::{DetailedError, FailureReason, ProcessingError};
-use models_email::gmail::operations::GmailApiOperation;
/// Consumer for `BackfillOperation::SeedSentContact`. Fetches one recent sent
/// message and enqueues a sender<->recipient contact connection for every
@@ -19,46 +17,26 @@ use models_email::gmail::operations::GmailApiOperation;
/// Each connection is enqueued as a 2-element set (`{owner, recipient}`) rather
/// than the whole recipient list, so the contacts service connects the sender
/// to each recipient only — not the recipients to each other.
-#[tracing::instrument(skip(ctx, access_token))]
+#[tracing::instrument(skip(ctx))]
pub async fn seed_sent_contact(
ctx: &PubSubContext,
- access_token: &str,
scope: &JobScopedPayload<SeedSentContactPayload>,
link: &link::Link,
) -> Result<(), ProcessingError> {
let p = &scope.payload;
- check_gmail_rate_limit(CheckGmailRateLimitArgs {
- redis_client: &ctx.redis_client,
- link_id: link.id,
- gmail_operation: GmailApiOperation::MessagesGet,
- retryable: true,
- is_backfill: true,
- })
- .await?;
-
- let message_resource = match ctx
- .gmail_client
- .get_message(access_token, &p.message_provider_id)
+ let Some(fetched) = ctx
+ .email_api
+ .get_message(link.id, &p.message_provider_id)
.await
- {
- Ok(Some(message)) => message,
+ .map_err(|error| {
+ map_email_api_error(error, "Failed to get sent message for contact seed")
+ })?
+ else {
// The message was deleted between listing and this fetch; nothing to seed.
- Ok(None) => return Ok(()),
- Err(e) => {
- return Err(ProcessingError::Retryable(DetailedError {
- reason: FailureReason::GmailApiFailed,
- source: e.context("Gmail API failed to get sent message for contact seed"),
- }));
- }
+ return Ok(());
};
-
- let message = map_message_resource_to_service(message_resource, link.id).map_err(|e| {
- ProcessingError::NonRetryable(DetailedError {
- reason: FailureReason::GmailApiFailed,
- source: e.context("Failed to map message resource to service"),
- })
- })?;
+ let message = fetched.message;
let self_email = link.email_address.0.as_ref().to_ascii_lowercase();
diff --git a/services/email_service/src/pubsub/backfill/worker.rs b/services/email_service/src/pubsub/backfill/worker.rs
index 5d678fb546..844f92bbec 100644
--- a/services/email_service/src/pubsub/backfill/worker.rs
+++ b/services/email_service/src/pubsub/backfill/worker.rs
@@ -1,3 +1,4 @@
+use crate::outbound::email_api::GmailApi;
use crate::pubsub::backfill::process;
use crate::pubsub::context::{
CalendarBackfillServices, CrmServiceType, NotificationIngressType, PubSubContext,
@@ -5,7 +6,6 @@ use crate::pubsub::context::{
};
use crate::pubsub::worker_lifecycle::run_until_cancelled;
use crate::util::redis::RedisClient;
-use authentication_service_client::AuthServiceClient;
use connection_gateway_client::client::ConnectionGatewayClient;
use contacts::domain::service::SqsContactsIngress;
use contacts::outbound::ingress::SqsContactsQueue;
@@ -23,8 +23,7 @@ pub async fn run_worker(
worker: sqs_worker::SQSWorker,
sqs_client: sqs_client::SQS,
contacts_ingress: Arc<SqsContactsIngress<SqsContactsQueue>>,
- gmail_client: gmail_client::GmailClient,
- auth_service_client: AuthServiceClient,
+ email_api: GmailApi,
redis_client: RedisClient,
notification_ingress_service: Arc<NotificationIngressType>,
sfs_client: StaticFileServiceClient,
@@ -41,8 +40,7 @@ pub async fn run_worker(
worker,
sqs_client,
contacts_ingress,
- gmail_client,
- auth_service_client,
+ email_api,
redis_client,
notification_ingress_service,
sfs_client,
@@ -67,8 +65,7 @@ pub async fn run_worker_with_cancellation(
worker: sqs_worker::SQSWorker,
sqs_client: sqs_client::SQS,
contacts_ingress: Arc<SqsContactsIngress<SqsContactsQueue>>,
- gmail_client: gmail_client::GmailClient,
- auth_service_client: AuthServiceClient,
+ email_api: GmailApi,
redis_client: RedisClient,
notification_ingress_service: Arc<NotificationIngressType>,
sfs_client: StaticFileServiceClient,
@@ -87,8 +84,7 @@ pub async fn run_worker_with_cancellation(
sqs_worker: worker.clone(),
sqs_client,
contacts_ingress,
- gmail_client,
- auth_service_client,
+ email_api,
redis_client,
notification_ingress_service,
sfs_client,
diff --git a/services/email_service/src/pubsub/context.rs b/services/email_service/src/pubsub/context.rs
index 134cd5941f..c7d879b327 100644
--- a/services/email_service/src/pubsub/context.rs
+++ b/services/email_service/src/pubsub/context.rs
@@ -1,6 +1,6 @@
+use crate::outbound::email_api::GmailApi;
use crate::pubsub::calendar_backfill_adapters::RedisCalendarRequestGate;
use crate::util::redis::RedisClient;
-use authentication_service_client::AuthServiceClient;
use calendar_events::{
domain::models::GoogleWatchConfig,
domain::service::{GoogleCalendarBackfillCoordinator, GoogleCalendarBackfillFailureService},
@@ -16,7 +16,6 @@ use crm::outbound::apollo_resolver::ApolloCompanyMetadataResolver;
use crm::outbound::companies_repo::CompaniesRepositoryImpl;
use crm::outbound::unfurl_resolver::UnfurlCompanyMetadataResolver;
use document_storage_service_client::DocumentStorageServiceClient;
-use gmail_client::GmailClient;
use macro_event_broker::{KafkaEventPublisher, MacroEventBrokerService};
use notification::domain::service::SqsNotificationIngress;
use notification::outbound::queue::SqsQueue;
@@ -129,8 +128,7 @@ pub struct PubSubContext {
pub sqs_worker: sqs_worker::SQSWorker,
pub sqs_client: sqs_client::SQS,
pub contacts_ingress: Arc<SqsContactsIngress<SqsContactsQueue>>,
- pub gmail_client: GmailClient,
- pub auth_service_client: AuthServiceClient,
+ pub email_api: GmailApi,
pub redis_client: RedisClient,
pub notification_ingress_service: Arc<NotificationIngressType>,
pub sfs_client: StaticFileServiceClient,
diff --git a/services/email_service/src/pubsub/gmail_ops/email_api_error.rs b/services/email_service/src/pubsub/gmail_ops/email_api_error.rs
new file mode 100644
index 0000000000..e187dfb2d3
--- /dev/null
+++ b/services/email_service/src/pubsub/gmail_ops/email_api_error.rs
@@ -0,0 +1,118 @@
+use email_api_client::domain::models::EmailApiError;
+use models_email::gmail::gmail_ops::GmailOpsPubsubMessage;
+use models_email::service::pubsub::{DetailedError, FailureReason, ProcessingError};
+
+use crate::pubsub::gmail_ops::worker::GmailOpsContext;
+
+#[cfg(test)]
+mod test;
+
+#[derive(Debug, PartialEq, Eq)]
+enum ErrorPolicy {
+ RateLimited,
+ Retry,
+ Permanent,
+}
+
+#[derive(Debug, PartialEq, Eq)]
+enum RateLimitRoute {
+ EnqueueRetry,
+ RetryAfterVisibilityTimeout,
+}
+
+fn error_policy(error: &EmailApiError) -> ErrorPolicy {
+ // Exhaustive: a new EmailApiError variant must force a policy decision
+ // here rather than silently dropping the operation as permanent.
+ match error {
+ EmailApiError::RateLimited { .. } => ErrorPolicy::RateLimited,
+ EmailApiError::Transient { .. } => ErrorPolicy::Retry,
+ EmailApiError::AuthRequired
+ | EmailApiError::Forbidden
+ | EmailApiError::NotFound
+ | EmailApiError::Conflict
+ | EmailApiError::OutdatedCursor
+ | EmailApiError::Permanent { .. } => ErrorPolicy::Permanent,
+ }
+}
+
+pub(crate) async fn handle_email_api_error(
+ ctx: &GmailOpsContext,
+ data: &GmailOpsPubsubMessage,
+ error: EmailApiError,
+) -> ProcessingError {
+ match error_policy(&error) {
+ ErrorPolicy::RateLimited => handle_rate_limit(ctx, data, error).await,
+ ErrorPolicy::Retry => processing_error(error, true),
+ ErrorPolicy::Permanent => processing_error(error, false),
+ }
+}
+
+async fn handle_rate_limit(
+ ctx: &GmailOpsContext,
+ data: &GmailOpsPubsubMessage,
+ error: EmailApiError,
+) -> ProcessingError {
+ if rate_limit_route(ctx.retry_worker) == RateLimitRoute::RetryAfterVisibilityTimeout {
+ tracing::info!(
+ link_id = %data.link_id,
+ "Gmail API rate limited in retry worker, message will be retried after visibility timeout"
+ );
+ return processing_error(error, true);
+ }
+
+ tracing::info!(
+ link_id = %data.link_id,
+ "Gmail API rate limited, moving message from primary queue to retry queue"
+ );
+ if let Err(enqueue_error) = ctx
+ .sqs_client
+ .enqueue_gmail_ops_retry_notification(data.clone())
+ .await
+ {
+ return ProcessingError::Retryable(DetailedError {
+ reason: FailureReason::SqsEnqueueFailed,
+ source: enqueue_error.context("Failed to enqueue gmail ops retry message"),
+ });
+ }
+
+ processing_error(error, false)
+}
+
+fn rate_limit_route(retry_worker: bool) -> RateLimitRoute {
+ if retry_worker {
+ RateLimitRoute::RetryAfterVisibilityTimeout
+ } else {
+ RateLimitRoute::EnqueueRetry
+ }
+}
+
+fn processing_error(error: EmailApiError, retryable: bool) -> ProcessingError {
+ let reason = match error {
+ EmailApiError::RateLimited { .. } => FailureReason::GmailApiRateLimited,
+ EmailApiError::AuthRequired => FailureReason::AccessTokenFetchFailed,
+ EmailApiError::OutdatedCursor => FailureReason::OutdatedHistoryId,
+ EmailApiError::Forbidden
+ | EmailApiError::NotFound
+ | EmailApiError::Conflict
+ | EmailApiError::Transient { .. }
+ | EmailApiError::Permanent { .. } => FailureReason::GmailApiFailed,
+ };
+ let detail = DetailedError {
+ reason,
+ source: anyhow::Error::new(error),
+ };
+
+ if retryable {
+ ProcessingError::Retryable(detail)
+ } else {
+ ProcessingError::NonRetryable(detail)
+ }
+}
+
+pub(crate) fn is_permanent_mutation_error(error: &EmailApiError) -> bool {
+ matches!(error_policy(error), ErrorPolicy::Permanent)
+}
+
+pub(crate) fn is_delete_label_success(error: &EmailApiError) -> bool {
+ matches!(error, EmailApiError::NotFound)
+}
diff --git a/services/email_service/src/pubsub/gmail_ops/email_api_error/test.rs b/services/email_service/src/pubsub/gmail_ops/email_api_error/test.rs
new file mode 100644
index 0000000000..7172cb202b
--- /dev/null
+++ b/services/email_service/src/pubsub/gmail_ops/email_api_error/test.rs
@@ -0,0 +1,81 @@
+use std::time::Duration;
+
+use super::*;
+
+#[test]
+fn rate_limits_use_queue_routing_policy() {
+ let provider_rate_limit = EmailApiError::RateLimited {
+ retry_after: Some(Duration::from_secs(30)),
+ origin: email_api_client::domain::models::RateLimitOrigin::Provider,
+ };
+
+ assert_eq!(error_policy(&provider_rate_limit), ErrorPolicy::RateLimited);
+ assert_eq!(rate_limit_route(false), RateLimitRoute::EnqueueRetry);
+ assert_eq!(
+ rate_limit_route(true),
+ RateLimitRoute::RetryAfterVisibilityTimeout
+ );
+ assert!(matches!(
+ processing_error(provider_rate_limit.clone(), false),
+ ProcessingError::NonRetryable(DetailedError {
+ reason: FailureReason::GmailApiRateLimited,
+ ..
+ })
+ ));
+ assert!(matches!(
+ processing_error(provider_rate_limit, true),
+ ProcessingError::Retryable(DetailedError {
+ reason: FailureReason::GmailApiRateLimited,
+ ..
+ })
+ ));
+}
+
+#[test]
+fn transient_failures_are_retried() {
+ let error = EmailApiError::Transient {
+ message: "provider unavailable".to_string(),
+ };
+
+ assert_eq!(error_policy(&error), ErrorPolicy::Retry);
+ assert!(matches!(
+ processing_error(error, true),
+ ProcessingError::Retryable(DetailedError {
+ reason: FailureReason::GmailApiFailed,
+ ..
+ })
+ ));
+}
+
+#[test]
+fn modify_message_labels_permanent_failures_are_terminal_and_require_revert() {
+ let error = EmailApiError::Permanent {
+ message: "invalid label mutation".to_string(),
+ };
+
+ assert!(is_permanent_mutation_error(&error));
+ assert!(matches!(
+ processing_error(error, false),
+ ProcessingError::NonRetryable(DetailedError {
+ reason: FailureReason::GmailApiFailed,
+ ..
+ })
+ ));
+}
+
+#[test]
+fn not_found_is_success_for_delete_label() {
+ assert!(is_delete_label_success(&EmailApiError::NotFound));
+ assert!(!is_delete_label_success(&EmailApiError::Forbidden));
+}
+
+#[test]
+fn modify_message_labels_rate_limited_and_transient_failures_do_not_revert() {
+ assert!(!is_permanent_mutation_error(&EmailApiError::RateLimited {
+ retry_after: None,
+ origin: email_api_client::domain::models::RateLimitOrigin::Provider,
+ }));
+ assert!(!is_permanent_mutation_error(&EmailApiError::Transient {
+ message: "timeout".to_string(),
+ }));
+}
diff --git a/services/email_service/src/pubsub/gmail_ops/mod.rs b/services/email_service/src/pubsub/gmail_ops/mod.rs
index 02edf7f6b0..2789fcf283 100644
--- a/services/email_service/src/pubsub/gmail_ops/mod.rs
+++ b/services/email_service/src/pubsub/gmail_ops/mod.rs
@@ -1,3 +1,4 @@
+mod email_api_error;
pub mod error_handlers;
pub mod operations;
pub mod process;
diff --git a/services/email_service/src/pubsub/gmail_ops/operations/block_sender.rs b/services/email_service/src/pubsub/gmail_ops/operations/block_sender.rs
index 83d563c7a0..b42060c996 100644
--- a/services/email_service/src/pubsub/gmail_ops/operations/block_sender.rs
+++ b/services/email_service/src/pubsub/gmail_ops/operations/block_sender.rs
@@ -1,9 +1,8 @@
-use crate::pubsub::gmail_ops::process::{check_gmail_rate_limit, fetch_gmail_token};
-use crate::pubsub::gmail_ops::worker::GmailOpsContext;
+use email_api_client::domain::models::EmailApiError;
use models_email::gmail::gmail_ops::BlockSenderPayload;
-use models_email::gmail::operations::GmailApiOperation;
use models_email::service::link::Link;
-use models_email::service::pubsub::{DetailedError, FailureReason, ProcessingError};
+
+use crate::pubsub::gmail_ops::worker::GmailOpsContext;
/// Creates a filter to block a sender in Gmail.
#[tracing::instrument(skip(ctx, link), err)]
@@ -11,43 +10,8 @@ pub async fn block_sender(
ctx: &GmailOpsContext,
link: &Link,
payload: &BlockSenderPayload,
-) -> Result<(), ProcessingError> {
- check_gmail_rate_limit(
- ctx,
- link.id,
- GmailApiOperation::SettingsFiltersCreate,
- models_email::gmail::gmail_ops::GmailOpsOperation::BlockSender(payload.clone()),
- )
- .await?;
-
- let gmail_access_token = fetch_gmail_token(ctx, link).await?;
-
- // Check if already blocked
- let existing_filter = ctx
- .gmail_client
- .find_block_filter_for_sender(&gmail_access_token, &payload.email_address)
+) -> Result<(), EmailApiError> {
+ ctx.email_api
+ .block_sender(link.id, &payload.email_address)
.await
- .map_err(|e| {
- ProcessingError::Retryable(DetailedError {
- reason: FailureReason::GmailApiFailed,
- source: anyhow::anyhow!("Failed to check existing block filters: {}", e),
- })
- })?;
-
- if existing_filter.is_some() {
- tracing::debug!("Sender is already blocked, skipping");
- return Ok(());
- }
-
- ctx.gmail_client
- .block_sender(&gmail_access_token, &payload.email_address)
- .await
- .map_err(|e| {
- ProcessingError::Retryable(DetailedError {
- reason: FailureReason::GmailApiFailed,
- source: anyhow::anyhow!("Failed to block sender in Gmail: {}", e),
- })
- })?;
-
- Ok(())
}
diff --git a/services/email_service/src/pubsub/gmail_ops/operations/delete_label.rs b/services/email_service/src/pubsub/gmail_ops/operations/delete_label.rs
index 9bd44a5e8b..6ccf6d66ad 100644
--- a/services/email_service/src/pubsub/gmail_ops/operations/delete_label.rs
+++ b/services/email_service/src/pubsub/gmail_ops/operations/delete_label.rs
@@ -1,9 +1,9 @@
-use crate::pubsub::gmail_ops::process::{check_gmail_rate_limit, fetch_gmail_token};
-use crate::pubsub::gmail_ops::worker::GmailOpsContext;
+use email_api_client::domain::models::EmailApiError;
use models_email::gmail::gmail_ops::DeleteLabelPayload;
-use models_email::gmail::operations::GmailApiOperation;
use models_email::service::link::Link;
-use models_email::service::pubsub::{DetailedError, FailureReason, ProcessingError};
+
+use crate::pubsub::gmail_ops::email_api_error::is_delete_label_success;
+use crate::pubsub::gmail_ops::worker::GmailOpsContext;
/// Deletes a label from Gmail.
#[tracing::instrument(skip(ctx, link), err)]
@@ -11,36 +11,20 @@ pub async fn delete_label(
ctx: &GmailOpsContext,
link: &Link,
payload: &DeleteLabelPayload,
-) -> Result<(), ProcessingError> {
- check_gmail_rate_limit(
- ctx,
- link.id,
- GmailApiOperation::LabelsDelete,
- models_email::gmail::gmail_ops::GmailOpsOperation::DeleteLabel(payload.clone()),
- )
- .await?;
-
- let gmail_access_token = fetch_gmail_token(ctx, link).await?;
-
+) -> Result<(), EmailApiError> {
match ctx
- .gmail_client
- .delete_label(&gmail_access_token, &payload.provider_label_id)
+ .email_api
+ .delete_label(link.id, &payload.provider_label_id)
.await
{
- Ok(()) => {}
- Err(models_email::gmail::error::GmailError::NotFound(_)) => {
+ Ok(()) => Ok(()),
+ Err(error) if is_delete_label_success(&error) => {
tracing::warn!(
provider_label_id = %payload.provider_label_id,
"Label not found in Gmail when attempting to delete, ignoring"
);
+ Ok(())
}
- Err(e) => {
- return Err(ProcessingError::Retryable(DetailedError {
- reason: FailureReason::GmailApiFailed,
- source: anyhow::anyhow!("Failed to delete label from Gmail: {}", e),
- }));
- }
+ Err(error) => Err(error),
}
-
- Ok(())
}
diff --git a/services/email_service/src/pubsub/gmail_ops/operations/modify_message_labels.rs b/services/email_service/src/pubsub/gmail_ops/operations/modify_message_labels.rs
index a18bf6f251..bd50f24a48 100644
--- a/services/email_service/src/pubsub/gmail_ops/operations/modify_message_labels.rs
+++ b/services/email_service/src/pubsub/gmail_ops/operations/modify_message_labels.rs
@@ -1,12 +1,10 @@
-use crate::pubsub::gmail_ops::process::{check_gmail_rate_limit, fetch_gmail_token};
+use crate::pubsub::gmail_ops::email_api_error::is_permanent_mutation_error;
use crate::pubsub::gmail_ops::worker::GmailOpsContext;
use anyhow::Context;
-use models_email::gmail::error::GmailError;
+use email_api_client::domain::models::EmailApiError;
use models_email::gmail::gmail_ops::ModifyMessageLabelsPayload;
-use models_email::gmail::operations::GmailApiOperation;
use models_email::service;
use models_email::service::link::Link;
-use models_email::service::pubsub::{DetailedError, FailureReason, ProcessingError};
/// Modifies labels for a single message in Gmail. Reverts DB changes on permanent failure.
/// Transient errors (5xx, network) are retried; permanent errors (4xx) trigger revert.
@@ -15,61 +13,37 @@ pub async fn modify_message_labels(
ctx: &GmailOpsContext,
link: &Link,
payload: &ModifyMessageLabelsPayload,
-) -> Result<(), ProcessingError> {
- check_gmail_rate_limit(
- ctx,
- link.id,
- GmailApiOperation::MessagesModify,
- models_email::gmail::gmail_ops::GmailOpsOperation::ModifyMessageLabels(payload.clone()),
- )
- .await?;
-
- let gmail_access_token = fetch_gmail_token(ctx, link).await?;
-
+) -> Result<(), EmailApiError> {
let result = ctx
- .gmail_client
+ .email_api
.modify_message_labels(
- &gmail_access_token,
+ link.id,
&payload.provider_message_id,
&payload.labels_to_add,
&payload.labels_to_remove,
)
.await;
- match result {
- Ok(()) => Ok(()),
- Err(
- e @ (GmailError::ServerError(..)
- | GmailError::HttpRequest(_)
- | GmailError::RateLimitExceeded),
- ) => {
- tracing::warn!(
- error = ?e,
- db_message_id = %payload.db_message_id,
- provider_message_id = %payload.provider_message_id,
- "Transient Gmail error modifying labels, will retry"
- );
- Err(ProcessingError::Retryable(DetailedError {
- reason: FailureReason::GmailApiFailed,
- source: anyhow::anyhow!("{}", e),
- }))
- }
- Err(e) => {
+ if let Err(error) = &result {
+ if is_permanent_mutation_error(error) {
tracing::error!(
- error = ?e,
+ error = ?error,
db_message_id = %payload.db_message_id,
provider_message_id = %payload.provider_message_id,
"Permanent Gmail error modifying labels, reverting database changes"
);
-
revert_db_changes(ctx, link, payload).await;
-
- Err(ProcessingError::NonRetryable(DetailedError {
- reason: FailureReason::GmailApiFailed,
- source: anyhow::anyhow!("{}", e),
- }))
+ } else {
+ tracing::warn!(
+ error = ?error,
+ db_message_id = %payload.db_message_id,
+ provider_message_id = %payload.provider_message_id,
+ "Retryable Gmail error modifying labels, preserving optimistic database changes"
+ );
}
}
+
+ result
}
/// Reverts the optimistic DB changes for a single message that failed in Gmail.
diff --git a/services/email_service/src/pubsub/gmail_ops/operations/unblock_sender.rs b/services/email_service/src/pubsub/gmail_ops/operations/unblock_sender.rs
index e3f8ec1f30..d2c0699033 100644
--- a/services/email_service/src/pubsub/gmail_ops/operations/unblock_sender.rs
+++ b/services/email_service/src/pubsub/gmail_ops/operations/unblock_sender.rs
@@ -1,9 +1,8 @@
-use crate::pubsub::gmail_ops::process::{check_gmail_rate_limit, fetch_gmail_token};
-use crate::pubsub::gmail_ops::worker::GmailOpsContext;
+use email_api_client::domain::models::EmailApiError;
use models_email::gmail::gmail_ops::UnblockSenderPayload;
-use models_email::gmail::operations::GmailApiOperation;
use models_email::service::link::Link;
-use models_email::service::pubsub::{DetailedError, FailureReason, ProcessingError};
+
+use crate::pubsub::gmail_ops::worker::GmailOpsContext;
/// Finds and removes a block filter for a sender in Gmail.
#[tracing::instrument(skip(ctx, link), err)]
@@ -11,31 +10,8 @@ pub async fn unblock_sender(
ctx: &GmailOpsContext,
link: &Link,
payload: &UnblockSenderPayload,
-) -> Result<(), ProcessingError> {
- check_gmail_rate_limit(
- ctx,
- link.id,
- GmailApiOperation::SettingsFiltersDelete,
- models_email::gmail::gmail_ops::GmailOpsOperation::UnblockSender(payload.clone()),
- )
- .await?;
-
- let gmail_access_token = fetch_gmail_token(ctx, link).await?;
-
- let result = ctx
- .gmail_client
- .unblock_sender(&gmail_access_token, &payload.email_address)
+) -> Result<(), EmailApiError> {
+ ctx.email_api
+ .unblock_sender(link.id, &payload.email_address)
.await
- .map_err(|e| {
- ProcessingError::Retryable(DetailedError {
- reason: FailureReason::GmailApiFailed,
- source: anyhow::anyhow!("Failed to unblock sender in Gmail: {}", e),
- })
- })?;
-
- if !result {
- tracing::warn!("No block filter found for sender in Gmail");
- }
-
- Ok(())
}
diff --git a/services/email_service/src/pubsub/gmail_ops/process.rs b/services/email_service/src/pubsub/gmail_ops/process.rs
index 8b2d03de57..e0fffc8352 100644
--- a/services/email_service/src/pubsub/gmail_ops/process.rs
+++ b/services/email_service/src/pubsub/gmail_ops/process.rs
@@ -1,17 +1,14 @@
+use crate::pubsub::gmail_ops::email_api_error::handle_email_api_error;
use crate::pubsub::gmail_ops::error_handlers::prefix_error_source;
use crate::pubsub::gmail_ops::operations::block_sender::block_sender;
use crate::pubsub::gmail_ops::operations::delete_label::delete_label;
use crate::pubsub::gmail_ops::operations::modify_message_labels::modify_message_labels;
use crate::pubsub::gmail_ops::operations::unblock_sender::unblock_sender;
use crate::pubsub::gmail_ops::worker::GmailOpsContext;
-use crate::util::redis::rate_limit::RateLimitArgs;
use anyhow::{Context, Result, anyhow};
use models_email::gmail::gmail_ops::{GmailOpsOperation, GmailOpsPubsubMessage};
-use models_email::gmail::operations::GmailApiOperation;
-use models_email::service::link::Link;
use models_email::service::pubsub::{DetailedError, FailureReason, ProcessingError};
use sqs_worker::cleanup_message;
-use uuid::Uuid;
/// Processes a message from the gmail ops queue.
pub async fn process_message(
@@ -68,33 +65,28 @@ async fn inner_process_message(
})
})?;
- match &data.operation {
- GmailOpsOperation::ModifyMessageLabels(payload) => {
- modify_message_labels(ctx, &link, payload)
- .await
- .map_err(|e| prefix_error_source(e, "modify_message_labels"))?;
- tracing::debug!("Successfully processed modify message labels operation");
- }
+ let (operation_name, operation_result) = match &data.operation {
+ GmailOpsOperation::ModifyMessageLabels(payload) => (
+ "modify_message_labels",
+ modify_message_labels(ctx, &link, payload).await,
+ ),
GmailOpsOperation::DeleteLabel(payload) => {
- delete_label(ctx, &link, payload)
- .await
- .map_err(|e| prefix_error_source(e, "delete_label"))?;
- tracing::debug!("Successfully processed delete label operation");
+ ("delete_label", delete_label(ctx, &link, payload).await)
}
GmailOpsOperation::BlockSender(payload) => {
- block_sender(ctx, &link, payload)
- .await
- .map_err(|e| prefix_error_source(e, "block_sender"))?;
- tracing::debug!("Successfully processed block sender operation");
+ ("block_sender", block_sender(ctx, &link, payload).await)
}
GmailOpsOperation::UnblockSender(payload) => {
- unblock_sender(ctx, &link, payload)
- .await
- .map_err(|e| prefix_error_source(e, "unblock_sender"))?;
- tracing::debug!("Successfully processed unblock sender operation");
+ ("unblock_sender", unblock_sender(ctx, &link, payload).await)
}
+ };
+
+ if let Err(error) = operation_result {
+ let processing_error = handle_email_api_error(ctx, data, error).await;
+ return Err(prefix_error_source(processing_error, operation_name));
}
+ tracing::debug!(operation_name, "Successfully processed Gmail operation");
Ok(())
}
@@ -108,85 +100,3 @@ fn extract_gmail_ops_message(
.context("Failed to deserialize message body to GmailOpsPubsubMessage")?;
Ok(gmail_ops_message)
}
-
-/// Fetches a Gmail access token for use in pubsub workers.
-#[tracing::instrument(skip(ctx, link), err)]
-pub async fn fetch_gmail_token(
- ctx: &GmailOpsContext,
- link: &Link,
-) -> Result<String, ProcessingError> {
- let gmail_access_token = crate::util::gmail::auth::fetch_token_or_mark_reauth(
- link,
- &ctx.db,
- &ctx.redis_client,
- &ctx.auth_service_client,
- &ctx.sqs_client,
- )
- .await
- .map_err(|e| {
- ProcessingError::NonRetryable(DetailedError {
- reason: FailureReason::AccessTokenFetchFailed,
- source: e.context("Failed to fetch gmail access token"),
- })
- })?;
- Ok(gmail_access_token)
-}
-
-/// Checks Gmail API rate limits and routes processing accordingly.
-///
-/// Uses a two-tier system to prevent rate limit backpressure:
-/// - **Primary worker**: If rate limited, enqueues to retry queue and returns non-retryable error
-/// - **Retry worker**: If rate limited, returns retryable error so it gets tried again later
-#[tracing::instrument(skip(ctx, gmail_ops_operation), err)]
-pub async fn check_gmail_rate_limit(
- ctx: &GmailOpsContext,
- link_id: Uuid,
- operation: GmailApiOperation,
- gmail_ops_operation: GmailOpsOperation,
-) -> Result<(), ProcessingError> {
- if !ctx
- .redis_client
- .is_rate_limited(RateLimitArgs {
- user_id: link_id,
- operation,
- is_backfill: false,
- })
- .await
- {
- return Ok(());
- }
-
- if !ctx.retry_worker {
- tracing::info!(
- link_id = %link_id,
- "Gmail API rate limited, moving message from primary queue to retry queue"
- );
- ctx.sqs_client
- .enqueue_gmail_ops_retry_notification(GmailOpsPubsubMessage {
- link_id,
- operation: gmail_ops_operation,
- })
- .await
- .map_err(|e| {
- ProcessingError::Retryable(DetailedError {
- reason: FailureReason::SqsEnqueueFailed,
- source: e.context("Failed to enqueue gmail ops retry message"),
- })
- })?;
- Err(ProcessingError::NonRetryable(DetailedError {
- reason: FailureReason::GmailApiRateLimited,
- source: anyhow::Error::msg(
- "Gmail API rate limit exceeded, enqueued message on retry queue",
- ),
- }))
- } else {
- tracing::info!(
- link_id = %link_id,
- "Gmail API rate limited in retry worker, message will be retried after visibility timeout"
- );
- Err(ProcessingError::Retryable(DetailedError {
- reason: FailureReason::GmailApiRateLimited,
- source: anyhow::Error::msg("Gmail API rate limit exceeded in retry worker"),
- }))
- }
-}
diff --git a/services/email_service/src/pubsub/gmail_ops/worker.rs b/services/email_service/src/pubsub/gmail_ops/worker.rs
index 7075a51ba3..01a32dae8f 100644
--- a/services/email_service/src/pubsub/gmail_ops/worker.rs
+++ b/services/email_service/src/pubsub/gmail_ops/worker.rs
@@ -1,9 +1,7 @@
+use crate::outbound::email_api::GmailApi;
use crate::pubsub::gmail_ops::process;
use crate::pubsub::worker_lifecycle::run_until_cancelled;
-use crate::util::redis::RedisClient;
-use authentication_service_client::AuthServiceClient;
use futures::StreamExt;
-use gmail_client::GmailClient;
use sqlx::PgPool;
use tokio_util::sync::CancellationToken;
@@ -14,9 +12,7 @@ pub struct GmailOpsContext {
pub db: PgPool,
pub sqs_worker: sqs_worker::SQSWorker,
pub sqs_client: sqs_client::SQS,
- pub gmail_client: GmailClient,
- pub auth_service_client: AuthServiceClient,
- pub redis_client: RedisClient,
+ pub email_api: GmailApi,
pub retry_worker: bool,
}
@@ -25,18 +21,14 @@ pub async fn run_worker(
db: PgPool,
worker: sqs_worker::SQSWorker,
sqs_client: sqs_client::SQS,
- gmail_client: GmailClient,
- auth_service_client: AuthServiceClient,
- redis_client: RedisClient,
+ email_api: GmailApi,
retry_worker: bool,
) {
run_worker_with_cancellation(
db,
worker,
sqs_client,
- gmail_client,
- auth_service_client,
- redis_client,
+ email_api,
retry_worker,
CancellationToken::new(),
)
@@ -46,14 +38,11 @@ pub async fn run_worker(
/// Ingests Gmail operations messages until cancellation is requested.
///
/// A batch already returned by SQS is fully processed before shutdown.
-#[allow(clippy::too_many_arguments)]
pub async fn run_worker_with_cancellation(
db: PgPool,
worker: sqs_worker::SQSWorker,
sqs_client: sqs_client::SQS,
- gmail_client: GmailClient,
- auth_service_client: AuthServiceClient,
- redis_client: RedisClient,
+ email_api: GmailApi,
retry_worker: bool,
cancellation_token: CancellationToken,
) {
@@ -61,9 +50,7 @@ pub async fn run_worker_with_cancellation(
db,
sqs_worker: worker.clone(),
sqs_client,
- gmail_client,
- auth_service_client,
- redis_client,
+ email_api,
retry_worker,
};
diff --git a/services/email_service/src/pubsub/inbox_sync/email_api_error.rs b/services/email_service/src/pubsub/inbox_sync/email_api_error.rs
new file mode 100644
index 0000000000..e1cd79702d
--- /dev/null
+++ b/services/email_service/src/pubsub/inbox_sync/email_api_error.rs
@@ -0,0 +1,101 @@
+use email_api_client::domain::models::{EmailApiError, RateLimitOrigin};
+use models_email::gmail::inbox_sync::{InboxSyncOperation, InboxSyncPubsubMessage};
+use models_email::service::pubsub::{DetailedError, FailureReason, ProcessingError};
+
+use crate::pubsub::context::PubSubContext;
+
+#[cfg(test)]
+mod test;
+
+#[derive(Debug, PartialEq, Eq)]
+enum RateLimitRoute {
+ EnqueueRetry,
+ RetryAfterVisibilityTimeout,
+}
+
+fn rate_limit_route(retry_worker: bool) -> RateLimitRoute {
+ if retry_worker {
+ RateLimitRoute::RetryAfterVisibilityTimeout
+ } else {
+ RateLimitRoute::EnqueueRetry
+ }
+}
+
+pub(crate) async fn handle_operation_error(
+ ctx: &PubSubContext,
+ link_id: uuid::Uuid,
+ operation: InboxSyncOperation,
+ error: EmailApiError,
+) -> ProcessingError {
+ if !matches!(error, EmailApiError::RateLimited { .. }) {
+ return processing_error(error);
+ }
+
+ if rate_limit_route(ctx.retry_worker) == RateLimitRoute::RetryAfterVisibilityTimeout {
+ return processing_error(error);
+ }
+
+ let message = InboxSyncPubsubMessage { link_id, operation };
+ if let Err(enqueue_error) = ctx
+ .sqs_client
+ .enqueue_gmail_retry_inbox_sync_notification(message)
+ .await
+ {
+ return ProcessingError::Retryable(DetailedError {
+ reason: FailureReason::SqsEnqueueFailed,
+ source: enqueue_error.context("Failed to enqueue inbox sync retry message"),
+ });
+ }
+
+ non_retryable(error)
+}
+
+pub(crate) fn handle_gmail_message_error(error: EmailApiError) -> ProcessingError {
+ // Local budget refusals drop the notification by design: no provider
+ // quota was consumed and a later notification covers the same cursor
+ // range, avoiding fan-out backpressure. A provider-origin 429 retries
+ // (main's behavior) so an idle mailbox does not stay unsynced until its
+ // next change.
+ if matches!(
+ error,
+ EmailApiError::RateLimited {
+ origin: RateLimitOrigin::Local,
+ ..
+ }
+ ) {
+ return non_retryable(error);
+ }
+
+ processing_error(error)
+}
+
+fn processing_error(error: EmailApiError) -> ProcessingError {
+ if error.is_transient() || matches!(error, EmailApiError::RateLimited { .. }) {
+ ProcessingError::Retryable(detail(error))
+ } else {
+ non_retryable(error)
+ }
+}
+
+fn non_retryable(error: EmailApiError) -> ProcessingError {
+ ProcessingError::NonRetryable(detail(error))
+}
+
+fn detail(error: EmailApiError) -> DetailedError {
+ // Exhaustive: a new EmailApiError variant must force a policy decision
+ // here rather than silently falling into a catch-all.
+ let reason = match error {
+ EmailApiError::RateLimited { .. } => FailureReason::GmailApiRateLimited,
+ EmailApiError::AuthRequired => FailureReason::AccessTokenFetchFailed,
+ EmailApiError::OutdatedCursor => FailureReason::OutdatedHistoryId,
+ EmailApiError::Forbidden
+ | EmailApiError::NotFound
+ | EmailApiError::Conflict
+ | EmailApiError::Transient { .. }
+ | EmailApiError::Permanent { .. } => FailureReason::GmailApiFailed,
+ };
+ DetailedError {
+ reason,
+ source: anyhow::Error::new(error),
+ }
+}
diff --git a/services/email_service/src/pubsub/inbox_sync/email_api_error/test.rs b/services/email_service/src/pubsub/inbox_sync/email_api_error/test.rs
new file mode 100644
index 0000000000..bcf89f7df8
--- /dev/null
+++ b/services/email_service/src/pubsub/inbox_sync/email_api_error/test.rs
@@ -0,0 +1,140 @@
+use std::time::Duration;
+
+use super::*;
+
+#[test]
+fn primary_worker_routes_rate_limits_to_retry_queue() {
+ assert_eq!(rate_limit_route(false), RateLimitRoute::EnqueueRetry);
+}
+
+#[test]
+fn retry_worker_uses_visibility_timeout_for_rate_limits() {
+ assert_eq!(
+ rate_limit_route(true),
+ RateLimitRoute::RetryAfterVisibilityTimeout
+ );
+}
+
+#[test]
+fn gmail_message_local_rate_refusal_is_non_retryable() {
+ let error = handle_gmail_message_error(EmailApiError::RateLimited {
+ retry_after: Some(Duration::from_secs(10)),
+ origin: RateLimitOrigin::Local,
+ });
+
+ assert!(matches!(
+ error,
+ ProcessingError::NonRetryable(DetailedError {
+ reason: FailureReason::GmailApiRateLimited,
+ ..
+ })
+ ));
+}
+
+#[test]
+fn gmail_message_provider_429_is_retried() {
+ let error = handle_gmail_message_error(EmailApiError::RateLimited {
+ retry_after: Some(Duration::from_secs(10)),
+ origin: RateLimitOrigin::Provider,
+ });
+
+ assert!(matches!(
+ error,
+ ProcessingError::Retryable(DetailedError {
+ reason: FailureReason::GmailApiRateLimited,
+ ..
+ })
+ ));
+}
+
+/// Pins the full `EmailApiError` → `ProcessingError` policy table for
+/// inbox_sync operations (the non-rate-limit path of `handle_operation_error`
+/// and the retry-worker rate-limit branch both route through
+/// `processing_error`), mirroring the backfill policy test's coverage.
+#[test]
+fn processing_error_policy_covers_every_variant() {
+ let cases: Vec<(EmailApiError, bool, FailureReason)> = vec![
+ (
+ EmailApiError::RateLimited {
+ retry_after: Some(Duration::from_secs(5)),
+ origin: RateLimitOrigin::Provider,
+ },
+ true,
+ FailureReason::GmailApiRateLimited,
+ ),
+ (
+ EmailApiError::RateLimited {
+ retry_after: None,
+ origin: RateLimitOrigin::Local,
+ },
+ true,
+ FailureReason::GmailApiRateLimited,
+ ),
+ (
+ EmailApiError::AuthRequired,
+ false,
+ FailureReason::AccessTokenFetchFailed,
+ ),
+ (
+ EmailApiError::Forbidden,
+ false,
+ FailureReason::GmailApiFailed,
+ ),
+ (
+ EmailApiError::NotFound,
+ false,
+ FailureReason::GmailApiFailed,
+ ),
+ (
+ EmailApiError::Conflict,
+ false,
+ FailureReason::GmailApiFailed,
+ ),
+ (
+ EmailApiError::OutdatedCursor,
+ false,
+ FailureReason::OutdatedHistoryId,
+ ),
+ (
+ EmailApiError::Transient {
+ message: "blip".to_string(),
+ },
+ true,
+ FailureReason::GmailApiFailed,
+ ),
+ (
+ EmailApiError::Permanent {
+ message: "broken".to_string(),
+ },
+ false,
+ FailureReason::GmailApiFailed,
+ ),
+ ];
+
+ for (error, expect_retryable, expect_reason) in cases {
+ let description = format!("{error:?}");
+ match processing_error(error) {
+ ProcessingError::Retryable(detail) => {
+ assert!(expect_retryable, "{description} must not be retryable");
+ assert_eq!(detail.reason, expect_reason, "{description}");
+ }
+ ProcessingError::NonRetryable(detail) => {
+ assert!(!expect_retryable, "{description} must be retryable");
+ assert_eq!(detail.reason, expect_reason, "{description}");
+ }
+ }
+ }
+}
+
+#[test]
+fn outdated_cursor_is_a_terminal_history_failure() {
+ let error = handle_gmail_message_error(EmailApiError::OutdatedCursor);
+
+ assert!(matches!(
+ error,
+ ProcessingError::NonRetryable(DetailedError {
+ reason: FailureReason::OutdatedHistoryId,
+ ..
+ })
+ ));
+}
diff --git a/services/email_service/src/pubsub/inbox_sync/mod.rs b/services/email_service/src/pubsub/inbox_sync/mod.rs
index 59b1da2379..8b472c0358 100644
--- a/services/email_service/src/pubsub/inbox_sync/mod.rs
+++ b/services/email_service/src/pubsub/inbox_sync/mod.rs
@@ -1,3 +1,4 @@
+mod email_api_error;
mod error_handlers;
mod operations;
pub(crate) mod process;
diff --git a/services/email_service/src/pubsub/inbox_sync/operations/gmail_message.rs b/services/email_service/src/pubsub/inbox_sync/operations/gmail_message.rs
index c5acb6db1c..ab8e7b83ce 100644
--- a/services/email_service/src/pubsub/inbox_sync/operations/gmail_message.rs
+++ b/services/email_service/src/pubsub/inbox_sync/operations/gmail_message.rs
@@ -1,19 +1,24 @@
-use crate::convert::map_history_list_response_to_history;
use crate::pubsub::context::PubSubContext;
-use crate::pubsub::inbox_sync::process::fetch_pubsub_gmail_token;
-use crate::pubsub::util::{CheckGmailRateLimitArgs, check_gmail_rate_limit};
+use crate::pubsub::inbox_sync::email_api_error::handle_gmail_message_error;
use crate::util::process_pre_insert::sync_labels::sync_labels;
-use models_email::gmail::history::InboxChanges;
+use email_api_client::domain::models::{EmailApiError, InboxChanges, SyncCursor};
+use models_email::email::service::backfill::BackfillJob;
+use models_email::email::service::backfill::{
+ BackfillOperation, BackfillPubsubMessage, InitPayload, JobScopedPayload,
+};
use models_email::gmail::inbox_sync::{
DeleteMessagePayload, GmailMessagePayload, InboxSyncOperation, InboxSyncPubsubMessage,
UpdateLabelsPayload, UpsertMessagePayload,
};
-use models_email::gmail::operations::GmailApiOperation;
use models_email::service::link::{Link, UserProvider};
use models_email::service::pubsub::{DetailedError, FailureReason, ProcessingError};
+use sqlx::PgPool;
use std::result;
use uuid::Uuid;
+#[cfg(test)]
+mod test;
+
// handle the initial message received from gmail notifying us of inbox changes.
// ensure the message is valid, then send off pubsub messages for each change.
#[tracing::instrument(skip(ctx))]
@@ -22,10 +27,6 @@ pub async fn gmail_message(
link: &Link,
payload: &GmailMessagePayload,
) -> result::Result<(), ProcessingError> {
- let gmail_access_token = fetch_pubsub_gmail_token(ctx, link).await?;
-
- // get the user's latest history_id in the database
- // if it's GTE this message's history id, do nothing - db is already updated or being updated
let db_history_id = email_db_client::histories::fetch_history_id_for_link(
&ctx.db,
link.email_address.0.as_ref(),
@@ -35,7 +36,7 @@ pub async fn gmail_message(
.map_err(|e| {
ProcessingError::Retryable(DetailedError {
reason: FailureReason::DatabaseQueryFailed,
- source: e.context("Failed to fetch history id from db".to_string()),
+ source: e.context("Failed to fetch history id from db"),
})
})?
.ok_or_else(|| {
@@ -45,89 +46,64 @@ pub async fn gmail_message(
})
})?;
- let db_history_u64 = db_history_id.parse::<u64>().map_err(|e| {
- ProcessingError::NonRetryable(DetailedError {
- reason: FailureReason::OutdatedHistoryId,
- source: anyhow::Error::from(e).context("Failed to parse current history_id as u64"),
- })
- })?;
+ let db_history_u64 = match db_history_id.parse::<u64>() {
+ Ok(history_id) => history_id,
+ Err(error) => {
+ schedule_stale_cursor_backfill(ctx, link, payload.history_id).await?;
+ return Err(ProcessingError::NonRetryable(DetailedError {
+ reason: FailureReason::OutdatedHistoryId,
+ source: anyhow::Error::from(error)
+ .context("Failed to parse current history_id as u64"),
+ }));
+ }
+ };
if db_history_u64 >= payload.history_id {
return Ok(());
}
- // ensure user's labels are synced before we start processing changes.
- check_gmail_rate_limit(CheckGmailRateLimitArgs {
- redis_client: &ctx.redis_client,
- link_id: link.id,
- gmail_operation: GmailApiOperation::LabelsList,
- // don't retry if rate limited, just wait until the next inbox update comes in. if we're
- // rate limited it's likely because of a large previous inbox update, so let that get
- // fully processed before the next one.
- retryable: false,
- is_backfill: false,
- })
- .await?;
- sync_labels(&ctx.db, &ctx.gmail_client, &gmail_access_token, link.id)
+ // Gmail message notifications intentionally refuse labels/history work when quota is
+ // exhausted. A later notification will cover the same cursor range, avoiding fan-out
+ // backpressure while preserving the separate retry queue for child operations.
+ let labels = ctx
+ .email_api
+ .list_labels(link.id)
.await
- .map_err(|e| {
- ProcessingError::Retryable(DetailedError {
- reason: FailureReason::GmailApiFailed,
- source: e.context("Failed to sync labels"),
- })
- })?;
-
- // the history.list call in gmail api fetches all changes SINCE the history_id we pass to it.
- // we pass the db_history_id, aka history_id at the time of the last update. once
- // we update the database, we set the db history_id to be the message history_id
- // (the current history_id for the user)
- check_gmail_rate_limit(CheckGmailRateLimitArgs {
- redis_client: &ctx.redis_client,
- link_id: link.id,
- gmail_operation: GmailApiOperation::HistoryList,
- // don't retry if rate limited, just wait until the next inbox update comes in. if we're
- // rate limited it's likely because of a large previous inbox update, so let that get
- // fully processed before the next one.
- retryable: false,
- is_backfill: false,
- })
- .await?;
- let history_response = ctx
- .gmail_client
- .get_history(&gmail_access_token, &db_history_id)
+ .map_err(handle_gmail_message_error)?;
+ sync_labels(&ctx.db, link.id, &labels).await.map_err(|e| {
+ ProcessingError::Retryable(DetailedError {
+ reason: FailureReason::DatabaseQueryFailed,
+ source: e.context("Failed to reconcile labels"),
+ })
+ })?;
+
+ let change_batch = match ctx
+ .email_api
+ .list_changes(link.id, &SyncCursor::gmail(&db_history_id))
.await
- .map_err(|e| {
- ProcessingError::Retryable(DetailedError {
- reason: FailureReason::GmailApiFailed,
- source: e.context(format!("unable to get history for link id: {}", link.id)),
- })
- })?;
- let inbox_changes = map_history_list_response_to_history(history_response);
-
- // Update the history_id in the database immediately to prevent duplicate processing.
- // The db history_id is used to determine which inbox changes need processing when
- // handling GmailMessage InboxSyncOperations. By updating it before processing the
- // current changes, we ensure that any new GmailMessage notifications that arrive
- // will use the latest history_id for comparison. This prevents duplicate processing
- // that could occur if we updated the history_id after processing the changes.
+ {
+ Ok(batch) => batch,
+ Err(EmailApiError::OutdatedCursor) => {
+ schedule_stale_cursor_backfill(ctx, link, payload.history_id).await?;
+ return Err(handle_gmail_message_error(EmailApiError::OutdatedCursor));
+ }
+ Err(error) => return Err(handle_gmail_message_error(error)),
+ };
+
email_db_client::histories::upsert_gmail_history(
&ctx.db,
link.id,
- &inbox_changes.current_history_id,
+ change_batch.next_cursor.as_str(),
)
.await
.map_err(|e| {
ProcessingError::NonRetryable(DetailedError {
reason: FailureReason::DatabaseQueryFailed,
- source: e.context("Failed to upsert gmail history".to_string()),
+ source: e.context("Failed to upsert gmail history"),
})
})?;
- // Build pubsub messages from inbox_changes
- let pubsub_messages = build_pubsub_messages(link.id, inbox_changes);
-
- // Send them off
- for ps_message in pubsub_messages {
+ for ps_message in build_pubsub_messages(link.id, change_batch.changes) {
let message_for_error = ps_message.clone();
ctx.sqs_client
.enqueue_gmail_inbox_sync_notification(ps_message)
@@ -135,7 +111,7 @@ pub async fn gmail_message(
.map_err(|e| {
ProcessingError::NonRetryable(DetailedError {
reason: FailureReason::SqsEnqueueFailed,
- source: e.context(format!("Failed to enqueue message {:?}", message_for_error)),
+ source: e.context(format!("Failed to enqueue message {message_for_error:?}")),
})
})?;
}
@@ -143,15 +119,118 @@ pub async fn gmail_message(
Ok(())
}
-/// Builds pubsub messages from history data
-#[tracing::instrument]
+async fn schedule_stale_cursor_backfill(
+ ctx: &PubSubContext,
+ link: &Link,
+ notification_history_id: u64,
+) -> result::Result<(), ProcessingError> {
+ let (job, created) =
+ ensure_recovery_backfill_job(&ctx.db, link.id, link.fusionauth_user_id.as_str()).await?;
+
+ let message = BackfillPubsubMessage {
+ backfill_operation: BackfillOperation::Init(JobScopedPayload {
+ link_id: link.id,
+ job_id: job.id,
+ payload: InitPayload {},
+ }),
+ };
+
+ if let Err(enqueue_error) = ctx.sqs_client.enqueue_email_backfill_message(message).await {
+ if created {
+ email_db_client::backfill::job::update::fail_backfill_job(&ctx.db, job.id)
+ .await
+ .map_err(recovery_db_error)?;
+ }
+ return Err(ProcessingError::Retryable(DetailedError {
+ reason: FailureReason::SqsEnqueueFailed,
+ source: enqueue_error.context("Failed to enqueue stale-cursor backfill"),
+ }));
+ }
+
+ repair_stale_cursor(&ctx.db, link.id, notification_history_id).await;
+
+ Ok(())
+}
+
+/// Finds the link's active backfill job, creating one when none exists.
+///
+/// Returns the job and whether it was created by this call.
+async fn ensure_recovery_backfill_job(
+ db: &PgPool,
+ link_id: Uuid,
+ fusionauth_user_id: &str,
+) -> result::Result<(BackfillJob, bool), ProcessingError> {
+ let existing_job = email_db_client::backfill::job::get::get_active_backfill_job(db, link_id)
+ .await
+ .map_err(recovery_db_error)?;
+
+ if let Some(job) = existing_job {
+ return Ok((job, false));
+ }
+
+ match email_db_client::backfill::job::insert::create_backfill_job(
+ db,
+ link_id,
+ fusionauth_user_id,
+ None,
+ // Stale-cursor recovery: refresh existing threads so the gap window's
+ // replies are recovered (see backfill_thread's refresh path).
+ true,
+ )
+ .await
+ .map_err(recovery_db_error)?
+ {
+ Some(job) => Ok((job, true)),
+ None => {
+ let job = email_db_client::backfill::job::get::get_active_backfill_job(db, link_id)
+ .await
+ .map_err(recovery_db_error)?
+ .ok_or_else(|| {
+ recovery_db_error(anyhow::anyhow!(
+ "backfill insert conflicted but no active job was found"
+ ))
+ })?;
+ Ok((job, false))
+ }
+ }
+}
+
+/// Persists the notification's history id as the link's sync cursor once a
+/// recovery backfill covers the gap.
+///
+/// Without this write the expired cursor stays in place, so every subsequent
+/// notification re-enters the `OutdatedCursor` arm and schedules another
+/// full-mailbox backfill forever. A write failure is deliberately swallowed:
+/// the notification is dropped either way, and the next notification re-enters
+/// this path (reusing the active job) and retries the repair.
+async fn repair_stale_cursor(db: &PgPool, link_id: Uuid, notification_history_id: u64) {
+ let _ = email_db_client::histories::upsert_gmail_history(
+ db,
+ link_id,
+ &notification_history_id.to_string(),
+ )
+ .await
+ .inspect_err(|error| {
+ tracing::warn!(error = ?error, %link_id, "failed to repair stale gmail sync cursor");
+ });
+}
+
+fn recovery_db_error(error: impl Into<anyhow::Error>) -> ProcessingError {
+ ProcessingError::Retryable(DetailedError {
+ reason: FailureReason::DatabaseQueryFailed,
+ source: error
+ .into()
+ .context("Failed to schedule stale-cursor backfill"),
+ })
+}
+
+/// Builds pubsub messages from history data.
fn build_pubsub_messages(
link_id: Uuid,
inbox_changes: InboxChanges,
) -> Vec<InboxSyncPubsubMessage> {
let mut pubsub_messages = Vec::new();
- // Process messages to upsert
for message_id in inbox_changes.message_ids_to_upsert {
pubsub_messages.push(InboxSyncPubsubMessage {
link_id,
@@ -160,8 +239,6 @@ fn build_pubsub_messages(
}),
});
}
-
- // Process messages to delete
for message_id in inbox_changes.message_ids_to_delete {
pubsub_messages.push(InboxSyncPubsubMessage {
link_id,
@@ -170,7 +247,6 @@ fn build_pubsub_messages(
}),
});
}
-
for message_id in inbox_changes.labels_to_update {
pubsub_messages.push(InboxSyncPubsubMessage {
link_id,
diff --git a/services/email_service/src/pubsub/inbox_sync/operations/gmail_message/test.rs b/services/email_service/src/pubsub/inbox_sync/operations/gmail_message/test.rs
new file mode 100644
index 0000000000..b12d0aec84
--- /dev/null
+++ b/services/email_service/src/pubsub/inbox_sync/operations/gmail_message/test.rs
@@ -0,0 +1,88 @@
+use super::*;
+use macro_db_migrator::MACRO_DB_MIGRATIONS;
+
+async fn insert_email_link(pool: &PgPool) -> (Uuid, String) {
+ let link_id = Uuid::now_v7();
+ let email_address = format!("stale-cursor-{link_id}@example.com");
+ sqlx::query!(
+ r#"
+ INSERT INTO email_links (
+ id, macro_id, fusionauth_user_id, email_address, provider
+ )
+ VALUES ($1, $2, $2, $3, 'GMAIL')
+ "#,
+ link_id,
+ email_address,
+ )
+ .execute(pool)
+ .await
+ .unwrap();
+ (link_id, email_address)
+}
+
+async fn stored_history_id(pool: &PgPool, email_address: &str) -> Option<String> {
+ email_db_client::histories::fetch_history_id_for_link(pool, email_address, UserProvider::Gmail)
+ .await
+ .unwrap()
+}
+
+#[sqlx::test(migrator = "MACRO_DB_MIGRATIONS")]
+async fn recovery_backfill_job_is_created_once_and_then_reused(pool: PgPool) {
+ let (link_id, _) = insert_email_link(&pool).await;
+
+ let (job, created) = ensure_recovery_backfill_job(&pool, link_id, "fa-user")
+ .await
+ .unwrap();
+ assert!(created, "first stale-cursor recovery creates a job");
+
+ let (reused_job, created_again) = ensure_recovery_backfill_job(&pool, link_id, "fa-user")
+ .await
+ .unwrap();
+ assert!(
+ !created_again,
+ "a second notification must reuse the active recovery job instead of creating another"
+ );
+ assert_eq!(job.id, reused_job.id);
+
+ // Recovery jobs are flagged so backfill refreshes existing threads
+ // instead of skipping them (and the init outbox skips the priority pass).
+ let is_recovery = sqlx::query_scalar!(
+ r#"SELECT is_recovery FROM email_backfill_jobs WHERE id = $1"#,
+ job.id,
+ )
+ .fetch_one(&pool)
+ .await
+ .unwrap();
+ assert!(is_recovery);
+}
+
+#[sqlx::test(migrator = "MACRO_DB_MIGRATIONS")]
+async fn stale_cursor_repair_persists_the_notification_history_id(pool: PgPool) {
+ let (link_id, email_address) = insert_email_link(&pool).await;
+ email_db_client::histories::upsert_gmail_history(&pool, link_id, "12345")
+ .await
+ .unwrap();
+
+ repair_stale_cursor(&pool, link_id, 99999).await;
+
+ // The stored cursor now parses and matches the notification, so the next
+ // notification takes the incremental list_changes path (its freshness
+ // check `db_history >= payload.history_id` holds for this history id).
+ assert_eq!(
+ stored_history_id(&pool, &email_address).await.as_deref(),
+ Some("99999")
+ );
+}
+
+#[sqlx::test(migrator = "MACRO_DB_MIGRATIONS")]
+async fn stale_cursor_repair_inserts_a_cursor_when_none_exists(pool: PgPool) {
+ let (link_id, email_address) = insert_email_link(&pool).await;
+
+ repair_stale_cursor(&pool, link_id, 424242).await;
+
+ assert_eq!(
+ stored_history_id(&pool, &email_address).await.as_deref(),
+ Some("424242")
+ );
+}
diff --git a/services/email_service/src/pubsub/inbox_sync/operations/update_labels.rs b/services/email_service/src/pubsub/inbox_sync/operations/update_labels.rs
index 8d6d07dc5d..eb968876cc 100644
--- a/services/email_service/src/pubsub/inbox_sync/operations/update_labels.rs
+++ b/services/email_service/src/pubsub/inbox_sync/operations/update_labels.rs
@@ -1,6 +1,5 @@
use crate::pubsub::context::PubSubContext;
-use crate::pubsub::inbox_sync::process;
-use crate::pubsub::inbox_sync::process::check_gmail_rate_limit_inbox_sync;
+use crate::pubsub::inbox_sync::email_api_error::handle_operation_error;
use crate::pubsub::util::{
cg_refresh_email, complete_transaction_with_processing_error, publish_email_event,
};
@@ -18,7 +17,6 @@ use models_email::email::service::link;
use models_email::gmail::inbox_sync::{
InboxSyncOperation, InboxSyncPubsubMessage, UpdateLabelsPayload, UpsertMessagePayload,
};
-use models_email::gmail::operations::GmailApiOperation;
use models_email::service;
use models_email::service::pubsub::{DetailedError, FailureReason, ProcessingError};
use sqlx::PgPool;
@@ -35,7 +33,6 @@ pub async fn update_labels(
link: &link::Link,
payload: &UpdateLabelsPayload,
) -> result::Result<(), ProcessingError> {
- let gmail_access_token = process::fetch_pubsub_gmail_token(ctx, link).await?;
let provider_message_id = &payload.provider_message_id;
// fetch simple message to get db_id from provider_id
@@ -95,27 +92,22 @@ pub async fn update_labels(
})
})?;
- // get the message labels from gmail
- check_gmail_rate_limit_inbox_sync(
- ctx,
- link.id,
- GmailApiOperation::MessagesGet,
- InboxSyncOperation::UpdateLabels(payload.clone()),
- )
- .await?;
-
- let gmail_message_labels = match ctx
- .gmail_client
- .get_message_label_ids(&gmail_access_token, &payload.provider_message_id)
- .await
- .map_err(|e| {
- ProcessingError::Retryable(DetailedError {
- reason: FailureReason::GmailApiFailed,
- source: e.context("Failed to get message from gmail api".to_string()),
- })
- })? {
- Some(labels) => labels,
- None => {
+ let provider_labels = ctx
+ .email_api
+ .get_message_label_ids(link.id, &payload.provider_message_id)
+ .await;
+ let gmail_message_labels = match provider_labels {
+ Ok(Some(labels)) => labels,
+ Err(error) => {
+ return Err(handle_operation_error(
+ ctx,
+ link.id,
+ InboxSyncOperation::UpdateLabels(payload.clone()),
+ error,
+ )
+ .await);
+ }
+ Ok(None) => {
tracing::debug!(provider_message_id = %payload.provider_message_id, link_id = %link.id,
"Message not found in gmail when attempting to update labels");
return Ok(());
diff --git a/services/email_service/src/pubsub/inbox_sync/operations/upsert_message.rs b/services/email_service/src/pubsub/inbox_sync/operations/upsert_message.rs
index 3c085530b3..3540d27251 100644
--- a/services/email_service/src/pubsub/inbox_sync/operations/upsert_message.rs
+++ b/services/email_service/src/pubsub/inbox_sync/operations/upsert_message.rs
@@ -1,7 +1,5 @@
-use crate::convert::{map_message_resource_to_service, map_thread_resources_to_service};
use crate::pubsub::context::PubSubContext;
-use crate::pubsub::inbox_sync::process;
-use crate::pubsub::inbox_sync::process::check_gmail_rate_limit_inbox_sync;
+use crate::pubsub::inbox_sync::email_api_error::handle_operation_error;
use crate::pubsub::util::{
CrmContactRecipient, build_notification_recipients, enqueue_populate_crm_contacts,
};
@@ -33,12 +31,12 @@ use models_email::db::address::EmailRecipientType;
use models_email::email::service::link;
use models_email::email::service::message::SimpleMessage;
use models_email::gmail::inbox_sync::{InboxSyncOperation, UpsertMessagePayload};
-use models_email::gmail::operations::GmailApiOperation;
use models_email::service::attachment::{
Attachment, AttachmentUploadArgs, AttachmentUploadDestination, AttachmentUploadMetadata,
};
-use models_email::service::message::{Message, is_spam_or_trash};
+use models_email::service::message::{Message, is_inbound, is_outbound, is_spam_or_trash};
use models_email::service::pubsub::{DetailedError, FailureReason, ProcessingError};
+use models_email::service::thread::Thread;
use notification::domain::models::SendNotificationRequestBuilder;
use notification::domain::service::NotificationIngress;
use std::collections::HashSet;
@@ -87,44 +85,29 @@ pub async fn upsert_message(
link: &link::Link,
payload: &UpsertMessagePayload,
) -> result::Result<(), ProcessingError> {
- let gmail_access_token = process::fetch_pubsub_gmail_token(ctx, link).await?;
-
- // we have to fetch the message to get its provider thread id
- check_gmail_rate_limit_inbox_sync(
- ctx,
- link.id,
- GmailApiOperation::MessagesGet,
- InboxSyncOperation::UpsertMessage(payload.clone()),
- )
- .await?;
-
- let message_resource = match ctx
- .gmail_client
- .get_message(&gmail_access_token, &payload.provider_message_id)
- .await
- .map_err(|e| {
- // retryable because we don't return an error if message doesn't exist, so this means
- // it had to be some sort of internal gmail api error
- ProcessingError::Retryable(DetailedError {
- reason: FailureReason::GmailApiFailed,
- source: e.context("Failed to get message from gmail api".to_string()),
- })
- })? {
- Some(msg) => msg,
- None => {
+ let provider_message = ctx
+ .email_api
+ .get_message(link.id, &payload.provider_message_id)
+ .await;
+ let fetched = match provider_message {
+ Ok(Some(fetched)) => fetched,
+ Ok(None) => {
tracing::debug!(provider_message_id = %payload.provider_message_id, link_id = %link.id,
"Message not found in gmail when attempting to upsert");
return Ok(());
}
+ Err(error) => {
+ return Err(handle_operation_error(
+ ctx,
+ link.id,
+ InboxSyncOperation::UpsertMessage(payload.clone()),
+ error,
+ )
+ .await);
+ }
};
+ let mut message = fetched.message;
- // Map Gmail resource to service model (IDs are generated in the parse function)
- let mut message = map_message_resource_to_service(message_resource, link.id).map_err(|e| {
- ProcessingError::NonRetryable(DetailedError {
- reason: FailureReason::GmailApiFailed,
- source: e.context("Failed to map message resource to service".to_string()),
- })
- })?;
let message_attachment_count = message.attachments.len();
// will always exist because we just fetched it
@@ -241,20 +224,11 @@ pub async fn upsert_message(
})
})?;
} else {
- fetch_and_insert_thread(
- ctx,
- payload,
- &gmail_access_token,
- link.id,
- &provider_thread_id,
- )
- .await
- .map_err(|e| {
- ProcessingError::Retryable(DetailedError {
- reason: FailureReason::DatabaseQueryFailed,
- source: e.context("Failed to fetch and insert thread".to_string()),
- })
- })?;
+ // Propagated verbatim: fetch_and_insert_thread already routed provider
+ // errors through handle_operation_error (retry queue vs redelivery),
+ // and re-wrapping would double-process rate limits and mislabel
+ // permanent failures as retryable.
+ fetch_and_insert_thread(ctx, payload, link.id, &provider_thread_id).await?;
}
let (message_db_id, thread_db_id) =
@@ -326,14 +300,7 @@ pub async fn upsert_message(
publish_email_event(&ctx.macro_event_broker, &event);
}
- handle_attachment_upload(
- ctx,
- &gmail_access_token,
- link,
- payload,
- &message.attachments,
- )
- .await?;
+ handle_attachment_upload(ctx, link, payload, &message.attachments).await?;
handle_contacts_sync(
ctx,
@@ -376,10 +343,9 @@ pub async fn upsert_message(
Ok(())
}
-#[tracing::instrument(skip(ctx, gmail_access_token, attachments), err)]
+#[tracing::instrument(skip(ctx, attachments), err)]
async fn handle_attachment_upload(
ctx: &PubSubContext,
- gmail_access_token: &str,
link: &link::Link,
payload: &UpsertMessagePayload,
attachments: &[Attachment],
@@ -478,12 +444,10 @@ async fn handle_attachment_upload(
let ctx_upload = UploadAttachmentContext {
db: &ctx.db,
- redis_client: &ctx.redis_client,
- gmail_client: &ctx.gmail_client,
+ email_api: &ctx.email_api,
dss_client: &ctx.dss_client,
sfs_client: &ctx.sfs_client,
system_properties_service: &ctx.system_properties_service,
- access_token: gmail_access_token,
link,
};
@@ -572,46 +536,30 @@ async fn handle_contacts_sync(
}
/// Process and insert email threads by handling attachments and images
-#[tracing::instrument(skip(ctx, gmail_access_token))]
+#[tracing::instrument(skip(ctx))]
async fn fetch_and_insert_thread(
ctx: &PubSubContext,
payload: &UpsertMessagePayload,
- gmail_access_token: &str,
link_id: Uuid,
provider_thread_id: &str,
-) -> anyhow::Result<()> {
- // fetch threads
- check_gmail_rate_limit_inbox_sync(
- ctx,
+) -> result::Result<(), ProcessingError> {
+ let messages = match ctx.email_api.get_thread(link_id, provider_thread_id).await {
+ Ok(messages) => messages,
+ Err(error) => {
+ return Err(handle_operation_error(
+ ctx,
+ link_id,
+ InboxSyncOperation::UpsertMessage(payload.clone()),
+ error,
+ )
+ .await);
+ }
+ };
+ let mut threads = vec![thread_from_normalized_messages(
link_id,
- GmailApiOperation::ThreadsGet,
- InboxSyncOperation::UpsertMessage(payload.clone()),
- )
- .await
- .map_err(anyhow::Error::from)?;
-
- let thread_resource = ctx
- .gmail_client
- .get_thread(gmail_access_token, provider_thread_id)
- .await
- .map_err(|e| {
- // retryable because a failure here is likely a transient Gmail API error,
- // matching the get_message error handling above
- ProcessingError::Retryable(DetailedError {
- reason: FailureReason::GmailApiFailed,
- source: e.context("Failed to get thread from gmail api".to_string()),
- })
- })?;
-
- // Map Gmail resources to service models (IDs are generated in the parse functions)
- let mut threads = map_thread_resources_to_service(vec![thread_resource], link_id)
- .await
- .map_err(|e| {
- ProcessingError::NonRetryable(DetailedError {
- reason: FailureReason::GmailApiFailed,
- source: anyhow::anyhow!("Failed to map thread resources: {}", e),
- })
- })?;
+ provider_thread_id,
+ messages,
+ )];
// process threads
process_threads_pre_insert(&mut threads).await;
@@ -631,6 +579,51 @@ async fn fetch_and_insert_thread(
Ok(())
}
+fn thread_from_normalized_messages(
+ link_id: Uuid,
+ provider_thread_id: &str,
+ mut messages: Vec<Message>,
+) -> Thread {
+ messages.sort_by_key(|message| message.internal_date_ts);
+ let inbox_visible = messages.iter().any(|message| {
+ message.labels.iter().any(|label| {
+ label.provider_label_id == models_email::service::label::system_labels::INBOX
+ })
+ });
+ let is_read = messages.iter().all(|message| message.is_read);
+ let latest_inbound_message_ts = messages
+ .iter()
+ .rfind(|message| is_inbound(message))
+ .and_then(|message| message.internal_date_ts);
+ let latest_outbound_message_ts = messages
+ .iter()
+ .rfind(|message| is_outbound(message))
+ .and_then(|message| message.internal_date_ts);
+ let latest_non_spam_message_ts = messages
+ .iter()
+ .rfind(|message| !is_spam_or_trash(message))
+ .and_then(|message| message.internal_date_ts);
+ let thread_db_id = Uuid::now_v7();
+ for message in &mut messages {
+ message.thread_db_id = thread_db_id;
+ }
+ let now = chrono::Utc::now();
+
+ Thread {
+ db_id: thread_db_id,
+ provider_id: Some(provider_thread_id.to_string()),
+ link_id,
+ inbox_visible,
+ is_read,
+ latest_inbound_message_ts,
+ latest_outbound_message_ts,
+ latest_non_spam_message_ts,
+ created_at: now,
+ updated_at: now,
+ messages,
+ }
+}
+
/// Process and insert message
#[tracing::instrument(skip(ctx))]
async fn process_and_insert_message(
diff --git a/services/email_service/src/pubsub/inbox_sync/process.rs b/services/email_service/src/pubsub/inbox_sync/process.rs
index 64e4e5e3c4..6161e6c6f6 100644
--- a/services/email_service/src/pubsub/inbox_sync/process.rs
+++ b/services/email_service/src/pubsub/inbox_sync/process.rs
@@ -4,15 +4,11 @@ use crate::pubsub::inbox_sync::operations::delete_message::delete_message;
use crate::pubsub::inbox_sync::operations::gmail_message::gmail_message;
use crate::pubsub::inbox_sync::operations::update_labels::update_labels;
use crate::pubsub::inbox_sync::operations::upsert_message::upsert_message;
-use crate::util::redis::rate_limit::RateLimitArgs;
use anyhow::{Context, Result, anyhow};
use models_email::gmail::inbox_sync::{InboxSyncOperation, InboxSyncPubsubMessage};
-use models_email::gmail::operations::GmailApiOperation;
-use models_email::service::link::Link;
use models_email::service::pubsub::{DetailedError, FailureReason, ProcessingError};
use sqs_worker::cleanup_message;
use std::result;
-use uuid::Uuid;
/// Processes a message from the gmail inbox sync queue.
pub async fn process_message(
@@ -124,78 +120,3 @@ fn extract_inbox_sync_message(
Ok(backfill_message)
}
-
-pub async fn fetch_pubsub_gmail_token(
- ctx: &PubSubContext,
- link: &Link,
-) -> result::Result<String, ProcessingError> {
- let gmail_access_token = crate::util::gmail::auth::fetch_token_or_mark_reauth(
- link,
- &ctx.db,
- &ctx.redis_client,
- &ctx.auth_service_client,
- &ctx.sqs_client,
- )
- .await
- .map_err(|e| {
- ProcessingError::NonRetryable(DetailedError {
- reason: FailureReason::AccessTokenFetchFailed,
- source: e.context("Failed to fetch gmail access token".to_string()),
- })
- })?;
- Ok(gmail_access_token)
-}
-
-/// Checks Gmail API rate limits and routes processing accordingly.
-///
-/// Uses a two-tier inbox sync system to prevent rate limit backpressure:
-/// - **Primary worker**: If rate limited, enqueues to retry queue and returns non-retryable error
-/// - **Retry worker**: If rate limited, returns retryable error so it gets tried again later
-///
-/// This design keeps the primary queue flowing by offloading rate-limited operations to a
-/// separate retry queue, preventing head-of-line blocking.
-pub async fn check_gmail_rate_limit_inbox_sync(
- ctx: &PubSubContext,
- link_id: Uuid,
- operation: GmailApiOperation,
- sync_operation: InboxSyncOperation,
-) -> result::Result<(), ProcessingError> {
- if !ctx
- .redis_client
- .is_rate_limited(RateLimitArgs {
- user_id: link_id,
- operation,
- is_backfill: false,
- })
- .await
- {
- // Not rate limited, continue processing
- return Ok(());
- }
-
- if !ctx.retry_worker {
- ctx.sqs_client
- .enqueue_gmail_retry_inbox_sync_notification(InboxSyncPubsubMessage {
- link_id,
- operation: sync_operation,
- })
- .await
- .map_err(|e| {
- ProcessingError::NonRetryable(DetailedError {
- reason: FailureReason::SqsEnqueueFailed,
- source: e.context("Failed to enqueue retry message"),
- })
- })?;
- Err(ProcessingError::NonRetryable(DetailedError {
- reason: FailureReason::GmailApiRateLimited,
- source: anyhow::Error::msg(
- "Gmail API rate limit exceeded, enqueued message on retry queue",
- ),
- }))
- } else {
- Err(ProcessingError::Retryable(DetailedError {
- reason: FailureReason::GmailApiRateLimited,
- source: anyhow::Error::msg("Gmail API rate limit exceeded in retry worker"),
- }))
- }
-}
diff --git a/services/email_service/src/pubsub/inbox_sync/worker.rs b/services/email_service/src/pubsub/inbox_sync/worker.rs
index e929816522..a14eb1e7f5 100644
--- a/services/email_service/src/pubsub/inbox_sync/worker.rs
+++ b/services/email_service/src/pubsub/inbox_sync/worker.rs
@@ -1,3 +1,4 @@
+use crate::outbound::email_api::GmailApi;
use crate::pubsub::context::{
CalendarBackfillServices, CrmServiceType, NotificationIngressType, PubSubContext,
PubSubEventBroker,
@@ -5,7 +6,6 @@ use crate::pubsub::context::{
use crate::pubsub::inbox_sync::process;
use crate::pubsub::worker_lifecycle::run_until_cancelled;
use crate::util::redis::RedisClient;
-use authentication_service_client::AuthServiceClient;
use connection_gateway_client::client::ConnectionGatewayClient;
use contacts::domain::service::SqsContactsIngress;
use contacts::outbound::ingress::SqsContactsQueue;
@@ -23,8 +23,7 @@ pub async fn run_worker(
worker: sqs_worker::SQSWorker,
sqs_client: sqs_client::SQS,
contacts_ingress: Arc<SqsContactsIngress<SqsContactsQueue>>,
- gmail_client: gmail_client::GmailClient,
- auth_service_client: AuthServiceClient,
+ email_api: GmailApi,
redis_client: RedisClient,
notification_ingress_service: Arc<NotificationIngressType>,
sfs_client: StaticFileServiceClient,
@@ -42,8 +41,7 @@ pub async fn run_worker(
worker,
sqs_client,
contacts_ingress,
- gmail_client,
- auth_service_client,
+ email_api,
redis_client,
notification_ingress_service,
sfs_client,
@@ -69,8 +67,7 @@ pub async fn run_worker_with_cancellation(
worker: sqs_worker::SQSWorker,
sqs_client: sqs_client::SQS,
contacts_ingress: Arc<SqsContactsIngress<SqsContactsQueue>>,
- gmail_client: gmail_client::GmailClient,
- auth_service_client: AuthServiceClient,
+ email_api: GmailApi,
redis_client: RedisClient,
notification_ingress_service: Arc<NotificationIngressType>,
sfs_client: StaticFileServiceClient,
@@ -90,8 +87,7 @@ pub async fn run_worker_with_cancellation(
sqs_worker: worker.clone(),
sqs_client,
contacts_ingress,
- gmail_client,
- auth_service_client,
+ email_api,
redis_client,
notification_ingress_service,
sfs_client,
diff --git a/services/email_service/src/pubsub/link_manager/context.rs b/services/email_service/src/pubsub/link_manager/context.rs
index dd2cfb0599..847154d088 100644
--- a/services/email_service/src/pubsub/link_manager/context.rs
+++ b/services/email_service/src/pubsub/link_manager/context.rs
@@ -1,8 +1,8 @@
+use crate::outbound::email_api::GmailApi;
use crate::pubsub::context::{CrmServiceType, NotificationIngressType, PubSubEventBroker};
use crate::util::redis::RedisClient;
use authentication_service_client::AuthServiceClient;
use connection_gateway_client::client::ConnectionGatewayClient;
-use gmail_client::GmailClient;
use sqlx::PgPool;
use sqs_client::SQS;
use std::sync::Arc;
@@ -11,7 +11,7 @@ use std::sync::Arc;
pub struct LinkManagerContext {
pub db: PgPool,
pub sqs_worker: sqs_worker::SQSWorker,
- pub gmail_client: GmailClient,
+ pub email_api: GmailApi,
pub auth_service_client: AuthServiceClient,
pub redis_client: RedisClient,
pub sqs_client: SQS,
diff --git a/services/email_service/src/pubsub/link_manager/process.rs b/services/email_service/src/pubsub/link_manager/process.rs
index 906443ec5f..4b69c7fbd1 100644
--- a/services/email_service/src/pubsub/link_manager/process.rs
+++ b/services/email_service/src/pubsub/link_manager/process.rs
@@ -1,15 +1,12 @@
use crate::pubsub::link_manager::context::LinkManagerContext;
use crate::pubsub::util::{build_notification_recipients, cg_refresh_email, publish_email_event};
-use crate::util::gmail::auth::{
- fetch_gmail_access_token_from_link, fetch_token_or_mark_reauth,
- fetch_token_or_mark_reauth_no_cache, is_forbidden_error, is_reauth_required_error,
-};
use crate::util::sync_contacts::sync_contacts;
use anyhow::{Context, anyhow};
use crm::domain::service::CrmService;
use email::domain::events::{
EmailMacroEvent, LinkDisconnectReason, LinkDisconnectedMetadata, LinkReauthRequiredMetadata,
};
+use email_api_client::domain::models::{AccessToken, EmailApiError, TokenFreshness};
use model_entity::EntityType;
use model_notifications::InboxReauthRequiredMetadata;
use models_email::api::refresh::RefreshEmailEvent;
@@ -19,8 +16,37 @@ use models_email::service::link::{Link, UserProvider};
use notification::domain::models::SendNotificationRequestBuilder;
use notification::domain::service::NotificationIngress;
use sqs_worker::cleanup_message;
+use std::future::Future;
use std::time::Duration;
-use tokio_retry::RetryIf;
+
+#[cfg(test)]
+mod test;
+
+/// Backoff schedule for teardown provider calls: three attempts total.
+const TEARDOWN_RETRY_DELAYS: [Duration; 2] =
+ [Duration::from_millis(200), Duration::from_millis(400)];
+
+/// Runs a teardown provider call with a bounded retry (3 attempts, 200/400ms).
+///
+/// Only transient failures retry. Permanent errors (revoked grants, missing
+/// scopes) return immediately: retrying cannot help while tearing a link down.
+async fn retry_teardown<F, Fut>(mut operation: F) -> Result<(), EmailApiError>
+where
+ F: FnMut() -> Fut,
+ Fut: Future<Output = Result<(), EmailApiError>>,
+{
+ let mut delays = TEARDOWN_RETRY_DELAYS.iter();
+ loop {
+ match operation().await {
+ Ok(()) => return Ok(()),
+ Err(error) if error.is_transient() => match delays.next() {
+ Some(delay) => tokio::time::sleep(*delay).await,
+ None => return Err(error),
+ },
+ Err(error) => return Err(error),
+ }
+ }
+}
#[tracing::instrument(skip(ctx, message), err)]
pub async fn process_message(
@@ -34,17 +60,13 @@ pub async fn process_message(
let link = get_link_or_skip(&ctx, message, link_id).await?;
let Some(link) = link else { return Ok(()) };
- let result = fetch_token_or_mark_reauth(
- &link,
- &ctx.db,
- &ctx.redis_client,
- &ctx.auth_service_client,
- &ctx.sqs_client,
- )
- .await;
+ let result = ctx
+ .email_api
+ .get_access_token(link.id, TokenFreshness::Cached)
+ .await;
- if let Some(gmail_access_token) = settle_reauth_fetch(&ctx, &link, result).await? {
- handle_refresh(&ctx, &link, &gmail_access_token).await?;
+ if settle_reauth_fetch(&ctx, &link, result).await?.is_some() {
+ handle_refresh(&ctx, &link).await?;
}
}
LinkManagerMessage::HealthCheck { link_id } => {
@@ -54,14 +76,10 @@ pub async fn process_message(
// Probe-only: the health side effects happen inside the fetch; a live token
// needs no follow-up work here. No-cache so a just-revoked grant is observed
// now rather than masked by a still-valid cached access token.
- let result = fetch_token_or_mark_reauth_no_cache(
- &link,
- &ctx.db,
- &ctx.redis_client,
- &ctx.auth_service_client,
- &ctx.sqs_client,
- )
- .await;
+ let result = ctx
+ .email_api
+ .get_access_token(link.id, TokenFreshness::Fresh)
+ .await;
settle_reauth_fetch(&ctx, &link, result).await?;
}
@@ -78,8 +96,7 @@ pub async fn process_message(
let link = get_link_or_skip(&ctx, message, link_id).await?;
let Some(link) = link else { return Ok(()) };
- let gmail_access_token = fetch_teardown_token(&ctx, &link).await;
- handle_delete(&ctx, &link, gmail_access_token.as_deref(), &deletion_reason).await?;
+ handle_delete(&ctx, &link, &deletion_reason).await?;
}
LinkManagerMessage::DeleteUser { fusionauth_user_id } => {
handle_delete_all_user_links(&ctx, &fusionauth_user_id).await?;
@@ -90,8 +107,8 @@ pub async fn process_message(
Ok(())
}
-/// Settles the outcome of a token fetch that records reauth health (the `*_or_mark_reauth`
-/// family). Returns the token on success. When the grant is gone the link has already been
+/// Settles the outcome of a service token probe that records reauth health.
+/// Returns the token on success. When the grant is gone the link has already been
/// marked for reauth as a side effect, so the message is terminal — return `None` to let it
/// be dropped — but only once that mark is persisted; if the mark write itself failed,
/// propagate the error so the message retries and the health signal isn't lost. Other,
@@ -99,23 +116,30 @@ pub async fn process_message(
async fn settle_reauth_fetch(
ctx: &LinkManagerContext,
link: &Link,
- result: anyhow::Result<String>,
-) -> anyhow::Result<Option<String>> {
+ result: Result<AccessToken, EmailApiError>,
+) -> anyhow::Result<Option<AccessToken>> {
match result {
Ok(token) => Ok(Some(token)),
- Err(e) if is_reauth_required_error(&e) => {
+ Err(EmailApiError::AuthRequired) => {
let persisted = email_db_client::links::get::fetch_link_by_id(&ctx.db, link.id)
.await
.context("Failed to verify needs_reauth state after token fetch failure")?
.is_some_and(|l| l.needs_reauth);
- if !persisted {
- return Err(e.context("reauth required but needs_reauth not persisted"));
- }
-
- Ok(None)
+ settle_reauth_result(Err(EmailApiError::AuthRequired), persisted)
}
- Err(e) => Err(e),
+ result => settle_reauth_result(result, false),
+ }
+}
+
+fn settle_reauth_result(
+ result: Result<AccessToken, EmailApiError>,
+ needs_reauth_persisted: bool,
+) -> anyhow::Result<Option<AccessToken>> {
+ match result {
+ Ok(token) => Ok(Some(token)),
+ Err(EmailApiError::AuthRequired) if needs_reauth_persisted => Ok(None),
+ Err(error) => Err(anyhow::Error::new(error)),
}
}
@@ -133,77 +157,29 @@ async fn get_link_or_skip(
Ok(link)
}
-/// Best-effort token fetch for stopping a Gmail watch during link teardown. A transient
-/// auth-service failure would otherwise drop the stop silently and leave the watch
-/// running, so retry a few times. A revoked grant (Forbidden) can never yield a token,
-/// so don't retry it — the watch then lingers until Gmail expires it or the next connect
-/// stops it.
-async fn fetch_teardown_token(ctx: &LinkManagerContext, link: &Link) -> Option<String> {
- const MAX_ATTEMPTS: usize = 3;
-
- let retry_strategy = [Duration::from_millis(200), Duration::from_millis(400)];
- let mut attempt = 0usize;
- let result = RetryIf::start(
- retry_strategy,
- || {
- attempt += 1;
- async move {
- let result = fetch_gmail_access_token_from_link(
- link,
- &ctx.redis_client,
- &ctx.auth_service_client,
- )
- .await;
- if let Err(error) = &result
- && !is_forbidden_error(error)
- && attempt < MAX_ATTEMPTS
- {
- tracing::warn!(error=?error, attempt, link_id=%link.id, "Transient failure fetching token to stop Gmail watch; retrying");
- }
- result
- }
- },
- |error: &anyhow::Error| !is_forbidden_error(error),
- )
- .await;
-
- match result {
- Ok(token) => Some(token),
- Err(error) if is_forbidden_error(&error) => {
- tracing::warn!(error=?error, link_id=%link.id, "Gmail access revoked; cannot stop watch (it will expire on its own)");
- None
+/// Handles the Refresh operation: renews Gmail watch subscription and syncs contacts.
+#[tracing::instrument(skip(ctx), fields(link = ?link), err)]
+async fn handle_refresh(ctx: &LinkManagerContext, link: &Link) -> anyhow::Result<()> {
+ // A refused or transient renewal must leave the worker message available for retry.
+ // Deterministic provider failures preserve the previous best-effort behavior.
+ if let Err(error) = ctx.email_api.register_subscription(link.id).await {
+ if matches!(error, EmailApiError::AuthRequired) {
+ settle_reauth_fetch(ctx, link, Err(error)).await?;
+ return Ok(());
}
- Err(error) => {
- tracing::warn!(error=?error, link_id=%link.id, "Could not fetch token to stop Gmail watch after retries; watch will linger until it expires or the next connect stops it");
- None
+ if error.is_transient() {
+ return Err(anyhow::Error::new(error).context("Failed to renew Gmail watch"));
}
+ tracing::error!(error=?error, "Failed to renew Gmail watch");
}
-}
-
-/// Handles the Refresh operation: renews Gmail watch subscription and syncs contacts.
-#[tracing::instrument(skip(ctx, gmail_access_token), fields(link = ?link), err)]
-async fn handle_refresh(
- ctx: &LinkManagerContext,
- link: &Link,
- gmail_access_token: &str,
-) -> anyhow::Result<()> {
- // Renew the Gmail watch subscription to ensure we keep getting updates.
- // We can proceed with contact sync even if this fails, so we'll just log the error.
- renew_gmail_watch(ctx, gmail_access_token, link)
- .await
- .inspect_err(|e| {
- tracing::error!(error=?e, "Failed to renew Gmail watch");
- })
- .ok();
// Sync contacts and update sync tokens in the database
if let Err(e) = sync_contacts(
link,
&ctx.db,
- &ctx.gmail_client,
+ &ctx.email_api,
&ctx.sqs_client,
&ctx.macro_event_broker,
- gmail_access_token,
)
.await
{
@@ -291,16 +267,7 @@ async fn handle_delete_all_user_links(
);
for link in &links {
- let gmail_access_token = fetch_teardown_token(ctx, link).await;
-
- if let Err(e) = handle_delete(
- ctx,
- link,
- gmail_access_token.as_deref(),
- &DeletionReason::UserDeleted,
- )
- .await
- {
+ if let Err(e) = handle_delete(ctx, link, &DeletionReason::UserDeleted).await {
tracing::error!(error=?e, link_id=?link.id, "Failed to delete link during user cleanup");
}
}
@@ -309,11 +276,10 @@ async fn handle_delete_all_user_links(
}
/// notifies downstream dependencies of link deletion, and deletes link (and all data) from database
-#[tracing::instrument(skip(ctx, gmail_access_token), fields(link = ?link), err)]
+#[tracing::instrument(skip(ctx), fields(link = ?link), err)]
async fn handle_delete(
ctx: &LinkManagerContext,
link: &Link,
- gmail_access_token: Option<&str>,
deletion_reason: &DeletionReason,
) -> anyhow::Result<()> {
tracing::info!("Deleting link");
@@ -330,6 +296,17 @@ async fn handle_delete(
})
.ok();
+ // Best effort: revoked grants and provider failures must not block local teardown.
+ // Stop before evicting the token so a valid cached grant remains available for the call.
+ // The health-neutral path never marks the link as needing reauth or notifies the
+ // user about an inbox that is being intentionally removed.
+ retry_teardown(|| ctx.email_api.stop_subscription_for_link(link))
+ .await
+ .inspect_err(|error| {
+ tracing::warn!(error=?error, "Gmail call to stop watch failed");
+ })
+ .ok();
+
// delete cached access token, in case user re-enables within cache window
ctx.redis_client
.delete_gmail_access_token(&TokenCacheKey::new(
@@ -343,16 +320,6 @@ async fn handle_delete(
})
.ok();
- // make call to gmail to unregister. may fail if the user revoked our access (which is a reason
- // that we may be deleting their link in the first place)
- if let Some(token) = gmail_access_token {
- if let Err(e) = ctx.gmail_client.stop_watch(token).await {
- tracing::warn!(error=?e, "Gmail call to stop watch failed");
- }
- } else {
- tracing::debug!("Skipping Gmail stop_watch - no access token available");
- }
-
// remove google fusionauth link with gmail inbox permissions. best-effort: the FA user may
// already be gone (e.g. account deleted before we delete their email), so we warn and keep
// going rather than failing the message and retrying.
@@ -494,27 +461,3 @@ fn extract_message(message: &aws_sdk_sqs::types::Message) -> anyhow::Result<Link
serde_json::from_str(message_body)
.context("Failed to deserialize message body to LinkManagerMessage")
}
-
-/// Calls the Gmail API to renew the watch subscription for inbox updates.
-async fn renew_gmail_watch(
- ctx: &LinkManagerContext,
- gmail_access_token: &str,
- link: &Link,
-) -> anyhow::Result<()> {
- // We ignore the result of the watch call itself, but map the error for logging.
- let _ = ctx
- .gmail_client
- .register_watch(gmail_access_token)
- .await
- .map_err(|e| {
- let error_message = "Unable to register Gmail watch";
- tracing::error!(
- error = ?e,
- email = %link.macro_id,
- provider = ?link.provider,
- error_message
- );
- anyhow!(error_message)
- });
- Ok(())
-}
diff --git a/services/email_service/src/pubsub/link_manager/process/test.rs b/services/email_service/src/pubsub/link_manager/process/test.rs
new file mode 100644
index 0000000000..3f439d5605
--- /dev/null
+++ b/services/email_service/src/pubsub/link_manager/process/test.rs
@@ -0,0 +1,93 @@
+use super::*;
+use std::sync::atomic::{AtomicU32, Ordering};
+
+fn transient() -> EmailApiError {
+ EmailApiError::Transient {
+ message: "blip".to_string(),
+ }
+}
+
+async fn run_retry(results: Vec<Result<(), EmailApiError>>) -> (Result<(), EmailApiError>, u32) {
+ let attempts = AtomicU32::new(0);
+ let results = std::sync::Mutex::new(results.into_iter());
+ let outcome = retry_teardown(|| {
+ attempts.fetch_add(1, Ordering::SeqCst);
+ let next = results.lock().unwrap().next().expect("unexpected attempt");
+ async move { next }
+ })
+ .await;
+ (outcome, attempts.load(Ordering::SeqCst))
+}
+
+#[tokio::test(start_paused = true)]
+async fn teardown_retries_transient_failures_then_succeeds() {
+ let (outcome, attempts) = run_retry(vec![Err(transient()), Err(transient()), Ok(())]).await;
+
+ assert!(outcome.is_ok());
+ assert_eq!(attempts, 3);
+}
+
+#[tokio::test(start_paused = true)]
+async fn teardown_gives_up_after_three_transient_attempts() {
+ let (outcome, attempts) =
+ run_retry(vec![Err(transient()), Err(transient()), Err(transient())]).await;
+
+ assert!(matches!(outcome, Err(EmailApiError::Transient { .. })));
+ assert_eq!(attempts, 3);
+}
+
+#[tokio::test(start_paused = true)]
+async fn teardown_does_not_retry_permanent_failures() {
+ for error in [
+ EmailApiError::Forbidden,
+ EmailApiError::AuthRequired,
+ EmailApiError::Permanent {
+ message: "gone".to_string(),
+ },
+ ] {
+ let (outcome, attempts) = run_retry(vec![Err(error)]).await;
+
+ assert!(outcome.is_err());
+ assert_eq!(attempts, 1, "permanent errors must not retry");
+ }
+}
+
+#[test]
+fn settle_reauth_returns_successful_token() {
+ let result = settle_reauth_result(Ok(AccessToken::new("token")), false).unwrap();
+
+ assert_eq!(result.unwrap().expose_secret(), "token");
+}
+
+#[test]
+fn settle_reauth_is_terminal_after_health_is_persisted() {
+ let result = settle_reauth_result(Err(EmailApiError::AuthRequired), true).unwrap();
+
+ assert!(result.is_none());
+}
+
+#[test]
+fn settle_reauth_retries_when_health_was_not_persisted() {
+ let error = settle_reauth_result(Err(EmailApiError::AuthRequired), false).unwrap_err();
+
+ assert!(matches!(
+ error.downcast_ref::<EmailApiError>(),
+ Some(EmailApiError::AuthRequired)
+ ));
+}
+
+#[test]
+fn settle_reauth_retries_transient_probe_failures() {
+ let error = settle_reauth_result(
+ Err(EmailApiError::Transient {
+ message: "temporary failure".to_string(),
+ }),
+ true,
+ )
+ .unwrap_err();
+
+ assert!(matches!(
+ error.downcast_ref::<EmailApiError>(),
+ Some(EmailApiError::Transient { .. })
+ ));
+}
diff --git a/services/email_service/src/pubsub/link_manager/worker.rs b/services/email_service/src/pubsub/link_manager/worker.rs
index 9fbcbafd34..c9d70ba5a5 100644
--- a/services/email_service/src/pubsub/link_manager/worker.rs
+++ b/services/email_service/src/pubsub/link_manager/worker.rs
@@ -1,3 +1,4 @@
+use crate::outbound::email_api::GmailApi;
use crate::pubsub::context::{CrmServiceType, NotificationIngressType, PubSubEventBroker};
use crate::pubsub::link_manager::context::LinkManagerContext;
use crate::pubsub::link_manager::process;
@@ -16,7 +17,7 @@ use tokio_util::sync::CancellationToken;
pub async fn run_worker(
worker: sqs_worker::SQSWorker,
db: PgPool,
- gmail_client: gmail_client::GmailClient,
+ email_api: GmailApi,
auth_service_client: AuthServiceClient,
redis_client: RedisClient,
sqs_client: SQS,
@@ -28,7 +29,7 @@ pub async fn run_worker(
run_worker_with_cancellation(
worker,
db,
- gmail_client,
+ email_api,
auth_service_client,
redis_client,
sqs_client,
@@ -48,7 +49,7 @@ pub async fn run_worker(
pub async fn run_worker_with_cancellation(
worker: sqs_worker::SQSWorker,
db: PgPool,
- gmail_client: gmail_client::GmailClient,
+ email_api: GmailApi,
auth_service_client: AuthServiceClient,
redis_client: RedisClient,
sqs_client: SQS,
@@ -61,7 +62,7 @@ pub async fn run_worker_with_cancellation(
let ctx = LinkManagerContext {
db,
sqs_worker: worker.clone(),
- gmail_client,
+ email_api,
auth_service_client,
redis_client,
sqs_client,
diff --git a/services/email_service/src/pubsub/scheduled/context.rs b/services/email_service/src/pubsub/scheduled/context.rs
index 44cf774ba5..a29483d1ae 100644
--- a/services/email_service/src/pubsub/scheduled/context.rs
+++ b/services/email_service/src/pubsub/scheduled/context.rs
@@ -1,16 +1,12 @@
+use crate::outbound::email_api::GmailApi;
use crate::pubsub::context::PubSubEventBroker;
-use crate::util::redis::RedisClient;
-use authentication_service_client::AuthServiceClient;
-use gmail_client::GmailClient;
use sqlx::PgPool;
#[derive(Clone)]
pub struct ScheduledContext {
pub db: PgPool,
pub sqs_worker: sqs_worker::SQSWorker,
- pub gmail_client: GmailClient,
- pub auth_service_client: AuthServiceClient,
- pub redis_client: RedisClient,
+ pub email_api: GmailApi,
pub s3_client: s3_client::S3,
pub attachment_bucket: String,
pub macro_event_broker: PubSubEventBroker,
diff --git a/services/email_service/src/pubsub/scheduled/process.rs b/services/email_service/src/pubsub/scheduled/process.rs
index c2341c2c46..45d84a58a7 100644
--- a/services/email_service/src/pubsub/scheduled/process.rs
+++ b/services/email_service/src/pubsub/scheduled/process.rs
@@ -1,6 +1,5 @@
use crate::pubsub::scheduled::context::ScheduledContext;
use crate::pubsub::util::publish_email_event;
-use crate::util::gmail::auth::fetch_gmail_access_token_from_link;
use crate::util::gmail::send::{
cleanup_draft_attachments, fetch_and_attach_draft_attachments,
fetch_and_attach_forwarded_attachments, generate_email_threading_headers,
@@ -8,12 +7,16 @@ use crate::util::gmail::send::{
use anyhow::Context;
use chrono::Utc;
use email::domain::events::{EmailEventOrigin, EmailMacroEvent, MessageSentMetadata};
+use email_api_client::domain::models::{SendRequest, SentIds};
use email_db_client::messages::scheduled::get::get_and_start_processing_scheduled_message;
use models_email::service::message::MessageToSend;
use models_email::service::pubsub::ScheduledPubsubMessage;
use sqlx_core::any::AnyConnectionBackend;
use sqs_worker::cleanup_message;
+#[cfg(test)]
+mod test;
+
#[tracing::instrument(skip(ctx, message), err)]
pub async fn process_message(
ctx: ScheduledContext,
@@ -68,10 +71,6 @@ async fn process_scheduled_message_inner(
return Ok(());
};
- let gmail_access_token =
- fetch_gmail_access_token_from_link(&link, &ctx.redis_client, &ctx.auth_service_client)
- .await?;
-
// Get scheduled message from database
let scheduled_message =
match get_and_start_processing_scheduled_message(&ctx.db, data.link_id, data.message_id)
@@ -143,29 +142,28 @@ async fn process_scheduled_message_inner(
.await?;
// Include forwarded attachments (fetched from Gmail at send time)
- fetch_and_attach_forwarded_attachments(
- &ctx.db,
- &ctx.gmail_client,
- &gmail_access_token,
- &link,
- &mut message_to_send,
- )
- .await?;
+ fetch_and_attach_forwarded_attachments(&ctx.db, &ctx.email_api, &link, &mut message_to_send)
+ .await?;
- // send message to gmail api
- ctx.gmail_client
+ let send_request = SendRequest {
+ message: message_to_send.clone(),
+ from: sender_contact,
+ parent_message_id,
+ references,
+ };
+ let sent_ids = ctx
+ .email_api
.send_message(
- gmail_access_token.as_str(),
- &mut message_to_send,
- &sender_contact,
- parent_message_id,
- references,
+ link.id,
+ &send_request,
+ message_to_send.provider_thread_id.as_deref(),
)
.await
.context(format!(
"Failed to send message to gmail api for message_id {}",
data.message_id
))?;
+ apply_sent_ids(&mut message_to_send, sent_ids);
let mut tx = ctx
.db
@@ -184,8 +182,7 @@ async fn process_scheduled_message_inner(
// Gmail accepted the send and the DB updates are committed:
// publish the message_sent event resolving the earlier
- // message_send_queued. Provider ids were set on
- // `message_to_send` by the Gmail send call above.
+ // message_send_queued.
// Actor is not tracked on scheduled sends; owner is on `link`.
if let (Some(message_db_id), Some(thread_db_id)) =
(message_to_send.db_id, message_to_send.thread_db_id)
@@ -260,6 +257,11 @@ async fn process_scheduled_message_inner(
Ok(())
}
+fn apply_sent_ids(message: &mut MessageToSend, sent_ids: SentIds) {
+ message.provider_id = Some(sent_ids.provider_message_id);
+ message.provider_thread_id = Some(sent_ids.provider_thread_id);
+}
+
#[tracing::instrument(skip(message))]
fn extract_scheduled_message(
message: &aws_sdk_sqs::types::Message,
diff --git a/services/email_service/src/pubsub/scheduled/process/test.rs b/services/email_service/src/pubsub/scheduled/process/test.rs
new file mode 100644
index 0000000000..3f23e3b200
--- /dev/null
+++ b/services/email_service/src/pubsub/scheduled/process/test.rs
@@ -0,0 +1,45 @@
+use email_api_client::domain::models::SentIds;
+use models_email::service::message::MessageToSend;
+use uuid::Uuid;
+
+use super::apply_sent_ids;
+
+#[test]
+fn sent_ids_are_written_back_for_existing_persistence_flow() {
+ let mut message = message_to_send();
+
+ apply_sent_ids(
+ &mut message,
+ SentIds {
+ provider_message_id: "provider-message".to_string(),
+ provider_thread_id: "provider-thread".to_string(),
+ },
+ );
+
+ assert_eq!(message.provider_id.as_deref(), Some("provider-message"));
+ assert_eq!(
+ message.provider_thread_id.as_deref(),
+ Some("provider-thread")
+ );
+}
+
+fn message_to_send() -> MessageToSend {
+ MessageToSend {
+ db_id: Some(Uuid::new_v4()),
+ provider_id: None,
+ replying_to_id: None,
+ provider_thread_id: None,
+ thread_db_id: Some(Uuid::new_v4()),
+ link_id: Uuid::new_v4(),
+ subject: "subject".to_string(),
+ to: None,
+ cc: None,
+ bcc: None,
+ body_text: Some("body".to_string()),
+ body_html: None,
+ body_macro: None,
+ attachments: None,
+ headers_json: None,
+ send_time: None,
+ }
+}
diff --git a/services/email_service/src/pubsub/scheduled/worker.rs b/services/email_service/src/pubsub/scheduled/worker.rs
index c0d6e72aef..5be5be1f99 100644
--- a/services/email_service/src/pubsub/scheduled/worker.rs
+++ b/services/email_service/src/pubsub/scheduled/worker.rs
@@ -1,21 +1,17 @@
+use crate::outbound::email_api::GmailApi;
use crate::pubsub::context::PubSubEventBroker;
use crate::pubsub::scheduled::context::ScheduledContext;
use crate::pubsub::scheduled::process;
use crate::pubsub::worker_lifecycle::run_until_cancelled;
-use crate::util::redis::RedisClient;
-use authentication_service_client::AuthServiceClient;
use futures::StreamExt;
use sqlx::PgPool;
use tokio_util::sync::CancellationToken;
/// method that ingests sqs messages and calls the process function for each
-#[expect(clippy::too_many_arguments, reason = "matches the other workers")]
pub async fn run_worker(
worker: sqs_worker::SQSWorker,
db: PgPool,
- gmail_client: gmail_client::GmailClient,
- auth_service_client: AuthServiceClient,
- redis_client: RedisClient,
+ email_api: GmailApi,
s3_client: s3_client::S3,
attachment_bucket: String,
macro_event_broker: PubSubEventBroker,
@@ -23,9 +19,7 @@ pub async fn run_worker(
run_worker_with_cancellation(
worker,
db,
- gmail_client,
- auth_service_client,
- redis_client,
+ email_api,
s3_client,
attachment_bucket,
macro_event_broker,
@@ -37,13 +31,10 @@ pub async fn run_worker(
/// Ingests SQS messages until cancellation is requested.
///
/// A batch already returned by SQS is fully processed before shutdown.
-#[expect(clippy::too_many_arguments, reason = "matches the other workers")]
pub async fn run_worker_with_cancellation(
worker: sqs_worker::SQSWorker,
db: PgPool,
- gmail_client: gmail_client::GmailClient,
- auth_service_client: AuthServiceClient,
- redis_client: RedisClient,
+ email_api: GmailApi,
s3_client: s3_client::S3,
attachment_bucket: String,
macro_event_broker: PubSubEventBroker,
@@ -52,9 +43,7 @@ pub async fn run_worker_with_cancellation(
let ctx = ScheduledContext {
db,
sqs_worker: worker.clone(),
- gmail_client,
- auth_service_client,
- redis_client,
+ email_api,
s3_client,
attachment_bucket,
macro_event_broker,
diff --git a/services/email_service/src/pubsub/util.rs b/services/email_service/src/pubsub/util.rs
index f6bda06c14..23ac1c457b 100644
--- a/services/email_service/src/pubsub/util.rs
+++ b/services/email_service/src/pubsub/util.rs
@@ -1,6 +1,4 @@
use crate::pubsub::context::PubSubContext;
-use crate::util::redis::RedisClient;
-use crate::util::redis::rate_limit::RateLimitArgs;
use chrono::{DateTime, Utc};
use connection_gateway_client::client::ConnectionGatewayClient;
use email::domain::events::EmailMacroEvent;
@@ -15,7 +13,6 @@ use models_email::email::service::backfill::{
BackfillOperation, BackfillPubsubMessage, LinkScopedPayload, PopulateCrmContactPayload,
};
use models_email::email::service::pubsub::{DetailedError, FailureReason, ProcessingError};
-use models_email::gmail::operations::GmailApiOperation;
use std::collections::HashSet;
use uuid::Uuid;
@@ -53,44 +50,6 @@ pub fn build_notification_recipients(
/// contact's pre-aggregated MIN/MAX.
pub type CrmContactRecipient = (String, Option<String>, DateTime<Utc>, DateTime<Utc>);
-/// Arguments for checking Gmail API rate limits
-pub struct CheckGmailRateLimitArgs<'a> {
- pub redis_client: &'a RedisClient,
- pub link_id: Uuid,
- pub gmail_operation: GmailApiOperation,
- pub retryable: bool,
- pub is_backfill: bool,
-}
-
-// check if we are rate limited by gmail before making any requests to the api
-pub async fn check_gmail_rate_limit(
- args: CheckGmailRateLimitArgs<'_>,
-) -> Result<(), ProcessingError> {
- if args
- .redis_client
- .is_rate_limited(RateLimitArgs {
- user_id: args.link_id,
- operation: args.gmail_operation,
- is_backfill: args.is_backfill,
- })
- .await
- {
- return if args.retryable {
- Err(ProcessingError::Retryable(DetailedError {
- reason: FailureReason::GmailApiRateLimited,
- source: anyhow::Error::msg("Gmail API rate limit exceeded"),
- }))
- } else {
- Err(ProcessingError::NonRetryable(DetailedError {
- reason: FailureReason::GmailApiRateLimited,
- source: anyhow::Error::msg("Gmail API rate limit exceeded"),
- }))
- };
- }
-
- Ok(())
-}
-
#[tracing::instrument(skip(tx, result), level = "debug")]
pub async fn complete_transaction_with_processing_error<T>(
tx: sqlx::Transaction<'_, sqlx::Postgres>,
diff --git a/services/email_service/src/util/gmail/auth.rs b/services/email_service/src/util/gmail/auth.rs
index be1ae40921..dab171a8ad 100644
--- a/services/email_service/src/util/gmail/auth.rs
+++ b/services/email_service/src/util/gmail/auth.rs
@@ -1,259 +1,31 @@
use crate::util::redis::RedisClient;
use anyhow::Context;
-use authentication_service_client::{AuthServiceClient, error::AuthServiceClientError};
-use axum::Json;
-use axum::http::StatusCode;
-use axum::response::{IntoResponse, Response};
use gmail_client::GmailClient;
-use macro_user_id::user_id::MacroUserIdStr;
-use model::response::ErrorResponse;
-use model::user::UserContext;
-use models_email::email::service::cache::TokenCacheKey;
-use models_email::email::service::link::Link;
-use models_email::email::service::link::UserProvider;
-use models_email::email::service::pubsub::LinkManagerMessage;
use models_email::gmail::inbox_sync::KeyMap;
-use sqs_client::SQS;
use std::sync::Arc;
-/// Fetches a Gmail access token for a link and records its sync health as a side
-/// effect: clears the link's reauth flag on success, and on a revoked or missing
-/// grant marks the link as needing reauth (and enqueues a one-time fan-out
-/// notification on the first such transition). Other, transient failures are
-/// returned unchanged without touching health state.
-///
-/// Pubsub handlers should use this so a dead grant surfaces for reconnect instead
-/// of stalling silently. API handlers should use `fetch_gmail_access_token_from_link`.
-#[tracing::instrument(skip(db, redis_client, auth_service_client, sqs_client))]
-pub async fn fetch_token_or_mark_reauth(
- link: &Link,
- db: &sqlx::PgPool,
- redis_client: &RedisClient,
- auth_service_client: &AuthServiceClient,
- sqs_client: &SQS,
-) -> anyhow::Result<String> {
- let result = fetch_gmail_access_token_from_link(link, redis_client, auth_service_client).await;
- record_token_health(link, db, sqs_client, result).await
-}
-
-/// Like [`fetch_token_or_mark_reauth`] but bypasses the Redis token cache and forces a
-/// fresh refresh against the auth service. A cached access token outlives a grant
-/// revocation by up to its TTL — revocation invalidates the refresh token, not an
-/// already-minted access token — so a cache-respecting fetch can miss a just-revoked
-/// grant. Probes that must observe revocation promptly use this path.
-#[tracing::instrument(skip(db, redis_client, auth_service_client, sqs_client))]
-pub async fn fetch_token_or_mark_reauth_no_cache(
- link: &Link,
- db: &sqlx::PgPool,
- redis_client: &RedisClient,
- auth_service_client: &AuthServiceClient,
- sqs_client: &SQS,
-) -> anyhow::Result<String> {
- let result =
- fetch_gmail_access_token_from_link_no_cache(link, redis_client, auth_service_client).await;
- record_token_health(link, db, sqs_client, result).await
-}
-
-/// Records a link's sync health from the outcome of a token fetch: clears the reauth
-/// flag on success, marks the link as needing reauth on a revoked or missing grant
-/// (enqueuing a one-time fan-out only on the first false->true transition), and leaves
-/// health state untouched for transient failures. Returns the fetch result unchanged.
-async fn record_token_health(
- link: &Link,
- db: &sqlx::PgPool,
- sqs_client: &SQS,
- result: anyhow::Result<String>,
-) -> anyhow::Result<String> {
- match result {
- Ok(token) => {
- email_db_client::links::update::clear_link_needs_reauth(db, link.id)
- .await
- .inspect_err(|e| {
- tracing::warn!(error=?e, link_id=%link.id, "Failed to clear needs_reauth after successful token fetch");
- })
- .ok();
- Ok(token)
- }
- Err(e) if is_reauth_required_error(&e) => {
- tracing::warn!(
- link_id = %link.id,
- fusionauth_user_id = %link.fusionauth_user_id,
- "Gmail grant no longer yields a token - marking link as needing reauth"
- );
-
- match email_db_client::links::update::set_link_needs_reauth(db, link.id).await {
- // Only the transition into needs-reauth fans out a notification, so a
- // link that keeps failing every cycle notifies its sharers just once.
- Ok(true) => {
- sqs_client
- .enqueue_link_manager_notification(
- LinkManagerMessage::NotifyReauthRequired { link_id: link.id },
- )
- .await
- .inspect_err(|e| {
- tracing::error!(error=?e, link_id=%link.id, "Failed to enqueue reauth notification");
- })
- .ok();
- }
- Ok(false) => {}
- Err(e) => {
- tracing::error!(error=?e, link_id=%link.id, "Failed to mark link as needing reauth");
- }
- }
-
- Err(e)
- }
- Err(e) => Err(e),
- }
-}
-
-/// Checks if an error chain contains a Forbidden error from the auth service.
-pub(crate) fn is_forbidden_error(e: &anyhow::Error) -> bool {
- e.chain().any(|cause| {
- cause
- .downcast_ref::<AuthServiceClientError>()
- .map(|e| matches!(e, AuthServiceClientError::Forbidden))
- .unwrap_or(false)
- })
-}
-
-/// Whether a token-fetch error means the link's grant is gone (revoked, or the
-/// underlying IdP link is missing) and the user must reconnect — as opposed to a
-/// transient failure that should be retried without flagging the link.
-pub fn is_reauth_required_error(e: &anyhow::Error) -> bool {
- e.chain().any(|cause| {
- cause
- .downcast_ref::<AuthServiceClientError>()
- .map(|e| {
- matches!(
- e,
- AuthServiceClientError::Forbidden | AuthServiceClientError::NotFound
- )
- })
- .unwrap_or(false)
- })
-}
-
-/// Creates a cache key using a link, then fetches access token. Returns error if access token can't
-/// be fetched.
-pub async fn fetch_gmail_access_token_from_link(
- link: &Link,
- redis_client: &RedisClient,
- auth_service_client: &AuthServiceClient,
-) -> anyhow::Result<String> {
- let key = TokenCacheKey::new(
- &link.fusionauth_user_id,
- link.email_address.0.as_ref(),
- link.provider.as_str(),
- );
-
- fetch_gmail_access_token(&key, redis_client, auth_service_client).await
-}
-
-/// Like [`fetch_gmail_access_token_from_link`] but bypasses the Redis cache and forces a
-/// fresh token from the auth service.
-pub async fn fetch_gmail_access_token_from_link_no_cache(
- link: &Link,
- redis_client: &RedisClient,
- auth_service_client: &AuthServiceClient,
-) -> anyhow::Result<String> {
- let key = TokenCacheKey::new(
- &link.fusionauth_user_id,
- link.email_address.0.as_ref(),
- link.provider.as_str(),
- );
-
- let conn = redis_client
- .inner
- .get_multiplexed_async_connection()
- .await
- .context("unable to connect to redis")?;
- email::outbound::fetch_gmail_access_token_no_cache(&key, &conn, auth_service_client).await
-}
-
-/// fetches a user's gmail token using the user_context from the API request.
-/// This always resolves to the JWT subject's *primary* inbox — the email part of
-/// `user_context.user_id`. For multi-inbox callers that need a specific linked
-/// inbox's token, build a `TokenCacheKey` from that link's `email_address`
-/// directly or use `fetch_gmail_access_token_from_link`.
-pub async fn fetch_gmail_token_usercontext_response(
- user_context: &UserContext,
- redis_client: &RedisClient,
- auth_service_client: &AuthServiceClient,
-) -> Result<String, Response> {
- let key = TokenCacheKey::new(
- &user_context.fusion_user_id,
- MacroUserIdStr::parse_from_str(&user_context.user_id)
- .map(|id| id.email_str().to_string())
- .map_err(|e| {
- tracing::error!(error=?e, user_id=%user_context.user_id, "unable to derive email from user id");
- (
- StatusCode::INTERNAL_SERVER_ERROR,
- Json(ErrorResponse {
- message: "unable to get gmail access token".into(),
- }),
- )
- .into_response()
- })?,
- UserProvider::Gmail.as_str(),
- );
-
- fetch_gmail_access_token(&key, redis_client, auth_service_client)
- .await
- .map_err(|e| {
- tracing::error!(error=?e, "unable to get gmail access token");
- (
- StatusCode::INTERNAL_SERVER_ERROR,
- Json(ErrorResponse {
- message: "unable to get gmail access token".into(),
- }),
- )
- .into_response()
- })
-}
-
-/// Fetches the gmail access token, first looking in the redis cache then hitting the auth service.
-///
-/// Delegates to [`email::outbound::fetch_gmail_access_token`].
-pub async fn fetch_gmail_access_token(
- key: &TokenCacheKey,
- redis_client: &RedisClient,
- auth_service_client: &AuthServiceClient,
-) -> anyhow::Result<String> {
- let conn = redis_client
- .inner
- .get_multiplexed_async_connection()
- .await
- .context("unable to connect to redis")?;
- email::outbound::fetch_gmail_access_token(key, &conn, auth_service_client).await
-}
-
-/// Retrieves Google public keys, first looking in the redis cache then fetching them from the Gmail client
+/// Retrieves Google public keys, first looking in the Redis cache and then fetching them.
#[tracing::instrument(skip(redis_client, gmail_client))]
pub async fn get_google_public_keys(
redis_client: Arc<RedisClient>,
gmail_client: Arc<GmailClient>,
) -> anyhow::Result<KeyMap> {
- // Try to get the keys from Redis cache first
- let keys_from_redis = redis_client
+ let cached_keys = redis_client
.get_google_public_keys()
.await
- .map_err(|e| {
- tracing::warn!(error=?e, "Failed to get Google public keys from Redis, falling back.");
+ .inspect_err(|error| {
+ tracing::warn!(error=?error, "Failed to get Google public keys from Redis, falling back");
})
.ok()
.flatten();
- let public_keys = if let Some(keys) = keys_from_redis {
- keys
- } else {
- fetch_and_cache_google_public_keys(redis_client, gmail_client).await?
- };
-
- Ok(public_keys)
+ match cached_keys {
+ Some(keys) => Ok(keys),
+ None => fetch_and_cache_google_public_keys(redis_client, gmail_client).await,
+ }
}
-/// Fetches Google public keys from Gmail client and caches them in Redis
+/// Fetches Google public keys from Gmail and caches them in Redis.
#[tracing::instrument(skip(redis_client, gmail_client))]
pub async fn fetch_and_cache_google_public_keys(
redis_client: Arc<RedisClient>,
@@ -264,8 +36,8 @@ pub async fn fetch_and_cache_google_public_keys(
.await
.context("Failed to fetch Google public keys")?;
- if let Err(cache_err) = redis_client.set_google_public_keys(&fetched_keys).await {
- tracing::warn!(error = ?cache_err, "Failed to cache Google public keys in Redis");
+ if let Err(cache_error) = redis_client.set_google_public_keys(&fetched_keys).await {
+ tracing::warn!(error=?cache_error, "Failed to cache Google public keys in Redis");
}
Ok(fetched_keys.keys)
diff --git a/services/email_service/src/util/gmail/send.rs b/services/email_service/src/util/gmail/send.rs
index e7f0d08dde..a75f334061 100644
--- a/services/email_service/src/util/gmail/send.rs
+++ b/services/email_service/src/util/gmail/send.rs
@@ -1,5 +1,5 @@
+use crate::outbound::email_api::GmailApi;
use anyhow::Context;
-use gmail_client::GmailClient;
use models_email::service::attachment::{AttachmentDraft, AttachmentToSend};
use models_email::service::link::Link;
use models_email::service::message;
@@ -109,13 +109,12 @@ pub async fn fetch_and_attach_draft_attachments(
/// Forwarded attachments reference original Gmail attachments, so their data is fetched
/// from Gmail at send time rather than from S3.
#[tracing::instrument(
- skip(db, gmail_client, access_token, message_to_send),
+ skip(db, email_api, message_to_send),
fields(message_db_id = ?message_to_send.db_id), err
)]
pub async fn fetch_and_attach_forwarded_attachments(
db: &PgPool,
- gmail_client: &GmailClient,
- access_token: &str,
+ email_api: &GmailApi,
link: &Link,
message_to_send: &mut message::MessageToSend,
) -> anyhow::Result<()> {
@@ -137,8 +136,8 @@ pub async fn fetch_and_attach_forwarded_attachments(
let fetch_futures = fwd_attachments.iter().map(|fwd_att| async move {
let provider_att_id = fwd_att.provider_attachment_id.as_deref().unwrap_or_default();
- let data = gmail_client
- .get_attachment_data(access_token, &fwd_att.message_provider_id, provider_att_id)
+ let data = email_api
+ .get_attachment(link.id, &fwd_att.message_provider_id, provider_att_id)
.await
.with_context(|| {
format!(
diff --git a/services/email_service/src/util/mod.rs b/services/email_service/src/util/mod.rs
index 6ae6ebe3e1..3e3aff2840 100644
--- a/services/email_service/src/util/mod.rs
+++ b/services/email_service/src/util/mod.rs
@@ -1,6 +1,5 @@
pub mod gmail;
pub mod process_pre_insert;
pub mod redis;
-pub mod sanitizer;
pub mod sync_contacts;
pub mod upload_attachment;
diff --git a/services/email_service/src/util/process_pre_insert/sync_labels.rs b/services/email_service/src/util/process_pre_insert/sync_labels.rs
index d3f93fc214..c4ff320c59 100644
--- a/services/email_service/src/util/process_pre_insert/sync_labels.rs
+++ b/services/email_service/src/util/process_pre_insert/sync_labels.rs
@@ -1,43 +1,36 @@
use anyhow::Context;
-use gmail_client::GmailClient;
use models_email::email::service::label::Label;
use sqlx::PgPool;
use std::collections::HashMap;
use uuid::Uuid;
// syncs our db labels with gmail - adds new labels, updates changed labels, deletes removed labels
-#[tracing::instrument(skip(db, gmail_client, access_token), level = "info")]
+#[tracing::instrument(skip(db, provider_labels), err)]
pub async fn sync_labels(
db: &PgPool,
- gmail_client: &GmailClient,
- access_token: &str,
link_id: Uuid,
+ provider_labels: &[Label],
) -> anyhow::Result<()> {
- // Step 1: Fetch all labels from both sources
+ // Step 1: Fetch the persisted labels
let db_labels = email_db_client::labels::get::fetch_labels_by_link_id(db, link_id)
.await
.context("Failed to fetch labels from database")?;
- let gmail_labels = gmail_client
- .fetch_user_labels(access_token, link_id)
- .await
- .context("Failed to fetch labels from Gmail API")?;
-
// Create maps for easier comparison
let db_label_map: HashMap<String, Label> = db_labels
.into_iter()
.map(|label| (label.provider_label_id.clone(), label))
.collect();
- let gmail_label_map: HashMap<String, Label> = gmail_labels
- .into_iter()
- .map(|label| (label.provider_label_id.clone(), label))
+ let provider_label_map: HashMap<&str, &Label> = provider_labels
+ .iter()
+ .map(|label| (label.provider_label_id.as_str(), label))
.collect();
// Step 2: Identify labels to delete (in DB but not in Gmail)
let labels_to_delete: Vec<String> = db_label_map
.keys()
- .filter(|provider_id| !gmail_label_map.contains_key(*provider_id))
+ .filter(|provider_id| !provider_label_map.contains_key(provider_id.as_str()))
.cloned()
.collect();
@@ -46,24 +39,24 @@ pub async fn sync_labels(
let mut update_count = 0;
// Step 3: Identify labels to insert or update
- for gmail_label in gmail_label_map.values() {
+ for provider_label in provider_label_map.values() {
// if the label exists in both the db and gmail
- if let Some(db_label) = db_label_map.get(&gmail_label.provider_label_id) {
- // if any of the label fields are different in gmail, update it in the db
- let needs_update = gmail_label.name != db_label.name
- || gmail_label.message_list_visibility != db_label.message_list_visibility
- || gmail_label.label_list_visibility != db_label.label_list_visibility
- || gmail_label.type_ != db_label.type_;
+ if let Some(db_label) = db_label_map.get(&provider_label.provider_label_id) {
+ // if any of the label fields are different in the provider, update it in the db
+ let needs_update = provider_label.name != db_label.name
+ || provider_label.message_list_visibility != db_label.message_list_visibility
+ || provider_label.label_list_visibility != db_label.label_list_visibility
+ || provider_label.type_ != db_label.type_;
if needs_update {
- let mut updated_label = gmail_label.clone();
+ let mut updated_label = (*provider_label).clone();
updated_label.id = db_label.id;
labels_to_upsert.push(updated_label);
update_count += 1;
}
- // if the label exists in gmail but not in our db, insert it into the db
+ // if the label exists in the provider but not in our db, insert it into the db
} else {
- let mut new_label = gmail_label.clone();
+ let mut new_label = (*provider_label).clone();
new_label.id = Some(macro_uuid::generate_uuid_v7());
labels_to_upsert.push(new_label);
insert_count += 1;
diff --git a/services/email_service/src/util/sync_contacts.rs b/services/email_service/src/util/sync_contacts.rs
index 594d2d8360..2490cb5dc3 100644
--- a/services/email_service/src/util/sync_contacts.rs
+++ b/services/email_service/src/util/sync_contacts.rs
@@ -1,14 +1,14 @@
-use crate::convert::map_person_to_contact;
+use crate::outbound::email_api::GmailApi;
use crate::pubsub::util::publish_email_event;
use anyhow::{Context, anyhow};
use email::domain::events::{
EmailMacroEvent, ThreadsReindexReason, ThreadsReindexRequestedMetadata,
};
+use email_api_client::domain::models::EmailApiError;
use futures::{StreamExt, stream};
-use gmail_client::GmailClient;
use macro_event_broker::MacroEventBroker;
use macro_user_id::user_id::MacroUserIdStr;
-use models_email::service::contact::Contact;
+use models_email::service::contact::{Contact, ContactList};
use models_email::service::link::Link;
use models_email::service::pubsub::SFSUploaderMessage;
use models_email::service::sync_token::SyncTokens;
@@ -25,28 +25,33 @@ mod test;
pub async fn sync_contacts<B: MacroEventBroker>(
link: &Link,
db: &PgPool,
- gmail_client: &GmailClient,
+ email_api: &GmailApi,
sqs_client: &SQS,
macro_event_broker: &B,
- gmail_access_token: &str,
) -> anyhow::Result<()> {
// 1. Get existing sync tokens from our DB
let (contacts_sync_token, other_contacts_sync_token) =
fetch_existing_sync_tokens(db, link).await?;
// 2. Fetch new contacts and the corresponding new sync tokens from the Gmail API
- let (new_contacts, new_tokens) = fetch_new_contacts_from_google(
- gmail_client,
+ let (new_contacts, new_tokens) = Box::pin(fetch_new_contacts_from_google(
+ email_api,
link,
- gmail_access_token,
contacts_sync_token,
other_contacts_sync_token,
- )
+ ))
.await;
// 3. If we received any new/updated contacts, process and store them.
if !new_contacts.is_empty() {
- process_and_store_contacts(db, sqs_client, macro_event_broker, link, new_contacts).await?;
+ Box::pin(process_and_store_contacts(
+ db,
+ sqs_client,
+ macro_event_broker,
+ link,
+ new_contacts,
+ ))
+ .await?;
}
// 4. Store the new sync tokens in our DB
@@ -76,9 +81,8 @@ async fn fetch_existing_sync_tokens(
/// Fetches primary and "other" contacts from the Google API.
/// Errors from the API are logged but do not cause this function to fail.
async fn fetch_new_contacts_from_google(
- gmail_client: &GmailClient,
+ email_api: &GmailApi,
link: &Link,
- gmail_access_token: &str,
contacts_sync_token: Option<String>,
other_contacts_sync_token: Option<String>,
) -> (Vec<Contact>, SyncTokens) {
@@ -86,9 +90,8 @@ async fn fetch_new_contacts_from_google(
let mut new_contacts_token = None;
let mut new_other_contacts_token = None;
- match gmail_client.get_self_contact(gmail_access_token).await {
- Ok(person_resource) => {
- let contact = map_person_to_contact(link.id, person_resource);
+ match email_api.get_self_contact(link.id).await {
+ Ok(contact) => {
all_new_contacts.push(contact);
}
Err(e) => {
@@ -96,32 +99,34 @@ async fn fetch_new_contacts_from_google(
}
};
- match gmail_client
- .get_contacts(gmail_access_token, contacts_sync_token.as_deref())
- .await
+ match list_contacts_with_expiry_recovery(
+ email_api,
+ link,
+ contacts_sync_token.as_deref(),
+ ContactListKind::Primary,
+ )
+ .await
{
- Ok((person_resources, sync_token)) => {
- new_contacts_token = Some(sync_token);
- let contacts = person_resources
- .into_iter()
- .map(|p| map_person_to_contact(link.id, p));
- all_new_contacts.extend(contacts);
+ Ok(contact_list) => {
+ new_contacts_token = Some(contact_list.next_sync_token);
+ all_new_contacts.extend(contact_list.contacts);
}
Err(e) => {
tracing::debug!(error = ?e, link_id = %link.id, "Failed to get primary contacts");
}
};
- match gmail_client
- .get_other_contacts(gmail_access_token, other_contacts_sync_token.as_deref())
- .await
+ match list_contacts_with_expiry_recovery(
+ email_api,
+ link,
+ other_contacts_sync_token.as_deref(),
+ ContactListKind::Other,
+ )
+ .await
{
- Ok((person_resources, sync_token)) => {
- new_other_contacts_token = Some(sync_token);
- let contacts = person_resources
- .into_iter()
- .map(|p| map_person_to_contact(link.id, p));
- all_new_contacts.extend(contacts);
+ Ok(contact_list) => {
+ new_other_contacts_token = Some(contact_list.next_sync_token);
+ all_new_contacts.extend(contact_list.contacts);
}
Err(e) => {
tracing::debug!(error = ?e, link_id = %link.id, "Failed to get other contacts");
@@ -137,6 +142,49 @@ async fn fetch_new_contacts_from_google(
(all_new_contacts, new_sync_tokens)
}
+#[derive(Debug, Clone, Copy)]
+enum ContactListKind {
+ Primary,
+ Other,
+}
+
+/// Lists one contact collection, retrying once from scratch when the stored
+/// sync token has expired.
+///
+/// People API sync tokens expire after about seven days; without this
+/// recovery, an idle link's contact sync would fail permanently until the
+/// user reconnected the inbox.
+async fn list_contacts_with_expiry_recovery(
+ email_api: &GmailApi,
+ link: &Link,
+ sync_token: Option<&str>,
+ kind: ContactListKind,
+) -> Result<ContactList, EmailApiError> {
+ match list_contacts_once(email_api, link, sync_token, kind).await {
+ Err(EmailApiError::OutdatedCursor) if sync_token.is_some() => {
+ tracing::warn!(
+ link_id = %link.id,
+ ?kind,
+ "contacts sync token expired; retrying with a full sync"
+ );
+ list_contacts_once(email_api, link, None, kind).await
+ }
+ result => result,
+ }
+}
+
+async fn list_contacts_once(
+ email_api: &GmailApi,
+ link: &Link,
+ sync_token: Option<&str>,
+ kind: ContactListKind,
+) -> Result<ContactList, EmailApiError> {
+ match kind {
+ ContactListKind::Primary => email_api.list_contacts(link.id, sync_token).await,
+ ContactListKind::Other => email_api.list_other_contacts(link.id, sync_token).await,
+ }
+}
+
/// Handles processing (SFS uploads) and database storage for a list of contacts.
async fn process_and_store_contacts<B: MacroEventBroker>(
db: &PgPool,
diff --git a/services/email_service/src/util/upload_attachment.rs b/services/email_service/src/util/upload_attachment.rs
index 9f1403bd73..677715a569 100644
--- a/services/email_service/src/util/upload_attachment.rs
+++ b/services/email_service/src/util/upload_attachment.rs
@@ -1,13 +1,11 @@
-use crate::util::redis::RedisClient;
-use crate::util::redis::rate_limit::RateLimitArgs;
+use crate::outbound::email_api::GmailApi;
use base64::Engine;
use base64::engine::general_purpose::STANDARD;
use document_storage_service_client::DocumentStorageServiceClient;
-use gmail_client::GmailClient;
+use email_api_client::domain::models::EmailApiError;
use macro_user_id::cowlike::ArcCowStr;
use macro_user_id::user_id::MacroUserId;
use model::document::response::{CreateDocumentRequest, CreateDocumentResponse};
-use models_email::gmail::operations::GmailApiOperation;
use models_email::service::attachment::{
AttachmentSfs, AttachmentUploadArgs, AttachmentUploadMetadata,
};
@@ -24,11 +22,11 @@ use uuid::Uuid;
#[derive(Error, Debug)]
pub enum UploadAttachmentError {
- #[error("Rate limit check failed: {0}")]
- RateLimitCheckFailed(String),
+ #[error("Gmail API rate limit exceeded")]
+ RateLimited,
#[error("Failed to fetch attachment data from Gmail: {0}")]
- GmailFetchFailed(String),
+ GmailFetchFailed(EmailApiError),
#[error("Failed to upload media to SFS: {0}")]
SfsUploadFailed(String),
@@ -63,13 +61,11 @@ pub enum UploadAttachmentError {
/// Context required for uploading an email attachment.
pub struct UploadAttachmentContext<'a> {
pub db: &'a sqlx::Pool<sqlx::Postgres>,
- pub redis_client: &'a RedisClient,
- pub gmail_client: &'a GmailClient,
+ pub email_api: &'a GmailApi,
pub dss_client: &'a DocumentStorageServiceClient,
pub sfs_client: &'a StaticFileServiceClient,
pub system_properties_service:
&'a Arc<SystemPropertiesServiceImpl<PgSystemPropertiesRepository>>,
- pub access_token: &'a str,
pub link: &'a link::Link,
}
@@ -78,28 +74,9 @@ pub async fn upload_attachment(
ctx: UploadAttachmentContext<'_>,
args: &AttachmentUploadArgs,
) -> Result<String, UploadAttachmentError> {
- // 1. Check rate limits before making a Gmail API call.
- if ctx
- .redis_client
- .is_rate_limited(RateLimitArgs {
- user_id: ctx.link.id,
- operation: GmailApiOperation::MessagesAttachmentsGet,
- is_backfill: args.backfill,
- })
- .await
- {
- return Err(UploadAttachmentError::RateLimitCheckFailed(
- "Gmail API rate limit exceeded".to_string(),
- ));
- }
-
- // 2. Fetch the raw attachment data from Gmail.
- let attachment_data = fetch_gmail_attachment_data(
- ctx.gmail_client,
- ctx.access_token,
- &args.attachment_metadata,
- )
- .await?;
+ // Fetching through the email API service applies this context's token and quota policy.
+ let attachment_data =
+ fetch_gmail_attachment_data(ctx.email_api, ctx.link, &args.attachment_metadata).await?;
let mime_type = args.attachment_metadata.mime_type.clone();
@@ -192,18 +169,19 @@ async fn upload_document_attachment(
/// Fetches the raw attachment data from the Gmail API.
async fn fetch_gmail_attachment_data(
- gmail_client: &GmailClient,
- access_token: &str,
+ email_api: &GmailApi,
+ link: &link::Link,
p: &AttachmentUploadMetadata,
) -> Result<Vec<u8>, UploadAttachmentError> {
- gmail_client
- .get_attachment_data(
- access_token,
- &p.email_provider_id,
- &p.provider_attachment_id,
- )
+ email_api
+ .get_attachment(link.id, &p.email_provider_id, &p.provider_attachment_id)
.await
- .map_err(|e| UploadAttachmentError::GmailFetchFailed(e.to_string()))
+ .map_err(|error| match error {
+ EmailApiError::RateLimited { .. } => UploadAttachmentError::RateLimited,
+ // Preserve the provider error so API handlers can map it to the
+ // right status instead of collapsing everything to 500.
+ error => UploadAttachmentError::GmailFetchFailed(error),
+ })
}
/// Calculates the SHA256 hash of the attachment data in both hex and base64 formats.