Breaking changes coming to Adapters' use of custom sessions

[briantist]

Background

The Adapter system in Vault wraps HTTP calls, and by default handles creation of the Session object. As a result, Adapters accept some options for customizing how the session is created:

• verify
• cert
• proxies

Adapters also support passing in a session you've created on your own, allowing complete customization of the session object.

Problem

Because of the way we store some of the Adapter session options, and use them later in making requests, it's possible that if you created a session yourself, some of the options you chose in the session might be overridden by the option values set in the Adapter. This happens even if you didn't use the Adapter options and left them at their defaults. More info:

• Custom certificate verification fails with requests>=2.28.0 #991

What's changing

Ideally, if you passed a session into the adapter, we shouldn't be touching it: we trust that you created the session exactly as you wanted it to be. But this is an abrupt change and would lead to some unexpected changes around things like verifying certificates.

As a result, we're going to make a series of smaller breaking changes, starting with us inspecting a passed in session, and only allowing overriding of its properties if those things aren't set in the session:

• adapters: if session is user-supplied, do not overwrite session options with Client/Adapter options #1021

In the next major version after that, we'll look to remove that middle ground, and when a session object is passed in, we will ignore the other options completely and only use your passed in session.

Schedule

As of right now, the schedule looks like this:

• v2.0.0 -- when a passed in session sets verify, cert, or proxies, don't use the Adapter versions of those variables
  • adapters: if session is user-supplied, do not overwrite session options with Client/Adapter options #1021
• v3.0.0 -- we stop inspecting session, and values passed into verify, cert, or proxies are either ignored, or raise an exception when passed along with session, or may be removed from adapters entirely