bufpolicy

package
v1.57.2 Latest Latest
Warning

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

 Go to latest Published: Sep 16, 2025 License: Apache-2.0 Imports: 26 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	// PolicyVisibilityPublic says the Policy is public on the registry.
	PolicyVisibilityPublic = iota + 1
	// PolicyVisibilityPrivate says the Policy is private on the registry.
	PolicyVisibilityPrivate
)

Variables

View Source 
var (
	// AllDigestTypes are all known DigestTypes.
	AllDigestTypes = []DigestType{
		DigestTypeO1,
	}
)

Functions

func DigestEqual 

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.

func MarshalPolicyConfigAsJSON added in v1.56.0 

func MarshalPolicyConfigAsJSON(policyConfig PolicyConfig) ([]byte, error)

MarshalPolicyConfigAsJSON marshals the PolicyConfig to a stable JSON representation.

It is a valid JSON encoding of the type buf.registry.policy.v1beta1.PolicyConfig. This is used to calculate the O1 digest.

Types

type BreakingConfig added in v1.56.0 

type BreakingConfig interface {
	// The list of check rules and/or categories used for the Policy.
	//
	// Sorted.
	UseIDsAndCategories() []string
	// The list of check rules and/or categories to exclude for the Policy.
	//
	// Sorted.
	ExceptIDsAndCategories() []string
	// IgnoreUnstablePackages returns true if unstable packages should be ignored:
	//   - v\d+test.*
	//   - v\d+(alpha|beta)\d*
	//   - v\d+p\d+(alpha|beta)\d*
	IgnoreUnstablePackages() bool
	// DisableBuiltin says to disable the Rules and Categories builtin to the Buf CLI and only
	// use plugins.
	//
	// This will make it as if these rules did not exist.
	DisableBuiltin() bool
	// contains filtered or unexported methods
}

BreakingConfig is the configuration for a Policy Breaking.

func NewBreakingConfig added in v1.56.0 

func NewBreakingConfig(
	use []string,
	except []string,
	ignoreUnstablePackages bool,
	disableBuiltin bool,
) (BreakingConfig, error)

NewBreakingConfig creates a new BreakingConfig.

type Commit 

