wsdl 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b34bce8e0ddef018aacc3f2357687c4b7c1baea3e5ec8239709875f37944bd04
-  data.tar.gz: 1b645e59314af7de7ed7940fdd27390a4ea1ba421614fd6ae1b14f39f9385796
+  metadata.gz: 044e32ff942cf640331b3f1d46c0eb97671808f46b84bc7448c7da006f258e4b
+  data.tar.gz: d3d7195b2fa0a137563588ce73a7a2d3e1ce0c0d969737b063dbf50cccdc590d
 SHA512:
-  metadata.gz: 3665061539c5a1b4535a0967289e1c80d5b60f291cc852cd975e3548cb3fead7bc00534bdbd98e2dfe0138e23c00756b9bb659c9e0f4a724203c880bce10d57d
-  data.tar.gz: b15aadb1512d7f48ef7527843f3a07ec9baac43bbb7392bafe01b0b356247c0ffbe3b0b2a309091ab7803c0eef21d2d800a0480d4ba22ded9f1d45fb9f695710
+  metadata.gz: 63e158807c68530a300551f7731dea515a20abd40060d97e8fd2620c8b7d4fa6b5b611fb68aab440350631c86665dfb8c241f9f8f59c13568f61c728d9203b7c
+  data.tar.gz: 24da4db1155a9d0238559a3ba55c2aa64e2bfa3f395a00087f9a0742782a1827104a026ac1d9628eab921701db54bf33e90eabb9071186e0494afece704fb064

data/.gitignore

@@ -3,12 +3,13 @@
 yard_docs
 coverage
 .yardoc
-graph
+.claude/settings.local.json
 pkg
 *~
 *.rbc
 *.gem
-.rspec
 .bundle
 Gemfile.lock
 bin/
+tmp/
+docs/reference/specs

data/AGENTS.md

@@ -1,107 +1,35 @@
 # AGENTS.md
 
-WSDL toolkit for Ruby. Turn WSDL 1.1 documents into inspectable services and callable operations.
+WSDL toolkit for Ruby. Turn WSDL 1.1 documents into inspectable definitions and callable operations.
+
+## Priorities
+
+- **Developer happiness** — clear errors, good defaults, minimal configuration
+- **Code quality** — 100% YARD docs, 95%+ coverage, clean RuboCop, no shortcuts
+- **Security** — maintain and extend defenses (XXE, SSRF, XML Signature); never regress
+- **Specification compliance** — code must conform to W3C/OASIS specs; local copies in `docs/reference/specs/`, overview in `docs/reference/specifications.md`
+- **Automation** — build tools that verify correctness, enforce quality, and reduce manual work
+- **Performance** — the parser is designed for speed; measure before and after changes
 
 ## Getting Started
 
-```sh
-bundle install              # Install dependencies
-bundle exec rspec           # Run tests
-bundle exec rubocop         # Run linter
-bundle exec rake ci         # Run all checks (CI task)
-bundle exec rake benchmark  # Run performance benchmarks
-bundle exec yard            # Generate YARD documentation
-```
+@docs/contributing/development.md
 
 ## Key Concepts
 
-- **Client** — Main entry point (`lib/wsdl/client.rb`)
+- **Definition** — Frozen IR of a parsed WSDL service (`lib/wsdl/definition.rb`). Created by `WSDL.parse`, serialized by `WSDL.dump`, restored by `WSDL.load`. Provides discovery, introspection, provenance, and serialization. Everything downstream operates on the Definition.
+- **Client** — Wraps a Definition with an HTTP client for calling operations (`lib/wsdl/client.rb`)
 - **Operation** — Callable SOAP operation with body, headers, and security
-- **Parser** — Parses WSDL and XSD documents
+- **Parser** — Parses WSDL and XSD documents into intermediate structures consumed by the Definition Builder
 - **Request DSL + Serializer** — `operation.prepare { ... }` builds a `Request::Envelope` and `WSDL::Request::Serializer` / `Operation#to_xml` produce SOAP XML
 - **Response** — Wraps SOAP responses with parsing and verification
 - **Security** — WS-Security implementation (see `docs/security/ws-security.md`)
 
