xf: single-file HTTP file transfer serverHEADmaster

Serve a directory tree over HTTP through one embedded page: a listing
with download links and a multi-file upload form.

Filesystem access is confined to the served root with os.Root, and
only regular files are served. Uploads are bounded by size and part
count, and every file is staged in the target directory before any is
renamed into place, so a refused or interrupted request leaves the
directory untouched.

Standard library only, no third-party dependencies.

1 files changed, 62 insertions, 0 deletions

diff --git a/README b/README
new file mode 100644
index 0000000..cdb36a1
--- /dev/null
+++ b/README
@@ -0,0 +1,62 @@
+xf
+==
+xf (xfer) is a single-file HTTP file transfer server. Every directory under
+the served root renders as one web page that lists its entries with download
+links and provides a form to upload one or more files into that directory.
+
+
+Build
+-----
+Build a binary with the Go toolchain:
+    go build -o xf .
+Everything, including the web page, is embedded in main.go. There are no
+third-party dependencies.
+
+
+Run
+---
+Serve the current directory on loopback port 8080:
+    ./xf
+Serve a different directory or bind a different address:
+    ./xf -dir /srv/files -addr 192.0.2.10:9000
+Open the printed address in a browser. Uploads are streamed to a temporary
+file in the target directory. All files in a request are staged before any are
+renamed into place. Existing regular files are overwritten atomically and keep
+their mode; new files are created mode 0600.
+
+
+Options
+-------
+    -addr         listen address (default "127.0.0.1:8080")
+    -dir          directory to serve (default ".")
+    -max-upload   maximum bytes in one upload request (default 1073741824)
+
+
+Debug
+-----
+The access log goes to standard output, one line per request:
+    2026/07/02 10:14:38 get "/hello.txt" -> 200 (6 bytes) from 127.0.0.1
+    2026/07/02 10:14:39 upload "/sub/up.txt" (9 bytes) from 127.0.0.1
+Startup and error diagnostics go to standard error. To exercise the server
+without a browser:
+    curl -F files=@somefile http://127.0.0.1:8080/
+    curl -O http://127.0.0.1:8080/somefile
+
+
+Security
+--------
+xf has no authentication. It serves every file under the directory, including
+hidden files, to anyone who can reach the address, and it accepts uploads from
+anyone. The default listener is loopback; binding another address deliberately
+exposes the server to that network.
+
+Filesystem access is confined to the served root. Relative symbolic links may
+point elsewhere inside the root, but absolute links and links that escape it
+are rejected. Upload requests are limited to 1 GiB by default and at most 1000
+multipart parts. The server does not limit upload duration or concurrent
+requests. Run it only on systems and networks you trust.
+
+An interrupted process can leave a mode-0600 .xf-upload-* staging file.
+These reserved names are neither listed nor served and can be removed when no
+xf process is using the directory. A rare rename failure while committing a
+multi-file request can leave an initial subset committed.