Native @aws-sdk/client-s3 (+ s3-request-presigner) and fastify multipart/form-data parsing

[proggeramlug]

Context

Porting sharity-api (Express + Mongoose, ~23k LoC) to Perry. Two
adjacent gaps block every upload flow: server-side multipart parsing
and AWS S3.

Multipart / form-data on fastify

The Fastify server in perry-ext-fastify handles JSON bodies, but every
upload route in the target app is multipart/form-data — avatars, cover
photos, item images. Need a multer-equivalent or fastify-multipart-style
plugin with:

• Disk and memory storage modes
• File size limits (limits: { fileSize: 5 * 1024 * 1024 })
• MIME filter (fileFilter: (file) => /^image\//.test(file.mimetype))
• Multiple field names (avatar, image, cover-photo)
• Generated filenames (UUID + original extension)
• Stream the file body without buffering the whole multipart payload in
  memory

AWS S3

Sharity-api uses S3 as the canonical image store. Local disk fallback
exists but isn't viable in production. Surface needed:

• @aws-sdk/client-s3: PutObjectCommand, GetObjectCommand,
  DeleteObjectCommand, HeadObjectCommand
• @aws-sdk/s3-request-presigner: getSignedUrl(command, {expiresIn})
• Region + credential resolution from env (AWS_REGION,
  AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_S3_BUCKET_NAME)
• ACL support (public-read is what the existing app uses)

Acceptance

A fastify route that accepts a multipart upload, streams it to S3 with
PutObjectCommand, and returns a presigned GET URL for the uploaded key.
Compiles and runs against real S3 (or LocalStack) under perry run.

Why both in one issue

The two together are how every upload endpoint in a typical Node API is
wired. Splitting them lets the multipart side ship without S3 (still
useful for disk-only setups), but the issue tracks both because
sharity-api needs both.

[proggeramlug]

Researched the pure-JS S3 ecosystem before sketching a perry-ext-s3 Rust binding. The best fit is @bradenmacdonald/s3-lite-client (MIT, zero deps, ~1.9k LoC across 4 runtime files).

Audited it against Perry's TS-subset:

• ✅ No eval / new Function / dynamic imports
• ✅ No Symbol(...) / Proxy / WeakMap / Reflect
• ✅ No decorators / lookbehind regex / prototype manipulation / computed property keys
• ✅ No Node-specific Buffer / node:stream / node:crypto — Web APIs only

Surface coverage: PutObject, GetObject, DeleteObject, statObject (Head), copyObject, listObjects, presignedGetObject / presignedPutObject / presignPostV4, multipart streaming uploads, ACL (x-amz-acl: private | public-read | …). Matches everything #551 lists.

Two stdlib gaps block native compilation today:

• crypto.subtle.digest / importKey / sign (HMAC-SHA-256, SHA-256) — Web Crypto: implement crypto.subtle.digest / importKey / sign (HMAC-SHA-256, SHA-256) #561
• Extending WritableStream / TransformStream — Web Streams: allow user classes to extend WritableStream / TransformStream / ReadableStream #562

Both are general-purpose primitives many other packages will need. Read paths (getObject, statObject, deleteObject, listObjects, presignedGetObject, presignedPostObject) hit only #561; the streaming upload path needs #562 too.

With both landed, s3-lite-client should compile via perry.compilePackages with no patches. Bonus: it speaks any S3-compatible endpoint (R2, MinIO, B2, Spaces, Supabase, LocalStack) for free — a perry-ext-s3 Rust binding would lock you into AWS-only unless endpoint flexibility is re-implemented.

Multipart/form-data parsing on fastify is the orthogonal half of #551 and not addressed here — that's @fastify/multipart (busboy-based) territory, separate research.

[proggeramlug]

First compile attempt at v0.5.655 (post #561 + #562) — got 9 of 10 modules through HIR + codegen. Three new gaps surfaced underneath, all with reproducible repros:

• codegen: String.prototype.split rejects 2-arg form (separator, limit) #567 — String.prototype.split(sep, limit) 2-arg form rejected by codegen. Hits signing.ts:254 which uses element.split("=", 2) for SigV4 query-string canonicalization. Hard blocker.
• cross-module method dispatch: export { X as Y } rename produces undefined-symbol link error #568 — export { Client as S3Client } rename produces undefined-symbol link error. Source-side emits Client__greet, consumer-side calls S3Client__greet, link fails. Hard blocker, structural (not s3-lite-specific).
• HIR: function-scoped function declarations not hoisted — silent runtime undefined #569 — Function-scoped function declarations not hoisted at HIR lowering. xml-parser.ts (recursive-descent parser shape, ~10 inner functions) compiles with warnings then returns undefined at runtime. Silent runtime corruption — every S3 XML response would parse to garbage.

With those three landed, this should compile + run for at least the read paths (Get/Head/Delete/List/presigned*).

[proggeramlug]

v0.5.663 (post #567 + #568 + #569): the package compiles and links cleanly. Read-path runtime exposes three more gaps, all with reproducible repros:

• HIR/codegen: object-destructure pattern in class method/ctor params binds every name to 0 #572 — Object-destructure pattern in class methods / constructors binds every name to 0. Top-level functions are fine; class members are broken. Hits S3Client's constructor({ endPoint, useSSL, port, pathPrefix, ...params }) — every param arrives as 0, the validation chain trips and throws immediately. Hard blocker, structural.
• runtime: class X extends Error {} (bare) loses constructor args + SIGABRT on property access #573 — class X extends Error {} (bare-derived) drops the super(msg) arg and produces an instance with .name / .message undefined; intermittent SIGABRT on first property access. Hits the entire s3-lite error hierarchy (S3Error → InvalidArgumentError → InvalidEndpointError → ...).
• imports: import * as Ns from "./mod.js" produces non-object namespace; class members unreachable #574 — import * as Ns from "./mod.js" produces a non-object namespace where class exports are unreachable (primitive consts partially work). Hits export * as S3Errors from "./errors.js" and breaks every instanceof S3Errors.ServerError check.

All three are general-purpose gaps that will hit any modern TS-style npm package, not just s3-lite. With them landed I'll re-test.

[proggeramlug]

v0.5.664 (post #572 + #573 + #574): the package compiles, links, runs, and produces a presigned URL end-to-end. Constructor works, all imports resolve, the SigV4 chain runs without crashing, and a URL string comes back. Big jump.

The URL is structurally correct but has two correctness bugs:

.../hello.txt?%5Bobject%20Object%5D=&X-Amz-Algorithm=AWS4-HMAC-SHA256&...&X-Amz-SignedHeaders=&X-Amz-Signature=
                ^^^^^^^^^^^^^^^^^^^^                                              ^^^empty^^^   ^^^empty^^^

• stdlib: URLSearchParams.toString() returns "[object Object]" for every input shape #575 — URLSearchParams(...).toString() returns "[object Object]" for every input shape (empty record, populated record, query string). Hits buildRequestOptions and injects the stray ?[object Object]=& segment. Beyond s3-lite, breaks every form-encoder / URL builder.
• stdlib: for…of headers.keys() produces empty iteration; headers.forEach works #576 — for (const k of headers.keys()) iterates zero entries. headers.forEach((v, k) => ...) correctly yields all of them. The SigV4 canonical-request build uses for…of headers.keys() → SignedHeaders is empty → signature is empty → the URL would fail authentication against AWS even though the structure is right.

With those two landed, the URL should match bun byte-for-byte and authenticate against real S3. Read paths (Get/Head/Delete/List/presign) should then work. Upload path needs the cross-module TsParamProp slot bug separately — that one isn't reached yet by the smoke test.