Rewrite batch mode to use temp directory

[requilence]

Problem

When uploading large files through UnixFS or other IPLD structures, the current batch implementation keeps everything in memory and writes blocks individually. If the application crashes mid-process, partial blocks remain in FlatFS, making garbage collection extremely difficult since there's no way to identify which blocks belong to incomplete operations.

Solution

This PR rewrites the batch mode to use a temporary directory approach:

1. Atomic batch operations: All blocks in a batch are written to a temporary directory first, then renamed to their final locations only on commit. If the process crashes, no partial data remains in the main datastore - the temp directory is cleaned on restart.
2. Memory efficiency: Instead of keeping all data in memory, blocks are written directly to temp files, enabling large file uploads without high RAM usage.
3. Read operations in batch: Added BatchReader interface implementing Get/Has/GetSize methods. This is essential for IPLD structures which need to verify block links during construction. Without batch reads, you cannot build complex IPLD structures that reference blocks added earlier in the same batch. This follows standard database transaction semantics where reads within a transaction see uncommitted writes.

Implementation Details

• Each batch creates a unique temp directory under .temp/
• Files are written without sharding in temp
• On commit, files are atomically renamed to their sharded destinations
• On discard or crash, temp files are cleaned up (on the next startup). This code was already existing
• Thread-safe with mutex protection
• Batch can be reused after commit/discard (because this behavior of Batch was before my changes)

[welcome]

Thank you for submitting this PR!
A maintainer will be here shortly to review it.
We are super grateful, but we are also overloaded! Help us by making sure that:

• The context for this PR is clear, with relevant discussion, decisions
  and stakeholders linked/mentioned.

• Your contribution itself is clear (code comments, self-review for the
  rest) and in its best form. Follow the code contribution
  guidelines
  if they apply.

Getting other community members to do a review would be great help too on complex PRs (you can ask in the chats/forums). If you are unsure about something, just leave us a comment.
Next steps:

• A maintainer will triage and assign priority to this PR, commenting on
  any missing things and potentially assigning a reviewer for high
  priority items.

• The PR gets reviews, discussed and approvals as needed.

• The PR is merged by maintainers when it has been approved and comments addressed.

We currently aim to provide initial feedback/triaging within two business days. Please keep an eye on any labelling actions, as these will indicate priorities and status of your contribution.
We are very grateful for your contribution!

[gammazero]

Need to review. Check that there is still ability to do in-memory batching for smaller batches.

[gammazero]

My concern is that this will negatively impact the performance of Put. This will make Commit faster because the temp files are already written, but existing code my expect a Put that is not slowed down by writing to the filesystem.

It may be worth considering having Put write the temp files asynchronously in a separate goroutine. Then Commit will wait for any outstanding Put to finish, handle any errors from async Puts , and then move all the temp files to their final destination.

[hsanjuan]

Triage questions that come up:

• Can you describe the scenario in which memory usage of batches becomes a problem? Is this while using Kubo or are you using flatfs and interacting with it in a different application?

[lidel]

Triage notes:

• being able to remove RAM-limit is useful for self-hosted adoption, but comes with some risk
• we could mitigate by do writes async until the final batch commit is executed, and wait for async work

@requilence gentle ping, are you able to answer where this problem/need surfaced? Are yo uusing Kubo or your own implementation? On what hardware are you running?

[gammazero]

Batch can be reused after commit/discard (because this behavior of Batch was before my changes)

I do not think we need or want to guarantee this, because the ability to reuse a Batch was not consistent across different datastores, so should not be done in general.

[requilence]

@lidel Thanks for the review! I've addressed the feedback:

Async Write Operations

• Put now writes to temp files asynchronously in goroutines and returns immediately
• Commit and all read/write operations waits for all async writes to complete before proceeding
• Fail-fast error handling: First async error is captured and returned on next Put/Delete/Commit or any read operation, preventing unnecessary work if disk is full or other errors occur

[requilence]

Triage questions that come up:

• Can you describe the scenario in which memory usage of batches becomes a problem? Is this while using Kubo, or are you using flatfs and interacting with it in a different application?

We are using flatfs and the IPLD structures in Anytype (http://github.com/anyproto/anytype-heart) to store files on users' devices. If we are not using a batch operation, we can find ourselves in a situation where the user force-closes the app in the middle of a large file (e.g., 4 GB video) addin, which will leave a lot of garbage blocks in flatfs. Therefore, we are using atomic batch operations. At the same time, we are trying to avoid heap allocations and reusing memory, as it is especially critical on mobile devices.

@lidel, I'm not sure async Put is really a good option for us. We would prefer to do it synchronously; otherwise, it could lead to heap spikes. I'm considering a clean way to make this configurable while maintaining backward compatibility. Perhaps a new OpenWithArgs that will have variadic arguments? It will also be possible to override the fs.FS implementation with a custom or mocked version.

[gammazero]

@requilence

I'm not sure async Put is really a good option for us. We would prefer to do it synchronously

Consider limiting the number of asynchronous write operations. I think that it is reasonable for an async write operation to wait until the previous async write operation has completed. This will allow a write function to return immediately, while the work is done during accumulation of operations in the next batch.

Additionally, there could be an option to enable/disable asynchronous puts. Although this is probably not necessary if above limit is implemented.

[gammazero]

See and commit suggestions: Added a semaphore to limit concurrent puts

[lidel]

I tried to document the current state (see godoc drafts in comments below) and one things that stands out is O(n) related to linear seartch in puts – not sure how big of an impact this is, but we already have O(1) for deletes so maybe do the same for puts? (details inline).

If we do that, godoc should be updated to relfect that.

[gammazero]

Triage: We will look at this after kubo v0.39