bufmodule

package
v1.0.0-rc9 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Dec 15, 2021 License: Apache-2.0 Imports: 20 Imported by: 49

Documentation

Index

Constants

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

Variables

This section is empty.

Functions

func ModuleDigestB1 

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

ModuleDigestB1 returns the b1 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 hashes (sorted lexicographically by the string representation)
  3. Produce the final digest by URL-base64 encoding the summed bytes and prefixing it with the digest prefix

func ModuleDigestB3 added in v1.0.0 

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 added in v1.0.0 

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 added in v1.0.0 

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 added in v1.0.0 

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

NewWorkspace returns a new module workspace.

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.