feat: full NFSv4.2 server and client in pure Go

Assisted-by: GLM 5.3 Flash

.gitea/workflows/race.yml

@@ -0,0 +1,39 @@
+# Race, Go. Dispatched by hand, and never a gate on a push or a tag: the release tag is
+# cut only after `just gates` has already raced the tree, so this workflow is the
+# explicit second opinion, not a step of the release.
+#
+# The race detector roughly doubles both time and memory, which the shared runner box
+# cannot afford on every push. Locally it belongs to `just gates`, which runs it once per
+# task; here it is a decision rather than a routine.
+#
+# Every step is one command, so the step that fails is the gate that failed.
+name: Race
+
+on:
+  workflow_dispatch:
+
+env:
+  # One core: parallelism buys no speed here and costs memory the box does not have.
+  GOFLAGS: -p=1
+  GOMAXPROCS: "2"
+
+jobs:
+  race:
+    runs-on: fedora
+    timeout-minutes: 20
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: actions/setup-go@v6
+        with:
+          go-version-file: go.mod
+          cache: true
+
+      - name: Install gcc
+        # The race detector needs cgo and the runner image carries no C compiler.
+        run: dnf install -y gcc
+
+      - name: Race
+        # The pattern matches `packages` in the project's justfile: the logic
+        # packages under internal/.
+        run: go test -race -count=1 -timeout 10m ./internal/...

.gitea/workflows/release.yml

