Use headers from thrown Responses (v3_singleFetch)

[byrichardpowell]

With v3_singleFetch enabled, routes must add a headers export if a loader or action throws or returns Responses with headers that matter. This makes the DX a little tricky for packages that throw Responses.

Headers & single_fetch

Pre single_fetch:

export async function loader({request}) {
  throw new Response(200, {
    headers: {
      my: "header"
    }
  })
}

I believe this must change post single_fetch to this:

export async function loader({request}) {
  throw new Response(200, {
    headers: {
      my: "header"
    }
  })
}

export const headers: HeadersFunction = (headers) => {
  // Do stuff to make sure my "header" is included.
};

The Package use case

Where it gets a little nuanced is a package which throws responses with use case critical headers. For example:

import authenticate from "some-package"

export async function loader({request}) {
  const context = authenticate(request)
  
  if (thing === true) {
    context.doSomething()
  }
  
  return null
}

Here 2 things could be throwing a Response that is use-case critical without it being obvious:

• authenticate(request)
• context.doSomething()

If the consumer of the package does not realize that these 2 functions can throw Responses, or if they forget to add the headers export, functionality could break. If the functionality is not encountered during development (call it an edge case), it seems easy to ship breaking code to production.

Today's solution is for the package to provide a function that manages headers and for the developer to remember a headers export. For example:

import authenticate, {manageHeaders} from "some-package"

export const headers = (headers) => {
  return manageHeaders(headers);
};

export async function loader({request}) {
  const context = authenticate(request)
  
  if (thing === true) {
    context.doSomething()
  }
  
  return null
}

But this has some downsides. The package author must educate the developer that this is required, and when. A package could provide a linting rule, but there is no guarantee a developer uses it. Even if the developer does use the linting rule and manageHeaders, it seems possible that a complex headers function may still drop the required headers in a way that would be difficult to lint against.

The Proposal

1. If a loader or action throws a Response, that Response's headers should be used
2. If multiple loaders or actions throw a Response, the first Response should be used.

This would ensure that code pre single_fetch still works post single_fetch:

import authenticate from "some-package"

export async function loader({request}) {
  const context = authenticate(request)
  
  if (thing === true) {
    context.doSomething()
  }
  
  return null
}

There may be a version of this where if the headers export is present, it is used rather than the automatic behaviour I've proposed above. This has benefits:

1. It gives package authors a default, automatic way
2. It gives developers control over the headers, should they want it.

The downside is that If a developer adds a headers export, but forgets to merge headers thrown by the loader/action, use-case ciritical headers provided by the package may be lost.

Middleware

Middleware may be the eventual best-case end-state solution here since they have ultimate control over the Response. In the example above authenticate and context.doSomething could add headers to Context for a Middleware to read.

But what I'm proposing here gives package authors adopting v3_singleFetch the ability to enable the same DX they offer developers today, without forcing a migration to Middleware.

[brophdawg11]

I chatted with @ryanflorence on this and I don't think we're going to adopt this. You nailed it above in that the real solution here for "libraries/utilities that want to throw responses to short circuit" is to do it from middleware. It would just introduce churn to add breaking behavior behind a future flag, that only served a short-term solution until middleware was adopted.

Headers behavior is, tbh, already a bit tricky - but at least it's consistent now with single fetch in that headers is the source of truth.

It's worth noting that your "pre single-fetch" example above was has a generally unnoticed bug in that your headers were present on data requests but not on document requests.