Editoast error management

[leovalais]

Settling on this topic is necessary in order to go forward with the split in crates.

[woshilapin]

Here is a first round, hope you like it. I'm really worried by the complexity of this macro and if there would be some other solution.

[leovalais]

Thanks for all the corrections! I'll get back to this document when I have some time, hopefully in the next iteration :)

[leovalais]

I've added a bit of content, especially an implementation plan and details about how to forward Core errors.

[leovalais]

Thanks for the corrections!

[woshilapin]

Nice introducing some new sections about "Issues of the old system" or "Implementation plan".

[leovalais]

This looks mergeable as it is to me.

@Khoyo: we discussed about Core errors with @flomonster yesterday and settled on wrapping the errors, but not parsing them. Lmk if it's ok.

@Khoyo @woshilapin: do I drop the "Rejected Ideas" section or not? (Personally I don't care.)

A final round of review would be much appreciated 🙏

[woshilapin]

Sorry, made a few more comments, I believe most of them are not fundamental so should not move things too much.

And for your questions, I'd prefer to keep "Rejected ideas", it's a good thing to keep these around so we avoid to reinvent things we might have explore in the past.

[woshilapin]

If all our errors implements EditoastError, can't we not do it with something like impl<T: EditoastError> utoipa::ToSchema for T once and for all (and avoid to do that in the macro, and therefore, avoid also a lot of code generation?).

[leovalais]

Not sure if there's a misunderstanding or just a typo here. All errors returned by endpoints implement trait ViewError (trait EditoastError is bound to disappear).

The problem is that impl ViewError errors are not serialized in the response. They are converted into what is currently a struct InternalError which has its own serialization. So we can't just #[derive(ToSchema)] on a trait ViewError since the generated schema is inferred from the "would-be" serialization of the type.

Instead, we want MyViewError::schema() to return the schema of the error, but following the structure of InternalError!

For example:

#[derive(ToSchema)]
struct MyViewError { cause: String }

MyViewError::schema()

shouldn't be:

type MyViewError = { cause: string };

but instead:

type MyViewError = {
	status: 500,
	error_type: 'editoast:MyViewError',
	context: { cause: string },
	message: string
}

We can't just impl<T: EditoastError> utoipa::ToSchema for T: the function schema() would build its result based on which information? (We don't necessarily have to generate the whole ToSchema, but we do need to generate enough information at compile-time to build the schema. Rust doesn't have introspection.)

I realize all that is worth a section on this document to avoid confusion.

[leovalais]

accb041 (#237)

[woshilapin]

nitpick: Isn't it this?

Suggested change

	- `impl utoipa::IntoResponses for T` (may be generated or inferred)
	- `impl<T: ViewError> utoipa::IntoResponses for T` (may be generated or inferred)

[woshilapin]

I believe we still want serde, just not the automatic derive.

Suggested change

	making `serde` basically useless for our errors. On top of that, since by design the derive macros of `utoipa` (`ToSchema`, `IntoResponse` especially) interpret the type structure like `serde` would do, we can't rely on them either. Therefore we need a custom derive-macro to convey the structural information of the type at runtime.
	making `derive(serde::Serialize)` basically useless for our errors. ...

Here are some ideas for not codegen the serialize implementation.

[woshilapin]

typo:

Suggested change

The macro doesn't even have to be overly complex. The `trait ViewError` could be responsible of translating the static type definition into an associated constant, which would be used to compute data produced at runtime. (Ie. `impl axum::IntoResponse for T: ViewError` and `impl utoipa::IntoResponses for T: ViewError`.) This would reduce the amount of generated code, at the expense of more complex data manaipulation at runtime.

The macro doesn't even have to be overly complex. The `trait ViewError` could be responsible of translating the static type definition into an associated constant, which would be used to compute data produced at runtime. (Ie. `impl axum::IntoResponse for T: ViewError` and `impl utoipa::IntoResponses for T: ViewError`.) This would reduce the amount of generated code, at the expense of more complex data manipulation at runtime.

[SergeCroise]

Suggested change

	[^2]: Core errors will likely never be recoverable from either editoast or the frontend. For the latter, such errors are likely to be displayed as a generic "Internal error" message. So no translation is needed. For these reasons, we don't need to them in the OpenAPI. However, if in the future, we want editoast to actually parse Core errors, ensuring a proper mapping will still be possible.
	[^2]: Core errors will likely never be recoverable from either editoast or the frontend. For the latter, such errors are likely to be displayed as a generic "Internal error" message. So no translation is needed. For these reasons, we don't need to pass them in the OpenAPI. However, if in the future, we want editoast to actually parse Core errors, ensuring a proper mapping will still be possible.

(j'avoue que ne n'ai pas trop compris la phrase)