# How the Cloudflare Computer FUSE Driver Falls Back When the Buffered-Write Surface Is Not Exposed

> Discover how the Cloudflare Computer FUSE driver handles unexposed buffered-write surfaces by automatically reverting to direct-write operations and the VFS layer for all data.

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

---

**When the buffered-write surface is not exposed, the Computer FUSE driver automatically falls back to direct-write operations by reverting to the underlying VFS layer for all reads, writes, and metadata queries.**

The [cloudflare/computer](https://github.com/cloudflare/computer) repository implements a FUSE driver that maintains two distinct write paths: buffered writes that keep data in memory before flushing to the VFS, and direct writes that communicate immediately with the VFS provider. When the `hasBufferedWrites` flag indicates that the **buffered-write surface is not exposed**, the driver seamlessly switches to the direct-write path to ensure filesystem operations continue without interruption.

## Understanding the Dual Write Path Architecture

The Computer FUSE driver is designed with flexibility in mind, supporting both high-performance buffered operations and reliable direct I/O.

### Buffered Writes vs. Direct Writes

**Buffered writes** utilize an in-memory write buffer created via `openWriteBufferSync`, allowing the driver to accumulate changes before persisting them to the underlying VFS. **Direct writes** bypass this buffer entirely, with the driver communicating directly to the VFS provider through methods like `writeRangeSync` and `readRangeSync`. When the buffered-write surface is not exposed, the `hasBufferedWrites` boolean prevents the driver from attempting to initialize these memory buffers.

## Fallback Behavior by Operation

The fallback logic is embedded throughout the driver's operation handlers in [`packages/computerd/src/fuse/driver.ts`](https://github.com/cloudflare/computer/blob/main/packages/computerd/src/fuse/driver.ts), ensuring each filesystem operation degrades gracefully to direct VFS calls.

### File Open Operations

In [`driver.ts:22-25`](https://github.com/cloudflare/computer/blob/main/packages/computerd/src/fuse/driver.ts#L22), the `open` handler checks the `hasBufferedWrites` flag before attempting to call `openWriteBufferSync`. When buffered writes are disabled, the driver skips the buffer initialization entirely and proceeds directly to opening the file handle after verifying the path is not a directory.

```typescript
// Open – no buffered surface → just open the handle
if (hasBufferedWrites) {
  directWriteVfs.openWriteBufferSync?.(toVfs(path));
}
cb(0, openFileHandle(path));

```

### Read Operations

The read handler implements a cascading fallback strategy at [`driver.ts:89-108`](https://github.com/cloudflare/computer/blob/main/packages/computerd/src/fuse/driver.ts#L89). When a file is not found in the driver's in-memory `files` map, the driver first checks for `directWriteVfs.readRangeSync` to serve the request directly from the VFS. If the direct-read method is unavailable, it falls back to `vfs.readFileSync`, hydrates an entry from the persisted data, and serves the read from that snapshot.

```typescript
// Read – fallback to direct VFS read if no buffered entry
if (entry === undefined) {
  if (hasDirectWrites && directWriteVfs.readRangeSync) {
    const slice = directWriteVfs.readRangeSync(toVfs(path), position, length);
    // …serve slice…
  } else {
    const data = vfs.readFileSync(toVfs(path));
    // …hydrate entry and serve from `data`…
  }
}

```

### Write Operations

For write operations at [`driver.ts:45-68`](https://github.com/cloudflare/computer/blob/main/packages/computerd/src/fuse/driver.ts#L45), the driver never attempts to open a write buffer when `hasBufferedWrites` is false. Instead, it checks for `hasDirectWrites` and forwards the operation to `directWriteVfs.writeRangeSync` when available. If direct writes are also unavailable, the driver reads the existing file from the VFS, creates a new in-memory entry, and writes into that transient entry.

### Attribute and Directory Operations

The `getattr` handler at [`driver.ts:77-84`](https://github.com/cloudflare/computer/blob/main/packages/computerd/src/fuse/driver.ts#L77) prefers the size stored in the in-memory entry (`entry.size`) when present. If no buffered entry exists, it returns stats from the underlying VFS inode using `vfs.lstatSync`. Directory operations such as `readdir` and `opendir` at [`driver.ts:64-71`](https://github.com/cloudflare/computer/blob/main/packages/computerd/src/fuse/driver.ts#L64) rely exclusively on `vfs.readdirSync` and `vfs.statSync`, remaining unaffected by the buffered-write surface status.

```typescript
// Getattr – use VFS stats when no buffered entry
const stat = entry?.pendingCreate
  ? pendingStat(entry)
  : statNode(vfs.lstatSync(toVfs(path)));
if (entry !== undefined) {
  stat.size = entry.size;           // buffered size overrides VFS size
  stat.blocks = blocksForSize(entry.size);
}

```

## Implementation Details in driver.ts

According to the cloudflare/computer source code, the core fallback logic resides in [`packages/computerd/src/fuse/driver.ts`](https://github.com/cloudflare/computer/blob/main/packages/computerd/src/fuse/driver.ts), where conditional checks against `hasBufferedWrites` determine whether to invoke buffered operations or revert to the VFS layer. This design ensures that even when the kernel does not expose the buffer via `openWriteBufferSync`, the filesystem continues to function by delegating all operations to the stable VFS interface.

Key source files supporting this behavior include:

- [`packages/computerd/src/fuse/driver.ts`](https://github.com/cloudflare/computer/blob/main/packages/computerd/src/fuse/driver.ts) — Contains the primary fallback logic for open, read, write, and getattr operations.
- [`packages/computerd/src/fuse/driver.test.ts`](https://github.com/cloudflare/computer/blob/main/packages/computerd/src/fuse/driver.test.ts) — Validates that FUSE direct reads do not force later writes onto the buffered fallback.
- [`packages/dofs/src/fs/writeBuffer.test.ts`](https://github.com/cloudflare/computer/blob/main/packages/dofs/src/fs/writeBuffer.test.ts) — Tests the buffered-write lifecycle and driver behavior when the buffer is absent.

## Summary

- When `hasBufferedWrites` is false, the driver automatically **reverts to the VFS layer** for all reads, writes, and metadata queries.
- The **open** operation skips `openWriteBufferSync` and opens file handles directly when buffered writes are unavailable.
- **Read operations** cascade from `directWriteVfs.readRangeSync` to `vfs.readFileSync` depending on available interfaces.
- **Write operations** forward to `directWriteVfs.writeRangeSync` or create transient in-memory entries when the buffered surface is absent.
- **Directory listings** always use the VFS directly via `vfs.readdirSync`, independent of the buffered-write configuration.

## Frequently Asked Questions

### What triggers the fallback to direct writes in the Computer FUSE driver?

The fallback is triggered when the `hasBufferedWrites` flag is set to false, indicating that the buffered-write surface is not exposed by the kernel or underlying system. When this flag is disabled, the driver avoids calling `openWriteBufferSync` and routes all operations through the direct-write VFS methods or standard VFS calls.

### How does the driver handle read operations without buffered writes?

When buffered writes are unavailable, the driver first checks if a file exists in its in-memory `files` map. If not, it attempts to use `directWriteVfs.readRangeSync` for direct VFS access. If that method is unavailable, it falls back to `vfs.readFileSync` to hydrate the file data from persistent storage before serving the read request.

### Can the buffered-write and direct-write modes coexist?

The driver maintains support for both modes simultaneously in the codebase, but the active path is determined by the `hasBufferedWrites` flag at runtime. While the code structure allows for both paths to be present, a specific file operation will use either the buffered or direct path based on this flag, effectively making them mutually exclusive for any given operation context.

### Where is the fallback logic implemented in the source code?

According to the cloudflare/computer source code, the primary fallback logic is implemented in [`packages/computerd/src/fuse/driver.ts`](https://github.com/cloudflare/computer/blob/main/packages/computerd/src/fuse/driver.ts). Specific lines include the open handler (22-25), write handler (45-68), directory operations (64-71), getattr (77-84), and read operations (89-108), where conditional checks against `hasBufferedWrites` determine the execution path.