feat: add MaxKeys typed parameter with validation and ergonomic API

[HJLebbink]

feat: add MaxKeys typed parameter with validation and ergonomic API

Implements client-side validation for the max_keys parameter used in
ListObjects API calls, replacing implicit panics with explicit ValidationErr
handling. This ensures invalid user input is caught early with clear error
messages rather than causing runtime panics.

Key improvements:

• Adds MaxKeys typed parameter with validation (range: 1-1000) that matches
  MinIO EOS hard limits
• Provides ergonomic builder API: .max_keys(500) instead of requiring
  .max_keys(MaxKeys::new(500)?)
• Defers validation to request building time via to_s3request(), allowing
  graceful error propagation instead of panicking in From
• Updates client documentation to reflect client-side validation behavior
• Adds 17 comprehensive unit tests covering boundary conditions, parsing,
  and conversions
• Fixes error message redundancy to match project patterns
• Relaxes integration test assertions to respect max_keys as an upper bound,
  preventing flakiness across S3 implementations
• Removes dead code (unused MAX_KEYS_TESTING.md, new_unchecked())

The builder now accepts max_keys values via multiple ergonomic paths:

• .max_keys(500) - accepts u16 directly
• .max_keys(MaxKeys::new(500)?) - explicit pre-validation
• .max_keys(None) - use server default (1000)

Validation ensures compliance with MinIO/S3 constraints while maintaining
clean error handling throughout the request lifecycle.

[Copilot]

Pull request overview

Adds a typed MaxKeys parameter (1–1000) for ListObjects APIs, updates the list-objects builder/client docs accordingly, and introduces tests/docs to validate pagination behavior.

Changes:

• Introduce MaxKeys typed parameter with range validation and conversions (parsing/display).
• Update ListObjects builder internals to accept ergonomic .max_keys(…) input and send validated max-keys query params.
• Add integration/unit tests plus a documentation note for testing max_keys pagination behavior.

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 9 comments.

Show a summary per file

File	Description
src/s3/types/typed_parameters.rs	Adds the validated MaxKeys type and related conversions.
src/s3/error.rs	Adds ValidationErr::InvalidMaxKeys for client-side validation failures.
src/s3/types/mod.rs	Re-exports MaxKeys from types.
src/s3/builders/list_objects.rs	Switches list-objects query building to use MaxKeys; adds an ergonomic wrapper type and unit tests.
src/s3/client/list_objects.rs	Expands API docs explaining max_keys paging semantics/limits.
tests/s3/list_objects.rs	Adds integration tests covering pagination with max_keys and the max_keys=1 edge case.
docs/MAX_KEYS_TESTING.md	New doc describing how to test and reason about max_keys paging behavior.