bufmodule

Documentation

Index

• Constants
• func ModuleDigestB3(ctx context.Context, module Module) (string, error)
• func ModuleToBucket(ctx context.Context, module Module, writeBucket storage.WriteBucket) error
• func ModuleToProtoModule(ctx context.Context, module Module) (*modulev1alpha1.Module, error)
• func TargetModuleFilesToBucket(ctx context.Context, module Module, writeBucket storage.WriteBucket) error
• func ValidateProtoModule(protoModule *modulev1alpha1.Module) error
• type Module
  • func ModuleWithExcludePaths(module Module, excludePaths []string) (Module, error)
  • func ModuleWithExcludePathsAllowNotExist(module Module, excludePaths []string) (Module, error)
  • func ModuleWithTargetPaths(module Module, targetPaths []string, excludePaths []string) (Module, error)
  • func ModuleWithTargetPathsAllowNotExist(module Module, targetPaths []string, excludePaths []string) (Module, error)
  • func NewModuleForBucket(ctx context.Context, readBucket storage.ReadBucket, options ...ModuleOption) (Module, error)
  • func NewModuleForProto(ctx context.Context, protoModule *modulev1alpha1.Module, ...) (Module, error)
• type ModuleFile
• type ModuleFileSet
  • func NewModuleFileSet(module Module, dependencies []Module) ModuleFileSet
• type ModuleOption
  • func ModuleWithModuleIdentity(moduleIdentity bufmoduleref.ModuleIdentity) ModuleOption
  • func ModuleWithModuleIdentityAndCommit(moduleIdentity bufmoduleref.ModuleIdentity, commit string) ModuleOption
• type ModuleReader
  • func NewNopModuleReader() ModuleReader
• type ModuleResolver
  • func NewNopModuleResolver() ModuleResolver
• type Workspace
  • func NewWorkspace(namedModules map[string]Module, allModules []Module) Workspace

Constants

const (
	// DocumentationFilePath defines the path to the documentation file, relative to the root of the module.
	DocumentationFilePath = "buf.md"
)

Functions

func ModuleDigestB3

func ModuleDigestB3(ctx context.Context, module Module) (string, error)

ModuleDigestB3 returns the b3 digest for the Module.

To create the module digest (SHA256):

1. For every file in the module (sorted lexicographically by path): a. Add the file path b. Add the file contents
2. Add the dependency's module identity and commit ID (sorted lexicographically by commit ID)
3. Add the module identity if available.
4. Add the module documentation if available.
5. Add the breaking and lint configurations if available.
6. Produce the final digest by URL-base64 encoding the summed bytes and prefixing it with the digest prefix

func ModuleToBucket

func ModuleToBucket(
	ctx context.Context,
	module Module,
	writeBucket storage.WriteBucket,
) error

ModuleToBucket writes the given Module to the WriteBucket.

This writes the sources and the buf.lock file. This copies external paths if the WriteBucket supports setting of external paths.

func ModuleToProtoModule

func ModuleToProtoModule(ctx context.Context, module Module) (*modulev1alpha1.Module, error)

ModuleToProtoModule converts the Module to a proto Module.

This takes all Sources and puts them in the Module, not just Targets.

func TargetModuleFilesToBucket

func TargetModuleFilesToBucket(
	ctx context.Context,
	module Module,
	writeBucket storage.WriteBucket,
) error

TargetModuleFilesToBucket writes the target files of the given Module to the WriteBucket.

This does not write the buf.lock file. This copies external paths if the WriteBucket supports setting of external paths.

func ValidateProtoModule

func ValidateProtoModule(protoModule *modulev1alpha1.Module) error

ValidateProtoModule verifies the given module is well-formed. It performs client-side validation only, and is limited to fields we do not think will change in the future.

Types

type Module

type Module interface {
	// TargetFileInfos gets all FileInfos specified as target files. This is either
	// all the FileInfos belonging to the module, or those specified by ModuleWithTargetPaths().
	//
	// It does not include dependencies.
	//
	// The returned TargetFileInfos are sorted by path.
	TargetFileInfos(ctx context.Context) ([]bufmoduleref.FileInfo, error)
	// SourceFileInfos gets all FileInfos belonging to the module.
	//
	// It does not include dependencies.
	//
	// The returned SourceFileInfos are sorted by path.
	SourceFileInfos(ctx context.Context) ([]bufmoduleref.FileInfo, error)
	// GetModuleFile gets the source file for the given path.
	//
	// Returns storage.IsNotExist error if the file does not exist.
	GetModuleFile(ctx context.Context, path string) (ModuleFile, error)
	// DependencyModulePins gets the dependency ModulePins.
	//
	// The returned ModulePins are sorted by remote, owner, repository, branch, commit, and then digest.
	// The returned ModulePins are unique by remote, owner, repository.
	//
	// This includes all transitive dependencies.
	DependencyModulePins() []bufmoduleref.ModulePin
	// Documentation gets the contents of the module documentation file, buf.md and returns the string representation.
	// This may return an empty string if the documentation file does not exist.
	Documentation() string
	// BreakingConfig returns the breaking change check configuration set for the module.
	//
	// This may be nil, since older versions of the module would not have this stored.
	BreakingConfig() *bufbreakingconfig.Config
	// LintConfig returns the lint check configuration set for the module.
	//
	// This may be nil, since older versions of the module would not have this stored.
	LintConfig() *buflintconfig.Config
	// contains filtered or unexported methods
}

Module is a Protobuf module.

It contains the files for the sources, and the dependency names.

Terminology:

Targets (Modules and ModuleFileSets):

