Release 1.9.1

[skupriienko]

Summary

This PR finalizes the release of v1.9.1 (October 7, 2026), incorporating the auto-pagination fix from PR #158 alongside key reliability, security, and supply-chain enhancements:

• Pagination Reliability: Enforces the Mailjet API specification ceiling (Limit=1000) in Endpoint.stream(), normalizes query parameter filter keys (limit vs Limit), and addresses premature pagination termination caused by page-local Total metadata.
• Security Hardening (SpamGuard DoS Protection): Introduces a 10,000-tag structural ceiling (MAX_TAG_COUNT) and explicit MAX_HTML_SIZE (5MB) enforcement in _SpamGuardParser to defend against HTML tag-bomb denial-of-service vectors (CWE-400).
• Test Suite Idempotency: Resolves integration test webhook collisions (MJ18 errors) via pre-test cleanup in test_live_eventcallbackurl_crud_lifecycle.
• Documentation & Samples: Adds interactive pagination stream examples, stream resumption samples, and automated smoke test validation.
• CI/CD & Supply Chain Maintenance: Optimizes ClusterFuzzLite scheduling, updates pre-commit hook revisions, and merges Dependabot action updates across CodeQL, Miniconda, Codecov, and OSV-Scanner (PRs build(deps): bump github/codeql-action/upload-sarif from 4.37.9 to 4.38.0 #151–build(deps): bump github/codeql-action/analyze from 4.38.0 to 4.38.1 #157).

---

Actions

• Core SDK & Endpoint Pagination (mailjet_rest/endpoint.py):

  • Fixed premature auto-pagination termination in Endpoint.stream() caused by page-local Total metadata (Total == len(Data)), continuing across full pages until len(data) < chunk_size.
  • Enforced Mailjet's API pagination ceiling (MAX_LIMIT: int = 1000) in Endpoint.stream() with an explicit ValueError guard to prevent silent page truncation caused by upstream clamping.
  • Updated _normalize_stream_filters() to strip both "limit" and "Limit" keys from input filters, ensuring caller filters do not conflict with chunk_size.
  • Updated Endpoint.stream() docstrings to document the 1,000-record maximum chunk limit.

• Security & Guardrails (mailjet_rest/utils/guardrails.py, SECURITY.md):

  • HTML Tag Bomb DoS Mitigation (CWE-400): Defined SecurityGuard.MAX_TAG_COUNT = 10000 and implemented _count_tag() across start, end, self-closing, and comment tag handlers in _SpamGuardParser to trigger immediate ValidationError on nested tag flood attacks.
  • Explicitly exposed SecurityGuard.MAX_HTML_SIZE = 5 * 1024 * 1024 (5MB) and safeguarded parser closing lifecycles.
  • Updated SECURITY.md supported versions table to designate versions < 1.9.1 as end-of-life.

• Tests, Fuzzing & Reliability (tests/):

  • Added test_stream_with_page_local_total verifying multi-page streaming across varied offsets (Offset: 0, Offset: 10) and collection sizes (size: 3, size: 4).
  • Added test_stream_chunk_size_max_limit_rejection to verify ValueError triggers when chunk_size > 1000.
  • Added test_stream_filter_strips_both_limit_casings to ensure filter normalization cleanly strips both casing variants.
  • Added test_stream_empty_collection_exits_immediately to verify a clean 1-request exit on empty collections.
  • Fixed test_live_eventcallbackurl_crud_lifecycle failure by adding idempotent pre-test cleanup for existing "open" webhooks, preventing MJ18 duplicate resource constraint errors (400 Bad Request).
  • Cleaned up misplaced imports (DoesNotExistError, ValidationError) in tests/integration/test_client.py.
  • Optimized tests/fuzz/fuzz_spamguard.py harness performance (bounded baseline buffer to 4,096 chars, deterministic >5MB memory exhaustion checks) and pruned duplicate entries from tests/fuzz/fuzzer.dict.

• Documentation & Developer Experience (DX):

  • Expanded README.md with explicit side-by-side examples comparing manual single-page queries (.get(filters={"Limit": ..., "Offset": ...})) against lazy auto-pagination (.stream()).
  • Documented stream resumption using explicit starting offsets and query string parsing (urllib.parse.parse_qs).
  • Added stream_all_contacts() to samples/contacts_sample.py.
  • Added automated smoke validation for .stream(), offset resumption, and multidict filters to samples/smoke_readme_runner.py.

• CI/CD, Workflows & Dependencies:

  • Reduced ClusterFuzzLite batch fuzzing schedule in .github/workflows/cflite_batch.yml from every 6 hours to monthly (0 0 1 * *).
  • Documented the weekly full security scan in .github/workflows/security.yml.
  • Bumped pre-commit hook revisions across commitizen (v4.19.1), semgrep (v1.179.0), typos (v1.50.3), check-jsonschema (0.38.2), slotscheck (requests>=2.33.0), ruff (v0.16.10), and mypy (v2.4.0).
  • Merged Dependabot GitHub Action dependency updates:
    • Bumped github/codeql-action/upload-sarif from 4.37.9 to 4.38.0 (build(deps): bump github/codeql-action/upload-sarif from 4.37.9 to 4.38.0 #151) and to 4.38.1 (build(deps): bump github/codeql-action/upload-sarif from 4.38.0 to 4.38.1 #156).
    • Bumped github/codeql-action/analyze from 4.37.9 to 4.38.0 (build(deps): bump github/codeql-action/analyze from 4.37.9 to 4.38.0 #152) and to 4.38.1 (build(deps): bump github/codeql-action/analyze from 4.38.0 to 4.38.1 #157).
    • Bumped google/osv-scanner-action/osv-scanner-action from 2.5.1 to 2.6.0 (build(deps): bump google/osv-scanner-action/osv-scanner-action from 2.5.1 to 2.6.0 #153).
    • Bumped codecov/codecov-action from 7.0.0 to 7.1.1 (build(deps): bump codecov/codecov-action from 7.0.0 to 7.1.1 #154).
    • Bumped conda-incubator/setup-miniconda from 4.0.1 to 4.1.0 (build(deps): bump conda-incubator/setup-miniconda from 4.0.1 to 4.1.0 #155).

---

Release

• Update files:

  • Update CHANGELOG.md (set release date to October 8, 2026, include merged PRs build(deps): bump github/codeql-action/upload-sarif from 4.37.9 to 4.38.0 #151–build(deps): bump github/codeql-action/analyze from 4.38.1 to 4.38.2 #161)
  • Bump version to 1.9.1 in mailjet_rest/_version.py

• Build & Publish:

  • Build package distributions from source (python -m build)
  • Validate distribution artifacts (twine check dist/*)
  • conda build conda.recipe
  • Tag git commit v1.9.1 and publish release to PyPI

---

Verification & Testing

To verify these changes locally, ensure your environment variables (MJ_APIKEY_PUBLIC and MJ_APIKEY_PRIVATE) are set, then execute:

• 1. Run the Unit & Integration Test Suite:
  Validates core routing, pagination boundary math, SpamGuard DoS protections, and live CRUD lifecycles.

pytest tests/ -v

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

manage.sh fuzz_all 28800 -use_value_profile=1 -max_len=4096 -shrink=1

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

bash manage.sh test_examples

---

Notes

• RC Pre-Release Verification:

python3 -m venv test_mailjet191rc1
source test_mailjet191rc1/bin/activate

pip3 install --upgrade pip
pip3 install mailjet-rest==1.9.1rc1

python3 -c "from mailjet_rest import Client"
python3 -c "import mailjet_rest; from importlib.metadata import version; print(f'Successfully installed v{version(\"mailjet_rest\")}')"

# Expected output:
# Successfully installed v1.9.1rc1