golang/mod

The golang.org/x/mod repository provides packages designed for writing tools that perform direct manipulation of Go module mechanics.

When to use this repository: Use these packages if your tool's primary purpose is to interact with, parse, or modify Go module files and structures (e.g., go.mod files, version selection logic, or module graph structures).

When NOT to use this repository: Do not use this repository if you are building general development tools that simply need to load packages in module mode. For tools where modules are incidental to the task (like static analysis or refactoring), use golang.org/x/tools/go/packages instead. For the most accurate package loading, you should invoke the go command directly, as it is the single source of truth for loading algorithms.

The sumdb.Server type implements the http.Handler interface and serves as the HTTP entry point for a module checksum database. To use it, you must provide an implementation of the ServerOps interface, which handles the actual database access (e.g., looking up records, reading tiles, and retrieving signed hashes).

To set up the server, use sumdb.NewServer(ops) and register it to handle the paths defined in sumdb.ServerPaths.

// Define your implementation of ServerOps
type myOps struct { /* ... */ }
// ... implement Signed, ReadRecords, Lookup, and ReadTileData ...

// Initialize the server
ops := &myOps{}
srv := sumdb.NewServer(ops)

// Register the server for the required paths
for _, path := range sumdb.ServerPaths {
	http.Handle(path, srv)
}

// Start your HTTP server
http.ListenAndServe(":8080", nil)

The Lookup(path, vers string) method returns the go.sum lines for a specific module path and version.

• If vers ends in /go.mod, it returns the hashes for the module's go.mod file.
• If the path matches a pattern set via SetGONOSUMDB, it returns ErrGONOSUMDB.
• The returned []string contains lines in the format: path version hash.

lines, err := client.Lookup("example.com/mod", "v1.0.0")
if err != nil {
	// handle error
}
for _, line := range lines {
	fmt.Println(line)
}

Use SetTileHeight(height int) to define the tile height for the client.

Constraints:

• Must be called before the first call to Lookup.
• Can be called at most once.
• If not called, the client defaults to a tile height of 8.
• Passing a non-positive integer will cause a panic.

client.SetTileHeight(8)

Create a new sumdb.Client by passing an implementation of ClientOps to NewClient. The client is safe for concurrent use by multiple goroutines.

Note that certain configuration methods like SetTileHeight and SetGONOSUMDB must be called before the first call to Lookup.

client := sumdb.NewClient(myOpsImplementation)

Use SetGONOSUMDB(list string) to provide a comma-separated list of module path patterns. If a module path matches one of these patterns, Lookup will return ErrGONOSUMDB instead of querying the database.

Constraints:

• Must be called before the first call to Lookup.
• Can be called at most once.

client.SetGONOSUMDB("example.com/bad-module,github.com/private/*")

The sumdb package defines several specific error variables:

• ErrWriteConflict: Returned by WriteConfig if the old data provided does not match the current configuration.
• ErrSecurity: Returned when the client detects a security violation (e.g., a misbehaving server or inconsistent tree).
• ErrGONOSUMDB: Returned by Lookup when the requested module path matches a pattern in the GONOSUMDB list.

var (
	ErrWriteConflict = errors.New("write conflict")
	ErrSecurity     = errors.New("security error: misbehaving server")
	ErrGONOSUMDB    = errors.New("skipped (listed in GONOSUMDB)")
)

The sumdb.Server is designed to serve specific URL paths. When configuring your HTTP router, you should register the server for all paths listed in sumdb.ServerPaths to ensure full protocol compliance.

var ServerPaths = []string{
	"/lookup/",
	"/latest",
	"/tile/",
}

The gosumcheck command verifies the checksums in a go.sum file against a Go checksum database server.

WARNING: gosumcheck is a proof-of-concept demo. It is not intended for production scripts or continuous integration (CI) testing because it does not cache information, making it expensive and unable to detect certain server misbehaviors or HTTPS man-in-the-middle attacks. Additionally, it does not set an exit status to report problems found, which makes it unsuitable for automated error detection.

To use it, provide one or more go.sum files as arguments.

gosumcheck go.sum