feat: implement builder-based connection API with TLS support (v0.3.0)

[bug-ops]

Summary

Implements Phase 7 of the builder-based connection API with comprehensive TLS/SSL support. This is a breaking change release (v0.3.0) that removes deprecated code and adds a modern builder pattern for connections and pools.

New Features

TlsConfig Class

Factory-based configuration for SSL/TLS connections:

• TlsConfig.from_directory(path) - Load certificates from directory
• TlsConfig.from_environment(env_var) - Load from environment variable
• TlsConfig.from_certificate(pem_content) - Use PEM string directly
• TlsConfig.with_system_roots() - Use system root certificates
• TlsConfig.insecure() - Disable verification (development only)

Builder API

• ConnectionBuilder - Programmatic connection configuration
• AsyncConnectionBuilder - Async connections with builder pattern
• ConnectionPoolBuilder - Pool configuration with TLS support
• Automatic TLS detection for hdbsqls:// URL scheme

Python Integration

• All builder classes registered in PyModule
• Comprehensive type stubs in _core.pyi for IDE autocomplete
• Export from pyhdb_rs and pyhdb_rs.aio packages
• Security: no credential leaks in __repr__ or error messages

Breaking Changes

• Removed statement_cache_size parameter from async connect() (deprecated since v0.2.x)
• Removed TypedConnection<S> internal typestate implementation (unused, 270 lines)

Migration Guide

# Old API (still works)
conn = await connect("hdbsql://user:pass@host:30015")

# New builder API  
from pyhdb_rs import TlsConfig, ConnectionBuilder

conn = (ConnectionBuilder()
    .host("hana.example.com")
    .port(30015)
    .credentials("SYSTEM", "password")
    .tls(TlsConfig.with_system_roots())
    .build())

See CHANGELOG.md for complete migration details.

Implementation Details

• Dual builder architecture:
  • Internal builder.rs - Typestate pattern for compile-time safety
  • Public py_builder.rs - Runtime validation for Python API
• Security: No credential leaks in repr/errors
• Quality: All clippy checks pass (strict mode), formatted with cargo +nightly fmt
• Testing: 48 clippy warnings fixed, all unit tests pass

Documentation

• ✅ Added v0.3.0 section to CHANGELOG.md
• ✅ Updated README with TLS/SSL examples
• ✅ Complete Python type stubs for IDE support
• ✅ Docstrings for all public methods

Verification

# Rust checks
cargo +nightly fmt --check
cargo clippy --workspace --all-features -- -D warnings  
cargo nextest run --workspace

# Python checks
ruff check python/ tests/
ruff format --check python/ tests/

# Python imports
maturin develop
python -c "from pyhdb_rs import TlsConfig, ConnectionBuilder"
python -c "from pyhdb_rs.aio import AsyncConnectionBuilder"

Files Changed

• Added: crates/hdbconnect-py/src/tls.rs (332 lines)
• Added: crates/hdbconnect-py/src/connection/py_builder.rs (790 lines)
• Deleted: crates/hdbconnect-py/src/connection/state.rs (270 lines)
• Modified: lib.rs, pool.rs, wrapper.rs, Python files, docs

Stats: 14 files changed, 2359 insertions(+), 314 deletions(-)

Phase 7 Status

All acceptance criteria met:

• ✅ Builder classes implemented with TLS support
• ✅ PyModule registration complete
• ✅ Type stubs and exports added
• ✅ ConnectionPool TLS integration
• ✅ Documentation updated (README, CHANGELOG, type stubs)
• ✅ All clippy/fmt/test checks pass
• ✅ Code review completed
• ✅ Bloat analysis complete (minimal optimization opportunities found)

Related

• Architecture plan: .local/plan/phase-7-builder-connection-api.md
• Bloat analysis: .local/analysis/hdbconnect-py-bloat-analysis.md
• Review report: .local/review/phase-7-code-review.md

[codecov-commenter]

Codecov Report

❌ Patch coverage is 0% with 3 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
python/pyhdb_rs/aio/__init__.py	0.00%	2 Missing ⚠️
crates/hdbconnect-py/src/async_support/pool.rs	0.00%	1 Missing ⚠️

❌ Your patch status has failed because the patch coverage (0.00%) is below the target coverage (80.00%). You can increase the patch coverage or adjust the target coverage.

@@            Coverage Diff             @@
##             main      #40      +/-   ##
==========================================
+ Coverage   72.24%   72.27%   +0.03%     
==========================================
  Files          38       38              
  Lines        6117     6114       -3     
==========================================
  Hits         4419     4419              
+ Misses       1698     1695       -3     

Files with missing lines	Coverage Δ
...ates/hdbconnect-py/src/async_support/connection.rs	0.00% <ø> (ø)
crates/hdbconnect-py/src/connection/builder.rs	91.50% <ø> (+4.12%)	⬆️
crates/hdbconnect-py/src/connection/wrapper.rs	0.00% <ø> (ø)
crates/hdbconnect-py/src/lib.rs	0.00% <ø> (ø)
python/pyhdb_rs/__init__.py	75.00% <ø> (ø)
crates/hdbconnect-py/src/async_support/pool.rs	4.40% <0.00%> (ø)
python/pyhdb_rs/aio/__init__.py	0.00% <0.00%> (ø)

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.