[Document] Highlight Cloudflare Workers Environment Differences

[catnaut]

What is the feature you are proposing?

I attempted to modify the HonoRequest headers directly via c.req.raw.headers, but encountered an error: TypeError: Can't modify immutable headers. This functionality works as expected on Bun. After reviewing the Cloudflare Workers documentation, I discovered that the Request object is entirely immutable in this environment, including its headers.

To help developers understand such differences, I propose adding a note to the documentation that highlights the immutability of the Request object in Cloudflare Workers and encourages awareness of environment-specific behaviors in Cloudflare Workers versus other environments.

Reference

Request | Cloudflare Workers docs

You may also want to construct a Request yourself when you need to modify a request object, because the incoming request parameter that you receive from the fetch() handler is immutable.

Code Examples

This code will fail in Cloudflare Workers due to the immutability of the Request headers. (Adapted from #2847)

app.use(async (c, next) => {
  c.req.raw.headers.set('x-username', '6km')
  await next()
})

app.get('/', (c) => {
  return c.json(c.req.header())
}) 

This code works in Cloudflare Workers by creating a new Request instance with modified headers.

app.use(async (c, next) => {
  const newHeader = new Headers(c.req.raw.headers);
  newHeader.append("test", "test");

  c.req.raw = new Request(c.req.raw, {
    headers: newHeader,
  });
  await next();
});

[yusukebe]

Hi @catnaut

I think this is not only a matter of Cloudflare Workers. The same behavior has occurred on Deno. There are different implementations, but perhaps the specification is that the header should be immutable.

By the way, we are working on discussion the Proxy Helper for the proxy use case to avoid the user writing code for copying headers: #3589

[yusukebe]

We already added the caution for it on our website: https://hono.dev/examples/proxy#proxy

[catnaut]

Hi @catnaut

I think this is not only a matter of Cloudflare Workers. The same behavior has occurred on Deno. There are different implementations, but perhaps the specification is that the header should be immutable.

By the way, we are working on discussion the Proxy Helper for the proxy use case to avoid the user writing code for copying headers: #3589

awesome work on this! 👍