modfs

Documentation

Overview

Package modfs implements an io/fs.FS backed by the Go module proxy protocol. It fetches modules over HTTP on demand and caches them in memory, so no module sources are written to disk. This makes it usable from WASM and other restricted environments.

The filesystem is plugged into goparser.Parser as a third-tier fallback after the user pkgfs and the embedded stdlib source FS, so any import path the parser cannot resolve locally is fetched dynamically.

Index

• Constants
• type FS
  • func New(opts Options) *FS
  • func (f *FS) Inject(modPath, version string, zipBytes []byte) error
  • func (f *FS) NetStats() NetStats
  • func (f *FS) Open(name string) (fs.File, error)
  • func (f *FS) ReadDir(name string) ([]fs.DirEntry, error)
  • func (f *FS) Stat(name string) (fs.FileInfo, error)
• type NetStats
• type Options

Constants

const DefaultProxy = "https://proxy.golang.org"

DefaultProxy is the public Go module proxy.

Types

type FS

type FS struct {
	// contains filtered or unexported fields
}

FS is an in-memory filesystem that resolves Go import paths against a module proxy. It implements fs.FS, fs.StatFS and fs.ReadDirFS.

func New

func New(opts Options) *FS

New returns an FS configured from opts.

func (*FS) Inject

func (f *FS) Inject(modPath, version string, zipBytes []byte) error

Inject installs a pre-fetched module into the in-memory cache. The zipBytes must use the standard Go module proxy layout (entries rooted at "<modPath>@<version>/"). After Inject, lookups under modPath are served from memory without network access. Any prior negative cache entry for modPath itself is cleared so locate() can find it.

func (*FS) NetStats

func (f *FS) NetStats() NetStats

NetStats returns a snapshot of the FS's proxy counters.

func (*FS) Open

func (f *FS) Open(name string) (fs.File, error)

Open implements fs.FS. The name is an import path or a path inside one (e.g. "github.com/foo/bar" or "github.com/foo/bar/sub/file.go").

func (*FS) ReadDir

func (f *FS) ReadDir(name string) ([]fs.DirEntry, error)

ReadDir implements fs.ReadDirFS.

func (*FS) Stat

func (f *FS) Stat(name string) (fs.FileInfo, error)

Stat implements fs.StatFS.

type NetStats

type NetStats struct {
	Requests     int
	BytesFetched int64
	FetchTime    time.Duration
}

NetStats summarizes the network work performed by an FS instance: proxy requests issued (200s and failures), bytes consumed from response bodies, and total wall-clock time spent in proxyGet.

Cache hits, Inject calls, and offline lookups do not contribute -- only real HTTP requests do. Snapshot the counters with FS.NetStats.

type Options

type Options struct {
	// Proxy is the module proxy base URL. Empty means DefaultProxy.
	Proxy string
	// Client is the HTTP client used for proxy requests. Empty means
	// http.DefaultClient.
	Client *http.Client
	// Offline disables proxy fetches. Only modules added via Inject are
	// served; any other lookup returns fs.ErrNotExist. Useful for
	// playground/WASM and GOPROXY=off, where the embedded stdlib zip is the
	// sole source.
	Offline bool
}

Options configures FS construction.