# What Happens When a Provider Advertises the Buffered‑Write Surface in the FUSE Driver

> Discover how a FUSE driver switches to buffered mode when a provider advertises the buffered-write surface, optimizing write operations in cloudflare/computer.

- Repository: [Cloudflare/computer](https://github.com/cloudflare/computer)
- Tags: internals
- Published: 2026-08-13

---

**When a VFS provider implements the buffered‑write API methods—including `openWriteBufferSync`, `releaseWriteBufferSync`, and optionally `openWriteBufferForCreateSync`—the FUSE driver in cloudflare/computer switches from pure‑direct‑write mode to a hybrid buffered mode that accumulates writes in memory and flushes them only on `fsync`, `flush`, or `release`.**

The FUSE driver in the **cloudflare/computer** repository dynamically adapts its write strategy based on provider capabilities. When a provider advertises the buffered‑write surface in the FUSE driver, the system enables an in‑memory buffering layer that batches small writes and defers persistence until explicit synchronization points, eliminating per‑write system‑call overhead and enabling atomic write semantics.

## Detection of the Buffered‑Write Surface

Early in [`packages/computerd/src/fuse/driver.ts`](https://github.com/cloudflare/computer/blob/main/packages/computerd/src/fuse/driver.ts), the driver inspects the supplied `vfs` object to determine which write surface the provider supports. The detection logic first verifies **direct‑write** primitives, then checks for **buffered‑write** extensions:

```typescript
const hasDirectWrites =
  directWriteVfs.createFileSync !== undefined &&
  directWriteVfs.writeRangeSync !== undefined &&
  directWriteVfs.truncateFileSync !== undefined;

const hasBufferedWrites =
  hasDirectWrites &&
  directWriteVfs.openWriteBufferSync !== undefined &&
  directWriteVfs.releaseWriteBufferSync !== undefined;

const hasDeferredCreate =
  hasBufferedWrites && directWriteVfs.openWriteBufferForCreateSync !== undefined;

```

If `hasBufferedWrites` evaluates to true, the driver initializes the **hybrid buffered mode**. This mode creates an in‑memory `Buffer` for each `FileEntry` and tracks dirty ranges rather than forwarding every write immediately to the underlying VFS.

## In‑Memory Buffering Architecture

For every opened file, the driver instantiates a `FileEntry` structure that holds an in‑memory buffer (`entry.buf`). Write operations apply changes exclusively to this buffer, and the entry is marked *dirty* with a list of modified ranges (`entry.dirtyRanges`). 

This design provides two immediate benefits:

- **Eliminated round‑trips**: Small, frequent writes complete entirely in memory without system calls to the provider.
- **Dirty‑range tracking**: The driver maintains precise metadata about which byte ranges have changed, enabling efficient ranged writes during flush.

No data touches the underlying VFS during the write syscall itself. The provider remains unaware of the file changes until the driver explicitly flushes the buffer.

## Deferred File Creation Semantics

When the provider also implements `openWriteBufferForCreateSync`, the driver supports **deferred file creation**. In this pattern, the driver calls the provider’s `createFileSync` early to establish the inode and metadata, but keeps the file content empty in the VFS backend.

This approach satisfies "create‑on‑open" semantics while deferring the bulk data transfer. The file exists in the namespace immediately, yet the provider stores no data until the buffered content flushes. This is particularly useful for providers that charge per byte stored or require atomic file appearance.

## Flush and Persistence Mechanism

The driver persists buffered data through the `flushEntry(path)` function, invoked during `flush`, `release`, or explicit `fsync` operations. According to the implementation in [`packages/computerd/src/fuse/driver.ts`](https://github.com/cloudflare/computer/blob/main/packages/computerd/src/fuse/driver.ts) (lines 66‑86), this function:

1. Extracts the dirty slice from the in‑memory buffer using the accumulated `dirtyRanges`.
2. Decides between **ranged writes** (`writeFileRangesSync`) or a **full write** (`writeFileSync`) based on the provider’s preferences and the distribution of dirty ranges.
3. Passes the original mode bits to preserve file permissions.
4. Clears dirty flags and releases the buffer reference.

If the provider prefers ranged writes, the driver supplies the specific dirty ranges, allowing the VFS backend to apply only the changed portions rather than rewriting the entire file.

## Error Handling and Limits

All buffer‑related operations return **POSIX‑style error numbers**. The driver translates JavaScript exceptions into errno values using `toErrno(error)` before surfacing them to the kernel. For example, if a write would cause the file to exceed `MAX_FILE_BYTES`, the driver returns `ERRNO.EFBIG`.

This error translation ensures that applications interacting with the FUSE mount receive standard Linux error codes (like `EFBIG`, `ENOMEM`, or `EIO`) rather than Java stack traces or internal exceptions.

## Code Example: Implementing the Buffered‑Write Surface

To advertise the buffered‑write surface, a provider must implement the extended interface:

```typescript
import { DirectWriteVfs } from '@cloudflare/computer';

interface BufferedWriteVfs extends DirectWriteVfs {
  openWriteBufferSync(path: string): void;
  releaseWriteBufferSync(path: string): void;
  // Optional: enables deferred creation
  openWriteBufferForCreateSync(
    path: string, 
    options: { mode: number }
  ): void;
}

const vfs: BufferedWriteVfs = {
  createFileSync(path, mode) { /* ... */ },
  writeRangeSync(path, offset, data) { /* ... */ },
  truncateFileSync(path, size) { /* ... */ },
  openWriteBufferSync(path) { /* allocate temp resources */ },
  releaseWriteBufferSync(path) { /* cleanup */ },
  openWriteBufferForCreateSync(path, { mode }) { /* create empty inode */ }
};

// Mount with FUSE driver
const fuse = new FuseDriver(vfs);
fuse.mount('/mnt/computer');

```

When application code writes to `/mnt/computer`, the driver buffers the data internally:

```typescript
import { writeFileSync, sync } from 'fs';

// Buffered in memory; no VFS call yet
writeFileSync('/mnt/computer/buffered.bin', Buffer.from('buffered-write'));

// Forces flushEntry() and persists to provider
sync('/mnt/computer/buffered.bin');

```

## Summary

When a provider advertises the buffered‑write surface in the FUSE driver, the system behavior changes significantly:

- **Capability detection** in [`packages/computerd/src/fuse/driver.ts`](https://github.com/cloudflare/computer/blob/main/packages/computerd/src/fuse/driver.ts) checks for `openWriteBufferSync` and `releaseWriteBufferSync` to enable hybrid mode.
- **In‑memory buffering** accumulates writes in a `FileEntry` buffer, tracking dirty ranges without immediate VFS round‑trips.
- **Deferred creation** allows early inode allocation via `openWriteBufferForCreateSync` while postponing data transfer.
- **Atomic flushing** via `flushEntry` writes dirty ranges using either `writeFileRangesSync` or `writeFileSync`, clearing buffers only after successful persistence.
- **POSIX error translation** ensures standard errno values (like `EFBIG` for files exceeding `MAX_FILE_BYTES`) reach the application layer.

## Frequently Asked Questions

### How does the FUSE driver detect buffered‑write support?

The driver inspects the provider object at initialization in [`packages/computerd/src/fuse/driver.ts`](https://github.com/cloudflare/computer/blob/main/packages/computerd/src/fuse/driver.ts). It verifies that `openWriteBufferSync` and `releaseWriteBufferSync` are defined as functions on the VFS object. If these methods exist alongside the base direct‑write primitives, the driver sets `hasBufferedWrites` to true and initializes the buffering layer.

### What is the difference between direct writes and buffered writes in this driver?

**Direct writes** invoke `writeRangeSync` or `truncateFileSync` immediately for every operation, causing a system‑call round‑trip per write. **Buffered writes** store data in a `FileEntry` memory buffer and apply changes only during `flush` or `release`, batching multiple small writes into a single VFS operation and reducing overhead.

### When does the driver actually write data to the underlying VFS?

The driver persists buffered data when it calls `flushEntry(path)`, which occurs during explicit `fsync` operations, implicit `flush` requests from the kernel, or final `release` when the file descriptor closes. Until one of these events fires, the data remains exclusively in the driver’s memory buffer.

### What happens if a buffered write exceeds MAX_FILE_BYTES?

The driver returns `ERRNO.EFBIG` (file too large) during the write operation. This error propagates through the `toErrno(error)` translation layer and surfaces to the application as a standard POSIX `EFBIG` error code, preventing the buffer from growing beyond the configured `MAX_FILE_BYTES` limit.