Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions .changes/next-release/bugfix-S3TransferManager-3eaf213.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
{
"type": "bugfix",
"category": "S3 Transfer Manager",
"contributor": "",
"description": "Fixed an issue in `downloadDirectory` where keys that resolve to the same local file could produce a file that mixes the bytes of several objects, by writing each object to a temporary file next to its destination and moving it into place once complete, which also leaves an existing file unchanged when its download fails."
}
Original file line number Diff line number Diff line change
Expand Up @@ -638,6 +638,18 @@ default DirectoryUpload uploadDirectory(Consumer<UploadDirectoryRequest.Builder>
* object content.
*
* <p>
* Each object is first written to a temporary file in the same directory as its destination, named
* {@code <name>.s3tmp.<random>}, or {@code s3tmp.<random>} when that name would be too long, where {@code <random>} is 16
* random hex digits. Once the object is complete, the temporary file is moved onto the destination, and only then is the
* object's download, and its
* {@link software.amazon.awssdk.transfer.s3.progress.TransferListener#transferComplete transferComplete}, completed. The
* move replaces the destination file rather than writing into it: a symbolic link at the destination is replaced instead of
* followed, and the file gets the default permissions of a new file. A download that fails leaves an existing destination
* file unchanged, and so does a cancel that arrives before the file is being moved into place. If the process stops while a
* download is in progress, its temporary file can be left behind. When several keys resolve to the same local file, such as
* {@code a/b} and {@code a//b}, the file holds the complete content of one of the objects.
*
* <p>
* The current user must have write access to all directories and files
*
* <p>
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -209,19 +209,20 @@ <ResultT> Download<ResultT> doDownloadWithDirectBufferPool(DownloadRequest<Resul
}

/**
* Downloads the object by handing the destination file to CRT, which writes the response body to it directly rather than
* Downloads the object by handing {@code writePath} to CRT, which writes the response body to it directly rather than
* streaming the body back through the SDK.
*/
@Override
FileDownload doDownloadFile(DownloadFileRequest downloadRequest) {
FileDownload downloadFileTo(DownloadFileRequest downloadRequest, Path writePath, Runnable beforeCompletion) {
Validate.paramNotNull(writePath, "writePath");
S3MetaRequestPauseObservable observable = new S3MetaRequestPauseObservable();
TransferProgressUpdater progressUpdater = new TransferProgressUpdater(downloadRequest, null);

DownloadFileRequest crtDownloadRequest = crtDownloadFileRequest(downloadRequest, observable, progressUpdater,
DownloadFileRequest crtDownloadRequest = crtDownloadFileRequest(downloadRequest, writePath, observable, progressUpdater,
ResponseFileOption.CREATE_OR_REPLACE);

CompletableFuture<CompletedFileDownload> returnFuture = new CompletableFuture<>();
initiateCrtDownload(crtDownloadRequest, progressUpdater, returnFuture);
initiateCrtDownload(crtDownloadRequest, progressUpdater, returnFuture, beforeCompletion);

return new CrtFileDownload(returnFuture, progressUpdater.progress(), observable, () -> crtDownloadRequest, null);
}
Expand Down Expand Up @@ -268,13 +269,14 @@ FileDownload doResumeDownloadFile(ResumableFileDownload resumableFileDownload) {
: ResponseFileOption.CREATE_OR_APPEND;

TransferProgressUpdater progressUpdater = new TransferProgressUpdater(newDownloadFileRequest, null);
DownloadFileRequest crtDownloadRequest = crtDownloadFileRequest(newDownloadFileRequest, observable,
DownloadFileRequest crtDownloadRequest = crtDownloadFileRequest(newDownloadFileRequest,
newDownloadFileRequest.destination(), observable,
progressUpdater, responseFileOption);

newDownloadFileRequestFuture.complete(crtDownloadRequest);
log.debug(() -> LogSanitizer.escapeControlCharacters("Sending downloadFileRequest " + crtDownloadRequest));

initiateCrtDownload(crtDownloadRequest, progressUpdater, returnFuture);
initiateCrtDownload(crtDownloadRequest, progressUpdater, returnFuture, NO_OP);
progressFuture.complete(progressUpdater.progress());
}).exceptionally(throwable -> {
handleException(returnFuture, progressFuture, newDownloadFileRequestFuture, throwable);
Expand Down Expand Up @@ -303,7 +305,8 @@ private static boolean hasCompletedParts(ResumableFileDownload resumableFileDown

private void initiateCrtDownload(DownloadFileRequest downloadRequest,
TransferProgressUpdater progressUpdater,
CompletableFuture<CompletedFileDownload> returnFuture) {
CompletableFuture<CompletedFileDownload> returnFuture,
Runnable beforeCompletion) {
try {
progressUpdater.transferInitiated();
AsyncResponseTransformer<GetObjectResponse, GetObjectResponse> responseTransformer =
Expand All @@ -318,26 +321,28 @@ private void initiateCrtDownload(DownloadFileRequest downloadRequest,
// Forward download cancellation to CRT future
CompletableFutureUtils.forwardExceptionTo(returnFuture, crtFuture);

CompletableFutureUtils.forwardTransformedResultTo(crtFuture, returnFuture,
res -> CompletedFileDownload.builder()
.response(res)
.build());
CompletableFutureUtils.forwardTransformedResultTo(crtFuture, returnFuture, res -> {
CompletedFileDownload completed = CompletedFileDownload.builder().response(res).build();
beforeCompletion.run();
return completed;
});
} catch (Throwable throwable) {
returnFuture.completeExceptionally(throwable);
}
}

/**
* Attaches the execution attributes that tell the CRT-based client to write the response body straight to the destination
* file, together with the progress listener and pause observable needed to report progress on and pause that transfer.
* Attaches the execution attributes that tell the CRT-based client to write the response body straight to {@code writePath},
* together with the progress listener and pause observable needed to report progress on and pause that transfer.
*/
private DownloadFileRequest crtDownloadFileRequest(DownloadFileRequest downloadRequest,
Path writePath,
S3MetaRequestPauseObservable observable,
TransferProgressUpdater progressUpdater,
ResponseFileOption responseFileOption) {
GetObjectRequest getObjectRequest = attachSdkAttribute(
downloadRequest.getObjectRequest(),
b -> b.putExecutionAttribute(RESPONSE_FILE_PATH, downloadRequest.destination())
b -> b.putExecutionAttribute(RESPONSE_FILE_PATH, writePath)
.putExecutionAttribute(RESPONSE_FILE_OPTION, responseFileOption));

GetObjectRequest crtGetObjectRequest = attachCrtSdkAttribute(
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -19,10 +19,13 @@
import static software.amazon.awssdk.transfer.s3.internal.TransferConfigurationOption.DEFAULT_PREFIX;

import java.io.IOException;
import java.nio.charset.StandardCharsets;
import java.nio.file.FileSystem;
import java.nio.file.Files;
import java.nio.file.InvalidPathException;
import java.nio.file.Path;
import java.nio.file.StandardCopyOption;
import java.security.SecureRandom;
import java.util.Collection;
import java.util.Queue;
import java.util.UUID;
Expand Down Expand Up @@ -57,16 +60,19 @@
@SdkInternalApi
public class DownloadDirectoryHelper {
private static final Logger log = Logger.loggerFor(S3TransferManager.class);
private static final String TEMP_FILE_INFIX = ".s3tmp.";
private static final SecureRandom TEMP_FILE_RANDOM = new SecureRandom();
private static final int MAX_FILE_NAME_BYTES = 255;
private final TransferManagerConfiguration transferConfiguration;
private final Function<DownloadFileRequest, FileDownload> downloadFileFunction;
private final FileDownloader fileDownloader;
private final ListObjectsHelper listObjectsHelper;

public DownloadDirectoryHelper(TransferManagerConfiguration transferConfiguration,
ListObjectsHelper listObjectsHelper,
Function<DownloadFileRequest, FileDownload> downloadFileFunction) {
FileDownloader fileDownloader) {

this.transferConfiguration = transferConfiguration;
this.downloadFileFunction = downloadFileFunction;
this.fileDownloader = fileDownloader;
this.listObjectsHelper = listObjectsHelper;
}

Expand Down Expand Up @@ -157,12 +163,23 @@ private Path determineDestinationPath(DownloadDirectoryRequest downloadDirectory
}

private void validatePath(Path destinationDirectory, Path targetPath, String key) {
if (!targetPath.toAbsolutePath().normalize().startsWith(destinationDirectory.toAbsolutePath().normalize())) {
Path normalizedDirectory = destinationDirectory.toAbsolutePath().normalize();
Path normalizedTarget = targetPath.toAbsolutePath().normalize();
if (!normalizedTarget.startsWith(normalizedDirectory)) {
throw SdkClientException.create("Cannot download key " + key +
", its relative path resolves outside the parent directory.");
}
if (normalizedTarget.equals(normalizedDirectory)) {
throw SdkClientException.create("Cannot download key " + key +
", its relative path resolves to the destination directory itself.");
}
}

/**
* Downloads the object to a temporary file next to its destination and moves it into place once it is complete. Keys such
* as "a/b" and "a//b", or "A" and "a" on a case-insensitive file system, resolve to the same file, and writing to it
* directly would let their concurrent downloads mix bytes or delete each other's file.
*/
private CompletableFuture<CompletedFileDownload> doDownloadSingleFile(
CompletableFuture<CompletedDirectoryDownload> returnFuture,
DownloadDirectoryRequest downloadDirectoryRequest,
Expand All @@ -183,25 +200,50 @@ private CompletableFuture<CompletedFileDownload> doDownloadSingleFile(
}

DownloadFileRequest downloadFileRequest = downloadFileRequest(downloadDirectoryRequest, s3Object, destinationPath);
Path destination = downloadFileRequest.destination();
Path tempFile;
try {
tempFile = tempFileNextTo(destination);
} catch (RuntimeException e) {
SdkClientException failure = SdkClientException.create("Cannot download key " + s3Object.key() + " to "
+ destination + ", it is not a path to a file", e);
failedFileDownloads.add(FailedFileDownload.builder().exception(failure).request(downloadFileRequest).build());
return CompletableFutureUtils.failedFuture(failure);
}

try {
log.debug(() -> LogSanitizer.escapeControlCharacters("Sending download request " + downloadFileRequest));
createParentDirectoriesIfNeeded(destinationPath);

// The move runs inside the download, so the download and its listeners complete only once the file is in place.
Runnable moveIntoPlaceOnSuccess = () -> {
SdkClientException failure = moveIntoPlace(returnFuture, tempFile, destination);
if (failure != null) {
throw failure;
}
};
CompletableFuture<CompletedFileDownload> executionFuture =
downloadFileFunction.apply(downloadFileRequest).completionFuture();
CompletableFuture<CompletedFileDownload> future = executionFuture.whenComplete((r, t) -> {
if (t != null) {
failedFileDownloads.add(FailedFileDownload.builder()
.exception(t instanceof CompletionException ? t.getCause() : t)
.request(downloadFileRequest)
.build());
fileDownloader.download(downloadFileRequest, tempFile, moveIntoPlaceOnSuccess).completionFuture();
CompletableFuture<CompletedFileDownload> future = new CompletableFuture<>();
// Attached to executionFuture rather than to the returned future, so the temporary file is also removed when the
// directory download cancels the returned future.
executionFuture.whenComplete((r, t) -> {
if (t == null) {
future.complete(r);
return;
}
deleteQuietly(tempFile);
failedFileDownloads.add(FailedFileDownload.builder()
.exception(t instanceof CompletionException ? t.getCause() : t)
.request(downloadFileRequest)
.build());
future.completeExceptionally(t);
});
CompletableFutureUtils.forwardExceptionTo(future, executionFuture);
return future;

} catch (Throwable throwable) {
deleteQuietly(tempFile);
failedFileDownloads.add(FailedFileDownload.builder()
.exception(throwable)
.request(downloadFileRequest)
Expand All @@ -210,6 +252,50 @@ private CompletableFuture<CompletedFileDownload> doDownloadSingleFile(
}
}

/**
* Returns {@code <name>.s3tmp.<16 hex>} next to the destination, or {@code s3tmp.<16 hex>} if that exceeds 255 bytes.
*/
private static Path tempFileNextTo(Path destination) {
Path fileName = destination.getFileName();
if (fileName == null) {
throw new IllegalArgumentException(destination + " has no file name");
}
String suffix = TEMP_FILE_INFIX + String.format("%016x", TEMP_FILE_RANDOM.nextLong());
String tempName = fileName + suffix;
if (tempName.getBytes(StandardCharsets.UTF_8).length > MAX_FILE_NAME_BYTES) {
tempName = suffix.substring(1);
}
return destination.resolveSibling(tempName);
}

/**
* Moves a completed download onto its destination, returning the failure to report for the key, or null on success.
*/
private static SdkClientException moveIntoPlace(CompletableFuture<CompletedDirectoryDownload> returnFuture,
Path tempFile,
Path destination) {
if (returnFuture.isCompletedExceptionally()) {
deleteQuietly(tempFile);
return SdkClientException.create("Download was cancelled before the file could be moved to " + destination);
}

try {
Files.move(tempFile, destination, StandardCopyOption.ATOMIC_MOVE, StandardCopyOption.REPLACE_EXISTING);
return null;
} catch (IOException | RuntimeException e) {
deleteQuietly(tempFile);
return SdkClientException.create("Failed to move the downloaded file to " + destination, e);
}
}

private static void deleteQuietly(Path path) {
try {
Files.deleteIfExists(path);
} catch (IOException | RuntimeException e) {
log.debug(() -> LogSanitizer.escapeControlCharacters("Failed to delete temporary file " + path), e);
}
}


/**
* Reports a key that can't be mapped to a path inside the destination directory as a single failed download, without
Expand Down Expand Up @@ -283,4 +369,12 @@ private static void createParentDirectoriesIfNeeded(Path destinationPath) {
throw SdkClientException.create("Failed to create parent directories for " + destinationPath, e);
}
}

/**
* Downloads one object into {@code writePath}, running {@code beforeCompletion} before the download completes.
*/
@FunctionalInterface
interface FileDownloader {
FileDownload download(DownloadFileRequest request, Path writePath, Runnable beforeCompletion);
}
}
Loading
Loading