[_]: fix: implement attachment upload limit handling

[jzunigax2]

• Introduced AttachmentUploadLimitError to manage scenarios where the upload limit is exceeded.
• Enhanced EmailService to throw HttpException with a 429 status when the upload limit is reached.
• Updated JmapMailProvider to recognize and propagate upload limit errors from upstream.
• Added comprehensive tests for attachment upload scenarios, including limit handling and error propagation.
• Improved logging in HttpGlobalExceptionFilter to include details from upstream errors.

Summary by CodeRabbit

• New Features
  • Added clear HTTP 429 responses when attachment upload allowances are exhausted.
  • Improved API documentation for attachment upload rate-limit responses.
• Bug Fixes
  • Preserved upstream HTTP status codes and response details for upload failures.
  • Distinguished quota-related upload errors from other failures.
  • Enhanced error logs with safely serialized and truncated upstream details.
• Tests
  • Added coverage for quota limits, unexpected failures, structured and unstructured error details, and unserializable data.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: b9b22ed6-4457-4a2a-937f-7b7fecd477b9

📥 Commits

Reviewing files that changed from the base of the PR and between 378abe3 and 0bfb5c1.

📒 Files selected for processing (10)

• src/common/filters/http-global-exception.filter.spec.ts
• src/common/filters/http-global-exception.filter.ts
• src/modules/email/email.controller.ts
• src/modules/email/email.service.spec.ts
• src/modules/email/email.service.ts
• src/modules/email/mail-provider.port.ts
• src/modules/infrastructure/jmap/jmap-mail.provider.spec.ts
• src/modules/infrastructure/jmap/jmap-mail.provider.ts
• src/modules/infrastructure/jmap/jmap.service.spec.ts
• src/modules/infrastructure/jmap/jmap.service.ts

Included review availability: Your plan provides up to 1 included review per hour; 0 remain after this review.

---

📝 Walkthrough

Walkthrough

The PR adds quota-aware attachment upload error handling and documents HTTP 429 responses. JMAP errors preserve upstream status codes. Global exception logs now include safely serialized upstream details.

Changes

Attachment quota error flow

Layer / File(s)	Summary
JMAP upload error status contract src/modules/infrastructure/jmap/jmap.service.ts, src/modules/infrastructure/jmap/jmap.service.spec.ts	JmapError now accepts an optional HTTP status code. Blob upload tests verify preservation of upstream 403 data.
JMAP quota failure translation src/modules/infrastructure/jmap/jmap-mail.provider.ts, src/modules/infrastructure/jmap/jmap-mail.provider.spec.ts	The provider detects quota-related 403 responses in JSON and raw-text formats and raises AttachmentUploadLimitError. Other failures propagate unchanged.
Email service quota response src/modules/email/mail-provider.port.ts, src/modules/email/email.service.ts, src/modules/email/email.service.spec.ts, src/modules/email/email.controller.ts	The email service maps AttachmentUploadLimitError to HTTP 429. Tests cover delegation and failure propagation. Swagger documents the 429 response.

Exception detail logging

Layer / File(s)	Summary
Exception detail normalization and logging src/common/filters/http-global-exception.filter.ts, src/common/filters/http-global-exception.filter.spec.ts	Global error handling extracts and safely serializes exception details, truncates them to 2,000 characters, and logs them for HTTP and unexpected errors.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Merge Risk: ⚪ Minimal · up to 0bfb5

The PR adds attachment upload-limit error handling and related tests; no actionable merge-blocking risk remains based on the available evidence.

Suggested reviewers: xabg2

Sequence Diagram(s)

sequenceDiagram
  participant EmailController
  participant EmailService
  participant JmapMailProvider
  participant JmapService
  EmailController->>EmailService: uploadAttachment
  EmailService->>JmapMailProvider: uploadAttachment
  JmapMailProvider->>JmapService: upload blob
  JmapService-->>JmapMailProvider: JmapError with statusCode 403
  JmapMailProvider-->>EmailService: AttachmentUploadLimitError
  EmailService-->>EmailController: HttpException 429

Loading

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 3 functions across 10 files.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: handling attachment upload limits.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

• Fix all pre-merge checks with AI

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/upload-error-handling

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
93.4% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud