Skip to content

fix: only rewrite whole Windows reserved device names - #2704

Open
Pranav-IIITM wants to merge 7 commits into
buildpacks:mainfrom
Pranav-IIITM:fix-reserved-names-substring
Open

Pranav-IIITM wants to merge 7 commits into
buildpacks:mainfrom
Pranav-IIITM:fix-reserved-names-substring

Conversation

@Pranav-IIITM

Copy link
Copy Markdown
Member

Summary

paths.FilterReservedNames rewrote valid names because it matched the Windows reserved words (aux, com, con, lpt, nul, prn) as substrings, and it ran on every OS. As a result, ordinary names were mangled — including on Linux and macOS, where no names are reserved — which changed the Docker cache volume names users actually asked for.

Before / After

                     before                after
my-company-cache  -> my-c_o_mpany-cache -> my-company-cache
connection-cache  -> c_o_nnection-cache -> connection-cache
config            -> c_o_nfig           -> config
nul   (Windows)   -> n_u_l              -> n_u_l
nul.txt (Windows) -> n_u_l.txt          -> n_u_l.txt
nul   (Linux/mac) -> n_u_l              -> nul   (unchanged)

What changed

  • Skip the transformation entirely on non-Windows platforms — these names are only reserved on Windows.
  • Match the whole base name (the part before the first .), case-insensitively, instead of matching a reserved word anywhere in the string.
  • Use the accurate Windows reserved set: CON, PRN, AUX, NUL, COM1–COM9, LPT1–LPT9. Bare com/lpt are no longer rewritten, since they are not actually reserved.
  • Preserve original casing and any extension, so nul.txt becomes n_u_l.txt.
  • Replace the old test that asserted the substring behavior with cases covering Windows reserved names, Windows ordinary names, and the non-Windows no-op.

Impact

  • Cache volume names now match what the user requested, so they are recognizable in docker volume ls and via scripting.
  • A user-pre-created volume whose name merely contains a reserved word (e.g. my-company-cache) is no longer missed.
  • Ordinary names are no longer needlessly rewritten on Linux and macOS.

Migration note

Existing incorrectly mangled volumes are not renamed automatically. After upgrading, pack may reference a new, correctly named volume while the old mangled volume remains until it is cleaned up manually.

Testing

  • go build ./internal/paths/...
  • go vet ./internal/paths/
  • go test ./internal/paths/... ./pkg/cache/...

Closes #2703

FilterReservedNames matched reserved words (aux, com, con, lpt, nul,
prn) as substrings and ran on every OS, so valid names were mangled
(e.g. "my-company-cache" -> "my-c_o_mpany-cache", "config" ->
"c_o_nfig"), including on Linux and macOS where nothing is reserved.
This changed Docker cache volume names away from what users requested.

Match only the whole base name, case-insensitively, against the actual
Windows reserved set (CON, PRN, AUX, NUL, COM1-COM9, LPT1-LPT9), handle
names with an extension such as "nul.txt", and skip the transformation
entirely on non-Windows platforms.

Signed-off-by: Pranav-IIITM <jogdandpranav2007@gmail.com>
@Pranav-IIITM
Pranav-IIITM requested review from a team as code owners September 28, 2026 14:28
@github-actions github-actions Bot added the type/enhancement Issue that requests a new feature or improvement. label Sep 28, 2026
@github-actions github-actions Bot added this to the 0.41.0 milestone Sep 28, 2026
@Pranav-IIITM

Copy link
Copy Markdown
Member Author

@jjbustamante PTAL at this PR, when you have time !!

@jjbustamante

Copy link
Copy Markdown
Member

@Pranav-IIITM

Thanks for working on this!.

I'd like us to go one step further though: rather than making the matching more precise, let's delete FilterReservedNames and its call sites. Here's the archaeology behind that.

Why it was introduced

When Commit What
Aug 2020 76374db8 "Support windows containers for pack build" FilterReservedNames is born, as part of the WCOW feature
Jul 2022 397c959c "Add support for 'volume' cache format using --cache" the user-supplied cache name branch lands, first time a human-chosen name flows through the filter
Apr 2025 b5bde435 "Removing build workflow for WCOW" the filter's reason to exist disappears
today #2703 someone notices --cache name=my-company-cache becomes my-c_o_mpany-cache

The original concern was real but narrow: with Windows containers, a volume name becomes a directory under the daemon's data root on a Windows host, and Win32 resolves con/nul/aux/prn/com1… to device objects in any directory. So the worry was that the random volume name pack invents (pack-layers- + 10 random lowercase letters) might come out containing a reserved word.

Who it was ever for

pack client daemon needed it?
Linux/macOS Linux no, nothing is reserved on the daemon's filesystem
Windows Linux (Docker Desktop/WSL2 — most Windows users) no, the volume directory lives on a Linux filesystem
Linux/macOS Windows containers yes in principle, and the old code happened to cover it by never gating on OS
Windows Windows containers (WCOW) yes, the only real audience, and gone since Apr 2025

That table is also why I'd avoid the runtime.GOOS gate in the current patch: the volume lives on the daemon, so the client's OS was never the right axis. A Windows client against a Linux daemon would still rewrite nul, and the same --cache name= would resolve to different volumes depending on which machine ran the build.

What I'd like the PR to do

  • Drop FilterReservedNames entirely, along with its four call sites and its tests.
  • Please extend the migration note to cover auto-generated cache volumes too, not just user-specified ones.

**My only concern is that, once we release a new pack version, this change will invalidate old cache volumes, so I'll need to notify end-users about it. **

