greatly expand testsuite coverage and add coverage analysis with gcov

.github/workflows/coverage.yml

@@ -0,0 +1,71 @@
+name: Coverage (Ubuntu)
+
+on:
+  push:
+    branches: [ master ]
+    paths-ignore:
+      - '.github/workflows/*.yml'
+      - '!.github/workflows/coverage.yml'
+  pull_request:
+    branches: [ master ]
+    paths-ignore:
+      - '.github/workflows/*.yml'
+      - '!.github/workflows/coverage.yml'
+  schedule:
+    - cron: '42 9 * * *'
+  workflow_dispatch:
+
+jobs:
+  coverage:
+    runs-on: ubuntu-latest
+    name: gcov coverage
+    steps:
+    - uses: actions/checkout@v4
+      with:
+        fetch-depth: 0
+    - name: prep
+      run: |
+        sudo apt-get update
+        sudo apt-get install -y acl libacl1-dev attr libattr1-dev liblz4-dev libzstd-dev libxxhash-dev python3-cmarkgfm openssl gcovr
+        echo "/usr/local/bin" >>$GITHUB_PATH
+    - name: configure
+      run: ./configure --enable-coverage --with-rrsync
+    - name: make
+      run: make
+    - name: info
+      run: rsync --version
+    # Two coverage runs: the default pipe transport, then a second pass over a
+    # real loopback rsyncd (--use-tcp) which also exercises the require_tcp-only
+    # tests. gcovr's --print-summary line/branch/decision totals go to the step
+    # log (and the job summary below), so the numbers are visible in CI.
+    # `make coverage` exits with the suite's status, so a regression fails CI.
+    - name: coverage (pipe transport)
+      run: |
+        set -o pipefail
+        sudo make coverage 2>&1 | tee cov-pipe.log
+    - name: coverage (TCP transport)
+      run: |
+        set -o pipefail
+        sudo make coverage-tcp 2>&1 | tee cov-tcp.log
+    - name: coverage summary
+      if: always()
+      run: |
+        {
+          echo "## gcov coverage"
+          echo "### Pipe transport (\`make coverage\`)"
+          echo '```'
+          grep -E '^(lines|functions|branches|decisions):' cov-pipe.log || echo '(no summary -- see step log)'
+          echo '```'
+          echo "### TCP transport (\`make coverage-tcp\`)"
+          echo '```'
+          grep -E '^(lines|functions|branches|decisions):' cov-tcp.log || echo '(no summary -- see step log)'
+          echo '```'
+        } >> "$GITHUB_STEP_SUMMARY"
+    - name: upload HTML reports
+      if: always()
+      uses: actions/upload-artifact@v4
+      with:
+        name: coverage-html
+        path: |
+          coverage
+          coverage-tcp

.github/workflows/cygwin-build.yml

@@ -44,7 +44,7 @@ jobs:
       # package installed above), verified on a real Cygwin host. The real
       # chown/devices tests still skip (need root/mknod), as do the
       # RESOLVE_BENEATH symlink-race tests.
-      run: bash -c 'RSYNC_EXPECT_SKIPPED=acls-default,acls,bare-do-open-symlink-race,chdir-symlink-race,chown,daemon-chroot-acl,devices,dir-sgid,open-noatime,protected-regular,proxy-response-line-too-long,sender-flist-symlink-leak,simd-checksum,symlink-dirlink-basis make check'
+      run: bash -c 'RSYNC_EXPECT_SKIPPED=acls-default,acls-depth,acls,bare-do-open-symlink-race,chdir-symlink-race,chown,daemon-chroot-acl,devices,dir-sgid,open-noatime,protected-regular,proxy-response-line-too-long,sender-flist-symlink-leak,simd-checksum,symlink-dirlink-basis make check'
     - name: check (TCP daemon transport)
       # Second run with daemon tests over a real loopback rsyncd; the default
       # 'make check' above uses the secure stdio-pipe transport.

.github/workflows/macos-build.yml

@@ -44,7 +44,7 @@ jobs:
       # chown-fake / devices-fake / xattrs / xattrs-hlink now RUN on macOS
       # (rsyncfns.py drives xattrs via the `xattr` command), verified on a
       # real macOS host, so they're no longer in the skip set.
-      run: sudo RSYNC_EXPECT_SKIPPED=acls-default,chmod-temp-dir,daemon-chroot-acl,dir-sgid,open-noatime,protected-regular,proxy-response-line-too-long,simd-checksum make check
+      run: sudo RSYNC_EXPECT_SKIPPED=acls-default,acls-depth,chmod-temp-dir,daemon-chroot-acl,dir-sgid,open-noatime,protected-regular,proxy-response-line-too-long,simd-checksum,sparse make check
     - name: check (TCP daemon transport)
       # Second run with daemon tests over a real loopback rsyncd; the default
       # 'make check' above uses the secure stdio-pipe transport.