-## Workflow Rules
-
-1. **Always make a plan first.** Propose a plan and wait for explicit confirmation before making changes.
-
-2. **Run quality checks after every code change.** Run `bundle exec rake ci` to ensure both RuboCop and RSpec pass. Never consider a task complete until CI is green. Let RuboCop autofix problems.
-
-3. **Follow the official specifications.** Code must conform to the W3C and OASIS specifications in `docs/reference/specifications.md`.
-
-4. **Update documentation after every change.** Check if YARD docs, `docs/` folder, `AGENTS.md`, or `README.md` need updates. Run `bundle exec yard` to verify.
+## Workflow
 
-## Code Style
-
-- Ruby 3.3+ with modern idioms (shorthand hash syntax, Data classes)
-- `# frozen_string_literal: true` at the top of every file
-- Single quotes for strings, 120 character max line length
-- Semantic blocks: `do...end` for side effects, `{...}` for return values
-- Readability comes first. When a linting rule conflicts with clear code:
-  1. Try refactoring — extract a method, simplify logic, etc.
-  2. If the code is already clean, add an inline `rubocop:disable` comment.
-  3. If inline disables accumulate for the same rule, relax it in `.rubocop.yml`.
-- Never degrade code quality (shorten docs, remove blank lines, merge logic) just to satisfy a metric.
+- **CI must pass before a task is complete.** Run `bundle exec rake ci` (lint + YARD audit + tests). RuboCop runs automatically on every file edit via a hook — let it autofix.
+- **When implementing protocol behavior**, consult the local spec docs in `docs/reference/specs/` and reference the relevant section.
 
 ## Testing
 
-- Every public method must be tested, 100% coverage is a must
-- Use existing fixtures in `spec/fixtures/` (45+ real-world WSDLs)
-- Unit tests in `spec/wsdl/` mirror `lib/wsdl/` structure
-- Integration tests in `spec/integration/`
-
-## Documentation
-
-- Complete YARD docs for all public methods (enforced by `rubocop-yard`)
-- Use proper YARD type syntax: `Hash{String => String}` not `Hash<String, String>`
-- Use the latest YARD version and features where possible; review updates in `https://rubydoc.info/gems/yard/file/docs/WhatsNew.md`
-- Detailed docs live in `docs/` folder; keep README brief
-
-## Error Handling
-
-Exception definitions and the current hierarchy are in `lib/wsdl/errors.rb` (source of truth).
-
-General guidance:
-
-- Use `WSDL::Error` for recoverable domain errors that callers may reasonably handle and continue from.
-- Use `WSDL::FatalError` for non-recoverable conditions, especially security violations or hard safety constraints that must not be ignored.
-- New custom exceptions should inherit from one of these two base classes and be defined in `lib/wsdl/errors.rb`.
-
-## Naming Conventions
-
-- Class/module names should match their role (`*Parser`, `*Validator`, `*Resolver`, `*Contract`, `*Policy`, `*Context`, `*Builder` when actually building structures).
-- Keep namespaces and file paths aligned (e.g., `WSDL::Parser::Result` in `lib/wsdl/parser/result.rb`).
-- Predicate methods: `?` suffix and boolean return values (e.g., `configured?`).
-- Bang methods: `!` suffix for strict/raising or state-changing variants (e.g., `validate!`, `verify!`, `seal!`).
-- Exception classes: `*Error` suffix and inheritance from `WSDL::Error` or `WSDL::FatalError`.
-- Avoid generic names like `Helper`, `Manager`, or `Utils` unless the scope is very narrow and explicit.
-
-## Security
-
-WS-Security docs: `docs/security/ws-security*.md`
-
-Key points:
-- Never log or expose private keys, passwords, or tokens
-- Use constants from `WSDL::Security::Constants` — never hardcode namespace URIs
-- SHA-256 is the default for X.509 signatures
-- UsernameToken digest uses SHA-1 (spec-mandated, not a bug)
-
-## Common Pitfalls
-
-- **XML Namespaces** — Use constants (`WSDL::NS::SOAP_1_1`, `WSDL::Security::Constants::NS::Security::WSSE`), never hardcode URIs
-- **WSDL Variability** — Test against multiple fixtures; don't assume consistent structure
-- **SOAP Versions** — 1.1 and 1.2 use different namespaces; the WSDL determines which to use
-- **Import Resolution** — Relative imports require a base location; see `UnresolvableImportError`
-
-## Quick Links
-
-| Resource | Path |
-|----------|------|
-| Main entry point | `lib/wsdl/client.rb` |
-| Error definitions | `lib/wsdl/errors.rb` |
-| Namespace constants | `lib/wsdl/ns.rb` |
-| Security constants | `lib/wsdl/security/constants.rb` |
-| WS-Security docs | `docs/security/ws-security.md` |
-| Specifications | `docs/reference/specifications.md` |
-| Benchmarks | `docs/reference/benchmarks.md` |
+Every public method must be tested, 100% coverage is a must. See [Testing docs](docs/contributing/testing.md) for test structure, fixtures, helpers, and coverage requirements.

