refactor(grz-common): extract get_metadata_upload_timestamp helper

Move the "head_object on $submission_id/metadata/metadata.json -> timestamp"
operation into a free function in `grz_common.transfer`, alongside
`init_s3_client`. `Worker.load_metadata_with_submission_date` calls it
and narrows the result to a `date` for storage in the DB.

Documents the inbox-vs-archive caveat: the S3 `LastModified` of the
metadata.json object is the authoritative inbox-receipt timestamp, but
once the submission has moved to the archive bucket the `LastModified`
no longer reflects the time of submission. Callers operating against
the archive (e.g. `grzctl db backfill`) must therefore not use this
helper and must keep deferring to the in-file
`submission.submissionDate` field. The existing `_backfill_submission`
already adds "submission_date" to `ignore_fields`, so this is already
the case in practice.

Author: Hoeze

packages/grz-common/src/grz_common/transfer.py

@@ -2,6 +2,7 @@
 Common methods for transferring data to and from GRZ buckets.
 """
 
+import datetime
 import logging
 from typing import TYPE_CHECKING
 
@@ -80,3 +81,24 @@ def init_s3_resource(s3_options: S3Options) -> S3ServiceResource:
     )
 
     return s3_resource
+
+
+def get_metadata_upload_timestamp(s3_client: S3Client, bucket: str, submission_id: str) -> datetime.datetime:
+    """Return the S3 last-modified timestamp of a submission's ``metadata/metadata.json`` object.
+
+    This is the authoritative "received at the inbox" timestamp: it cannot be forged by
+    the submitter (unlike ``submission.submissionDate`` inside the JSON itself) and is
+    only meaningful while the object still lives in the inbox bucket. Do **not** call
+    this against the archive bucket: the archive's ``LastModified`` reflects the time
+    of archival, not the time of submission.
+
+    :param s3_client: boto3 S3 client pointed at the inbox bucket.
+    :param bucket: Name of the inbox bucket.
+    :param submission_id: Submission identifier (the top-level S3 prefix).
+    :returns: ``LastModified`` (timezone-aware ``datetime``) for
+        ``<submission_id>/metadata/metadata.json``. Callers that only need the date
+        portion should call ``.date()`` themselves.
+    :raises botocore.exceptions.ClientError: If the object does not exist or S3 returns an error.
+    """
+    response = s3_client.head_object(Bucket=bucket, Key=f"{submission_id}/metadata/metadata.json")
+    return response["LastModified"]

packages/grz-common/src/grz_common/workers/worker.py

@@ -17,7 +17,7 @@
 from ..models.identifiers import IdentifiersModel
 from ..models.s3 import S3Options
 from ..progress import EncryptionState, FileProgressLogger, ValidationState
-from ..transfer import init_s3_client
+from ..transfer import get_metadata_upload_timestamp, init_s3_client
 from .download import S3BotoDownloadWorker
 from .submission import EncryptedSubmission, Submission, SubmissionValidationError
 from .upload import S3BotoUploadWorker, UploadError
@@ -318,13 +318,16 @@ def load_metadata_with_submission_date(
     ) -> tuple[GrzSubmissionMetadata, datetime.date]:
         """Load the downloaded metadata.json and fetch its S3 last-modified date.
 
-        Returns the parsed :class:`GrzSubmissionMetadata` plus the date the
-        metadata.json was last modified on S3, suitable for feeding into
-        :meth:`grz_db.models.submission.SubmissionDb.populate`.
+        :param s3_options: S3 connection options for the inbox bucket.
+        :param submission_id: Submission identifier (the top-level S3 prefix).
+        :returns: The parsed :class:`GrzSubmissionMetadata` plus the inbox upload
+            date derived from
+            :func:`grz_common.transfer.get_metadata_upload_timestamp`, suitable
+            for feeding into
+            :meth:`grz_db.models.submission.SubmissionDb.populate`.
         """
         s3_client = init_s3_client(s3_options)
-        response = s3_client.head_object(Bucket=s3_options.bucket, Key=f"{submission_id}/metadata/metadata.json")
-        submission_date = response["LastModified"].date()
+        submission_date = get_metadata_upload_timestamp(s3_client, s3_options.bucket, submission_id).date()
 
         metadata_file_path = self.metadata_dir / "metadata.json"
         with open(metadata_file_path) as fd:

packages/grz-db/src/grz_db/models/submission/__init__.py

@@ -1310,7 +1310,7 @@ def assert_metadata_not_redacted(
         ) and "pseudonym" not in ignore_fields:
             raise ValueError(f"Submission {submission_id} has missing or redacted local_case_id in metadata.")
 
-    def populate(
+    def populate(  # noqa: PLR0913
         self,
         submission_id: str,
         metadata: GrzSubmissionMetadata,