Add KJ Filesystem API.

This has three main parts:
* The Path data structure, a more-explicit approach to file paths.
* The File/Directory abstract interfaces.
* The "InMemory" implementations of File and Directory.

Disk-based implementations will come in a future commit.

c++/src/kj/filesystem-test.c++

+// Copyright (c) 2016 Sandstorm Development Group, Inc. and contributors
+// Licensed under the MIT License:
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal
+// in the Software without restriction, including without limitation the rights
+// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+// copies of the Software, and to permit persons to whom the Software is
+// furnished to do so, subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in
+// all copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+// THE SOFTWARE.
+
+#include "filesystem.h"
+#include "test.h"
+
+namespace kj {
+namespace {
+
+KJ_TEST("Path") {
+  KJ_EXPECT(Path(nullptr).toString() == ".");
+  KJ_EXPECT(Path(nullptr).toString(true) == "/");
+  KJ_EXPECT(Path("foo").toString() == "foo");
+  KJ_EXPECT(Path("foo").toString(true) == "/foo");
+
+  KJ_EXPECT(Path({"foo", "bar"}).toString() == "foo/bar");
+  KJ_EXPECT(Path({"foo", "bar"}).toString(true) == "/foo/bar");
+
+  KJ_EXPECT(Path::parse("foo/bar").toString() == "foo/bar");
+  KJ_EXPECT(Path::parse("foo//bar").toString() == "foo/bar");
+  KJ_EXPECT(Path::parse("foo/./bar").toString() == "foo/bar");
+  KJ_EXPECT(Path::parse("foo/../bar").toString() == "bar");
+  KJ_EXPECT(Path::parse("foo/bar/..").toString() == "foo");
+  KJ_EXPECT(Path::parse("foo/bar/../..").toString() == ".");
+
+  KJ_EXPECT(Path({"foo", "bar"}).eval("baz").toString() == "foo/bar/baz");
+  KJ_EXPECT(Path({"foo", "bar"}).eval("./baz").toString() == "foo/bar/baz");
+  KJ_EXPECT(Path({"foo", "bar"}).eval("baz/qux").toString() == "foo/bar/baz/qux");
+  KJ_EXPECT(Path({"foo", "bar"}).eval("baz//qux").toString() == "foo/bar/baz/qux");
+  KJ_EXPECT(Path({"foo", "bar"}).eval("baz/./qux").toString() == "foo/bar/baz/qux");
+  KJ_EXPECT(Path({"foo", "bar"}).eval("baz/../qux").toString() == "foo/bar/qux");
+  KJ_EXPECT(Path({"foo", "bar"}).eval("baz/qux/..").toString() == "foo/bar/baz");
+  KJ_EXPECT(Path({"foo", "bar"}).eval("../baz").toString() == "foo/baz");
+  KJ_EXPECT(Path({"foo", "bar"}).eval("baz/../../qux/").toString() == "foo/qux");
+  KJ_EXPECT(Path({"foo", "bar"}).eval("/baz/qux").toString() == "baz/qux");
+  KJ_EXPECT(Path({"foo", "bar"}).eval("//baz/qux").toString() == "baz/qux");
+  KJ_EXPECT(Path({"foo", "bar"}).eval("/baz/../qux").toString() == "qux");
+
+  KJ_EXPECT(Path({"foo", "bar"}).basename()[0] == "bar");
+  KJ_EXPECT(Path({"foo", "bar", "baz"}).parent().toString() == "foo/bar");
+
+  KJ_EXPECT(Path({"foo", "bar"}).append("baz").toString() == "foo/bar/baz");
+  KJ_EXPECT(Path({"foo", "bar"}).append(Path({"baz", "qux"})).toString() == "foo/bar/baz/qux");
+
+  {
+    // Test methods which are overloaded for && on a non-rvalue path.
+    Path path({"foo", "bar"});
+    KJ_EXPECT(path.eval("baz").toString() == "foo/bar/baz");
+    KJ_EXPECT(path.eval("./baz").toString() == "foo/bar/baz");
+    KJ_EXPECT(path.eval("baz/qux").toString() == "foo/bar/baz/qux");
+    KJ_EXPECT(path.eval("baz//qux").toString() == "foo/bar/baz/qux");
+    KJ_EXPECT(path.eval("baz/./qux").toString() == "foo/bar/baz/qux");
+    KJ_EXPECT(path.eval("baz/../qux").toString() == "foo/bar/qux");
+    KJ_EXPECT(path.eval("baz/qux/..").toString() == "foo/bar/baz");
+    KJ_EXPECT(path.eval("../baz").toString() == "foo/baz");
+    KJ_EXPECT(path.eval("baz/../../qux/").toString() == "foo/qux");
+    KJ_EXPECT(path.eval("/baz/qux").toString() == "baz/qux");
+    KJ_EXPECT(path.eval("/baz/../qux").toString() == "qux");
+
+    KJ_EXPECT(path.basename()[0] == "bar");
+    KJ_EXPECT(path.parent().toString() == "foo");
+
+    KJ_EXPECT(path.append("baz").toString() == "foo/bar/baz");
+    KJ_EXPECT(path.append(Path({"baz", "qux"})).toString() == "foo/bar/baz/qux");
+  }
+
+  KJ_EXPECT(kj::str(Path({"foo", "bar"})) == "foo/bar");
+}
+
+KJ_TEST("Path exceptions") {
+  KJ_EXPECT_THROW_MESSAGE("invalid path component", Path(""));
+  KJ_EXPECT_THROW_MESSAGE("invalid path component", Path("."));
+  KJ_EXPECT_THROW_MESSAGE("invalid path component", Path(".."));
+  KJ_EXPECT_THROW_MESSAGE("NUL character", Path(StringPtr("foo\0bar", 7)));
+
+  KJ_EXPECT_THROW_MESSAGE("break out of starting", Path::parse(".."));
+  KJ_EXPECT_THROW_MESSAGE("break out of starting", Path::parse("../foo"));
+  KJ_EXPECT_THROW_MESSAGE("break out of starting", Path::parse("foo/../.."));
+  KJ_EXPECT_THROW_MESSAGE("expected a relative path", Path::parse("/foo"));
+
+  KJ_EXPECT_THROW_MESSAGE("NUL character", Path::parse(kj::StringPtr("foo\0bar", 7)));
+
+  KJ_EXPECT_THROW_MESSAGE("break out of starting", Path({"foo", "bar"}).eval("../../.."));
+  KJ_EXPECT_THROW_MESSAGE("break out of starting", Path({"foo", "bar"}).eval("../baz/../../.."));
+  KJ_EXPECT_THROW_MESSAGE("break out of starting", Path({"foo", "bar"}).eval("baz/../../../.."));
+  KJ_EXPECT_THROW_MESSAGE("break out of starting", Path({"foo", "bar"}).eval("/.."));
+  KJ_EXPECT_THROW_MESSAGE("break out of starting", Path({"foo", "bar"}).eval("/baz/../.."));
+
+  KJ_EXPECT_THROW_MESSAGE("root path has no basename", Path(nullptr).basename());
+  KJ_EXPECT_THROW_MESSAGE("root path has no parent", Path(nullptr).parent());
+}
+
+KJ_TEST("Win32 Path") {
+  KJ_EXPECT(Path({"foo", "bar"}).toWin32String() == "foo\\bar");
+  KJ_EXPECT(Path({"foo", "bar"}).toWin32String(true) == "\\\\foo\\bar");
+  KJ_EXPECT(Path({"c:", "foo", "bar"}).toWin32String(true) == "c:\\foo\\bar");
+  KJ_EXPECT(Path({"A:", "foo", "bar"}).toWin32String(true) == "A:\\foo\\bar");
+
+  KJ_EXPECT(Path({"foo", "bar"}).evalWin32("baz").toWin32String() == "foo\\bar\\baz");
+  KJ_EXPECT(Path({"foo", "bar"}).evalWin32("./baz").toWin32String() == "foo\\bar\\baz");
+  KJ_EXPECT(Path({"foo", "bar"}).evalWin32("baz/qux").toWin32String() == "foo\\bar\\baz\\qux");
+  KJ_EXPECT(Path({"foo", "bar"}).evalWin32("baz//qux").toWin32String() == "foo\\bar\\baz\\qux");
+  KJ_EXPECT(Path({"foo", "bar"}).evalWin32("baz/./qux").toWin32String() == "foo\\bar\\baz\\qux");
+  KJ_EXPECT(Path({"foo", "bar"}).evalWin32("baz/../qux").toWin32String() == "foo\\bar\\qux");
+  KJ_EXPECT(Path({"foo", "bar"}).evalWin32("baz/qux/..").toWin32String() == "foo\\bar\\baz");
+  KJ_EXPECT(Path({"foo", "bar"}).evalWin32("../baz").toWin32String() == "foo\\baz");
+  KJ_EXPECT(Path({"foo", "bar"}).evalWin32("baz/../../qux/").toWin32String() == "foo\\qux");
+  KJ_EXPECT(Path({"foo", "bar"}).evalWin32(".\\baz").toWin32String() == "foo\\bar\\baz");
+  KJ_EXPECT(Path({"foo", "bar"}).evalWin32("baz\\qux").toWin32String() == "foo\\bar\\baz\\qux");
+  KJ_EXPECT(Path({"foo", "bar"}).evalWin32("baz\\\\qux").toWin32String() == "foo\\bar\\baz\\qux");
+  KJ_EXPECT(Path({"foo", "bar"}).evalWin32("baz\\.\\qux").toWin32String() == "foo\\bar\\baz\\qux");
+  KJ_EXPECT(Path({"foo", "bar"}).evalWin32("baz\\..\\qux").toWin32String() == "foo\\bar\\qux");
+  KJ_EXPECT(Path({"foo", "bar"}).evalWin32("baz\\qux\\..").toWin32String() == "foo\\bar\\baz");
+  KJ_EXPECT(Path({"foo", "bar"}).evalWin32("..\\baz").toWin32String() == "foo\\baz");
+  KJ_EXPECT(Path({"foo", "bar"}).evalWin32("baz\\..\\..\\qux\\").toWin32String() == "foo\\qux");
+  KJ_EXPECT(Path({"foo", "bar"}).evalWin32("baz\\../..\\qux/").toWin32String() == "foo\\qux");
+
+  KJ_EXPECT(Path({"c:", "foo", "bar"}).evalWin32("/baz/qux")
+      .toWin32String(true) == "c:\\baz\\qux");
+  KJ_EXPECT(Path({"c:", "foo", "bar"}).evalWin32("\\baz\\qux")
+      .toWin32String(true) == "c:\\baz\\qux");
+  KJ_EXPECT(Path({"c:", "foo", "bar"}).evalWin32("d:\\baz\\qux")
+      .toWin32String(true) == "d:\\baz\\qux");
+  KJ_EXPECT(Path({"c:", "foo", "bar"}).evalWin32("d:\\baz\\..\\qux")
+      .toWin32String(true) == "d:\\qux");
+  KJ_EXPECT(Path({"c:", "foo", "bar"}).evalWin32("\\\\baz\\qux")
+      .toWin32String(true) == "\\\\baz\\qux");
+  KJ_EXPECT(Path({"foo", "bar"}).evalWin32("d:\\baz\\..\\qux")
+      .toWin32String(true) == "d:\\qux");
+  KJ_EXPECT(Path({"foo", "bar", "baz"}).evalWin32("\\qux")
+      .toWin32String(true) == "\\\\foo\\bar\\qux");
+}
+
+KJ_TEST("Win32 Path exceptions") {
+  KJ_EXPECT_THROW_MESSAGE("colons are prohibited", Path({"c:", "foo", "bar"}).toWin32String());
+  KJ_EXPECT_THROW_MESSAGE("colons are prohibited", Path({"c:", "foo:bar"}).toWin32String(true));
+  KJ_EXPECT_THROW_MESSAGE("DOS reserved name", Path({"con"}).toWin32String());
+  KJ_EXPECT_THROW_MESSAGE("DOS reserved name", Path({"CON", "bar"}).toWin32String());
+  KJ_EXPECT_THROW_MESSAGE("DOS reserved name", Path({"foo", "cOn"}).toWin32String());
+  KJ_EXPECT_THROW_MESSAGE("DOS reserved name", Path({"prn"}).toWin32String());
+  KJ_EXPECT_THROW_MESSAGE("DOS reserved name", Path({"aux"}).toWin32String());
+  KJ_EXPECT_THROW_MESSAGE("DOS reserved name", Path({"NUL"}).toWin32String());
+  KJ_EXPECT_THROW_MESSAGE("DOS reserved name", Path({"nul.txt"}).toWin32String());
+  KJ_EXPECT_THROW_MESSAGE("DOS reserved name", Path({"com3"}).toWin32String());
+  KJ_EXPECT_THROW_MESSAGE("DOS reserved name", Path({"lpt9"}).toWin32String());
+  KJ_EXPECT_THROW_MESSAGE("DOS reserved name", Path({"com1.hello"}).toWin32String());
+
+  KJ_EXPECT_THROW_MESSAGE("drive letter or netbios", Path({"?", "foo"}).toWin32String(true));
+
+  KJ_EXPECT_THROW_MESSAGE("break out of starting", Path({"foo", "bar"}).evalWin32("../../.."));
+  KJ_EXPECT_THROW_MESSAGE("break out of starting", Path({"foo", "bar"}).evalWin32("../baz/../../.."));
+  KJ_EXPECT_THROW_MESSAGE("break out of starting", Path({"foo", "bar"}).evalWin32("baz/../../../.."));
+  KJ_EXPECT_THROW_MESSAGE("break out of starting", Path({"foo", "bar"}).evalWin32("c:\\..\\.."));
+  KJ_EXPECT_THROW_MESSAGE("break out of starting",
+      Path({"c:", "foo", "bar"}).evalWin32("/baz/../../.."));
+  KJ_EXPECT_THROW_MESSAGE("must specify drive letter", Path({"foo"}).evalWin32("\\baz\\qux"));
+}
+
+KJ_TEST("WriteMode operators") {
+  WriteMode createOrModify = WriteMode::CREATE | WriteMode::MODIFY;
+
+  KJ_EXPECT(has(createOrModify, WriteMode::MODIFY));
+  KJ_EXPECT(has(createOrModify, WriteMode::CREATE));
+  KJ_EXPECT(!has(createOrModify, WriteMode::CREATE_PARENT));
+  KJ_EXPECT(has(createOrModify, createOrModify));
+  KJ_EXPECT(!has(createOrModify, createOrModify | WriteMode::CREATE_PARENT));
+  KJ_EXPECT(!has(createOrModify, WriteMode::CREATE | WriteMode::CREATE_PARENT));
+  KJ_EXPECT(!has(WriteMode::CREATE, createOrModify));
+
+  KJ_EXPECT(createOrModify != WriteMode::MODIFY);
+  KJ_EXPECT(createOrModify != WriteMode::CREATE);
+
+  KJ_EXPECT(createOrModify - WriteMode::CREATE == WriteMode::MODIFY);
+  KJ_EXPECT(WriteMode::CREATE + WriteMode::MODIFY == createOrModify);
+
+  // Adding existing bit / subtracting non-existing bit are no-ops.
+  KJ_EXPECT(createOrModify + WriteMode::MODIFY == createOrModify);
+  KJ_EXPECT(createOrModify - WriteMode::CREATE_PARENT == createOrModify);
+}
+
+// ======================================================================================
+
+class TestClock final: public Clock {
+public:
+  void tick() {
+    time += 1 * SECONDS;
+  }
+
+  Date now() override { return time; }
+
+  void expectChanged(FsNode& file) {
+    KJ_EXPECT(file.stat().lastModified == time);
+    time += 1 * SECONDS;
+  }
+  void expectUnchanged(FsNode& file) {
+    KJ_EXPECT(file.stat().lastModified != time);
+  }
+
+private:
+  Date time = UNIX_EPOCH + 1 * SECONDS;
+};
+
+KJ_TEST("InMemoryFile") {
+  TestClock clock;
+
+  auto file = newInMemoryFile(clock);
+  clock.expectChanged(*file);
+
+  KJ_EXPECT(file->readAllText() == "");
+  clock.expectUnchanged(*file);
+
+  file->writeAll("foo");
+  clock.expectChanged(*file);
+  KJ_EXPECT(file->readAllText() == "foo");
+
+  file->write(3, StringPtr("bar").asBytes());
+  clock.expectChanged(*file);
+  KJ_EXPECT(file->readAllText() == "foobar");
+
+  file->write(3, StringPtr("baz").asBytes());
+  clock.expectChanged(*file);
+  KJ_EXPECT(file->readAllText() == "foobaz");
+
+  file->write(9, StringPtr("qux").asBytes());
+  clock.expectChanged(*file);
+  KJ_EXPECT(file->readAllText() == kj::StringPtr("foobaz\0\0\0qux", 12));
+
+  file->truncate(6);
+  clock.expectChanged(*file);
+  KJ_EXPECT(file->readAllText() == "foobaz");
+
+  file->truncate(18);
+  clock.expectChanged(*file);
+  KJ_EXPECT(file->readAllText() == kj::StringPtr("foobaz\0\0\0\0\0\0\0\0\0\0\0\0", 18));
+
+  {
+    auto mapping = file->mmap(0, 18);
+    auto privateMapping = file->mmapPrivate(0, 18);
+    auto writableMapping = file->mmapWritable(0, 18);
+    clock.expectUnchanged(*file);
+
+    KJ_EXPECT(mapping.size() == 18);
+    KJ_EXPECT(privateMapping.size() == 18);
+    KJ_EXPECT(writableMapping->get().size() == 18);
+    clock.expectUnchanged(*file);
+
+    KJ_EXPECT(writableMapping->get().begin() == mapping.begin());
+    KJ_EXPECT(privateMapping.begin() != mapping.begin());
+
+    KJ_EXPECT(kj::str(mapping.slice(0, 6).asChars()) == "foobaz");
+    KJ_EXPECT(kj::str(privateMapping.slice(0, 6).asChars()) == "foobaz");
+    clock.expectUnchanged(*file);
+
+    file->write(0, StringPtr("qux").asBytes());
+    clock.expectChanged(*file);
+    KJ_EXPECT(kj::str(mapping.slice(0, 6).asChars()) == "quxbaz");
+    KJ_EXPECT(kj::str(privateMapping.slice(0, 6).asChars()) == "foobaz");
+
+    file->write(12, StringPtr("corge").asBytes());
+    KJ_EXPECT(kj::str(mapping.slice(12, 17).asChars()) == "corge");
+
+    // Can shrink.
+    file->truncate(6);
+    KJ_EXPECT(kj::str(mapping.slice(12, 17).asChars()) == kj::StringPtr("\0\0\0\0\0", 5));
+
+    // Can regrow.
+    file->truncate(18);
+    KJ_EXPECT(kj::str(mapping.slice(12, 17).asChars()) == kj::StringPtr("\0\0\0\0\0", 5));
+
+    // Can't grow past previoous capacity.
+    KJ_EXPECT_THROW_MESSAGE("cannot resize the file backing store", file->truncate(100));
+
+    clock.expectChanged(*file);
+    writableMapping->changed(writableMapping->get().slice(0, 3));
+    clock.expectChanged(*file);
+    writableMapping->sync(writableMapping->get().slice(0, 3));
+    clock.expectChanged(*file);
+  }
+
+  // But now we can since the mapping is gone.
+  file->truncate(100);
+
+  file->truncate(6);
+  clock.expectChanged(*file);
+
+  KJ_EXPECT(file->readAllText() == "quxbaz");
+  file->zero(3, 3);
+  clock.expectChanged(*file);
+  KJ_EXPECT(file->readAllText() == StringPtr("qux\0\0\0", 6));
+}
+
+KJ_TEST("InMemoryFile::copy()") {
+  TestClock clock;
+
+  auto source = newInMemoryFile(clock);
+  source->writeAll("foobarbaz");
+
+  auto dest = newInMemoryFile(clock);
+  dest->writeAll("quxcorge");
+  clock.expectChanged(*dest);
+
+  KJ_EXPECT(dest->copy(3, *source, 6, kj::maxValue) == 3);
+  clock.expectChanged(*dest);
+  KJ_EXPECT(dest->readAllText() == "quxbazge");
+
+  KJ_EXPECT(dest->copy(0, *source, 3, 4) == 4);
+  clock.expectChanged(*dest);
+  KJ_EXPECT(dest->readAllText() == "barbazge");
+
+  KJ_EXPECT(dest->copy(0, *source, 128, kj::maxValue) == 0);
+  clock.expectUnchanged(*dest);
+
+  KJ_EXPECT(dest->copy(4, *source, 3, 0) == 0);
+  clock.expectUnchanged(*dest);
+
+  String bigString = strArray(repeat("foobar", 10000), "");
+  source->truncate(bigString.size() + 1000);
+  source->write(123, bigString.asBytes());
+
+  dest->copy(321, *source, 123, bigString.size());
+  KJ_EXPECT(dest->readAllText().slice(321) == bigString);
+}
+
+KJ_TEST("File::copy()") {
+  TestClock clock;
+
+  auto source = newInMemoryFile(clock);
+  source->writeAll("foobarbaz");
+
+  auto dest = newInMemoryFile(clock);
+  dest->writeAll("quxcorge");
+  clock.expectChanged(*dest);
+
+  KJ_EXPECT(dest->File::copy(3, *source, 6, kj::maxValue) == 3);
+  clock.expectChanged(*dest);
+  KJ_EXPECT(dest->readAllText() == "quxbazge");
+
+  KJ_EXPECT(dest->File::copy(0, *source, 3, 4) == 4);
+  clock.expectChanged(*dest);
+  KJ_EXPECT(dest->readAllText() == "barbazge");
+
+  KJ_EXPECT(dest->File::copy(0, *source, 128, kj::maxValue) == 0);
+  clock.expectUnchanged(*dest);
+
+  KJ_EXPECT(dest->File::copy(4, *source, 3, 0) == 0);
+  clock.expectUnchanged(*dest);
+
+  String bigString = strArray(repeat("foobar", 10000), "");
+  source->truncate(bigString.size() + 1000);
+  source->write(123, bigString.asBytes());
+
+  dest->File::copy(321, *source, 123, bigString.size());
+  KJ_EXPECT(dest->readAllText().slice(321) == bigString);
+}
+
+KJ_TEST("InMemoryDirectory") {
+  TestClock clock;
+
+  auto dir = newInMemoryDirectory(clock);
+  clock.expectChanged(*dir);
+
+  KJ_EXPECT(dir->listNames() == nullptr);
+  KJ_EXPECT(dir->listEntries() == nullptr);
+  KJ_EXPECT(!dir->exists(Path("foo")));
+  KJ_EXPECT(dir->tryOpenFile(Path("foo")) == nullptr);
+  KJ_EXPECT(dir->tryOpenFile(Path("foo"), WriteMode::MODIFY) == nullptr);
+  clock.expectUnchanged(*dir);
+
+  {
+    auto file = dir->openFile(Path("foo"), WriteMode::CREATE);
+    clock.expectChanged(*dir);
+    file->writeAll("foobar");
+    clock.expectUnchanged(*dir);
+  }
+  clock.expectUnchanged(*dir);
+
+  KJ_EXPECT(dir->exists(Path("foo")));
+  clock.expectUnchanged(*dir);
+
+  {
+    auto stats = dir->lstat(Path("foo"));
+    clock.expectUnchanged(*dir);
+    KJ_EXPECT(stats.type == FsNode::Type::FILE);
+    KJ_EXPECT(stats.size == 6);
+  }
+
+  {
+    auto list = dir->listNames();
+    clock.expectUnchanged(*dir);
+    KJ_ASSERT(list.size() == 1);
+    KJ_EXPECT(list[0] == "foo");
+  }
+
+  {
+    auto list = dir->listEntries();
+    clock.expectUnchanged(*dir);
+    KJ_ASSERT(list.size() == 1);
+    KJ_EXPECT(list[0].name == "foo");
+    KJ_EXPECT(list[0].type == FsNode::Type::FILE);
+  }
+
+  KJ_EXPECT(dir->openFile(Path("foo"))->readAllText() == "foobar");
+  clock.expectUnchanged(*dir);
+
+  KJ_EXPECT(dir->tryOpenFile(Path({"foo", "bar"}), WriteMode::MODIFY) == nullptr);
+  KJ_EXPECT(dir->tryOpenFile(Path({"bar", "baz"}), WriteMode::MODIFY) == nullptr);
+  KJ_EXPECT_THROW_MESSAGE("parent is not a directory",
+      dir->tryOpenFile(Path({"bar", "baz"}), WriteMode::CREATE));
+  clock.expectUnchanged(*dir);
+
+  {
+    auto file = dir->openFile(Path({"bar", "baz"}), WriteMode::CREATE | WriteMode::CREATE_PARENT);
+    clock.expectChanged(*dir);
+    file->writeAll("bazqux");
+    clock.expectUnchanged(*dir);
+  }
+  clock.expectUnchanged(*dir);
+
+  KJ_EXPECT(dir->openFile(Path({"bar", "baz"}))->readAllText() == "bazqux");
+  clock.expectUnchanged(*dir);
+
+  {
+    auto stats = dir->lstat(Path("bar"));
+    clock.expectUnchanged(*dir);
+    KJ_EXPECT(stats.type == FsNode::Type::DIRECTORY);
+  }
+
+  {
+    auto list = dir->listNames();
+    clock.expectUnchanged(*dir);
+    KJ_ASSERT(list.size() == 2);
+    KJ_EXPECT(list[0] == "bar");
+    KJ_EXPECT(list[1] == "foo");
+  }
+
+  {
+    auto list = dir->listEntries();
+    clock.expectUnchanged(*dir);
+    KJ_ASSERT(list.size() == 2);
+    KJ_EXPECT(list[0].name == "bar");
+    KJ_EXPECT(list[0].type == FsNode::Type::DIRECTORY);
+    KJ_EXPECT(list[1].name == "foo");
+    KJ_EXPECT(list[1].type == FsNode::Type::FILE);
+  }
+
+  {
+    auto subdir = dir->openSubdir(Path("bar"));
+    clock.expectUnchanged(*dir);
+    clock.expectUnchanged(*subdir);
+
+    KJ_EXPECT(subdir->openFile(Path("baz"))->readAllText() == "bazqux");
+    clock.expectUnchanged(*subdir);
+  }
+
+  auto subdir = dir->openSubdir(Path("corge"), WriteMode::CREATE);
+  clock.expectChanged(*dir);
+
+  subdir->openFile(Path("grault"), WriteMode::CREATE)->writeAll("garply");
+  clock.expectUnchanged(*dir);
+  clock.expectChanged(*subdir);
+
+  KJ_EXPECT(dir->openFile(Path({"corge", "grault"}))->readAllText() == "garply");
+
+  dir->openFile(Path({"corge", "grault"}), WriteMode::CREATE | WriteMode::MODIFY)
+     ->write(0, StringPtr("rag").asBytes());
+  KJ_EXPECT(dir->openFile(Path({"corge", "grault"}))->readAllText() == "ragply");
+  clock.expectUnchanged(*dir);
+
+  {
+    auto replacer =
+        dir->replaceFile(Path({"corge", "grault"}), WriteMode::CREATE | WriteMode::MODIFY);
+    clock.expectUnchanged(*subdir);
+    replacer->get().writeAll("rag");
+    clock.expectUnchanged(*subdir);
+    // Don't commit.
+  }
+  clock.expectUnchanged(*subdir);
+  KJ_EXPECT(dir->openFile(Path({"corge", "grault"}))->readAllText() == "ragply");
+
+  {
+    auto replacer =
+        dir->replaceFile(Path({"corge", "grault"}), WriteMode::CREATE | WriteMode::MODIFY);
+    clock.expectUnchanged(*subdir);
+    replacer->get().writeAll("rag");
+    clock.expectUnchanged(*subdir);
+    replacer->commit();
+    clock.expectChanged(*subdir);
+    KJ_EXPECT(dir->openFile(Path({"corge", "grault"}))->readAllText() == "rag");
+  }
+
+  KJ_EXPECT(dir->openFile(Path({"corge", "grault"}))->readAllText() == "rag");
+
+  {
+    auto appender = dir->appendFile(Path({"corge", "grault"}), WriteMode::MODIFY);
+    appender->write("waldo", 5);
+    appender->write("fred", 4);
+  }
+
+  KJ_EXPECT(dir->openFile(Path({"corge", "grault"}))->readAllText() == "ragwaldofred");
+
+  KJ_EXPECT(dir->exists(Path("foo")));
+  clock.expectUnchanged(*dir);
+  dir->remove(Path("foo"));
+  clock.expectChanged(*dir);
+  KJ_EXPECT(!dir->exists(Path("foo")));
+  KJ_EXPECT(!dir->tryRemove(Path("foo")));
+  clock.expectUnchanged(*dir);
+
+  KJ_EXPECT(dir->exists(Path({"bar", "baz"})));
+  clock.expectUnchanged(*dir);
+  dir->remove(Path({"bar", "baz"}));
+  clock.expectUnchanged(*dir);
+  KJ_EXPECT(!dir->exists(Path({"bar", "baz"})));
+  KJ_EXPECT(dir->exists(Path("bar")));
+  KJ_EXPECT(!dir->tryRemove(Path({"bar", "baz"})));
+  clock.expectUnchanged(*dir);
+
+  KJ_EXPECT(dir->exists(Path("corge")));
+  KJ_EXPECT(dir->exists(Path({"corge", "grault"})));
+  clock.expectUnchanged(*dir);
+  dir->remove(Path("corge"));
+  clock.expectChanged(*dir);
+  KJ_EXPECT(!dir->exists(Path("corge")));
+  KJ_EXPECT(!dir->exists(Path({"corge", "grault"})));
+  KJ_EXPECT(!dir->tryRemove(Path("corge")));
+  clock.expectUnchanged(*dir);
+}
+
+KJ_TEST("InMemoryDirectory symlinks") {
+  TestClock clock;
+
+  auto dir = newInMemoryDirectory(clock);
+  clock.expectChanged(*dir);
+
+  dir->symlink(Path("foo"), "bar/qux/../baz", WriteMode::CREATE);
+  clock.expectChanged(*dir);
+
+  KJ_EXPECT(!dir->trySymlink(Path("foo"), "bar/qux/../baz", WriteMode::CREATE));
+  clock.expectUnchanged(*dir);
+
+  {
+    auto stats = dir->lstat(Path("foo"));
+    clock.expectUnchanged(*dir);
+    KJ_EXPECT(stats.type == FsNode::Type::SYMLINK);
+  }
+
+  KJ_EXPECT(dir->readlink(Path("foo")) == "bar/qux/../baz");
+
+  // Broken link into non-existing directory cannot be opened in any mode.
+  KJ_EXPECT(dir->tryOpenFile(Path("foo")) == nullptr);
+  KJ_EXPECT(dir->tryOpenFile(Path("foo"), WriteMode::CREATE) == nullptr);
+  KJ_EXPECT(dir->tryOpenFile(Path("foo"), WriteMode::MODIFY) == nullptr);
+  KJ_EXPECT_THROW_MESSAGE("parent is not a directory",
+      dir->tryOpenFile(Path("foo"), WriteMode::CREATE | WriteMode::MODIFY));
+  KJ_EXPECT_THROW_MESSAGE("parent is not a directory",
+      dir->tryOpenFile(Path("foo"),
+          WriteMode::CREATE | WriteMode::MODIFY | WriteMode::CREATE_PARENT));
+
+  // Create the directory.
+  auto subdir = dir->openSubdir(Path("bar"), WriteMode::CREATE);
+  clock.expectChanged(*dir);
+
+  // Link still points to non-existing file so cannot be open in most modes.
+  KJ_EXPECT(dir->tryOpenFile(Path("foo")) == nullptr);
+  KJ_EXPECT(dir->tryOpenFile(Path("foo"), WriteMode::CREATE) == nullptr);
+  KJ_EXPECT(dir->tryOpenFile(Path("foo"), WriteMode::MODIFY) == nullptr);
+  clock.expectUnchanged(*dir);
+
+  // But... CREATE | MODIFY works.
+  dir->openFile(Path("foo"), WriteMode::CREATE | WriteMode::MODIFY)
+     ->writeAll("foobar");
+  clock.expectUnchanged(*dir);  // Change is only to subdir!
+
+  KJ_EXPECT(dir->openFile(Path({"bar", "baz"}))->readAllText() == "foobar");
+  KJ_EXPECT(dir->openFile(Path("foo"))->readAllText() == "foobar");
+  KJ_EXPECT(dir->openFile(Path("foo"), WriteMode::MODIFY)->readAllText() == "foobar");
+
+  // operations that modify the symlink
+  dir->symlink(Path("foo"), "corge", WriteMode::MODIFY);
+  KJ_EXPECT(dir->openFile(Path({"bar", "baz"}))->readAllText() == "foobar");
+  KJ_EXPECT(dir->readlink(Path("foo")) == "corge");
+  KJ_EXPECT(!dir->exists(Path("foo")));
+  KJ_EXPECT(dir->lstat(Path("foo")).type == FsNode::Type::SYMLINK);
+  KJ_EXPECT(dir->tryOpenFile(Path("foo")) == nullptr);
+
+  dir->remove(Path("foo"));
+  KJ_EXPECT(!dir->exists(Path("foo")));
+  KJ_EXPECT(dir->tryOpenFile(Path("foo")) == nullptr);
+}
+
+KJ_TEST("InMemoryDirectory link") {
+  TestClock clock;
+
+  auto src = newInMemoryDirectory(clock);
+  auto dst = newInMemoryDirectory(clock);
+
+  src->openFile(Path({"foo", "bar"}), WriteMode::CREATE | WriteMode::CREATE_PARENT)
+     ->writeAll("foobar");
+  src->openFile(Path({"foo", "baz", "qux"}), WriteMode::CREATE | WriteMode::CREATE_PARENT)
+     ->writeAll("bazqux");
+  clock.expectChanged(*src);
+  clock.expectUnchanged(*dst);
+
+  dst->transfer(Path("link"), WriteMode::CREATE, *src, Path("foo"), TransferMode::LINK);
+  clock.expectUnchanged(*src);
+  clock.expectChanged(*dst);
+
+  KJ_EXPECT(dst->openFile(Path({"link", "bar"}))->readAllText() == "foobar");
+  KJ_EXPECT(dst->openFile(Path({"link", "baz", "qux"}))->readAllText() == "bazqux");
+
+  KJ_EXPECT(dst->exists(Path({"link", "bar"})));
+  src->remove(Path({"foo", "bar"}));
+  KJ_EXPECT(!dst->exists(Path({"link", "bar"})));
+}
+
+KJ_TEST("InMemoryDirectory copy") {
+  TestClock clock;
+
+  auto src = newInMemoryDirectory(clock);
+  auto dst = newInMemoryDirectory(clock);
+
+  src->openFile(Path({"foo", "bar"}), WriteMode::CREATE | WriteMode::CREATE_PARENT)
+     ->writeAll("foobar");
+  src->openFile(Path({"foo", "baz", "qux"}), WriteMode::CREATE | WriteMode::CREATE_PARENT)
+     ->writeAll("bazqux");
+  clock.expectChanged(*src);
+  clock.expectUnchanged(*dst);
+
+  dst->transfer(Path("link"), WriteMode::CREATE, *src, Path("foo"), TransferMode::COPY);
+  clock.expectUnchanged(*src);
+  clock.expectChanged(*dst);
+
+  KJ_EXPECT(src->openFile(Path({"foo", "bar"}))->readAllText() == "foobar");
+  KJ_EXPECT(src->openFile(Path({"foo", "baz", "qux"}))->readAllText() == "bazqux");
+  KJ_EXPECT(dst->openFile(Path({"link", "bar"}))->readAllText() == "foobar");
+  KJ_EXPECT(dst->openFile(Path({"link", "baz", "qux"}))->readAllText() == "bazqux");
+
+  KJ_EXPECT(dst->exists(Path({"link", "bar"})));
+  src->remove(Path({"foo", "bar"}));
+  KJ_EXPECT(dst->openFile(Path({"link", "bar"}))->readAllText() == "foobar");
+}
+
+KJ_TEST("InMemoryDirectory move") {
+  TestClock clock;
+
+  auto src = newInMemoryDirectory(clock);
+  auto dst = newInMemoryDirectory(clock);
+
+  src->openFile(Path({"foo", "bar"}), WriteMode::CREATE | WriteMode::CREATE_PARENT)
+     ->writeAll("foobar");
+  src->openFile(Path({"foo", "baz", "qux"}), WriteMode::CREATE | WriteMode::CREATE_PARENT)
+     ->writeAll("bazqux");
+  clock.expectChanged(*src);
+  clock.expectUnchanged(*dst);
+
+  dst->transfer(Path("link"), WriteMode::CREATE, *src, Path("foo"), TransferMode::MOVE);
+  clock.expectChanged(*src);
+
+  KJ_EXPECT(!src->exists(Path({"foo"})));
+  KJ_EXPECT(dst->openFile(Path({"link", "bar"}))->readAllText() == "foobar");
+  KJ_EXPECT(dst->openFile(Path({"link", "baz", "qux"}))->readAllText() == "bazqux");
+}
+
+KJ_TEST("InMemoryDirectory createTemporary") {
+  TestClock clock;
+
+  auto dir = newInMemoryDirectory(clock);
+  auto file = dir->createTemporary();
+  file->writeAll("foobar");
+  KJ_EXPECT(file->readAllText() == "foobar");
+  KJ_EXPECT(dir->listNames() == nullptr);
+}
+
+}  // namespace
+}  // namespace kj

c++/src/kj/filesystem.c++

+// Copyright (c) 2015 Sandstorm Development Group, Inc. and contributors
+// Licensed under the MIT License:
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal
+// in the Software without restriction, including without limitation the rights
+// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+// copies of the Software, and to permit persons to whom the Software is
+// furnished to do so, subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in
+// all copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+// THE SOFTWARE.
+
+#include "filesystem.h"
+#include "vector.h"
+#include "debug.h"
+#include "one-of.h"
+#include <map>
+
+namespace kj {
+
+Path::Path(StringPtr name): Path(heapString(name)) {}
+Path::Path(String&& name): parts(heapArray<String>(1)) {
+  parts[0] = kj::mv(name);
+  validatePart(parts[0]);
+}
+
+Path::Path(ArrayPtr<const StringPtr> parts)
+    : Path(KJ_MAP(p, parts) { return heapString(p); }) {}
+Path::Path(Array<String> partsParam)
+    : Path(kj::mv(partsParam), ALREADY_CHECKED) {
+  for (auto& p: parts) {
+    validatePart(p);
+  }
+}
+
+Path PathPtr::clone() {
+  return Path(KJ_MAP(p, parts) { return heapString(p); }, Path::ALREADY_CHECKED);
+}
+
+Path Path::parse(StringPtr path) {
+  KJ_REQUIRE(!path.startsWith("/"), "expected a relative path, got absolute", path) {
+    // When exceptions are disabled, go on -- the leading '/' will end up ignored.
+    break;
+  }
+  return evalImpl(Vector<String>(countParts(path)), path);
+}
+
+Path PathPtr::append(Path suffix) const {
+  auto newParts = kj::heapArrayBuilder<String>(parts.size() + suffix.parts.size());
+  for (auto& p: parts) newParts.add(heapString(p));
+  for (auto& p: suffix.parts) newParts.add(kj::mv(p));
+  return Path(newParts.finish(), Path::ALREADY_CHECKED);
+}
+Path Path::append(Path suffix) && {
+  auto newParts = kj::heapArrayBuilder<String>(parts.size() + suffix.parts.size());
+  for (auto& p: parts) newParts.add(kj::mv(p));
+  for (auto& p: suffix.parts) newParts.add(kj::mv(p));
+  return Path(newParts.finish(), ALREADY_CHECKED);
+}
+Path PathPtr::append(PathPtr suffix) const {
+  auto newParts = kj::heapArrayBuilder<String>(parts.size() + suffix.parts.size());
+  for (auto& p: parts) newParts.add(heapString(p));
+  for (auto& p: suffix.parts) newParts.add(heapString(p));
+  return Path(newParts.finish(), Path::ALREADY_CHECKED);
+}
+Path Path::append(PathPtr suffix) && {
+  auto newParts = kj::heapArrayBuilder<String>(parts.size() + suffix.parts.size());
+  for (auto& p: parts) newParts.add(kj::mv(p));
+  for (auto& p: suffix.parts) newParts.add(heapString(p));
+  return Path(newParts.finish(), ALREADY_CHECKED);
+}
+
+Path PathPtr::eval(StringPtr pathText) const {
+  if (pathText.startsWith("/")) {
+    // Optimization: avoid copying parts that will just be dropped.
+    return Path::evalImpl(Vector<String>(Path::countParts(pathText)), pathText);
+  } else {
+    Vector<String> newParts(parts.size() + Path::countParts(pathText));
+    for (auto& p: parts) newParts.add(heapString(p));
+    return Path::evalImpl(kj::mv(newParts), pathText);
+  }
+}
+Path Path::eval(StringPtr pathText) && {
+  if (pathText.startsWith("/")) {
+    // Optimization: avoid copying parts that will just be dropped.
+    return evalImpl(Vector<String>(countParts(pathText)), pathText);
+  } else {
+    Vector<String> newParts(parts.size() + countParts(pathText));
+    for (auto& p: parts) newParts.add(kj::mv(p));
+    return evalImpl(kj::mv(newParts), pathText);
+  }
+}
+
+PathPtr PathPtr::basename() const {
+  KJ_REQUIRE(parts.size() > 0, "root path has no basename");
+  return PathPtr(parts.slice(parts.size() - 1, parts.size()));
+}
+Path Path::basename() && {
+  KJ_REQUIRE(parts.size() > 0, "root path has no basename");
+  auto newParts = kj::heapArrayBuilder<String>(1);
+  newParts.add(kj::mv(parts[parts.size() - 1]));
+  return Path(newParts.finish(), ALREADY_CHECKED);
+}
+
+PathPtr PathPtr::parent() const {
+  KJ_REQUIRE(parts.size() > 0, "root path has no parent");
+  return PathPtr(parts.slice(0, parts.size() - 1));
+}
+Path Path::parent() && {
+  KJ_REQUIRE(parts.size() > 0, "root path has no parent");
+  return Path(KJ_MAP(p, parts.slice(0, parts.size() - 1)) { return kj::mv(p); }, ALREADY_CHECKED);
+}
+
+String PathPtr::toString(bool absolute) const {
+  if (parts.size() == 0) {
+    // Special-case empty path.
+    return absolute ? kj::str("/") : kj::str(".");
+  }
+
+  size_t size = absolute + (parts.size() - 1);
+  for (auto& p: parts) size += p.size();
+
+  String result = kj::heapString(size);
+
+  char* ptr = result.begin();
+  bool leadingSlash = absolute;
+  for (auto& p: parts) {
+    if (leadingSlash) *ptr++ = '/';
+    leadingSlash = true;
+    memcpy(ptr, p.begin(), p.size());
+    ptr += p.size();
+  }
+  KJ_ASSERT(ptr == result.end());
+
+  return result;
+}
+
+Path Path::slice(size_t start, size_t end) && {
+  return Path(KJ_MAP(p, parts.slice(start, end)) { return kj::mv(p); });
+}
+
+Path PathPtr::evalWin32(StringPtr pathText) const {
+  Vector<String> newParts(parts.size() + Path::countPartsWin32(pathText));
+  for (auto& p: parts) newParts.add(heapString(p));
+  return Path::evalWin32Impl(kj::mv(newParts), pathText);
+}
+Path Path::evalWin32(StringPtr pathText) && {
+  Vector<String> newParts(parts.size() + countPartsWin32(pathText));
+  for (auto& p: parts) newParts.add(kj::mv(p));
+  return evalWin32Impl(kj::mv(newParts), pathText);
+}
+
+String PathPtr::toWin32String(bool absolute) const {
+  if (parts.size() == 0) {
+    // Special-case empty path.
+    KJ_REQUIRE(!absolute, "absolute path is missing disk designator") {
+      break;
+    }
+    return absolute ? kj::str("\\\\") : kj::str(".");
+  }
+
+  bool isUncPath = false;
+  if (absolute) {
+    if (Path::isWin32Drive(parts[0])) {
+      // It's a win32 drive
+    } else if (Path::isNetbiosName(parts[0])) {
+      isUncPath = true;
+    } else {
+      KJ_FAIL_REQUIRE("absolute win32 path must start with drive letter or netbios host name",
+                      parts[0]);
+    }
+  }
+
+  size_t size = (isUncPath ? 2 : 0) + (parts.size() - 1);
+  for (auto& p: parts) size += p.size();
+
+  String result = heapString(size);
+
+  char* ptr = result.begin();
+
+  if (isUncPath) {
+    *ptr++ = '\\';
+    *ptr++ = '\\';
+  }
+
+  bool leadingSlash = false;
+  for (auto& p: parts) {
+    if (leadingSlash) *ptr++ = '\\';
+    leadingSlash = true;
+
+    KJ_REQUIRE(!Path::isWin32Special(p), "path cannot contain DOS reserved name", p) {
+      // Recover by blotting out the name with invalid characters which Win32 syscalls will reject.
+      for (size_t i = 0; i < p.size(); i++) {
+        *ptr++ = '|';
+      }
+      continue;
+    }
+
+    memcpy(ptr, p.begin(), p.size());
+    ptr += p.size();
+  }
+
+  KJ_ASSERT(ptr == result.end());
+
+  // Check for colons (other than in drive letter), which on NTFS would be interpreted as an
+  // "alternate data stream", which can lead to surprising results. If we want to support ADS, we
+  // should do so using an explicit API. Note that this check also prevents a relative path from
+  // appearing to start with a drive letter.
+  for (size_t i: kj::indices(result)) {
+    if (result[i] == ':') {
+      if (absolute && i == 1) {
+        // False alarm: this is the drive letter.
+      } else {
+        KJ_FAIL_REQUIRE(
+            "colons are prohibited in win32 paths to avoid triggering alterante data streams",
+            result) {
+          // Recover by using a different character which we know Win32 syscalls will reject.
+          result[i] = '|';
+        }
+      }
+    }
+  }
+
+  return result;
+}
+
+// -----------------------------------------------------------------------------
+
+String Path::stripNul(String input) {
+  kj::Vector<char> output(input.size());
+  for (char c: input) {
+    if (c != '\0') output.add(c);
+  }
+  output.add('\0');
+  return String(output.releaseAsArray());
+}
+
+void Path::validatePart(StringPtr part) {
+  KJ_REQUIRE(part != "" && part != "." && part != "..", "invalid path component", part);
+  KJ_REQUIRE(strlen(part.begin()) == part.size(), "NUL character in path component", part);
+  KJ_REQUIRE(part.findFirst('/') == nullptr,
+      "'/' character in path component; did you mean to use Path::parse()?", part);
+}
+
+void Path::evalPart(Vector<String>& parts, ArrayPtr<const char> part) {
+  if (part.size() == 0) {
+    // Ignore consecutive or trailing '/'s.
+  } else if (part.size() == 1 && part[0] == '.') {
+    // Refers to current directory; ignore.
+  } else if (part.size() == 2 && part[0] == '.' && part [1] == '.') {
+    KJ_REQUIRE(parts.size() > 0, "can't use \"..\" to break out of starting directory") {
+      // When exceptions are disabled, ignore.
+      return;
+    }
+    parts.removeLast();
+  } else {
+    auto str = heapString(part);
+    KJ_REQUIRE(strlen(str.begin()) == str.size(), "NUL character in path component", str) {
+      // When exceptions are disabled, strip out '\0' chars.
+      str = stripNul(kj::mv(str));
+      break;
+    }
+    parts.add(kj::mv(str));
+  }
+}
+
+Path Path::evalImpl(Vector<String>&& parts, StringPtr path) {
+  if (path.startsWith("/")) {
+    parts.clear();
+  }
+
+  size_t partStart = 0;
+  for (auto i: kj::indices(path)) {
+    if (path[i] == '/') {
+      evalPart(parts, path.slice(partStart, i));
+      partStart = i + 1;
+    }
+  }
+  evalPart(parts, path.slice(partStart));
+
+  return Path(parts.releaseAsArray(), Path::ALREADY_CHECKED);
+}
+
+Path Path::evalWin32Impl(Vector<String>&& parts, StringPtr path) {
+  // Convert all forward slashes to backslashes.
+  String ownPath;
+  if (path.findFirst('/') != nullptr) {
+    ownPath = heapString(path);
+    for (char& c: ownPath) {
+      if (c == '/') c = '\\';
+    }
+    path = ownPath;
+  }
+
+  // Interpret various forms of absolute paths.
+  if (path.startsWith("\\\\")) {
+    // UNC path.
+    path = path.slice(2);
+
+    // This path is absolute. The first component is a server name.
+    parts.clear();
+  } else if (path.startsWith("\\")) {
+    // Path is relative to the current drive / network share.
+    if (parts.size() >= 1 && isWin32Drive(parts[0])) {
+      // Leading \ interpreted as root of current drive.
+      parts.truncate(1);
+    } else if (parts.size() >= 2) {
+      // Leading \ interpreted as root of current network share (which is indicated by the first
+      // *two* components of the path).
+      parts.truncate(2);
+    } else {
+      KJ_FAIL_REQUIRE("must specify drive letter", path) {
+        // Recover by assuming C drive.
+        parts.clear();
+        parts.add(kj::str("c:"));
+        break;
+      }
+    }
+  } else if ((path.size() == 2 || (path.size() > 2 && path[2] == '\\')) &&
+             isWin32Drive(path.slice(0, 2))) {
+    // Starts with a drive letter.
+    parts.clear();
+  }
+
+  size_t partStart = 0;
+  for (auto i: kj::indices(path)) {
+    if (path[i] == '\\') {
+      evalPart(parts, path.slice(partStart, i));
+      partStart = i + 1;
+    }
+  }
+  evalPart(parts, path.slice(partStart));
+
+  return Path(parts.releaseAsArray(), Path::ALREADY_CHECKED);
+}
+
+size_t Path::countParts(StringPtr path) {
+  size_t result = 1;
+  for (char c: path) {
+    result += (c == '/');
+  }
+  return result;
+}
+
+size_t Path::countPartsWin32(StringPtr path) {
+  size_t result = 1;
+  for (char c: path) {
+    result += (c == '/' || c == '\\');
+  }
+  return result;
+}
+
+bool Path::isWin32Drive(ArrayPtr<const char> part) {
+  return part.size() == 2 && part[1] == ':' &&
+         (('a' <= part[0] && part[0] <= 'z') || ('A' <= part[0] && part[0] <= 'Z'));
+}
+
+bool Path::isNetbiosName(ArrayPtr<const char> part) {
+  // Characters must be alphanumeric or '.' or '-'.
+  for (char c: part) {
+    if (c != '.' && c != '-' &&
+        (c < 'a' || 'z' < c) &&
+        (c < 'A' || 'Z' < c) &&
+        (c < '0' || '9' < c)) {
+      return false;
+    }
+  }
+
+  // Can't be empty nor start or end with a '.' or a '-'.
+  return part.size() > 0 &&
+      part[0] != '.' && part[0] != '-' &&
+      part[part.size() - 1] != '.' && part[part.size() - 1] != '-';
+}
+
+bool Path::isWin32Special(StringPtr part) {
+  bool isNumbered;
+  if (part.size() == 3 || (part.size() > 3 && part[3] == '.')) {
+    // Filename is three characters or three characters followed by an extension.
+    isNumbered = false;
+  } else if ((part.size() == 4 || (part.size() > 4 && part[4] == '.')) &&
+             '1' <= part[3] && part[3] <= '9') {
+    // Filename is four characters or four characters followed by an extension, and the fourth
+    // character is a nonzero digit.
+    isNumbered = true;
+  } else {
+    return false;
+  }
+
+  // OK, this could be a Win32 special filename. We need to match the first three letters against
+  // the list of specials, case-insensitively.
+  char tmp[4];
+  memcpy(tmp, part.begin(), 3);
+  tmp[3] = '\0';
+  for (char& c: tmp) {
+    if ('A' <= c && c <= 'Z') {
+      c += 'a' - 'A';
+    }
+  }
+
+  StringPtr str(tmp, 3);
+  if (isNumbered) {
+    // Specials that are followed by a digit.
+    return str == "com" || str == "lpt";
+  } else {
+    // Specials that are not followed by a digit.
+    return str == "con" || str == "prn" || str == "aux" || str == "nul";
+  }
+}
+
+// =======================================================================================
+
+String ReadableFile::readAllText() {
+  String result = heapString(stat().size);
+  size_t n = read(0, result.asBytes());
+  if (n < result.size()) {
+    // Apparently file was truncated concurrently. Reduce to new size to match.
+    result = heapString(result.slice(0, n));
+  }
+  return result;
+}
+
+Array<byte> ReadableFile::readAllBytes() {
+  Array<byte> result = heapArray<byte>(stat().size);
+  size_t n = read(0, result.asBytes());
+  if (n < result.size()) {
+    // Apparently file was truncated concurrently. Reduce to new size to match.
+    result = heapArray(result.slice(0, n));
+  }
+  return result;
+}
+
+void File::writeAll(ArrayPtr<const byte> bytes) {
+  truncate(0);
+  write(0, bytes);
+}
+
+void File::writeAll(StringPtr text) {
+  writeAll(text.asBytes());
+}
+
+size_t File::copy(uint64_t offset, ReadableFile& from, uint64_t fromOffset, uint64_t size) {
+  byte buffer[8192];
+
+  size_t result = 0;
+  while (size > 0) {
+    size_t n = from.read(fromOffset, kj::arrayPtr(buffer, kj::min(sizeof(buffer), size)));
+    write(offset, arrayPtr(buffer, n));
+    result += n;
+    if (n < sizeof(buffer)) {
+      // Either we copied the amount requested or we hit EOF.
+      break;
+    }
+    fromOffset += n;
+    offset += n;
+    size -= n;
+  }
+
+  return result;
+}
+
+FsNode::Metadata ReadableDirectory::lstat(PathPtr path) {
+  KJ_IF_MAYBE(meta, tryLstat(path)) {
+    return *meta;
+  } else {
+    KJ_FAIL_REQUIRE("no such file", path) { break; }
+    return FsNode::Metadata();
+  }
+}
+
+Own<ReadableFile> ReadableDirectory::openFile(PathPtr path) {
+  KJ_IF_MAYBE(file, tryOpenFile(path)) {
+    return kj::mv(*file);
+  } else {
+    KJ_FAIL_REQUIRE("no such directory", path) { break; }
+    return newInMemoryFile(nullClock());
+  }
+}
+
+Own<ReadableDirectory> ReadableDirectory::openSubdir(PathPtr path) {
+  KJ_IF_MAYBE(dir, tryOpenSubdir(path)) {
+    return kj::mv(*dir);
+  } else {
+    KJ_FAIL_REQUIRE("no such file or directory", path) { break; }
+    return newInMemoryDirectory(nullClock());
+  }
+}
+
+String ReadableDirectory::readlink(PathPtr path) {
+  KJ_IF_MAYBE(p, tryReadlink(path)) {
+    return kj::mv(*p);
+  } else {
+    KJ_FAIL_REQUIRE("not a symlink", path) { break; }
+    return kj::str(".");
+  }
+}
+
+Own<File> Directory::openFile(PathPtr path, WriteMode mode) {
+  KJ_IF_MAYBE(f, tryOpenFile(path, mode)) {
+    return kj::mv(*f);
+  } else if (has(mode, WriteMode::CREATE) && !has(mode, WriteMode::MODIFY)) {
+    KJ_FAIL_REQUIRE("file already exists", path) { break; }
+  } else if (has(mode, WriteMode::MODIFY) && !has(mode, WriteMode::CREATE)) {
+    KJ_FAIL_REQUIRE("file does not exist", path) { break; }
+  } else if (!has(mode, WriteMode::MODIFY) && !has(mode, WriteMode::CREATE)) {
+    KJ_FAIL_ASSERT("neither WriteMode::CREATE nor WriteMode::MODIFY was given", path) { break; }
+  } else {
+    // Shouldn't happen.
+    KJ_FAIL_ASSERT("tryOpenFile() returned null despite no preconditions", path) { break; }
+  }
+  return newInMemoryFile(nullClock());
+}
+
+Own<AppendableFile> Directory::appendFile(PathPtr path, WriteMode mode) {
+  KJ_IF_MAYBE(f, tryAppendFile(path, mode)) {
+    return kj::mv(*f);
+  } else if (has(mode, WriteMode::CREATE) && !has(mode, WriteMode::MODIFY)) {
+    KJ_FAIL_REQUIRE("file already exists", path) { break; }
+  } else if (has(mode, WriteMode::MODIFY) && !has(mode, WriteMode::CREATE)) {
+    KJ_FAIL_REQUIRE("file does not exist", path) { break; }
+  } else if (!has(mode, WriteMode::MODIFY) && !has(mode, WriteMode::CREATE)) {
+    KJ_FAIL_ASSERT("neither WriteMode::CREATE nor WriteMode::MODIFY was given", path) { break; }
+  } else {
+    // Shouldn't happen.
+    KJ_FAIL_ASSERT("tryAppendFile() returned null despite no preconditions", path) { break; }
+  }
+  return newFileAppender(newInMemoryFile(nullClock()));
+}
+
+Own<Directory> Directory::openSubdir(PathPtr path, WriteMode mode) {
+  KJ_IF_MAYBE(f, tryOpenSubdir(path, mode)) {
+    return kj::mv(*f);
+  } else if (has(mode, WriteMode::CREATE) && !has(mode, WriteMode::MODIFY)) {
+    KJ_FAIL_REQUIRE("directory already exists", path) { break; }
+  } else if (has(mode, WriteMode::MODIFY) && !has(mode, WriteMode::CREATE)) {
+    KJ_FAIL_REQUIRE("directory does not exist", path) { break; }
+  } else if (!has(mode, WriteMode::MODIFY) && !has(mode, WriteMode::CREATE)) {
+    KJ_FAIL_ASSERT("neither WriteMode::CREATE nor WriteMode::MODIFY was given", path) { break; }
+  } else {
+    // Shouldn't happen.
+    KJ_FAIL_ASSERT("tryOpenSubdir() returned null despite no preconditions", path) { break; }
+  }
+  return newInMemoryDirectory(nullClock());
+}
+
+void Directory::symlink(PathPtr linkpath, StringPtr content, WriteMode mode) {
+  if (!trySymlink(linkpath, content, mode)) {
+    if (has(mode, WriteMode::CREATE)) {
+      KJ_FAIL_REQUIRE("path already exsits", linkpath) { break; }
+    } else {
+      // Shouldn't happen.
+      KJ_FAIL_ASSERT("symlink() returned null despite no preconditions", linkpath) { break; }
+    }
+  }
+}
+
+void Directory::transfer(PathPtr toPath, WriteMode toMode,
+                         Directory& fromDirectory, PathPtr fromPath,
+                         TransferMode mode) {
+  if (!tryTransfer(toPath, toMode, fromDirectory, fromPath, mode)) {
+    if (has(toMode, WriteMode::CREATE)) {
+      KJ_FAIL_REQUIRE("toPath already exists or fromPath doesn't exist", toPath, fromPath) {
+        break;
+      }
+    } else {
+      KJ_FAIL_ASSERT("fromPath doesn't exist", fromPath) { break; }
+    }
+  }
+}
+
+static void copyContents(Directory& to, ReadableDirectory& from);
+
+static bool tryCopyDirectoryEntry(Directory& to, PathPtr toPath, WriteMode toMode,
+                                  ReadableDirectory& from, PathPtr fromPath,
+                                  FsNode::Type type, bool atomic) {
+  // TODO(cleanup): Make this reusable?
+
+  switch (type) {
+    case FsNode::Type::FILE: {
+      KJ_IF_MAYBE(fromFile, from.tryOpenFile(fromPath)) {
+        if (atomic) {
+          auto replacer = to.replaceFile(toPath, toMode);
+          replacer->get().copy(0, **fromFile, 0, kj::maxValue);
+          return replacer->tryCommit();
+        } else KJ_IF_MAYBE(toFile, to.tryOpenFile(toPath, toMode)) {
+          toFile->get()->copy(0, **fromFile, 0, kj::maxValue);
+          return true;
+        } else {
+          return false;
+        }
+      } else {
+        // Apparently disappeared. Treat as source-doesn't-exist.
+        return false;
+      }
+    }
+    case FsNode::Type::DIRECTORY:
+      KJ_IF_MAYBE(fromSubdir, from.tryOpenSubdir(fromPath)) {
+        if (atomic) {
+          auto replacer = to.replaceSubdir(toPath, toMode);
+          copyContents(replacer->get(), **fromSubdir);
+          return replacer->tryCommit();
+        } else KJ_IF_MAYBE(toSubdir, to.tryOpenSubdir(toPath, toMode)) {
+          copyContents(**toSubdir, **fromSubdir);
+          return true;
+        } else {
+          return false;
+        }
+      } else {
+        // Apparently disappeared. Treat as source-doesn't-exist.
+        return false;
+      }
+    case FsNode::Type::SYMLINK:
+      KJ_IF_MAYBE(content, from.tryReadlink(fromPath)) {
+        return to.trySymlink(toPath, *content, toMode);
+      } else {
+        // Apparently disappeared. Treat as source-doesn't-exist.
+        return false;
+      }
+      break;
+
+    default:
+      // Note: Unclear whether it's better to throw an error here or just ignore it / log a
+      //   warning. Can reconsider when we see an actual use case.
+      KJ_FAIL_REQUIRE("can only copy files, directories, and symlinks", fromPath) {
+        return false;
+      }
+  }
+}
+
+static void copyContents(Directory& to, ReadableDirectory& from) {
+  for (auto& entry: from.listEntries()) {
+    Path subPath(kj::mv(entry.name));
+    tryCopyDirectoryEntry(to, subPath, WriteMode::CREATE, from, subPath, entry.type, false);
+  }
+}
+
+bool Directory::tryTransfer(PathPtr toPath, WriteMode toMode,
+                            Directory& fromDirectory, PathPtr fromPath,
+                            TransferMode mode) {
+  KJ_REQUIRE(toPath.size() > 0, "can't replace self") { return false; }
+
+  // First try reversing.
+  KJ_IF_MAYBE(result, fromDirectory.tryTransferTo(*this, toPath, toMode, fromPath, mode)) {
+    return *result;
+  }
+
+  switch (mode) {
+    case TransferMode::COPY:
+      KJ_IF_MAYBE(meta, fromDirectory.tryLstat(fromPath)) {
+        return tryCopyDirectoryEntry(*this, toPath, toMode, fromDirectory,
+                                     fromPath, meta->type, true);
+      } else {
+        // Source doesn't exist.
+        return false;
+      }
+    case TransferMode::MOVE:
+      // Implement move as copy-then-delete.
+      if (!tryTransfer(toPath, toMode, fromDirectory, fromPath, TransferMode::COPY)) {
+        return false;
+      }
+      fromDirectory.remove(fromPath);
+      return true;
+    case TransferMode::LINK:
+      KJ_FAIL_REQUIRE("can't link across different Directory implementations") { return false; }
+  }
+}
+
+Maybe<bool> Directory::tryTransferTo(Directory& toDirectory, PathPtr toPath, WriteMode toMode,
+                                     PathPtr fromPath, TransferMode mode) {
+  return nullptr;
+}
+
+void Directory::remove(PathPtr path) {
+  if (!tryRemove(path)) {
+    KJ_FAIL_REQUIRE("path to remove doesn't exist", path) { break; }
+  }
+}
+
+void Directory::commitFailed(WriteMode mode) {
+  if (has(mode, WriteMode::CREATE) && !has(mode, WriteMode::MODIFY)) {
+    KJ_FAIL_REQUIRE("replace target already exists") { break; }
+  } else if (has(mode, WriteMode::MODIFY) && !has(mode, WriteMode::CREATE)) {
+    KJ_FAIL_REQUIRE("replace target does not exist") { break; }
+  } else if (!has(mode, WriteMode::MODIFY) && !has(mode, WriteMode::CREATE)) {
+    KJ_FAIL_ASSERT("neither WriteMode::CREATE nor WriteMode::MODIFY was given") { break; }
+  } else {
+    KJ_FAIL_ASSERT("tryCommit() returned null despite no preconditions") { break; }
+  }
+}
+
+// =======================================================================================
+
+namespace {
+
+class InMemoryFile final: public File, public Refcounted {
+public:
+  InMemoryFile(Clock& clock): clock(clock), lastModified(clock.now()) {}
+
+  Own<OsHandle> cloneOsHandle() override {
+    return addRef(*this);
+  }
+
+  Maybe<int> getFd() override {
+    return nullptr;
+  }
+
+  Metadata stat() override {
+    return Metadata { Type::FILE, size, size, lastModified, 1 };
+  }
+
+  void sync() override {}
+  void datasync() override {}
+  // no-ops
+
+  size_t read(uint64_t offset, ArrayPtr<byte> buffer) override {
+    if (offset >= size) {
+      // Entirely out-of-range.
+      return 0;
+    }
+
+    size_t readSize = kj::min(buffer.size(), size - offset);
+    memcpy(buffer.begin(), bytes.begin() + offset, readSize);
+    return readSize;
+  }
+
+  Array<const byte> mmap(uint64_t offset, uint64_t size) override {
+    KJ_REQUIRE(offset + size >= offset, "mmap() request overflows uint64");
+    ensureCapacity(offset + size);
+
+    ArrayDisposer* disposer = new MmapDisposer(addRef(*this));
+    return Array<const byte>(bytes.begin() + offset, size, *disposer);
+  }
+
+  Array<byte> mmapPrivate(uint64_t offset, uint64_t size) override {
+    // Return a copy.
+
+    // Allocate exactly the size requested.
+    auto result = heapArray<byte>(size);
+
+    // Use read() to fill it.
+    size_t actual = read(offset, result);
+
+    // Ignore the rest.
+    if (actual < size) {
+      memset(result.begin() + actual, 0, size - actual);
+    }
+
+    return result;
+  }
+
+  void write(uint64_t offset, ArrayPtr<const byte> data) override {
+    if (data.size() == 0) return;
+    modified();
+    uint64_t end = offset + data.size();
+    KJ_REQUIRE(end >= offset, "write() request overflows uint64");
+    ensureCapacity(end);
+    size = kj::max(size, end);
+    memcpy(bytes.begin() + offset, data.begin(), data.size());
+  }
+
+  void zero(uint64_t offset, uint64_t zeroSize) override {
+    if (zeroSize == 0) return;
+    modified();
+    uint64_t end = offset + zeroSize;
+    KJ_REQUIRE(end >= offset, "zero() request overflows uint64");
+    ensureCapacity(end);
+    size = kj::max(size, end);
+    memset(bytes.begin() + offset, 0, zeroSize);
+  }
+
+  void truncate(uint64_t newSize) override {
+    if (newSize < size) {
+      modified();
+      memset(bytes.begin() + newSize, 0, size - newSize);
+      size = newSize;
+    } else if (newSize > size) {
+      modified();
+      ensureCapacity(newSize);
+      size = newSize;
+    }
+  }
+
+  Own<WritableFileMapping> mmapWritable(uint64_t offset, uint64_t size) override {
+    uint64_t end = offset + size;
+    KJ_REQUIRE(end >= offset, "mmapWritable() request overflows uint64");
+    ensureCapacity(end);
+    return heap<WritableFileMappingImpl>(addRef(*this), bytes.slice(offset, end));
+  }
+
+  size_t copy(uint64_t offset, ReadableFile& from,
+              uint64_t fromOffset, uint64_t copySize) override {
+    size_t fromFileSize = from.stat().size;
+    if (fromFileSize <= fromOffset) return 0;
+
+    // Clamp size to EOF.
+    copySize = kj::min(copySize, fromFileSize - fromOffset);
+    if (copySize == 0) return 0;
+
+    // Allocate space for the copy.
+    uint64_t end = offset + copySize;
+    ensureCapacity(end);
+
+    // Read directly into our backing store.
+    size_t n = from.read(fromOffset, bytes.slice(offset, end));
+    size = kj::max(size, offset + n);
+
+    modified();
+    return n;
+  }
+
+private:
+  Clock& clock;
+  Array<byte> bytes;
+  size_t size = 0;     // bytes may be larger than this to accommodate mmaps
+  Date lastModified;
+  uint mmapCount = 0;  // number of mappings outstanding
+
+  void ensureCapacity(size_t capacity) {
+    if (bytes.size() < capacity) {
+      KJ_ASSERT(mmapCount == 0,
+          "InMemoryFile cannot resize the file backing store while memory mappings exist.");
+
+      auto newBytes = heapArray<byte>(kj::max(capacity, bytes.size() * 2));
+      memcpy(newBytes.begin(), bytes.begin(), size);
+      memset(newBytes.begin() + size, 0, newBytes.size() - size);
+      bytes = kj::mv(newBytes);
+    }
+  }
+
+  void modified() {
+    lastModified = clock.now();
+  }
+
+  class MmapDisposer final: public ArrayDisposer {
+  public:
+    MmapDisposer(Own<InMemoryFile>&& refParam): ref(kj::mv(refParam)) {
+      ++ref->mmapCount;
+    }
+    ~MmapDisposer() noexcept(false) {
+      --ref->mmapCount;
+    }
+
+    void disposeImpl(void* firstElement, size_t elementSize, size_t elementCount,
+                     size_t capacity, void (*destroyElement)(void*)) const override {
+      delete this;
+    }
+
+  private:
+    Own<InMemoryFile> ref;
+  };
+
+  class WritableFileMappingImpl final: public WritableFileMapping {
+  public:
+    WritableFileMappingImpl(Own<InMemoryFile>&& refParam, ArrayPtr<byte> range)
+        : ref(kj::mv(refParam)), range(range) {
+      ++ref->mmapCount;
+    }
+    ~WritableFileMappingImpl() noexcept(false) {
+      --ref->mmapCount;
+    }
+
+    ArrayPtr<byte> get() override {
+      return range;
+    }
+
+    void changed(ArrayPtr<byte> slice) override {
+      ref->modified();
+    }
+
+    void sync(ArrayPtr<byte> slice) override {
+      ref->modified();
+    }
+
+  private:
+    Own<InMemoryFile> ref;
+    ArrayPtr<byte> range;
+  };
+};
+
+// -----------------------------------------------------------------------------
+
+class InMemoryDirectory final: public Directory, public Refcounted {
+public:
+  InMemoryDirectory(Clock& clock)
+      : clock(clock), lastModified(clock.now()) {}
+
+  Own<OsHandle> cloneOsHandle() override {
+    return addRef(*this);
+  }
+
+  Maybe<int> getFd() override {
+    return nullptr;
+  }
+
+  Metadata stat() override {
+    return Metadata { Type::DIRECTORY, 0, 0, lastModified, 1 };
+  }
+
+  void sync() override {}
+  void datasync() override {}
+  // no-ops
+
+  Array<String> listNames()  override {
+    return KJ_MAP(e, entries) { return heapString(e.first); };
+  }
+
+  Array<Entry> listEntries() override {
+    return KJ_MAP(e, entries) {
+      FsNode::Type type;
+      if (e.second.node.is<SymlinkNode>()) {
+        type = FsNode::Type::SYMLINK;
+      } else if (e.second.node.is<FileNode>()) {
+        type = FsNode::Type::FILE;
+      } else {
+        KJ_ASSERT(e.second.node.is<DirectoryNode>());
+        type = FsNode::Type::DIRECTORY;
+      }
+
+      return Entry { type, heapString(e.first) };
+    };
+  }
+
+  bool exists(PathPtr path) override {
+    if (path.size() == 0) {
+      return true;
+    } else if (path.size() == 1) {
+      KJ_IF_MAYBE(entry, tryGetEntry(path[0])) {
+        return exists(*entry);
+      } else {
+        return false;
+      }
+    } else {
+      KJ_IF_MAYBE(subdir, tryGetParent(path[0])) {
+        return subdir->get()->exists(path.slice(1, path.size()));
+      } else {
+        return false;
+      }
+    }
+  }
+
+  Maybe<FsNode::Metadata> tryLstat(PathPtr path) override {
+    if (path.size() == 0) {
+      return stat();
+    } else if (path.size() == 1) {
+      KJ_IF_MAYBE(entry, tryGetEntry(path[0])) {
+        if (entry->node.is<FileNode>()) {
+          return entry->node.get<FileNode>().file->stat();
+        } else if (entry->node.is<DirectoryNode>()) {
+          return entry->node.get<DirectoryNode>().directory->stat();
+        } else if (entry->node.is<SymlinkNode>()) {
+          auto& link = entry->node.get<SymlinkNode>();
+          return FsNode::Metadata { FsNode::Type::SYMLINK, 0, 0, link.lastModified, 1 };
+        } else {
+          KJ_FAIL_ASSERT("unknown node type") { return nullptr; }
+        }
+      } else {
+        return nullptr;
+      }
+    } else {
+      KJ_IF_MAYBE(subdir, tryGetParent(path[0])) {
+        return subdir->get()->tryLstat(path.slice(1, path.size()));
+      } else {
+        return nullptr;
+      }
+    }
+  }
+
+  Maybe<Own<ReadableFile>> tryOpenFile(PathPtr path) override {
+    if (path.size() == 0) {
+      KJ_FAIL_REQUIRE("not a file") { return nullptr; }
+    } else if (path.size() == 1) {
+      KJ_IF_MAYBE(entry, tryGetEntry(path[0])) {
+        return asFile(*entry);
+      } else {
+        return nullptr;
+      }
+    } else {
+      KJ_IF_MAYBE(subdir, tryGetParent(path[0])) {
+        return subdir->get()->tryOpenFile(path.slice(1, path.size()));
+      } else {
+        return nullptr;
+      }
+    }
+  }
+
+  Maybe<Own<ReadableDirectory>> tryOpenSubdir(PathPtr path) override {
+    if (path.size() == 0) {
+      return clone();
+    } else if (path.size() == 1) {
+      KJ_IF_MAYBE(entry, tryGetEntry(path[0])) {
+        return asDirectory(*entry);
+      } else {
+        return nullptr;
+      }
+    } else {
+      KJ_IF_MAYBE(subdir, tryGetParent(path[0])) {
+        return subdir->get()->tryOpenSubdir(path.slice(1, path.size()));
+      } else {
+        return nullptr;
+      }
+    }
+  }
+
+  Maybe<String> tryReadlink(PathPtr path) override {
+    if (path.size() == 0) {
+      KJ_FAIL_REQUIRE("not a symlink") { return nullptr; }
+    } else if (path.size() == 1) {
+      KJ_IF_MAYBE(entry, tryGetEntry(path[0])) {
+        return asSymlink(*entry);
+      } else {
+        return nullptr;
+      }
+    } else {
+      KJ_IF_MAYBE(subdir, tryGetParent(path[0])) {
+        return subdir->get()->tryReadlink(path.slice(1, path.size()));
+      } else {
+        return nullptr;
+      }
+    }
+  }
+
+  Maybe<Own<File>> tryOpenFile(PathPtr path, WriteMode mode) override {
+    if (path.size() == 0) {
+      if (has(mode, WriteMode::MODIFY)) {
+        KJ_FAIL_REQUIRE("not a file") { return nullptr; }
+      } else if (has(mode, WriteMode::CREATE)) {
+        return nullptr;  // already exists (as a directory)
+      } else {
+        KJ_FAIL_REQUIRE("can't replace self") { return nullptr; }
+      }
+    } else if (path.size() == 1) {
+      KJ_IF_MAYBE(entry, openEntry(path[0], mode)) {
+        return asFile(*entry, mode);
+      } else {
+        return nullptr;
+      }
+    } else {
+      KJ_IF_MAYBE(child, tryGetParent(path[0], mode)) {
+        return child->get()->tryOpenFile(path.slice(1, path.size()), mode);
+      } else {
+        return nullptr;
+      }
+    }
+  }
+
+  Own<Replacer<File>> replaceFile(PathPtr path, WriteMode mode) override {
+    if (path.size() == 0) {
+      KJ_FAIL_REQUIRE("can't replace self") { break; }
+    } else if (path.size() == 1) {
+      return heap<ReplacerImpl<File>>(*this, path[0], newInMemoryFile(clock), mode);
+    } else {
+      KJ_IF_MAYBE(child, tryGetParent(path[0], mode)) {
+        return child->get()->replaceFile(path.slice(1, path.size()), mode);
+      }
+    }
+    return heap<BrokenReplacer<File>>(newInMemoryFile(clock));
+  }
+
+  Maybe<Own<Directory>> tryOpenSubdir(PathPtr path, WriteMode mode) override {
+    if (path.size() == 0) {
+      if (has(mode, WriteMode::MODIFY)) {
+        return addRef(*this);
+      } else if (has(mode, WriteMode::CREATE)) {
+        return nullptr;  // already exists
+      } else {
+        KJ_FAIL_REQUIRE("can't replace self") { return nullptr; }
+      }
+    } else if (path.size() == 1) {
+      KJ_IF_MAYBE(entry, openEntry(path[0], mode)) {
+        return asDirectory(*entry, mode);
+      } else {
+        return nullptr;
+      }
+    } else {
+      KJ_IF_MAYBE(child, tryGetParent(path[0], mode)) {
+        return child->get()->tryOpenSubdir(path.slice(1, path.size()), mode);
+      } else {
+        return nullptr;
+      }
+    }
+  }
+
+  Own<Replacer<Directory>> replaceSubdir(PathPtr path, WriteMode mode) override {
+    if (path.size() == 0) {
+      KJ_FAIL_REQUIRE("can't replace self") { break; }
+    } else if (path.size() == 1) {
+      return heap<ReplacerImpl<Directory>>(*this, path[0], newInMemoryDirectory(clock), mode);
+    } else {
+      KJ_IF_MAYBE(child, tryGetParent(path[0], mode)) {
+        return child->get()->replaceSubdir(path.slice(1, path.size()), mode);
+      }
+    }
+    return heap<BrokenReplacer<Directory>>(newInMemoryDirectory(clock));
+  }
+
+  Maybe<Own<AppendableFile>> tryAppendFile(PathPtr path, WriteMode mode) override {
+    if (path.size() == 0) {
+      if (has(mode, WriteMode::MODIFY)) {
+        KJ_FAIL_REQUIRE("not a file") { return nullptr; }
+      } else if (has(mode, WriteMode::CREATE)) {
+        return nullptr;  // already exists (as a directory)
+      } else {
+        KJ_FAIL_REQUIRE("can't replace self") { return nullptr; }
+      }
+    } else if (path.size() == 1) {
+      KJ_IF_MAYBE(entry, openEntry(path[0], mode)) {
+        return asFile(*entry, mode).map(newFileAppender);
+      } else {
+        return nullptr;
+      }
+    } else {
+      KJ_IF_MAYBE(child, tryGetParent(path[0], mode)) {
+        return child->get()->tryAppendFile(path.slice(1, path.size()), mode);
+      } else {
+        return nullptr;
+      }
+    }
+  }
+
+  bool trySymlink(PathPtr path, StringPtr content, WriteMode mode) override {
+    if (path.size() == 0) {
+      if (has(mode, WriteMode::CREATE)) {
+        return false;
+      } else {
+        KJ_FAIL_REQUIRE("can't replace self") { return false; }
+      }
+    } else if (path.size() == 1) {
+      KJ_IF_MAYBE(entry, openEntry(path[0], mode)) {
+        entry->init(SymlinkNode { clock.now(), heapString(content) });
+        modified();
+        return true;
+      } else {
+        return false;
+      }
+    } else {
+      KJ_IF_MAYBE(child, tryGetParent(path[0], mode)) {
+        return child->get()->trySymlink(path.slice(1, path.size()), content, mode);
+      } else {
+        KJ_FAIL_REQUIRE("couldn't create parent directory") { return false; }
+      }
+    }
+  }
+
+  Own<File> createTemporary() override {
+    return newInMemoryFile(clock);
+  }
+
+  bool tryTransfer(PathPtr toPath, WriteMode toMode,
+                   Directory& fromDirectory, PathPtr fromPath, TransferMode mode) override {
+    if (toPath.size() == 0) {
+      if (has(toMode, WriteMode::CREATE)) {
+        return false;
+      } else {
+        KJ_FAIL_REQUIRE("can't replace self") { return false; }
+      }
+    } else if (toPath.size() == 1) {
+      // tryTransferChild() needs to at least know the node type, so do an lstat.
+      KJ_IF_MAYBE(meta, fromDirectory.tryLstat(fromPath)) {
+        KJ_IF_MAYBE(entry, openEntry(toPath[0], toMode)) {
+          // Make sure if we just cerated a new entry, and we don't successfully transfer to it, we
+          // remove the entry before returning.
+          bool needRollback = entry->node == nullptr;
+          KJ_DEFER(if (needRollback) { entries.erase(toPath[0]); });
+
+          if (tryTransferChild(*entry, meta->type, meta->lastModified, meta->size,
+                               fromDirectory, fromPath, mode)) {
+            modified();
+            needRollback = false;
+            return true;
+          } else {
+            KJ_FAIL_REQUIRE("InMemoryDirectory can't link an inode of this type", fromPath) {
+              return false;
+            }
+          }
+        } else {
+          return false;
+        }
+      } else {
+        return false;
+      }
+    } else {
+      // TODO(someday): Ideally we wouldn't create parent directories if fromPath doesn't exist.
+      //   This requires a different approach to the code here, though.
+      KJ_IF_MAYBE(child, tryGetParent(toPath[0], toMode)) {
+        return child->get()->tryTransfer(
+            toPath.slice(1, toPath.size()), toMode, fromDirectory, fromPath, mode);
+      } else {
+        return false;
+      }
+    }
+  }
+
+  Maybe<bool> tryTransferTo(Directory& toDirectory, PathPtr toPath, WriteMode toMode,
+                            PathPtr fromPath, TransferMode mode) override {
+    if (fromPath.size() <= 1) {
+      // If `fromPath` is in this directory (or *is* this directory) then we don't have any
+      // optimizations.
+      return nullptr;
+    }
+
+    // `fromPath` is in a subdirectory. It could turn out that that subdirectory is not an
+    // InMemoryDirectory and is instead something `toDirectory` is friendly with. So let's follow
+    // the path.
+
+    KJ_IF_MAYBE(child, tryGetParent(fromPath[0], WriteMode::MODIFY)) {
+      // OK, switch back to tryTransfer() but use the subdirectory.
+      return toDirectory.tryTransfer(toPath, toMode,
+          **child, fromPath.slice(1, fromPath.size()), mode);
+    } else {
+      // Hmm, doesn't exist. Fall back to standard path.
+      return nullptr;
+    }
+  }
+
+  bool tryRemove(PathPtr path) override {
+    if (path.size() == 0) {
+      KJ_FAIL_REQUIRE("can't remove self from self") { return false; }
+    } else if (path.size() == 1) {
+      auto iter = entries.find(path[0]);
+      if (iter == entries.end()) {
+        return false;
+      } else {
+        entries.erase(iter);
+        modified();
+        return true;
+      }
+    } else {
+      KJ_IF_MAYBE(child, tryGetParent(path[0], WriteMode::MODIFY)) {
+        return child->get()->tryRemove(path.slice(1, path.size()));
+      } else {
+        return false;
+      }
+    }
+  }
+
+private:
+  struct FileNode {
+    Own<File> file;
+  };
+  struct DirectoryNode {
+    Own<Directory> directory;
+  };
+  struct SymlinkNode {
+    Date lastModified;
+    String content;
+
+    Path parse() {
+      KJ_CONTEXT("parsing symlink", content);
+      return Path::parse(content);
+    }
+  };
+
+  struct EntryImpl {
+    String name;
+    OneOf<FileNode, DirectoryNode, SymlinkNode> node;
+
+    EntryImpl(String&& name): name(kj::mv(name)) {}
+
+    Own<File> init(FileNode&& value) {
+      return node.init<FileNode>(kj::mv(value)).file->clone();
+    }
+    Own<Directory> init(DirectoryNode&& value) {
+      return node.init<DirectoryNode>(kj::mv(value)).directory->clone();
+    }
+    void init(SymlinkNode&& value) {
+      node.init<SymlinkNode>(kj::mv(value));
+    }
+    bool init(OneOf<FileNode, DirectoryNode, SymlinkNode>&& value) {
+      node = kj::mv(value);
+      return node != nullptr;
+    }
+
+    void set(Own<File>&& value) {
+      node.init<FileNode>(FileNode { kj::mv(value) });
+    }
+    void set(Own<Directory>&& value) {
+      node.init<DirectoryNode>(DirectoryNode { kj::mv(value) });
+    }
+  };
+
+  Clock& clock;
+  std::map<StringPtr, EntryImpl> entries;
+  Date lastModified;
+
+  template <typename T>
+  class ReplacerImpl: public Replacer<T> {
+  public:
+    ReplacerImpl(InMemoryDirectory& directory, kj::StringPtr name, Own<T> inner, WriteMode mode)
+        : Replacer<T>(mode), directory(addRef(directory)), name(heapString(name)),
+          inner(kj::mv(inner)) {}
+
+    T& get() override { return *inner; }
+
+    bool tryCommit() override {
+      KJ_REQUIRE(!committed, "commit() already called") { return true; }
+
+      KJ_IF_MAYBE(entry, directory->openEntry(name, Replacer<T>::mode)) {
+        entry->set(inner->clone());
+        directory->modified();
+        return true;
+      } else {
+        return false;
+      }
+    }
+
+  private:
+    bool committed = false;
+    Own<InMemoryDirectory> directory;
+    kj::String name;
+    Own<T> inner;
+  };
+
+  template <typename T>
+  class BrokenReplacer: public Replacer<T> {
+    // For recovery path when exceptions are disabled.
+
+  public:
+    BrokenReplacer(Own<T> inner)
+        : Replacer<T>(WriteMode::CREATE | WriteMode::MODIFY),
+          inner(kj::mv(inner)) {}
+
+    T& get() override { return *inner; }
+    bool tryCommit() override { return false; }
+
+  private:
+    Own<T> inner;
+  };
+
+  Maybe<EntryImpl&> openEntry(kj::StringPtr name, WriteMode mode) {
+    // TODO(perf): We could avoid a copy if the entry exists, at the expense of a double-lookup if
+    //   it doesn't. Maybe a better map implementation will solve everything?
+    return openEntry(heapString(name), mode);
+  }
+
+  Maybe<EntryImpl&> openEntry(String&& name, WriteMode mode) {
+    if (has(mode, WriteMode::CREATE)) {
+      EntryImpl entry(kj::mv(name));
+      StringPtr nameRef = entry.name;
+      auto insertResult = entries.insert(std::make_pair(nameRef, kj::mv(entry)));
+
+      if (!insertResult.second && !has(mode, WriteMode::MODIFY)) {
+        // Entry already existed and MODIFY not specified.
+        return nullptr;
+      }
+
+      return insertResult.first->second;
+    } else if (has(mode, WriteMode::MODIFY)) {
+      return tryGetEntry(name);
+    } else {
+      // Neither CREATE nor MODIFY specified: precondition always fails.
+      return nullptr;
+    }
+  }
+
+  kj::Maybe<EntryImpl&> tryGetEntry(kj::StringPtr name) {
+    auto iter = entries.find(name);
+    if (iter == entries.end()) {
+      return nullptr;
+    } else {
+      return iter->second;
+    }
+  }
+
+  kj::Maybe<Own<ReadableDirectory>> tryGetParent(kj::StringPtr name) {
+    KJ_IF_MAYBE(entry, tryGetEntry(name)) {
+      return asDirectory(*entry);
+    } else {
+      return nullptr;
+    }
+  }
+
+  kj::Maybe<Own<Directory>> tryGetParent(kj::StringPtr name, WriteMode mode) {
+    // Get a directory which is a parent of the eventual target. If `mode` includes
+    // WriteMode::CREATE_PARENTS, possibly create the parent directory.
+
+    WriteMode parentMode = has(mode, WriteMode::CREATE) && has(mode, WriteMode::CREATE_PARENT)
+        ? WriteMode::CREATE | WriteMode::MODIFY   // create parent
+        : WriteMode::MODIFY;                      // don't create parent
+
+    // Possibly create parent.
+    KJ_IF_MAYBE(entry, openEntry(name, parentMode)) {
+      if (entry->node.is<DirectoryNode>()) {
+        return entry->node.get<DirectoryNode>().directory->clone();
+      } else if (entry->node == nullptr) {
+        modified();
+        return entry->init(DirectoryNode { newInMemoryDirectory(clock) });
+      }
+      // Continue on.
+    }
+
+    if (has(mode, WriteMode::CREATE)) {
+      // CREATE is documented as returning null when the file already exists. In this case, the
+      // file does NOT exist because the parent directory does not exist or is not a directory.
+      KJ_FAIL_REQUIRE("parent is not a directory") { return nullptr; }
+    } else {
+      return nullptr;
+    }
+  }
+
+  bool exists(EntryImpl& entry) {
+    if (entry.node.is<SymlinkNode>()) {
+      return exists(entry.node.get<SymlinkNode>().parse());
+    } else {
+      return true;
+    }
+  }
+  Maybe<Own<ReadableFile>> asFile(EntryImpl& entry) {
+    if (entry.node.is<FileNode>()) {
+      return entry.node.get<FileNode>().file->clone();
+    } else if (entry.node.is<SymlinkNode>()) {
+      return tryOpenFile(entry.node.get<SymlinkNode>().parse());
+    } else {
+      KJ_FAIL_REQUIRE("not a file") { return nullptr; }
+    }
+  }
+  Maybe<Own<ReadableDirectory>> asDirectory(EntryImpl& entry) {
+    if (entry.node.is<DirectoryNode>()) {
+      return entry.node.get<DirectoryNode>().directory->clone();
+    } else if (entry.node.is<SymlinkNode>()) {
+      return tryOpenSubdir(entry.node.get<SymlinkNode>().parse());
+    } else {
+      KJ_FAIL_REQUIRE("not a directory") { return nullptr; }
+    }
+  }
+  Maybe<String> asSymlink(EntryImpl& entry) {
+    if (entry.node.is<SymlinkNode>()) {
+      return heapString(entry.node.get<SymlinkNode>().content);
+    } else {
+      KJ_FAIL_REQUIRE("not a symlink") { return nullptr; }
+    }
+  }
+
+  Maybe<Own<File>> asFile(EntryImpl& entry, WriteMode mode) {
+    if (entry.node.is<FileNode>()) {
+      return entry.node.get<FileNode>().file->clone();
+    } else if (entry.node.is<SymlinkNode>()) {
+      // CREATE_PARENT doesn't apply to creating the parents of a symlink target. However, the
+      // target itself can still be created.
+      return tryOpenFile(entry.node.get<SymlinkNode>().parse(), mode - WriteMode::CREATE_PARENT);
+    } else if (entry.node == nullptr) {
+      KJ_ASSERT(has(mode, WriteMode::CREATE));
+      modified();
+      return entry.init(FileNode { newInMemoryFile(clock) });
+    } else {
+      KJ_FAIL_REQUIRE("not a file") { return nullptr; }
+    }
+  }
+  Maybe<Own<Directory>> asDirectory(EntryImpl& entry, WriteMode mode) {
+    if (entry.node.is<DirectoryNode>()) {
+      return entry.node.get<DirectoryNode>().directory->clone();
+    } else if (entry.node.is<SymlinkNode>()) {
+      // CREATE_PARENT doesn't apply to creating the parents of a symlink target. However, the
+      // target itself can still be created.
+      return tryOpenSubdir(entry.node.get<SymlinkNode>().parse(), mode - WriteMode::CREATE_PARENT);
+    } else if (entry.node == nullptr) {
+      KJ_ASSERT(has(mode, WriteMode::CREATE));
+      modified();
+      return entry.init(DirectoryNode { newInMemoryDirectory(clock) });
+    } else {
+      KJ_FAIL_REQUIRE("not a directory") { return nullptr; }
+    }
+  }
+
+  void modified() {
+    lastModified = clock.now();
+  }
+
+  bool tryTransferChild(EntryImpl& entry, const FsNode::Type type, kj::Maybe<Date> lastModified,
+                        kj::Maybe<uint64_t> size, Directory& fromDirectory, PathPtr fromPath,
+                        TransferMode mode) {
+    switch (type) {
+      case FsNode::Type::FILE:
+        KJ_IF_MAYBE(file, fromDirectory.tryOpenFile(fromPath, WriteMode::MODIFY)) {
+          if (mode == TransferMode::COPY) {
+            auto copy = newInMemoryFile(clock);
+            copy->copy(0, **file, 0, size.orDefault(kj::maxValue));
+            entry.set(kj::mv(copy));
+          } else {
+            if (mode == TransferMode::MOVE) {
+              KJ_ASSERT(fromDirectory.tryRemove(fromPath), "could't move node", fromPath) {
+                return false;
+              }
+            }
+            entry.set(kj::mv(*file));
+          }
+          return true;
+        } else {
+          KJ_FAIL_ASSERT("source node deleted concurrently during transfer", fromPath) {
+            return false;
+          }
+        }
+      case FsNode::Type::DIRECTORY:
+        KJ_IF_MAYBE(subdir, fromDirectory.tryOpenSubdir(fromPath, WriteMode::MODIFY)) {
+          if (mode == TransferMode::COPY) {
+            auto copy = refcounted<InMemoryDirectory>(clock);
+            for (auto& subEntry: subdir->get()->listEntries()) {
+              EntryImpl newEntry(kj::mv(subEntry.name));
+              Path filename(newEntry.name);
+              if (!copy->tryTransferChild(newEntry, subEntry.type, nullptr, nullptr, **subdir,
+                                          filename, TransferMode::COPY)) {
+                KJ_LOG(ERROR, "couldn't copy node of type not supported by InMemoryDirectory",
+                       filename);
+              } else {
+                StringPtr nameRef = newEntry.name;
+                copy->entries.insert(std::make_pair(nameRef, kj::mv(newEntry)));
+              }
+            }
+            entry.set(kj::mv(copy));
+          } else {
+            if (mode == TransferMode::MOVE) {
+              KJ_ASSERT(fromDirectory.tryRemove(fromPath), "could't move node", fromPath) {
+                return false;
+              }
+            }
+            entry.set(kj::mv(*subdir));
+          }
+          return true;
+        } else {
+          KJ_FAIL_ASSERT("source node deleted concurrently during transfer", fromPath) {
+            return false;
+          }
+        }
+      case FsNode::Type::SYMLINK:
+        KJ_IF_MAYBE(content, fromDirectory.tryReadlink(fromPath)) {
+          // Since symlinks are immutable, we can implement LINK the same as COPY.
+          entry.init(SymlinkNode { lastModified.orDefault(clock.now()), kj::mv(*content) });
+          if (mode == TransferMode::MOVE) {
+            KJ_ASSERT(fromDirectory.tryRemove(fromPath), "could't move node", fromPath) {
+              return false;
+            }
+          }
+          return true;
+        } else {
+          KJ_FAIL_ASSERT("source node deleted concurrently during transfer", fromPath) {
+            return false;
+          }
+        }
+      default:
+        return false;
+    }
+  }
+};
+
+// -----------------------------------------------------------------------------
+
+class AppendableFileImpl final: public AppendableFile {
+public:
+  AppendableFileImpl(Own<File>&& fileParam): file(kj::mv(fileParam)) {}
+
+  Own<OsHandle> cloneOsHandle() override {
+    return heap<AppendableFileImpl>(file->clone());
+  }
+
+  Maybe<int> getFd() override {
+    return nullptr;
+  }
+
+  Metadata stat() override {
+    return file->stat();
+  }
+
+  void sync() override { file->sync(); }
+  void datasync() override { file->datasync(); }
+
+  void write(const void* buffer, size_t size) override {
+    file->write(file->stat().size, arrayPtr(reinterpret_cast<const byte*>(buffer), size));
+  }
+
+private:
+  Own<File> file;
+};
+
+}  // namespace
+
+// -----------------------------------------------------------------------------
+
+Own<File> newInMemoryFile(Clock& clock) {
+  return refcounted<InMemoryFile>(clock);
+}
+Own<Directory> newInMemoryDirectory(Clock& clock) {
+  return refcounted<InMemoryDirectory>(clock);
+}
+Own<AppendableFile> newFileAppender(Own<File> inner) {
+  return heap<AppendableFileImpl>(kj::mv(inner));
+}
+
+} // namespace kj

