bufplugin

package
v1.50.0 Latest Latest
Warning

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

 Go to latest Published: Jan 17, 2025 License: Apache-2.0 Imports: 18 Imported by: 10

Documentation

Index

Constants

View Source 
const (
	// PluginVisibilityPublic says the Plugin is public on the registry.
	PluginVisibilityPublic = iota + 1
	// PluginVisibilityPublic says the Plugin is private on the registry.
	PluginVisibilityPrivate
)
View Source 
const (
	// PluginTypeCheck says the Plugin is a check plugin.
	PluginTypeCheck = iota + 1
)

Variables

View Source 
var (
	// AllDigestTypes are all known DigestTypes.
	AllDigestTypes = []DigestType{
		DigestTypeP1,
	}
)
View Source 
var (
	// AllPluginTypeStrings is all format strings without aliases.
	//
	// Sorted in the order we want to display them.
	AllPluginTypeStrings = []string{
		"check",
	}
)

Functions

func DigestEqual added in v1.47.0 

func DigestEqual(a Digest, b Digest) bool

DigestEqual returns true if the given Digests are considered equal.

If both Digests are nil, this returns true.

This checks both the DigestType and Digest value.

Types

type Commit added in v1.47.0 

type Commit interface {
	// PluginKey returns the PluginKey for the Commit.
	PluginKey() PluginKey
	// CreateTime returns the time the Commit was created on the BSR.
	CreateTime() (time.Time, error)
	// contains filtered or unexported methods
}

Commit represents a Commit for a Plugin on the BSR.

func NewCommit added in v1.47.0 

func NewCommit(
	pluginKey PluginKey,
	getCreateTime func() (time.Time, error),
) Commit

NewCommit returns a new Commit.

type Digest added in v1.47.0 

type Digest interface {
	// String() prints typeString:hexValue.
	fmt.Stringer

	// Type returns the type of digest.
	//
	// Always a valid value.
	Type() DigestType
	// Value returns the digest value.
	//
	// Always non-empty.
	Value() []byte
	// contains filtered or unexported methods
}

Digest is a digest of some content.

It consists of a DigestType and a digest value.

func NewDigest added in v1.47.0 

func NewDigest(digestType DigestType, bufcasDigest bufcas.Digest) (Digest, error)

NewDigest creates a new Digest.

func ParseDigest added in v1.47.0 

func ParseDigest(s string) (Digest, error)

ParseDigest parses a Digest from its string representation.

A Digest string is of the form typeString:hexValue. The string is expected to be non-empty, If not, an error is returned.

This reverses Digest.String().

Returns an error of type *bufparse.ParseError if the string could not be parsed.

type DigestMismatchError added in v1.47.0 

type DigestMismatchError struct {
	FullName       bufparse.FullName
	CommitID       uuid.UUID
	ExpectedDigest Digest
	ActualDigest   Digest
}

DigestMismatchError is the error returned if the Digest of a downloaded Plugin or Commit does not match the expected digest in a buf.lock file.

func (*DigestMismatchError) Error added in v1.47.0 

func (m *DigestMismatchError) Error() string

Error implements the error interface.

type DigestType added in v1.47.0 

type DigestType int

DigestType is a type of digest. 

const (
	// DigestTypeP1 represents the p1 plugin digest type.
	//
	// The string value of this is "p1".
	DigestTypeP1 DigestType = iota + 1
)

func ParseDigestType added in v1.47.0 

func ParseDigestType(s string) (DigestType, error)

ParseDigestType parses a DigestType from its string representation.

This reverses DigestType.String().

Returns an error of type *bufparse.ParseError if the string could not be parsed.

func UniqueDigestTypeForPluginKeys added in v1.48.0 

func UniqueDigestTypeForPluginKeys(pluginKeys []PluginKey) (DigestType, error)

UniqueDigestTypeForPluginKeys returns the unique DigestType for the given PluginKeys.

