savon 2.16.0 → 2.17.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 31b29512f6e1e259e34f95ef7cc0d38dd9ac8911d0b1307ca05bf69736985cbb
-  data.tar.gz: 3ae386e5a8ade343d99e7dc10d644499cf5315fc51d058a8e3f7cb103ad25872
+  metadata.gz: 2bba4a9ced6c62286d20de586b56ce7263413fa5e4b51771e87fded4c2433f39
+  data.tar.gz: 9327a65ee629c258691084a822b635738b4d31ea38c5bd38f8e3399f11b16cd9
 SHA512:
-  metadata.gz: e18a7a8ee40adfab9ab7e316abce340251ef30ad93dd50348640488a282aa5a462d16b46fd987414747c4efe76a04b68ec3e0e50d95de77ac331c4a630549182
-  data.tar.gz: 686fc36d67eb071a75ce201d16ec4ba3be443c23c48db90f87ee3bece8d76f05f81768acbc182fa32ffbf1623d022d9ca3b23871aa68c8b86c6ca6bd82df049a
+  metadata.gz: a1d50a4b5f588cc1e094189f41aada85a2bbecf7b6dbf92b27c6041d7b3eb882808ec69c0d2f0e907cc572cea73c17bad18f82d74c400e4019836200ce1255e9
+  data.tar.gz: 9a61b3a21ae8a2c16761fb851c85355cd3e2575e540447ec7ac0fa5cbd42ae5bfa456c26813a5dce907fb9924f2cd6dece545f841f65a970a87445123fe90005

data/CHANGELOG.md

@@ -1,17 +1,113 @@
 # Savon changelog
 
