Help determine the future of hvac's Adapter system

[briantist]

While not thoroughly documented, hvac uses an "Adapter" system for the various API methods to interact with Vault's REST API:
https://hvac.readthedocs.io/en/stable/advanced_usage.html#custom-requests-http-adapter

The idea is that you can pass an instance of any compliant Adapter to the Client.

It defaults to an adapter called JSONAdapter, which is a subclass of RawAdapter (which uses requests).

In theory, you can create your own Adapters by subclassing either of the above, or directly subclassing the abstract Adapter base class.
https://hvac.readthedocs.io/en/stable/_modules/hvac/adapters.html

In practice, we've found that a number of assumptions are made in the API methods that do not make this as useful or flexible as it would seem.

---

I have a number of ideas in flight for changes and improvements to the Adapter system, but given the current state of things, it seems unlikely that we can do much of anything without making breaking changes in some places.

How you can help

hvac has no telemetry, and so we have very little insight into exactly how people use it.

I'm looking to get feedback on the Adapter system and how it's used by hvac's users, to help us determine the direction for library.

Please choose the poll option that most closely resembles an accurate response.

In addition to the poll, please take the opportunity to write below with details!

I'd love to know:

• how you're using adapters
• why you're using them / what problems they solve for you
• pain points in using them
• which adapters you use
• experiences in developing custom adapters if applicable
• anything else you want to share

Thank you!

[WilkenSteiner]

Hello! My use case: I maintain a library that uses hvac to make some API calls to Vault and applies some light logic on the results afterwards. The interface allows to inject a hvac.Client, but I have constraints on how the API calls are made. In the current version, the adapter owns the connections, the base URL, etc, and thus replacing the whole adapter (for example to ensure that I get a JSON response) is awkward. I would like to configure how the calls are made (for example forcing strict_http), but also have control over the response format (not only an option for a JSON response), to integrate with the objects that I already use.

[briantist]

@WilkenSteiner Thank you for that! It sounds like you might be interested in this:

• [WIP] Add AdapterResponse types, and HvacAdapter #898

Unfortunately since starting that I've discovered that several of hvac's APIs make assumptions about the return value from an Adapter, and basically assume the JSONAdapter, which not only makes new proposals like that awkward, it also means that even the current system is limited and frankly inconsistent.

I put this poll up to gather some information that could inform the future of the Adapter system for the library.

[Tylerlhess]

OK, I have dissected the HVAC adapter system while trying to understand and fix the cert auth code I wrote 2 years ago. I think I was the last one to make significantly meaningful changes with adapter.py. So I guess I use the default adapter but only after changing it for my own use case. I still don't think that the requests adapter that sits under our adapter is handling certs to the point of persistence. Without rewriting the client class to hold the auth certs and passing them back down when a new requests session is created I'm not sure that that issue can really be resolved fully. The other half of the issue is that the requests adapter "should" only need to have the certs attached for the duration of getting a token and use that from then on during the lifetime of that client instance. So while I don't have a love for the current system I also don't have any solutions for fixing the issues that it has either. I think the current system is a workable solution that does allow for customization but there is really no need to do so and you will likely break everything trying to fix it to your needs as I did.

[briantist]

@Tylerlhess thank you for commenting!

I'm not quite following the cert stuff; are there any open issues for it now that you could link to? If not, could you open one if you think it's warranted?

Much of what this discussion is about is that there are things I'd like to improve in the library, which would be done mostly in the adapter system, but in digging into it, I've realized that while on the surface, our adapter system seems to have certain abstractions, in practice there are assumptions baked in various points in the library that break of the promises of an Adapter (like assuming the response comes from requests). In addition, some of the theoretical promises in adapters (like not necessarily relying on requests) also limit the types of improvements that can be made.

I think that we will need to make choices that limit some promises, in order to open up others, and any choice will inevitably break someone, but I'm trying to seek feedback about how folks are using adapters to get a sense of the impact that these changes could make. I have some ideas on direction and which choices to make, but feedback on how the system is used could influence those choices.

[Tylerlhess]

Here is the one that is still open. In there I go over my major complaints with the adapter class being so reliant on requests as it complicates cert auth requests and loses the certs if they are not used immediately for authentication.
I have moved onto a much smaller company where we don't use vault (yet) so I haven't been following hvac issues as well as I could. I also have been doing all auth in my personal projects with crypto signed messages for authentication which Vault doesn't have yet as far as I know.