type Commit interface {
	// PolicyKey returns the PolicyKey for the Commit.
	PolicyKey() PolicyKey
	// 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 Policy on the BSR.

func NewCommit 

func NewCommit(
	policyKey PolicyKey,
	getCreateTime func() (time.Time, error),
) Commit

NewCommit returns a new Commit.

type Digest 

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 

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

NewDigest creates a new Digest.

func ParseDigest 

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 

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

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

func (*DigestMismatchError) Error 

func (m *DigestMismatchError) Error() string

Error implements the error interface.

type DigestType 

type DigestType int

DigestType is a type of digest. 

const (
	// DigestTypeO1 represents the o1 policy digest type.
	//
	// The string value of this is "o1".
	DigestTypeO1 DigestType = iota + 1
)

func ParseDigestType 

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 UniqueDigestTypeForPolicyKeys 

func UniqueDigestTypeForPolicyKeys(policyKeys []PolicyKey) (DigestType, error)

UniqueDigestTypeForPolicyKeys returns the unique DigestType for the given PolicyKeys.

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

func (DigestType) String 

func (d DigestType) String() string

String prints the string representation of the DigestType.

type LintConfig added in v1.56.0 

type LintConfig interface {
	// The list of check rules and/or categories used for the Policy.
	//
	// Sorted.
	UseIDsAndCategories() []string
	// The list of check rules and/or categories to exclude for the Policy.
	//
	// Sorted.
	ExceptIDsAndCategories() []string
	// EnumZeroValueSuffix returns the suffix that controls the behavior of the
	// ENUM_ZERO_VALUE_SUFFIX lint rule. By default, this rule verifies that the zero value of all
	// enums ends in `_UNSPECIFIED`, however, this allows organizations to choose a different
	// suffix.
	EnumZeroValueSuffix() string
	// RPCAllowSameRequestResponse returns true to allow the same message type to be used for a
	// single RPC's request and response type.
	RPCAllowSameRequestResponse() bool
	// RPCAllowGoogleProtobufEmptyRequests returns true to allow RPC requests to be
	// google.protobuf.Empty messages.
	RPCAllowGoogleProtobufEmptyRequests() bool
	// RPCAllowGoogleProtobufEmptyResponses returns true to allow RPC responses to be
	// google.protobuf.Empty messages.
	RPCAllowGoogleProtobufEmptyResponses() bool
	// ServiceSuffix returns the suffix that controls the behavior of the SERVICE_SUFFIX lint rule.
	// By default, this rule verifies that all service names are suffixed with `Service`, however
	// this allows organizations to choose a different suffix.
	ServiceSuffix() string
	// DisableBuiltin says to disable the Rules and Categories builtin to the Buf CLI and only
	// use plugins.
	//
	// This will make it as if these rules did not exist.
	DisableBuiltin() bool
	// contains filtered or unexported methods
}

LintConfig is the configuration for a Policy Lint.

func NewLintConfig added in v1.56.0 

func NewLintConfig(
	use []string,
	except []string,
	enumZeroValueSuffix string,
	rpcAllowSameRequestResponse bool,
	rpcAllowGoogleProtobufEmptyRequests bool,
	rpcAllowGoogleProtobufEmptyResponses bool,
	serviceSuffix string,
	disableBuiltin bool,
) (LintConfig, error)

NewLintConfig creates a new LintConfig.

type PluginConfig added in v1.56.0 

type PluginConfig interface {
	// Name returns the name of the plugin.
	Name() string
	// Ref returns the reference to the plugin, may be nil.
	Ref() bufparse.Ref
	// Options returns the options for the plugin, which may be empty.
	Options() option.Options
	// Args returns the arguments for the plugin, which may be empty.
	Args() []string
	// contains filtered or unexported methods
}

PluginConfig is a configuration for a Policy Plugin.

func NewPluginConfig added in v1.56.0 

func NewPluginConfig(
	name string,
	ref bufparse.Ref,
	options option.Options,
	args []string,
) (PluginConfig, error)

NewPluginConfig creates a new PluginConfig.

type Policy 

type Policy interface {
	// OpaqueID returns an unstructured ID that can uniquely identify a Policy
	// 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 Policy, and only within the Workspace the Policy
	// is defined in.
	//
	// If two Policies have the same Name, they will have the same OpaqueID.
	OpaqueID() string
	// Name returns the name of the Policy.
	//  - For local Policies, this is the path to the policy yaml file.
	//  - For remote Policies, this is the FullName of the Policy in the form
	//    remote/owner/name.
	//
	// This is never empty.
	Name() string
	// FullName returns the full name of the Policy.
	//
	// May be nil. Callers should not rely on this value being present.
	// However, this is always present for remote Policies.
	//
	// 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 Policy.
	//
	// This is used to construct descriptive error messages pointing to configured policies.
	//
	// This will never be empty. If a description was not explicitly set, this falls back to
	// OpaqueID.
	Description() string
	// Digest returns the Policy digest for the given DigestType.
	Digest(DigestType) (Digest, error)
	// Config returns the PolicyConfig for the Policy.
	Config() (PolicyConfig, error)
	// IsLocal return true if the Policy is a local Policy.
	//
	// Policies are either local or remote.
	//
	// A local Policy is one which was contained in the local context.
	//
	// A remote Policy is one which was not contained in the local context,
	// and is a remote reference to a Policy.
	//
	// Remote Policies will always have FullNames.
	IsLocal() bool
	// contains filtered or unexported methods
}

Policy presents a BSR policy.

func NewPolicy 

func NewPolicy(
	description string,
	fullName bufparse.FullName,
	name string,
	commitID uuid.UUID,
	getConfig func() (PolicyConfig, error),
) (Policy, error)

NewPolicy creates a new Policy.

type PolicyConfig added in v1.56.0 

type PolicyConfig interface {
	// LintConfig returns the LintConfig for the Policy.
	LintConfig() LintConfig
	// BreakingConfig returns the BreakingConfig for the Policy.
	BreakingConfig() BreakingConfig
	// PluginConfigs returns an iterator over PluginConfig for the Policy.
	//
	// Sorted by plugin name.
	PluginConfigs() []PluginConfig
	// contains filtered or unexported methods
}

PolicyConfig is the configuration for a Policy.

func NewPolicyConfig added in v1.56.0 

func NewPolicyConfig(
	lintConfig LintConfig,
	breakingConfig BreakingConfig,
	pluginConfigs []PluginConfig,
) (PolicyConfig, error)

NewPolicyConfig creates a new PolicyConfig.

func UnmarshalJSONPolicyConfig added in v1.56.0 

func UnmarshalJSONPolicyConfig(registry string, data []byte) (PolicyConfig, error)

UnmarshalJSONPolicyConfig unmarshals the given JSON data into a PolicyConfig.

Data is a valid JSON encoding of the type buf.registry.policy.v1beta1.PolicyConfig.

type PolicyData 

type PolicyData interface {
	// PolicyKey used to download this PolicyData.
	//
	// The Digest from this PolicyKey is used for tamper-proofing. It will be checked
	// against the actual data downloaded before Data() returns.
	PolicyKey() PolicyKey
	// Config returns the PolicyConfig for the Policy.
	Config() (PolicyConfig, error)
	// contains filtered or unexported methods
}

PolicyData presents the raw Policy data read by PolicyKey.

A PolicyData generally represents the data on a Policy read from the BSR API or a cache.

Tamper-proofing is done as part of every function.

func NewPolicyData 

func NewPolicyData(
	ctx context.Context,
	policyKey PolicyKey,
	getConfig func() (PolicyConfig, error),
) (PolicyData, error)

NewPolicyData returns a new PolicyData.

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

type PolicyDataProvider 

type PolicyDataProvider interface {
	// GetPolicyDatasForPolicyKeys gets the PolicyDatas for the PolicyKeys.
	//
	// Returned PolicyDatas will be in the same order as the input PolicyKeys.
	//
	// The input PolicyKeys are expected to be unique by FullName. The implementation
	// may error if this is not the case.
	//
	// The input PolicyKeys 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 PolicyDatas returned will match the length of the PolicyKeys.
	// If there is an error, no PolicyDatas will be returned.
	// If any PolicyKey is not found, an error with fs.ErrNotExist will be returned.
	GetPolicyDatasForPolicyKeys(context.Context, []PolicyKey) ([]PolicyData, error)
}

PolicyDataProvider provides PolicyDatas. 

var (
	// NopPolicyDataProvider is a no-op PolicyDataProvider.
	NopPolicyDataProvider PolicyDataProvider = nopPolicyDataProvider{}
)

type PolicyKey 

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

	// FullName returns the full name of the Policy.
	//
	// 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 Policy digest.
	Digest() (Digest, error)
	// contains filtered or unexported methods
}

