or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

dirhash.mdgosumcheck.mdindex.mdmodfile.mdmodule.mdnote.mdsemver.mdstorage.mdsumdb.mdtlog.mdzip.md
tile.json

tessl/golang-golang-org-x--mod

Go module mechanics library providing tools for direct manipulation of Go modules

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
golangpkg:golang/golang.org/x/mod@v0.30.0

To install, run

npx @tessl/cli install tessl/golang-golang-org-x--mod@0.30.0

index.mddocs/

golang.org/x/mod

Go module mechanics library providing tools for direct manipulation of Go modules.

Package Information

  • Name: golang.org/x/mod
  • Type: Library
  • Language: Go
  • Version: v0.30.0
  • License: BSD-3-Clause

Installation

go get golang.org/x/mod@v0.30.0

Overview

The golang.org/x/mod module provides a comprehensive library for working directly with Go module mechanics. It offers low-level tools for direct manipulation of Go modules themselves, providing the foundational building blocks for Go tooling that operates at the module level.

This library includes functionality for:

  • Module path and version handling - Types, validation, and manipulation of module paths and semantic versions
  • Configuration file parsing - Reading, writing, and editing go.mod and go.work files
  • Semantic versioning - Comparison and manipulation following Semantic Versioning 2.0.0
  • Checksum database - Client and server implementations for Go's checksum database
  • Module distribution - Creating and extracting module zip files
  • Content verification - Directory hashing and cryptographic signatures

Core Imports

import (
    "golang.org/x/mod/module"          // Module path and version types
    "golang.org/x/mod/modfile"         // go.mod and go.work file parsing
    "golang.org/x/mod/semver"          // Semantic version comparison
    "golang.org/x/mod/sumdb"           // Checksum database client/server
    "golang.org/x/mod/sumdb/dirhash"   // Directory hashing
    "golang.org/x/mod/sumdb/note"      // Signed notes
    "golang.org/x/mod/sumdb/storage"   // Storage interfaces
    "golang.org/x/mod/sumdb/tlog"      // Tamper-evident log
    "golang.org/x/mod/zip"             // Module zip creation/extraction
)

Basic Usage

Parsing a go.mod File

package main

import (
    "fmt"
    "os"

    "golang.org/x/mod/modfile"
)

func main() {
    data, err := os.ReadFile("go.mod")
    if err != nil {
        panic(err)
    }

    f, err := modfile.Parse("go.mod", data, nil)
    if err != nil {
        panic(err)
    }

    fmt.Printf("Module: %s\n", f.Module.Mod.Path)
    fmt.Printf("Go version: %s\n", f.Go.Version)

    for _, req := range f.Require {
        fmt.Printf("Require: %s %s\n", req.Mod.Path, req.Mod.Version)
    }
}

Validating Module Paths and Versions

package main

import (
    "fmt"

    "golang.org/x/mod/module"
    "golang.org/x/mod/semver"
)

func main() {
    // Validate a module path
    if err := module.CheckPath("github.com/user/repo"); err != nil {
        fmt.Printf("Invalid path: %v\n", err)
    }

    // Compare semantic versions
    result := semver.Compare("v1.2.3", "v1.2.4")
    if result < 0 {
        fmt.Println("v1.2.3 is less than v1.2.4")
    }

    // Check path/version compatibility
    if err := module.Check("github.com/user/repo/v2", "v2.1.0"); err != nil {
        fmt.Printf("Incompatible: %v\n", err)
    }
}

Package Capabilities

module - Module Path and Version Types

Core types and validation for module paths and versions.

func CheckPath(path string) error
func Check(path, version string) error
func CanonicalVersion(v string) string
func EscapePath(path string) (string, error)

type Version struct {
    Path    string
    Version string
}

Full module API documentation →

modfile - go.mod and go.work File Parsing

Parser and formatter for Go module configuration files.

func Parse(file string, data []byte, fix VersionFixer) (*File, error)
func Format(f *FileSyntax) []byte

type File struct {
    Module  *Module
    Go      *Go
    Require []*Require
    Exclude []*Exclude
    Replace []*Replace
    Retract []*Retract
}

Full modfile API documentation →

semver - Semantic Version Comparison

Semantic version string comparison and manipulation.

func Compare(v, w string) int
func IsValid(v string) bool
func Major(v string) string
func Canonical(v string) string

Full semver API documentation →

sumdb - Checksum Database Client/Server

HTTP protocols for serving or accessing a module checksum database.

func NewClient(ops ClientOps) *Client
func NewServer(ops ServerOps) *Server

type Client struct { /* ... */ }
func (c *Client) Lookup(path, vers string) ([]string, error)

Full sumdb API documentation →

dirhash - Directory Hashing

Directory tree hashing for module content verification.

func HashDir(dir, prefix string, hash Hash) (string, error)
func HashZip(zipfile string, hash Hash) (string, error)
func Hash1(files []string, open func(string) (io.ReadCloser, error)) (string, error)

Full dirhash API documentation →

note - Signed Notes

Cryptographic signatures for Go module database.

func NewSigner(skey string) (Signer, error)
func NewVerifier(vkey string) (Verifier, error)
func Sign(n *Note, signers ...Signer) ([]byte, error)
func Open(msg []byte, known Verifiers) (*Note, error)

Full note API documentation →

storage - Storage Interfaces

Storage interfaces for checksum database implementation.

type Storage interface {
    ReadOnly(ctx context.Context, f func(context.Context, Transaction) error) error
    ReadWrite(ctx context.Context, f func(context.Context, Transaction) error) error
}

type Transaction interface {
    ReadValue(ctx context.Context, key string) (string, error)
    BufferWrites(writes []Write) error
}

Full storage API documentation →

tlog - Tamper-Evident Log

Transparent log implementation compatible with Certificate Transparency (RFC 6962).

func TreeHash(n int64, r HashReader) (Hash, error)
func ProveRecord(t, n int64, r HashReader) (RecordProof, error)
func CheckRecord(p RecordProof, t int64, th Hash, n int64, h Hash) error

type Tile struct {
    H int   // height
    L int   // level
    N int64 // number
    W int   // width
}

Full tlog API documentation →

zip - Module Zip Files

Creating and extracting module zip files following Go's module zip format.

func Create(w io.Writer, m module.Version, files []File) error
func CreateFromDir(w io.Writer, m module.Version, dir string) error
func Unzip(dir string, m module.Version, zipFile string) error
func CheckZip(m module.Version, zipFile string) (CheckedFiles, error)

Full zip API documentation →

gosumcheck - Checksum Verification Command

Command-line utility for verifying go.sum files against a checksum database.

gosumcheck [-h H] [-k key] [-u url] [-v] go.sum

Full gosumcheck documentation →

Use Cases

Building Go Tooling

Use golang.org/x/mod when building tools that need to:

  • Parse or modify go.mod files programmatically
  • Validate module paths and versions
  • Implement custom module proxies or caching
  • Create custom dependency analysis tools
  • Build alternative package managers

Module Verification

Implement checksum verification for:

  • Custom module mirrors
  • Corporate proxy servers
  • Air-gapped environments
  • Supply chain security tools

Version Management

Tools for:

  • Automated dependency updates
  • Version constraint analysis
  • Semver compatibility checking
  • Module compatibility testing

Related Resources

License

BSD-3-Clause