A Video Download Is Not Ready Until Its File Passes Acceptance
Build a local artifact acceptance gate with size and checksum checks, protected partial files, and eight synthetic tests without claiming a video API experiment.

A naive implementation such as broken_accept writes three incoming synthetic bytes directly into a target file path and closes the handle, treating those truncated bytes as if they represent a finished, accepted artifact. In the verified test environment, these three bytes come from slicing the arbitrary test literal b'synthetic bytes, not a video', which is explicitly not a video file, not an MP4 container, and not the result of a remote media generation API. When an application opens a final destination path in standard write-binary mode and streams arbitrary fragments directly into it, any failure, timeout, or premature termination leaves those three bytes sitting on disk under the official artifact name. Downstream processes monitoring that directory will observe that the target file exists and immediately attempt to read or process an incomplete fragment.
Finished remotely is different from accepted locally
This failure exposes the fundamental architectural distinction between an upstream task finishing remotely and an artifact being accepted locally. A remote service may successfully render an asset, store it in an object repository, and signal through a status message or webhook that the job is complete. However, that remote completion event does not describe the state of the local disk. Between the remote storage layer and the local filesystem lies a network boundary subject to dropped sockets, stalled connections, proxy timeouts, and truncated transfers. Assuming that a successful response status code or a completed remote job status guarantees local file integrity conflates an external announcement with local physical persistence.
When an application writes incoming data directly to the destination path, the filesystem immediately exposes that unverified state to every other process running on the host. If a network interruption halts the transfer after several kilobytes, the partial file remains on the volume. A subsequent run might see the filename, assume the artifact is already present, and skip the operation entirely, thereby locking broken data into production storage. Alternatively, downstream workers such as media packagers, validation daemons, or indexing tasks may attempt to read the file while the write handle is still open or immediately after it fails, leading to parsing errors, unhandled exceptions, and silent data corruption across dependent pipelines.
True local acceptance requires decoupling the transport phase from the publishing phase. The bytes arriving across a connection must be treated as untrusted candidates until they pass rigorous validation against an explicit artifact contract. This means the incoming stream must be written to an isolated, exclusively owned temporary or partial file rather than the target name. During this ingestion phase, the process must tally the received bytes incrementally and compute an ongoing cryptographic checksum. The final artifact name must not exist on disk until the entire stream has finished and the accumulated physical metrics match the authoritative expected record precisely.
Local byte acceptance must also be understood within its proper boundaries. Verifying that an on-disk file matches an expected byte count and SHA-256 digest checks the received stream against the supplied length and digest. It does not verify that the contents form a playable media container, that codecs are compatible, or that the video meets semantic quality standards. In our verified test suite, using synthetic bytes that are explicitly not video data isolates filesystem behavior and boundary conditions from media decoding logic. Establishing a strict file-acceptance gate ensures that before an application debates media contents, it first applies the defined byte-acceptance rule.
Reproduce a short file that was accepted too early
Python documents os.link as creating a hard link. This example requires support on the same filesystem and propagates failures; its tests ran on a Windows filesystem. Python3.12 os.link reference
A common pattern in data ingestion pipelines opens the final destination path directly in write-binary mode and streams incoming byte chunks until the iterator terminates. In the reference implementation, this vulnerable approach is encapsulated by the broken_accept function, which accepts a target path and an iterable of byte chunks. The function invokes Path(target).open with write-binary flags and iterates over the chunks, writing each segment to disk as it arrives. To demonstrate the operational hazard of this structure, the test suite executes test_broken_accepts_short, passing a single chunk containing the first three bytes of the synthetic fixture b'synthetic bytes, not a video'. These three bytes are strictly synthetic test inputs rather than fragments of an actual video container or media stream. Nevertheless, the function executes cleanly, closes the file handle upon exiting the context manager, and leaves behind a three-byte file at the canonical target path.
Use bounded retry decisions for each distinct operation rather than repeating a whole workflow after any exception. A file retrieval failure does not establish that the remote video job needs to be created again; first reconcile the job and the local artifact state.
A consumer that treats existence of output.bin as sufficient evidence of readiness could accept the three-byte fixture. The baseline test itself only reads the file back and compares those bytes; it does not run a monitoring daemon, parser or distribution pipeline. The filesystem name carries no built-in assertion about media completeness. That is an application convention, so an application that uses a final filename as a readiness signal must define who may create it and which checks precede that creation. The corrected example demonstrates one possible convention in a controlled directory, rather than proving how every downstream process reacts.
This premature acceptance stems from conflating the termination of a stream with the successful delivery of an artifact. A network connection may be severed abruptly, a remote proxy may close prematurely, or an upstream source might truncate a payload without emitting an overt transport error. In test_broken_accepts_short, passing only self.data[:3] simulates an interrupted or truncated stream. Because broken_accept accepts only a target path and an iterable of byte chunks, it operates without an authoritative reference point. It has no knowledge of how many bytes the payload should contain, nor does it have an independent checksum to verify that the byte sequence matches the producer's declaration. The function's implicit contract guarantees only that whatever bytes were delivered will be written to disk, leaving the validity of the resulting artifact entirely unchecked.
artifact_file.py
from pathlib import Path
import hashlib
import os
def broken_accept(target, chunks):
with Path(target).open('wb') as handle:
for chunk in chunks:
handle.write(chunk)
def accept_artifact(target, chunks, expected_size, expected_sha256):
target = Path(target)
partial = target.with_name(target.name + '.part')
owned = False
digest = hashlib.sha256()
size = 0
try:
with partial.open('xb') as handle:
owned = True
for chunk in chunks:
size += len(chunk)
if size > expected_size:
raise ValueError('Artifact exceeds declared size')
handle.write(chunk)
digest.update(chunk)
if size != expected_size or digest.hexdigest() != expected_sha256:
raise ValueError('Artifact bytes do not match the expected record')
# Same-filesystem hard link fails if target already exists.
os.link(partial, target)
return target
finally:
if owned:
partial.unlink()
Recorded local check: Eight local file-acceptance tests on a Windows filesystem using synthetic bytes that are NOT a video. No HTTP client, video API, generation, codec playback, signed URL, resume, fsync durability or power-loss recovery was tested. Hard links require a supported same filesystem; failures propagate. Caller must supply trusted expected length/hash. No provider is claimed to return a checksum.; environment: Python3.12.3 on Windows
Make the expected artifact record explicit
An acceptance gate requires a trusted, authoritative reference point before it can evaluate candidate data. If an application inspects an incoming stream without a pre-existing standard of correctness, it can only measure what arrived, never whether what arrived was complete, authentic, or uncorrupted. In the verified implementation, accept_artifact makes this contract mandatory across its signature by requiring expected_size and expected_sha256 alongside the destination path and the chunk generator. The gate treats these values not as advisory hints or optional post-processing metrics, but as strict preconditions that must be satisfied before candidate bytes can be promoted into the primary filesystem tree. Calculating the size and checksum of an arbitrary stream after it finishes writing confirms only that the file system captured what was transmitted; it cannot distinguish an interrupted stream or a mutated payload from intended output unless an independent reference exists to evaluate it against.
The function updates a byte count and SHA-256 digest while writing each supplied chunk. The digest describes the bytes fed to update; the code does not reopen the completed file to perform a separate read-back check. Matching the expected length and digest is therefore the acceptance rule implemented here, not a measurement of physical disk correctness or a proof of authenticity. Normal write and close errors can still propagate. Media parsing, source trust and storage durability remain separate concerns. Keeping the measurement named accurately helps a maintainer avoid treating an input-stream checksum as a full storage or video validation system.
The fixture supplies its expected length and digest from a known local byte string. A real integration must define how it obtains an independent expected record and what that record means. This article did not inspect a video provider response and makes no claim that a provider returns either value. Check the actual service contract before using this function. If no trusted expected SHA-256 value is available, the function cannot honestly provide its stated comparison; do not invent one from the same unchecked transfer and call that an independent reference. A different acceptance policy would require a separately specified implementation and report.
Before writing a chunk, the function adds its length to the running count and raises if that count exceeds expected_size. That bounds the bytes it attempts to write under the supplied size contract. It does not bound the memory already occupied by a chunk, the time spent waiting for the iterator, or every possible storage failure. A caller can supply an impractically large expected size, and the filesystem can run out of space before reaching it. Those constraints belong in a proposed transport and resource policy. The excess-byte fixture checks one rejection path, not overall system stability against arbitrary streams.
Read the eight file-acceptance checks
The local acceptance gate relies on an explicit suite of eight synthetic unit tests to verify state transitions under normal, corrupted, and colliding conditions. These tests operate entirely against an isolated temporary directory using fixed synthetic byte sequences rather than video streams or live network connections. The first test, test_broken_accepts_short, records the baseline defect of unvalidated writes: by invoking broken_accept with only three bytes of data, the routine immediately writes to the destination path and leaves a malformed, truncated file marked as complete. In contrast, test_complete verifies the healthy path through accept_artifact. It passes multi-part chunks through the staging pipeline, validates the total byte count and SHA-256 digest against the reference values, links the temporary file to the final target name, and ensures the intermediate staging file is deleted from the filesystem.
The second pair of checks evaluates length boundary enforcement. In test_short_rejected, the caller feeds an incomplete byte sequence that terminates well before reaching the declared length. Because the final byte count falls short of expected_size, accept_artifact raises a ValueError, suppresses the promotion link, and ensures that the target filename never appears in the target directory. Symmetrically, test_excess_rejected verifies runaway stream handling by feeding bytes that surpass the declared limit. The internal chunk loop detects that the accumulated counter exceeds expected_size on an intermediate write, terminating the stream immediately with a ValueError rather than buffering uncontracted data. In both edge cases, the partial file is unlinked upon exit and the target destination remains unoccupied.
The fifth and sixth checks address cryptographic validation and in-flight transport failures. In test_hash_rejected, the generator delivers the exact expected number of bytes, but the test runner supplies a deliberately corrupted reference digest consisting of sixty-four zeros. Although the byte count matches the contract, the SHA-256 calculation fails the equality check, raising a ValueError and leaving the destination path empty. In test_stream_error, the input stream is configured as a generator that yields one initial fragment and then immediately raises an unhandled RuntimeError to simulate a broken network socket or interrupted transport pipe. The exception propagates out of accept_artifact and the test asserts that the target path does not exist; the source also attempts cleanup of the owned partial file in finally.
The final two checks govern namespace collision and mutual exclusion on disk. In test_existing_final_preserved, a pre-existing file already occupies the final target name before the transfer begins. When accept_artifact attempts to finalize the transfer via os.link, the operating system rejects the link because the destination already exists, raising a FileExistsError and ensuring the original file bytes remain intact and uncorrupted. Similarly, test_existing_partial_preserved checks what happens when a stale or concurrent process has already created the partial staging file. Because accept_artifact opens the partial path using exclusive creation mode xb, the runtime raises a FileExistsError immediately before opening or modifying the file. The routine aborts without modifying or deleting the pre-existing partial file, ensuring it does not overwrite in-flight work belonging to another process.
Together, these eight checks demonstrate that local acceptance can be enforced deterministically through standard filesystem primitives and running cryptographic accumulators. However, the scope of these verified checks is strictly bounded. The test suite ran on a Windows filesystem against fixed synthetic bytes without HTTP clients, video container parsers, or cloud provider APIs. It does not measure disk synchronization durability through fsync, recovery from system crashes during the os.link transition, or resume capabilities across broken sessions. Passing these eight tests proves that a file on disk matches an expected byte length and SHA-256 hash without clobbering existing names, but it does not evaluate whether the accepted bytes constitute a playable, coherent video stream.
Keep partial files and final names under separate ownership
hashlib supports incremental updates to a SHA-256 digest as byte fragments arrive. Matching a supplied digest checks bytes against that record, not whether video playback or content is correct. Python3.12 hashlib reference
The partial file is opened with xb, and owned becomes true only after that exclusive creation succeeds. When an already existing partial path makes open fail, the finally block leaves it untouched; the corresponding fixture checks that its original bytes remain. This is useful ownership discipline in the controlled directory assumed by the example. It is not a hostile-filesystem sandbox or a defense against another actor replacing pathnames while the operation runs. Choose a parent directory whose ownership the application controls, and define how competing jobs are coordinated. The tests did not exercise concurrent threads or containers.
Promoting the validated staging file to its final canonical name requires a non-destructive transition mechanism. Standard rename operations on many operating systems silently replace an existing target file if one is already present at the destination path, which introduces the risk of overwriting previously accepted artifacts. The verified implementation uses os.link to establish a new directory entry pointing to the accepted file record. Python documents os.link as creating a hard link on the filesystem. This operation naturally fails with a FileExistsError if the target name already exists, preventing inadvertent overwrites. However, this safety guarantee comes with strict physical boundaries. Hard links are valid only when the staging path and the target destination reside on the exact same filesystem and storage volume. If the directories span different mounts or unsupported network shares, os.link fails immediately, propagating an operating system error to the caller.
After the final hard link is created, finally removes the partial name. A cleanup error at that point can make the function raise even though the final path already exists. A caller must therefore reconcile both paths and the expected record before retrying after an exception; failure does not always mean that no final artifact was created. The tests cover normal successful cleanup and several earlier failures, but do not inject a post-link unlink error. No fsync or crash-recovery procedure was implemented. A possible integration can record the promotion and cleanup observations separately, then decide how to resolve an uncertain result without overwriting an existing file.
Connect the gate to a real download only after defining its contract
For a proposed HTTP integration, define a byte-only iterator and preserve its transport exceptions. The supplied function has no HTTP status handling, timeout, decompression policy or retry loop. If the iterator raises, the function attempts to clean up its owned partial name and propagates the failure. Do not silently restart a whole response inside the same iterator unless a documented resume contract ensures exactly which bytes continue. A safer proposed orchestration records the attempt, reconciles any final or partial paths, and starts a separate attempt when appropriate. Neither a real HTTP client nor range resumption was implemented in the eight local tests.
The caller must also decide what to do when independent expected metadata is unavailable. The shown signature requires a size and SHA-256 string; an MD5 value or a guessed file length does not satisfy that contract. A service may offer other acceptance evidence, but this article did not measure any service behavior. If the application adopts a different policy, name it accurately and test it separately instead of describing it as the same checksum gate. Retain the source operation identifier and the observations needed to reconcile retrieval. A local file failure is not a reason by itself to create another remote video job.
The caller must also define strict operational policies regarding file locks, retry semantics, and reconciliation of abandoned staging paths. The verified implementation enforces mutual exclusion by opening the partial file with exclusive creation flags. If two concurrent workers attempt to download the same asset simultaneously, or if a previous attempt died unexpectedly and left an orphaned staging file, the second caller immediately encounters a FileExistsError. While this design prevents destructive write interleaving, it transfers ownership management to the orchestration layer. An integration architecture must not automatically delete existing partial files on encounter, as doing so could sever an active download belonging to another operational thread or container. Instead, proposed designs should employ external leasing mechanisms, deterministic task partitioning by worker, or parent-directory scoping to ensure only one process manages a specific target name. When process crashes leave stranded partial files on disk, external cleanup tasks with time-based thresholds must audit and reconcile those paths before scheduling subsequent download retries.
A successful return means the function reached its link operation after the supplied byte stream met the expected count and SHA-256 comparison, then completed its cleanup normally. It does not establish playback, container structure, image content or durable storage after power loss. A real video workflow needs its own subsequent checks, chosen for its destination and declared as separate stages. For example, media parsing or a playback inspection could be proposed after byte acceptance, but neither was run against the synthetic fixture here. Keep the returned path as a locally accepted binary artifact under this contract until those additional readiness requirements have been satisfied.
Prepared with AI assistance and automated editorial reviews. The original code was checked locally against synthetic fixtures; no provider call, real video generation or production workload was tested.



