fs: Change the default value of `mode` argument of `fs.copyFile()` to `fs.constants.COPYFILE_FICLONE`

What is the problem this feature will solve?

Today's operating systems and some file systems supports copy-on-write operation for copying a file (e.g. btrfs on Linux, APFS on Apple's Darwins).

fs.copyFile() has already supported them as opt-in behavior if the underlying platform support such operations and libuv support them.

• https://nodejs.org/api/fs.html#fspromisescopyfilesrc-dest-mode
• https://github.com/libuv/libuv/blob/3f331e97da5b1cc2e24765dcb6d26c9dd313418f/src/unix/fs.c#L1309-L1490

However, it's still opt-in behavior.

The default value of mode argument. of fs.copyFile() is 0. This mean that fs.copyFile() does not use copy-on-write and use traditional copying mechanism operation even if the underlying platform and libuv supports such operation.

An user can use copy-on-write operation by passingfs.constants.COPYFILE_FICLONE to mode argument.

But if we forget to pass it, fs.copyFile() does not use an enhancement underlying mechanism. We (all programmers) tend to forget to supply a such optional flag to API and to lose a chance to improve a performance. I think this is a bug for API egonomics and having a value we should fix.

What is the feature you are proposing to solve the problem?

My proposal is changing the default value of mode argument of fs.copyFile() to fs.constants.COPYFILE_FICLONE from 0.

By this change, all exist programs using fs.copyFile() in all over the world can get a chance to improve their throughput without any code change.

If the underlying platform does not support copy-on-write behavior, then fs.constants.COPYFILE_FICLONE flag fallback into the traditional approach. I think this change is painless approach.

fs.constants.COPYFILE_FICLONE: The copy operation will attempt to create a copy-on-write reflink. If the platform does not support copy-on-write, then a fallback copy mechanism is used.

https://nodejs.org/api/fs.html#fspromisescopyfilesrc-dest-mode

What alternatives have you considered?

1. This change might be a "breaking change" if we think it strictly. If there is a user program expect fs.copyFile() copy a file without copy-on-write, this change would be problematic.
   • I think it's not be a problem to change a file copying mechanism for user program. It's an abstracted problem by a platform (Node.js, operation system, and file system). An user program should be agnostic about it.
   • But I'm not sure about the Node.js' committee's breaking change policy, I note about this point as a consideration.
2. This also affects the behavior of other APIs that uses fs.copyFile() internally (e.g. fs.cp()).

fs.copyFile() API と fs.constants.COPYFILE_FICLONE の動作を確認し、続いて libuv の src/unix/fs.c の実装を調査します。関連する fs.cp() の動作と互換性への影響を考慮してから、どのテストとドキュメントによって完了を定義するかを決定します。