[IO] add handle copy function

src/io/copy.php

@@ -0,0 +1,36 @@
+<?hh
+/*
+ *  Copyright (c) 2004-present, Facebook, Inc.
+ *  All rights reserved.
+ *
+ *  This source code is licensed under the MIT license found in the
+ *  LICENSE file in the root directory of this source tree.
+ *
+ */
+
+namespace HH\Lib\IO;
+
+use namespace HH\Lib\Str;
+
+/**
+ * Copies content from the given $source read handle to the $target write handle
+ * until the eol of $source is reached.
+ *
+ * If `$chunk_size` is `null`, there is no limit on the chunk size - this function will
+ * copy the content of $source all at once.
+ */
+async function copy(
+  <<__AcceptDisposable>> ReadHandle $source,
+  <<__AcceptDisposable>> WriteHandle $target,
+  ?int $chunk_size = null,
+  ?float $timeout_seconds = null,
+): Awaitable<void> {
+  if (!$source->isEndOfFile()) {
+    $content = await $source->readAsync($chunk_size, $timeout_seconds);
+    await $target->writeAsync($content, $timeout_seconds);
+  }
+
+  if (!$source->isEndOfFile()) {
+    await copy($source, $target, $chunk_size, $timeout_seconds);
+  }
+}

tests/io/CopyTest.php

@@ -0,0 +1,45 @@
+<?hh // strict
+/*
+ *  Copyright (c) 2004-present, Facebook, Inc.
+ *  All rights reserved.
+ *
+ *  This source code is licensed under the MIT license found in the
+ *  LICENSE file in the root directory of this source tree.
+ *
+ */
+
+use namespace HH\Lib\IO;
+use namespace HH\Lib\File;
+
+use function Facebook\FBExpect\expect; // @oss-enable
+use type Facebook\HackTest\HackTest; // @oss-enable
+// @oss-disable: use type HackTest;
+
+// @oss-disable: <<Oncalls('hack')>>
+final class CopyTest extends HackTest {
+  public async function testCopy(): Awaitable<void> {
+    await using $source = File\temporary_file();
+    await using $target = File\temporary_file();
+
+    await $source->writeAsync('Hello, World!');
+    await $source->seekAsync(0);
+
+    expect($source->isEndOfFile())->toBeFalse();
+    expect($target->isEndOfFile())->toBeFalse();
+
+    expect(await $target->readAsync())->toBeSame('');
+
+    await IO\copy($source, $target);
+
+    expect($source->isEndOfFile())->toBeTrue();
+    expect($target->isEndOfFile())->toBeTrue();
+
+    // Assert that the content has been copied.
+    await $target->seekAsync(0);
+    expect(await $target->readAsync())->toBeSame('Hello, World!');
+
+    // Assert that the original file contains the same content. not modifications are made.
+    await $source->seekAsync(0);
+    expect(await $source->readAsync())->toBeSame('Hello, World!');
+  }
+}