If the PluginKeys have different DigestTypes, an error is returned. If the PluginKeys slice is empty, an error is returned.

func (DigestType) String added in v1.47.0 

func (d DigestType) String() string

String prints the string representation of the DigestType.

type Plugin added in v1.7.0 

type Plugin interface {
	// OpaqueID returns an unstructured ID that can uniquely identify a Plugin
	// relative to the Workspace.
	//
	// An OpaqueID's structure should not be relied upon, and is not a
	// globally-unique identifier. It's uniqueness property only applies to
	// the lifetime of the Plugin, and only within the Workspace the Plugin
	// is defined in.
	//
	// If two Plugins have the same Name and Args, they will have the same OpaqueID.
	OpaqueID() string
	// Name returns the name of the Plugin.
	//  - For local Plugins, this is the path to the executable binary.
	//  - For local Wasm Plugins, this is the path to the Wasm binary.
	//  - For remote Plugins, this is the FullName of the Plugin in the form
	//    remote/owner/name.
	//
	// This is never empty.
	Name() string
	// Args returns the arguments to invoke the Plugin.
	//
	// May be nil.
	Args() []string
	// FullName returns the full name of the Plugin.
	//
	// May be nil. Callers should not rely on this value being present.
	// However, this is always present for remote Plugins.
	//
	// Use OpaqueID as an always-present identifier.
	FullName() bufparse.FullName
	// CommitID returns the BSR ID of the Commit.
	//
	// It is up to the caller to convert this to a dashless ID when necessary.
	//
	// May be empty, that is CommitID() == uuid.Nil may be true.
	// Callers should not rely on this value being present.
	//
	// If FullName is nil, this will always be empty.
	CommitID() uuid.UUID
	// Description returns a human-readable description of the Plugin.
	//
	// This is used to construct descriptive error messages pointing to configured plugins.
	//
	// This will never be empty. If a description was not explicitly set, this falls back to
	// OpaqueID.
	Description() string
	// Digest returns the Plugin digest for the given DigestType.
	//
	// Note this is *not* a bufcas.Digest - this is a Digest.
	// bufcas.Digests are a lower-level type that just deal in terms of
	// files and content. A Digest is a specific algorithm applied to the
	// content of a Plugin.
	//
	// Will return an error if the Plugin is not a Wasm Plugin.
	Digest(DigestType) (Digest, error)
	// Data returns the bytes of the Plugin as a Wasm module.
	//
	// This is the raw bytes of the Wasm module in an uncompressed form.
	//
	// Will return an error if the Plugin is not a Wasm Plugin.
	Data() ([]byte, error)
	// IsWasm returns true if the Plugin is a Wasm Plugin.
	//
	// Plugins are either Wasm or local.
	//
	// A Wasm Plugin is a Plugin that is a Wasm module. Wasm Plugins are invoked
	// with the wasm.Runtime. The Plugin will have Data and will be able to
	// calculate Digests.
	//
	// Wasm Plugins will always have Data.
	IsWasm() bool
	// IsLocal returns true if the Plugin is a local Plugin.
	//
	// Plugins are either local or remote.
	//
	// A local Plugin is one that is built from sources from the "local context",
	// such as a Workspace. Local Plugins are important for understanding what Plugins
	// to push.
	//
	// Remote Plugins will always have FullNames.
	IsLocal() bool
	// contains filtered or unexported methods
}

Plugin presents a BSR plugin.

func NewLocalWasmPlugin added in v1.48.0 

func NewLocalWasmPlugin(
	pluginFullName bufparse.FullName,
	args []string,
	getData func() ([]byte, error),
) (Plugin, error)

NewLocalWasmPlugin returns a new Plugin for a local Wasm plugin.

type PluginData added in v1.47.0 

