AWS API Gateway returns 400 when {} are present in query values

[aldenquimby]

Context

What's your version of nuqs?

    "nuqs": "2.5.2",

What framework are you using?

• ✅ Next.js (app router)

Which version of your framework are you using?

    "next": "14.2.32",

Description

• Requests to AWS API Gateway with {} in query values fail with 400 bad request (and appear to hard-crash the gateway, because no execution or access logs appear in CloudWatch for these requests)
• I am trying to use parseAsJson, which ends up serializing { hello: ['a', 'b'] } as {%22hello%22:[%22a%22,%22b%22]}
• I expect {} to be URL-escaped into %7B and %7D respectively
• :, [, and ] do not need to be escaped - AWS API Gateway works fine with those as-is

Reproduction

• I do not have any public API Gateway services right now
• I could look into creating one if needed

Related

• nginx servers return errors when special characters {}|\^ are present in query parameters #1069
• fix: Add encoding for additional special characters in encodeQueryValue #1068
• Encode unsafe URI characters #925

[aldenquimby]

I realize this would be a breaking change, so you may not want to implement it. Here is my workaround for now:

const parseAsJsonSafe = <T>(validator: Parameters<typeof parseAsJson<T>>[0]) => {
  const { parse, serialize, eq } = parseAsJson(validator);
  return createParser<T>({
    parse: (query) => parse(decodeURIComponent(query)),
    serialize: (value: T) => serialize(value).replaceAll('{', '%7B').replaceAll('}', '%7D'),
    eq,
  });
};

Please let me know if anything seems off with my workaround. I'd be fine rolling with that and closing this issue if you think it looks good

[franky47]

That's a good workaround for the moment, but we still need to address this.

Initially, URL encoding was tweaked to get "prettier" URLs (see #355 & #372), but since it leads to compatibility issues with some servers, we need a better story for controlling the URL rendering.

Since it impacts both the hooks and the serializer, it can't be an adapter option. I'm thinking of an API that looks like this:

import { configure } from 'nuqs'

// Name TBD
configure({
  renderQueryString(search: URLSearchParams) {
    return search.toString() // Calls encodeURIComponent on all values by default
  }
})

One issue with Next.js app router is that this code needs to run both server-side (for SSR'd serializer calls) and client-side (for the hooks and CSR'd serializer calls). That might be tricky to do properly (wrt/ 'use client' directives).

What do you think?