Introduce turbo:frame-missing event

[seanpdoyle]

Closes hotwired/turbo#432
Follow-up to hotwired/turbo#94
Follow-up to hotwired/turbo#31

When a response from within a frame is missing a matching frame, fire
the turbo:frame-missing event.

There is an existing contract that dictates a request from within a
frame stays within a frame.

However, if an application is interested in reacting to a response
without a frame, dispatch a turbo:frame-missing event. The event's
target is the FrameElement, and the detail contains the
fetchResponse: key. Unless it's canceled (by calling
event.preventDefault()), Turbo Drive will visit the frame's URL as a
full-page navigation.

The event listener is also a good opportunity to change the
<turbo-frame> element itself to prevent future missing responses.

For example, if the reason the frame is missing is access (an expired
session, for example), the call to visit() can be made with { action: "replace" } to remove the current page from Turbo's page history.

[tleish]

In the above example, does Turbo.visit(url, { response }) update the page/url with the existing response or generate another server request?

[seanpdoyle]

@tleish if there's a response key in the Partial<VisitOptions> passed to the visit call, the HTTP request is "simulated" by the Visit, and does not result in an additional call:

https://github.com/hotwired/turbo/blob/v7.1.0-rc.1/src/core/drive/visit.ts#L171-L173

As part of this draft, I'm investigating ways to more easily transform the FetchResponse into Turbo.visit arguments so that client applications don't need to deconstruct them themselves.

[tleish]

there's a response key in the Partial<VisitOptions> passed to the visit call, the HTTP request is "simulated" by the Visit, and does not result in an additional call:

A good solution. It would be even better if a developer didn't have to recreate response object. Something like:

addEventListener("turbo:frame-missing", async ({ target, detail: { fetchResponse } }) => {
  // the details of `shouldRedirectOnMissingFrame(element: FrameElement)`
  // are up to the application to decide
  if (shouldRedirectOnMissingFrame(target)) {
    Turbo.visit(fetchResponse.location, { response: fetchResponse })
  }
})

Learned something new, thanks!

[tobyzerner]

Working beautifully for the most part. But I think I'm running into a bug? I'm using the exact code sample suggested:

addEventListener("turbo:frame-missing", async ({ target, detail: { fetchResponse } }) => {
    const { location, redirected, statusCode, responseHTML } = fetchResponse
    const response = { redirected, statusCode, responseHTML: await responseHTML }

    Turbo.visit(location, { response })
})

The first time this event is triggered by a form submission, it works great – the whole page is replaced with the new HTML. But if I repeat the submission a second time, it breaks. Turbo seems to revert to a cached snapshot of the whole page, and never completes the visit ([aria-busy=true] and [data-turbo-preview] attributes remain on body). Not sure if that's enough info for a reproduction?

[seanpdoyle]

I'll investigate that.

I'm not sure if it's related, but it's also worth mentioning that if you're using turbo-rails, you'll have to manually override the controller to render a layout so that the response is a fully formed HTML document.

[tleish]

you'll have to manually override the controller to render a layout so that the response is a fully formed HTML document

Assuming 'frame-missing' still logs a message to the console, should Turbo.visit also log a message of "responseHTML not a fully formed HTML document"?

[tleish]

@tobyzerner - this might be unrelated to these changes as I think I stumbled across a similar issue on 7.0.1.

1. Visit page with turbo-frame (first time) via redirect and the frame loads src.
2. Leave page and update data which impacts turbo-frame
3. Return to page via redirect with the turbo-frame, old data is still displayed in the turbo-frame
4. Hard refresh of the page shows the updated data.

What I observed is that turbo renders the page and fetches the turbo-frame source. Inspecting the fetch request I can see in includes a full HTML document with the expected updates and the correct turbo-frame. It just does not update the turbo-frame.

Adding <meta name="turbo-cache-control" content="no-cache"> to this particular page resolves the issue, but unless I'm misunderstanding turbo caching, adding <meta name="turbo-cache-control" content="no-cache"> to every page with a turbo-frame shouldn't be a permanent solution.

@seanpdoyle - If needed, I can file a separate issue.

[tleish]

Turns out this has nothing to do with turbo-frames, but overall turbo-caching and server redirects.

Created issue #447

[seanpdoyle]

@tleish I've extended the turbo:frame-missing to yield a callable visit() function that knows how to transform the FetchResponse into a visit. Callers can pass additional VisitOptions like action: to the function.

[tleish]

Will this be in the next release?

[seanpdoyle]

I'm not sure when the next release will be. I've marked this as a Draft PR to try and start up a discussion.

I think there might be some details to work out:

• Is turbo:frame-missing a good name? Should it be named turbo:frame-not-found, :frame-error, or something else?
• Does dispatching a reference to the FetchResponse make sense? It'd effectively make the shape of FetchResponse objects public API, and would represent a commitment to support that API in future releases
• Does treating turbo-frame[id][disabled] in the body as a "missing" frame deserve its own conversation or PR?

[lefermierperso]

Hey guys, any updates ?

[tbeemster]

This will be super helpful for the use case of redirecting to a login page if a frame tries to load and the user session has expired for example -- and even better because it will encourage proper status codes when redirecting (e.g. using a 401 in an authorization-check redirect instead of default 3xx).

I arrived here from the thread in #257 and am looking a solution to the exact use case mentioned above and am wondering if there are plans for this event to be added to Turbo Frames (or if another solution is in the works)

[pfeiffer]

Could this be a good candidate for inclusion in 7.2.0?

An alternative could be to combine the PR in #560 introducing turbo:error with a change that returns a structured Error when a frame is missing instead of just an error message. This would at least allow developers to handle the missing frames, albeit not as elegant as this PR.

[eladmarg]

this should be merged.
I used this on production for long time, without any issues.

[seanpdoyle]

I've opened hotwired/turbo-rails#367 to explore an alternative for "breaking out" of a frame from the server.

As far as what happens when a frame is missing, that seems to be an ongoing discussion.

[seanpdoyle]

Since servers (like Rails) can respond to Frame requests with incomplete HTML documents, I'm unsure about how to best handle a response without a matching frame.

I'm not sure whether or not Drive should re-use the response HTML or issue a new request to fetch a full page of content. My gut tells me to always make a full request, but I'm curious if there's a quick win I'm not considering.

[dhh]

I think the current default is correct, because the majority case here will be to deal with pages like 500 errors or authentication expired errors, where full pages will be returned. But I think we can help developers here by logging a warning to point them in the direction of what's going on.

[dhh]

Ah, I see you changed it to a full visit instead. I guess it doesn't matter that much. This behavior is for the exceptional case in any circumstance. Not for the normal, steady flow.

[dhh]

Would be good to follow up with a doc PR explaining the new event and its power to prevent the default visiting fallback behavior.