PersistentAI API Documentation / @persistentai/fireflow-types / IVFSContextService

Interface: IVFSContextService

Defined in: packages/fireflow-types/src/execution/services/vfs-context-service.ts:146

VFS Context Service Interface

Provides read-only access to the Virtual File System (lakeFS) during execution.

Key Design Decisions:

• Read-only: Nodes cannot modify files during execution
• ACL enforced: Permissions checked against effectiveUserId (flow owner)
• Text-only readFile(): Binary files require getPresignedUrl()

Example

async execute(context: ExecutionContext): Promise<NodeExecutionResult> {
  const { vfs, dbos } = context.services!;

  // Read a JSON config file (wrapped in a step for durability)
  const configJson = await dbos.runStep(
    () => vfs.readFile('workspace-123', 'main', 'config/settings.json'),
    { name: 'read-config' }
  );
  const config = JSON.parse(configJson);

  // Get presigned URL for a binary file
  const imageUrl = await dbos.runStep(
    () => vfs.getPresignedUrl('workspace-123', 'main', 'assets/logo.png'),
    { name: 'get-image-url' }
  );

  return {};
}

Extended by

• IVFSWriteContextService

Properties

exists()

exists: (workspaceId, ref, path) => Promise<boolean>

Defined in: packages/fireflow-types/src/execution/services/vfs-context-service.ts:205

Check if a file or directory exists.

Parameters

workspaceId

string

The workspace (lakeFS repository) ID

ref

string

Branch, tag, or commit ID

path

string

Path within the workspace

Returns

Promise<boolean>

true if exists AND user has read permission

Example

if (await vfs.exists('ws-123', 'main', 'config/optional.json')) {
  const config = await vfs.readFile('ws-123', 'main', 'config/optional.json');
}

---

getPresignedUrl()

getPresignedUrl: (workspaceId, ref, path) => Promise<IPresignedUrlResult>

Defined in: packages/fireflow-types/src/execution/services/vfs-context-service.ts:188

Get a pre-signed URL for direct file access.

Use this for:

• Binary files (images, PDFs, audio, video)
• Large files that shouldn't be loaded into memory
• Passing URLs to external services

Parameters

workspaceId

string

The workspace (lakeFS repository) ID

ref

string

Branch, tag, or commit ID

path

string

Path within the workspace

Returns

Promise<IPresignedUrlResult>

Pre-signed URL info with expiration

Throws

Error if permission denied

Example

const { url } = await vfs.getPresignedUrl('ws-123', 'main', 'images/photo.jpg');
// Pass URL to image processing service
await processImage(url);

---

listDirectory()

listDirectory: (workspaceId, ref, path) => Promise<ITreeNode[]>

Defined in: packages/fireflow-types/src/execution/services/vfs-context-service.ts:222

List contents of a directory.

Parameters

workspaceId

string

The workspace (lakeFS repository) ID

ref

string

Branch, tag, or commit ID

path

string

Directory path (use "" for root)

Returns

Promise<ITreeNode[]>

Array of file/directory entries

Throws

Error if permission denied or path is not a directory

Example

const entries = await vfs.listDirectory('ws-123', 'main', 'flows/');
const flowFiles = entries.filter(e => e.name.endsWith('.fflow'));

---

readFile()

readFile: (workspaceId, ref, path) => Promise<string>

Defined in: packages/fireflow-types/src/execution/services/vfs-context-service.ts:165

Read a text file's contents as a UTF-8 string.

ONLY works for text-based content types (JSON, YAML, Markdown, etc.). For binary files, use getPresignedUrl() instead.

Parameters

workspaceId

string

The workspace (lakeFS repository) ID

ref

string

Branch, tag, or commit ID

path

string

Path within the workspace (e.g., "config/settings.json")

Returns

Promise<string>

File contents as string

Throws

Error if permission denied or file is binary

Example

const json = await vfs.readFile('ws-123', 'main', 'flows/calc.fflow');
const flowDef = JSON.parse(json);

---

stat()

stat: (workspaceId, ref, path) => Promise<IFileStat | null>

Defined in: packages/fireflow-types/src/execution/services/vfs-context-service.ts:242

Get metadata about a file or directory.

Parameters

workspaceId

string

The workspace (lakeFS repository) ID

ref

string

Branch, tag, or commit ID

path

string

Path within the workspace

Returns

Promise<IFileStat | null>

File metadata, or null if not found

Throws

Error if permission denied

Example

const stats = await vfs.stat('ws-123', 'main', 'data/large-file.csv');
if (stats && stats.size > 10_000_000) {
  // File is > 10MB, use presigned URL instead
  const { url } = await vfs.getPresignedUrl(...);
}