nvflare.fuel.f3.drivers.file_driver module

class FileConnection(conn_dir: str, connector: ConnectorInfo, cfg: _ConnConfig)

Bases: Connection

A connection emulated over a shared directory with one append log per direction.

close()

Close connection

Raises:

CommError – If any errors

get_conn_properties() → dict

Get connection specific properties, like peer address, TLS certificate etc

Raises:

CommError – If any errors

read_loop(stopped: Event)

Poll the incoming log and deliver frames until the connection ends.

Liveness is tracked by observed changes of the peer’s lease mtime (not absolute file times), so it is immune to clock skew between nodes.

send_frame(frame: bytes | bytearray | memoryview | list)

Send a SFM frame through the connection to the remote endpoint.

Parameters:

frame – The frame to be sent

Raises:

CommError – If any error happens while sending the frame

class FileDriver

Bases: BaseDriver

Transport driver that exchanges SFM frames through a shared filesystem (e.g. Lustre).

Intended for deployments where two cells share a filesystem but have no network path between them (e.g. an HPC compute node and a gateway node). The URL form is shared-file://0/absolute/dir (“0” is the empty-host placeholder). The passive side owns the directory; each active peer creates a connection subdirectory with one append log per direction. There is no transport security: directory permissions are the trust boundary. Directories are created 0o770 and files 0o660 regardless of umask; override with the dir_mode/file_mode resources (octal strings) if the two sides run as different users needing other group semantics.

Typical use is job-cell to client-parent communication, configured in the client’s comm_config.json. connect_generation 1 routes job-cell traffic through the client parent instead of dialing the server directly:

{

“backbone”: {“connect_generation”: 1}, “internal”: {

“scheme”: “shared-file”, “resources”: {

“root_dir”: “/absolute/shared/path/cellnet”, “connection_security”: “clear”, “poll_interval”: 0.05, “max_poll_interval”: 0.5, “lease_interval”: 5, “lease_timeout”: 30, “fsync”: false

}

}

}

The tuning resources are optional (defaults in _ConnConfig) and are propagated to the child cell through the query string of the generated connect URL; a cell can locally override them (except max_log_size, which must match on both sides) via a “shared-file” section in its own comm_config.json. The example above pins lower-latency polling than the defaults.

Filesystem metadata load: an idle connection costs one log stat per poll tick per direction (2/max_poll_interval per second) plus roughly 3 lease/marker ops per lease_interval per side, about 1.4 client-side metadata syscalls/sec per idle connection at the defaults (max_poll_interval=2, lease_interval=15) — these are client syscall counts; caching may or may not absorb them server-side. A listener adds ~0.5 listdir/sec. Costs shrink proportionally as max_poll_interval grows, at the price of first-message-after-idle latency. During traffic the peer-lease and closed-marker checks are skipped, data is read in 8MB chunks without sleeping, and stat frequency tracks frame arrival, so throughput is unaffected by poll settings. Note for NFS: attribute caching (actimeo) can delay lease-change and size visibility; mount with a low actimeo or raise lease_timeout well above the attribute-cache window. fsync=true is recommended on filesystems without close-to-open or POSIX coherence.

static capabilities() → Dict[str, Any]

Return a dictionary of capabilities of the driver.

connect(connector: ConnectorInfo)

Start the driver in active mode

Parameters:

connector – Connector with parameters

Raises:

CommError – If any errors

static get_urls(scheme: str, resources: dict) -> (<class 'str'>, <class 'str'>)

Get active and passive URL pair based on resources

Parameters:

• scheme – A scheme supported by the driver, like http or https

• resources – User specified resources like host and port ranges.

Returns:

A tuple with active and passive URLs

Raises:

CommError – If no free port can be found

listen(connector: ConnectorInfo)

Start the driver in passive mode

Parameters:

connector – Connector with parameters

Raises:

CommError – If any errors

shutdown()

Stop driver and disconnect all the connections created by it

Raises:

CommError – If any errors

static supported_transports() → List[str]

Return a list of transports supported by this driver, for example [“http”, “https”, “grpc”, “grpcs”]

parse_file_url(url: str) → str

Parse and validate a shared-file transport URL of the form shared-file://0/absolute/dir.

The authority must be the empty-host placeholder “0” and the path must be an absolute directory. This is the single source of truth for shared-file URL semantics; launchers and deploy tools that need the directory (e.g. to bind-mount it into a container) should use this instead of parsing the URL themselves.

Returns:

The absolute directory path (query parameters excluded).

Raises:

CommError – If the URL is not a valid shared-file transport URL.