Makefile.in

@@ -280,6 +280,8 @@ clean: cleantests
 	rm -f *~ $(OBJS) $(CHECK_PROGS) $(CHECK_OBJS) $(CHECK_SYMLINKS) @MAKE_RRSYNC@ \
 		git-version.h rounding rounding.h *.old rsync*.1 rsync*.5 @MAKE_RRSYNC_1@ \
 		*.html daemon-parm.h help-*.h default-*.h proto.h proto.h-tstamp
+	rm -f *.gcno *.gcda lib/*.gcno lib/*.gcda zlib/*.gcno zlib/*.gcda popt/*.gcno popt/*.gcda
+	rm -rf coverage coverage-tcp
 
 .PHONY: cleantests
 cleantests:
@@ -324,6 +326,22 @@ test: check
 # `make check CHECK_J=1` (serial) or any other value.
 CHECK_J = 8
 
+# Parallelism for `make coverage`. Defaults to the same as CHECK_J: the
+# coverage build sets -fprofile-update=atomic (atomic in-memory counters) and
+# gcc's libgcov serializes the per-source .gcda read-modify-write merge with a
+# file lock, so concurrent rsync processes (incl. the forked sender/generator/
+# receiver) accumulate exactly -- verified by a count-linearity check (a hot
+# line accumulates identically at -j1 and -P16). Override with
+# `make coverage COVERAGE_J=1` if your libgcov does not lock .gcda merges.
+COVERAGE_J = $(CHECK_J)
+
+# Output directory and extra runtests.py flags for `make coverage`. The
+# `coverage-tcp` target reuses the coverage recipe with --use-tcp (real
+# loopback rsyncd, which exercises the TCP accept/auth path and the
+# require_tcp-only tests) and a separate output directory.
+COVERAGE_DIR = coverage
+COVERAGE_RUNFLAGS =
+
 .PHONY: check
 check: all $(CHECK_PROGS) $(CHECK_SYMLINKS)
 	$(srcdir)/runtests.py --rsync-bin=`pwd`/rsync$(EXEEXT) -j $(CHECK_J)
@@ -336,6 +354,35 @@ check29: all $(CHECK_PROGS) $(CHECK_SYMLINKS)
 check30: all $(CHECK_PROGS) $(CHECK_SYMLINKS)
 	$(srcdir)/runtests.py --rsync-bin=`pwd`/rsync$(EXEEXT) -j $(CHECK_J) --protocol=30
 
+# Whole-suite gcov coverage report (HTML, with branch + decision coverage).
+# Requires a build configured with --enable-coverage and the `gcovr` tool
+# (pip install gcovr). Runs the suite in parallel (COVERAGE_J, default CHECK_J):
+# this is safe because the coverage build uses -fprofile-update=atomic and
+# libgcov locks the per-source .gcda during its merge, so concurrent rsync
+# processes accumulate exactly (see COVERAGE_J above). Use COVERAGE_J=1 if your
+# toolchain's libgcov does not lock .gcda merges.
+.PHONY: coverage
+coverage: all $(CHECK_PROGS) $(CHECK_SYMLINKS)
+	@case '$(CFLAGS)' in *--coverage*) ;; \
+	  *) echo "*** not a coverage build; reconfigure with --enable-coverage"; exit 1 ;; esac
+	@command -v gcovr >/dev/null 2>&1 || { echo "*** gcovr not found (pip install gcovr)"; exit 1; }
+	find . -name '*.gcda' -delete
+	@rc=0; $(srcdir)/runtests.py --rsync-bin=`pwd`/rsync$(EXEEXT) -j $(COVERAGE_J) $(COVERAGE_RUNFLAGS) || rc=$$?; \
+	  rm -rf $(COVERAGE_DIR) && mkdir -p $(COVERAGE_DIR); \
+	  gcovr --root $(srcdir) --decisions --print-summary \
+	      --html-details -o $(COVERAGE_DIR)/index.html . || exit $$?; \
+	  echo "Coverage report written to $(COVERAGE_DIR)/index.html"; \
+	  if test $$rc != 0; then \
+	    echo "*** test suite FAILED (status $$rc) -- coverage report still written above"; \
+	  fi; \
+	  exit $$rc
+
+# Same as `make coverage` but with the daemon tests run over a real loopback
+# rsyncd (--use-tcp), into a separate report directory.
+.PHONY: coverage-tcp
+coverage-tcp:
+	$(MAKE) coverage COVERAGE_RUNFLAGS=--use-tcp COVERAGE_DIR=coverage-tcp
+
 wildtest.o: wildtest.c t_stub.o lib/wildmatch.c rsync.h config.h
 wildtest$(EXEEXT): wildtest.o lib/compat.o lib/snprintf.o @BUILD_POPT@
 	$(CC) $(CFLAGS) $(LDFLAGS) -o $@ wildtest.o lib/compat.o lib/snprintf.o @BUILD_POPT@ $(LIBS)

cleanup.c

@@ -269,8 +269,16 @@ NORETURN void _exit_cleanup(int code, const char *file, int line)
 		break;
 	}
 
-	if (called_from_signal_handler)
+	if (called_from_signal_handler) {
+#ifdef GCOV_COVERAGE
+		/* _exit() bypasses the gcov atexit flush; rsync's generator (and
+		 * other processes) normally finish via the signal handler, so
+		 * without this they would write no .gcda. Harmless otherwise. */
+		extern void __gcov_dump(void);
+		__gcov_dump();
+#endif
 		_exit(exit_code);
