GEN-196: Move error-stack-experimental into error-stack

[indietyp]

🌟 What is the purpose of this PR?

This moves error-stack-experimental into the error-stack crate, reason for this is that we didn't plan on publishing error-stack-experimental anyway, this allows us to use the experimental features, while also giving it to users under a feature flag and makes developing these unstable features easier.

The only problem is that this means that error-stack unstable features won't be semver compatible anymore, but we judged that that was a good tradeoff to be made.

This PR also replaces the ResultMultiExt with a ReportSink, sadly due to must_use limitations we cannot solely rely on must_use to ensure the value is consumed, instead ReportSink makes use of runtime validation (which is only active during debug_assertions). ReportSink::new() will create a sink that will stderr if the sink isn't finished, Report::new_armed goes a bit further and will panic. This ensures that the value really is used every single time, but is quite disruptive, so is not the default.

Pre-Merge Checklist 🚀

🚢 Has this modified a publishable library?

This PR:

• modifies a Cargo-publishable library and I have amended the version

📜 Does this require a change to the docs?

The changes in this PR:

• require changes to docs which are made as part of this PR

🕸️ Does this require a change to the Turbo Graph?

The changes in this PR:

• affected the execution graph, and the turbo.json's have been updated to reflect this

[vilkinsons]

Rationale makes sense. Legal approval-only here. Tim for UAT.

[codecov]

Codecov Report

Attention: Patch coverage is 76.11940% with 48 lines in your changes missing coverage. Please review.

Project coverage is 19.72%. Comparing base (6b3b709) to head (bc779f7).
Report is 25 commits behind head on main.

Files with missing lines	Patch %	Lines
libs/error-stack/src/sink.rs	75.14%	44 Missing ⚠️
libs/error-stack/src/macros.rs	78.94%	4 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #5181      +/-   ##
==========================================
+ Coverage   18.12%   19.72%   +1.60%     
==========================================
  Files         506      510       +4     
  Lines       16776    17182     +406     
  Branches     2546     2546              
==========================================
+ Hits         3041     3390     +349     
- Misses      13723    13780      +57     
  Partials       12       12              

Flag	Coverage Δ
blockprotocol.type-system	55.38% <ø> (ø)
local.hash-backend-utils	9.38% <ø> (ø)
local.hash-isomorphic-utils	1.06% <ø> (ø)
rust.deer	5.88% <ø> (ø)
rust.error-stack	72.23% <76.11%> (+2.13%)	⬆️
rust.sarif	87.83% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[TimDiekmann]

Mainly a few comments/questions. Looks very good, excited to test this out!

[TimDiekmann]

I don't think we need to mention this everywhere as the documentation is properly generating this:

[indietyp]

I just wanted to make sure to mention that it is exempt from semver guarantees and why, not necessarily that it's unstable.

[TimDiekmann]

Is there a way to not include this feature flag in the docs? Maybe somethig like #[cfg(not(docs))]? Because currently, we have this:

[indietyp]

I would've liked if there's a way to conditionally disable match arms that would circumvent the problem. Sadly I didn't find an obvious ergonomic way to do so. I'll just disable the unstable macro during generation.

[TimDiekmann]

I noticed, that the bail macro is probably not working as expected:

error[E0034]: multiple applicable items in scope
  --> libs/error-stack/tests/test_macros.rs:36:55
   |
36 |     let report = capture_error(|| bail!([RootError])).attach_printable(PrintableA(0));
   |                                                       ^^^^^^^^^^^^^^^^ multiple `attach_printable` found
   |
   = note: candidate #1 is defined in an impl for the type `error_stack::Report<C>`
   = note: candidate #2 is defined in an impl for the type `error_stack::Report<[C]>`

Probably an issue for a follow-up (-> non-blocking)

[TimDiekmann]

I tried around with it a bit and failed to properly generate a doc here. We might want to remove the current bail from the docs and add a bail macro with both variants and a notice that the second variant is unstable.

[indietyp]

I noticed this as well, I wanted to do this in a follow up - because the code for Report<[C]> and Report<C> is actually the same now (previously the return type was different)

[TimDiekmann]

Do we want to move the documentation to the variants instead?

[TimDiekmann]

add is a term which is rarely used in Rust. Maybe we want to use append or the Extend trait? I don't have a strong opinion on that, I just want to mention it 🙂

[indietyp]

