Prevent unstable dependencies in our public API

[coryan]

Once we reach 1.0, we will not want to expose unstable APIs in the public APIs of our crates. We would like a tool or CI build to enforce this.

[dbolduc]

There is a way to do this. https://doc.rust-lang.org/cargo/reference/unstable.html#public-dependency

...but only in the nightly build. https://github.com/rust-lang/rust/issues/44663. I do not think it is ready for primetime.

---

Eventually, it would be nice to adopt. I explored it briefly. See: https://github.com/dbolduc/google-cloud-rust/commit/1950373c849d60cd9ea5815d201cf9eb35691f8c

Background

https://doc.rust-lang.org/cargo/reference/unstable.html#public-dependency

Changes

I made some manual changes to the crates upstream of google-cloud-gax (at the moment).

Dependencies are assumed to be private, so we add public = true to any dependency that is...

• an external crate with a stable version. (these are safe to expose).
• one of our non-internal crates. (these will eventually be 1.0, and are for public consumption).

Building

We build with:

RUSTFLAGS="-D exported-private-dependencies" \
  cargo +nightly build -Zpublic-dependency -p google-cloud-gax

A normal build prints unseemly warnings:

cargo build -p google-cloud-gax

There is one of these warnings for each line that uses public in each Cargo.toml. I do not know how to suppress them.

warning: /home/dbolduc/code/git/google-cloud-rust/src/generated/rpc/types/Cargo.toml: ignoring `public` on dependency bytes, pass `-Zpublic-dependency` to enable support for it

Findings:

This thing only caught false positives. Yay?

It flagged auth types that are not exposed outside of the crate. Hence the changes to jws.rs.

[coryan]

We might be able to refactor the definition of all the dependencies to the top-level Cargo.toml file. If we did that, then maybe we could run a script to change said level Cargo.toml file and check for unstable deps as part of the release process?

[dbolduc]

Another approach would be to enumerate the types we use in our public APIs: https://github.com/awslabs/cargo-check-external-types

tonic does this: https://github.com/hyperium/tonic/blob/master/tonic/Cargo.toml#L112-L136