My current plan for Savon 2.x and eventually 3.0

[rubiii]

Hey. I need to get this out of my head. If you discovered this, you're very welcome to provide feedback.

Savon has been around for a long time, and if you run it in production today, chances are you are not on the latest version. I would like to change that.

The goal for 2.x

Every 2.x release is strictly safe to upgrade to.

• Public APIs only get fixed or extended.
  If it worked in 2.12.1, it works in every 2.x release. Nothing gets removed or renamed.
• Soft deprecations only.
  You might see a warning nudging you toward a newer API. The old one keeps working until 3.0.
• New behavior is opt-in.
  If you don't set a new option, Savon behaves exactly as before. The only default-on changes are fixes for behavior that is plainly broken. Anything defensible stays as it is, and the correct behavior becomes something you opt into.

Recent releases already work this way. 2.16 restored APIs that broke between 2.13 and 2.15, 2.17 introduced an optional Faraday-based transport that was planned for 3.0 as an opt-in feature while HTTPI remains the default, and 2.17.1–2.17.4 fixed regressions without touching any defaults. Check out the CHANGELOG to see what already happened.

Companion gems

Savon is really a stack. Nori parses responses, Gyoku builds request XML, Wasabi reads WSDLs, Akami handles WS-Security, HTTPI does transport. I'm treating these pretty much the same, keeping backward compatibility and adding new feature only via opt-in. For example, Nori 2.8.0 just shipped a :standards option that makes parsing follow the XML spec more closely.

Opting into the future

All those opt-in options add up, and nobody wants to hunt down twelve flags across six gems. So the plan is one switch in Savon:

Savon.client(wsdl: "...", future: true)

future: true means give me the next major version's defaults, today. It turns on everything that will become default in the next major version. The Faraday transport, spec-correct parsing, serializable response values, and whatever joins later.

This flag is the one documented exception to the safe-upgrade goal. It's a preview channel and its behavior grows with minor releases, and each release's changelog will list what joined under a dedicated heading. There are deliberately no per-feature opt-outs on it. If something under future: true breaks your integration, please report any issues so we can fix them instead of adding more workarounds. Your feedback really helps.

What 3.0 will look like

The idea for 3.0 is to flip the future defaults on for everyone and remove what 2.x soft-deprecated. If your suite is green on the last 2.x release with future: true, upgrading to 3.0 should be a non-event. You choose when to do the work, one flag at a time or all at once, on a version you can roll back.

cc @olleolleolle @pcai

[rubiii]

I released Nori 2.8.0 and 2.9.0. Two things relevant to this plan:

• Added a :serializable option.
  Values become plain, directly-serializable data as suggested in Add ability to return XML node attributes as hash, not as object property nori#106. Closes the long-standing Nori::StringWithAttributes should implement #as_json nori#99, Add Nori::StringWithAttributes#as_json nori#100, Add ability to return XML node attributes as hash, not as object property nori#106, Attributes not always included in final hash nori#107 cluster of issues.
• Added a :standards option.
  With this, Nori no longer applies schema-less typing. No more bare type=/nil= magic or guessing dates and booleans from string shape. Typing belongs to a schema-aware layer, which is where Savon comes in at some point.

Both opt-in, defaults untouched. These are the kind of behaviors future: true will bundle once it lands in Savon.
Check out the Nori changelog and readme for more details.

[rubiii]

Pushed a PR for the future: true option: #1061
Going to leave that open for a few days and come back to it.
I appreciate your feedback!

[md5]

I'm glad to see some movement on this since there are some rough spots that we had to work around in savon when we implemented the functionality that uses it a few years ago that can likely be smoothed out as things are improved here.

My one concern is that since that integration on our side has mostly been "just running" for years and the more conservative approach represented by not turning on future: true is probably part of that stability, I'm not sure I'd be comfortable with our ability to adequately test whether minor version upgrades were breaking things. Most of this is attributable to the fact that testing the SOAP integrations is difficult outside of interacting with the actual SOAP services we're calling, since it's difficult to adequately mock the full range of responses we could get from the server in our specs.

In our case, I would prefer to just be able to set standards: true in our savon/nori configuration, but if setting future: true is the only way to opt into that before 3.0 is released I can probably convince myself to do that.

[rubiii]

Thanks for your feedback! Ensuring those integrations still work is a very valid concern and I'll see if we can improve on that.

[md5]

I'd probably just have savon take a nori or parsing key in its config and delegate what options are allowed to nori. I could see it making sense to still have a future key and delegating that to the other gems as well.

So you could do either:

savon = Savon.client(
  wsdl:,
  future: true
)

Or:

savon = Savon.client(
  wsdl:,
  parsing: { future: true }
)

Passing future to the top-level config would pass it to all the underlying gems that supported a future key.

In my case, before upgrading to Savon 3, I could do this:

savon = Savon.client(
  wsdl:,
  parsing: { standards: true }
)