SDK modernization

[skupriienko]

Links:

Jira

Actions:

• Architecture & Developer Experience (DX):

  • Fluent Payload Builders: Introduced MessageBuilder, SendPayloadBuilder, and TemplateContentBuilder to provide a type-safe, fluent interface for constructing complex v3.1 schemas without manual dictionary manipulation.
  • O(1) Static Route Map (routes.py): Replaced heavy, recursive __getattr__ magic methods with a pre-compiled _ROUTE_MAP registry. This drastically improves CPU cold-boot performance and dynamic route resolution.
  • ChunkedStreamer File Attachments: Implemented memory-safe lazy partitioning for file attachments using 512KB chunks, allowing absolute path attachment resolution without loading entire files into RAM.
  • Jitter Retry Engine: Built a custom JitterRetry policy for requests.Session with exponential backoff and randomized full jitter to handle transient 429/5xx errors and prevent the "Thundering Herd" effect on Mailjet's upstream API.
  • Punycode IDN Routing: Added SecurityGuard.normalize_domain() to automatically and safely encode Internationalized Domain Names (IDNs) in email sender/recipient strings (RFC 3490).

• Security & Guardrails (OWASP):

  • [Something important] Path Traversal & CRLF Mitigation (CWE-22 / CWE-113): Implemented strict path segment sanitization using urllib.parse.quote(safe="") in Endpoint, and centralized validation in SecurityGuard.sanitize_segment to completely neutralize injection attempts across the request stack.
  • Enterprise Runtime Security: Added opt-in PEP 578 Audit Hooks (sys.addaudithook) managed via the enable_security_audit config attribute to monitor runtime network events for SIEM/SecOps compliance.
  • SSRF & MitM Protection (CWE-918 / CWE-319): Hardened URL parsing in Config to strictly require https:// and valid mailjet.com or local CI loopback hostnames. Integrated SecureHTTPAdapter to strictly enforce TLS 1.2+.
  • Resource Exhaustion Guards (CWE-400): Capped HTMLPart and TextPart builder inputs at 5MB, strictly validated floating-point timeouts (blocking NaN/Infinity), and prevented infinite loops in .stream() by enforcing chunk_size > 0.
  • Secret Hygiene (CWE-316): Implemented SecretAuth to obfuscate API keys in memory dumps/tracebacks, and integrated RedactingFilter to recursively scrub secrets from standard logging outputs.
  • Pre-Flight Deliverability Validation (SpamGuard): Built a lightweight HTML static analyzer that preemptively blocks known inline XSS payloads (<script>, onerror=) before network dispatch.

• Bug Fixes:

  • Generator Infinite Loop: Fixed a critical bug in Endpoint.stream() where negative/zero chunk sizes or None offsets would cause infinite API pagination loops.
  • Builder Immutability Leak: Added .copy() to TemplateContentBuilder.build() to prevent downstream scripts from accidentally mutating internal builder state.
  • Legacy Serialization Fallback: Fixed the ensure_ascii fallback in Endpoint to properly intercept and serialize list batch payloads instead of just dict objects.

• Testing, CI/CD & Documentation:

  • Automated Fuzzing: Integrated the Atheris (libFuzzer) code coverage suite into development workflows, exposing a unified orchestration entry point (manage.sh fuzz_all) to continuously prove memory safety. Integrated ClusterFuzzLite via GitHub Actions.
  • Stateful Property Testing: Introduced Hypothesis for mathematically rigorous, rule-based state machine testing against API payloads, configurations, and URL routing logic.
  • Consolidated Tooling: Migrated completely to Ruff as the single source of truth for formatting and linting, purging legacy tools from the pipeline.
  • Supply Chain Security: Hardened the GitHub Actions validation pipeline by implementing scorecard.yml (OpenSSF), Google's osv-scanner, and independent pip-audit security jobs.

Verification & Testing:

To verify these changes locally, ensure your environment variables (MJ_APIKEY_PUBLIC and MJ_APIKEY_PRIVATE) are set, then run the following commands:

1. Run the Unit & Integration Test Suite:
Validates core routing, HTTP mappings, builder schemas, and runs live CRUD integration checks.

pytest tests/ -v

2. Run the Stateful Property Suite (Hypothesis):
Executes thousands of dynamic boundary checks against routing interpolation, pagination math, exception hierarchies, and string sanitization.

pytest tests/property/ -v

3. Run the Advanced Fuzzing Suite (Atheris):
Executes mutation coverage across core handlers, parsers, HTML filters, and differential serializers.

bash manage.sh fuzz_all 3600

4. Execute the Interactive Examples:
Runs the unified documentation scripts demonstrating fluent builders, attachment chunking, and pagination streaming.

bash manage.sh test_samples