Support All of Structure Clone in RSC Serialization

[sebmarkbage]

The React Server Components payload is a custom protocol that extends what is serializable beyond just JSON. Beyond just JSON we also support all React primitives (React.lazy, ReactNode) and global named symbols (Symbol.for). We also already have plan to expand this support with these as well:

• Promises
• Typed Arrays / DataView
• BigInt
• undefined, Infinity, NaN, -0

We don't have plans to make this algorithm pluggable from the outside because we're concerned about the complexity this puts on the ecosystem and that components won't be reusable in different contexts where they're not configured or configurations are conflicting.

However, it might make sense to expand support to the types supported by the Structured clone algorithm which is already standardized and specified.

• Cyclic references: We already support references in the protocol. This is mostly just an implementation detail for the perf cost whether something should be inlined as JSON or defined as a separate row.
• ArrayBuffer: For Typed Arrays we might stick to using the underlying buffer coming from the stream instead of cloning the data. All values are considered immutable anyway. For ArrayBuffers we can't use that trick though so it would require a new clone of the data which might be a bit of a foot gun when switching between buffers and typed arrays.
• Error objects: We already support thrown errors and we could support more errors in the encoding. However, we intentionally don't pass them through with all information. We cover them up with digests since the error message and stack can sometimes include sensitive information that only the server should have access to. We would likely have to do the same here.
• Boolean/String objects: We don't currently support the object wrappers around primitives e.g. new String(). You're not really supposed to use these in modern JS so it's kind of annoying to have to add extra code to handle this case.
• RegExp: These are pretty straightforward but can possibly have security implications.
• Date, Map, Set: These are fairly straightforward to serialize so it's mostly a matter of allowing these as special cases. Why are these special? Because Structured Clone says so.
• (Temporal: It seems appropriate that this would be added to structured clone but we need to confirm.)

We probably won't support Web specific APIs that don't necessarily have an equivalent on the Server or isn't directly transferrable such as if it has handles to local hardware or file system resources. The only one that might be easy to support:

• Blob: This would be a wrapper around a ReadableStream with a mime type.
• (File: This is just a Blob with a modified time and file name. I think we'll likely want to only support Blobs and not Files, meaning that File object would serialize as Blob, so the receiving type has to be Blob. Because file names and modified times could have security implications and it's too easy to accidentally leak this data.)

[KATT]

I really appreciate that you're thinking about structures outside of the default JSON-stuff.

Maybe there's a world where React itself doesn't do the heavy lifting, but you instead allow developers to add their own serialization libraries?

There's devalue, superjson, and others that can do a lot more than the built-in limitations of JSON.stringify/JSON.parse()

I for one would love to be able to use BigInt & Temporal polyfills for date objects (which I both currently can use with superjson together with tRPC).

[sebmarkbage]

The serialization algorithm itself is most of what the RSC server is and it has a lot of special features as part of that. So it's not as easily pluggable.

Another consideration is that for static types to be preserved, it needs to get the same type on both sides. E.g. toJSON() is not supported even though it's supported in JSON.stringify because that changes the type on the receiving side.

It's also important to us that code is interchangeable between projects and that npm packages are able to support. It's easy for a plug-in system to go out of control.

That said, we already support or want to support most things that those other libraries support, so if you have specific examples it would be good to add to the list.

It seems likely that Temporal would soon be added to structured clone, but it would be good to get that confirmed and that there's no blockers to doing so in the web spec.

[KATT]

For me, it's all about getting static types to be preserved and used interchangeably across the HTTP boundary.

Ideally, I'd like to be able to have some sort of mapper where I can interpret any sort of object and serialize/deserialize according to my own preference since that allows me to statically type an object and "know" its integrity will remain the same throughout the serialization.

I don't think React itself should be the gatekeeper or responsible for what data types can or cannot be serialized.

I do see how something like supporting promises will make this hard as this seems very specific to the RSC implementation, but I don't think opening this up would impede the use of making code interchangeable across projects - most likely, any open-source project would not depend on a special type.

[sophiebits]

RegExp: These are pretty straightforward but can possibly have security implications.

What's the security risk here?

[sebmarkbage]

What's the security risk here?

The main attack vector that I'm concerned about right now is the reverse form, when you can pass it back into the server as an argument to an action. That can trick code to execute a regexp that itself has a zero-day. Since regexps implementations in C++ has been known to have those.

Passing out to the client is a little less concerning since a user supplied object. The programmer would have to opt-in to letting the user provide a regexp. However, it can limit the usefulness of the protocol for things like mashups/federation where you take an RSC response from a third party.

[sebmarkbage]

We could consider DOMPoint/DOMRect/DOMMatrix/DOMQuad if that's actually something people want to use and if those get proper polyfills in server environments. One question is whether these will actually end up being replaced by value types or views over typed arrays.

[hamlim]

One of the things we ran into when starting to adopt RSC within Next is that URL instances can't be passed as prop values down into client components, did some digging and it seems like it's also not supported in structuredClone as well (which seems odd to me). Would it be possible to support URL's within the RSC serialization?

For the short term, we've opted to .toString() the value and then pass it back into the URL constructor on the other side within the client component. But this adds a bit of overhead/complexity when jumping between the boundary.

[sebmarkbage]

URL has been brought up before. If it’s a frequent enough exception then maybe it’s worth breaking rules but we have to have some guideline for what we include and not. In generally things that have significant benefits to the serialization format or can’t be done any other way are favored.

Ideally it would get brought up as a Web proposal first so that it’s clear that it’ll keep working and not break in the future. E.g. if stateful stuff are added to that data structure in the future we may not be able to support it.

Another complexity is that URLs have a validation step that something is a valid url which can change over time or have divergent implementations. With Date and Temporal there’s always some standard format that we can use in the transfer but that’s not always true for URL. So it might not be possible to transfer a URL from one environment to another. This is somewhat of an edge case but it does show that it’s a bit sketchy to support if we’re not confident that we can keep it seamless. I’m favoring holding off on it for now.

[hamlim]

That sounds reasonable to me 👍

[Janpot]

We don't have plans to make this algorithm pluggable from the outside because we're concerned about the complexity this puts on the ecosystem and that components won't be reusable in different contexts where they're not configured or configurations are conflicting.

Makes sense. How about exposing the serialization/deserialization APIs in React? I'd be glad to be able to use those methods in my own code.

[sebmarkbage]

I'm going to close this issue now since with #29035 we'll have landed all serializations we plan on supporting. Until something new appears (e.g. Temporal).

Some notable omissions:

• Error objects outside of thrown/rejected. (Edit: Partially addressed in [Flight] Serialize Error Values #31104.)
• Boolean/String objects.
• RegExp.
• Symbols in the Reply for security reasons. See [Flight Reply] Don't allow Symbols to be passed to a reply #28610.