+	}
 	exit(exit_code);
 }
 

configure.ac

@@ -82,6 +82,32 @@ if test x"$enable_profile" = x"yes"; then
 	CFLAGS="$CFLAGS -pg"
 fi
 
+dnl Coverage build (gcov) for `make coverage`. NOTE: --enable-profile above is
+dnl gprof (-pg) and is NOT coverage. -O0 keeps branch coverage meaningful;
+dnl -fprofile-update=atomic keeps the shared .gcda counters correct while the
+dnl suite runs many rsync processes in parallel.
+AC_ARG_ENABLE(coverage,
+	AS_HELP_STRING([--enable-coverage],[build with gcov instrumentation for `make coverage`]))
+if test x"$enable_coverage" = x"yes"; then
+	CFLAGS="$CFLAGS --coverage -fprofile-update=atomic -O0"
+	CXXFLAGS="$CXXFLAGS --coverage -fprofile-update=atomic -O0"
+	LDFLAGS="$LDFLAGS --coverage"
+	AC_DEFINE([GCOV_COVERAGE], 1,
+		[Flush gcov counters at exit_cleanup: rsync's children exit via _exit(), which bypasses the gcov atexit handler, so without this no .gcda is written for the receiver/generator/daemon-worker processes.])
+fi
+
+dnl openat2(RESOLVE_BENEATH) is used on Linux 5.6+ for the secure resolver.
+dnl --disable-openat2 forces the portable per-component O_NOFOLLOW fallback to
+dnl run as the primary resolver on ordinary Linux, so that tier is exercised
+dnl (and coverage-counted) without needing a pre-5.6 kernel. Behaviour-neutral
+dnl by default (the knob only REMOVES a tier when explicitly disabled).
+AC_ARG_ENABLE(openat2,
+	AS_HELP_STRING([--disable-openat2],[do not use Linux openat2(RESOLVE_BENEATH); force the portable resolver (for exercising the fallback tier)]))
+if test x"$enable_openat2" != x"no"; then
+	AC_DEFINE([HAVE_OPENAT2], 1,
+		[Define to use Linux openat2(RESOLVE_BENEATH) in secure_relative_open where available.])
+fi
+
 AC_MSG_CHECKING([if md2man can create manpages])
 if test x"$ac_cv_path_PYTHON3" = x; then
     AC_MSG_RESULT(no - python3 not found)

main.c

@@ -1618,6 +1618,11 @@ static void sigusr2_handler(UNUSED(int val))
 	if (!am_server)
 		output_summary();
 	close_all();
+#ifdef GCOV_COVERAGE
+	/* The receiver child is killed here via SIGUSR2 and exits with _exit(),
+	 * bypassing the gcov atexit flush; without this it writes no .gcda. */
+	{ extern void __gcov_dump(void); __gcov_dump(); }
+#endif
 	if (got_xfer_error)
 		_exit(RERR_PARTIAL);
 	_exit(0);

receiver.c

@@ -83,6 +83,44 @@ static int updating_basis_or_equiv;
 #define MAX_UNIQUE_NUMBER 999999
 #define MAX_UNIQUE_LOOP 100
 
+/* Open a basis/output path that may legitimately be an operator-trusted
+ * ABSOLUTE path -- e.g. an absolute --partial-dir ("a directory reserved for
+ * partial-dir work") or --backup-dir. secure_relative_open() deliberately
+ * rejects an absolute relpath, so feeding it the whole absolute partialptr
+ * (with a NULL basedir) returns EINVAL: the basis fd is then -1, no basis is
+ * mapped, and receive_data() omits every matched block from the whole-file
+ * verification checksum -> a spurious "failed verification" that strands the
+ * (correct) data in the partial-dir forever.
+ *
+ * The operator's directory is trusted; only the leaf basename is peer-supplied.
+ * So when basedir is NULL and relpath is absolute, split it into its directory
+ * (trusted) and leaf and confine just the leaf -- exactly how secure_relative_
+ * open already trusts an absolute basedir while O_NOFOLLOW-confining the leaf.
+ * Anything else is a straight pass-through that preserves the strict contract. */
+static int secure_basis_open(const char *basedir, const char *relpath, int flags, mode_t mode)
+{
+	if (!basedir && relpath && *relpath == '/') {
+		const char *slash = strrchr(relpath, '/');
+		const char *leaf = slash + 1;
+		char dirbuf[MAXPATHLEN];
+		const char *dir;
+		if (slash == relpath)
+			dir = "/";
+		else {
+			size_t dlen = slash - relpath;
+			if (dlen >= sizeof dirbuf) {
+				errno = ENAMETOOLONG;
+				return -1;
+			}
+			memcpy(dirbuf, relpath, dlen);
+			dirbuf[dlen] = '\0';
+			dir = dirbuf;
+		}
+		return secure_relative_open(dir, leaf, flags, mode);
+	}
+	return secure_relative_open(basedir, relpath, flags, mode);
+}
+
 /* get_tmpname() - create a tmp filename for a given filename
  *
  * If a tmpdir is defined, use that as the directory to put it in.  Otherwise,
@@ -364,6 +402,18 @@ static int receive_data(int f_in, char *fname_r, int fd_r, OFF_T size_r,
 
 		stats.matched_data += len;
 
+		/* A block match can only be honored if we actually mapped the
+		 * basis. If we didn't (basis open failed), the sender should
+		 * never have been told a basis existed -- treat it as a protocol
+		 * inconsistency rather than silently omitting these bytes from
+		 * the verification checksum (which yields a spurious failure) or
+		 * leaving a hole in the output. */
+		if (!mapbuf) {
+			rprintf(FERROR, "got a block match with no basis file for %s [%s]\n",
+				full_fname(fname), who_am_i());
+			exit_cleanup(RERR_PROTOCOL);
+		}
+
 		if (DEBUG_GTE(DELTASUM, 3)) {
 			rprintf(FINFO,
 				"chunk[%d] of size %ld at %s offset=%s%s\n",
@@ -793,8 +843,9 @@ int recv_files(int f_in, int f_out, char *local_name)
 				fnamecmp = fname;
 		}
 
-		/* open the file */
-		fd1 = secure_relative_open(basedir, fnamecmp, O_RDONLY, 0);
+		/* open the file (secure_basis_open tolerates an operator-trusted
+		 * absolute fnamecmp, e.g. an absolute --partial-dir basis) */
+		fd1 = secure_basis_open(basedir, fnamecmp, O_RDONLY, 0);
 
 		if (fd1 == -1 && protocol_version < 29) {
 			if (fnamecmp != fname) {
@@ -884,7 +935,7 @@ int recv_files(int f_in, int f_out, char *local_name)
 			 * attacker could switch a directory to a symlink between
 			 * path validation and file open. */
 			if (use_secure_symlinks)
-				fd2 = secure_relative_open(NULL, fnametmp, O_WRONLY|O_CREAT, 0600);
+				fd2 = secure_basis_open(NULL, fnametmp, O_WRONLY|O_CREAT, 0600);
 			else
 				fd2 = do_open(fnametmp, O_WRONLY|O_CREAT, 0600);
 #ifdef linux

syscall.c

@@ -33,7 +33,7 @@
 #include <sys/syscall.h>
 #endif
 
-#ifdef __linux__
+#if defined(__linux__) && defined(HAVE_OPENAT2)
 #include <sys/syscall.h>
 #include <linux/openat2.h>
 #endif
@@ -1691,7 +1691,7 @@ static int path_has_dotdot_component(const char *path)
 	return 0;
 }
 
-#ifdef __linux__
+#if defined(__linux__) && defined(HAVE_OPENAT2)
 static int secure_relative_open_linux(const char *basedir, const char *relpath, int flags, mode_t mode)
 {
 	struct open_how how;
@@ -1791,11 +1791,13 @@ int secure_relative_open(const char *basedir, const char *relpath, int flags, mo
 		return -1;
 	}
 
-#ifdef __linux__
+#if defined(__linux__) && defined(HAVE_OPENAT2)
 	{
 		int fd = secure_relative_open_linux(basedir, relpath, flags, mode);
 		/* ENOSYS = kernel < 5.6 doesn't have the syscall even though
-		 * glibc/kernel-headers do; fall through to the portable path. */
+		 * glibc/kernel-headers do; fall through to the portable path.
+		 * (Built unconditionally unless --disable-openat2, which forces
+		 * the portable resolver below so that tier is exercised.) */
 		if (fd != -1 || errno != ENOSYS)
 			return fd;
 	}