Filesharing Service File Details Task

task api name: file_details

The file_details task returns metadata about a file, including existence status, size in bytes, and MD5 hash. Use it to verify file integrity or check a file before downloading it.

Inputs

Parameter	Required	Description
url	Yes	File URL to inspect

Output

Returns metadata for the requested file, including whether it exists, its size, and its MD5 hash when available.

Examples

CLIPython

Show file details:

nf#file details url nf://filesharing/test_file_1.txt

Context manager:

from norfab.core.nfapi import NorFab

with NorFab(inventory="./inventory.yaml") as nf:
    client = nf.make_client()

    result = client.run_job(
        service="filesharing",
        task="file_details",
        workers="any",
        kwargs={"url": "nf://filesharing/test_file_1.txt"},
    )
    print(result)

Direct lifecycle:

from norfab.core.nfapi import NorFab

nf = NorFab(inventory="./inventory.yaml")
try:
    nf.start()
    client = nf.make_client()

    result = client.run_job(
        service="filesharing",
        task="file_details",
        workers="any",
        kwargs={"url": "nf://templates/base.j2"},
    )
    print(result)
finally:
    nf.destroy()

Filesharing File Details Command Shell Reference

NorFab shell supports these command options for Filesharing file_details task:

nf# man tree file.details
root
└── file:    File sharing service
    └── details:    Show file details
        └── url:    File location, default 'nf://'

nf#

Python API Reference

Return integrity and size details for one published file.

Parameters:

Name	Type	Description	Default
url	str	File URL beginning with nf://.	required

Returns:

Type	Description
Result	A result containing md5hash, size_bytes, and exists.
Result	Missing files and unsafe URLs produce failed results.

Source code in norfab\workers\filesharing_worker\local_files_tasks.py

@Task(
    input=FileDetailsInput,
    output=FileDetailsResult,
    fastapi={"methods": ["GET"]},
    agent={"enabled": False},
    mcp={
        "annotations": {
            "title": "Get File Details",
            "readOnlyHint": True,
            "destructiveHint": False,
            "idempotentHint": True,
            "openWorldHint": False,
        }
    },
)
def file_details(self, url: str) -> Result:
    """Return integrity and size details for one published file.

    Args:
        url: File URL beginning with ``nf://``.

    Returns:
        A result containing ``md5hash``, ``size_bytes``, and ``exists``.
        Missing files and unsafe URLs produce failed results.
    """
    ret = Result(result={"md5hash": None, "size_bytes": None, "exists": False})
    try:
        full_path = self._safe_path(url)
    except ValueError as exc:
        ret.failed = True
        ret.errors = [str(exc)]
        return ret
    exists = os.path.exists(full_path) and os.path.isfile(full_path)

    if exists:
        with open(full_path, "rb") as file_obj:
            file_hash = hashlib.md5()
            chunk = file_obj.read(8192)
            while chunk:
                file_hash.update(chunk)
                chunk = file_obj.read(8192)
        ret.result = {
            "md5hash": file_hash.hexdigest(),
            "size_bytes": os.path.getsize(full_path),
            "exists": True,
        }
    else:
        ret.failed = True
        ret.errors = [f"'{url}' file not found"]

    return ret