Skip to content

Conversation

@pskry
Copy link

@pskry pskry commented Jan 2, 2026

This PR adds support for loading CUE packages and modules from a virtual
filesystem provided via load.Config.FS.

This enables embedding CUE modules in Go binaries and similar use cases where
access to the host filesystem is not desired or not possible.

When Config.FS is set, all filesystem operations performed by the loader
(stat, read, open, directory walking, and encoding reads) are routed through
io/fs.FS instead of the host operating system filesystem. This enables
loading CUE code from sources such as embed.FS, fstest.MapFS, or other
virtual filesystems, without accessing the host filesystem.

The existing behavior is preserved when Config.FS is nil.

Design notes

  • A small internal abstraction (loadFS) centralizes filesystem access and
    normalizes host and virtual filesystem behavior.
  • When loading from a virtual filesystem, paths are interpreted as absolute
    loader paths rooted at a synthetic root (/@fs), avoiding accidental host
    filesystem access.
  • Overlays continue to work and must use absolute loader paths when FS is set.
  • Encoding now receives an injected open function to ensure it does not bypass
    the loader filesystem.

Tests

New tests cover:

  • Loading a module and packages from fstest.MapFS
  • Ensuring the host filesystem is not accessed when FS is set
  • Subdirectory loading via Config.Dir
  • Overlay behavior with a virtual filesystem
  • Ensuring encoding does not fall back to os.Open

No public APIs are removed, and existing behavior is unchanged unless
Config.FS is explicitly set.

This change is intended to support embedding CUE modules in Go binaries and similar use cases.

@pskry pskry requested a review from cueckoo as a code owner January 2, 2026 23:53
@pskry
Copy link
Author

pskry commented Jan 3, 2026

Wow, I am sorry to see this failing on windows. I do not have access to a windows machine, so can't test it locally.
I'm pretty sure, this is caused by "/@fs" shenanigans for the virtual FS root.

I hope someone will review this PR anyways, maybe even give some (much needed) windows insight into pathing there.

@pskry pskry force-pushed the load-fs-support branch 11 times, most recently from 0ddff42 to ef1dbb0 Compare January 3, 2026 13:51
@pskry
Copy link
Author

pskry commented Jan 3, 2026

The Windows CI issues turned out to be path canonicalization problems in the overlay/virtual FS boundary and are now resolved. All tests are green across platforms.

This PR should now be ready for review.

The change is intended to enable a fairly common use case (loading CUE modules from embedded or virtual filesystems) while keeping existing behavior unchanged when Config.FS is nil. I hope this turns out to be useful for others embedding or sandboxing CUE.

Feedback very welcome — especially around the overall approach and any edge cases I may have missed.

Allow the loader to operate on a virtual filesystem supplied via Config.FS.
When FS is set, all filesystem access is routed through io/fs instead of the
host OS filesystem, enabling loading from embed.FS and similar sources.

The default behavior is unchanged when FS is nil.

Signed-off-by: pskry <peter@skrypalle.dk>
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