PolicyKey provides identifying information for a Policy.

PolicyKeys are returned from PolicyKeyProviders, and represent a Policy's complete identity. They also match to what we store in buf.lock files. PolicyKeys can be used to get Policies via a PolicyProvider.

func NewPolicyKey 

func NewPolicyKey(
	policyFullName bufparse.FullName,
	commitID uuid.UUID,
	getDigest func() (Digest, error),
) (PolicyKey, error)

NewPolicyKey returns a new PolicyKey.

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

type PolicyKeyProvider 

type PolicyKeyProvider interface {
	// GetPolicyKeysForPolicyRefs gets the PolicyKets for the given PolicyRefs.
	//
	// Returned PolicyKeys will be in the same order as the input PolicyRefs.
	//
	// The input PolicyRefs 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 PolicyKeys returned will match the length of the Refs.
	// If there is an error, no PolicyKeys will be returned.
	// If any PolicyRef is not found, an error with fs.ErrNotExist will be returned.
	GetPolicyKeysForPolicyRefs(context.Context, []bufparse.Ref, DigestType) ([]PolicyKey, error)
}

PolicyKeyProvider provides PolicyKeys for bufparse.Refs. 

var (
	// NopPolicyKeyProvider is a no-op PolicyKeyProvider.
	NopPolicyKeyProvider PolicyKeyProvider = nopPolicyKeyProvider{}
)

