feat(recovery): receive bounded WAL with explicit end request

[seonghobae]

Bounded PostgreSQL WAL receive — ACTIVE DRAFT / EXPLICIT #233 CHILD

This branch adds a finite pg_receivewal execution seam and remains an explicit child of #233. Protected main@b84f0c94154043a3473939c01bb6471de5a129ae is unchanged.

Exact stack — refreshed 2026-08-21

• base: fix/recovery-evidence-weakref-coverage-b84f0c9@5951b7a4d779903b8924abaef2a387cae50b7f54 (test(recovery): cover stale evidence registry cleanup #233)
• head: feat/postgres-wal-receive-b84f0c9@1b223841ee522950e09470a4910604fbb979733f
• Draft: yes
• mechanically mergeable at the latest refetch
• formal reviews: none
• inline review threads: none
• targeted branch inventory: this is the only postgres-wal-receive branch

#233 must integrate first. No predecessor, stale, queued, absent, status-only, author-only, or synthetic evidence transfers to this head.

Branch-only receive contract

receive_postgres_wal_archive(...) requires a canonical nonzero requested end LSN, an existing operator-governed physical replication slot, and an owner-only initially empty archive-directory descriptor. It snapshots directory authority, retains a reviewed root-owned non-set-id pg_receivewal executable inode, restricts inherited libpq environment, uses --synchronous, --no-loop, --no-password, a finite timeout, and revalidates the same private directory identity after the receiver exits.

The result records only requested_end_lsn. It does not assert that the receiver reached that LSN. Exact reach, gap-free WAL continuity, segment integrity, timeline ancestry, replay/PITR, application usability, external secret/configuration recovery, and deployment RPO/RTO/HA/DR remain separate evidence.

#282 completion-authority RCA and narrow fix

PostgreSQL 18 documents handled SIGINT/SIGTERM as normal exit status 0 for pg_receivewal, the same process status observed after --endpos completion. subprocess.CompletedProcess.returncode == 0 therefore cannot distinguish the two causes once the child handles the signal.

A deterministic RED was committed at 5958a135cf0459543df32095cfc65aa887968002: a signal-indistinguishable zero exit must not produce an object that exposes end_lsn=<requested> as achieved evidence. Source head b2dd7f1ed8d8d017309b72a9e427afcccaaf97b7 narrowed the result contract instead of parsing localized stderr or inventing a completion reason: it records only the requested bound and documents that a zero process exit is not endpoint proof. Existing storage, executable, timeout, slot, environment, and final directory-authority controls remain intact.

The result constructor keeps the branch-local end_lsn= construction spelling only as a compatibility input alias for pre-existing tests; returned objects have no end_lsn attribute and do not expose an achieved-end claim.

Exact-head stale-regression RCA and repair

CI 32351879605 on exact predecessor b2dd7f1ed8d8d017309b72a9e427afcccaaf97b7 independently checked out that head and exposed one branch-owned stale assertion in tests/test_postgres_wal_archive_fd_race.py: the regression still read result.end_lsn after the product contract had intentionally removed that achieved-end attribute. The same run otherwise reached exact 100% owned production statement/branch coverage, so this was a test/contract mismatch rather than a coverage defect.

Current exact head 1b223841ee522950e09470a4910604fbb979733f changes only that regression assertion to result.requested_end_lsn == "0/1000000", preserving the FD-substitution security test while aligning it with the narrowed evidence contract. No production source changed in this follow-up commit.

#270 aggregate disk-exhaustion boundary

A finite requested end LSN and timeout do not by themselves bound aggregate bytes when an existing slot retains much older WAL. The branch therefore retains the kernel-backed storage authority boundary already established for #270:

• maximum_archive_bytes is an exact positive built-in integer, default 64 GiB, hard maximum 1 TiB;
• the retained empty archive directory must be the root of a filesystem distinct from its parent;
• fstatvfs() total data-block capacity must not exceed the selected ceiling before the receiver starts; and
• malformed/unavailable capacity authority fails through fixed content-free package errors.

Current exact-head gates

For unchanged exact 1b223841ee522950e09470a4910604fbb979733f at the latest refetch:

• CI 32362141410: completed / success;
• Release Acceptance 32362141479: completed / success;
• exact-head Security Scan / SAST Semgrep: not materialized in the commit-scoped pull-request workflow inventory;
• formal reviews: none; and
• inline threads: none.

The two exact-head repository-local successes prove their own checkout only. Absent Security/SAST and absent review remain non-passing. Keep this PR Draft and unchanged unless a branch-owned defect or material dependency state change appears.

Remaining acceptance boundary

Before this PR can leave Draft, exact hosted evidence must prove the unchanged current source and tests, including Python 3.14, exact owned-production statement/branch coverage, public docstrings, security/SAST, package/provenance/release gates, and live review policy. After #233 integrates through live governance, reconcile this branch to the resulting protected main, re-prove exact ancestry/relative diff, and reacquire every then-required gate.

Refs #204, #233, #239, #240, #244, #270, #282.

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}