Vendor dependencies with dep

vendor/bazil.org/fuse/doc/.gitignore

@@ -0,0 +1,4 @@
+/*.seq.svg
+
+# not ignoring *.seq.png; we want those committed to the repo
+# for embedding on Github

vendor/bazil.org/fuse/doc/README.md

@@ -0,0 +1,6 @@
+# bazil.org/fuse documentation
+
+See also API docs at http://godoc.org/bazil.org/fuse
+
+- [The mount sequence](mount-sequence.md)
+- [Writing documentation](writing-docs.md)

vendor/bazil.org/fuse/doc/mount-linux-error-init.seq

@@ -0,0 +1,32 @@
+seqdiag {
+  app;
+  fuse [label="bazil.org/fuse"];
+  fusermount;
+  kernel;
+  mounts;
+
+  app;
+  fuse [label="bazil.org/fuse"];
+  fusermount;
+  kernel;
+  mounts;
+
+  app -> fuse [label="Mount"];
+  fuse -> fusermount [label="spawn, pass socketpair fd"];
+  fusermount -> kernel [label="open /dev/fuse"];
+  fusermount -> kernel [label="mount(2)"];
+  kernel ->> mounts [label="mount is visible"];
+  fusermount <-- kernel [label="mount(2) returns"];
+  fuse <<-- fusermount [diagonal, label="exit, receive /dev/fuse fd", leftnote="on Linux, successful exit here\nmeans the mount has happened,\nthough InitRequest might not have yet"];
+  app <-- fuse [label="Mount returns\nConn.Ready is already closed"];
+
+  app -> fuse [label="fs.Serve"];
+  fuse => kernel [label="read /dev/fuse fd", note="starts with InitRequest"];
+  fuse -> app [label="Init"];
+  fuse <-- app [color=red];
+  fuse -> kernel [label="write /dev/fuse fd", color=red];
+  kernel -> kernel [label="set connection\nstate to error", color=red];
+  fuse <-- kernel;
+  ... conn.MountError == nil, so it is still mounted ...
+  ... call conn.Close to clean up ...
+}

vendor/bazil.org/fuse/doc/mount-linux.seq

@@ -0,0 +1,41 @@
+seqdiag {
+  // seqdiag -T svg -o doc/mount-osx.svg doc/mount-osx.seq
+  app;
+  fuse [label="bazil.org/fuse"];
+  fusermount;
+  kernel;
+  mounts;
+
+  app -> fuse [label="Mount"];
+  fuse -> fusermount [label="spawn, pass socketpair fd"];
+  fusermount -> kernel [label="open /dev/fuse"];
+  fusermount -> kernel [label="mount(2)"];
+  kernel ->> mounts [label="mount is visible"];
+  fusermount <-- kernel [label="mount(2) returns"];
+  fuse <<-- fusermount [diagonal, label="exit, receive /dev/fuse fd", leftnote="on Linux, successful exit here\nmeans the mount has happened,\nthough InitRequest might not have yet"];
+  app <-- fuse [label="Mount returns\nConn.Ready is already closed", rightnote="InitRequest and StatfsRequest\nmay or may not be seen\nbefore Conn.Ready,\ndepending on platform"];
+
+  app -> fuse [label="fs.Serve"];
+  fuse => kernel [label="read /dev/fuse fd", note="starts with InitRequest"];
+  fuse => app [label="FS/Node/Handle methods"];
+  fuse => kernel [label="write /dev/fuse fd"];
+  ... repeat ...
+
+  ... shutting down ...
+  app -> fuse [label="Unmount"];
+  fuse -> fusermount [label="fusermount -u"];
+  fusermount -> kernel;
+  kernel <<-- mounts;
+  fusermount <-- kernel;
+  fuse <<-- fusermount [diagonal];
+  app <-- fuse [label="Unmount returns"];
+
+  // actually triggers before above
+  fuse <<-- kernel [diagonal, label="/dev/fuse EOF"];
+  app <-- fuse [label="fs.Serve returns"];
+
+  app -> fuse [label="conn.Close"];
+  fuse -> kernel  [label="close /dev/fuse fd"];
+  fuse <-- kernel;
+  app <-- fuse;
+}

vendor/bazil.org/fuse/doc/mount-osx-error-init.seq

@@ -0,0 +1,32 @@
+seqdiag {
+  app;
+  fuse [label="bazil.org/fuse"];
+  wait [label="callMount\nhelper goroutine"];
+  mount_osxfusefs;
+  kernel;
+
+  app -> fuse [label="Mount"];
+  fuse -> kernel [label="open /dev/osxfuseN"];
+  fuse -> mount_osxfusefs [label="spawn, pass fd"];
+  fuse -> wait [label="goroutine", note="blocks on cmd.Wait"];
+  app <-- fuse [label="Mount returns"];
+
+  mount_osxfusefs -> kernel [label="mount(2)"];
+
+  app -> fuse [label="fs.Serve"];
+  fuse => kernel [label="read /dev/osxfuseN fd", note="starts with InitRequest,\nalso seen before mount exits:\ntwo StatfsRequest calls"];
+  fuse -> app [label="Init"];
+  fuse <-- app [color=red];
+  fuse -> kernel [label="write /dev/osxfuseN fd", color=red];
+  fuse <-- kernel;
+
+  mount_osxfusefs <-- kernel [label="mount(2) returns", color=red];
+  wait <<-- mount_osxfusefs [diagonal, label="exit", color=red];
+  app <<-- wait [diagonal, label="mount has failed,\nclose Conn.Ready", color=red];
+
+  // actually triggers before above
+  fuse <<-- kernel [diagonal, label="/dev/osxfuseN EOF"];
+  app <-- fuse [label="fs.Serve returns"];
+  ... conn.MountError != nil, so it was was never mounted ...
+  ... call conn.Close to clean up ...
+}

vendor/bazil.org/fuse/doc/mount-osx.seq

@@ -0,0 +1,45 @@
+seqdiag {
+  // seqdiag -T svg -o doc/mount-osx.svg doc/mount-osx.seq
+  app;
+  fuse [label="bazil.org/fuse"];
+  wait [label="callMount\nhelper goroutine"];
+  mount_osxfusefs;
+  kernel;
+  mounts;
+
+  app -> fuse [label="Mount"];
+  fuse -> kernel [label="open /dev/osxfuseN"];
+  fuse -> mount_osxfusefs [label="spawn, pass fd"];
+  fuse -> wait [label="goroutine", note="blocks on cmd.Wait"];
+  app <-- fuse [label="Mount returns"];
+
+  mount_osxfusefs -> kernel [label="mount(2)"];
+
+  app -> fuse [label="fs.Serve"];
+  fuse => kernel [label="read /dev/osxfuseN fd", note="starts with InitRequest,\nalso seen before mount exits:\ntwo StatfsRequest calls"];
+  fuse => app [label="FS/Node/Handle methods"];
+  fuse => kernel [label="write /dev/osxfuseN fd"];
+  ... repeat ...
+
+  kernel ->> mounts [label="mount is visible"];
+  mount_osxfusefs <-- kernel [label="mount(2) returns"];
+  wait <<-- mount_osxfusefs [diagonal, label="exit", leftnote="on OS X, successful exit\nhere means we finally know\nthe mount has happened\n(can't trust InitRequest,\nkernel might have timed out\nwaiting for InitResponse)"];
+
+  app <<-- wait [diagonal, label="mount is ready,\nclose Conn.Ready", rightnote="InitRequest and StatfsRequest\nmay or may not be seen\nbefore Conn.Ready,\ndepending on platform"];
+
+  ... shutting down ...
+  app -> fuse [label="Unmount"];
+  fuse -> kernel [label="umount(2)"];
+  kernel <<-- mounts;
+  fuse <-- kernel;
+  app <-- fuse [label="Unmount returns"];
+
+  // actually triggers before above
+  fuse <<-- kernel [diagonal, label="/dev/osxfuseN EOF"];
+  app <-- fuse [label="fs.Serve returns"];
+
+  app -> fuse [label="conn.Close"];
+  fuse -> kernel [label="close /dev/osxfuseN"];
+  fuse <-- kernel;
+  app <-- fuse;
+}

vendor/bazil.org/fuse/doc/mount-sequence.md

@@ -0,0 +1,30 @@
+# The mount sequence
+
+FUSE mounting is a little bit tricky. There's a userspace helper tool
+that performs the handshake with the kernel, and then steps out of the
+way. This helper behaves differently on different platforms, forcing a
+more complex API on us.
+
+## Successful runs
+
+On Linux, the mount is immediate and file system accesses wait until
+the requests are served.
+
+![Diagram of Linux FUSE mount sequence](mount-linux.seq.png)
+
+On OS X, the mount becomes visible only after `InitRequest` (and maybe
+more) have been served.
+
+![Diagram of OSXFUSE mount sequence](mount-osx.seq.png)
+
+
+## Errors
+
+Let's see what happens if `InitRequest` gets an error response. On
+Linux, the mountpoint is there but all operations will fail:
+
+![Diagram of Linux error handling](mount-linux-error-init.seq.png)
+
+On OS X, the mount never happened:
+
+![Diagram of OS X error handling](mount-osx-error-init.seq.png)

vendor/bazil.org/fuse/doc/writing-docs.md

@@ -0,0 +1,16 @@
+# Writing documentation
+
+## Sequence diagrams
+
+The sequence diagrams are generated with `seqdiag`:
+http://blockdiag.com/en/seqdiag/index.html
+
+An easy way to work on them is to automatically update the generated
+files with https://github.com/cespare/reflex :
+
+    reflex -g 'doc/[^.]*.seq' -- seqdiag -T svg -o '{}.svg' '{}' &
+
+    reflex -g 'doc/[^.]*.seq' -- seqdiag -T png -o '{}.png' '{}' &
+
+The markdown files refer to PNG images because of Github limitations,
+but the SVG is generally more pleasant to view.