type PluginData interface {
	// PluginKey used to download this PluginData.
	//
	// The Digest from this PluginKey is used for tamper-proofing. It will be checked
	// against the actual data downloaded before Data() returns.
	PluginKey() PluginKey
	// Data returns the bytes of the Plugin as a Wasm module.
	//
	// This is the raw bytes of the Wasm module in an uncompressed form.
	Data() ([]byte, error)
	// contains filtered or unexported methods
}

PluginData presents the raw Plugin data read by PluginKey.

A PluginData generally represents the data on a Plugin read from the BSR API or a cache.

Tamper-proofing is done as part of every function.

func NewPluginData added in v1.47.0 

func NewPluginData(
	ctx context.Context,
	pluginKey PluginKey,
	getData func() ([]byte, error),
) (PluginData, error)

NewPluginData returns a new PluginData.

getData is expected to be lazily-loaded function where possible.

type PluginDataProvider added in v1.47.0 

type PluginDataProvider interface {
	// GetPluginDatasForPluginKeys gets the PluginDatas for the PluginKeys.
	//
	// Returned PluginDatas will be in the same order as the input PluginKeys.
	//
	// The input PluginKeys are expected to be unique by FullName. The implementation
	// may error if this is not the case.
	//
	// The input PluginKeys are expected to have the same DigestType. The implementation
	// may error if this is not the case.
	//
	// If there is no error, the length of the PluginDatas returned will match the length of the PluginKeys.
	// If there is an error, no PluginDatas will be returned.
	// If any PluginKey is not found, an error with fs.ErrNotExist will be returned.
	GetPluginDatasForPluginKeys(
		context.Context,
		[]PluginKey,
	) ([]PluginData, error)
}

PluginDataProvider provides PluginsDatas. 

var (
	// NopPluginDataProvider is a no-op PluginDataProvider.
	NopPluginDataProvider PluginDataProvider = nopPluginDataProvider{}
)

type PluginKey added in v1.47.0 

type PluginKey interface {
	// String returns "registry/owner/name:dashlessCommitID".
	fmt.Stringer

	// FullName returns the full name of the Plugin.
	//
	// Always present.
	FullName() bufparse.FullName
	// CommitID returns the ID of the Commit.
	//
	// It is up to the caller to convert this to a dashless ID when necessary.
	//
	// Always present, that is CommitID() == uuid.Nil will always be false.
	CommitID() uuid.UUID
	// Digest returns the Plugin digest.
	//
	// Note this is *not* a bufcas.Digest - this is a Digest.
	// bufcas.Digests are a lower-level type that just deal in terms of
	// files and content. A PluginDigest is a specific algorithm applied to
	// the Plugin data.
	Digest() (Digest, error)
	// contains filtered or unexported methods
}

PluginKey provides identifying information for a Plugin.

PluginKeys are returned from PluginKeyProviders, and represent a Plugin's complete identity. They also match to what we store in buf.lock files. PluginKeys can be used to get Plugins via a PluginProvider.

func NewPluginKey added in v1.47.0 

func NewPluginKey(
	pluginFullName bufparse.FullName,
	commitID uuid.UUID,
	getDigest func() (Digest, error),
) (PluginKey, error)

NewPluginKey returns a new PluginKey.

The Digest will be loaded lazily if needed. Note this means that NewPluginKey does *not* validate the digest. If you need to validate the digest, call Digest() and evaluate the returned error.

type PluginKeyProvider added in v1.47.0 

type PluginKeyProvider interface {
	// GetPluginKeysForPluginRefs gets the PluginKets for the given PluginRefs.
	//
	// Returned PluginKeys will be in the same order as the input PluginRefs.
	//
	// The input PluginRefs are expected to be unique by FullName. The implementation
	// may error if this is not the case.
	//
	// If there is no error, the length of the PluginKeys returned will match the length of the Refs.
	// If there is an error, no PluginKeys will be returned.
	// If any PluginRef is not found, an error with fs.ErrNotExist will be returned.
	GetPluginKeysForPluginRefs(context.Context, []bufparse.Ref, DigestType) ([]PluginKey, error)
}