Thought about that as well but didn't rename it because of the follow up PR that applies the changes to the worktree. I was thinking of renaming it to either "push" or "append" (more likely append) to be in line with the existing methods in Report<[C]>.

What di you think about append?

[TimDiekmann]

As I proposed append myself I'm fine with that 🚀

We can always change it later, no rush 👍🏻

[TimDiekmann]

Non-blocking: Similar to bool.then_some we could use finish_ok().

[TimDiekmann]

A few things we like to do in follow-up but nothing blocking this PR from being merged 🚀

[hashdotai]

Rationale makes sense. Legal approval-only here. Tim for UAT.

Legal re-approval

[hashdotai]

Rationale makes sense. Legal approval-only here. Tim for UAT.

Legal re-approval

[hashdotai]

Rationale makes sense. Legal approval-only here. Tim for UAT.

Legal re-approval

[github-actions]

Benchmark results

@rust/graph-benches – Integrations

scaling_read_entity_linkless

Function	Value	Mean	Flame graphs
entity_by_id	10 entities	$$1.87 \mathrm{ms} \pm 4.28 \mathrm{μs}\left({\color{gray}-2.867 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id	100 entities	$$2.02 \mathrm{ms} \pm 6.74 \mathrm{μs}\left({\color{gray}-2.921 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id	1000 entities	$$2.73 \mathrm{ms} \pm 11.9 \mathrm{μs}\left({\color{lightgreen}-23.180 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id	10000 entities	$$12.5 \mathrm{ms} \pm 121 \mathrm{μs}\left({\color{gray}-0.358 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id	1 entities	$$1.90 \mathrm{ms} \pm 10.4 \mathrm{μs}\left({\color{gray}1.11 \mathrm{\%}}\right) $$	Flame Graph

scaling_read_entity_complete_zero_depth

Function	Value	Mean	Flame graphs
entity_by_id	10 entities	$$2.07 \mathrm{ms} \pm 12.7 \mathrm{μs}\left({\color{gray}-0.680 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id	50 entities	$$4.18 \mathrm{ms} \pm 17.9 \mathrm{μs}\left({\color{gray}3.68 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id	5 entities	$$1.93 \mathrm{ms} \pm 15.7 \mathrm{μs}\left({\color{gray}0.237 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id	25 entities	$$3.07 \mathrm{ms} \pm 16.2 \mathrm{μs}\left({\color{red}5.86 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id	1 entities	$$1.88 \mathrm{ms} \pm 10.3 \mathrm{μs}\left({\color{gray}-0.806 \mathrm{\%}}\right) $$	Flame Graph

representative_read_entity

Function	Value	Mean	Flame graphs
entity_by_id	entity type ID: https://blockprotocol.org/@alice/types/entity-type/organization/v/1	$$15.7 \mathrm{ms} \pm 186 \mathrm{μs}\left({\color{lightgreen}-14.979 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id	entity type ID: https://blockprotocol.org/@alice/types/entity-type/uk-address/v/1	$$15.6 \mathrm{ms} \pm 184 \mathrm{μs}\left({\color{lightgreen}-33.649 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id	entity type ID: https://blockprotocol.org/@alice/types/entity-type/person/v/1	$$15.4 \mathrm{ms} \pm 187 \mathrm{μs}\left({\color{gray}-1.123 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id	entity type ID: https://blockprotocol.org/@alice/types/entity-type/song/v/1	$$16.0 \mathrm{ms} \pm 167 \mathrm{μs}\left({\color{gray}4.19 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id	entity type ID: https://blockprotocol.org/@alice/types/entity-type/page/v/2	$$15.9 \mathrm{ms} \pm 168 \mathrm{μs}\left({\color{gray}1.68 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id	entity type ID: https://blockprotocol.org/@alice/types/entity-type/block/v/1	$$16.0 \mathrm{ms} \pm 185 \mathrm{μs}\left({\color{gray}0.277 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id	entity type ID: https://blockprotocol.org/@alice/types/entity-type/book/v/1	$$16.0 \mathrm{ms} \pm 179 \mathrm{μs}\left({\color{red}5.74 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id	entity type ID: https://blockprotocol.org/@alice/types/entity-type/playlist/v/1	$$16.4 \mathrm{ms} \pm 205 \mathrm{μs}\left({\color{red}5.04 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id	entity type ID: https://blockprotocol.org/@alice/types/entity-type/building/v/1	$$16.1 \mathrm{ms} \pm 161 \mathrm{μs}\left({\color{gray}3.24 \mathrm{\%}}\right) $$	Flame Graph

representative_read_entity_type

Function	Value	Mean	Flame graphs
get_entity_type_by_id	Account ID: d4e16033-c281-4cde-aa35-9085bf2e7579	$$1.41 \mathrm{ms} \pm 4.44 \mathrm{μs}\left({\color{gray}-1.046 \mathrm{\%}}\right) $$	Flame Graph

scaling_read_entity_complete_one_depth

Function	Value	Mean	Flame graphs
entity_by_id	10 entities	$$51.7 \mathrm{ms} \pm 186 \mathrm{μs}\left({\color{red}18.9 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id	50 entities	$$272 \mathrm{ms} \pm 1.03 \mathrm{ms}\left({\color{gray}0.542 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id	5 entities	$$25.1 \mathrm{ms} \pm 282 \mathrm{μs}\left({\color{gray}0.123 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id	25 entities	$$75.6 \mathrm{ms} \pm 264 \mathrm{μs}\left({\color{gray}4.36 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id	1 entities	$$20.2 \mathrm{ms} \pm 158 \mathrm{μs}\left({\color{gray}-1.587 \mathrm{\%}}\right) $$	Flame Graph

representative_read_multiple_entities

Function	Value	Mean	Flame graphs
link_by_source_by_property	depths: DT=2, PT=2, ET=2, E=2	$$97.9 \mathrm{ms} \pm 505 \mathrm{μs}\left({\color{gray}-0.914 \mathrm{\%}}\right) $$	Flame Graph
link_by_source_by_property	depths: DT=0, PT=2, ET=2, E=2	$$94.1 \mathrm{ms} \pm 399 \mathrm{μs}\left({\color{gray}-2.648 \mathrm{\%}}\right) $$	Flame Graph
link_by_source_by_property	depths: DT=255, PT=255, ET=255, E=255	$$106 \mathrm{ms} \pm 505 \mathrm{μs}\left({\color{gray}-1.104 \mathrm{\%}}\right) $$	Flame Graph
link_by_source_by_property	depths: DT=0, PT=0, ET=0, E=0	$$42.6 \mathrm{ms} \pm 246 \mathrm{μs}\left({\color{gray}2.62 \mathrm{\%}}\right) $$	Flame Graph
link_by_source_by_property	depths: DT=0, PT=0, ET=0, E=2	$$79.8 \mathrm{ms} \pm 338 \mathrm{μs}\left({\color{gray}-1.216 \mathrm{\%}}\right) $$	Flame Graph
link_by_source_by_property	depths: DT=0, PT=0, ET=2, E=2	$$89.6 \mathrm{ms} \pm 419 \mathrm{μs}\left({\color{gray}-3.893 \mathrm{\%}}\right) $$	Flame Graph
entity_by_property	depths: DT=2, PT=2, ET=2, E=2	$$59.3 \mathrm{ms} \pm 291 \mathrm{μs}\left({\color{gray}0.825 \mathrm{\%}}\right) $$	Flame Graph
entity_by_property	depths: DT=0, PT=2, ET=2, E=2	$$54.8 \mathrm{ms} \pm 315 \mathrm{μs}\left({\color{gray}-0.073 \mathrm{\%}}\right) $$	Flame Graph
entity_by_property	depths: DT=255, PT=255, ET=255, E=255	$$68.3 \mathrm{ms} \pm 499 \mathrm{μs}\left({\color{gray}2.33 \mathrm{\%}}\right) $$	Flame Graph
entity_by_property	depths: DT=0, PT=0, ET=0, E=0	$$39.9 \mathrm{ms} \pm 307 \mathrm{μs}\left({\color{gray}0.091 \mathrm{\%}}\right) $$	Flame Graph
entity_by_property	depths: DT=0, PT=0, ET=0, E=2	$$43.6 \mathrm{ms} \pm 320 \mathrm{μs}\left({\color{gray}0.022 \mathrm{\%}}\right) $$	Flame Graph
entity_by_property	depths: DT=0, PT=0, ET=2, E=2	$$50.4 \mathrm{ms} \pm 384 \mathrm{μs}\left({\color{gray}-0.794 \mathrm{\%}}\right) $$	Flame Graph