data/CHANGELOG.md

@@ -1,6 +1,136 @@
 # Changelog
 
-## 1.0.0 — 2026-03-06
+All notable changes to this project will be documented in this file.
+
+## [1.1.0] — 2026-03-29
+
+**Upgrading?** See the [migration guide](#migrating-from-10) below.
+
+### Added
+
+- `WSDL.parse`, `WSDL.dump`, and `WSDL.load` entry points for explicit control over when fetching/parsing happens. `WSDL.parse` returns a frozen, serializable `Definition`. `WSDL.dump` serializes one to a hash. `WSDL.load` restores one from a cached hash.
+- `WSDL::Definition` — frozen intermediate representation of everything the library knows about a WSDL service. Provides discovery (`services`, `ports`, `operations`), introspection (`input`, `input_header`, `output`, `output_header`), DSL generation (`to_dsl`), provenance (`sources`, `fingerprint`), and serialization (`WSDL.dump`, `to_h`, `to_json`).
+- `Client.new` accepts a `Definition` as its first argument, skipping parsing entirely. All `Client` methods route through the `Definition`.
+- `Definition#verify!` raises `DefinitionError` if any operations could not be fully resolved. This is the opt-in strict check — parsing itself is always best-effort.
+- `Definition#build_issues` provides transparency into operations that could not be fully resolved, with error details for each.
+- `WSDL::DefinitionError` — raised by `Definition#verify!`, carries all build issues with `error.issues` for programmatic access.
+- Source provenance with SHA-256 content digests for every fetched document. Enables fingerprint-based change detection.
+- `Client#definition` accessor returns the `Definition` for the client's WSDL.
+- Operation overloading support per WSDL 1.1 §2.4.5. Same-named operations with different input/output messages are stored correctly and disambiguated via `client.operation(:Svc, :Port, :Op, input_name: :InputName)`. WS-I Basic Profile R2304 validation in strict mode raises `OperationOverloadError`.
+- `client.services` now includes an `operations` array for each port, listing all available operations. Overloaded operations include `input_name` for disambiguation.
+- Extract XML attributes from response elements into the parsed hash with `_`-prefixed keys (e.g., `transactionKey="TXN-123"` → `_transactionKey: "TXN-123"`). Attributes are type-coerced when schema metadata is available.
+- One-way operations (no `<output>` message) are now supported. Response contract returns empty elements and `output_style` returns `nil`.
+- `strictness:` provides granular control over 4 validation concerns: `schema_imports`, `schema_references`, `operation_overloading`, `request_validation`. Accepts a hash (`strictness: { schema_imports: false }`), boolean (`strictness: false`), or object.
+- All `ResourceLimitError` and strictness error messages now include copy-pasteable fix examples (e.g., `limits: { max_schemas: 51 }`, `strictness: { schema_imports: false }`).
+- `limits:` now accepts a hash shorthand (`limits: { max_schemas: 200 }`) in addition to a `Limits` object.
+- All 46 XSD built-in types are now explicitly handled by `TypeCoercer`. List types (`IDREFS`, `ENTITIES`, `NMTOKENS`) are now get coerced into arrays.
+- `xs:group` (model group) references are now resolved and their elements expanded, mirroring the existing `xs:attributeGroup` support.
+- `xs:list` simpleType derivation is now supported for both elements and attributes. List values are parsed by splitting on whitespace, with per-item type coercion based on the `itemType`. Built by joining array values with spaces.
+- `xs:union` simpleType derivation is now supported for both elements and attributes. The first `memberType` is used as the base type for coercion.
+- `Element#kind` returns `:simple`, `:complex`, or `:recursive` for programmatic dispatch. Included in both `paths` and `tree` contract output.
+- `Attribute#to_h` provides a consistent hash representation. Contract `paths` and `tree` now return identical attribute metadata including `name`, `type`, `required`, and `list`.
+- `operation.invoke { ... }` accepts an optional block, combining `prepare` and `invoke` into a single call.
+- `operation.to_xml(pretty: true)` for formatted XML output. Request XML is compact by default.
+- `Client` is thread-safe. Multiple threads can share a `Client` and create `Operation` instances concurrently.
+- Type coercion failures are now logged at debug level, making silent string fallbacks visible.
+
+### Changed
+
+- `Client.new` only accepts a `Definition` instance. Use `WSDL.parse(source)` to create one. Parse-time options (`strictness:`, `limits:`, `sandbox_paths:`) belong on `WSDL.parse`, runtime options (`strictness:`, `limits:`) on `Client.new`.
+- Removed built-in parse cache (`WSDL.cache`, `Cache` class, `cache:` parameter on `Client.new` and `WSDL.parse`). `Definition` is serializable via `WSDL.dump`/`to_h`/`to_json`/`from_h` — cache at the Definition level instead (file, Redis, etc.).
+- Nokogiri dependency relaxed from `~> 1.19, >= 1.19.1` to `>= 1.19.1` to allow Nokogiri 1.20+.
+- Removed `cache_key` contract from HTTP clients. Custom clients no longer need to implement `#cache_key`.
+- Removed `InvalidHTTPAdapterError` (was only used for `cache_key` validation).
+- `WSDL::HTTPAdapter` renamed to `WSDL::HTTP::Client`. Config, RedirectGuard, and Response moved into the `WSDL::HTTP` namespace. `WSDL.http_adapter` accessor renamed to `WSDL.http_client`.
+- `WSDL::HTTPResponse` renamed to `WSDL::HTTP::Response`.
+- Removed `WSDL.strictness` and `WSDL.limits` global setters. Pass `strictness:` and `limits:` as kwargs on `WSDL.parse` or `Client.new` instead. Defaults are sensible — no configuration needed for most use cases.
+- I/O concerns extracted from `Parser` into `WSDL::Resolver` namespace (`Resolver::Source`, `Resolver::Loader`, `Resolver::Importer`). Old `Source`, `Parser::Resolver`, and `Parser::Importer` classes removed.
+- Element tree building is always best-effort. Unresolvable types, missing elements, and resource limits are recorded as build issues rather than raising exceptions. Operations are included in the `Definition` with whatever data was successfully collected.
+- `BindingOperation#find_input_child_nodes` returns `[]` for missing `<input>` instead of raising.
+- `PortTypeOperation#input` returns `nil` for missing `<input>` (matching how `output` already handled missing `<output>`).
+- `MessageParts` records issues via an issues pipeline instead of raising for missing messages and header references.
+- `ElementBuilder` always uses lenient schema resolution (`find_*` instead of `fetch_*`) and records issues via the pipeline. Nesting depth and element/attribute count limits are recorded as resource limit issues.
+- Removed `format_xml` option from `Config`, `Client`, and `Operation`. Request XML is now always compact. Use `operation.to_xml(pretty: true)` when formatted output is needed.
+- `response.xml` replaces `response.raw`.
+- Removed `response.envelope_hash` (and `to_envelope_hash` alias) from the public API. Use `response.body` and `response.header` for schema-aware access, or `response.doc` for direct XML access.
+- Removed `response.xpath`. Use `response.doc.xpath` instead.
+
+### Removed
+
+- `strict_schema:` keyword on `Client.new` and `Config.new`. Use `strictness:` instead.
+
+### Fixed
+
+- RPC/literal responses now receive schema-aware type coercion. Previously, the RPC wrapper element prevented the parser from matching schema parts, so all values were returned as strings instead of typed Ruby objects (Integer, Date, BigDecimal, etc.).
+- Documents without a root XML element (empty files, binary content, truncated XML, non-XML responses from imports) now raise `WSDL::Error` instead of `NoMethodError`.
+- Binding operations missing a required `<input>` element now raise `WSDL::UnresolvedReferenceError` instead of `NoMethodError`.
+- Binding operations not found in the referenced portType now raise `WSDL::UnresolvedReferenceError` instead of `KeyError`.
+- Unknown XSD built-in types (e.g., `xsd:nonExistentType`) now raise `WSDL::UnresolvedReferenceError` in strict schema mode instead of being silently treated as simple types.
+- Overloaded operations no longer silently overwrite each other. Previously, the second definition just replaced the first.
+- Schema resolution now degrades gracefully when `schema_references` strictness is relaxed.
+- Integer type coercion no longer interprets leading zeros as octal (`"010"` → `10`, not `8`). XSD integers are strictly base-10 per §3.3.13.1.
+- Float/double coercion now handles XSD special values `INF`, `-INF`, and `NaN` per §3.2.4.1/§3.2.5.1.
+- `Verifier#find_element_by_id` now validates the ID format itself (defense-in-depth) instead of relying on callers to pre-validate, hardening against XPath injection.
+
+### Migrating from 1.0
+
+**Client initialization** now takes a `Definition` instead of a URL:
+
+```ruby
+# Before
+client = WSDL::Client.new("service.wsdl")
+
+# After
+definition = WSDL.parse("service.wsdl")
+client     = WSDL::Client.new(definition)
+```
+
+Parse-time options (`strictness:`, `limits:`, `sandbox_paths:`) go on `WSDL.parse`.
+
+**Caching** — the built-in cache is gone. Serialize Definitions instead:
+
+```ruby
+File.write("def.json", definition.to_json)
+definition = WSDL.load(JSON.parse(File.read("def.json")))
+```
+
+**Global setters removed** — pass `strictness:` and `limits:` as kwargs:
+
+```ruby
+# Before
+WSDL.strictness = false
+
+# After
+definition = WSDL.parse("service.wsdl", strictness: false)
+```
+
+**`strict_schema:` removed** — use `strictness:` with granular keys:
+
+```ruby
+WSDL.parse(url, strictness: { schema_imports: false, request_validation: false })
+```
+
+**HTTP namespace** changed:
+
+| Before | After |
+|---|---|
+| `WSDL::HTTPAdapter` | `WSDL::HTTP::Client` |
+| `WSDL::HTTPResponse` | `WSDL::HTTP::Response` |
+| `WSDL.http_adapter` | `WSDL.http_client` |
+
+**Response API** changed:
+
+| Before | After |
+|---|---|
+| `response.raw` | `response.xml` |
+| `response.envelope_hash` | `response.body` / `response.header` |
+| `response.xpath(expr)` | `response.doc.xpath(expr)` |
+
+**`format_xml` removed** — use `operation.to_xml(pretty: true)` instead.
+
+**Error handling** — parsing is now best-effort. Use `definition.build_issues` to inspect problems and `definition.verify!` to opt into strict validation.
+
+## [1.0.0] — 2026-03-06
 
 Initial public release.
 
@@ -17,7 +147,6 @@ Initial public release.
 
 - Full WSDL 1.1 parsing with recursive XSD import/include resolution
 - Strict and relaxed schema import modes for incomplete or malformed schemas
-- In-memory LRU cache with configurable TTL and max entries for parsed definitions
 - Sandbox path restrictions to prevent path traversal attacks
 - Configurable iteration limits for schema import cycles
 
@@ -61,7 +190,7 @@ Initial public release.
 
 ### HTTP
 
-- Stdlib `net/http` adapter with no external HTTP dependencies
+- Stdlib `net/http` client with no external HTTP dependencies
 - HTTPS-only by default with configurable TLS settings
 - Redirect following with SSRF-safe target validation
 - Transparent gzip decompression disabled to prevent gzip bomb attacks
@@ -72,10 +201,14 @@ Initial public release.
 - Global and per-client configuration with thread-safe defaults
 - 11 configurable resource limits (document size, schema count, nesting depth, and more)
 - Pluggable logger (defaults to silent `NullLogger`)
-- Pluggable HTTP adapter and cache implementations
+- Pluggable HTTP client
 
 ### Dependencies
 
 - **nokogiri** (>= 1.19.1) for XML parsing and C14N
 - **base64** for encoding/decoding
 - All cryptography delegated to Ruby's built-in **OpenSSL**
+
+[Unreleased]: https://github.com/rubiii/wsdl/compare/v1.1.0...HEAD
+[1.1.0]: https://github.com/rubiii/wsdl/compare/v1.0.0...v1.1.0
+[1.0.0]: https://github.com/rubiii/wsdl/releases/tag/v1.0.0

data/CONTRIBUTING.md

@@ -1,6 +1,6 @@
 # Contributing to WSDL
 
-Thanks for your interest in contributing! This guide covers everything you need to get started.
+Thanks for your interest in contributing!
 
 Please note that this project is released with a [Code of Conduct](CODE_OF_CONDUCT.md).
 By participating, you agree to abide by its terms.
@@ -13,85 +13,35 @@ and any relevant WSDL fixtures. You will receive a response within 48 hours.
 
 ## Getting Started
 
-Requirements:
-
-- Ruby 3.3+
-- Bundler
+Requirements: Ruby 3.3+ and Bundler.
 
 ```sh
 git clone https://github.com/rubiii/wsdl.git
 cd wsdl
 bundle install
-bundle exec rake ci   # Run all checks (RuboCop + RSpec)
-```
-
-Useful commands:
-
-```sh
-bundle exec rspec            # Run tests only
-bundle exec rake benchmark   # Run performance benchmarks
-bundle exec rubocop          # Run linter only
-bundle exec rubocop -a       # Autofix lint offenses
-bundle exec yard             # Generate YARD documentation
-bundle exec rake yard:audit  # Run yard audit only
+bundle exec rake ci   # Run all checks (Linting + Docs + Specs)
 ```
 
 ## How to Contribute
 
-### Bug Reports
-
-Open an [issue](https://github.com/rubiii/wsdl/issues) with:
-
-- A minimal WSDL fixture that reproduces the problem
-- The SOAP version (1.1 or 1.2) if relevant
-- Ruby version and `wsdl` gem version
-- Steps to reproduce and actual vs. expected behavior
-
-### Feature Requests
+**Bug reports** — Open an [issue](https://github.com/rubiii/wsdl/issues) with a minimal WSDL fixture that reproduces the problem, the SOAP version, Ruby version, and steps to reproduce.
 
-Open an issue to discuss the idea before writing code. This avoids wasted effort
-if the feature doesn't fit the project's scope.
+**Feature requests** — Open an issue to discuss the idea before writing code.
 
-### Bug Fixes
+**Bug fixes** — Write a failing test, fix the bug, run `bundle exec rake ci`.
 
-1. Write a failing test that demonstrates the bug
-2. Fix the bug
-3. Run `bundle exec rake ci` to verify everything passes
+**Documentation** — Improvements to YARD docs, the `docs/` folder, or the README are welcome.
 
-### Documentation
-
-Improvements to YARD docs, the `docs/` folder, or the README are always welcome.
-Run `bundle exec yard` to verify documentation compiles without warnings.
-
-## Pull Request Guidelines
+## Pull Requests
 
 1. Fork the repository and create a branch from `main`
 2. Keep each PR focused on a single concern
 3. Include tests for any behavior changes
-4. Ensure `bundle exec rake ci` passes (RSpec + RuboCop + YARD)
-5. Update documentation if your change affects the public API
-6. Write clear commit messages that explain *why*, not just *what*
-
-## Code Style
-
-The project uses RuboCop for style enforcement.
-See `.rubocop.yml` for the full configuration.
-
-## Testing
-
-- Test directory structure mirrors `lib/`: `spec/wsdl/` corresponds to `lib/wsdl/`
-- Integration tests live in `spec/integration/`
-- Use existing WSDL fixtures in `spec/fixtures/` (45+ real-world documents)
-- Add new fixtures when testing WSDL features not covered by existing ones
-- Every public method must be tested; the project targets 100% code coverage
-
-## Documentation
+4. Ensure `bundle exec rake ci` passes
+5. Write clear commit messages that explain *why*, not just *what*
 
-- All public methods require complete YARD docs (description, `@param`, `@return`)
-- Use proper YARD type syntax: `Hash{String => String}` not `Hash<String, String>`
-- Detailed guides live in the `docs/` folder; keep the README brief
+For code style, naming conventions, and other guidelines, see the [development guide](docs/contributing/development.md). For testing details, see the [testing docs](docs/contributing/testing.md).
 
 ## Getting Help
 
 Not sure where to start? Open an [issue](https://github.com/rubiii/wsdl/issues) and ask.
-We're happy to point you in the right direction.

data/Gemfile

@@ -12,18 +12,24 @@ gem 'benchmark' if RUBY_VERSION >= '3.4'
 # irb was removed from default gems in Ruby 4.0 (required by yard's legacy parser)
 gem 'irb' if RUBY_VERSION >= '4.0'
 
+# webrick was removed from default gems in Ruby 3.0
+gem 'webrick' if RUBY_VERSION >= '3.0'
+
 group :development do
   gem 'benchmark-ips', '~> 2.14', require: false
   gem 'equivalent-xml', '~> 0.6'
+  gem 'mutant-rspec', '~> 0.12', require: false
   gem 'rake', '~> 13.3'
   gem 'rantly', '~> 2.0', require: false
   gem 'redcarpet', require: false
   gem 'rspec', '~> 3'
+  gem 'rspec-github', '~> 2.4', require: false
   gem 'rubocop', require: false
   gem 'rubocop-rake', require: false
   gem 'rubocop-rspec', require: false
   gem 'rubocop-yard', require: false
   gem 'simplecov', '~> 0.22', require: false
+  gem 'stackprof', require: false
   gem 'webmock', '~> 3.24', require: false
   gem 'yard', require: false
   gem 'yard-markdown-relative-links', require: false

data/README.md

@@ -2,7 +2,7 @@
 
 [![CI](https://github.com/rubiii/wsdl/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/rubiii/wsdl/actions/workflows/ci.yml) [![Gem Version](https://img.shields.io/gem/v/wsdl)](https://rubygems.org/gems/wsdl)
 
-WSDL toolkit for Ruby. Parse WSDL 1.1 documents, inspect operation contracts, and execute SOAP calls.
+WSDL toolkit for Ruby. Turn WSDL 1.1 documents into inspectable definitions and callable operations.
 
 ## Installation
 
@@ -16,13 +16,23 @@ Or in `Gemfile`:
 gem 'wsdl'
 ```
 
+## Requirements
+
+- Ruby 3.3+
+- [Nokogiri](https://nokogiri.org/) >= 1.19.1 (installed automatically)
+
 ## Quickstart
 
 ```ruby
 require 'wsdl'
 
-# Parse a WSDL document
-client = WSDL::Client.new('http://example.com/service?wsdl')
+# Parse a WSDL and create a client
+definition = WSDL.parse('http://example.com/service?wsdl')
+client = WSDL::Client.new(definition)
+
+# The definition is serializable — cache it to skip re-parsing
+File.write('cache.json', definition.to_json)
+definition = WSDL.load(JSON.parse(File.read('cache.json')))
 
 # Discover available services, ports, and operations
 client.services     # => { "OrderService" => { ports: { "OrderPort" => { ... } } } }
@@ -49,30 +59,41 @@ puts operation.contract.request.body.template(mode: :minimal).to_dsl
 # end
 
 # Fill in the values and invoke the operation
-operation.prepare do
+response = operation.invoke do
   tag('GetOrder') do
     tag('orderId', 123)
   end
 end
-response = operation.invoke
 
 # Response body is automatically parsed with schema-aware type conversion
 response.body
 # => { "GetOrderResponse" => { "order" => { "id" => 123, "total" => 0.9999e2,
 #        "shipped" => true, "items" => [{ "name" => "Widget" }] } } }
 
+# Check for SOAP faults
+if response.fault?
+  fault = response.fault
+  puts "#{fault.code}: #{fault.reason}"   # => "soap:Server: Order not found"
+end
+
 # Access HTTP metadata and raw XML when needed
 response.http_status   # => 200
-response.raw           # => "<?xml version=\"1.0\" ...>"
+response.xml           # => "<?xml version=\"1.0\" ...>"
 ```
 
 ## Documentation
 
-See [Getting Started](docs/getting_started.md) for the documentation entrypoint and guide map.
+See [Getting Started](docs/getting_started.md) for the full guide map.
+
+- [Inspecting Services](docs/core/inspecting-services.md) — discover operations and inspect contracts
+- [Building Requests](docs/core/building-requests.md) — request DSL, headers, namespaces, templates
+- [Handling Responses](docs/core/handling-responses.md) — parsing, faults, security verification
+- [Configuration](docs/core/configuration.md) — strictness, limits, caching, HTTP client
+- [WS-Security](docs/security/ws-security.md) — UsernameToken, signatures, timestamps
+- [Error Reference](docs/reference/errors.md) — full error hierarchy and rescue patterns
 
 ## Features
 
-- **WSDL 1.1 Only** — WSDL 2.0 documents are detected and rejected with a clear error
 - **WSDL/XSD Parsing** — Full support for imports, includes, and multiple schema documents
 - **Service Discovery** — Inspect services, ports, and operations programmatically
 - **Contract Introspection** — Explore request/response structure with flat paths or tree views
@@ -82,6 +103,10 @@ See [Getting Started](docs/getting_started.md) for the documentation entrypoint
 - **Schema-Aware Parsing** — Type conversion and array handling based on XSD metadata
 - **Security Hardening** — DOCTYPE rejection, resource limits, and sandboxed file access
 
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines. Security issues: [SECURITY.md](SECURITY.md).
+
 ## License
 
 Released under the [MIT License](MIT-LICENSE).

data/Rakefile

@@ -6,7 +6,7 @@ require 'rubocop/rake_task'
 require 'yard'
 
 RSpec::Core::RakeTask.new
-RuboCop::RakeTask.new
+RuboCop::RakeTask.new('lint:ruby')
 YARD::Rake::YardocTask.new
 
 namespace :yard do
@@ -24,12 +24,77 @@ namespace :yard do
   end
 end
 
+namespace :lint do
+  desc 'Check markdown links point to existing files'
+  task :links do
+    require_relative 'scripts/lint_links'
+    LintLinks.check
+  end
+
+  desc 'Autofix RuboCop offenses (safe and unsafe)'
+  task fix: 'lint:ruby:autocorrect_all'
+end
+
 desc 'Run linting'
-task lint: :rubocop
+task lint: %i[lint:ruby lint:links]
+
+namespace :specifications do
+  desc 'Check if local specification documents are up to date'
+  task :check do
+    require_relative 'scripts/specifications'
+    abort unless Specifications.check
+  end
+
+  desc 'Download and convert all specification documents'
+  task :update do
+    require_relative 'scripts/specifications'
+    Specifications.update
+  end
+
+  desc 'Re-download and reconvert all specification documents'
+  task :reconvert do
+    require_relative 'scripts/specifications'
+    Specifications.update(force: true)
+  end
+end
 
 desc 'Run performance benchmarks'
 task :benchmark do
   ruby 'benchmarks/run.rb'
 end
 
+namespace :benchmark do
+  desc 'Run performance specs (allocation budgets + timing)'
+  task :specs do
+    sh 'bundle exec rspec spec/performance/ --format documentation'
+  end
+end
+
+namespace :profile do
+  modes = {
+    wall: 'Wall-time', cpu: 'CPU',
+    objects: 'Object allocation', all: 'All (wall + cpu + objects)'
+  }
+  modes.each do |mode, label|
+    desc "#{label} profile of large WSDL parse"
+    task(mode) { ruby "benchmarks/profile.rb #{mode}" }
+  end
+
+  desc 'Print a StackProf dump report'
+  task :report, [:dump] do |_t, args|
+    abort 'Usage: rake profile:report[path/to/dump]' unless args[:dump]
+    sh 'bundle', 'exec', 'stackprof', args[:dump], '--text', '--limit', '30'
+  end
+
+  desc 'Drill into a specific method in a StackProf dump'
+  task :method, [:dump, :method_name] do |_t, args|
+    abort 'Usage: rake profile:method[path/to/dump,ClassName#method]' unless args[:dump] && args[:method_name]
+    sh 'bundle', 'exec', 'stackprof', args[:dump], '--method', args[:method_name]
+  end
+end
+
 task ci: %i[lint yard:audit spec]
+
+task :default do
+  system 'rake -T'
+end