Run up to 0.15.0

[arlyon]

Hi all,

I am planning on releasing 0.14 soon so I thought I'd write a quick 'state of the union'.

Goals completed in 0.14

• improve test coverage: we added tarpaulin and started tracking coverage. from now on new contributions will be expected to be tested properly, and we will be adding extensive examples
• piles of examples: we have a whole load of shiny examples to look at, along with example-doc linking to put the examples straight alongside the code in docs.rs. very happy with the ergonomics here.
• make sure the 'unusual params' are implemented properly: we added card to the api! 🥳
• explore the effects of implementing Default across the codebase: we added default everywhere! Derive Default on structs #152
• allow the openapi generator to box in specific places: there is a simple extensible heuristic for this! Split out and organise openapi code #160
• opt-in auto-retry functionality following the stripe retry headers: the client will retry failed requests 🎉
• opt in idempotency: now you can make the same mistake twice :P

The library is in a great place. In addition to this we have refactored the codegen to be structured more cleanly, a refactor that opens up some new directions for us.

Goals for 0.15

• split the generated code into crates by feature: this will solve two problems. first, it will force us to resolve our feature dependency tree explicitly, so that any combination of features can be used without breakages, while secondly breaking it up into parallelizable compilation units.
• rework the generation code to support all the declared operations, rather than the a few pre-determined ones: right now our codegen assumes the existence of GET, POST, PUT, DELETE and only generates code for those methods. there may be apis which don't follow this convention that we would like to support.
• build out additional tooling: look here for more info Overhaul the reporting #193

[erichCompSci]

Hey Arlyon, great work as always. So, speaking of the rework on the generated code...

The biggest change that we will need to make is that currently the "request" API's are tied to specific structs with methods instead of functions. We probably should break that. Structs that are specified in the openapi spec should be standalone, especially when they don't take that object as a paremeter. Then we need to decide where we are going to put the new "request" modules. A natural grouping would be by just how Stripe does them (example: "Account" API gets its own "Account" module).

Unfortunately, the way the current code is written is that each file is generated one at a time...and I think that's okay. But it leaves us with a choice.

The only question is...is it going to be difficult to have "Account" be built with these functions, or will it be easier to have a separate file that extends Account like we do manual extensions now. I don't know the answer. With Rust we can do either...so I think it's on your preference. However, they won't be easy to switch once we implement one or the other so we need to discuss this before we do it.

Hopefully this is clear. I'm mostly just trying to start a conversation before I go off and try to implement this because I can do it multiple ways and all ways are equal, but they all have pros and cons and I'd hate to implement one way only to be requested to re implement the other way.

[arlyon]

I think we'd benefit from writing out a spec on this. In an ideal world we'd be able to split this into crates organised by feature, with async-stripe just pulling in the subcrates it needs. There are a few issues with this approach though, namely:

• how do we author our 'ext' files when we are generating crates? We could have a 'generated' folder in each crate but that may get messy
• how do we handle circular dependencies? what if two features (now crates) need to reference one-another? rustc can handle circular types intra-crate but not inter-crate so the crate-dependency tree needs to be a DAG

I agree we could benefit from not having impl's per struct. Currently you call Customer::list with the client, which calls a method on the client itself. We could transpose this. Could you maybe write some concrete examples on what this should look like from an API perspective, and we'll work from there? This is complex enough to warrant some proper design work.

[erichCompSci]

I want to kill the ext files for everything except for the API's that are not in the standard (of which I think the webhooks API are the only ones). I think these files are going to kill us in the end because they become out of date so easily and Stripe has proven to change magnitudes of their API's on whims.

Circular dependencies are a big problem and make me hesitate to use a crate approach. I think the feature approach can work for us, but we need to organize the feature by the first level of the API's. I've also back tracked on the idea of not having impl's per struct. We just need to do it a different way.

Here is what I was thinking: The json is written like so,

1. There is a component section which describes each data type referenced in the documentation. Each of these components should be a new file with a new struct bearing it's name (i.e account.rs has an account struct). Up to here this is the same. BUT, crucially, there should be no functions in these structs by default, except for maybe the id's. Is there any benefit to having the id be the fancy objects that they are now and not just strings...I don't know we should discuss that.
2. Then there is an info section which is small and not important for this part of the code.
3. Then there is a paths section. In this paths section are the actual REST API calls. These start with a /v1/ prefix. So each set of generates a file such as type_interface.rs that implements a set of function for the given . This gives us clean API boundaries that match the Stripe and is intuitive to the interface described in the documentation. In theory, we can then include the API pieces as we need them in the generated and resources.rs and don't have to worry about circular dependencies.

The only problem with this approach is that the "id's" for the API are not clearly labeled. They are just labeled as strings with the description carrying the intent and it's not always obvious from context that the API's use a specific id in the path. I need to examine these a bit more, but if we can get around this problem, this should give us the cleanest interface without changing the top level interface too much, but drastically simplifying our work and giving us more features. This is a big change though and I haven't started on it yet, but I'm looking at this week and next week to get started.