Clarify what errors are catchable

[florian-lefebvre]

📚 Subject area/topic

Error handling

📋 Page(s) affected (or suggested, for new content)

• https://docs.astro.build/en/basics/astro-pages/#error
• Maybe the middleware page? We don't show error handling in there but maybe should

📋 Description of content that is out-of-date or incorrect

Follows withastro/astro#12383

prop for any error thrown during rendering

Quoting @Fryuni:

I'd say that sentence is actually the opposite of the technical truth 😅
It happens for every error except those that happen during rendering, since those are on an ongoing stream.
But what is calling the literal renderComponent function and what users might think as rendering might not be the same

🖥️ Reproduction in StackBlitz (if reporting incorrect content or code samples)

No response

[Fryuni]

Expanding my quote, considering the following middleware code:

defineMiddleware(async (context, next) => {
	const res = await next();
	const body = await res.text();
	return new Response(body, res);
})

• Users can modify the request state in context up to await next()
• At await next() the frontmatter of the page is executed. Any error thrown on the route file can be caught by wrapping this call in a try/catch. (As a reference to match internal code to the docs, this is when the RenderInstance is created)
• None of the body has been rendered at this point, neither from the route nor from any component.
• By reading the body with await res.text() (could be in any other format, not just text) the body of the page is rendered, including the template of the page, the frontmatter of components and the template of components. Any error thrown on any component can be caught by wrapping this call. (Internal reference, this is the part we iteratively call the RenderInstance.render method, so the actual rendering to HTML).

Reading the whole body using res.text/res.json/... renders the entire page to memory, effectively disabling HTML streaming. If the user intend to change the response based on an error, they must disable streaming since it is conceptually incompatible, they can't change what was already sent to the client. If they want to change what comes after an error or just do something extra based on an error, they can do so without rendering to memory. Sentry integration recently added support for detecting and reporting errors while streaming, it is quite more verbose:

https://github.com/getsentry/sentry-javascript/blob/5ee25973e6baf534ac7502b802f658bb469bbb85/packages/astro/src/server/middleware.ts#L190-L232

The error property given to the 500 page is the value thrown by await next(). By rendering the body to memory in a middleware the user effectively moves the error from the rendering to the await next of a middleware before theirs, so disabling middlewares

[fkatsuhiro]

I'll give it a try.

[fkatsuhiro]

I'm open to feedback and happy to make any necessary changes.