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

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