c++/src/kj/filesystem.h

+// Copyright (c) 2015 Sandstorm Development Group, Inc. and contributors
+// Licensed under the MIT License:
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal
+// in the Software without restriction, including without limitation the rights
+// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+// copies of the Software, and to permit persons to whom the Software is
+// furnished to do so, subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in
+// all copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+// THE SOFTWARE.
+
+#ifndef KJ_FILESYSTEM_H_
+#define KJ_FILESYSTEM_H_
+
+#include "memory.h"
+#include "io.h"
+#include <inttypes.h>
+#include "time.h"  // TODO(now): problematic
+#include "function.h"
+
+namespace kj {
+
+template <typename T>
+class Vector;
+
+class PathPtr;
+
+class Path {
+  // A Path identifies a file in a directory tree.
+  //
+  // In KJ, we avoid representing paths as plain strings because this can lead to path injection
+  // bugs as well as numerous kinds of bugs relating to path parsing edge cases. The Path class's
+  // interface is designed to "make it hard to screw up".
+  //
+  // A "Path" is in fact a list of strings, each string being one component of the path (as would
+  // normally be separated by '/'s). Path components are not allowed to contain '/' nor '\0', nor
+  // are they allowed to be the special names "", ".", nor "..".
+  //
+  // If you explicitly want to parse a path that contains '/'s, ".", and "..", you must use
+  // parse() and/or eval(). However, users of this interface are encouraged to avoid parsing
+  // paths at all, and instead express paths as string arrays.
+  //
+  // Note that when using the Path class, ".." is always canonicalized in path space without
+  // consulting the actual filesystem. This means that "foo/some-symlink/../bar" is exactly
+  // equivalent to "foo/bar". This differs from the kernel's behavior when resolving paths passed
+  // to system calls: the kernel would have resolved "some-symlink" to its target physical path,
+  // and then would have interpreted ".." relative to that. In practice, the kernel's behavior is
+  // rarely what the user or programmer intended, hence canonicalizing in path space produces a
+  // better result.
+  //
+  // Path objects are "immutable": functions that "modify" the path return a new path. However,
+  // if the path being operated on is an rvalue, copying can be avoided. Hence it makes sense to
+  // write code like:
+  //
+  //     Path p = ...;
+  //     p = kj::mv(p).append("bar");  // in-place update, avoids string copying
+
+public:
+  Path(decltype(nullptr));  // empty path
+
+  explicit Path(StringPtr name);
+  explicit Path(String&& name);
+  // Create a Path containing only one component. `name` is a single filename; it cannot contain
+  // '/' nor '\0' nor can it be exactly "" nor "." nor "..".
+  //
+  // If you want to allow '/'s and such, you must call Path::parse(). We force you to do this to
+  // prevent path injection bugs where you didn't consider what would happen if the path contained
+  // a '/'.
+
+  explicit Path(std::initializer_list<StringPtr> parts);
+  explicit Path(ArrayPtr<const StringPtr> parts);
+  explicit Path(Array<String> parts);
+  // Construct a path from an array. Note that this means you can do:
+  //
+  //     Path{"foo", "bar", "baz"}   // equivalent to Path::parse("foo/bar/baz")
+
+  KJ_DISALLOW_COPY(Path);
+  Path(Path&&) = default;
+  Path& operator=(Path&&) = default;
+
+  Path clone() const;
+
+  static Path parse(StringPtr path);
+  // Parses a path in traditional format. Components are separated by '/'. Any use of "." or
+  // ".." will be canonicalized (if they can't be canonicalized, e.g. because the path starts with
+  // "..", an exception is thrown). Multiple consecutive '/'s will be collapsed. A leading '/'
+  // is NOT accepted -- if that is a problem, you probably want `eval()`. Trailing '/'s are
+  // ignored.
+
+  Path append(Path suffix) const&;
+  Path append(Path suffix) &&;
+  Path append(PathPtr suffix) const&;
+  Path append(PathPtr suffix) &&;
+  Path append(StringPtr suffix) const&;
+  Path append(StringPtr suffix) &&;
+  Path append(String suffix) const&;
+  Path append(String suffix) &&;
+  // Create a new path by appending the given path to this path.
+  //
+  // `suffix` cannot contain '/' characters. Instead, you can append an array:
+  //
+  //     path.append({"foo", "bar"})
+  //
+  // Or, use Path::parse():
+  //
+  //     path.append(Path::parse("foo//baz/../bar"))
+
+  Path eval(StringPtr pathText) const&;
+  Path eval(StringPtr pathText) &&;
+  // Evaluates a traditional path relative to this one. `pathText` is parsed like `parse()` would,
+  // except that:
+  // - It can contain leading ".." components that traverse up the tree.
+  // - It can have a leading '/' which completely replaces the current path.
+  //
+  // THE NAME OF THIS METHOD WAS CHOSEN TO INSPIRE FEAR.
+  //
+  // Instead of using `path.eval(str)`, always consider whether you really want
+  // `path.append(Path::parse(str))`. The former is much riskier than the latter in terms of path
+  // injection vulnerabilities.
+
+  PathPtr basename() const&;
+  Path basename() &&;
+  // Get the last component of the path. (Use `basename()[0]` to get just the string.)
+
+  PathPtr parent() const&;
+  Path parent() &&;
+  // Get the parent path.
+
+  String toString(bool absolute = false) const;
+  // Converts the path to a traditional path string, appropriate to pass to a unix system call.
+  // Never throws.
+
+  const String& operator[](size_t i) const&;
+  String operator[](size_t i) &&;
+  size_t size() const;
+  const String* begin() const;
+  const String* end() const;
+  PathPtr slice(size_t start, size_t end) const&;
+  Path slice(size_t start, size_t end) &&;
+  // A Path can be accessed as an array of strings.
+
+  Path evalWin32(StringPtr pathText) const&;
+  Path evalWin32(StringPtr pathText) &&;
+  // Evaluates a Win32-style path. Differences from `eval()` include:
+  //
+  // - Backslashes can be used as path separators.
+  // - Absolute paths begin with a drive letter followed by a colon. The drive letter, including
+  //   the colon, will become the first component of the path, e.g. "c:\foo" becomes {"c:", "foo"}.
+  // - A network path like "\\host\share\path" is parsed as {"host", "share", "path"}.
+
+  String toWin32String(bool absolute = false) const;
+  // Converts the path to a Win32 path string.
+  //
+  // (In most cases you'll want to further convert the returned string from UTF-8 to UTF-16.)
+  //
+  // If `absolute` is true, the path is expected to be an absolute path, meaning the first
+  // component is a drive letter, namespace, or network host name. These are converted to their
+  // regular Win32 format -- i.e. this method does the reverse of `evalWin32()`.
+  //
+  // This throws if the path would have unexpected special meaning or is otherwise invalid on
+  // Windows, such as if it contains backslashes (within a path component), colons, or special
+  // names like "con".
+
+private:
+  Array<String> parts;
+
+  // TODO(perf): Consider unrolling one element from `parts`, so that a one-element path doesn't
+  //   require allocation of an array.
+
+  enum { ALREADY_CHECKED };
+  Path(Array<String> parts, decltype(ALREADY_CHECKED));
+
+  friend class PathPtr;
+
+  static String stripNul(String input);
+  static void validatePart(StringPtr part);
+  static void evalPart(Vector<String>& parts, ArrayPtr<const char> part);
+  static Path evalImpl(Vector<String>&& parts, StringPtr path);
+  static Path evalWin32Impl(Vector<String>&& parts, StringPtr path);
+  static size_t countParts(StringPtr path);
+  static size_t countPartsWin32(StringPtr path);
+  static bool isWin32Drive(ArrayPtr<const char> part);
+  static bool isNetbiosName(ArrayPtr<const char> part);
+  static bool isWin32Special(StringPtr part);
+};
+
+class PathPtr {
+  // Points to a Path or a slice of a Path, but doesn't own it.
+  //
+  // PathPtr is to Path as ArrayPtr is to Array and StringPtr is to String.
+
+public:
+  PathPtr(decltype(nullptr));
+  PathPtr(const Path& path);
+
+  Path clone();
+  Path append(Path suffix) const;
+  Path append(PathPtr suffix) const;
+  Path append(StringPtr suffix) const;
+  Path append(String suffix) const;
+  Path eval(StringPtr pathText) const;
+  PathPtr basename() const;
+  PathPtr parent() const;
+  String toString(bool absolute = false) const;
+  const String& operator[](size_t i) const;
+  size_t size() const;
+  const String* begin() const;
+  const String* end() const;
+  PathPtr slice(size_t start, size_t end) const;
+  Path evalWin32(StringPtr pathText) const;
+  String toWin32String(bool absolute = false) const;
+  // Equivalent to the corresponding methods of `Path`.
+
+private:
+  ArrayPtr<const String> parts;
+
+  explicit PathPtr(ArrayPtr<const String> parts);
+
+  friend class Path;
+};
+
+// =======================================================================================
+// The filesystem API
+//
+// This API is strictly synchronous because, unfortunately, there's no such thing as asynchronous
+// filesystem access in practice. The filesystem drivers on Linux are written to assume they can
+// block. The AIO API is only actually asynchronous for reading/writing the raw file blocks, but if
+// the filesystem needs to be involved (to allocate blocks, update metadata, etc.) that will block.
+// It's best to imagine that the filesystem is just another tier of memory that happens to be
+// slower than RAM (which is slower than L3 cache, which is slower than L2, which is slower than
+// L1). You can't do asynchronous RAM access so why asynchronous filesystem? The only way to
+// parallelize these is using threads.
+
+class OsHandle {
+public:
+  Own<OsHandle> clone();
+  // Creates a new object of exactly the same type as this one, pointing at exactly the same
+  // external object.
+  //
+  // Under the hood, this will call dup(), so the FD number will not be the same.
+
+  virtual Maybe<int> getFd() = 0;
+  // Get the underlying file descriptor, if any. Returns nullptr if this object actually isn't
+  // wrapping a file descriptor.
+  //
+  // TODO(now): Do we really want everything inheriting OsHandle or should people dynamic_cast to
+  //     it? What about people without RTTI?
+
+protected:
+  virtual Own<OsHandle> cloneOsHandle() = 0;
+  // Implements clone(). Required to return an object with exactly the same type as this one.
+  // Hence, every subclass must implement this.
+};
+
+class FsNode: public OsHandle {
+public:
+  Own<FsNode> clone();
+
+  enum class Type {
+    FILE,
+    DIRECTORY,
+    SYMLINK,
+    BLOCK_DEVICE,
+    CHARACTER_DEVICE,
+    NAMED_PIPE,
+    SOCKET,
+    OTHER,
+  };
+
+  struct Metadata {
+    Type type = Type::FILE;
+
+    uint64_t size = 0;
+    // Logical size of the file.
+
+    uint64_t spaceUsed = 0;
+    // Physical size of the file on disk. May be smaller for sparse files, or larger for
+    // pre-allocated files.
+
+    Date lastModified = UNIX_EPOCH;
+    // Last modification time of the file.
+
+    uint linkCount = 1;
+    // Number of hard links pointing to this node.
+
+    // Not currently included:
+    // - Device / inode number: Rarely useful, and not safe to use in practice anyway.
+    // - Access control info: Differs wildly across platforms, and KJ prefers capabilities anyway.
+    // - Other timestamps: Differs across platforms.
+    // - Device number: If you care, you're probably doing platform-specific stuff anyway.
+  };
+
+  virtual Metadata stat() = 0;
+
+  virtual void sync() = 0;
+  virtual void datasync() = 0;
+  // Maps to fsync() and fdatasync() system calls.
+  //
+  // Also, when creating or overwriting a file, the first call to sync() atomically links the file
+  // into the filesystem (*after* syncing the data), so than incomplete data is never visible to
+  // other processes. (In practice this works by writing into a temporary file and then rename()ing
+  // it.)
+};
+
+class ReadableFile: public FsNode {
+public:
+  Own<ReadableFile> clone();
+
+  String readAllText();
+  // Read all text in the file and return as a big string.
+
+  Array<byte> readAllBytes();
+  // Read all bytes in the file and return as a big byte array.
+  //
+  // This differs from mmap() in that the read is performed all at once. Future changes to the file
+  // do not affect the returned copy. Consider using mmap() instead, particularly for large files.
+
+  virtual size_t read(uint64_t offset, ArrayPtr<byte> buffer) = 0;
+  // Fills `buffer` with data starting at `offset`. Returns the number of bytes actually read --
+  // the only time this is less than `buffer.size()` is when EOF occurs mid-buffer.
+
+  virtual Array<const byte> mmap(uint64_t offset, uint64_t size) = 0;
+  // Maps the file to memory read-only. The returned array always has exactly the requested size.
+  // Depending on the capabilities of the OS and filesystem, the mapping may or may not reflect
+  // changes that happen to the file after mmap() returns.
+  //
+  // Multiple calls to mmap() on the same file may or may not return the same mapping (it is
+  // immutable, so there's no possibility of interference).
+  //
+  // If the file cannot be mmap()ed, an implementation may choose to allocate a buffer on the heap,
+  // read into it, and return that. This should only happen if a real mmap() is impossible.
+  //
+  // The returned array is always exactly the size requested. However, accessing bytes beyond the
+  // current end of the file may raise SIGBUS, or may simply return zero.
+
+  virtual Array<byte> mmapPrivate(uint64_t offset, uint64_t size) = 0;
+  // Like mmap() but returns a view that the caller can modify. Modifications will not be written
+  // to the underlying file. Every call to this method returns a unique mapping. Changes made to
+  // the underlying file by other clients may or may not be reflected in the mapping -- in fact,
+  // some changes may be reflected while others aren't, even within the same mapping.
+  //
+  // In practice this is often implemented using copy-on-write pages. When you first write to a
+  // page, a copy is made. Hence, changes to the underlying file within that page stop being
+  // reflected in the mapping.
+};
+
+class AppendableFile: public FsNode, public OutputStream {
+public:
+  Own<AppendableFile> clone();
+
+  // All methods are inherited.
+};
+
+class WritableFileMapping {
+public:
+  virtual ArrayPtr<byte> get() = 0;
+  // Gets the mapped bytes. The returned array can be modified, and those changes may be written to
+  // the underlying file, but there is no guarantee that they are written unless you subsequently
+  // call changed().
+
+  virtual void changed(ArrayPtr<byte> slice) = 0;
+  // Notifies the implementation that the given bytes have changed. For some implementations this
+  // may be a no-op while for others it may be necessary in order for the changes to be written
+  // back at all.
+  //
+  // `slice` must be a slice of `bytes()`.
+
+  virtual void sync(ArrayPtr<byte> slice) = 0;
+  // Implies `changed()`, and then waits until the range has actually been written to disk before
+  // returning.
+  //
+  // `slice` must be a slice of `bytes()`.
+};
+
+class File: public ReadableFile {
+public:
+  Own<File> clone();
+
+  void writeAll(ArrayPtr<const byte> bytes);
+  void writeAll(StringPtr text);
+  // Completely replace the file with the given bytes or text.
+
+  virtual void write(uint64_t offset, ArrayPtr<const byte> data) = 0;
+  // Write the given data starting at the given offset in the file.
+
+  virtual void zero(uint64_t offset, uint64_t size) = 0;
+  // Write zeros to the file, starting at `offset` and continuing for `size` bytes. If the platform
+  // supports it, this will "punch a hole" in the file, such that blocks that are entirely zeros
+  // do not take space on disk.
+
+  virtual void truncate(uint64_t size) = 0;
+  // Set the file end pointer to `size`. If `size` is less than the current size, data past the end
+  // is truncated. If `size` is larger than the current size, zeros are added to the end of the
+  // file. If the platform supports it, blocks containing all-zeros will not be stored to disk.
+
+  virtual Own<WritableFileMapping> mmapWritable(uint64_t offset, uint64_t size) = 0;
+  // Like ReadableFile::mmap() but returns a mapping for which any changes will be immediately
+  // visible in other mappings of the file on the same system and will eventually be written back
+  // to the file.
+
+  virtual size_t copy(uint64_t offset, ReadableFile& from, uint64_t fromOffset, uint64_t size);
+  // Copies bytes from one file to another.
+  //
+  // Copies `size` bytes or to EOF, whichever comes first. Returns the number of bytes actually
+  // copied. Hint: Pass kj::maxValue for `size` to always copy to EOF.
+  //
+  // The copy is not atomic. Concurrent writes may lead to garbage results.
+  //
+  // The default implementation performs a series of reads and writes. Subclasses can often provide
+  // superior implementations that offload the work to the OS or even implement copy-on-write.
+};
+
+class ReadableDirectory: public FsNode {
+  // Read-only subset of `Directory`.
+
+public:
+  Own<ReadableDirectory> clone();
+
+  virtual Array<String> listNames() = 0;
+  // List the contents of this directory. Does NOT include "." nor "..".
+
+  struct Entry {
+    FsNode::Type type;
+    String name;
+  };
+
+  virtual Array<Entry> listEntries() = 0;
+  // List the contents of the directory including the type of each file. On some platforms and
+  // filesystems, this is just as fast as listNames(), but on others it may require stat()ing each
+  // file.
+
+  virtual bool exists(PathPtr path) = 0;
+  // Does the specified path exist?
+  //
+  // If the path is a symlink, the symlink is followed and the return value indicates if the target
+  // exists. If you want to know if the symlink exists, use lstat(). (This implies that listNames()
+  // may return names for which exists() reports false.)
+
+  FsNode::Metadata lstat(PathPtr path);
+  virtual Maybe<FsNode::Metadata> tryLstat(PathPtr path) = 0;
+  // Gets metadata about the path. If the path is a symlink, it is not followed -- the metadata
+  // describes the symlink itself. `tryLstat()` returns null if the path doesn't exist.
+
+  Own<ReadableFile> openFile(PathPtr path);
+  virtual Maybe<Own<ReadableFile>> tryOpenFile(PathPtr path) = 0;
+  // Open a file for reading.
+  //
+  // `tryOpenFile()` returns null if the path doesn't exist. Other errors still throw exceptions.
+
+  Own<ReadableDirectory> openSubdir(PathPtr path);
+  virtual Maybe<Own<ReadableDirectory>> tryOpenSubdir(PathPtr path) = 0;
+  // Opens a subdirectory.
+  //
+  // `tryOpenSubdir()` returns null if the path doesn't exist. Other errors still throw exceptions.
+
+  String readlink(PathPtr path);
+  virtual Maybe<String> tryReadlink(PathPtr path) = 0;
+  // If `path` is a symlink, reads and returns the link contents.
+  //
+  // See Directory::symlink() for warnings about symlinks.
+};
+
+enum class WriteMode {
+  // Mode for opening a file (or directory) for write.
+  //
+  // (To open a file or directory read-only, do not specify a mode.)
+  //
+  // WriteMode is a bitfield. Hence, it overloads the bitwise logic operators. To check if a
+  // particular bit is set in a bitfield, use kj::has(), like:
+  //
+  //     if (kj::has(mode, WriteMode::MUST_EXIST)) {
+  //       requireExists(path);
+  //     }
+  //
+  // (`if (mode & WriteMode::MUST_EXIST)` doesn't work because WriteMode is an enum class, which
+  // cannot be converted to bool. Alas, C++ does not allow you to define a conversion operator
+  // on an enum type, so we can't define a conversion to bool.)
+
+  // -----------------------------------------
+  // Core flags
+  //
+  // At least one of CREATE or MODIFY must be specified. Optionally, the two flags can be combined
+  // with a bitwise-OR.
+
+  CREATE = 1,
+  // Create a new empty file.
+  //
+  // This can be OR'd with MODIFY, but not with REPLACE.
+  //
+  // When not combined with MODIFY, if the file already exists (including as a broken symlink),
+  // tryOpenFile() returns null (and openFile() throws).
+  //
+  // When combined with MODIFY, if the path already exists, it will be opened as if CREATE hadn't
+  // been specified at all. If the path refers to a broken symlink, the file at the target of the
+  // link will be created (if its parent directory exists).
+
+  MODIFY = 2,
+  // Modify an existing file.
+  //
+  // This can be OR'd with CREATE, but not with REPLACE.
+  //
+  // When not combined with CREATE, if the file doesn't exist (including if it is a broken symlink),
+  // tryOpenFile() returns null (and openFile() throws).
+  //
+  // When combined with CREATE, if the path doesn't exist, it will be created as if MODIFY hadn't
+  // been specified at all. If the path refers to a broken symlink, the file at the target of the
+  // link will be created (if its parent directory exists).
+
+  // -----------------------------------------
+  // Additional flags
+  //
+  // Any number of these may be OR'd with the core flags.
+
+  CREATE_PARENT = 4,
+  // Indicates that if the target node's parent directory doesn't exist, it should be created
+  // automatically, along with its parent, and so on. This creation is NOT atomic.
+  //
+  // This bit only makes sense with CREATE or REPLACE.
+
+  EXECUTABLE = 8,
+  // Mark this file executable, if this is a meaningful designation on the host platform.
+
+  PRIVATE = 16,
+  // Indicates that this file is sensitive and should have permissions masked so that it is only
+  // accessible by the current user.
+  //
+  // When this is not used, the platform's default access control settings are used. On Unix,
+  // that usually means the umask is applied. On Windows, it means permissions are inherited from
+  // the parent.
+};
+
+inline constexpr WriteMode operator|(WriteMode a, WriteMode b) {
+  return static_cast<WriteMode>(static_cast<uint>(a) | static_cast<uint>(b));
+}
+inline constexpr WriteMode operator&(WriteMode a, WriteMode b) {
+  return static_cast<WriteMode>(static_cast<uint>(a) & static_cast<uint>(b));
+}
+inline constexpr WriteMode operator+(WriteMode a, WriteMode b) {
+  return static_cast<WriteMode>(static_cast<uint>(a) | static_cast<uint>(b));
+}
+inline constexpr WriteMode operator-(WriteMode a, WriteMode b) {
+  return static_cast<WriteMode>(static_cast<uint>(a) & ~static_cast<uint>(b));
+}
+template <typename T, typename = EnableIf<__is_enum(T)>>
+bool has(T haystack, T needle) {
+  return (static_cast<__underlying_type(T)>(haystack) &
+          static_cast<__underlying_type(T)>(needle)) ==
+          static_cast<__underlying_type(T)>(needle);
+}
+
+enum class TransferMode {
+  // Specifies desired behavior for Directory::transfer().
+
+  MOVE,
+  // The node is moved to the new location, i.e. the old location is deleted. If possible, this
+  // move is performed without copying, otherwise it is performed as a copy followed by a delete.
+
+  LINK,
+  // The new location becomes a synonym for the old location (a "hard link"). Filesystems have
+  // varying support for this -- typically, it is not supported on directories.
+
+  COPY
+  // The new location becomes a copy of the old.
+  //
+  // Some filesystems may implement this in terms of copy-on-write.
+  //
+  // If the filesystem supports sparse files, COPY takes sparseness into account -- it will punch
+  // holes in the target file where holes exist in the source file.
+};
+
+class Directory: public ReadableDirectory {
+  // Refers to a specific directory on disk.
+  //
+  // A `Directory` object *only* provides access to children of the directory, not parents. That
+  // is, you cannot open the file "..", nor jump to the root directory with "/".
+  //
+  // On OSs that support in, a `Directory` is backed by an open handle to the directory node. This
+  // means:
+  // - If the directory is renamed on-disk, the `Directory` object still points at it.
+  // - Opening files in the directory only requires the OS to traverse the path from the directory
+  //   to the file; it doesn't have to re-traverse all the way from the filesystem root.
+
+public:
+  Own<Directory> clone();
+
+  template <typename T>
+  class Replacer {
+    // Implements an atomic replacement of a file or directory, allowing changes to be made to
+    // storage in a way that avoids losing data in a power outage and prevents other processes
+    // from observing content in an inconsistent state.
+    //
+    // `T` may be `File` or `Directory`. For readability, the text below describes replacing a
+    // file, but the logic is the same for directories.
+    //
+    // When you call `Directory::replaceFile()`, a temporary file is created, but the specified
+    // path is not yet touched. You may call `get()` to obtain the temporary file object, through
+    // which you may initialize its content, knowing that no other process can see it yet. The file
+    // is atomically moved to its final path when you call `commit()`. If you destroy the Replacer
+    // without calling commit(), the temporary file is deleted.
+    //
+    // Note that most operating systems sadly do not support creating a truly unnamed temporary file
+    // and then linking it in later. Moreover, the file cannot necessarily be created in the system
+    // temporary directory because it might not be on the same filesystem as the target. Therefore,
+    // the replacement file may initially be created in the same directory as its eventual target.
+    // The implementation of Directory will choose a name that is unique and "hidden" according to
+    // the conventions of the filesystem. Additionally, the implementation of Directory will avoid
+    // returning these temporary files from its list*() methods, in order to avoid observable
+    // inconsistencies across platforms.
+  public:
+    explicit Replacer(WriteMode mode);
+
+    virtual T& get() = 0;
+    // Gets the File or Directory representing the replacement data. Fill in this object before
+    // calling commit().
+
+    void commit();
+    virtual bool tryCommit() = 0;
+    // Commit the replacement.
+    //
+    // `tryCommit()` may return false based on the CREATE/MODIFY bits passed as the WriteMode when
+    // the replacement was initiated. (If CREATE but not MODIFY was used, tryCommit() returns
+    // false to indicate that the target file already existed. If MODIFY but not CREATE was used,
+    // tryCommit() returns false to indicate that the file didn't exist.)
+    //
+    // `commit()` is atomic, meaning that there is no point in time at which other processes
+    // observing the file will see it in an intermediate state -- they will either see the old
+    // content or the complete new content. This includes in the case of a power outage or machine
+    // failure: on recovery, the file will either be in the old state or the new state, but not in
+    // some intermediate state.
+    //
+    // It's important to note that a power failure *after commit() returns* can still revert the
+    // file to its previous state. That is, `commit()` does NOT guarantee that, upon return, the
+    // new content is durable. In order to guarantee this, you must call `sync()` on the immediate
+    // parent directory of the replaced file.
+    //
+    // Note that, sadly, not all filesystems / platforms are capable of supporting all of the
+    // guarantees documented above. In such cases, commit() will make a best-effort attempt to do
+    // what it claims. Some examples of possible problems include:
+    // - Any guarantees about durability through a power outage probably require a journaling
+    //   filesystem.
+    // - Many platforms do not support atomically replacing a non-empty directory. Linux does as
+    //   of kernel 3.15 (via the renameat2() syscall using RENAME_EXCHANGE). Where not supported,
+    //   the old directory will be moved away just before the replacement is moved into place.
+    // - Many platforms do not support atomically requiring the existence or non-existence of a
+    //   file before replacing it. In these cases, commit() may have to perform the check as a
+    //   separate step, with a small window for a race condition.
+    // - Many platforms do not support "unlinking" a non-empty directory, meaning that a replaced
+    //   directory will need to be deconstructed by deleting all contents. If another process has
+    //   the directory open when it is replaced, that process will observe the contents
+    //   disappearing after the replacement (actually, a swap) has taken place. This differs from
+    //   files, where a process that has opened a file before it is replaced will continue see the
+    //   file's old content unchanged after the replacement.
+
+  protected:
+    const WriteMode mode;
+  };
+
+  using ReadableDirectory::openFile;
+  using ReadableDirectory::openSubdir;
+  using ReadableDirectory::tryOpenFile;
+  using ReadableDirectory::tryOpenSubdir;
+
+  Own<File> openFile(PathPtr path, WriteMode mode);
+  virtual Maybe<Own<File>> tryOpenFile(PathPtr path, WriteMode mode) = 0;
+  // Open a file for writing.
+  //
+  // `tryOpenFile()` returns null if the path is required to exist but doesn't (MODIFY or REPLACE)
+  // or if the path is required not to exist but does (CREATE or RACE).
+
+  virtual Own<Replacer<File>> replaceFile(PathPtr path, WriteMode mode) = 0;
+  // Construct a file which, when ready, will be atomically moved to `path`, replacing whatever
+  // is there already. See `Replacer<T>` for detalis.
+  //
+  // The `CREATE` and `MODIFY` bits of `mode` are not enforced until commit time, hence
+  // `replaceFile()` has no "try" variant.
+
+  virtual Own<File> createTemporary() = 0;
+  // Create a temporary file backed by this directory's filesystem, but which isn't linked into
+  // the directory tree. The file is deleted from disk when all references to it have been dropped.
+
+  Own<AppendableFile> appendFile(PathPtr path, WriteMode mode);
+  virtual Maybe<Own<AppendableFile>> tryAppendFile(PathPtr path, WriteMode mode) = 0;
+  // Opens the file for appending only. Useful for log files.
+  //
+  // If the underlying filesystem supports it, writes to the file will always be appended even if
+  // other writers are writing to the same file at the same time -- however, some implementations
+  // may instead assume that no other process is changing the file size between writes.
+
+  Own<Directory> openSubdir(PathPtr path, WriteMode mode);
+  virtual Maybe<Own<Directory>> tryOpenSubdir(PathPtr path, WriteMode mode) = 0;
+  // Opens a subdirectory for writing.
+
+  virtual Own<Replacer<Directory>> replaceSubdir(PathPtr path, WriteMode mode) = 0;
+  // Construct a directory which, when ready, will be atomically moved to `path`, replacing
+  // whatever is there already. See `Replacer<T>` for detalis.
+  //
+  // The `CREATE` and `MODIFY` bits of `mode` are not enforced until commit time, hence
+  // `replaceSubdir()` has no "try" variant.
+
+  void symlink(PathPtr linkpath, StringPtr content, WriteMode mode);
+  virtual bool trySymlink(PathPtr linkpath, StringPtr content, WriteMode mode) = 0;
+  // Create a symlink. `content` is the raw text which will be written into the symlink node.
+  // How this text is interpreted is entirely dependent on the filesystem. Note in particular that:
+  // - Windows will require a path that uses backslashes as the separator.
+  // - InMemoryDirectory does not support symlinks containing "..".
+  //
+  // Unfortunately under many implementations symlink() can be used to break out of the directory
+  // by writing an absolute path or utilizing "..". Do not call this method with a value for
+  // `target` that you don't trust.
+  //
+  // `mode` must be CREATE or REPLACE, not MODIFY. CREATE_PARENT is honored but EXECUTABLE and
+  // PRIVATE have no effect. `trySymlink()` returns false in CREATE mode when the target already
+  // exists.
+
+  void transfer(PathPtr toPath, WriteMode toMode,
+                PathPtr fromPath, TransferMode mode);
+  void transfer(PathPtr toPath, WriteMode toMode,
+                Directory& fromDirectory, PathPtr fromPath,
+                TransferMode mode);
+  virtual bool tryTransfer(PathPtr toPath, WriteMode toMode,
+                           Directory& fromDirectory, PathPtr fromPath,
+                           TransferMode mode);
+  virtual Maybe<bool> tryTransferTo(Directory& toDirectory, PathPtr toPath, WriteMode toMode,
+                                    PathPtr fromPath, TransferMode mode);
+  // Move, link, or copy a file/directory tree from one location to another.
+  //
+  // Filesystems vary in what kinds of transfers are allowed, especially for TransferMode::LINK,
+  // and whether TransferMode::MOVE is implemented as an actual move vs. copy+delete.
+  //
+  // tryTransfer() returns false if the source location didn't exist, or when `toMode` is CREATE
+  // and the target already exists. The default implementation implements only TransferMode::COPY.
+  //
+  // tryTransferTo() exists to implement double-dispatch. It should be called as a fallback by
+  // implementations of tryTransfer() in cases where the target directory would otherwise fail or
+  // perform a pessimal transfer. The default implementation returns nullptr, which the caller
+  // should interpret as: "I don't have any special optimizations; do the obvious thing."
+  //
+  // `toMode` controls how the target path is created. CREATE_PARENT is honored but EXECUTABLE and
+  // PRIVATE have no effect.
+
+  void remove(PathPtr path);
+  virtual bool tryRemove(PathPtr path) = 0;
+  // Deletes/unlinks the given path. If the path names a directory, it is recursively deleted.
+  //
+  // tryRemove() returns false if the path doesn't exist; remove() throws in this case.
+
+  // TODO(someday):
+  // - Support sockets? There's no openat()-like interface for sockets, so it's hard to support
+  //   them currently. Also you'd probably want to use them with the async library.
+  // - Support named pipes? Unclear if there's a use case that isn't better-served by sockets.
+  //   Then again, they can be openat()ed.
+  // - Support watching for changes (inotify). Probably also requires the async library. Also
+  //   lacks openat()-like semantics.
+  // - xattrs -- linux-specific
+  // - chown/chmod/etc. -- unix-specific, ACLs, eww
+  // - set timestamps -- only needed by archiving programs/
+  // - advisory locks
+  // - sendfile?
+  // - fadvise and such
+
+private:
+  static void commitFailed(WriteMode mode);
+};
+
+class Filesystem {
+public:
+  virtual Directory& getRoot() = 0;
+  // Get the filesystem's root directory.
+  //
+  // `getRoot()` returns a special directory for which `getFd()` throws. You may call
+  // `getRoot().openSubdir(nullptr)` to get a Directory representing the root which has a valid
+  // file descriptor (and which isn't affected by `chroot()`).
+
+  virtual Directory& getCurrent() = 0;
+  // Get the filesystem's current directory.
+  //
+  // The returned Directory object is a special one for which a call to the `chdir()` syscall will
+  // change the Directory's target. We recommend against using `chdir()` in KJ code, but if you
+  // want a Directory that avoids this behavior, you can call `.openSubdir(nullptr)` on it to
+  // reopen itself. Additionally, `getCurrent()` returns a directory for which `getFd()` throws;
+  // `openSubdir(nullptr)` solves that problem as well.
+
+  virtual Path getCurrentPath() = 0;
+  // Get the path from the root to the current directory. Note that because a `Directory` does not
+  // provide access to its parent, if you want to follow `..` from the current directory, you must
+  // use `getCurrentPath().eval("..")` or `getCurrentPath().parent()`.
+  //
+  // This function attempts to determine the path as it appeared in the user's shell before this
+  // program was started. That means, if the user had `cd`ed into a symlink, the path through that
+  // symlink is returned, *not* the canonical path.
+  //
+  // Because of this, there is an important difference between how the operating system interprets
+  // "../foo" and what you get when you write `getCurrentPath().eval("../foo")`: The former
+  // will interpret ".." relative to the directory's canonical path, whereas the latter will
+  // interpret it relative to the path shown in the user's shell. In practice, the latter is
+  // almost always what the user wants! But the former behavior is what almost all commands do
+  // in practice, and it leads to confusion. KJ commands should implement the behavior the user
+  // expects.
+};
+
+// =======================================================================================
+
+Own<File> newInMemoryFile(Clock& clock);
+Own<Directory> newInMemoryDirectory(Clock& clock);
+// Construct file and directory objects which reside in-memory.
+//
+// InMemoryFile has the following special properties:
+// - The backing store is not sparse and never gets smaller even if you truncate the file.
+// - While a non-private memory mapping exists, the backing store cannot get larger. Any operation
+//   which would expand it will throw.
+//
+// InMemoryDirectory has the following special properties:
+// - Symlinks are processed using Path::parse(). This implies tha a symlink cannot point to a
+//   parent directory -- InMemoryDirectory does not know its parent.
+// - link() can link directory nodes in addition to files.
+// - link() and rename() accept any kind of Directory as `fromDirectory` -- it doesn't need to be
+//   another InMemoryDirectory. However, for rename(), the from path must be a directory.
+
+Own<AppendableFile> newFileAppender(Own<File> inner);
+// Creates an AppendableFile by wrapping a File. Note that this implementation assumes it is the
+// only writer. A correct implementation should always append to the file even if other writes
+// are happening simultaneously, as is achieved with the O_APPEND flag to open(2), but that
+// behavior is not possible to emulate on top of `File`.
+
+Own<ReadableFile> newDiskReadableFile(kj::AutoCloseFd fd);
+Own<AppendableFile> newDiskAppendableFile(kj::AutoCloseFd fd);
+Own<File> newDiskFile(kj::AutoCloseFd fd);
+Own<ReadableDirectory> newDiskReadableDirectory(kj::AutoCloseFd fd);
+Own<Directory> newDiskDirectory(kj::AutoCloseFd fd);
+
+Own<Filesystem> newDiskFilesystem();
+
+// =======================================================================================
+// inline implementation details
+
+inline Path::Path(decltype(nullptr)): parts(nullptr) {}
+inline Path::Path(std::initializer_list<StringPtr> parts)
+    : Path(arrayPtr(parts.begin(), parts.end())) {}
+inline Path::Path(Array<String> parts, decltype(ALREADY_CHECKED))
+    : parts(kj::mv(parts)) {}
+inline Path Path::clone() const { return PathPtr(*this).clone(); }
+inline Path Path::append(Path suffix) const& { return PathPtr(*this).append(kj::mv(suffix)); }
+inline Path Path::append(PathPtr suffix) const& { return PathPtr(*this).append(suffix); }
+inline Path Path::append(StringPtr suffix) const& { return append(Path(suffix)); }
+inline Path Path::append(StringPtr suffix) && { return kj::mv(*this).append(Path(suffix)); }
+inline Path Path::append(String suffix) const& { return append(Path(kj::mv(suffix))); }
+inline Path Path::append(String suffix) && { return kj::mv(*this).append(Path(kj::mv(suffix))); }
+inline Path Path::eval(StringPtr pathText) const& { return PathPtr(*this).eval(pathText); }
+inline PathPtr Path::basename() const& { return PathPtr(*this).basename(); }
+inline PathPtr Path::parent() const& { return PathPtr(*this).parent(); }
+inline const String& Path::operator[](size_t i) const& { return parts[i]; }
+inline String Path::operator[](size_t i) && { return kj::mv(parts[i]); }
+inline size_t Path::size() const { return parts.size(); }
+inline const String* Path::begin() const { return parts.begin(); }
+inline const String* Path::end() const { return parts.end(); }
+inline PathPtr Path::slice(size_t start, size_t end) const& {
+  return PathPtr(*this).slice(start, end);
+}
+inline String Path::toString(bool absolute) const { return PathPtr(*this).toString(absolute); }
+inline Path Path::evalWin32(StringPtr pathText) const& {
+  return PathPtr(*this).evalWin32(pathText);
+}
+inline String Path::toWin32String(bool absolute) const {
+  return PathPtr(*this).toWin32String(absolute);
+}
+
+inline PathPtr::PathPtr(decltype(nullptr)): parts(nullptr) {}
+inline PathPtr::PathPtr(const Path& path): parts(path.parts) {}
+inline PathPtr::PathPtr(ArrayPtr<const String> parts): parts(parts) {}
+inline Path PathPtr::append(StringPtr suffix) const { return append(Path(suffix)); }
+inline Path PathPtr::append(String suffix) const { return append(Path(kj::mv(suffix))); }
+inline const String& PathPtr::operator[](size_t i) const { return parts[i]; }
+inline size_t PathPtr::size() const { return parts.size(); }
+inline const String* PathPtr::begin() const { return parts.begin(); }
+inline const String* PathPtr::end() const { return parts.end(); }
+inline PathPtr PathPtr::slice(size_t start, size_t end) const {
+  return PathPtr(parts.slice(start, end));
+}
+
+inline Own<OsHandle> OsHandle::clone() { return cloneOsHandle(); }
+inline Own<FsNode> FsNode::clone() { return cloneOsHandle().downcast<FsNode>(); }
+inline Own<ReadableFile> ReadableFile::clone() { return cloneOsHandle().downcast<ReadableFile>(); }
+inline Own<AppendableFile> AppendableFile::clone() {
+  return cloneOsHandle().downcast<AppendableFile>();
+}
+inline Own<File> File::clone() { return cloneOsHandle().downcast<File>(); }
+inline Own<ReadableDirectory> ReadableDirectory::clone() {
+  return cloneOsHandle().downcast<ReadableDirectory>();
+}
+inline Own<Directory> Directory::clone() { return cloneOsHandle().downcast<Directory>(); }
+
+inline void Directory::transfer(
+    PathPtr toPath, WriteMode toMode, PathPtr fromPath, TransferMode mode) {
+  return transfer(toPath, toMode, *this, fromPath, mode);
+}
+
+template <typename T>
+inline Directory::Replacer<T>::Replacer(WriteMode mode): mode(mode) {}
+
+template <typename T>
+void Directory::Replacer<T>::commit() {
+  if (!tryCommit()) commitFailed(mode);
+}
+
+} // namespace kj
+
+#endif // KJ_FILESYSTEM_H_