FluxFlow.Components.FileSystem 1.2.0

FluxFlow.Components.FileSystem

Reusable file system components for FluxFlow.

Nodes

Failures emit FlowError through the node error stream and do not stop later messages from being processed.

Runtime Timing

File write results, file read results, file watch events, and directory enumeration entries use the package clock for timestamps. Existing callers use the default system clock. Hosts and tests can provide a deterministic clock through registration:

registry.RegisterFileSystemComponents(options => options
    .UseClock(fileSystemClock));

Write Request

new FileWriteRequest
{
    Path = "logs/output.txt",
    Content = "hello",
    Mode = FileWriteMode.Overwrite,
    CreateDirectories = true
}

Bytes can be used instead of Content. When both are set, Bytes wins.

Read Request

new FileReadRequest
{
    Path = "logs/output.txt",
    ReadAs = FileReadMode.Text
}

Use ReadAs = FileReadMode.Bytes when the workflow needs raw bytes. Text reads use the request Encoding value when provided, otherwise defaultEncoding.

Watch Output

{
  "type": "file.watch",
  "directory": "inbox",
  "filter": "*.json",
  "includeSubdirectories": false,
  "notifyFilters": [ "FileName", "LastWrite", "Size" ],
  "baseDirectory": "data",
  "allowAbsolutePaths": false,
  "internalBufferSize": 8192,
  "boundedCapacity": 128
}

file.watch emits FileWatchEvent values with the changed path, directory, name, change type, and old path/name for rename events. internalBufferSize optionally sets the underlying watcher buffer and must be between 4096 and 65536 bytes when set.

Directory Enumerate Output

{
  "type": "directory.enumerate",
  "directory": "inbox",
  "filter": "*.json",
  "includeSubdirectories": true,
  "includeFiles": true,
  "includeDirectories": false,
  "maxEntries": 1000,
  "baseDirectory": "data",
  "allowAbsolutePaths": false,
  "boundedCapacity": 128
}

directory.enumerate emits DirectoryEnumerateEntry values with the resolved path, source directory, name, entry type, optional byte length, timestamps, and file attributes.

Configuration

{
  "type": "file.read",
  "baseDirectory": "data",
  "allowAbsolutePaths": false,
  "defaultEncoding": "utf-8",
  "maxBytes": 1048576,
  "boundedCapacity": 128
}

Relative paths are resolved under baseDirectory when it is set. Relative paths that escape the base directory are rejected. Absolute paths are rejected unless allowAbsolutePaths is true. When baseDirectory is not set and allowAbsolutePaths is false, the current working directory is the implicit base and relative paths that escape it are rejected.

maxBytes defaults to 16777216 (16 MiB) when the option is absent. Set it higher for larger files, or set it explicitly to null to keep unlimited reads.

Supported write modes:

• Overwrite
• Append
• CreateNew

Supported read modes:

• Text
• Bytes

Design Metadata

This package exposes a package-owned IComponentDesignMetadataProvider for its node types. Hosts can compose it through ComponentDesignMetadataCatalog to populate palettes, editors, validation views, and documentation without duplicating package descriptors.

Composition Guidance

Use this package as one part of a host-composed graph. See Component Composition for recommended host boundaries, package boundaries, and extraction timing.