func NewStaticPolicyKeyProvider 

func NewStaticPolicyKeyProvider(policyKeys []PolicyKey) (PolicyKeyProvider, error)

NewStaticPolicyKeyProvider returns a new PolicyKeyProvider for a static set of PolicyKeys.

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

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

type PolicyPluginDataProvider added in v1.56.0 

type PolicyPluginDataProvider interface {
	// GetPluginDataProviderForPolicy returns the PluginDataProvider for the given policy name.
	//
	// The PluginDataProvider returned will be used to resolve the PluginData for the given policy.
	// If the Policy is not found a bufplugin.NopPluginDataProvider will be returned.
	GetPluginDataProviderForPolicy(policyName string) bufplugin.PluginDataProvider
}

PolicyPluginDataProvider provides PluginData for a specific Policy. 

var (
	// NopPolicyPluginDataProvider is a no-op PolicyDataProvider.
	NopPolicyPluginDataProvider PolicyPluginDataProvider = nopPolicyPluginDataProvider{}
)

func NewStaticPolicyPluginDataProvider added in v1.56.0 

func NewStaticPolicyPluginDataProvider(policyNameToPluginDataProvider map[string]bufplugin.PluginDataProvider) (PolicyPluginDataProvider, error)

NewStaticPolicyPluginDataProvider returns a new PolicyPluginDataProvider for a static set of PolicyNames to PluginData.

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

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

type PolicyPluginKeyProvider added in v1.56.0 

type PolicyPluginKeyProvider interface {
	// GetPluginKeyProviderForPolicy returns the PluginKeyProvider for the given policy name.
	//
	// The PluginKeyProvider returned will be used to resolve the PluginKeys for the given policy.
	// If the Policy is not found a bufplugin.NopPluginKeyProvider will be returned.
	GetPluginKeyProviderForPolicy(policyName string) bufplugin.PluginKeyProvider
}

PolicyPluginKeyProvider provides PluginKeys for a specific Policy. 

var (
	// NopPolicyPluginKeyProvider is a no-op PolicyPluginKeyProvider.
	NopPolicyPluginKeyProvider PolicyPluginKeyProvider = nopPolicyPluginKeyProvider{}
)

func NewStaticPolicyPluginKeyProvider added in v1.56.0 

func NewStaticPolicyPluginKeyProvider(policyNameToPluginKeys map[string][]bufplugin.PluginKey) (PolicyPluginKeyProvider, error)

NewStaticPolicyPluginKeyProvider returns a new PolicyPluginKeyProvider for a static set of PolicyNames to PluginKeys.

Each 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 PolicyPluginKey by FullName. If the Ref is not found in the set of provided keys, an fs.ErrNotExist will be returned.

type PolicyVisibility 

type PolicyVisibility int

PolicyVisibility is the visibility of a Policy on a registry.

Only used for Upload for now.

func ParsePolicyVisibility 

func ParsePolicyVisibility(s string) (PolicyVisibility, error)

ParsePolicyVisibility parses the PolicyVisibility from the string.

type UploadOption 

type UploadOption func(*uploadOptions)

UploadOption is an option for an Upload.

func UploadWithCreateIfNotExist 

func UploadWithCreateIfNotExist(createPolicyVisibility PolicyVisibility) UploadOption

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

func UploadWithLabels 

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 

func UploadWithSourceControlURL(sourceControlURL string) UploadOption

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

type UploadOptions 

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

UploadOptions are the possible options for upload.

This is used by Uploader implementations.

func NewUploadOptions 

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

NewUploadOptions returns a new UploadOptions.

type Uploader 

type Uploader interface {
	// Upload uploads the given Policies.
	Upload(ctx context.Context, policies []Policy, options ...UploadOption) ([]Commit, error)
}

Uploader uploads Policies. 

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.