File migrations *always* copy in files, even if the files were off-line copied to destination

Patch for configuration option.

Added tests.

This will need a reroll when #2695297: Refactor EntityFile and use process plugins instead gets in.

I think "preserve_files" is going to be confusing to people who've used the D7 migrate module, because what it's doing here is not what is was doing there. In D7, "preserve_files" meant to not delete files on rollback (so that rolling back nodes with file references would not remove files when file_usage would otherwise be empty for a given file). The D7 means of indicating the desired behavior here (if the destination file already exists, use the existing file instead of recopying it) was to extend the core $replace flags of FILE_EXISTS_RENAME and FILE_EXISTS_REPLACE with an additional MigrateFile::FILE_EXISTS_REUSE.

No interdiff since this takes a different approach now that #2695297: Refactor EntityFile and use process plugins instead is in core.

1. +++ b/core/modules/migrate/tests/src/Kernel/process/CopyFileTest.php
   @@ -33,7 +35,12 @@ class CopyFileTest extends FileTestBase {
   +    $this->container->get('stream_wrapper_manager')->registerWrapper('public', PublicStream::class, StreamWrapperInterface::LOCAL_NORMAL);
   

   I believe the public stream wrapper is already registered by the system module in a kernel test -- does it still pass if we remove this line?

2. +++ b/core/modules/migrate/tests/src/Kernel/process/CopyFileTest.php
   @@ -33,7 +35,12 @@ class CopyFileTest extends FileTestBase {
   +  protected function tearDown() {
   +    parent::tearDown();
      }
   

   Looks like this isn't adding anything useful, can we remove it?

3. +++ b/core/modules/migrate/tests/src/Kernel/process/CopyFileTest.php
   @@ -71,6 +78,29 @@ public function testSuccessfulCopies() {
   +    self::assertEquals((new \SplFileInfo($destination_path))->getMTime(), $timestamp);
   

   Why use self::? Can we switch to $this->assertGreaterThan() and $this->assertLessThan() when asserting against the timestamp?

   Let's also add a couple of calls like $this->assertInternalType('int', $modified_time), since, as far as I can infer from the PHP documentation, SplFileInfo::getMTime() might return FALSE on failure.

Additionally, it'd be cool if we also added a test of an unsuccessful reuse.

For #30

1. +++ b/core/modules/migrate/src/Plugin/migrate/process/FileCopy.php
   @@ -142,13 +148,17 @@ protected function writeFile($source, $destination, $replace = FILE_EXISTS_REPLA
   +   *   FILE_EXISTS_REPLACE (default) FILE_EXISTS_RENAME, or FILE_EXISTS_ERROR
   

   Nit: comma after (default) (can be fixed on commit).

2. +++ b/core/modules/migrate/tests/src/Kernel/process/CopyFileTest.php
   @@ -71,6 +73,32 @@ public function testSuccessfulCopies() {
   +    sleep(1);
   

   I kinda got an icky feeling at adding a second to test time - but, I don't see an alternative and besides, if I'm counting correctly, the full test suite is already losing 22 seconds to sleep() calls...

Committed/pushed to 8.3.x and cherry-picked to 8.2.x. Thanks!