lather

# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [1.1.0] - 2026-09-05

### Added
- `Lather.Soap.Elements`: prefix-agnostic lookups (`get/2`, `get_in/2`,
  `local_name/1`, `soap_version/1`) over parsed SOAP documents.

### Changed
- `Lather.Xml.Builder`: a bare list value under a key now renders as repeated
  sibling elements (`%{"Item" => ["1", "2"]}` → `<Item>1</Item><Item>2</Item>`),
  mirroring how `Lather.Xml.Parser` represents repeated elements. Previously a
  list rendered as a single element whose content was the joined items. A list
  of `{key, value}` pairs keeps its ordered-children meaning (#9).

### Fixed
- SOAP envelopes with any namespace prefix (`soapenv:`, `SOAP-ENV:`, `s:`,
  `env:`, none, ...) are now accepted by `Lather.Soap.Envelope.parse_response/1`,
  `Lather.Server.RequestParser`, `Lather.DynamicClient` fault detection,
  `Lather.Error.parse_soap_fault/2` and `Lather.Operation.Builder`; the SOAP
  version is detected from the namespace bound to whichever prefix is used. A
  document without an Envelope is reported as `{:error, :invalid_soap_response}`
  instead of `{:error, {:soap_fault, :invalid_soap_response}}` (#10).
- `Lather.Soap.Envelope.parse_response/1` returns `{:ok, %{}}` for an empty
  `<Body/>` instead of raising (#11).
- `Lather.Server.Handler`: malformed XML now yields a 400 Client fault instead
  of raising (#12); successful responses are no longer double-wrapped in
  `<Response><OpResponse>` and match `Lather.Server.Plug` byte for byte (#13);
  every `POST` is a SOAP call and every `GET` serves the WSDL, so paths that
  happen to contain "wsdl" no longer get a 405 (#14). Transport-level faults
  are built with `ResponseBuilder.build_fault/1` so fault strings are escaped.
- `Lather.Operation.Builder` (used by `Lather.DynamicClient.call/4`) serialises
  parameters with `Lather.Soap.Body.serialize_params/1`: nested maps no longer
  raise, lists render as repeated elements instead of being concatenated, and
  dates/booleans are rendered as XML literals. Array-typed parts wrap list values
  in the array's item element (from WSDL `:types` when available, else `item`)
  (#17).
- `Lather.Operation.Builder.validate_parameters/2` no longer requires parts the
  WSDL marks `minOccurs="0"`, matching `get_operation_metadata/1` (#18).
- `Lather.DynamicClient` `:authentication` option: `{:basic, u, p}` raised a
  `KeyError` (the client struct has no `headers` field) and
  `{:wssecurity, u, p}` was silently ignored. Basic auth is now sent as the
  `Authorization` header and WS-Security as a `UsernameToken` SOAP header;
  `{:wssecurity, u, p, opts}` passes options such as `password_type: :digest`
  (#19).
- `Lather.Auth.Basic.decode/1` accepts the `Basic` scheme case-insensitively and
  tolerates extra whitespace, per RFC 7235 (#21).
- SOAP 1.2 requests now get SOAP 1.2 responses from `Lather.Server.Plug`,
  `Handler` and `EnhancedPlug`: the envelope namespace, `Code/Value` +
  `Reason/Text` fault structure and `application/soap+xml` content type follow
  the version of the request envelope (`RequestParser` now reports
  `:soap_version`). `ResponseBuilder.build_response/3` and `build_fault/2` take
  a `:soap_version` option (#22).
- `Lather.Auth.WSSecurity.username_token/3` with `password_type: :digest` always
  produces a digest (nonce and created are optional inputs to it) instead of
  silently falling back to `PasswordText`; an unknown `password_type` raises (#20).
- `Lather.Server.validate_param_types/2` validates the lexical form of simple
  XSD types (`int`, `decimal`, `boolean`, `dateTime`, `date`, `time`, ...),
  accepts DSL atom types and `xsd:` prefixes, and returns a Client fault instead
  of raising when structured content is sent for a simple type (#16).
- `Lather.Server.RequestParser`: empty elements are `""` (was `%{}`), list items
  get the same namespace/attribute cleaning as single elements, and an element
  carrying only attributes and text collapses to its text (#15).
- `Lather.Xml.Builder`: a `parse/1` → `build_fragment/1` round-trip no longer
  collapses repeated elements into one element with joined text (#9).
- `Lather.Xml.Builder`: an element can now carry attributes and repeated child
  siblings, e.g. `%{"@xsi:type" => "...", "string" => ["A", "B"]}`; `#content`
  with `{tag, value}` pairs remains available for ordered children (#8).
- `Lather.Xml.Builder`: mixed content (`#text` alongside child elements) emits a
  text node instead of a literal `<#text>` element.
- `Lather.Soap.Body.serialize_params/1` and
  `Lather.Server.ResponseBuilder`: `DateTime`/`Date`/`Time` (and boolean)
  clauses are ordered ahead of the generic map/atom clauses so date/time values
  serialize to ISO 8601 instead of raising; regression tests added (#7).

## [1.0.49] - 2026-06-08

### Changed
- Updated development toolchain metadata to Elixir 1.20.0 on Erlang/OTP 29.
- Updated HTTP and documentation dependencies, including Bandit, Finch, Plug, ExDoc, Jason, and Telemetry.
- Adjusted Finch pool configuration for current Finch versions.

### Fixed
- Removed compiler warnings surfaced by Elixir 1.20 in project code and tests.
- Hardened an integration test server setup against random port collisions.

## [1.0.5] - 2025-12-25

### Added
- **4 new livebooks** for comprehensive feature coverage:
  - `soap12_client.livemd` - SOAP 1.2 protocol differences and client usage
  - `mtom_attachments.livemd` - Binary data transmission with MTOM/XOP
  - `production_monitoring.livemd` - Telemetry, metrics, health checks, and dashboards
  - `testing_strategies.livemd` - Unit testing, mocking, integration and contract testing
- **5 new example files** demonstrating advanced features:
  - `mtom_client.ex` - MTOM attachment handling
  - `calculator_service.ex` - Multi-type operations with error handling
  - `enhanced_plug_example.ex` - Multi-protocol server endpoints
  - `phoenix_integration.ex` - Complete Phoenix setup patterns
  - `ws_security_service.ex` - WS-Security authentication and validation
- **API.md expanded** from 13 to 30 modules (100% coverage)
- **Enhanced livebooks** with ~1,400 lines of new content:
  - `soap_server_development.livemd` - EnhancedPlug demos and multi-protocol examples
  - `enterprise_integration.livemd` - Circuit breakers, retry strategies, resilience patterns

### Fixed
- Corrected `WsdlGenerator` → `WSDLGenerator` module name references across all documentation
- Fixed non-existent `security_header/2` API references in enterprise examples and livebooks
- Fixed invalid Elixir `return` statements in debugging livebook
- Fixed `IP.puts` typo in debugging livebook
- Updated `TESTING.md` to use correct `--include external_api` flag (removed incorrect `ENABLE_LIVE_API_TESTS` references)
- Corrected `username_token/3` documentation to show keyword options instead of atom argument

### Changed
- Updated examples READMEs to accurately reflect existing files (removed 9 non-existent file references)
- All 11 livebooks now listed in README.md and USAGE.md
- Version references updated to 1.0.5 throughout documentation

## [1.0.4] - 2025-12-02

### Added
- Enhanced multi-protocol support documentation in soap_server_development livebook
- Examples of EnhancedPlug and EnhancedWSDLGenerator usage
- Phoenix router patterns for multi-protocol endpoints

### Changed
- Updated livebook documentation to highlight v1.0+ enhanced features
- Improved deployment patterns section with basic and enhanced examples

## [1.0.3] - 2025-12-02

### Fixed
- Removed references to non-existent CONTRIBUTING.md file from all documentation
- Updated GitHub repository references from markcotner to awksedgreep across all files

## [1.0.1] - 2025-01-15

### Changed
- Updated documentation to reflect current v1.0.0 status rather than treating it as "next release"
- Enhanced README with comprehensive livebooks section and detailed descriptions of all 7 interactive tutorials
- Updated USAGE.md with current API examples, multi-protocol capabilities, and production-ready patterns
- Updated all livebooks to reference correct version numbers and include hex package installation options
- Improved overall documentation consistency and confidence about current capabilities
- Updated roadmap to focus on v1.1.0, v1.2.0, and future releases

## [1.0.0] - 2025-01-15

### 🚀 **Production Release - Enhanced Multi-Protocol SOAP Library**

This is the first stable release of Lather, featuring comprehensive SOAP 1.1 and SOAP 1.2 support with modern web interfaces and multi-protocol capabilities.

### Added

- 🌟 **Enhanced WSDL Generation** (434 lines)
  - Multi-protocol WSDL documents with SOAP 1.1, SOAP 1.2, and HTTP/REST bindings
  - Layered API approach: SOAP 1.1 (compatibility) → SOAP 1.2 (enhanced) → REST/JSON (modern)
  - Protocol negotiation and automatic version detection
  - Enhanced inline documentation and service metadata
  - Backward compatibility with existing WSDL generators

- 📝 **Interactive Web Forms** (832 lines)
  - Professional HTML5 interface similar to .NET Web Services
  - Interactive operation testing with real-time form validation
  - Multi-protocol examples (SOAP 1.1, SOAP 1.2, JSON/REST)
  - Responsive CSS design with mobile support
  - **Dark mode support** - Automatically respects browser dark mode preference
  - JavaScript-powered form interaction and submission
  - Parameter validation and type-aware input controls

- 🔌 **Enhanced Plug Integration** (562 lines)
  - Multi-endpoint routing for different protocols
  - Content negotiation and automatic protocol detection
  - Interactive web interface hosting
  - Multiple WSDL variants per service (standard and enhanced)
  - RESTful JSON endpoints alongside SOAP

- 🌐 **Complete SOAP 1.2 Support** (85-90% implementation)
  - Full SOAP 1.2 envelope handling with correct namespaces
  - Version-aware HTTP transport with proper Content-Type headers
  - Enhanced error handling and fault processing
  - 17/17 integration tests passing (100% success rate)
  - Real-world service validation completed

- 🏗️ **Three-Layer Protocol Architecture**
  ```
  ┌─ SOAP 1.1 (Top - Maximum Compatibility)    │ Legacy systems, .NET Framework
  ├─ SOAP 1.2 (Middle - Enhanced Features)     │ Modern SOAP with better error handling  
  └─ REST/JSON (Bottom - Modern Applications)  │ Web apps, mobile, JavaScript
  ```

### Enhanced

- **WSDL Generation**: Now supports multiple protocol bindings in single document
- **Service Discovery**: Enhanced metadata and operation documentation
- **User Experience**: Dark mode support for better accessibility and modern UX
- **Error Handling**: Improved fault processing for SOAP 1.2
- **Performance**: Sub-millisecond processing overhead, optimized for production
- **Testing**: Comprehensive test suite with 549/556 tests passing (98.7%)

### URL Structure

- `GET  /service` → Service overview with interactive forms
- `GET  /service?wsdl` → Standard WSDL (SOAP 1.1 only)  
- `GET  /service?wsdl&enhanced=true` → Multi-protocol WSDL
- `GET  /service?op=OperationName` → Interactive operation testing form
- `POST /service` → SOAP 1.1 endpoint (maximum compatibility)
- `POST /service/v1.2` → SOAP 1.2 endpoint (enhanced features)
- `POST /service/api` → JSON/REST endpoint (modern applications)

### Dependencies

- Added `{:jason, "~> 1.4", optional: true}` for JSON support in enhanced features
- Made Plug integration more robust with graceful degradation

### Fixed

- Resolved unused variable warnings in enhanced modules
- Improved error handling for missing optional dependencies
- Enhanced list length checking for better performance
- Better JSON encoding/decoding with fallback handling

### Performance

- **Small requests (<10KB)**: 1-3ms processing overhead
- **Large requests (>100KB)**: Network-bound, processing negligible
- **WSDL generation**: 10-50ms one-time cost
- **Memory usage**: Optimized with native Elixir data structures

### Compatibility

- ✅ **Full backward compatibility** maintained
- ✅ **Existing 0.9.x services** work unchanged
- ✅ **Standard WSDL** generation unchanged
- ✅ **All existing APIs** preserved

### Migration from 0.9.x

No breaking changes. Enhanced features are additive:

```elixir
# Existing code continues to work
service_info = MyService.__service_info__()
wsdl = Lather.Server.WSDLGenerator.generate(service_info, base_url)

# Enhanced features available optionally
enhanced_wsdl = Lather.Server.EnhancedWSDLGenerator.generate(service_info, base_url)
forms = Lather.Server.FormGenerator.generate_service_overview(service_info, base_url)
```

### Known Limitations

- **MTOM Attachment Support**: Currently incomplete with 7 failing tests related to binary attachment handling. This does not affect core SOAP 1.1/1.2 functionality or any enhanced features. MTOM is an advanced feature for optimizing large binary transfers.
- **JSON Endpoint Integration**: Requires optional `jason` dependency for full functionality. Gracefully degrades when not available.

### What's Next (v1.1.0+)

- **MTOM Support Completion**: Complete binary attachment handling (7 failing tests to resolve)
- **OpenAPI 3.0 Integration**: Generate OpenAPI specs from SOAP services  
- **WS-Security Enhancements**: XML Signature and Encryption support
- **Advanced Authentication**: OAuth 2.0 and JWT token support

---

## [0.9.0] - 2025-10-30

### Added
- 🚀 **Complete SOAP Client Framework**
  - Generic SOAP client with dynamic operation discovery
  - WSDL parsing and analysis with comprehensive type extraction
  - Dynamic client generation from any WSDL
  - Support for complex types, arrays, and nested structures
  - Automatic type mapping and struct generation

- 🛡️ **Authentication & Security**
  - WS-Security UsernameToken support (PasswordText & PasswordDigest)
  - HTTP Basic Authentication
  - Custom authentication headers
  - Timestamp and nonce generation
  - Pluggable authentication system

- 🖥️ **SOAP Server Framework**
  - Complete server-side SOAP implementation
  - Macro-based DSL for defining SOAP services
  - Automatic WSDL generation from service definitions
  - Phoenix integration via Plug
  - Generic HTTP handler for standalone deployment
  - Operation dispatch and request/response handling

- 🏗️ **Core Infrastructure**
  - Robust XML parsing and generation
  - SOAP envelope construction and parsing
  - HTTP transport with Finch (connection pooling, SSL/TLS)
  - Comprehensive error handling with structured error types
  - Telemetry integration for observability
  - Support for SOAP 1.1 standard

- 📚 **Documentation & Examples**
  - 5 comprehensive Livebook tutorials
  - Interactive client examples with real SOAP services
  - Server implementation guides
  - Type system and debugging tutorials
  - Enterprise integration patterns
  - Complete API documentation

### Features
- **Universal WSDL Support**: Works with any SOAP service without hardcoded implementations
- **Type Safety**: Automatic type validation and conversion
- **Phoenix Integration**: Seamless integration with Phoenix applications
- **Production Ready**: Comprehensive error handling, logging, and monitoring
- **Extensible**: Pluggable architecture for custom authentication and transport

### Technical Details
- Built on Elixir 1.14+ and OTP 25+
- Uses Finch for HTTP transport with connection pooling
- SweetXml for robust XML parsing
- Custom XML builder for reliable SOAP envelope generation
- Telemetry for metrics and observability
- Optional Plug dependency for Phoenix integration

### Compatibility
- SOAP 1.1 (SOAP 1.2 planned for v1.0)
- WSDL 1.1 with XSD schema support
- HTTP and HTTPS transport
- Works with any SOAP service (tested with multiple public APIs)

## [1.1.0] - 2026-09-05

### Planned for v1.0.0
- SOAP 1.2 support
- Enhanced WS-Security features
- Performance optimizations
- Additional server examples
- Binary attachment support (MTOM)
- Advanced WS-* standards support

---

**Note**: This library went from concept to full-featured SOAP ecosystem in record time, 
delivering both client and server capabilities that were originally planned across multiple phases.