feat: add SHA-1 idempotency primitives for CoreFileObject

changelog/+idempotent-file-ops-unsaved-node.fixed.md

@@ -0,0 +1 @@
+Fixed `InfrahubNode.download_file(skip_if_unchanged=True)` silently returning `0` bytes-written on nodes that had never been saved. Previously, if the local file at `dest` happened to have the same SHA-1 as whatever was cached on the unsaved node's `checksum.value`, callers got back a success-looking `0` result instead of a clear failure — which could mask the fact that the node had no server counterpart at all. Calling `download_file` on an unsaved node now raises `ValueError` consistently, whether or not `skip_if_unchanged` is set.

changelog/+idempotent-file-ops.added.md

@@ -0,0 +1,7 @@
+Added SHA-1 idempotency primitives for `CoreFileObject` nodes:
+
+- `InfrahubNode.matches_local_checksum(source)` / sync variant — compare a local `bytes | Path | BinaryIO` source against the node's server-stored checksum without invoking a transfer.
+- `InfrahubNode.upload_if_changed(source, name=None)` / sync variant — stage + save only when the local source differs from the server, returning an `UploadResult(uploaded, checksum)` dataclass.
+- `download_file(..., skip_if_unchanged=True)` — short-circuit the download when `dest` already exists on disk with a matching SHA-1. Returns `0` bytes written when skipped.
+
+A shared `sha1_of_source` helper (streaming, 64 KiB chunks) centralises the hashing convention in `infrahub_sdk.file_handler`.

infrahub_sdk/file_handler.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import hashlib
 from dataclasses import dataclass
 from io import BytesIO
 from pathlib import Path
@@ -13,6 +14,52 @@
 if TYPE_CHECKING:
     from .client import InfrahubClient, InfrahubClientSync
 
+_SHA1_CHUNK_BYTES = 64 * 1024
+
+
+def sha1_of_source(source: bytes | Path | BinaryIO) -> str:
+    """Compute the SHA-1 hex digest of an upload/download source.
+
+    Accepts the same shapes as :meth:`FileHandlerBase.prepare_upload` so
+    callers can compare local content against a server-stored checksum
+    without materialising the full file in memory.
+
+    Args:
+        source: The content to hash. ``bytes`` are hashed in one shot.
+            A ``Path`` is read in 64 KiB chunks. A ``BinaryIO`` is read
+            from its current position, then rewound so downstream
+            callers can re-read it.
+
+    Returns:
+        Lowercase SHA-1 hex digest, matching the algorithm Infrahub
+        stores in ``CoreFileObject.checksum``.
+
+    Raises:
+        TypeError: If ``source`` is not one of the supported types.
+    """
+    hasher = hashlib.sha1(usedforsecurity=False)
+
+    if isinstance(source, bytes):
+        hasher.update(source)
+        return hasher.hexdigest()
+
+    if isinstance(source, Path):
+        with source.open("rb") as fh:
+            while chunk := fh.read(_SHA1_CHUNK_BYTES):
+                hasher.update(chunk)
+        return hasher.hexdigest()
+
+    if hasattr(source, "read") and hasattr(source, "seek"):
+        start = source.tell()
+        try:
+            while chunk := source.read(_SHA1_CHUNK_BYTES):
+                hasher.update(chunk)
+        finally:
+            source.seek(start)
+        return hasher.hexdigest()
+
+    raise TypeError(f"sha1_of_source expects bytes, Path, or BinaryIO; got {type(source).__name__}")
+
 
 @dataclass
 class PreparedFile:

infrahub_sdk/node/__init__.py

@@ -7,11 +7,13 @@
     ARTIFACT_GENERATE_FEATURE_NOT_SUPPORTED_MESSAGE,
     HFID_STR_SEPARATOR,
     IP_TYPES,
+    MATCHES_LOCAL_CHECKSUM_FEATURE_NOT_SUPPORTED_MESSAGE,
     PROPERTIES_FLAG,
     PROPERTIES_OBJECT,
     SAFE_VALUE,
+    UPLOAD_IF_CHANGED_FEATURE_NOT_SUPPORTED_MESSAGE,
 )
-from .node import InfrahubNode, InfrahubNodeBase, InfrahubNodeSync
+from .node import InfrahubNode, InfrahubNodeBase, InfrahubNodeSync, UploadResult
 from .parsers import parse_human_friendly_id
 from .property import NodeProperty
 from .related_node import RelatedNode, RelatedNodeBase, RelatedNodeSync
@@ -23,9 +25,11 @@
     "ARTIFACT_GENERATE_FEATURE_NOT_SUPPORTED_MESSAGE",
     "HFID_STR_SEPARATOR",
     "IP_TYPES",
+    "MATCHES_LOCAL_CHECKSUM_FEATURE_NOT_SUPPORTED_MESSAGE",
     "PROPERTIES_FLAG",
     "PROPERTIES_OBJECT",
     "SAFE_VALUE",
+    "UPLOAD_IF_CHANGED_FEATURE_NOT_SUPPORTED_MESSAGE",
     "Attribute",
     "InfrahubNode",
     "InfrahubNodeBase",
@@ -37,5 +41,6 @@
     "RelationshipManager",
     "RelationshipManagerBase",
     "RelationshipManagerSync",
+    "UploadResult",
     "parse_human_friendly_id",
 ]

infrahub_sdk/node/constants.py

@@ -30,6 +30,12 @@
 FILE_DOWNLOAD_FEATURE_NOT_SUPPORTED_MESSAGE = (
     "calling download_file is only supported for nodes that inherit from CoreFileObject"
 )
+MATCHES_LOCAL_CHECKSUM_FEATURE_NOT_SUPPORTED_MESSAGE = (
+    "calling matches_local_checksum is only supported for nodes that inherit from CoreFileObject"
+)
+UPLOAD_IF_CHANGED_FEATURE_NOT_SUPPORTED_MESSAGE = (
+    "calling upload_if_changed is only supported for nodes that inherit from CoreFileObject"
+)
 
 HIERARCHY_FETCH_FEATURE_NOT_SUPPORTED_MESSAGE = "Hierarchical fields are not supported for this node."