-## 2.16.0 (2026-05-18)
+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.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [2.17.4] - 2026-07-03
+
+**Restore WS-Addressing headers and fix `:wsse_signature` resolution**
+
+### Fixed
+
+* **WS-Addressing headers are populated from the WSDL again** ([#1057](https://github.com/savonrb/savon/issues/1057)). With `use_wsa_headers: true` and no explicit `:soap_action` or `:endpoint`, Savon emitted empty `<wsa:Action xsi:nil="true"/>` and `<wsa:To xsi:nil="true"/>` elements instead of the operation's SOAPAction and service endpoint. Up to 2.16.0 those values were populated as a side effect of building the HTTP request. The 2.17.0 transport refactor removed that step.
+* **A global `:host` override no longer rewrites the WSDL's endpoint.** Resolving the request endpoint with `:host` set replaced host and port of the parsed WSDL address in place, visible as a permanently changed `client.wsdl.endpoint` after the first call. Endpoint and SOAPAction resolution moved into `Savon::EffectiveOptions`, which applies the override to a copy and never touches the WSDL document.
+* **A local `:wsse_signature` no longer crashes when set to `false`.** Passing `wsse_signature: false` to a call raised `NoMethodError: undefined method 'have_document?' for false` while building the WSSE header. The envelope builder and the SOAP header also resolved the option with different rules, so they could disagree on which signature applies. Both now read it through `Savon::EffectiveOptions`, the one place that resolves options settable in both the global and the local scope. A falsy local `:wsse_signature` falls back to the global one. Setting a signature object in either scope is unaffected.
+
+### Deprecated
+
+* **`Savon::Builder::WSA_NAMESPACE`.** WS-Addressing emission moved into `Savon::Addressing`, which owns the namespace as `Savon::Addressing::NAMESPACE`. The constant on `Savon::Builder` stays available as an alias and will be removed in Savon 3.
+
+## [2.17.3] - 2026-06-23
+
+**Fix Savon::HTTPError compatibility with Faraday transport**
+
+### Fixed
+
+* **`Savon::HTTPError` works with the Faraday transport** ([#1050](https://github.com/savonrb/savon/issues/1050)). When a the WSDL could not be fetched under `transport: :faraday`, `Savon::HTTPError#to_s` and `#to_hash` raised `NoMethodError: undefined method 'code'` because they were handed a raw `Faraday::Response`, which exposes `#status` rather than `#code`. Transports now normalize adapter-specific response objects into `Savon::Transport::Response` before they reach `Savon::HTTPError`.
+
+## [2.17.2] - 2026-06-10
+
+**Fix CVE-2026-53510 and restore 2.17.0 cookie regressions**
+
+### Fixed
+
+* **Fix CVE-2026-53510** `Savon::Model` generated SOAP operation methods by interpolating operation names into Ruby source passed to `module_eval`. An attacker who can control the operation names of a WSDL, can inject Ruby code that executes in the application process. This affects only the `.all_operations` class method provided by `Savon::Model` to automatically register all operations provided by the WSDL. Configuring `Savon::Model` with trusted operation names via `.operations` is safe. Thanks to @connorshea for securely disclosing this, providing a proof and a great report.
+* **`:cookies` request option works again.** The 2.17.0 transport refactor reimplemented cookie handling on top of `Array#map`, which broke callers passing an object that responds to `#cookies` and lost cookie-name de-duplication via `HTTPI::CookieStore`. The HTTPI transport delegates to `HTTPI::Request#set_cookies` again, restoring both shapes.
+* **`response.http.cookies` works again.** 2.17.0's `Savon::Transport::Response` only exposed `code`, `headers`, and `body`. The HTTPI transport now returns `Array<HTTPI::Cookie>` (matching 2.12.1). The Faraday transport returns `Hash<String, String>` so Faraday callers do not need HTTPI types.
+* **`:attachments` now works with a user-supplied `:xml` envelope** ([#761](https://github.com/savonrb/savon/pull/761)). Multipart support shipped in 2.13.0 but only wrapped envelopes Savon built itself. When a caller passed their own `:xml`, attachments were silently dropped.
+
+### Added
+
+* **Faraday `:cookies` option accepts a `String` or `Hash`.** Strings are used verbatim, Hashes are formatted as `"name=value; name=value"`. Round-trippable with the Faraday response shape.
+* **Three Nori response-parsing options exposed as Savon globals:** `:empty_tag_value` (default `nil`), `:convert_dashes_to_underscores` (default `true`), and `:scrub_xml` (default `true`). Defaults match Nori's own for backwards compatibility.
+
+### Changed
+
+* **Minimum Nori version is now `~> 2.7`** (was `~> 2.4`). Needed for the new parsing options (`:empty_tag_value` arrived in Nori 2.6.0, `:scrub_xml` in 2.7.0). The 2.5–2.7 series also brings fixes callers benefit from automatically: invalid byte sequences parse instead of raising, REXML no longer turns `&lt;` inside CDATA into `<`, `xs:date`/`xs:time`/`xs:dateTime` typecasting was corrected, and Nori stopped monkey-patching `String` and `Object`.
+* **Faraday migration hints are now value-aware and verified.** Each hint prints the caller's actual option value and spells out the full gem/require/setup where needed. Fixed several incorrect examples and added tests to verify every hint.
+
+### Deprecated
+
+* Deprecated the global and local `:multipart` options. They have been no-ops since v2.13.0. Specifically since commit 4e7ae5e. Savon detects multipart responses by checking the `Content-Type` header.
+
+## [2.17.1] - 2026-05-21
+
+### Fixed
+
+* [#1008](https://github.com/savonrb/savon/pull/1008) - The HTTPI and Faraday transports no longer set an explicit `Content-Length` request header. The underlying HTTP library already computes it from the body. Sending it as well produced a duplicate header on adapters that do not deduplicate (e.g. httpclient), which some servers reject.
+* Requests using `attachments` were sent with a plain `text/xml` Content-Type instead of `multipart/related`. The 2.17.0 transport refactor assembled the request headers before the multipart body was built, leaving `Builder#multipart` empty at header time, so servers received a multipart body labelled as plain XML. 2.16.x and earlier are unaffected.
+
+## [2.17.0] - 2026-05-19
+
+**Add opt-in Faraday transport**
+
+Callers who set `transport: :faraday` get a memoized `Faraday::Connection` via `client.faraday` and full control over middleware, SSL, auth, and timeouts. Callers who do not set this option see no behavior change. HTTPI remains the default for 2.x.
+
+### Added
+
+* `transport: :faraday` global option. Defaults to `:httpi` (#992).
+* `client.faraday` returns a memoized `Faraday::Connection` for configuring middleware, SSL, auth, and timeouts when using the Faraday transport.
+* `Savon.client` raises if `transport: :faraday` is set but the faraday gem is not installed, or if any httpi-specific global option (`proxy`, timeouts, `ssl`, auth, `adapter`) is set alongside it. All conflicts are reported with their Faraday equivalents.
+
+### Changed
+
+* Observers must return `Savon::Transport::Response` (or `nil`) instead of `HTTPI::Response`.
+
+### Deprecated
+
+* The HTTPI transport (currently the default) and all HTTPI-specific global options enumerated in `Savon::FaradayMigrationHint::OPTIONS` (`proxy`, `open_timeout`, `read_timeout`, `write_timeout`, the `ssl_*` family, `basic_auth`, `digest_auth`, `ntlm`, `follow_redirects`, `adapter`) will be removed in 3.0. Migrate to `transport: :faraday`. `FaradayMigrationHint` shows the Faraday equivalent for each option.
+* Returning `HTTPI::Response` from observers emits a deprecation warning and will be removed in 3.0. Return `Savon::Transport::Response` instead.
+
+The Faraday transport unblocks:
+
+* redirect following for WSDL fetches via `faraday-follow-redirects` middleware (#1033, savonrb/wasabi#18)
+* digest authentication via `faraday-digestauth` middleware (#1021, savonrb/httpi#250)
+* proxy authentication with special characters in passwords (#941)
+* and setting an `Accept` header for WSDL requests from Rails apps (savonrb/wasabi#115)
+
+## [2.16.0] - 2026-05-18
 
 **Restore compatibility**
 
 If you stayed on 2.12.1 because a later version broke something, this release is for you. The fixes below target the most commonly reported upgrade blockers. Existing code should work without modification.
 
-* Fix: Restore `Savon::Response#hash` removed in 2.14.0 (#985). Callers on 2.12.1 that use `response.hash` get the soap body back instead of Ruby's integer object id. A deprecation warning is emitted on each call. Use `#full_hash` going forward.
-* Fix: Require wasabi >= 5.1.0 (#1015, #1016). Wasabi 4.x used message names as soap body element names and SOAPAction header values instead of operation names (savonrb/wasabi#122), causing servers to return a fault or reject the action for operations whose message name carried an `In` suffix.
-* Fix: Stop dumping all WSDL namespaces into every soap envelope (#1014, #942). 2.13.0 injected every namespace from the entire WSDL document into each request, including structural ones that have no place in a request body. Strict servers reject envelopes with unexpected or duplicate declarations.
-* Fix: Raise a proper `SOAPFault` instead of a raw exception when `soap:Fault` contains invalid encoding (#923).
-* Fix: `SOAPFault.present?` was ignoring its `xml` argument and always operating on the instance's own body.
-* Change: Added Ruby 3.4 (#1024) and Ruby 4.0 (#1039) to the CI test matrix.
+### Fixed
+
+* Restore `Savon::Response#hash` removed in 2.14.0 (#985). Callers on 2.12.1 that use `response.hash` get the soap body back instead of Ruby's integer object id.
+* Require wasabi >= 5.1.0 (#1015, #1016). Wasabi 4.x used message names as soap body element names and SOAPAction header values instead of operation names (savonrb/wasabi#122), causing servers to return a fault or reject the action for operations whose message name carried an `In` suffix.
+* Stop dumping all WSDL namespaces into every soap envelope (#1014, #942). 2.13.0 injected every namespace from the entire WSDL document into each request, including structural ones that have no place in a request body. Strict servers reject envelopes with unexpected or duplicate declarations.
+* Raise a proper `SOAPFault` instead of a raw exception when `soap:Fault` contains invalid encoding (#923).
+* `SOAPFault.present?` was ignoring its `xml` argument and always operating on the instance's own body.
+
+### Changed
+
+* Added Ruby 3.4 (#1024) and Ruby 4.0 (#1039) to the CI test matrix.
+
+### Deprecated
+
+* `Savon::Response#hash` emits a deprecation warning on each call. Use `#full_hash` going forward. Will be removed in 3.0.
 
 ## 2.15.1 (2024-07-08)
 
@@ -1165,3 +1261,10 @@ Pay attention to the following list and read the updated Wiki: http://wiki.githu
 ## 0.5.0 (2009-11-29)
 
 * Complete rewrite and public release.
+
+[2.17.4]: https://github.com/savonrb/savon/compare/v2.17.3...v2.17.4
+[2.17.3]: https://github.com/savonrb/savon/compare/v2.17.2...v2.17.3
+[2.17.2]: https://github.com/savonrb/savon/compare/v2.17.1...v2.17.2
+[2.17.1]: https://github.com/savonrb/savon/compare/v2.17.0...v2.17.1
+[2.17.0]: https://github.com/savonrb/savon/compare/v2.16.0...v2.17.0
+[2.16.0]: https://github.com/savonrb/savon/compare/v2.15.1...v2.16.0

data/README.md

@@ -2,82 +2,88 @@
 
 Heavy metal SOAP client
 
-[Documentation](https://www.rubydoc.info/gems/savon/) | [Support](https://stackoverflow.com/questions/tagged/savon) |
-[Mailing list](https://groups.google.com/forum/#!forum/savonrb)
-
 [![Ruby](https://github.com/savonrb/savon/actions/workflows/ci.yml/badge.svg)](https://github.com/savonrb/savon/actions/workflows/ci.yml)
 [![Gem Version](https://badge.fury.io/rb/savon.svg)](http://badge.fury.io/rb/savon)
 [![Coverage Status](https://coveralls.io/repos/savonrb/savon/badge.svg)](https://coveralls.io/r/savonrb/savon)
 
+Savon is a SOAP client for Ruby. [SOAP is the protocol](https://www.w3.org/TR/soap/) spoken by many enterprise systems. When they hand you a WSDL URL or file instead of a REST spec, it's SOAP. Savon reads the WSDL, maps available operations to Ruby symbols, converts Ruby hashes to SOAP envelopes and turns XML responses into hashes you can work with.
 
-## Installation
-
-Savon is available through [Rubygems](http://rubygems.org/gems/savon) and can be installed via:
-
-```
-$ gem install savon
-```
+Full documentation is at [savonrb.com](https://savonrb.com).
 
-or add it to your Gemfile like this:
+## Installation
 
-```
-gem 'savon', '~> 2.15.0'
+```ruby
+gem 'savon', '~> 2.17'
 ```
 
-## Usage example
+## Usage
 
-``` ruby
+```ruby
 require 'savon'
 
-# create a client for the service
-client = Savon.client(wsdl: 'http://service.example.com?wsdl')
-
-# or: create a client with a wsdl provided as a string
-client = Savon.client do |config|
-  wsdl_content = File.read("/path/to/wsdl")
-  config.wsdl wsdl_content
-end
+# Point Savon to a local or remote WSDL document
+client = Savon.client(wsdl: 'https://service.example.com?wsdl')
 
+# See what the service exposes
 client.operations
-# => [:find_user, :list_users]
+# => [:find_user, :create_user]
 
-# call the 'findUser' operation
+# Make a request and work with the response
 response = client.call(:find_user, message: { id: 42 })
+response.body[:find_user_response]
+# => { id: 42, name: "Hoff" }
 
-response.body
-# => { find_user_response: { id: 42, name: 'Hoff' } }
+# Savon raises a Savon::SOAPFault when the server returns a SOAP fault
+rescue Savon::SOAPFault => e
+  puts e.to_hash.dig(:fault, :faultstring)
 ```
 
-For more examples, you should check out the
-[integration tests](https://github.com/savonrb/savon/tree/version2/spec/integration).
+Enable logging to see the raw SOAP envelopes. That's probably the single most useful thing while getting a new integration working:
 
-## Ruby version support
+```ruby
+client = Savon.client(
+  wsdl: 'https://service.example.com?wsdl',
+  pretty_print_xml: true,
+  log: true
+)
+```
 
-Every savon release is tested with contemporary supported versions of ruby. Historical compatibility information:
+### Authentication
 
-* `main` - same support as Ruby
-* 2.15.x - MRI 3.0, 3.1, 3.2, 3.3
-* 2.13.x, 2.14.x - MRI 2.7, 3.0, 3.1
-* 2.12.x - MRI 2.2, 2.3, 2.4, 2.5
-* 2.11.x - MRI 2.0, 2.1, 2.2, and 2.3
+Most enterprise services require authentication. Common options:
 
-If you are running MRI 1.8.7, try a 2.6.x release.
+```ruby
+# HTTP basic auth
+Savon.client(wsdl: '...', basic_auth: ['user', 'secret'])
 
-Most changes are not backported to older versions of savon, or unsupported ruby versions.
+# WS-Security (WSSE)
+Savon.client(wsdl: '...', wsse_auth: ['user', 'secret', :digest], wsse_timestamp: true)
+```
 
-## Running tests
+See [Authentication](https://savonrb.com/version2/globals.html) on the website for HTTP digest, NTLM, and certificate-based options.
 
-```bash
-$ bundle install
-$ bundle exec rspec
-```
+### Transport
+
+Savon uses [HTTPI](https://github.com/savonrb/httpi) for HTTP by default. Since v2.17.0 you can opt-in to use Faraday by passing `transport: :faraday` which exposes the Faraday connection at `client.faraday` for you to configure. Savon is only adding some SOAP-specifics on top.
+
+## Ruby support
+
+Savon 2.x requires Ruby >= 3.0.0, kept as the lower bound for backward compatibility. Note that Ruby 3.0–3.3 are EOL or security-only. Ruby 3.4+ is the minimum version with active maintenance.
+
+## Versioning & stability
+
+Savon follows [Semantic Versioning 2.0.0](https://semver.org/spec/v2.0.0.html). The changelog format is [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+**The 2.x line is anchored on 2.12.1.** Every 2.x release is supposed to be safe to upgrade to from 2.12.1, and anything that worked in 2.12.1 keeps working. We do not remove or rename public APIs in the 2.x line. New behavior is opt-in and requires an explicit option change. If you found a problem with that, please let us know.
+
+We only soft-deprecate APIs we plan to remove. The `Deprecated` sections of the [changelog](CHANGELOG.md) list every API that is planned to be removed with version 3.0.
 
-## FAQ
+Callers on 2.13.0–2.15.x may see specific post-2.12.1 behaviors restored to the 2.12.1 contract. This is intentional.
 
-* URI::InvalidURIError -- if you see this error, then it is likely that the http client you are using cannot parse the URI for your WSDL. Try `gem install httpclient` or add it to your `Gemfile`.
-  - See https://github.com/savonrb/savon/issues/488 for more info
+## Known limitations
 
+**WSDL imports are not followed.** Savon parses only the root WSDL document via [Wasabi](https://github.com/savonrb/wasabi). Messages, port types, and bindings defined in imported files are invisible to Savon. If you control the WSDL, merge the imported elements into the root document and pass that to Savon as a string. If you need full import support, the [WSDL](https://rubygems.org/gems/wsdl) gem is an alternative.
 
-## Documentation
+## Contributing
 
-Please be sure to [read the documentation](https://www.rubydoc.info/github/savonrb/savon/).
+See [CONTRIBUTING.md](CONTRIBUTING.md). MIT licensed.

data/Rakefile

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require "bundler/gem_tasks"
 require "rspec/core/rake_task"
 
@@ -10,5 +12,7 @@ RSpec::Core::RakeTask.new "spec:integration" do |t|
   t.pattern = "spec/integration/**/*_spec.rb"
 end
 
-task :default => :spec
-task :test => :spec
+desc "Alias for spec task"
+task test: :spec
+
+task default: :spec

data/lib/savon/addressing.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require "gyoku"
+require "securerandom"
+
+module Savon
+  # Emits the WS-Addressing message addressing properties of a request
+  # (WS-Addressing 1.0 - Core §3.2): +wsa:Action+, +wsa:To+ and +wsa:MessageID+.
+  #
+  # This object owns everything Savon knows about WS-Addressing: the namespace,
+  # whether the headers are emitted at all, and how the resolved SOAPAction and
+  # endpoint map onto the addressing properties. It works on plain values.
+  # {Savon::Header} resolves them via {Savon::EffectiveOptions} and constructs
+  # this object, keeping option resolution and WSA emission separate.
+  class Addressing
+    # The WS-Addressing 1.0 namespace,
+    # https://www.w3.org/TR/ws-addr-core/#namespaces.
+    NAMESPACE = "http://www.w3.org/2005/08/addressing"
+
+    # @param enabled [Object] whether the headers are emitted, any truthy value
+    #   counts (the +:use_wsa_headers+ global)
+    # @param action [String, nil] the resolved SOAPAction, emitted as
+    #   +wsa:Action+, or +nil+ when the caller disabled it
+    # @param to [URI, String, nil] the resolved endpoint, emitted as +wsa:To+
+    def initialize(enabled:, action: nil, to: nil)
+      @enabled = enabled
+      @action  = action
+      @to      = to
+    end
+
+    # @return [Boolean] whether the WS-Addressing headers are emitted
+    def enabled?
+      !!@enabled
+    end
+
+    # Returns the namespace declaration the enclosing Header element needs.
+    # The +wsa+ prefix is declared once on the Header, not on each child.
+    #
+    # @return [Hash{String => String}] +{"xmlns:wsa" => NAMESPACE}+, or an
+    #   empty Hash when disabled
+    def namespace_attributes
+      enabled? ? { "xmlns:wsa" => NAMESPACE } : {}
+    end
+
+    # Renders the three addressing properties, each rendering with a freshly
+    # generated +wsa:MessageID+. A +nil+ action or destination is emitted as
+    # an +xsi:nil+ element rather than being dropped.
+    #
+    # @return [String] the header elements, or an empty String when disabled
+    def to_xml
+      return "" unless enabled?
+
+      Gyoku.xml(
+        "wsa:Action"    => @action,
+        "wsa:To"        => @to,
+        "wsa:MessageID" => "urn:uuid:#{SecureRandom.uuid}"
+      )
+    end
+  end
+end

data/lib/savon/block_interface.rb

@@ -1,16 +1,16 @@
 # frozen_string_literal: true
+
 module Savon
   class BlockInterface
-
     def initialize(target)
       @target = target
     end
 
     def evaluate(block)
-      if block.arity > 0
+      if block.arity.positive?
         block.call(@target)
       else
-        @original = eval("self", block.binding)
+        @original = eval("self", block.binding, __FILE__, __LINE__)
         instance_eval(&block)
       end
     end
@@ -22,6 +22,5 @@ module Savon
     rescue NoMethodError
       @original.send(method, *args, &block)
     end
-
   end
 end

data/lib/savon/builder.rb

@@ -1,40 +1,59 @@
 # frozen_string_literal: true
+
+require "savon/addressing"
 require "savon/header"
 require "savon/message"
+require "savon/effective_options"
 require "nokogiri"
 require "builder"
 require "gyoku"
 
 module Savon
+  # Builds the SOAP request for an operation: the XML envelope, or
+  # a multipart/related message when the request carries attachments
+  # (SOAP with Attachments, https://www.w3.org/TR/SOAP-attachments).
+  #
+  # It owns the envelope structure, its namespace declarations, and the body,
+  # and signs the document when a WSSE signature is present. Message-body
+  # serialization is delegated to {Savon::Message}, the Header element to
+  # {Savon::Header}, and Hash-to-XML conversion to Gyoku.
   class Builder
     attr_reader :multipart
 
     SCHEMA_TYPES = {
       "xmlns:xsd" => "http://www.w3.org/2001/XMLSchema",
       "xmlns:xsi" => "http://www.w3.org/2001/XMLSchema-instance"
-    }
+    }.freeze
 
     SOAP_NAMESPACE = {
       1 => "http://schemas.xmlsoap.org/soap/envelope/",
       2 => "http://www.w3.org/2003/05/soap-envelope"
-    }
+    }.freeze
 
-    WSA_NAMESPACE = "http://www.w3.org/2005/08/addressing"
+    # @deprecated Use {Savon::Addressing::NAMESPACE} instead. This alias will
+    #   be removed in Savon 3.0.
+    WSA_NAMESPACE = Addressing::NAMESPACE
 
+    # @param operation_name [Symbol] the SOAP operation being called
+    # @param wsdl [Wasabi::Document] the parsed WSDL, or an empty document when
+    #   the client was configured without one
+    # @param globals [Savon::GlobalOptions] client-level options
+    # @param locals [Savon::LocalOptions] per-request options
     def initialize(operation_name, wsdl, globals, locals)
       @operation_name = operation_name
 
       @wsdl      = wsdl
       @globals   = globals
       @locals    = locals
-      @signature = @locals[:wsse_signature] || @globals[:wsse_signature]
+      @effective = EffectiveOptions.new(operation_name, wsdl, globals, locals)
+      @signature = @effective.wsse_signature
 
       @types = convert_type_definitions_to_hash
       @used_namespaces = convert_type_namespaces_to_hash
     end
 
     def pretty
-      Nokogiri.XML(to_s).to_xml(:indent => 2)
+      Nokogiri.XML(to_s).to_xml(indent: 2)
     end
 
     def build_document
@@ -61,40 +80,50 @@ module Savon
       end
     end
 
+    # Returns the XML attributes of the envelope's Header element, provided
+    # by the header's sections.
+    #
+    # @return [Hash{String => String}]
     def header_attributes
-      @globals[:use_wsa_headers] ? { 'xmlns:wsa' => WSA_NAMESPACE } : {}
+      header.attributes
     end
 
     def body_attributes
       @body_attributes ||= @signature.nil? ? {} : @signature.body_attributes
     end
 
+    # Returns the request body as a String. When the caller supplies a pre-built
+    # envelope via the :xml local option it is used verbatim, but it must still
+    # be wrapped in a multipart message when :attachments are present.
+    # Otherwise the attachments are silently dropped.
     def to_s
-      return @locals[:xml] if @locals.include? :xml
-      build_document
+      if @locals.include?(:xml)
+        xml = @locals[:xml]
+        @locals[:attachments] ? build_multipart_message(xml) : xml
+      else
+        build_document
+      end
     end
 
     private
 
     def convert_type_definitions_to_hash
-      @wsdl.type_definitions.inject({}) do |memo, (path, type)|
+      @wsdl.type_definitions.each_with_object({}) do |(path, type), memo|
         memo[path] = type
-        memo
       end
     end
 
     def convert_type_namespaces_to_hash
-      @wsdl.type_namespaces.inject({}) do |memo, (path, uri)|
+      @wsdl.type_namespaces.each_with_object({}) do |(path, uri), memo|
         key, value = use_namespace(path, uri)
         memo[key] = value
-        memo
       end
     end
 
     def use_namespace(path, uri)
       @internal_namespace_count ||= 0
 
-      unless identifier = namespace_by_uri(uri)
+      unless (identifier = namespace_by_uri(uri))
         wsdl_identifier = @wsdl.document? ? @wsdl.parser.namespaces.key(uri) : nil
         # The prefix may already be taken by the target namespace or a user-supplied
         # :namespaces override - fall back to ins0, ins1... rather than overwriting it.
@@ -120,7 +149,7 @@ module Savon
           @globals[:namespace] || @wsdl.namespace
 
         # check env_namespace
-        namespaces["xmlns#{env_namespace && env_namespace != "" ? ":#{env_namespace}" : ''}"] =
+        namespaces["xmlns#{env_namespace && env_namespace != '' ? ":#{env_namespace}" : ''}"] =
           SOAP_NAMESPACE[@globals[:soap_version]]
 
         namespaces
@@ -132,13 +161,14 @@ module Savon
     end
 
     def header
-      @header ||= Header.new(@globals, @locals)
+      @header ||= Header.new(@globals, @effective)
     end
 
     def namespaced_message_tag
       tag_name = message_tag
-      return [tag_name] if @wsdl.document? and @wsdl.soap_input(@operation_name.to_sym).is_a?(Hash)
-      if namespace_identifier == nil
+      return [tag_name] if @wsdl.document? && @wsdl.soap_input(@operation_name.to_sym).is_a?(Hash)
+
+      if namespace_identifier.nil?
         [tag_name, message_attributes]
       elsif @used_namespaces[[tag_name.to_s]]
         [@used_namespaces[[tag_name.to_s]], tag_name, message_attributes]
@@ -156,6 +186,7 @@ module Savon
       message_tag = serialized_message_tag[1]
       @wsdl.soap_input(@operation_name.to_sym)[message_tag].each_pair do |message, type|
         break if @locals[:message].nil?
+
         message_locals = @locals[:message][StringUtils.snakecase(message).to_sym]
         message_content = Message.new(message_tag, namespace_identifier, @types, @used_namespaces, message_locals, :unqualified, @globals[:convert_request_keys_to], @globals[:unwrap]).to_s
         messages += "<#{message} xsi:type=\"#{type.join(':')}\">#{message_content}</#{message}>"
@@ -169,7 +200,7 @@ module Savon
       message_tag = wsdl_tag_name.keys.first if wsdl_tag_name.is_a?(Hash)
       message_tag ||= @locals[:message_tag]
       message_tag ||= wsdl_tag_name
-      message_tag ||= Gyoku.xml_tag(@operation_name, :key_converter => @globals[:convert_request_keys_to])
+      message_tag ||= Gyoku.xml_tag(@operation_name, key_converter: @globals[:convert_request_keys_to])
 
       message_tag.to_sym
     end
@@ -179,7 +210,7 @@ module Savon
     end
 
     def body_message
-      if @wsdl.document? and @wsdl.soap_input(@operation_name.to_sym).is_a?(Hash)
+      if @wsdl.document? && @wsdl.soap_input(@operation_name.to_sym).is_a?(Hash)
         serialized_messages
       else
         message.to_s
@@ -213,7 +244,7 @@ module Savon
 
     def builder
       builder = ::Builder::XmlMarkup.new
-      builder.instruct!(:xml, :encoding => @globals[:encoding])
+      builder.instruct!(:xml, encoding: @globals[:encoding])
       builder
     end
 
@@ -246,7 +277,7 @@ module Savon
 
       # the mail.body.encoded algorithm reorders the parts, default order is [ "text/plain", "text/enriched", "text/html" ]
       # should redefine the sort order, because the soap request xml should be the first
-      multipart_message.body.set_sort_order [ "text/xml" ]
+      multipart_message.body.set_sort_order ["text/xml"]
 
       multipart_message.body.encoded(multipart_message.content_transfer_encoding)
     end
@@ -261,10 +292,10 @@ module Savon
       end
       multipart_message.add_part xml_part
 
-      #request.headers["Content-Type"] = "multipart/related; boundary=\"#{multipart_message.body.boundary}\"; type=\"text/xml\"; start=\"#{xml_part.content_id}\""
+      # request.headers["Content-Type"] = "multipart/related; boundary=\"#{multipart_message.body.boundary}\"; type=\"text/xml\"; start=\"#{xml_part.content_id}\""
       @multipart = {
         multipart_boundary: multipart_message.body.boundary,
-        start: xml_part.content_id,
+        start: xml_part.content_id
       }
 
       multipart_message