Happy to help if any of this is awkward to unwind, and thanks again; the investment made this much easier to reason about.

@Pranav-IIITM

Copy link
Copy Markdown
Member Author

Thanks @jjbustamante, that's really helpful context. The history makes it clear that the right fix is to remove the filter rather than refine it, and you're right that the client OS was never the right thing to check, since the volume lives on the daemon.

I'll update the PR to:

  • Remove FilterReservedNames entirely, along with its four call sites (pack-layers-* / pack-app-* in lifecycle_execution.go and both branches in volume_cache.go) and its tests.
  • Drop the runtime.GOOS gate and the reserved-name set this PR added.
  • Extend the migration note to cover auto-generated cache volumes as well as user-specified ones.

On the cache invalidation concern, I traced which volumes actually change names. The blast radius is fairly small:

Volume Affected? Why
pack-layers-* / pack-app-* No Random name per build, removed when the build ends; never reused
Auto-generated pack-cache-<ref>-<hash>.<suffix> Only if the image's repository path or tag contains aux, com, con, lpt, nul or prn The hash is hex (0-9a-f) so it can never match, and sanitizedRef strips the registry host, so domains like registry.gitlab.com were never affected
User-specified --cache '...;format=volume;name=<name>' Only if <name> contains one of those substrings e.g. my-company-cache was stored as my-c_o_mpany-cache

For affected users the result is a single cold build: pack creates a new, correctly named volume and the build works normally. The old mangled volume is left behind until removed. No data is lost and no build fails.

Here's a draft for the release notes, if it's useful:

Cache volume names are no longer rewritten. Earlier versions of pack rewrote volume names containing aux, com, con, lpt, nul or prn (e.g. my-company-cache became my-c_o_mpany-cache). This applied to user-specified cache volumes and to auto-generated cache volumes for images whose repository path or tag contains one of those strings. pack now uses the name exactly as given, so affected projects will run one build without a warm cache. Old volumes can be found with docker volume ls --filter name=_ and removed with docker volume rm <name>.

I'll push the changes shortly. Thanks again for the review!

FilterReservedNames was introduced for Windows containers, where a
volume name becomes a directory on a Windows daemon host. The WCOW build
workflow has since been removed, so the rewrite no longer protects any
supported setup, while it still mangles user-chosen and auto-generated
cache volume names (e.g. "my-company-cache" -> "my-c_o_mpany-cache").

Remove the function, its call sites and its tests so volume names are
used exactly as given.

Signed-off-by: Pranav-IIITM <jogdandpranav2007@gmail.com>
@Pranav-IIITM
Pranav-IIITM force-pushed the fix-reserved-names-substring branch from e2ea339 to cd0574b Compare October 19, 2026 15:02
Signed-off-by: Pranav-IIITM <jogdandpranav2007@gmail.com>
@Pranav-IIITM

Copy link
Copy Markdown
Member Author

The latest CI failures look unrelated to this change. When you have a moment, could you re-run the failed jobs?

  • test (windows): all unit tests pass. Only the coverage upload step fails, because Chocolatey returned 503 Service Unavailable while installing codecov.
  • acceptance-combo: Docker Hub returned 502 Bad Gateway while pulling buildpacksio/lifecycle:0.21.24. The other combos were cancelled when that job failed.

Thanks!

@jjbustamante

Copy link
Copy Markdown
Member

@Pranav-IIITM

Looks like the problem is on this test on Windows:

=== RUN   TestBuild/build/#Build/Buildpacks_option/buildpacks_include_URIs/buildpack_is_from_a_registry/all_buildpacks_are_added_to_ephemeral_builder
    build_test.go:1798: Expected nil: unlinkat C:\Users\RUNNER~1\AppData\Local\Temp\registry2670797477\bp-1130947187.tar: The process cannot access the file because it is being used by another process.

I wonder if, after removing this function, we still have some edge case on Windows we are missing

@jjbustamante

Copy link
Copy Markdown
Member

@Pranav-IIITM

Looks like the problem is on this test on Windows:

=== RUN   TestBuild/build/#Build/Buildpacks_option/buildpacks_include_URIs/buildpack_is_from_a_registry/all_buildpacks_are_added_to_ephemeral_builder
    build_test.go:1798: Expected nil: unlinkat C:\Users\RUNNER~1\AppData\Local\Temp\registry2670797477\bp-1130947187.tar: The process cannot access the file because it is being used by another process.

I wonder if, after removing this function, we still have some edge case on Windows we are missing

@Pranav-IIITM actually, it is a flaky test. I saw the same error in another PR I was working on, and I didn't touch any Go code. I will try to fix it

@Pranav-IIITM

Copy link
Copy Markdown
Member Author

Thanks for confirming @jjbustamante! I also found the same failure on an unrelated branch back in August (run 31387831260), so it does look like a pre-existing flake. My guess is a layer reader that isn't always closed before the test's os.RemoveAll cleanup runs, which only Windows complains about. Happy to help with the fix if useful. Let me know if anything else is needed on this PR.

jjbustamante and others added 3 commits October 21, 2026 12:33
Signed-off-by: Juan Bustamante <bustamantejj@gmail.com>
The merge left the container import mis-indented and kept the paths
import, which is unused now that FilterReservedNames is gone.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Juan Bustamante <bustamantejj@gmail.com>
@jjbustamante jjbustamante added type/bug Issue that reports an unexpected behaviour. and removed type/enhancement Issue that requests a new feature or improvement. labels Nov 15, 2026

This branch has not been deployed

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

Labels

type/bug Issue that reports an unexpected behaviour.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Bug: Cache volume names are mangled

2 participants