Skip to content

Commit 0222d68

Browse files
ryansolidlxsmnsyc
andauthored
feat(web): send files anywhere in rich server function arguments (#4208)
Ports solidjs/solid-start#2359 (from #4177 by @lxsmnsyc), with uploads kept off the core client request path: they keep the Serialized tag and the handler spots them by their multipart content type. Co-authored-by: Alexis H. Munsayac <[email protected]>
1 parent a40b6cd commit 0222d68

8 files changed

Lines changed: 486 additions & 13 deletions

File tree

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
"@solidjs/web": patch
3+
---
4+
5+
With `enableRichArguments()`, a server function can take files and blobs anywhere in its arguments. Calls like `upload(file, { tags })`, `upload({ file })` and `upload(formData, 1)` used to fail before sending. They now send multipart form data, with each file as its own part instead of encoded inside the arguments.

‎documentation/solid-2.0/10-server-functions.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -44,7 +44,7 @@ One architectural fact worth stating, because the two directive levels land on o
4444

4545
The package resolves to a client entry in the browser and a server entry elsewhere.
4646

47-
**Client:** `configureServerFunctionsClient({ endpoint?, codec?, fetch?, prepareRequest?, serializeArgs?, responseHandler? })` — call once in the client entry, only when deviating from the defaults (endpoint defaults to `/_server`; `codec` takes seroval plugin options and must match the server’s; `fetch` replaces the function the transport sends with — always called as `(address, init)` — for concerns the runtime has no opinion about: retries, telemetry, a test double, or pointing calls at a route of the app’s own, which the handler serves through the same `Request` it serves everything else with; `prepareRequest` is the transport middleware hook below; `responseHandler` is the integration seam server components install — see [RFC 11](11-server-components.md)). Compiled client output produces callables that POST to the call’s **data address** — `<endpoint>/data/<id>`, the id in a path segment — with no per-call header of their own (a read is exactly its url to caches and `<link rel="preload">`). The data address is the scripted transport’s own path, where answers are the codec’s; the bare `<endpoint>/<id>` address (a reference’s `.url`, what renders into form actions) answers plain HTTP. Two paths because the two caller kinds get differently shaped answers and shared caches key on the URL: with one shape per path, a cached answer can only ever be replayed to the caller kind it was made for. (A third caller kind, `live`'s loop, gets a third path — `<endpoint>/live/<id>`, answered as an event stream; same rule.) **Argument encoding (updated since first draft):** arguments with a natural HTTP encoding (a lone string, FormData, File, Blob, ...) go as-is; everything else is sent as **plain JSON by default** — no serializer in the client bundle — and values JSON can’t carry faithfully (Dates, Maps, Sets, typed arrays, cycles, a top-level `undefined` — except in a bound call whose trailing argument is a body-like object (FormData, URLSearchParams, File, Blob, ...), where the leading arguments ride `?args=` and `undefined` is sent as `null` as in the action url; a trailing string is not a body in this sense, so `fn(1, undefined, "str")` goes through the codec) **throw with a directed message** unless you opt in once via `enableRichArguments()` from `@solidjs/web/server-functions/rich-args`, which installs the codec’s write half (~5 KB gz) as `serializeArgs` — importing the entry is the opt-in at the module-graph level, so the serializer ships only when the app asks for it. _Results_ are unaffected — they always travel through the codec, whose decode half the client carries regardless. Async returns (promises, streams) settle over the open connection via length-prefixed chunk framing; a `live` source's response — requested at the live address — is the same stream framed as server-sent events (see `live(fn)` under the extension surface). (A `@solidjs/web/serialization` subpath exists; most of it is integration-facing plumbing — the bridge exposing the runtime’s serializer machinery for the runtime’s own entries and for integrations building transports — exempt from the 2.0 stability guarantee and subject to change. The one application-facing part is plugin _authoring_: `createPlugin` and `OpaqueReference` are re-exported there from the runtime’s own seroval instance, and custom plugins for the `codec` option must be built from that import — a plugin built against your own `seroval` dependency edge would not fail the build, it would emit nodes the other end of the wire can’t interpret (the version-pinning lesson of solid-start #1474). Application and router code authors plugins there and feeds them to `codec`; everything else on the subpath it should leave alone.)
47+
**Client:** `configureServerFunctionsClient({ endpoint?, codec?, fetch?, prepareRequest?, serializeArgs?, responseHandler? })` — call once in the client entry, only when deviating from the defaults (endpoint defaults to `/_server`; `codec` takes seroval plugin options and must match the server’s; `fetch` replaces the function the transport sends with — always called as `(address, init)` — for concerns the runtime has no opinion about: retries, telemetry, a test double, or pointing calls at a route of the app’s own, which the handler serves through the same `Request` it serves everything else with; `prepareRequest` is the transport middleware hook below; `responseHandler` is the integration seam server components install — see [RFC 11](11-server-components.md)). Compiled client output produces callables that POST to the call’s **data address** — `<endpoint>/data/<id>`, the id in a path segment — with no per-call header of their own (a read is exactly its url to caches and `<link rel="preload">`). The data address is the scripted transport’s own path, where answers are the codec’s; the bare `<endpoint>/<id>` address (a reference’s `.url`, what renders into form actions) answers plain HTTP. Two paths because the two caller kinds get differently shaped answers and shared caches key on the URL: with one shape per path, a cached answer can only ever be replayed to the caller kind it was made for. (A third caller kind, `live`'s loop, gets a third path — `<endpoint>/live/<id>`, answered as an event stream; same rule.) **Argument encoding (updated since first draft):** arguments with a natural HTTP encoding (a lone string, FormData, File, Blob, ...) go as-is; everything else is sent as **plain JSON by default** — no serializer in the client bundle — and values JSON can’t carry faithfully (Dates, Maps, Sets, typed arrays, cycles, a top-level `undefined` — except in a bound call whose trailing argument is a body-like object (FormData, URLSearchParams, File, Blob, ...), where the leading arguments ride `?args=` and `undefined` is sent as `null` as in the action url; a trailing string is not a body in this sense, so `fn(1, undefined, "str")` goes through the codec) **throw with a directed message** unless you opt in once via `enableRichArguments()` from `@solidjs/web/server-functions/rich-args`, which installs the codec’s write half (~5 KB gz) as `serializeArgs` — importing the entry is the opt-in at the module-graph level, so the serializer ships only when the app asks for it. With the codec on, files and blobs can sit anywhere in the arguments: next to other arguments, or inside arrays, objects, maps, sets and `FormData` entries. Such a call sends multipart form data, with the codec output in an `args` field and each file as it is in its own `file<index>` part (still `X-Server-Function-Format: 0`; the `multipart/form-data` content type marks the upload). A file used twice is sent once and arrives as one value, a `Blob` arrives as a `File` named `blob`, and `bodySizeLimit` bounds the whole body. _Results_ are unaffected — they always travel through the codec, whose decode half the client carries regardless. Async returns (promises, streams) settle over the open connection via length-prefixed chunk framing; a `live` source's response — requested at the live address — is the same stream framed as server-sent events (see `live(fn)` under the extension surface). (A `@solidjs/web/serialization` subpath exists; most of it is integration-facing plumbing — the bridge exposing the runtime’s serializer machinery for the runtime’s own entries and for integrations building transports — exempt from the 2.0 stability guarantee and subject to change. The one application-facing part is plugin _authoring_: `createPlugin` and `OpaqueReference` are re-exported there from the runtime’s own seroval instance, and custom plugins for the `codec` option must be built from that import — a plugin built against your own `seroval` dependency edge would not fail the build, it would emit nodes the other end of the wire can’t interpret (the version-pinning lesson of solid-start #1474). Application and router code authors plugins there and feeds them to `codec`; everything else on the subpath it should leave alone.)
4848

4949
**Server:** `configureServerFunctionsServer({ endpoint?, codec?, provideEvent?, wrapInvocation?, collectFlightData?, transformResult?, transformDirectResult? })` plus the web-standard HTTP handler:
5050

‎packages/web/server-functions/src/argument-codec.ts‎

Lines changed: 15 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -118,12 +118,24 @@ function encodeRefusal(name) {
118118

119119
let encodeRefusals;
120120

121-
/** The configured codec options with encode-side refusals ahead of every plugin. */
122-
export function argumentEncodeCodec(codec) {
121+
/**
122+
* The configured codec options with encode-side refusals ahead of every
123+
* plugin. `extra` holds plugins for one call (the upload serializer), which
124+
* go first.
125+
*/
126+
export function argumentEncodeCodec(codec, extra = []) {
123127
if (!encodeRefusals) encodeRefusals = [encodeRefusal("Response"), encodeRefusal("Request")];
124-
const refusals = encodeRefusals;
128+
const refusals = extra.length ? [...extra, ...encodeRefusals] : encodeRefusals;
125129
return {
126130
...codec,
127131
plugins: codec && codec.plugins ? [...refusals, ...codec.plugins] : refusals
128132
};
129133
}
134+
135+
/**
136+
* Decode options from `argumentDecodeCodec` with plugins for one request
137+
* (the upload deserializer) ahead of the resolved list.
138+
*/
139+
export function withArgumentPlugins(argumentCodec, extra) {
140+
return { ...argumentCodec, [RESOLVED_PLUGINS]: [...extra, ...argumentCodec[RESOLVED_PLUGINS]] };
141+
}

‎packages/web/server-functions/src/client.ts‎

Lines changed: 9 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -307,9 +307,11 @@ export interface ServerFunctionsClientConfig {
307307
* Encoder for argument lists JSON can't carry faithfully. JSON-safe args
308308
* always go as plain JSON (no codec in the bundle); anything else throws
309309
* unless this is set. Installed by `enableRichArguments()` from the
310-
* rich-args entry — set directly only for custom wire encodings.
310+
* rich-args entry — set directly only for custom wire encodings. A
311+
* `FormData` answer is sent as an upload: the codec output in its `args`
312+
* field and each file in a `file<index>` part.
311313
*/
312-
serializeArgs?(args: unknown[]): string | Promise<string>;
314+
serializeArgs?(args: unknown[]): string | FormData | Promise<string | FormData>;
313315
}
314316

315317
/** Wire-state transitions a live call's iterable can report. */
@@ -434,7 +436,7 @@ function serializeArguments(args) {
434436
"Server function arguments are sent as JSON by default and these " +
435437
"arguments are not JSON-serializable. Call enableRichArguments() " +
436438
'(from "@solidjs/web/server-functions/rich-args") once at startup ' +
437-
"to send Dates, Maps, Sets, typed arrays, etc. through the codec — " +
439+
"to send Dates, Maps, Sets, typed arrays, files, etc. through the codec — " +
438440
"or pass a single Blob/FormData/File argument, which has a native " +
439441
"HTTP encoding."
440442
);
@@ -760,6 +762,10 @@ async function initializeResponse(base, id, options, args, meta) {
760762
}
761763
}
762764
// Everything else needs the codec, which is opt-in (enableRichArguments).
765+
// The encoder answers `FormData` when the arguments hold files (see
766+
// uploads.js). No content type is set here: fetch gives a string body
767+
// `text/plain` and a form its multipart boundary, which is how the handler
768+
// tells the two apart.
763769
return createRequest(
764770
base,
765771
id,
@@ -768,7 +774,6 @@ async function initializeResponse(base, id, options, args, meta) {
768774
body: await serializeArguments(args),
769775
headers: {
770776
...options.headers,
771-
"Content-Type": "text/plain",
772777
[BODY_FORMAT_HEADER]: BodyFormat.Serialized
773778
}
774779
},

‎packages/web/server-functions/src/rich-args.ts‎

Lines changed: 12 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,8 @@
1111
// results as plain JSON and only rich results wake the decode half.
1212
import { getServerFunctionsCodec, serializeString } from "./shared.js";
1313
import { configureServerFunctionsClient } from "./client.js";
14-
import { argumentEncodeCodec } from "./argument-codec.js"; /**
14+
import { argumentEncodeCodec } from "./argument-codec.js";
15+
import { createUploadBody, createUploadSerializer } from "./uploads.js"; /**
1516
* Opt-in codec encoding for server-function ARGUMENTS. By default the client
1617
* sends argument lists as plain JSON (no serializer in the bundle) and
1718
* throws on values JSON can't carry faithfully. Call once at startup to
@@ -20,12 +21,20 @@ import { argumentEncodeCodec } from "./argument-codec.js"; /**
2021
* the decode half responses already need). The handler accepts both
2122
* encodings unconditionally. `Response` and `Request` values are refused
2223
* (the call rejects before anything is sent): the handler never decodes
23-
* them from arguments.
24+
* them from arguments. Files and blobs can sit anywhere in the arguments:
25+
* the call then sends multipart form data with each file as its own part.
2426
*/
2527
export function enableRichArguments(): void;
2628

2729
export function enableRichArguments() {
2830
configureServerFunctionsClient({
29-
serializeArgs: args => serializeString(args, argumentEncodeCodec(getServerFunctionsCodec()))
31+
serializeArgs: async args => {
32+
const files = [];
33+
const serialized = await serializeString(
34+
args,
35+
argumentEncodeCodec(getServerFunctionsCodec(), [createUploadSerializer(files)])
36+
);
37+
return files.length ? await createUploadBody(serialized, files) : serialized;
38+
}
3039
});
3140
}

‎packages/web/server-functions/src/server.ts‎

Lines changed: 22 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -31,8 +31,10 @@ import {
3131
argumentDecodeCodec,
3232
namesRefusedType,
3333
refusedArgument,
34-
refusedArgumentError
34+
refusedArgumentError,
35+
withArgumentPlugins
3536
} from "./argument-codec.js";
37+
import { UPLOAD_ARGS_PART, createUploadDeserializer } from "./uploads.js";
3638
import {
3739
BODY_FORMAT_HEADER,
3840
BodyFormat,
@@ -2053,7 +2055,25 @@ async function parseArguments(request, url, scripted, codec, buffered) {
20532055
if (bodyFormat === BodyFormat.Serialized) {
20542056
let argumentCodec = argumentCodecFor(codec);
20552057
if (argumentCodec instanceof Promise) argumentCodec = await argumentCodec;
2056-
decoded = await decodeArguments(wire => extractBody(body, argumentCodec, wire), buffered);
2058+
if ((request.headers.get("content-type") || "").startsWith("multipart/form-data")) {
2059+
// A codec argument list with its files as form parts (see uploads.js).
2060+
// The tag stays `Serialized` so the client runtime pays nothing for
2061+
// uploads; the multipart content type is what marks one. The upload
2062+
// plugin is made for this request only, so a file index means
2063+
// something here and nowhere else.
2064+
const form = await body.formData();
2065+
const encoded = form.get(UPLOAD_ARGS_PART);
2066+
if (typeof encoded !== "string") {
2067+
throw new TypeError("Malformed server function upload");
2068+
}
2069+
const uploadCodec = withArgumentPlugins(argumentCodec, [createUploadDeserializer(form)]);
2070+
decoded = await decodeArguments(
2071+
wire => deserializeStream(new Response(encoded), uploadCodec, wire),
2072+
encoded
2073+
);
2074+
} else {
2075+
decoded = await decodeArguments(wire => extractBody(body, argumentCodec, wire), buffered);
2076+
}
20572077
} else {
20582078
decoded = await extractBody(body, codec);
20592079
}
Lines changed: 108 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,108 @@
1+
// @ts-nocheck
2+
// Files and blobs in server function arguments, on the codec path.
3+
//
4+
// The client sends a call whose arguments hold files as multipart form data:
5+
// - the codec output in the `UPLOAD_ARGS_PART` field;
6+
// - each file in its own `UPLOAD_FILE_PART<index>` part, as it is, without
7+
// base64.
8+
// The codec output holds only each file's index. The request keeps the
9+
// `Serialized` tag; its multipart content type is what marks an upload.
10+
//
11+
// A seroval plugin made for the call finds the files wherever the codec
12+
// meets one: arguments, arrays, objects, maps, sets, and `FormData` entries.
13+
// The server decodes with a plugin made for the request, which turns each
14+
// index back into its part. Any other body decodes without that plugin, so
15+
// an index in a plain codec body fails to decode.
16+
//
17+
// Ported from SolidStart (solidjs/solid-start#2359).
18+
19+
export const UPLOAD_ARGS_PART = "args";
20+
export const UPLOAD_FILE_PART = "file";
21+
22+
const UPLOAD_TAG = "solid/server-function-upload";
23+
24+
/**
25+
* True for a file or a blob. One from another frame is an instance of that
26+
* frame's `Blob`, so its shape tells instead.
27+
*/
28+
function isBlob(value) {
29+
if (typeof Blob !== "undefined" && value instanceof Blob) return true;
30+
return (
31+
typeof value === "object" &&
32+
value !== null &&
33+
typeof value.size === "number" &&
34+
typeof value.type === "string" &&
35+
typeof value.arrayBuffer === "function" &&
36+
typeof value.slice === "function"
37+
);
38+
}
39+
40+
function malformed() {
41+
return new TypeError("Malformed server function upload");
42+
}
43+
44+
/**
45+
* The client half. Each file or blob in the arguments serializes as its
46+
* index in `files`. A file that appears twice is pushed once, so it arrives
47+
* as one value.
48+
*/
49+
export function createUploadSerializer(files) {
50+
const indexOf = value => {
51+
const index = files.indexOf(value);
52+
return index === -1 ? files.push(value) - 1 : index;
53+
};
54+
return {
55+
tag: UPLOAD_TAG,
56+
test: isBlob,
57+
parse: {
58+
sync: (value, ctx) => ({ i: ctx.parse(indexOf(value)) }),
59+
async: async (value, ctx) => ({ i: await ctx.parse(indexOf(value)) }),
60+
stream: (value, ctx) => ({ i: ctx.parse(indexOf(value)) })
61+
},
62+
serialize: (node, ctx) => ctx.serialize(node.i),
63+
deserialize: () => {
64+
throw malformed();
65+
}
66+
};
67+
}
68+
69+
/**
70+
* The server half, made for one request. Each index turns back into its
71+
* part of `form`. A bad index or a missing part fails the decode.
72+
*/
73+
export function createUploadDeserializer(form) {
74+
const refuse = () => {
75+
throw malformed();
76+
};
77+
return {
78+
tag: UPLOAD_TAG,
79+
test: () => false,
80+
parse: { sync: refuse, async: refuse, stream: refuse },
81+
serialize: refuse,
82+
deserialize: (node, ctx) => {
83+
const index = ctx.deserialize(node.i);
84+
if (typeof index !== "number" || !Number.isSafeInteger(index) || index < 0) refuse();
85+
const part = form.get(UPLOAD_FILE_PART + index);
86+
if (!isBlob(part)) refuse();
87+
return part;
88+
}
89+
};
90+
}
91+
92+
/**
93+
* The request body for a call with files. `FormData` only takes blobs of its
94+
* own frame, so a blob from another frame is copied first.
95+
*/
96+
export async function createUploadBody(serialized, files) {
97+
const form = new FormData();
98+
form.set(UPLOAD_ARGS_PART, serialized);
99+
const blobs = await Promise.all(
100+
files.map(async file =>
101+
file instanceof Blob ? file : new Blob([await file.arrayBuffer()], { type: file.type })
102+
)
103+
);
104+
for (let i = 0; i < blobs.length; i++) {
105+
form.set(UPLOAD_FILE_PART + i, blobs[i], files[i].name ?? "blob");
106+
}
107+
return form;
108+
}

0 commit comments

Comments
 (0)