PluginKeyProvider provides PluginKeys for bufparse.Refs. 

var (
	// NopPluginKeyProvider is a no-op PluginKeyProvider.
	NopPluginKeyProvider PluginKeyProvider = nopPluginKeyProvider{}
)

func NewStaticPluginKeyProvider added in v1.48.0 

func NewStaticPluginKeyProvider(pluginKeys []PluginKey) (PluginKeyProvider, error)

NewStaticPluginKeyProvider returns a new PluginKeyProvider for a static set of PluginKeys.

The set of PluginKeys must be unique by FullName. If there are duplicates, an error will be returned.

When resolving Refs, the Ref will be matched to the PluginKey by FullName. If the Ref is not found in the set of provided keys, an fs.ErrNotExist will be returned.

type PluginType added in v1.48.0 

type PluginType int

PluginType is the type of a Plugin.

func ParsePluginType added in v1.48.0 

func ParsePluginType(s string) (PluginType, error)

ParsePluginType parses the PluginType from the string.

type PluginVisibility added in v1.48.0 

type PluginVisibility int

PluginVisibility is the visibility of a Plugin on a registry.

Only used for Upload for now.

func ParsePluginVisibility added in v1.48.0 

func ParsePluginVisibility(s string) (PluginVisibility, error)

ParsePluginVisibility parses the PluginVisibility from the string.

type UploadOption added in v1.48.0 

type UploadOption func(*uploadOptions)

UploadOption is an option for an Upload.

func UploadWithCreateIfNotExist added in v1.48.0 

func UploadWithCreateIfNotExist(createPluginVisibility PluginVisibility, createPluginType PluginType) UploadOption

UploadWithCreateIfNotExist returns a new UploadOption that will result in the Plugins being created on the registry with the given visibility if they do not exist.

func UploadWithLabels added in v1.48.0 

func UploadWithLabels(labels ...string) UploadOption

UploadWithLabels returns a new UploadOption that adds the given labels.

This can be called multiple times. The unique result set of labels will be used.

func UploadWithSourceControlURL added in v1.48.0 

func UploadWithSourceControlURL(sourceControlURL string) UploadOption

UploadWithSourceControlURL returns a new UploadOption that will set the source control url for the plugin contents uploaded.

type UploadOptions added in v1.48.0 

type UploadOptions interface {
	// Labels returns the unique and sorted set of labels to add. Labels
	// are set using the `--label` flag when calling `buf plugin upload`
	// and represent the labels that are set when uploading plugin data.
	Labels() []string
	// CreateIfNotExist says to create Plugins if they do not exist on the registry.
	CreateIfNotExist() bool
	// CreatePluginVisibility returns the visibility to create Plugins with.
	//
	// Will always be present if CreateIfNotExist() is true.
	CreatePluginVisibility() PluginVisibility
	// CreatePluginType returns the type to create Plugins with.
	//
	// Will always be present if CreateIfNotExist() is true.
	CreatePluginType() PluginType
	// SourceControlURL returns the source control URL set by the user for the plugin
	// contents uploaded. We set the same source control URL for all plugin contents.
	SourceControlURL() string
	// contains filtered or unexported methods
}

UploadOptions are the possible options for upload.

This is used by Uploader implementations.

func NewUploadOptions added in v1.48.0 

func NewUploadOptions(options []UploadOption) (UploadOptions, error)

NewUploadOptions returns a new UploadOptions.

type Uploader added in v1.48.0 

type Uploader interface {
	// Upload uploads the given Plugins.
	Upload(ctx context.Context, plugins []Plugin, options ...UploadOption) ([]Commit, error)
}

Uploader uploads Plugins. 

var (
	// NopUploader is a no-op Uploader.
	NopUploader Uploader = nopUploader{}
)

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.