Filesharing Service File Details Task

task api name: file_details

The file_details task returns metadata about a file including its existence status, size in bytes, and MD5 hash. This is useful for verifying file integrity, checking if a file exists before downloading, or comparing local and remote file versions without transferring the entire file.

Using it from Python

from norfab.core.nfapi import NorFab

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

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

Using it from nfcli

NORFAB CLI exposes File Sharing under the file command group.

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

nf#

API Reference

Get file details including md5 hash, size, and existence.

Parameters:

Name	Type	Description	Default
url	str	URL path starting with 'nf://' to get file details	required

Returns:

Type	Description
Result	Result containing md5hash, size_bytes, and exists fields

Source code in norfab\workers\filesharing_worker\filesharing_worker.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:
    """
    Get file details including md5 hash, size, and existence.

    Args:
        url: URL path starting with 'nf://' to get file details

    Returns:
        Result containing md5hash, size_bytes, and exists fields
    """
    ret = Result(result={"md5hash": None, "size_bytes": None, "exists": False})
    try:
        full_path = self._safe_path(url)
    except ValueError as e:
        ret.failed = True
        ret.errors = [str(e)]
        return ret
    exists = os.path.exists(full_path) and os.path.isfile(full_path)

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

    return ret