GEN-35: error-stack implement serde hooks

[indietyp]

🌟 What is the purpose of this PR?

This implements the equivalent of Debug hooks, but for the serde output, we're unable to know if a type implements Serialize directly; therefore, we need to register them via hooks.

🔗 Related links

🚫 Blocked by

🔍 What does this change?

Report gains 2 new functions:

impl Report<()> {
	pub fn install_serde_hook<T: serde::Serialize>();
	pub(crate) fn invoke_serde_hook<T>(closure: impl FnOnce(&Hooks) -> T) -> T;
}

(potentially, we could also provide a way to change how a type is serialized via: fn install_serde_custom_hook<T: serde::Serialize>(hook: impl Fn(&T) -> Box<dyn erased_serde::Serialize>) or something similar).

📜 Does this require a change to the docs?

Yes, we need to update the docs to reflect the new capabilities.

🏃 Next Steps

1. The fallback format hooks currently violate the contract described in the documentation when used in serde hooks. The fmt::HookContext is currently constructed for every separate invocation. This should instead be persisted (like how we currently carry forward the serde::HookContet)
2. Hooks are not invoked on Context objects because the current representation does not allow multiple values for a Context. Hooks can return more than a single serialized object. Further investigation 🕵️ is needed.
3. Default hooks are currently not invoked if std or hooks features are missing, behaviour of fmt hooks should be mirrored
4. Documentation is largely missing
5. (maybe, if possible): DynamicFn is overly restrictive regarding lifetime. Closures need to have the lifetime for<'a> Fn(&'a T &mut HookContext<T>) -> U + 'a. This is fine for functions but routinely fails for closures, as we cannot explicitly specify lifetimes on closures. Another possibility would be to relax further the lifetime to: for<'a: 'b, 'b> Fn(&'a T &mut HookContext<T>) -> U + 'b, but currently, this isn't possible because one cannot set lifetime bounds in HRTB, another approach might - if possible - be necessary.

📹 Demo

hash/packages/libs/error-stack/tests/snapshots/test_serialize__sources_nested@spantrace.snap

Lines 5 to 363 in aaca87f

	[
	{
	"context": "context A",
	"attachments": [
	{
	"file": "tests/common/snapshots.rs",
	"line": 207,
	"column": 10
	},
	"2",
	"1"
	],
	"sources": [
	{
	"context": "context A",
	"attachments": [
	{
	"file": "tests/common/snapshots.rs",
	"line": 201,
	"column": 10
	},
	"4",
	"3"
	],
	"sources": [
	{
	"context": "root error",
	"attachments": [
	{
	"file": "tests/common/mod.rs",
	"line": 4,
	"column": 5
	},
	{
	"spans": [
	{
	"fields": [],
	"level": "INFO",
	"name": "func_b",
	"target": "test_serialize::common::snapshots",
	"module_path": "test_serialize::common::snapshots",
	"file": "tests/common/snapshots.rs",
	"line": 73,
	"type": "span"
	},
	{
	"fields": [],
	"level": "INFO",
	"name": "func_a",
	"target": "test_serialize::common::snapshots",
	"module_path": "test_serialize::common::snapshots",
	"file": "tests/common/snapshots.rs",
	"line": 78,
	"type": "span"
	}
	]
	},
	"6"
	],
	"sources": []
	}
	]
	},
	{
	"context": "context A",
	"attachments": [
	{
	"file": "tests/common/snapshots.rs",
	"line": 196,
	"column": 10
	},
	"5",
	"3"
	],
	"sources": [
	{
	"context": "context A",
	"attachments": [
	{
	"file": "tests/common/snapshots.rs",
	"line": 194,
	"column": 10
	},
	"7"
	],
	"sources": [
	{
	"context": "context A",
	"attachments": [
	{
	"file": "tests/common/snapshots.rs",
	"line": 185,
	"column": 34
	},
	"9",
	"8"
	],
	"sources": [
	{
	"context": "root error",
	"attachments": [
	{
	"file": "tests/common/mod.rs",
	"line": 4,
	"column": 5
	},
	{
	"spans": [
	{
	"fields": [],
	"level": "INFO",
	"name": "func_b",
	"target": "test_serialize::common::snapshots",
	"module_path": "test_serialize::common::snapshots",
	"file": "tests/common/snapshots.rs",
	"line": 73,
	"type": "span"
	},
	{
	"fields": [],
	"level": "INFO",
	"name": "func_a",
	"target": "test_serialize::common::snapshots",
	"module_path": "test_serialize::common::snapshots",
	"file": "tests/common/snapshots.rs",
	"line": 78,
	"type": "span"
	}
	]
	}
	],
	"sources": []
	}
	]
	},
	{
	"context": "context A",
	"attachments": [
	{
	"file": "tests/common/snapshots.rs",
	"line": 179,
	"column": 10
	},
	"13",
	"10",
	"16",
	"9",
	"8"
	],
	"sources": [
	{
	"context": "root error",
	"attachments": [
	{
	"file": "tests/common/mod.rs",
	"line": 4,
	"column": 5
	},
	{
	"spans": [
	{
	"fields": [],
	"level": "INFO",
	"name": "func_b",
	"target": "test_serialize::common::snapshots",
	"module_path": "test_serialize::common::snapshots",
	"file": "tests/common/snapshots.rs",
	"line": 73,
	"type": "span"
	},
	{
	"fields": [],
	"level": "INFO",
	"name": "func_a",
	"target": "test_serialize::common::snapshots",
	"module_path": "test_serialize::common::snapshots",
	"file": "tests/common/snapshots.rs",
	"line": 78,
	"type": "span"
	}
	]
	}
	],
	"sources": []
	}
	]
	},
	{
	"context": "context A",
	"attachments": [
	{
	"file": "tests/common/snapshots.rs",
	"line": 165,
	"column": 10
	},
	"15",
	"14",
	"10",
	"16",
	"9",
	"8"
	],
	"sources": [
	{
	"context": "root error",
	"attachments": [
	{
	"file": "tests/common/mod.rs",
	"line": 4,
	"column": 5
	},
	{
	"spans": [
	{
	"fields": [],
	"level": "INFO",
	"name": "func_b",
	"target": "test_serialize::common::snapshots",
	"module_path": "test_serialize::common::snapshots",
	"file": "tests/common/snapshots.rs",
	"line": 73,
	"type": "span"
	},
	{
	"fields": [],
	"level": "INFO",
	"name": "func_a",
	"target": "test_serialize::common::snapshots",
	"module_path": "test_serialize::common::snapshots",
	"file": "tests/common/snapshots.rs",
	"line": 78,
	"type": "span"
	}
	]
	}
	],
	"sources": []
	}
	]
	},
	{
	"context": "context A",
	"attachments": [
	{
	"file": "tests/common/snapshots.rs",
	"line": 175,
	"column": 10
	},
	"11",
	"9",
	"8"
	],
	"sources": [
	{
	"context": "root error",
	"attachments": [
	{
	"file": "tests/common/mod.rs",
	"line": 4,
	"column": 5
	},
	{
	"spans": [
	{
	"fields": [],
	"level": "INFO",
	"name": "func_b",
	"target": "test_serialize::common::snapshots",
	"module_path": "test_serialize::common::snapshots",
	"file": "tests/common/snapshots.rs",
	"line": 73,
	"type": "span"
	},
	{
	"fields": [],
	"level": "INFO",
	"name": "func_a",
	"target": "test_serialize::common::snapshots",
	"module_path": "test_serialize::common::snapshots",
	"file": "tests/common/snapshots.rs",
	"line": 78,
	"type": "span"
	}
	]
	}
	],
	"sources": []
	}
	]
	},
	{
	"context": "context A",
	"attachments": [
	{
	"file": "tests/common/snapshots.rs",
	"line": 171,
	"column": 10
	},
	"12",
	"9",
	"8"
	],
	"sources": [
	{
	"context": "context A",
	"attachments": [
	{
	"file": "tests/common/snapshots.rs",
	"line": 170,
	"column": 10
	}
	],
	"sources": [
	{
	"context": "root error",
	"attachments": [
	{
	"file": "tests/common/mod.rs",
	"line": 4,
	"column": 5
	},
	{
	"spans": [
	{
	"fields": [],
	"level": "INFO",
	"name": "func_b",
	"target": "test_serialize::common::snapshots",
	"module_path": "test_serialize::common::snapshots",
	"file": "tests/common/snapshots.rs",
	"line": 73,
	"type": "span"
	},
	{
	"fields": [],
	"level": "INFO",
	"name": "func_a",
	"target": "test_serialize::common::snapshots",
	"module_path": "test_serialize::common::snapshots",
	"file": "tests/common/snapshots.rs",
	"line": 78,
	"type": "span"
	}
	]
	}
	],
	"sources": []
	}
	]
	}
	]
	}
	]
	}
	]
	}
	]
	}
	]

💡 Additional Information

DynamicFn is overly restrictive. This issue can be addressed using the nightly feature closure_lifetime_binder, which enables us to specify all lifetimes explicitly. It is more verbose than regular closures (and CLion hates it), but it solves the problem. I provided a test case (showcased below) for more context. This resolves our issue because taking Fn(&'a T): U, Rust infers (for regular closures) that, if references are taken from T, U might have a lifetime less than 'a, using HRTBs we're unable to create a trait that reflects this behavior as far as I know (this is because HRTBs cannot define lifetime bounds). The experimental feature lets us circumvent the issue by explicitly stating that U will have a lifetime of 'a. I have attached a screenshot of the error.

hash/packages/libs/error-stack/tests/test_serialize.rs

Lines 136 to 145 in 43c600b

	Report::install_custom_serde_hook(
	for<'a, 'b> |value: &'a DoesNotImplementSerialize,
	context: &'b mut HookContext<DoesNotImplementSerialize>|
	-> ImplementSerialize<'a> {
	ImplementSerialize {
	a: &value.a,
	b: &value.b,
	}
	},
	);

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Updated
hash	🔄 Building (Inspect)		Jan 3, 2023 at 0:55AM (UTC)
hash-design-system	🔄 Building (Inspect)		Jan 3, 2023 at 0:55AM (UTC)
hashdotdev	🔄 Building (Inspect)		Jan 3, 2023 at 0:55AM (UTC)

[indietyp]

Converting into draft, because everything is broken right now and the large change in formatting for 0.3 need to be applied to this PR

[linear]

GEN-35

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 56.81%. Comparing base (465e1aa) to head (d9b1f78).
Report is 3328 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1558      +/-   ##
==========================================
- Coverage   56.87%   56.81%   -0.07%     
==========================================
  Files         276      276              
  Lines       19801    19765      -36     
  Branches      421      421              
==========================================
- Hits        11262    11229      -33     
+ Misses       8534     8531       -3     
  Partials        5        5              

Flag	Coverage Δ
backend-integration-tests	3.66% <ø> (ø)
unit-tests	1.48% <ø> (ø)

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.

[vilkinsons]

Closing this PR following internal discussion.