Just the files specified to build. This will either be sources, or will be specific files
within sources, ie this is a subset of Sources. The difference between Targets and Sources happens
when i.e. the --path flag is used.

Sources (Modules and ModuleFileSets):

The files with no dependencies. This is a superset of Targets and subset of All.

All (ModuleFileSets only):

All files including dependencies. This is a superset of Sources.

func ModuleWithExcludePaths

func ModuleWithExcludePaths(
	module Module,
	excludePaths []string,
) (Module, error)

ModuleWithExcludePaths returns a new Module that excludes specific file or directory paths to build.

Note that this will result in TargetFileInfos containing only the paths that have not been excluded and any imports. Imports are still available via SourceFileInfos.

func ModuleWithExcludePathsAllowNotExist

func ModuleWithExcludePathsAllowNotExist(
	module Module,
	excludePaths []string,
) (Module, error)

ModuleWithExcludePathsAllowNotExist returns a new Module that excludes specific file or directory paths to build, but allows the specified paths to not exist.

Note that this will result in TargetFileInfos containing only these paths, and not any imports. Imports, and non-targeted files, are still available via SourceFileInfos.

func ModuleWithTargetPaths

func ModuleWithTargetPaths(
	module Module,
	targetPaths []string,
	excludePaths []string,
) (Module, error)

ModuleWithTargetPaths returns a new Module that specifies specific file or directory paths to build.

These paths must exist. These paths must be relative to the roots. These paths will be normalized and validated. These paths must be unique when normalized and validated. Multiple calls to this option will override previous calls.

Note that this will result in TargetFileInfos containing only these paths, and not any imports. Imports, and non-targeted files, are still available via SourceFileInfos.

func ModuleWithTargetPathsAllowNotExist

func ModuleWithTargetPathsAllowNotExist(
	module Module,
	targetPaths []string,
	excludePaths []string,
) (Module, error)

ModuleWithTargetPathsAllowNotExist returns a new Module specifies specific file or directory paths to build, but allows the specified paths to not exist.

Note that this will result in TargetFileInfos containing only these paths, and not any imports. Imports, and non-targeted files, are still available via SourceFileInfos.

func NewModuleForBucket

func NewModuleForBucket(
	ctx context.Context,
	readBucket storage.ReadBucket,
	options ...ModuleOption,
) (Module, error)

NewModuleForBucket returns a new Module. It attempts reads dependencies from a lock file in the read bucket.

func NewModuleForProto

func NewModuleForProto(
	ctx context.Context,
	protoModule *modulev1alpha1.Module,
	options ...ModuleOption,
) (Module, error)

NewModuleForProto returns a new Module for the given proto Module.

type ModuleFile

type ModuleFile interface {
	bufmoduleref.FileInfo
	io.ReadCloser
	// contains filtered or unexported methods
}

ModuleFile is a module file.

type ModuleFileSet

type ModuleFileSet interface {
	// Note that GetModuleFile will pull from All files instead of just Source Files!
	Module
	// AllFileInfos gets all FileInfos associated with the module, including dependencies.
	//
	// The returned FileInfos are sorted by path.
	AllFileInfos(ctx context.Context) ([]bufmoduleref.FileInfo, error)
	// contains filtered or unexported methods
}

ModuleFileSet is a Protobuf module file set.

It contains the files for both targets, sources and dependencies.

TODO: we should not have ModuleFileSet inherit from Module, this is confusing

func NewModuleFileSet

func NewModuleFileSet(
	module Module,
	dependencies []Module,
) ModuleFileSet

NewModuleFileSet returns a new ModuleFileSet.

type ModuleOption

type ModuleOption func(*module)

ModuleOption is used to construct Modules.

func ModuleWithModuleIdentity

func ModuleWithModuleIdentity(moduleIdentity bufmoduleref.ModuleIdentity) ModuleOption

ModuleWithModuleIdentity is used to construct a Module with a ModuleIdentity.

func ModuleWithModuleIdentityAndCommit

func ModuleWithModuleIdentityAndCommit(moduleIdentity bufmoduleref.ModuleIdentity, commit string) ModuleOption

ModuleWithModuleIdentityAndCommit is used to construct a Module with a ModuleIdentity and commit.

type ModuleReader

type ModuleReader interface {
	// GetModule gets the Module for the ModulePin.
	//
	// Returns an error that fufills storage.IsNotExist if the Module does not exist.
	GetModule(ctx context.Context, modulePin bufmoduleref.ModulePin) (Module, error)
}

ModuleReader reads resolved modules.

func NewNopModuleReader

func NewNopModuleReader() ModuleReader

NewNopModuleReader returns a new ModuleReader that always returns a storage.IsNotExist error.

type ModuleResolver

type ModuleResolver interface {
	// GetModulePin resolves the provided ModuleReference to a ModulePin.
	//
	// Returns an error that fufills storage.IsNotExist if the named Module does not exist.
	GetModulePin(ctx context.Context, moduleReference bufmoduleref.ModuleReference) (bufmoduleref.ModulePin, error)
}

ModuleResolver resolves modules.

func NewNopModuleResolver

func NewNopModuleResolver() ModuleResolver

NewNopModuleResolver returns a new ModuleResolver that always returns a storage.IsNotExist error.

type Workspace

type Workspace interface {
	// GetModule gets the module identified by the given ModuleIdentity.
	GetModule(moduleIdentity bufmoduleref.ModuleIdentity) (Module, bool)
	// GetModules returns all of the modules found in the workspace.
	GetModules() []Module
}

Workspace represents a module workspace.

func NewWorkspace

func NewWorkspace(
	namedModules map[string]Module,
	allModules []Module,
) Workspace

NewWorkspace returns a new module workspace.