feat: support stream uploads to Synapse

[shrirajpawar4]

Summary

addresses part of #325.

Adds ReadableStream<Uint8Array> support to the shared Synapse upload helpers so callers with pre-generated CAR files can stream upload data without first loading the whole CAR into memory.

Changes

• Add SynapseUploadData = Uint8Array | ReadableStream<Uint8Array>
• Update uploadToSynapse() and executeUpload() to accept SynapseUploadData
• Pass upload data directly through to synapse.storage.upload() without buffering
• Export the new upload data type from the public upload/type surface
• Add unit coverage proving stream objects are forwarded unchanged
• Update the CAR upload example to show streaming from disk with Readable.toWeb(createReadStream(...))

Notes

This intentionally does not implement true CAR creation streaming from #288, and it does not add byte-level progress callbacks from #326. This PR only covers uploading an already-created CAR as a stream. Will create separet PR for #326

Testing

pnpm run typecheck
pnpm exec vitest run --project unit src/test/unit/synapse-service.test.ts src/test/unit/upload-validation.test.ts
pnpm test

Full pnpm test passed locally:

- 37 test files passed
- 372 tests passed
- 11 skipped

[rvagg]

This looks pretty good, tightly scoped and solves the specific issue.

There's one additional thing you could do with this @shrirajpawar4, you look in src/import/import.ts you'll see we await readFile(options.filePath) for filecoin-pin import; we should be streaming that out. And I think the change is pretty simple there, we stat() separately and we even read the root CID from the CAR separately (using a stream).

[rvagg]

@shrirajpawar4 have a look at #287 which was a draft of a previous attempt and it does a few more things. I think the code might have moved on from that PR but it had a bit more, including streaming the temp car for add operations which you can do as well, and there's some minor changes to the docs in there but as per my comment we can't over-promise because we still cache things on disk and add is still bad in the browser because it makes a temp CAR in memory before streaming it out. So don't overpromise like the original text in there.
Also watch mocks when readFile is replaced with createReadStream, I think we need to add stat in there.

But, if you'd prefer to land this one first and do a follow-up with the second batch we can do that; this is a decent start but it shouldn't be hard to go a bit further.

[shrirajpawar4]

Thanks @rvagg . I applied the README suggestion and updated filecoin-pin import to stream the CAR file from disk instead of reading it fully into memory before upload.

I kept the broader add / server / action streaming work out of this PR so this can stay focused on #325; I can handle that as a follow up after this lands.

[SgtPooki]

short and sweet, nice PR. Just a few things to touch up and i'm good with it.

[shrirajpawar4]

@SgtPooki made changes ser.

[HavenCTO]

Approve this unblocks the streaming contract we need, thanks for the implementation!

[rvagg]

lgtm but we'll just have to make sure t he linked issue stays open so we can track the other part of t his

[shrirajpawar4]

@rvagg yes works, will close out the issue in next PR.