should erased types be considered part of a crate's public API?

[BurntSushi]

For example, let's say someone is using the failure crate and builds errors like this in a crate where csv is intended to be a private dependency:

#[derive(Clone, Debug, Fail)]
pub enum MyError {
    // This error occurs when reading input data.
    Input,
}

fn read_data(path_to_csv: &Path) -> Result<Data, MyError> {
    let mut data = Data::new();
    let mut rdr = csv::Reader::from_path(path_to_csv).context(MyError::Input)?;
    for result in rdr.records() {
        let record = result.context(MyError::Input)?;
        data.push(record[0].to_string()); // or whatever
    }
    Ok(data)
}

Given the above, there is no direct exposure of the csv::Error type. However, it is possible for callers to iterate over the causes of the returned error and downcast to capture the csv::Error. If my library bumps its internal major version of the csv crate, then it possible that uses of my crate that downcast to csv::Error will stop working, since vN's csv::Error type is distinct from v(N+1)'s csv::Error type.

There are some interesting angles on this problem:

• This particular breaking change does not result in a compilation error, but rather, a runtime condition that fails.
• Checking the details of error causes is somewhat niche, and therefore the scope of this change, even if it is a breaking change, is probably almost always very small. (For example, I’ve never had the occasion of wanting to look closely at any error other than io::Error.)
• Preventing the leakage of public errors through the causes returned by the failure crate is possible, but it is definitely not the happy path.

This was discussed a little bit here: https://users.rust-lang.org/t/when-returning-a-trait-object-is-the-underlying-concrete-type-a-part-of-your-public-api --- My summary of that thread is probably that erased types shouldn't be considered a part of a crate's public API by default. With that said, I can imagine that there may (as yet) exist crates where downcasting is a central focus of its API, and where changes on that front may be considered breaking.

As a counterpoint to the URLO thread, with respect to failure, I can see this coming up in the following interesting way:

• failure gains dominance as the way to handle errors in Rust.
• On occasion, people will find the need to look at the causes of an error and downcast them. I certainly do this today for io::Error, and I can imagine other use cases that extend to other error types.
• At some point, someone's downcast is going to fail when it is otherwise expected to succeed. If folks aren't aware of this possibility, I suspect this will be a fun bug for someone to track down. :-)

We should find a way to settle on a guideline here. For example, one possible guideline: "In general, assume that erased types are not a public part of a crate's API, but a crate may elect to document otherwise." Or perhaps a different but more specific guideline, "In general, a change in the behavior of a downcast is not considered a backwards incompatible change for the purposes of semver, but crates may elect to document otherwise." The former feels slightly more slimy than the latter to me, although perhaps it is a distinction without a difference.

[dtolnay]

I would be on board with recommending that the underlying type of a trait object or impl Trait should not be considered public API unless documented as such. How would you propose wording this guideline, given that it mainly deals with how users interact with an API rather than how the API is designed?

Mentioning @seanmonstar who brought up the same question in #96.

[BurntSushi]

@dtolnay Oh! I didn't realize #96 existed. I'd be OK closing this and merging into #96.