@@ -0,0 +1,420 @@
+# Release, Go binaries. Runs on version tags (v1.2.3) pushed to the repository.
+#
+# The module must sit at the repository root: the toolchain records a version only for a
+# root module, measured on go1.27.1, so a build of a module in a subdirectory reports
+# (devel) even at its own <module>/vX.Y.Z tag and this workflow's smoke test can never
+# pass for it. A Go repository is one module at the root.
+# The version contract these steps implement is in the `release` skill, and its point is
+# that nothing is injected: the toolchain records the tag into the binary's build
+# information, so the build simply has to happen at the tag, which the trigger guarantees.
+#
+# The gates run in their own job, once, before the matrix, minus the race detector: race
+# never runs on a push path or a tag, and the local gate raced this tree before the tag
+# was cut. Putting the gates inside the matrix would run the whole suite once per target
+# on the box that also hosts the forge. Each job validates the tag for itself rather than
+# passing a value between jobs, so no workflow feature has to be trusted for the version
+# to reach the file name.
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+
+env:
+  # The box is shared with the forge, so parallelism is bounded on purpose. The gates job
+  # needs it most; the build jobs inherit it for their parallel compilation.
+  GOFLAGS: -p=1
+  GOMAXPROCS: "2"
+
+jobs:
+  gates:
+    runs-on: fedora
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: actions/setup-go@v6
+        with:
+          go-version-file: go.mod
+          cache: true
+
+      - name: Install Perl
+        # Perl for the steps below. The install is a no-op where the package
+        # is already present.
+        run: dnf install -y perl
+
+      - name: Validate the tag
+        env:
+          VERSION: ${{ gitea.ref_name }}
+        run: |
+          perl -e '
+            my $v = $ENV{VERSION} // q{};
+            $v =~ m{^v[0-9]+(\.[0-9]+){0,2}([-+].*)?$}
+              or die qq{ERROR: expected a semver tag like v1.2.3, got: $v\n};
+            print qq{tag $v\n};
+          '
+
+      - name: Build
+        run: go build ./...
+
+      - name: Format
+        run: |
+          perl -e '
+            open(my $g, q{-|}, q{gofmt}, q{-l}, q{.}) or die qq{gofmt: $!};
+            my @bad = <$g>;
+            close($g);
+            print @bad;
+            exit(@bad ? 1 : 0);
+          '
+
+      - name: Vet
+        run: go vet ./...
+
+      - name: Modernise
+        run: go fix -diff ./...
+
+      - name: Tests
+        # The pattern matches `packages` in the project's justfile: the logic
+        # packages under internal/.
+        run: go test -count=1 -timeout 10m -coverprofile=coverage.out ./internal/...
+
+      - name: Coverage floor
+        run: |
+          perl -e '
+            open(my $c, q{-|}, q{go}, q{tool}, q{cover}, q{-func=coverage.out}) or die qq{cover: $!};
+            my $total;
+            while (my $l = <$c>) { $total = $1 if $l =~ m{^total:\s+\S+\s+([0-9.]+)%} }
+            close($c);
+            die qq{no total line in coverage.out\n} unless defined $total;
+            printf qq{Total coverage: %s%%\n}, $total;
+            exit($total < 80 ? 1 : 0);
+          '
+
+  build:
+    runs-on: fedora
+    timeout-minutes: 25
+    needs: gates
+    strategy:
+      fail-fast: false
+      matrix:
+        # Linux on amd64, arm64, loong64 and riscv64, FreeBSD, OpenBSD and
+        # NetBSD on amd64 and arm64 (the toolchain carries no riscv64 for
+        # the BSDs), darwin on arm64 only: Apple Silicon, no Intel macs.
+        # No 32-bit, no wasm, no Windows. The runner is linux/amd64 and is the only platform
+        # the suite runs on: every other target is cross compiled here.
+        # The BSDs carry their guarantee from the local QEMU batteries run
+        # before a tag; the darwin target carries none on purpose, it
+        # ships as a cross compiled build without runtime testing.
+        include:
+          - goos: linux
+            goarch: amd64
+          - goos: linux
+            goarch: arm64
+          - goos: linux
+            goarch: loong64
+          - goos: linux
+            goarch: riscv64
+          - goos: freebsd
+            goarch: amd64
+          - goos: freebsd
+            goarch: arm64
+          - goos: openbsd
+            goarch: amd64
+          - goos: openbsd
+            goarch: arm64
+          - goos: netbsd
+            goarch: amd64
+          - goos: netbsd
+            goarch: arm64
+          - goos: darwin
+            goarch: arm64
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: actions/setup-go@v6
+        with:
+          go-version-file: go.mod
+          cache: true
+
+      - name: Install Perl
+        run: dnf install -y perl
+
+      - name: Validate the tag
+        id: version
+        env:
+          VERSION: ${{ gitea.ref_name }}
+        run: |
+          perl -e '
+            my $v = $ENV{VERSION} // q{};
+            $v =~ m{^v[0-9]+(\.[0-9]+){0,2}([-+].*)?$}
+              or die qq{ERROR: expected a semver tag like v1.2.3, got: $v\n};
+            (my $nv = $v) =~ s{^v}{};
+            open(my $o, q{>>}, $ENV{GITEA_OUTPUT}) or die qq{GITEA_OUTPUT: $!};
+            print $o qq{version_no_v=$nv\n};
+            close($o);
+            print qq{version $nv\n};
+          '
+
+      - name: Build the server
+        env:
+          VERSION_NO_V: ${{ steps.version.outputs.version_no_v }}
+          GOOS: ${{ matrix.goos }}
+          GOARCH: ${{ matrix.goarch }}
+          CGO_ENABLED: "0"
+        run: |
+          # Nothing is injected. The toolchain records the tag into the binary's build
+          # information, so the version is right because this build happens at the tag, and
+          # there is no path for anyone to get wrong. -s -w only strips symbols.
+          go build -ldflags "-s -w" -o "bin/nfsd-${VERSION_NO_V}-${GOOS}-${GOARCH}" ./cmd/nfsd
+
+      - name: Build the client
+        env:
+          VERSION_NO_V: ${{ steps.version.outputs.version_no_v }}
+          GOOS: ${{ matrix.goos }}
+          GOARCH: ${{ matrix.goarch }}
+          CGO_ENABLED: "0"
+        run: go build -ldflags "-s -w" -o "bin/nfs-${VERSION_NO_V}-${GOOS}-${GOARCH}" ./cmd/nfs
+
+      # Artifacts stay on v3: v4 and later detect Gitea as GHES and abort.
+      - name: Upload the server artifact
+        uses: actions/upload-artifact@v3
+        with:
+          name: nfsd-${{ matrix.goos }}-${{ matrix.goarch }}
+          path: bin/nfsd-${{ steps.version.outputs.version_no_v }}-${{ matrix.goos }}-${{ matrix.goarch }}
+          if-no-files-found: error
+
+      - name: Upload the client artifact
+        uses: actions/upload-artifact@v3
+        with:
+          name: nfs-${{ matrix.goos }}-${{ matrix.goarch }}
+          path: bin/nfs-${{ steps.version.outputs.version_no_v }}-${{ matrix.goos }}-${{ matrix.goarch }}
+          if-no-files-found: error
+
+      - name: Smoke test the server
+        # Only a binary matching the runner can be run here. The check is not that --version
+        # exits cleanly but that it reports the tag and nothing more: a build outside version
+        # control reports (devel), and a build whose tree was dirty reports +dirty, and both
+        # would otherwise be published.
+        if: matrix.goos == 'linux' && matrix.goarch == 'amd64'
+        env:
+          TAG: ${{ gitea.ref_name }}
+          BIN: bin/nfsd-${{ steps.version.outputs.version_no_v }}-${{ matrix.goos }}-${{ matrix.goarch }}
+        run: |
+          perl -e '
+            my $want = $ENV{TAG} // die qq{ERROR: no tag\n};
+            open(my $bin, q{-|}, $ENV{BIN}, q{--version}) or die qq{$ENV{BIN}: $!};
+            my $got = <$bin>;
+            close($bin);
+            $got = defined $got ? $got : q{};
+            chomp $got;
+            index($got, $want) >= 0
+              or die qq{ERROR: the binary printed "$got", which does not contain $want. Version control was disabled, so there is no recorded version.\n};
+            index($got, q{+dirty}) < 0
+              or die qq{ERROR: the binary printed "$got". The tree was dirty at build time, which means the checkout was not the tag, or the build artefacts are not ignored.\n};
+            print qq{$ENV{BIN} reports $got\n};
+          '
+
+      - name: Smoke test the client
+        # The client reports its version through the version subcommand; the check
+        # is the same as the server's: the tag present, +dirty absent.
+        if: matrix.goos == 'linux' && matrix.goarch == 'amd64'
+        env:
+          TAG: ${{ gitea.ref_name }}
+          BIN: bin/nfs-${{ steps.version.outputs.version_no_v }}-${{ matrix.goos }}-${{ matrix.goarch }}
+        run: |
+          perl -e '
+            my $want = $ENV{TAG} // die qq{ERROR: no tag\n};
+            open(my $bin, q{-|}, $ENV{BIN}, q{version}) or die qq{$ENV{BIN}: $!};
+            my $got = <$bin>;
+            close($bin);
+            $got = defined $got ? $got : q{};
+            chomp $got;
+            index($got, $want) >= 0
+              or die qq{ERROR: the binary printed "$got", which does not contain $want. Version control was disabled, so there is no recorded version.\n};
+            index($got, q{+dirty}) < 0
+              or die qq{ERROR: the binary printed "$got". The tree was dirty at build time, which means the checkout was not the tag, or the build artefacts are not ignored.\n};
+            print qq{$ENV{BIN} reports $got\n};
+          '
+
+  release:
+    runs-on: fedora
+    timeout-minutes: 15
+    needs: build
+    permissions:
+      # contents: read is required for the checkout: a job that declares any
+      # permissions gets a token scoped to exactly those, and releases: write
+      # alone leaves the fetch with no read access, which Gitea answers with
+      # a 404 "Repository not found". Verified on the instance 2026-09-16.
+      contents: read
+      releases: write
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Download all artifacts
+        uses: actions/download-artifact@v3
+        with:
+          path: dist
+
+      - name: Install Perl
+        run: dnf install -y perl
+
+      - name: Extract the CHANGELOG section
+        env:
+          VERSION: ${{ gitea.ref_name }}
+        run: |
+          # Each step derives what it needs from the tag, so no value has to travel between
+          # jobs.
+          perl -e '
+            my $v = $ENV{VERSION} // q{};
+            $v =~ s{^v}{};
+            open(my $vout, q{>}, q{version-no-v.txt}) or die qq{version-no-v.txt: $!};
+            print $vout $v;
+            close($vout);
+            open(my $in, q{<}, q{CHANGELOG.md}) or die qq{CHANGELOG.md: $!};
+            my @lines = <$in>;
+            close($in);
+            my ($start, $end) = (-1, scalar @lines);
+            for my $i (0 .. $#lines) {
+              if ($start < 0) { $start = $i if $lines[$i] =~ m{^##\s+\[\Q$v\E\]} }
+              elsif ($lines[$i] =~ m{^##\s+\[}) { $end = $i; last }
+            }
+            $start >= 0 or die qq{ERROR: no CHANGELOG section for $v, expected a heading like: ## [$v] - YYYY-MM-DD\n};
+            my @body = grep { m{\S} } @lines[$start + 1 .. $end - 1];
+            @body or die qq{ERROR: the CHANGELOG section for $v is empty\n};
+            open(my $out, q{>}, q{release-body.md}) or die qq{release-body.md: $!};
+            print $out @body;
+            close($out);
+            printf qq{notes for %s: %d lines\n}, $v, scalar @body;
+          '
+
+      - name: Build the release request
+        run: |
+          perl -e '
+            open(my $vin, q{<}, q{version-no-v.txt}) or die qq{version-no-v.txt: $!};
+            my $v = <$vin>;
+            close($vin);
+            chomp $v;
+            open(my $in, q{<:raw}, q{release-body.md}) or die qq{release-body.md: $!};
+            my $body = do { local $/; <$in> };
+            close($in);
+            # Byte-oriented escaping: JSON is UTF-8, so non-ASCII passes through and only the
+            # characters JSON forbids are rewritten.
+            $body =~ s/([\\"])/\\$1/g;
+            $body =~ s/\t/\\t/g;
+            $body =~ s/\r//g;
+            $body =~ s/\n/\\n/g;
+            $body =~ s/([\x00-\x08\x0b\x0c\x0e-\x1f])/sprintf(q{\u%04x}, ord($1))/ge;
+            my $json = sprintf(qq{{"tag_name":"v%s","name":"v%s","body":"%s","draft":false,"prerelease":false}}, $v, $v, $body);
+            open(my $out, q{>}, q{release.json}) or die qq{release.json: $!};
+            print $out $json;
+            close($out);
+            print qq{release.json written for v$v\n};
+          '
+
+      - name: Create the release
+        env:
+          GITEA_TOKEN: ${{ secrets.GITEA_TOKEN }}
+          GITEA_SERVER_URL: ${{ gitea.server_url }}
+          GITEA_REPOSITORY: ${{ gitea.repository }}
+        run: |
+          perl -e '
+            my @cmd = (q{curl}, q{-sS}, q{-o}, q{response.json}, q{-w}, q{%{http_code}},
+              q{-H}, qq{Authorization: token $ENV{GITEA_TOKEN}},
+              q{-H}, q{Content-Type: application/json},
+              q{-X}, q{POST},
+              qq{$ENV{GITEA_SERVER_URL}/api/v1/repos/$ENV{GITEA_REPOSITORY}/releases},
+              q{--data-binary}, q{@release.json});
+            open(my $curl, q{-|}, @cmd) or die qq{curl: $!};
+            my $code = <$curl>;
+            my $ok = close($curl);
+            my $exit = $? >> 8;
+            $code = defined $code ? $code : q{};
+            $ok or die qq{ERROR: curl failed (exit $exit) calling $ENV{GITEA_SERVER_URL}\n};
+            open(my $r, q{<:raw}, q{response.json}) or die qq{response.json: $!};
+            my $body = do { local $/; <$r> };
+            close($r);
+            $code eq q{201} or die qq{ERROR: the release was not created, HTTP $code: $body\n};
+            $body =~ m{"id"\s*:\s*([0-9]+)} or die qq{ERROR: no release id in the response: $body\n};
+            open(my $o, q{>}, q{release-id.txt}) or die qq{release-id.txt: $!};
+            print $o $1;
+            close($o);
+            print qq{release id $1\n};
+          '
+
+      - name: Upload assets
+        env:
+          GITEA_TOKEN: ${{ secrets.GITEA_TOKEN }}
+          GITEA_SERVER_URL: ${{ gitea.server_url }}
+          GITEA_REPOSITORY: ${{ gitea.repository }}
+        run: |
+          perl -e '
+            open(my $f, q{<}, q{release-id.txt}) or die qq{release-id.txt: $!};
+            my $id = <$f>;
+            close($f);
+            chomp $id;
+            my @files = grep { -f $_ } glob(q{dist/*/*});
+            @files or die qq{ERROR: no assets under dist/\n};
+            my $bad = 0;
+            for my $path (@files) {
+              (my $name = $path) =~ s{.*/}{};
+              my @cmd = (q{curl}, q{-sS}, q{-o}, q{/dev/null}, q{-w}, q{%{http_code}},
+                q{-H}, qq{Authorization: token $ENV{GITEA_TOKEN}},
+                q{-H}, q{Content-Type: application/octet-stream},
+                # The @ must not sit inside a qq{} string: there it starts an
+                # array interpolation and the upload body collapses to empty,
+                # which Gitea stores as a 201-created zero-byte attachment.
+                q{-X}, q{POST}, q{--data-binary}, q{@} . $path,
+                qq{$ENV{GITEA_SERVER_URL}/api/v1/repos/$ENV{GITEA_REPOSITORY}/releases/$id/assets?name=$name});
+              open(my $curl, q{-|}, @cmd) or die qq{curl: $!};
+              my $code = <$curl>;
+              my $ok = close($curl);
+              my $exit = $? >> 8;
+              $code = defined $code ? $code : q{};
+              unless ($ok) {
+                printf qq{%s: curl failed (exit %d)\n}, $name, $exit;
+                $bad = 1;
+                next;
+              }
+              printf qq{%s: HTTP %s\n}, $name, $code;
+              $bad = 1 if $code ne q{201};
+            }
+            exit($bad ? 1 : 0);
+          '
+
+      - name: Verify the assets
+        # HTTP 201 alone lies: the upload can create the attachment and
+        # still store it empty, and a green run over an empty asset is a
+        # release nobody can install. Every asset is read back through
+        # the release download route and its served length must equal
+        # the sent length.
+        env:
+          GITEA_SERVER_URL: ${{ gitea.server_url }}
+          GITEA_REPOSITORY: ${{ gitea.repository }}
+          TAG: ${{ gitea.ref_name }}
+        run: |
+          perl -e '
+            my @files = grep { -f $_ } glob(q{dist/*/*});
+            @files or die qq{ERROR: no assets under dist/\n};
+            my $bad = 0;
+            for my $path (@files) {
+              (my $name = $path) =~ s{.*/}{};
+              my $body = qq{verify-$name};
+              my @cmd = (q{curl}, q{-sS}, q{-o}, $body, q{-w}, q{%{http_code}},
+                qq{$ENV{GITEA_SERVER_URL}/$ENV{GITEA_REPOSITORY}/releases/download/$ENV{TAG}/$name});
+              open(my $curl, q{-|}, @cmd) or die qq{curl: $!};
+              my $code = <$curl>;
+              my $ok = close($curl);
+              $code = defined $code ? $code : q{};
+              $ok or do { printf qq{%s: the read back failed\n}, $name; $bad = 1; next };
+              $code eq q{200} or do { printf qq{%s: HTTP %s on the read back\n}, $name, $code; $bad = 1; next };
+              my $sent = -s $path;
+              my $got = -s $body;
+              if (!defined $sent || !defined $got || $sent != $got) {
+                printf qq{%s: served %s bytes, sent %s\n}, $name, $got // q{?}, $sent // q{?};
+                $bad = 1;
+                next;
+              }
+              printf qq{%s: %s bytes verified\n}, $name, $got;
+            }
+            exit($bad ? 1 : 0);
+          '

.gitea/workflows/test.yml

@@ -0,0 +1,97 @@
+# Test, Go. Push and pull request to development. Never on main.
+# The standard repository points this trigger at development; the main-only
+# exception, which deploys on every push and has no release, points it at main.
+#
+# The gates are the ones the justfile's `gates` recipe runs, minus race: the shared
+# runner box cannot afford the race detector on every push, so it lives in race.yml.
+# The box is one core and 2 GB beside Gitea, so parallelism is bounded on purpose and
+# everything runs in one job. Extra jobs would duplicate the checkout, the Go setup and
+# the dependency download three times without buying any parallelism.
+#
+# Every step is one command, so the step that fails is the gate that failed, and no shell
+# option has to be trusted for the run to stop. The scripted steps are Perl, not shell and
+# not Python: Perl behaves the same on both runner images, there is no bashism to trip over
+# on ash, and it is one language instead of two. The Perl uses builtins only, because
+# Fedora packages the Perl modules separately and nothing beyond `perl` itself may be
+# assumed present.
+name: Test
+
+on:
+  push:
+    branches: [development]
+  pull_request:
+    branches: [development]
+
+env:
+  # One core: parallelism buys no speed here and costs memory the box does not have.
+  GOFLAGS: -p=1
+  GOMAXPROCS: "2"
+
+# A superseded run of the same ref is cancelled instead of queueing behind one that
+# no longer matters. Verified on Gitea 1.27.1 on 2026-09-17: a queued run whose ref
+# moved on is cancelled before it ever reaches the runner, while a run already
+# dispatched there runs to completion.
+concurrency:
+  group: ${{ gitea.workflow }}-${{ gitea.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    runs-on: fedora
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: actions/setup-go@v6
+        with:
+          # The module is the source of truth for the version, so it cannot drift.
+          go-version-file: go.mod
+          cache: true
+
+      - name: Install Perl
+        # The runner images are minimal and Perl is not guaranteed. The install is a
+        # no-op where it is already present; drop this step once verified on the box.
+        run: dnf install -y perl
+
+      # The steps follow the `gates` order of the justfile contract: build, format,
+      # vet, test. The vet gate is go vet and go fix -diff, two steps here.
+      - name: Build
+        run: go build ./...
+
+      - name: Format
+        run: |
+          perl -e '
+            open(my $g, q{-|}, q{gofmt}, q{-l}, q{.}) or die qq{gofmt: $!};
+            my @bad = <$g>;
+            close($g);
+            print @bad;
+            exit(@bad ? 1 : 0);
+          '
+
+      - name: Vet
+        run: go vet ./...
+
+      - name: Modernise
+        # Exits non-zero when it has something to rewrite, so it needs no output capture.
+        run: go fix -diff ./...
+
+      - name: Tests
+        # The suite must be fast: a push pipeline that cannot finish in a few minutes moves
+        # its heavy part behind a dispatch. The inner timeout matches the job's, so a
+        # hanging test reports its own goroutine dump rather than a silent job kill.
+        # The pattern matches `packages` in the project's justfile: the logic packages
+        # under internal/. The thin cmd binaries count as zero coverage and would drag
+        # the floor below 80 percent on their own.
+        run: go test -count=1 -timeout 10m -coverprofile=coverage.out ./internal/...
+
+      - name: Coverage floor
+        run: |
+          perl -e '
+            open(my $c, q{-|}, q{go}, q{tool}, q{cover}, q{-func=coverage.out}) or die qq{cover: $!};
+            my $total;
+            while (my $l = <$c>) { $total = $1 if $l =~ m{^total:\s+\S+\s+([0-9.]+)%} }
+            close($c);
+            die qq{no total line in coverage.out\n} unless defined $total;
+            printf qq{Total coverage: %s%%\n}, $total;
+            exit($total < 80 ? 1 : 0);
+          '