bufwork

Documentation

Overview

Package bufwork defines the primitives used to enable workspaces.

If a buf.work.yaml file exists in a parent directory (up to the root of the filesystem), the directory containing the file is used as the root of one or more modules. With this, modules can import from one another, and a variety of commands work on multiple modules rather than one. For example, if `buf lint` is run for an input that contains a buf.work.yaml, each of the modules contained within the workspace will be linted. Other commands, such as `buf build`, will merge workspace modules into one (i.e. a "supermodule") so that all of the files contained are consolidated into a single image.

In the following example, the workspace consists of two modules: the module defined in the petapis directory can import definitions from the paymentapis module without vendoring the definitions under a common root. To be clear, `import "acme/payment/v2/payment.proto";` from the acme/pet/v1/pet.proto file will suffice as long as the buf.work.yaml file exists.

// buf.work.yaml
version: v1
directories:
  - paymentapis
  - petapis

$ tree
.
├── buf.work.yaml
├── paymentapis
│   ├── acme
│   │   └── payment
│   │       └── v2
│   │           └── payment.proto
│   └── buf.yaml
└── petapis
    ├── acme
    │   └── pet
    │       └── v1
    │           └── pet.proto
    └── buf.yaml

Note that inputs MUST NOT overlap with any of the directories defined in the buf.work.yaml file. For example, it's not possible to build input "paymentapis/acme" since the image would otherwise include the content defined in paymentapis/acme/payment/v2/payment.proto as acme/payment/v2/payment.proto and payment/v2/payment.proto.

EVERYTHING IN THIS PACKAGE SHOULD ONLY BE CALLED BY THE CLI AND CANNOT BE USED IN SERVICES.

Index

• Constants
• Variables
• func BuildOptionsForWorkspaceDirectory(ctx context.Context, workspaceConfig *Config, moduleConfig *bufconfig.Config, ...) ([]bufmodulebuild.BuildOption, error)
• func ExistingConfigFilePath(ctx context.Context, readBucket storage.ReadBucket) (string, error)
• func ExternalPathsToSubDirRelPaths(relativeRootPath string, subDirPath string, externalDirOrFilePaths []string) (map[string]string, error)
• type Config
  • func GetConfigForBucket(ctx context.Context, readBucket storage.ReadBucket, relativeRootPath string) (*Config, error)
  • func GetConfigForData(ctx context.Context, data []byte) (*Config, error)
• type ExternalConfigV1
• type WorkspaceBuilder
  • func NewWorkspaceBuilder() WorkspaceBuilder

Constants

const (
	// ExternalConfigV1FilePath is the default configuration file path for v1.
	ExternalConfigV1FilePath = "buf.work.yaml"
	// V1Version is the version string used to indicate the v1 version of the buf.work.yaml file.
	V1Version = "v1"

	// BackupExternalConfigV1FilePath is another acceptable configuration file path for v1.
	//
	// Originally we thought we were going to use buf.work, and had this around for
	// a while, but then moved to buf.work.yaml. We still need to support buf.work as
	// we released with it, however.
	BackupExternalConfigV1FilePath = "buf.work"
)

Variables

var (
	// AllConfigFilePaths are all acceptable config file paths without overrides.
	//
	// These are in the order we should check.
	AllConfigFilePaths = []string{
		ExternalConfigV1FilePath,
		BackupExternalConfigV1FilePath,
	}
)

Functions

func BuildOptionsForWorkspaceDirectory

func BuildOptionsForWorkspaceDirectory(
	ctx context.Context,
	workspaceConfig *Config,
	moduleConfig *bufconfig.Config,
	externalDirOrFilePaths []string,
	externalExcludeDirOrFilePaths []string,
	subDirRelPaths []string,
	subDirRelExcludePaths []string,
	externalDirOrFilePathsAllowNotExist bool,
) ([]bufmodulebuild.BuildOption, error)

BuildOptionsForWorkspaceDirectory returns the bufmodulebuild.BuildOptions required for the given subDirPath based on the workspace configuration.

The subDirRelPaths are the relative paths of the externalDirOrFilePaths that map to the provided subDirPath. The subDirRelExcludePaths are the relative paths of the externalExcludeDirOrFilePaths that map to the provided subDirPath.

func ExistingConfigFilePath

func ExistingConfigFilePath(ctx context.Context, readBucket storage.ReadBucket) (string, error)

ExistingConfigFilePath checks if a configuration file exists, and if so, returns the path within the ReadBucket of this configuration file.

Returns empty string and no error if no configuration file exists.

func ExternalPathsToSubDirRelPaths

func ExternalPathsToSubDirRelPaths(
	relativeRootPath string,
	subDirPath string,
	externalDirOrFilePaths []string,
) (map[string]string, error)

ExternalPathsToSubDirRelPaths returns a map of the external paths provided to their relative path to the provided subDirPath.

Note not every external path provided may have a relative path mapped to the subDirPath.

Types

type Config

type Config struct {
	// Directories are normalized and validated.
	//
	// Must be non-empty to be a valid configuration.
	Directories []string
}

Config is the workspace config.

func GetConfigForBucket

func GetConfigForBucket(ctx context.Context, readBucket storage.ReadBucket, relativeRootPath string) (*Config, error)

GetConfigForBucket gets the Config for the YAML data at ConfigFilePath.

This function expects that there is a valid non-empty configuration in the bucket. Otherwise, this errors.

func GetConfigForData

func GetConfigForData(ctx context.Context, data []byte) (*Config, error)

GetConfigForData gets the Config for the given JSON or YAML data.

This function expects that there is a valid non-empty configuration. Otherwise, this errors.

type ExternalConfigV1

type ExternalConfigV1 struct {
	Version     string   `json:"version,omitempty" yaml:"version,omitempty"`
	Directories []string `json:"directories,omitempty" yaml:"directories,omitempty"`
}

ExternalConfigV1 represents the on-disk representation of the workspace configuration at version v1.

type WorkspaceBuilder

type WorkspaceBuilder interface {
	// BuildWorkspace builds a bufmodule.Workspace.
	//
	// The given targetSubDirPath is the only path that will have the configOverride applied to it.
	// TODO: delete targetSubDirPath entirely. We are building a Workspace, we don't necessarily
	// have a specific target directory within it. This would mean doing the config override at
	// a higher level for any specific modules within the Workspace. The only thing in the config
	// we care about is the build.excludes, so in theory we should be able to figure out a way
	// to say "exclude these files from these modules when you are building". Even better, the
	// WorkspaceBuilder has nothing to do with building modules.
	BuildWorkspace(
		ctx context.Context,
		workspaceConfig *Config,
		readBucket storage.ReadBucket,
		relativeRootPath string,
		targetSubDirPath string,
		configOverride string,
		externalDirOrFilePaths []string,
		externalExcludeDirOrFilePaths []string,
		externalDirOrFilePathsAllowNotExist bool,
	) (bufmodule.Workspace, error)

	// GetModuleConfig returns the bufmodule.Module and *bufconfig.Config, associated with the given
	// targetSubDirPath, if it exists.
	GetModuleConfig(targetSubDirPath string) (bufmodule.Module, *bufconfig.Config, bool)
}

WorkspaceBuilder builds workspaces. A single WorkspaceBuilder should NOT be persisted acorss calls because the WorkspaceBuilder caches the modules used in each workspace.

func NewWorkspaceBuilder

func NewWorkspaceBuilder() WorkspaceBuilder

NewWorkspaceBuilder returns a new WorkspaceBuilder.