Skip to content

Audit error types code base wide#2101

Merged
apoelstra merged 9 commits intorust-bitcoin:masterfrom
tcharding:10-04-error-audit
Oct 6, 2023
Merged

Audit error types code base wide#2101
apoelstra merged 9 commits intorust-bitcoin:masterfrom
tcharding:10-04-error-audit

Conversation

@tcharding
Copy link
Copy Markdown
Member

@tcharding tcharding commented Oct 4, 2023

PR aims to achieve two things:

  • Make error code brain dead easy to read
  • Get error code closer to being ready for v1.0

The first 8 patches are pretty basic, and are broken up into really small changes. The last patch is much bigger, it has a long git log to explain it but reviewing should not take too much brain power.

This PR does not introduce anything new, it just applies what we have been doing recently with errors. Before v1.0.0 others will likely want to re go over all the error types. As such I believe this PR can be merged under the one ack carve-out.

TODOs (future PRs)

We have a few errors that still need splitting up:

  • Split up merkle_tree::block::MerkleBlockError
  • Split up psbt::error::Error
  • Split up IncompleteBuilderError

Also, all error From's should probably have #[inline], I noticed late in the process and did not have the heart to visit every error again.

We typically layout error code as: definition, [impl block], `Display` impl,
`error::Error` impl, from imlps.

Code move only, no other changes.
Move the p2p error types to the bottom of the file next to the various
impls for these types.

Code move only, no other changes.
By convention we always include the suffix "Error" on our error types.

Rename the error type `UnknownChainHash` to `UnknownChainHashError`.
By convention we always include the suffix "Error" on our error types.

Rename the error type `UnknownMagic` to `UnknownMagicError`.
@tcharding tcharding mentioned this pull request Oct 4, 2023
8 tasks
By convention we always include the suffix "Error" on our error types.

Rename the error type `IncompleteBuilder` to `IncompleteBuilderError`.
By convention we always include the suffix "Error" on our error types.

Rename the error type `HiddenNodes` to `HiddenNodesError`.
We would like the codebase to be optimized for readability not ease of
development, as such code that is write-once-read-many should not use
macros.

Currently we use the `impl_std_error` macro to implement
`std::error::Error` for struct error types. This makes the code harder
to read at a glance because one has to think what the macro does.

Remove the `impl_std_error` macro and write the code explicitly.
In a further effort to make the code brain-dead easy to read; use an
explicit implementation of `std::error::Error` that returns `None`
instead of relying on the default trait implementation.
On our way to v1.0.0 we are defining a standard for our error types,
this includes:

- Uses the following derives (unless not possible, usually because of `io::Error`)

  `#[derive(Debug, Clone, PartialEq, Eq)]`

- Has `non_exhaustive` unless we really know we can commit to not adding
  anything.

Furthermore, we are trying to make the codebase easy to read. Error code
is write-once-read-many (well it should be) so if we make all the error
code super uniform the users can flick to an error and quickly see what
it includes. In an effort to achieve this I have made up a style and
over recent times have change much of the error code to that new style,
this PR audits _all_ error types in the code base and enforces the
style, specifically:

- Is layed out: definition, [impl block], Display impl, error::Error impl, From impls
- `error::Error` impl matches on enum even if it returns `None` for all variants
- Display/Error impls import enum variants locally
- match uses *self and `ref e`
- error::Error variants that return `Some` come first, `None` after

Re: non_exhaustive

To make dev and review easier I have added `non_exhaustive` to _every_
error type. We can then remove it error by error as we see fit. This is
because it takes a bit of thinking to do and review where as this patch
should not take much brain power to review.
apoelstra added a commit to rust-bitcoin/rust-bech32 that referenced this pull request Oct 4, 2023
9b23c9c Audit error types (Tobin C. Harding)

Pull request description:

  Audit all error types and ensure the following holds:

  - All use `non_exhaustive`
  - All derive `Debug, Clone, PartialEq, Eq` (unless `io::Error` is present, in which case only `Debug`)
  - All error `From` impls use `inline`

  This is similar to rust-bitcoin/rust-bitcoin#2101, probably should have done this one first.

ACKs for top commit:
  apoelstra:
    ACK 9b23c9c

Tree-SHA512: af525afc8d1a95327e40f7983afe905be18cfe9040b11ca4c14ec93329e32a52a830937c2d79b6b02c763dc17c9a7490871779094ab0fded64654852550a94c9
@apoelstra
Copy link
Copy Markdown
Member

This all looks great to me!

Copy link
Copy Markdown
Member

@apoelstra apoelstra left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ACK 10374af

Copy link
Copy Markdown
Member

@clarkmoody clarkmoody left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ACK 10374af

@apoelstra apoelstra merged commit 3743f27 into rust-bitcoin:master Oct 6, 2023
@tcharding tcharding deleted the 10-04-error-audit branch May 22, 2024 23:16
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants