Skip to content

Pin a Maven patch for a pinned rules_jvm_external hub with override_repo - #2163

Open
Mikola Lysenko (mikolalysenko) wants to merge 4 commits into
bazel-maven/01-hub-noticefrom
bazel-maven/02-override-repo
Open

Mikola Lysenko (mikolalysenko) wants to merge 4 commits into
bazel-maven/01-hub-noticefrom
bazel-maven/02-override-repo

Conversation

@mikolalysenko

@mikolalysenko Mikola Lysenko (mikolalysenko) commented Nov 19, 2026 •

Copy link
Copy Markdown
Collaborator

Hosted mode now patches a Maven artifact that a pinned rules_jvm_external hub of a Bazel workspace builds: socket-patch get <purl> --mode hosted at the Bazel root appends one managed block to MODULE.bazel (Bazel's override_repo), the build takes the patched jar at its sha256, and rollback / remove take the block out byte for byte.

Stacked. This pull request is on top of #2157 ("Say when a rules_jvm_external hub builds a Maven artifact that a patch does not reach"), whose branch bazel-maven/01-hub-notice is its base; below that are #2148, #2139 and #2123. It moves onto main when those have landed. The diff here is four commits: tests that record today's behaviour, the change, what a code review of it changed, and a correction of what a run reports beside an entry that has no effect.

What the code does today

A rules_jvm_external hub builds the jars its own lock (maven_install.json) pins and reads no pom.xml. So no Maven patch reaches a Bazel build. The first commit holds this on real Bazel, with the product code of the base:

  • In a tree that only Bazel builds, get --mode hosted reports the patch skipped (redirect_unconfirmed), writes nothing, and warns redirect_maven_no_pom and maven_bazel_hub_unpatched. The build prints the upstream marker before and after. rollback then exits 1 with manifest_not_found.
  • Beside a pom.xml, the command pins the pom, reports applied, and the Bazel build still takes the upstream jar.
  • After the checkout bumps the artifact to 1.11.0 and relocks, the build takes the new upstream jar. Nothing stops it.
  • With the user's own maven.override of the artifact, the command warns maven_bazel_unreadable and the build prints the override's target.

What changes

The block

The hub fetches each jar through a repository of its own, named after group, artifact and version. override_repo (Bazel 7.4.0 and later) puts another repository in its place. socket-patch appends this to the root MODULE.bazel, after one blank line:

# >>> socket-patch: Maven patches for Bazel (managed block: socket-patch writes and removes it) >>>
socket_patch_http_file = use_repo_rule("@bazel_tools//tools/build_defs/repo:http.bzl", "http_file")

socket_patch_maven = use_extension("<the label of the hub's own use_extension>", "maven")

# pkg:maven/<group>/<artifact>@<version>, Socket patch <uuid>
socket_patch_http_file(
    name = "socket_patch_<repository>",
    downloaded_file_path = "v1/<group path>/<artifact>/<version>/<artifact>-<version>.jar",
    sha256 = "<sha256 of the patched jar>",
    urls = ["<the patched jar on the Socket patch host>"],
)

# If Bazel stops at the next line ("does not generate repository"), the hub's lock no longer pins
# <group>:<artifact> at <version>: run `socket-patch rollback pkg:maven/<group>/<artifact>@<version>`.
# Do not change it to inject_repo(): the build would pass without the patch.
override_repo(
    socket_patch_maven,
    <repository> = "socket_patch_<repository>",
)
# <<< socket-patch <<<
  • One entry per patch, sorted by repository name, each with its own override_repo, so Bazel names the line of the one entry that went stale.
  • The hub, maven_install.json, every label and MODULE.bazel.lock stay as they are.
  • The block is socket-patch's when it is, byte for byte, what socket-patch writes for the patches it names, in the line break of its own lines. A block that was changed by hand, also in its first line alone, is neither written to nor read as a pin.
  • A new block is written in the line break of the file; in a file with both, in the more frequent one.
  • The undo takes an entry out; with the last entry the block and the blank line before it go. The file is then byte for byte what it was: in LF and CRLF files, in a file with both, with and without a last line break.

When it is written

Everything is read from the checkout; no Bazel runs. The block is written only when all of this holds:

  • the project is the Bazel root;
  • a pinned hub's lock holds the plain jar at the patch's version, and nothing about the workspace's hubs is in doubt;
  • the lock lists a repository for the jar;
  • the hub is on a shared (not isolated) use_extension;
  • Bazel is known to be 7.4.0 or later, and the rules_jvm_external release Bazel builds with is known to be one of 6.4 to 7.2;
  • no rc file of the checkout makes the block ineffective or the download impossible;
  • the patch is one of the plain jar, and comes with its served version and a sha256.

The rc files are .bazelrc and what it imports, up to 32 files: import, try-import and, from Bazel 8.7.0, try-import-if-bazel-version, whose condition is not evaluated; by a path under %workspace%/, or by a relative one, which is read from the Bazel root. Each file is read as Bazel reads one (rc_file.cc and the tokenizer in util/strings.cc at 7.4.0, 7.7.2, 8.8.2 and 9.3.2): a backslash before a line break joins two lines, a # outside quotes starts a comment, a word loses its quotes and the backslash before an escaped character, and the first word of a line is its command. A line with a quote that is never closed, or a backslash that nothing follows, makes the file one that cannot be read. An option counts as on or off the way Bazel's boolean converter reads it on those releases (false, 0, no, f, n in any case, or no before the name). A word that is neither for certain counts as the harmful one.

The release of the ruleset is the one whose source.json MODULE.bazel.lock holds, checked against what the root asks for, as Bazel takes it: a single_version_override with a version pins that release, whatever the bazel_dep line says; without one, the bazel_dep version is the least Bazel selects. Versions are compared in Bazel's order (7.2 is below 7.2.1).

Every decline

Otherwise the run writes nothing for the hub and gives one warning. Each says why, and ends with what the block of the root holds for the jar. The root is read for a project below it too, whose warning names the file as "the MODULE.bazel at the root".

  • Nothing: "socket-patch wrote nothing to MODULE.bazel for it, so the Bazel build keeps the upstream jar".
  • The entry of this patch, from an earlier run: "socket-patch left the entry that MODULE.bazel holds for it as it is".
  • The entry of another patch of the same jar: "socket-patch wrote nothing to MODULE.bazel for it: the entry of patch remains there, and where the block is in effect the Bazel build takes that patch's jar".
Code When
maven_bazel_not_at_root The project is below the Bazel root. Run the command there.
maven_bazel_not_pinned A hub has no lock_file, also beside a pinned hub that holds the jar. The message names the hub's line and the command that pins it (REPIN=1 bazel run @<the hub's name>//:pin).
maven_bazel_unreadable Something could not be read with certainty: a computed name or lock_file, two locks for one hub, a lock that is missing, empty, not format 2 or 3, no JSON or over 16 MiB, a WORKSPACE file that calls maven_install while Bazel may read it, an isolated use_extension, an rc file that cannot be read (also one that an import takes from outside the workspace by a relative path, and one with a line that has a quote that is never closed or a backslash that nothing follows; the message names the line), a MODULE.bazel that is a symbolic link, a block that was changed by hand.
maven_bazel_release .bazeliskrc or .bazelversion names a Bazel before 7.4.0; or neither names a release and MODULE.bazel.lock is missing or older than the format Bazel 7.5.0 writes; or MODULE.bazel.lock does not hold the source.json of exactly one rules_jvm_external release, that release is outside 6.4 to 7.2, or it is another one than MODULE.bazel now takes (older than the bazel_dep line, or any other than the one a single_version_override pins); or an archive_override, git_override, local_path_override or multiple_version_override of the ruleset, or a single_version_override whose version is no plain string, leaves the release unknown (the message names the override's line).
maven_bazel_artifact A character other than letters, digits, ., _, - in group, artifact or version (the repository's name is then not known); the lock lists no repository for the jar (m2local); the patch lacks its served version or sha256.
maven_bazel_no_effect The build would pass on the upstream jar: a maven.override of the artifact, or an rc file of the checkout gives --ignore_dev_dependency without switching it off, or gives enable_bzlmod other than switched on while the checkout names no Bazel 9 or later.
maven_bazel_download An rc file of the checkout gives a downloader config, --repository_disable_download or --vendor_dir.

What a run reports

  • Written: exit 0, applied, redirect.rewrittenFiles holds MODULE.bazel, no warning. Beside a pom.xml the same run pins both builds.
  • Declined, tree only Bazel builds: exit 0, skipped / redirect_unconfirmed, the one warning, in the place of redirect_maven_no_pom.
  • Declined, beside a pom.xml that was pinned: exit 0, applied, the same warning.
  • Declined, and the block of the root already holds the patch's entry from an earlier run: the entry stays, the patch is applied, and the warning says that the entry was left. This holds at the root and for a project below it. The exception is a decline for a reason that leaves an entry without effect (maven_bazel_no_effect): the patch is then not applied, and the warning says that the Bazel build keeps the upstream jar.
  • Declined, and the block holds the entry of another patch of the jar: that entry stays, the warning names its patch id, and the event is the one of the same run without the hub.
  • rollback / remove: the entry goes. list shows the pin with MODULE.bazel as its file. vex attests it while a pinned hub fetches that version and no rc file of the checkout switches the entry off, on any line, or cannot be read.
  • A version bump of a patched artifact: the relock passes; then Bazel stops at the entry's override_repo( line until socket-patch rollback <purl> has run. vex attests nothing for such an entry.
  • maven_bazel_hub_unpatched: a hosted run no longer gives it. Vendored and agent runs still do, with a text that names the hosted command, and not for a jar the block patches.
  • Vendored runs leave the block alone. vendor, scan / get --mode vendored and vendor --revert take over the other files of a hosted pin (a pom.xml, a Gradle build) and leave its entry in the block as it is, so the Bazel build keeps the patched jar; rollback and remove take the entry out. Without this, a vendor beside such an entry exited 0, took the entry out and said only that the Bazel build "stays unpatched" (seen in a run against a loopback stand-in of the API).

What does not change

  • A project in no Bazel workspace: nothing is read beyond the lookup of a workspace file, and output and written files are byte for byte those of the base.
  • A Maven project beside a Bazel workspace whose hubs do not hold the artifact at the patch's version: the same.
  • A patch of a jar with a classifier, or of another packaging than jar: the same, also when a patch of the plain jar of the same artifact is in the same run. A lock names the plain jar by group and artifact alone, so such a patch is not looked at for the hub.
  • --global. Vendored and agent mode patch no hub, as before; apart from the notice's text and the block they leave in place, they are the runs they were. list, rollback, remove and vex read the block whatever mode wrote the rest.

Code review

The third commit applies a code review of the second. One bullet per finding:

  • Two patches of the same coordinates in one run. The verdicts of a run were looked up by group, artifact and version, so beside a patch of the plain jar, a patch of a jar with a classifier could take the plain jar's entry or be reported as pinned by the hub. Fixed: one function names the patches a hub can take, from the purl of each, and a verdict belongs to one patch id. A unit test runs both patches in both orders.
  • vex attested an entry that an rc file switches off. Only the first thing the rc reading met was looked at, so an rc file that cannot be read, or an earlier option about downloads, hid a later --noenable_bzlmod. Fixed: every line is read; an option that switches the entry off, on any line, and an rc file that cannot be read withhold the statement, and the diagnostic names the reason. An option about downloads alone still attests: such a build takes the patched jar or fails.
  • A run below the Bazel root said "keeps the upstream jar" when the root's block already held the patch. Fixed: the root's block is read for such a project too; the run reports applied and says that the entry at the root was left, as the same case at the root does.
  • A decline beside the entry of another patch said "keeps the upstream jar". Fixed: the warning names that patch and says that its entry remains. It adds "where the block is in effect", because the decline may be about an rc file that switches the block off.
  • A root that pins the ruleset lower was declined for ever. Any bazel_dep version above the lock's was taken for a stale lock, also under a single_version_override, and a version of three numbers took the same branch; an override that replaces the ruleset's source got the advice to build once. Fixed as described under "When it is written" and in the maven_bazel_release row.
  • Options that Bazel reads and socket-patch did not see. Option names were matched against the blank-separated words of each physical line. Fixed: lines are joined and words are read as Bazel reads them; what Bazel's own source calls an oversight (a quote that is never closed, a backslash that nothing follows) makes the file one that cannot be read. As a result an option behind a # no longer counts, and an import whose path is quoted is followed.
  • Decline codes chosen by the wording of a message. The kind of a doubt is now a value beside its text, and the hub's name a field. The pom rewriter asks whether a hub decides a patch before it says "no pom.xml"; the hub lane no longer takes that warning back by its code. Every message is byte for byte what it was. Cost: about 24 code lines.
  • Three copies of how a Maven patch's group and artifact are derived. One function now, used by the pom rewriter and the hub lane. No behaviour change; the Maven redirect tests pass unedited.
  • A second rule for the line break of a file with both. The block now uses the helper the other writers that keep CRLF use (the more frequent line break). The undo holds byte for byte for every file shape of the unit test.
  • The hubs of a workspace are read again in each discovery. Left as it is, with a measurement: beside a 4.9 MiB lock, in a debug build, a hosted get reads the hubs twice (66 to 91 ms in all of a 102 to 152 ms run) and scan, list, vex and rollback once each (32 to 45 ms). Nearly all of a read is the JSON parse of the lock. Sharing that parse inside a run needs process-wide state keyed by the lock's content, about 15 code lines, to save one parse per get.

A fourth commit corrects one thing the review's changes left: a run that declined for a jar whose entry was already in the block reported the patch as applied whatever the reason. For maven_bazel_no_effect (an rc file that switches the block off, a maven.override of the jar) the entry is there and the Bazel build takes the upstream jar, so such a run no longer reports applied, and its warning ends "and while that stands the entry has no effect: the Bazel build keeps the upstream jar". A unit test holds both endings.

Contents and sizes

22 files, +4,542 −346 against the base (first commit: 6 files, +260 −55; second: 18 files, +3,719 −325; third: 9 files, +1,035 −438).

Part Files Lines
Implementation bazel/maven.rs (the block, the conditions, the lane, what discovery reads), bazel/rc.rs (MODULE.bazel.lock, rc files), hosted/engine.rs, patch/redirect/mod.rs, patch/redirect/upstream/bazel_maven.rs, vex/discover/bazel_maven.rs, two mod.rs, commands/vendor.rs +1,340 −61 outside cfg(test) items; 904 code lines by scripts/loc-budget.py (the third commit: 75)
Unit tests in the same files +1,765 −6
CLI tests e2e_bazel_build/maven.rs, e2e_bazel_maven_beside.rs, vendor_jvm_cli.rs +1,223 −210
Fixture three MODULE.bazel, reformatted to what bazel mod tidy keeps +27 −6
Docs docs/ecosystems.md, CLI_CONTRACT.md +155 −48
Workflow, scripts bazel-maven.yml, bazel-pins.txt, loc-budget.json +32 −15

scripts/loc-budget.json: bazel 1459 → 2230. lock-readers and lock-writers grow by 48 and 75 code lines; both were over their caps before, and the caps are not touched.

What it proves, and where

Real Bazel, four flows on each release, macOS arm64, final head:

Bazel rules_jvm_external Result Seconds per flow (tree only Bazel builds, pom beside the hub, the user's override, version bump) Requests to a public Maven host
9.3.2 7.2 4 pass 72.6, 75.5, 19.3, 22.4 (empty repository cache) 0 of 170
8.8.2 6.9 4 pass 78.8, 59.0, 12.8, 17.1 (empty repository cache) 0 of 113
7.7.2 6.5 4 pass 76.5, 59.1, 13.9, 18.7 (empty repository cache) 0 of 113
7.4.0 6.5 4 pass 34.8, 28.9, 18.0, 19.2 (the cache of 7.7.2) 0 of 94

The flows hold:

  • the block's exact text in MODULE.bazel;
  • the same build prints the marker of the patched jar, with this run's id, fetched from the patch host;
  • a --lockfile_mode=error build passes; the ruleset's relock leaves the lock as it is; bazel mod tidy leaves the file as it is;
  • rollback restores every file byte for byte, and the upstream build;
  • a second machine whose patch host serves other bytes fails with "Checksum was … but wanted …" and does not go to the upstream jar;
  • after a bump to 1.11.0 the build stops at MODULE.bazel:46, the entry's line, until rollback <purl>;
  • a hub with the user's own maven.override is declined and builds as before;
  • on 7.4.0, a checkout without .bazelversion is declined until it has one.

With a binary of the base's product code all four flows fail on 9.3.2 (run on the second commit; not repeated on the third).

Without Bazel:

  • one row per decline and its text, with each spelling Bazel reads as "off", each kind of rc import, each override of the ruleset, and versions of two and three numbers;
  • the rc tokenizer, row by row under the line of Bazel's source it rests on: blanks, comments, quotes, escapes, joined lines, and the two shapes that are not read;
  • the block added, added again and taken out over nine file shapes (LF, CRLF, both in one file; with and without a last line break; blank lines at the end);
  • the reader with and without the block, and with a block whose first line was touched;
  • two patches of the same coordinates in one run, in both orders, and what a decline says of the block at the root and below it;
  • discovery, the restore, and the CLI end to end: the pin and its undo, each decline, a decline beside an entry of an earlier run, a run below the root beside the root's entry, a decline beside another patch's entry, a block changed by hand under rollback and list, a patch of a classifier jar, vendor and vendor --revert beside an entry.

Each finding of the code review was first shown by a test that failed on the second commit: five unit tests and two CLI tests.

Single changes of the product, each of which fails a named test: 22 for the third commit, run on the final head, one per new or changed check (the plain-jar test, a verdict per patch id, every rc line for vex, an unreadable rc file, the root's block below the root, the other patch's entry, a pinned release, the version order, each kind of override, joined lines, quotes, escapes, comments, an open quote, the blanks around a line, %workspace%//, the kind of a doubt, the hub's name, the pom lane, the line break of a file with both). Before them: 16 for an earlier review and 41 during development, which were not repeated on the final head.

Do no harm, measured on the final head against a binary of the base: 272 runs over 8 checkouts (no Bazel file, another ruleset's hub, a pinned hub that holds the artifact at another version; each with a pom.xml, without one, and two with a Gradle build) of hosted get in JSON, human and dry-run form, list, vex, scan, rollback, remove, apply, vendor, vendor --check, vendor --revert and scan --mode vendored. 269 are byte for byte equal in stdout, stderr, exit code and written files; the other three differ only in the random id and the time of the VEX document. The vendor runs of that comparison end in the same refusal on both binaries; a vendor that succeeds beside a workspace is held by the two hub tests of vendor_jvm_cli.rs.

Three existing expectations changed in the second commit, all because of the behaviour above: a hosted run beside a hub it cannot patch gives the decline's code in the place of maven_bazel_hub_unpatched; a tree only Bazel builds gives that code alone, without "no pom.xml" (that test is renamed); the text of maven_bazel_hub_unpatched in three tests. The third commit changes expectations of the second commit's own unit tests only: an option behind a # is no longer found; a quoted import, and one joined over a line break, are followed where they were refused; a quoted option is named without its quotes; a decline beside another patch's entry names it; and "no pom.xml" is held at the pom rewriter, not at the hub lane.

What starts on main

  • bazel-maven.yml gets a fourth Linux leg: Bazel 7.4.0 with the fixture era of Bazel 7. 7.4.0 is the first release with override_repo, so the oldest Bazel the change accepts is one CI builds. Its two digests in scripts/bazel-pins.txt are from the release's published .sha256 files.
  • The new leg shares the repository cache of the 7.7.2 leg. Cold caches measured here: 404 MB (9.3.2), 352 MB (8.8.2), 333 MB (7.7.2); the 7.4.0 leg added 1 MB to the cache of 7.7.2.
  • No leg asks a public Maven repository. Every run here was behind a logging proxy that refuses such hosts: 490 requests over the four legs of the final head, none refused (the Bazel registry, GitHub, Bazel's mirror, the JDK's CDN and, on Bazel 9, go.dev). The patched jar comes from the test's loopback server, to which a downloader config on Bazel's command line sends the patch host.
  • On Linux, on GitHub's runners, the four Maven legs of this pull request pass at its head: Bazel 9.3.2 in 244 seconds, 8.8.2 in 205, 7.7.2 in 206 and 7.4.0 in 206, with the other 73 checks. The local runs were on one macOS arm64 machine.
  • On Windows the real-Bazel tests do not run (they are Unix-only). The tests without Bazel pass there (the unit tests of bazel::maven and bazel::rc and the thirteen tests of e2e_bazel_maven_beside), in a run of the workspace tests started by dispatch on this branch (run 44571237392). That run is red for one other test, scan_project_discovery_e2e::agent_scan_names_a_python_project_below_with_its_own_venv, in a file this pull request does not touch: it builds a virtualenv with the Unix layout.

Not covered

  • scan does not find the artifacts of a hub. It pins a hub's jar only for a package it found elsewhere (a pom.xml, a Gradle build). It does not take a stale entry out; rollback and remove do.
  • Vendored and agent mode patch no hub. After a vendored takeover beside a hub entry the package is vendored for Maven or Gradle and hosted for Bazel.
  • A hub without a lock, a maven_install of a WORKSPACE file, Bazel before 7.4.0, rules_jvm_external before 6.4 or after 7.2, a ruleset that an override takes from outside a registry: declined with a reason. A patch of a jar with a classifier or of another packaging: not looked at, and nothing is said of the hub.
  • A single_version_override that patches the ruleset (patches, patch_cmds) is taken as the release it names. If such a patch changes how the ruleset names a jar's repository, Bazel stops at the entry.
  • vex still attests a patch that only a pom.xml pin carries, although the Bazel build beside it is unpatched.
  • A hub or an override that another Bazel module declares, the command line (also --override_module), the rc files of the machine and of the home directory, and an rc file imported by an absolute path are not seen.
  • The rules for rc files, for the ruleset's overrides and for versions are held without Bazel (unit rows, and Bazel's sources read at four tags), not by a Bazel build.
  • maven_bazel_download names no remedy: while an rc file of the checkout gives one of those options no entry is written, whatever the downloader config allows.
  • For a block that was changed by hand, the warning of a hosted run still ends "the Bazel build keeps the upstream jar", although what such a block does for the build is not known. rollback, remove and list give the shared hosted_wiring_contested text, whose first advice (scan --mode hosted) does nothing here; the second (git checkout -- MODULE.bazel) is the remedy. The shared text is not changed.
  • A scanner that reads only maven_install.json keeps reporting the advisory: the lock names the upstream version on purpose.
  • The human "Next steps" after a hosted run still say "Reinstall from the updated lockfile"; for Bazel the next build is enough.
  • The hubs of a workspace are read once per discovery, so twice in a hosted get (measured under "Code review").

What follows

  1. scan finds the artifacts a pinned hub builds, and takes a stale entry out.
  2. VEX: withhold the statement of a patch that a hub builds unpatched.
  3. Vendored mode: a committed jar behind the same block.
  4. Agent mode.

Decisions for the owner

Appending a block to MODULE.bazel was decided ("great, do it"). These are taken as recommended, and each can still be overruled:

  1. A version bump of a patched artifact stops the build until socket-patch runs. Taken. The other choice is not to patch pinned hubs at all: nothing softer was found that is not silent.
  2. A build that cannot be shown safe from the checkout is declined, also where it would probably work. Taken, with one narrowing: enable_bzlmod switched on is accepted. The other choice trusts the bazel_dep version and only warns about rc files.
  3. Agent mode will use the vendored form. Not in this pull request: agent and vendored runs patch no hub yet and say so. The other choice is a decline that names vendored mode.
  4. The committed URL holds the patch's token, as a hosted pin in pom.xml does. Taken. The other choice is to wait for vendored mode.
  5. A patch that a hub builds unpatched still counts as applied when a pom or Gradle build took it, with the warning. Taken. The other choice reports skipped, which changes a contract for projects that pass today.
  6. The lock keeps naming the upstream version. Taken: the patch shows in MODULE.bazel and in vex. The other choice edits the lock, which the next relock undoes in silence.
  7. Hubs without a lock and WORKSPACE hubs are declined, not built. Taken. The other choice builds them by routes that were measured to be unsafe.
  8. A Bazel 7.4.0 leg. Taken. The other choice leaves the floor untested in CI.

Further choices made here:

  • The comment in the block names socket-patch rollback <purl>, not socket-patch scan, because scan does not take a stale entry out yet. The comment is part of how the block is recognised, so a later change of its wording must keep reading this one.
  • A hub without a lock beside the pinned hub that holds the jar declines. The other choice writes the block and names the other hub.
  • A block that was changed by hand makes rollback, remove and list refuse for the project until the file is restored, as other hosted wiring that cannot be attributed does.
  • A vendored takeover leaves the hub's entry hosted. The other choice takes the entry out and warns that the Bazel build lost its patch.
  • A patch of a classifier jar is not looked at for the hub. The other choice is a decline with maven_bazel_artifact, which needs the classifier entries of the lock read.
  • A decline for a patch whose entry is already in the block reports applied and leaves the entry, at the root and below it. The other choice reports skipped, as before, though the pin is there. One case of it deserves a look: when the decline is about an rc file that switches the block off, the run says applied with that warning while the build takes the upstream jar; vex attests nothing then.
  • For vex, an rc option under which the download of the patched jar may fail does not withhold the statement: such a build takes the patched jar or fails. The other choice withholds it for every rc finding.
  • A single_version_override that patches the ruleset is accepted. The other choice declines it, which turns away every checkout that patches rules_jvm_external.

🤖 Generated with Claude Code

…xternal hub

Tests only. They record what `socket-patch get <purl> --mode hosted` does
today in a Bazel workspace whose rules_jvm_external hub builds the
artifact from a pinned lock, for the shapes the next commit changes. In
all of them the command writes nothing a Bazel build reads, and the build
takes the jar the hub's lock pins.

The flows of `maven::` in `e2e_bazel_build`, on real Bazel:

- `a_tree_only_bazel_builds` (a checkout without pom.xml) gains two
  steps. `bazel mod tidy` passes and leaves MODULE.bazel byte for byte as
  it is. `rollback --yes` after the skipped patch exits 1 with
  `manifest_not_found` and changes no file: nothing was pinned.
- `a_version_bump_of_the_patched_artifact` is new. After the command
  skipped the patch, the checkout names the artifact at 1.11.0 beside the
  artifact that depends on it, the test serves that release, and the
  ruleset's own relock (`REPIN=1 bazel run @fixture_maven//:pin`) takes it
  into the lock. The build then prints the marker of the 1.11.0 jar.
  Nothing stops it.
- `the_users_own_override_of_the_artifact` is new. The hub has a
  `maven.override` that puts a `java_library` of the checkout in the
  artifact's place. The build prints that target's marker before and after
  the command, which reports the patch skipped, writes nothing, and names
  the override's line in `maven_bazel_unreadable` after "no pom.xml".
- `a_pom_patch_beside_a_pinned_hub` is unchanged.

The checkout setup is shared: `Pinned::open` takes what a flow adds to the
files and to MODULE.bazel before the pin, `serve_upstream` puts a release
in the test's Maven repository, and `skips` holds what the command says
and leaves in a tree without pom.xml.

The fixture's three MODULE.bazel files are now in the layout `bazel mod
tidy` keeps: `module(...)` and `single_version_override(...)` one
argument per line, a blank line before the override. Before, tidy rewrote
those two calls on every release tried, so "tidy leaves the file as it
is" could not be held. No call and no argument changed.

A fourth leg: Bazel 7.4.0 with the era of Bazel 7 (rules_jvm_external
6.5, lock format 2). 7.4.0 is the first release that has `override_repo`,
which the next commit writes, so the oldest Bazel it accepts is one that
CI builds. scripts/bazel-pins.txt gets the two digests from the release's
published `.sha256` files; the darwin-arm64 binary downloaded from the
GitHub release matched its digest before it ran.

Run on macOS arm64 with the product code of this commit, every child
behind a logging proxy that refuses public Maven hosts: the four flows
pass on Bazel 9.3.2 (36 s for the four, two at a time) and on 7.4.0 from
an empty repository cache (333 MB after the run; 404 MB on 9.3.2). No
request to a public Maven host on either (162 and 117 connections logged
on the cold runs: the Bazel registry, GitHub, Bazel's mirror, the JDK's
CDN and, on Bazel 9, go.dev).

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
A rules_jvm_external hub of a Bazel workspace builds the jars its own
lock pins, so until now no Maven patch reached a Bazel build: hosted mode
pinned a pom.xml beside the hub, or nothing, and said so. With this
commit `socket-patch get <purl> --mode hosted`, run at the Bazel root,
patches a pinned hub, and `rollback` and `remove` undo it.

How

The hub fetches each jar through a repository of its own, named after
group, artifact and version, and Bazel's `override_repo` (7.4.0 and
later) puts another repository in its place. socket-patch appends one
block to the root MODULE.bazel, after one blank line: per patch an
`http_file` with the URL of the patched jar on the Socket patch host and
its sha256, and an `override_repo` of the hub's repository. The hub, its
lock, every label and MODULE.bazel.lock stay as they are.

  # >>> socket-patch: Maven patches for Bazel (managed block: ...) >>>
  socket_patch_http_file = use_repo_rule("@bazel_tools//...:http.bzl", "http_file")

  socket_patch_maven = use_extension("<the label of the hub's own use_extension>", "maven")

  # pkg:maven/<group>/<artifact>@<version>, Socket patch <uuid>
  socket_patch_http_file(
      name = "socket_patch_<repository>",
      downloaded_file_path = "v1/<path of the upstream jar>",
      sha256 = "<of the patched jar>",
      urls = ["<the patched jar>"],
  )

  # If Bazel stops at the next line ("does not generate repository"), ...
  # <group>:<artifact> at <version>: run `socket-patch rollback <purl>`.
  # Do not change it to inject_repo(): the build would pass without the patch.
  override_repo(
      socket_patch_maven,
      <repository> = "socket_patch_<repository>",
  )
  # <<< socket-patch <<<

The block is recognised by its text alone: it is socket-patch's when it
is, byte for byte, what socket-patch writes for the patches it names.
One that is not was changed by hand, and is neither written to nor read
as a pin; so is one whose first line alone was touched (a blank after
it). The undo takes an entry out, and with the last entry the block and
the blank line before it: the file is then byte for byte what it was, in
LF and CRLF files and in a file with both, with and without a last line
break. A block is compared in the line break of its own lines.

When it is written

Everything is read from the checkout; no Bazel runs. An entry is written
only when all of this holds, and otherwise the run writes nothing for
the hub and gives one warning that says why and that the Bazel build
keeps the upstream jar:

- maven_bazel_not_at_root: the project is the Bazel root.
- maven_bazel_not_pinned: no hub of the workspace is without a lock.
- maven_bazel_unreadable: every hub and lock was read, no hub is on an
  isolated `use_extension`, MODULE.bazel is no symbolic link, no rc file
  is unreadable, and the block was not changed by hand.
- maven_bazel_release: `.bazeliskrc` or `.bazelversion` names Bazel 7.4.0
  or later, or MODULE.bazel.lock has the format Bazel 7.5.0 writes; and
  MODULE.bazel.lock holds the `source.json` of exactly one
  rules_jvm_external release, one of 6.4 to 7.2, not older than the
  `bazel_dep` line. The `bazel_dep` line alone is not taken: Bazel can
  select a newer release, and the name of a jar's repository is the
  ruleset's (read at each tag: `escape(coordinates)` to 6.7,
  `to_repository_name` from 6.8; they agree for coordinates of letters,
  digits, `.`, `_` and `-`).
- maven_bazel_artifact: the coordinates have only those characters, a
  repository of the lock lists the jar (a jar that only `m2local` gives
  has a repository on some machines and none on others), and the patch
  comes with its served version and a sha256.
- maven_bazel_no_effect: no `maven.override` of the artifact, and no rc
  file of the checkout names `--ignore_dev_dependency` without switching
  it off, or names `enable_bzlmod` other than switched on (below a
  declared Bazel 9): the build would pass on the upstream jar.
- maven_bazel_download: no rc file of the checkout names a downloader
  config, `--repository_disable_download` or `--vendor_dir`.

The rc files are `.bazelrc` and what it imports, up to 32 files, as
Bazel's rc_file.cc takes an import (read at 7.4.0, 7.7.2, 8.8.2 and
9.3.2): `import`, `try-import` and, from Bazel 8.7.0,
`try-import-if-bazel-version`, whose condition is not evaluated; by a
path under `%workspace%/`, or by a relative one, which Bazel opens from
where it runs and which is read from the root. An option is on or off as
Bazel's BooleanConverter reads it on those four releases: `false`, `0`,
`no`, `f`, `n` in any case, or a `no` before the name. A word that is
neither for certain counts as the harmful one. Not seen: the rc files of
the machine and of the home directory, an import of an absolute path,
and the command line.

A jar that no hub holds, and a project in no Bazel workspace, get
nothing of this: no file is read further, and the run is the one it was.
So does a patch of a jar with a classifier, or of another packaging: a
lock names the plain jar by group and artifact alone.

What a run reports

- The hub lane runs after the pom lane (`bazel::maven::rewrite`), from
  what the engine read of the checkout (`bazel::maven::site`, handed over
  under a synthetic candidate key as the sbt and Go answers are). A patch
  whose entry is in the block is `applied`, whatever a pom.xml or Gradle
  build beside the hub pins; `redirect.rewrittenFiles` holds
  MODULE.bazel. A patch that only a pom.xml took is `applied` too, with
  the hub's warning beside it.
- In a tree that only Bazel builds, a decline is `skipped` /
  `redirect_unconfirmed` with the hub's warning in the place of
  `redirect_maven_no_pom`.
- A decline for a patch whose entry an earlier run wrote leaves that
  entry where it is: the patch is still `applied`, and the warning ends
  "socket-patch left the entry that MODULE.bazel holds for it as it is".
- The previous `maven_bazel_hub_unpatched` is no longer given by a hosted
  run. Vendored and agent runs still give it, with a text that names the
  hosted command, and not for a jar the block patches.
- Vendored mode takes no hub over. `vendor`, `scan` / `get --mode
  vendored` and `vendor --revert` restore the other files of a hosted
  pin and leave its entry in the block as it is (`takeover_pins` in
  commands/vendor.rs), so the Bazel build keeps the patched jar; a pin
  that only the block wires is none of their pins. Without this a
  `vendor` beside such an entry exits 0, takes the entry out and says
  only that the Bazel build "stays unpatched" (seen in a run against a
  loopback stand-in of the API).
- Lockfile discovery reads the block (`vex/discover/bazel_maven.rs`), so
  `list`, `rollback`, `remove` and `vex` see the pin through the code
  they share. An entry whose jar a pinned hub no longer fetches at that
  version, or that an rc file switches off, is kept for the undo and
  withheld from attestation.

A version bump of a patched artifact

The relock passes. Then Bazel stops at the entry's `override_repo(` line
("does not generate repository ..., yet it is overridden via
override_repo()"), where the block names the command that takes the
entry out. Nothing softer exists: with `inject_repo`, which Bazel's
message suggests, the build passes on the upstream jar.

Tests

The flows of the previous commit now hold, on real Bazel: the block's
exact text; the same build prints the marker of the patched jar, fetched
from the patch host; a `--lockfile_mode=error` build passes; the
ruleset's relock leaves the lock and `bazel mod tidy` leaves the file as
they are; `rollback` restores every file byte for byte and the upstream
build; a second machine whose patch host serves other bytes fails on the
sha256 ("Checksum was ... but wanted ...") and does not go to the
upstream jar; after a bump to 1.11.0 the build stops at the entry's line
until `rollback <purl>`; a hub with the user's own `maven.override` is
declined and builds as before; a checkout of Bazel 7.4.0 without a
`.bazelversion` is declined until it has one. A pom.xml beside the hub
is pinned in the same run.

Run on macOS arm64 with the tree of this commit, every child behind a
logging proxy that refuses public Maven hosts, four flows per leg, each
leg from an empty repository cache but the last: Bazel 9.3.2 with
rules_jvm_external 7.2 (97 s, 404 MB), 8.8.2 with 6.9 (89 s, 352 MB),
7.7.2 with 6.5 (92 s, 333 MB), 7.4.0 with 6.5 on the cache of 7.7.2
(40 s). No request to a public Maven host on any leg (518 connections
in all: the Bazel registry, GitHub, Bazel's mirror, the JDK's CDN and,
on Bazel 9, go.dev). With a binary of the previous commit's product code
all four flows fail on 9.3.2.

Against that binary, 272 runs in checkouts without a Bazel file, with
another ruleset's hub, and with a pinned hub that holds the artifact at
another version (hosted get, list, vex, scan, rollback, remove, apply,
vendor and its check and revert) are byte for byte the same in output
and written files, but for the random id and the time of three VEX
documents.

Hermetic: one row per decline and its text, the block added, added
again and taken out over nine file shapes, the reader with and without
the block, discovery, the restore, and the CLI in
tests/e2e_bazel_maven_beside.rs (also: a decline beside an entry of an
earlier run, a block changed by hand under `rollback` and `list`, a
patch of a classifier jar) and in tests/vendor_jvm_cli.rs (`vendor` and
`vendor --revert` beside an entry). Three existing expectations change
there and in two other tests: a hosted run beside a hub that it cannot
patch now gives the decline's code in the place of
`maven_bazel_hub_unpatched`, a tree only Bazel builds gives it alone
(no "no pom.xml"), and the text of `maven_bazel_hub_unpatched` names
the hosted command.

Not here: `scan` does not find the artifacts of a hub, and does not
take a stale entry out; vendored and agent mode patch no hub; a hub
without a lock and a `maven_install` of a WORKSPACE file are declined.

scripts/loc-budget.json: bazel 1459 -> 2149.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Hosted mode writes one entry per Maven patch into a block of the root
MODULE.bazel, for a jar that a pinned rules_jvm_external hub builds, and
declines where it cannot show from the checkout that the entry works.
This closes cases in which it wrote, attested or said something that
the build does not bear out.

A verdict is that of one patch. The verdicts of a run were looked up by
group, artifact and version. In a run with a patch of the plain jar and
a patch of a jar with a classifier (or of another packaging) of the
same coordinates, the second took the first one's entry, or was
reported as pinned by the hub. bazel::maven::jars now names the patches
a hub can take, by the purl of each, and the verdicts are keyed by
patch id: a patch that is not among them gets no entry and no
confirmation.

The rc files are read as Bazel reads them. bazel::rc::mentions matched
option names against the blank-separated words of each physical line.
Bazel joins a line that ends in a backslash with the next one, takes
quotes and backslash escapes out of a word, ends a line at a # outside
quotes and takes the first word as the command (rc_file.cc, and
Tokenize in util/strings.cc, the same at 7.4.0, 7.7.2, 8.8.2 and
9.3.2). So "common --noenable_\" before "bzlmod", and
--noenable_"bzl"mod, were options that Bazel read and socket-patch did
not, and an option behind a # was one that socket-patch read and Bazel
does not. A line with a quote that is never closed, or with a backslash
that nothing follows, which Bazel's source calls an oversight, makes
the file one that cannot be read: maven_bazel_unreadable, with the
line. An import whose path is quoted is followed now, and so is
%workspace%//path.

VEX attests an entry only when nothing in the rc files stands against
it. Discovery took the first thing the rc reading tripped on, and
withheld the statement only when that was an option that switches the
entry off. So an rc file that could not be read, or an earlier option
about downloads, hid a later --noenable_bzlmod, and `vex` said
not_affected for a build that ignores MODULE.bazel. Every line is read
now. An option that switches the entry off, on any line, and an rc file
that cannot be read withhold the statement, and the diagnostic names
them. An option under which the download may fail still attests: such
a build takes the patched jar or fails.

A warning ends with what the block of the root holds for the jar. It
always ended "the Bazel build keeps the upstream jar", which was false
in two cases. Below the Bazel root the root's block is read now: when
it holds the entry of this patch, the run reports the patch as applied
and says that the entry stands, as a decline at the root does. When the
block holds the entry of another patch of the same jar, the warning
names that patch and says that its entry remains.

The release of the ruleset follows the root's overrides. A bazel_dep
version above the one that MODULE.bazel.lock holds was taken for a
stale lock. A root that pins the ruleset lower with
single_version_override was therefore declined for ever, with a remedy
that could not work, and so was a bazel_dep of three numbers. Now a
single_version_override with a version names the release the lock must
hold, older or newer; versions compare in Bazel's order; and an
override that takes the ruleset from no registry or keeps several
releases of it (archive_override, git_override, local_path_override,
multiple_version_override, a pinned version that is no string) declines
with the line of the override, because the release cannot be known.

Couplings that were held by matching text are gone. The kind of a doubt
(a hub without a lock, a maven.override, something unread) is a value
beside its text, and the hub's name a field: the decline code was
chosen by the wording of the doubt. The pom rewriter asks the verdicts
whether a hub decides a patch before it says "no pom.xml": the hub
lane took that warning back by its code afterwards. And the group, the
artifact and the maven2 override of a Maven patch come from one
function, redirect::maven_coordinates, for the pom rewriter and the
hub lane, where there were three copies.

A new block is written in the line break that utils::line_endings
gives for the file, as the other writers that keep CRLF do: in a file
with both, the more frequent one, where the block had a rule of its
own (CRLF if any). The undo is byte for byte as before, for every file
shape of the unit test.

Not changed: each command reads the hubs of a workspace again, and a
hosted get reads them twice (measured beside a 4.9 MiB lock in a debug
build: about 40 ms per read, nearly all of it the JSON parse of the
lock). Sharing that parse would take process-wide state to save one
parse per run.

The size budget of the bazel group moves from 2149 to 2230 code lines.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
A hosted run that declines for a jar whose entry is already in the block
confirmed the patch and reported it `applied`, whatever the reason of
the decline. For `maven_bazel_no_effect` that is false: an rc file that
switches the block off, or a `maven.override` of the jar, leaves the
entry in MODULE.bazel while the Bazel build takes the upstream jar.

Such a run no longer confirms the patch. Its warning ends "socket-patch
left the entry that MODULE.bazel holds for it as it is, and while that
stands the entry has no effect: the Bazel build keeps the upstream jar".
Every other decline beside the patch's own entry is as it was. The docs
say both endings, and the `bazel` budget follows the four added lines.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
@mikolalysenko
Mikola Lysenko (mikolalysenko) marked this pull request as ready for review November 19, 2026 16:53
@cursor

cursor Bot commented Nov 19, 2026 •

Copy link
Copy Markdown

PR Summary

High Risk
Changes hosted Maven/Bazel integration, MODULE.bazel rewriting, and CI compatibility legs—incorrect hub or rc handling could leave Bazel on upstream jars or break builds silently until checksum failure.

Overview
Hosted mode now patches jars that a pinned rules_jvm_external hub would otherwise take only from maven_install.json, by appending a managed block to the root MODULE.bazel (http_file + override_repo, Bazel ≥7.4.0). Successful runs rewrite MODULE.bazel (and Maven files when present); rollback/remove strip entries byte-for-byte. Discovery, upstream restore, and vex treat the block as hosted wiring.

The hosted engine wires hub analysis into discovery/rewrite (confirmed_bazel_maven_uuids, shared maven_coordinates). Vendored runs no longer “take over” pins that exist only in the block (takeover_pins drops MODULE.bazel). Hosted scan stops duplicating hub warnings via bazel_maven_notices (the hub lane owns declines). bazel/rc.rs gains MODULE.bazel.lock ruleset selection and .bazelrc parsing aligned with Bazel.

New maven_bazel_* warning codes document declines (release, unpinned hub, overrides, rc options, etc.); maven_bazel_hub_unpatched is narrowed to vendored/agent. CI adds Bazel 7.4.0, expands workflow path triggers, and docs/CLI_CONTRACT are updated. E2E and CLI tests cover real Bazel builds, tampered patch hosts, version bumps, and block lifecycle.

Reviewed by Cursor Bugbot for commit b79af8f. Configure here.

@cursor cursor Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Cursor Bugbot has reviewed your changes using high effort and found 1 potential issue.

Fix All in Cursor

❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.

Comment @cursor review or bugbot run to trigger another review on this PR

Reviewed by Cursor Bugbot for commit b79af8f. Configure here.

.extend(module.map(|module| (FILE.to_string(), module)));
let read = serde_json::to_string(&read).expect("a map of strings is JSON");
out.files.insert(SITE_KEY.to_string(), read);
}

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Non-UTF-8 MODULE.bazel treated as missing

Medium Severity

The hosted engine loads MODULE.bazel with read_text(...).ok(), so InvalidData (exist-but-undecodable) looks like a missing file. That path never records undecodable_reads, so the run does not refuse with candidate_file_unreadable and can still pin other Maven files while the Bazel rewrite candidate is unreadable.

Fix in Cursor Fix in Web

Triggered by learned rule: Non-UTF-8 candidates must refuse, never look absent

Reviewed by Cursor Bugbot for commit b79af8f. Configure here.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant