feat: Add metadata to cassettes

[hasier]

Thanks a lot for maintaining this library! I thought of opening a PR with a feature I think would be useful to include (it would definitely be for me 🙂).

I have a use case were I need to store additional information per test. I have a couple of scenarios in mind:

• I need to keep externally generated values to pass to subsequent HTTP requests (I do some "fun" stuff with playwright where I redirect to a browser and then come back to the test, where I need values from the resulting redirect).
• I need to generate random values to reach out to some services, and I don't want to filter out those values from the recording, which means each run generates new random values and there is a mismatch. I cannot keep a generic seed for those random values because each time a cassette is regenerated it needs to have a full new value, so I'd need to change the seed and therefore regenerate all cassettes.

I thought that keeping those values in the cassette made sense, we'd call it metadata, information that is not strictly related to a particular request-response interaction, but helps run the test.

To support this I have made a couple of almost-breaking changes: the deserializer might return 3 values rather than 2 (thought of returning a dict instead to make a more similar interface to serialize, but felt "more breaking"), and CannotOverwriteExistingCassetteException now may not be related to a request. They are still backwards compatible, but they somewhat change the current assumptions. Not sure if you'd prefer a version bump in the cassette format and/or a deprecation warning to encourage migrating to this new version that includes metadata.

Let me know your thoughts, happy to discuss the solution and improvements! 🙇

[hasier]

@jairhenrique thanks for running the tests! I am not sure the failures are related to my changes though 🤔 I can see HTTP 502: Bad Gateway errors, but they only seem to happen when sending a request to httpbin.org in Tornado and only in some of the builds. Have you encountered this before? Not sure what'd be the best approach to tackle this tough, the cassette would look rather odd if we just did a retry 😕

[hasier]

@jairhenrique did you have a chance to look into these errors? I see them happen in master too, so I guess it's a wider issue and not limited to this PR? If I run these tests locally they all pass.

[hasier]

@jairhenrique thanks for rerunning the tests, I see they all now pass! Any chance this proposal can now be reviewed? It'd be of great help for me to have it available as part of the library 🙏

[hasier]

@jairhenrique @kevin1024 sorry for the direct ping, just wondering if you'd have a bit of time to review this feature request? I've seen some movement in the repo lately, which is great, and I'd really appreciate if you could take a look at the proposal and provide some feedback, it'd be really useful for me to have this as part of the library 🙂 Thanks, and happy new year!