storage

Documentation

Index

• Variables
• func ContextWithTransactionID(ctx context.Context, id TransactionID) context.Context
• func DerivePoolPath(repositoryID int64) string
• func DeriveReplicaPath(repositoryID int64) string
• func InjectGitalyServers(ctx context.Context, name, address, token string) (context.Context, error)
• func InjectGitalyServersEnv(ctx context.Context) (context.Context, error)
• func IsPoolRepository(repo Repository) bool
• func IsPraefectPoolRepository(repo Repository) bool
• func IsRailsPoolRepository(repo Repository) bool
• func NewRepositoryNotFoundError(storageName string, relativePath string) error
• func NewStorageNotFoundError(storageName string) error
• func QuarantineDirectoryPrefix(repo Repository) string
• func RepoPathEqual(a, b Repository) bool
• func ValidateGitDirectory(path string) error
• func ValidateRelativePath(rootDir, relativePath string) (string, error)
• func WriteMetadataFile(storagePath string) (returnedErr error)
• type GetRepoPathConfig
• type GetRepoPathOption
  • func WithRepositoryVerificationSkipped() GetRepoPathOption
• type GitalyServers
  • func ExtractGitalyServers(ctx context.Context) (gitalyServersInfo GitalyServers, err error)
• type InvalidGitDirectoryError
  • func (err InvalidGitDirectoryError) Error() string
• type Locator
• type Metadata
  • func ReadMetadataFile(storagePath string) (Metadata, error)
• type Repository
• type ServerInfo
  • func ExtractGitalyServer(ctx context.Context, storageName string) (ServerInfo, error)
  • func (si ServerInfo) Zero() bool
• type TransactionID
  • func ExtractTransactionID(ctx context.Context) TransactionID
• type ValidateRepositoryConfig
• type ValidateRepositoryOption
  • func WithSkipRepositoryExistenceCheck() ValidateRepositoryOption
  • func WithSkipStorageExistenceCheck() ValidateRepositoryOption

Variables

var (
	// ErrStorageNotSet is returned when the storage name has not been set.
	ErrStorageNotSet = errors.New("storage name not set")
	// ErrStorageNotFound is returned when operating on a storage that doesn't exist.
	ErrStorageNotFound = errors.New("storage name not found")

	// ErrRepositoryNotSet is returned when the repository has not been set.
	ErrRepositoryNotSet = errors.New("repository not set")
	// ErrRepositoryPathNotSet is returned when the repository path has not been set.
	ErrRepositoryPathNotSet = errors.New("repository path not set")
	// ErrRepositoryNotFound is returned when operating on a repository that doesn't exist.
	//
	// This somewhat duplicates the above RepositoryNotFoundError but doesn't specify which
	// repository was not found. With repository IDs in use, the virtual storage and relative
	// path won't be available everywhere anymore.
	ErrRepositoryNotFound = errors.New("repository not found")
	// ErrRepositoryAlreadyExists is returned when attempting to create a repository that
	// already exists.
	ErrRepositoryAlreadyExists = errors.New("repository already exists")
	// ErrRepositoryNotValid is returned when operating on a path that is not a valid Git
	// repository.
	ErrRepositoryNotValid = errors.New("repository not valid")

	// ErrRelativePathEscapesRoot is returned when a relative path is passed that escapes the
	// storage's root directory.
	ErrRelativePathEscapesRoot = errors.New("relative path escapes root directory")
)

var ErrEmptyMetadata = errors.New("empty metadata")

ErrEmptyMetadata indicates that the gRPC metadata was not found in the context

var (
	// PraefectRootPathPrefix is the root directory for all git repositories.
	PraefectRootPathPrefix = "@cluster"
)

Functions

func ContextWithTransactionID

func ContextWithTransactionID(ctx context.Context, id TransactionID) context.Context

ContextWithTransactionID stores the transaction id in the context.

func DerivePoolPath

func DerivePoolPath(repositoryID int64) string

DerivePoolPath derives an object pools's disk storage path from its repository ID. The repository ID is hashed with SHA256 and the first four hex digits of the hash are used as the two subdirectories to ensure even distribution into subdirectories. The format is @cluster/pools/ab/cd/<repository-id>. The pools have a different directory prefix from other repositories so Gitaly can identify them in OptimizeRepository and avoid pruning them.

func DeriveReplicaPath

func DeriveReplicaPath(repositoryID int64) string

DeriveReplicaPath derives a repository's disk storage path from its repository ID. The repository ID is hashed with SHA256 and the first four hex digits of the hash are used as the two subdirectories to ensure even distribution into subdirectories. The format is @cluster/repositories/ab/cd/<repository-id>.

func InjectGitalyServers

func InjectGitalyServers(ctx context.Context, name, address, token string) (context.Context, error)

InjectGitalyServers injects gitaly-servers metadata into an outgoing context

func InjectGitalyServersEnv

func InjectGitalyServersEnv(ctx context.Context) (context.Context, error)

InjectGitalyServersEnv injects the GITALY_SERVERS env var into an incoming context.

func IsPoolRepository

func IsPoolRepository(repo Repository) bool

IsPoolRepository returns whether the repository is an object pool.

func IsPraefectPoolRepository

func IsPraefectPoolRepository(repo Repository) bool

IsPraefectPoolRepository returns whether the repository is a Praefect generated object pool repository.

func IsRailsPoolRepository

func IsRailsPoolRepository(repo Repository) bool

IsRailsPoolRepository returns whether the repository is a pool repository generated by Rails.

func NewRepositoryNotFoundError

func NewRepositoryNotFoundError(storageName string, relativePath string) error

NewRepositoryNotFoundError returns a new error that wraps ErrRepositoryNotFound. The virtual storage and relative path are appended as error metadata.

func NewStorageNotFoundError

func NewStorageNotFoundError(storageName string) error

NewStorageNotFoundError returns a new error wrapping ErrStorageNotFound with an InvalidArgument error code and metadata.

func QuarantineDirectoryPrefix

func QuarantineDirectoryPrefix(repo Repository) string

QuarantineDirectoryPrefix returns a prefix for use in the temporary directory. The prefix is based on the relative repository path and will stay stable for any given repository. This allows us to verify that a given quarantine object directory indeed belongs to the repository at hand. Ideally, this function would directly be located in the quarantine module, but this is not possible due to cyclic dependencies.

func RepoPathEqual

func RepoPathEqual(a, b Repository) bool

RepoPathEqual compares if two repositories are in the same location

func ValidateGitDirectory

func ValidateGitDirectory(path string) error

ValidateGitDirectory validates the directory at the given path looks like a valid Git repository. If the path points to a valid directory which doesn't contain the expected entries InvalidGitDirectoryError is returned. A directory is considered to be valid Git directory if it contains 'objects', 'refs' and 'HEAD'.

func ValidateRelativePath

func ValidateRelativePath(rootDir, relativePath string) (string, error)

ValidateRelativePath validates a relative path by joining it with rootDir and verifying the result is either rootDir or a path within rootDir. Returns clean relative path from rootDir to relativePath or an ErrRelativePathEscapesRoot if the resulting path is not contained within rootDir.

func WriteMetadataFile

func WriteMetadataFile(storagePath string) (returnedErr error)

WriteMetadataFile marshals and writes a metadata file

Types

type GetRepoPathConfig

type GetRepoPathConfig struct {
	// SkipRepositoryVerification will cause GetRepoPath to skip verification the verification whether the
	// computed path is an actual Git repository or not.
	SkipRepositoryVerification bool
}

GetRepoPathConfig is used to configure GetRepoPath.

type GetRepoPathOption

type GetRepoPathOption func(*GetRepoPathConfig)

GetRepoPathOption can be passed to GetRepoPath to change its default behavior.

func WithRepositoryVerificationSkipped

func WithRepositoryVerificationSkipped() GetRepoPathOption

WithRepositoryVerificationSkipped skips the repository path validation that ensures the Git directory is valid.

type GitalyServers

type GitalyServers map[string]ServerInfo

GitalyServers hold Gitaly servers info like {"default":{"token":"x","address":"y"}}, to be passed in `gitaly-servers` metadata.

func ExtractGitalyServers

func ExtractGitalyServers(ctx context.Context) (gitalyServersInfo GitalyServers, err error)

ExtractGitalyServers extracts `storage.GitalyServers` from an incoming context.

type InvalidGitDirectoryError

type InvalidGitDirectoryError struct {
	// MissingEntry is the expected directory entry that was missing.
	MissingEntry string
}

InvalidGitDirectoryError is returned when a Git directory being validated is invalid.

func (InvalidGitDirectoryError) Error

func (err InvalidGitDirectoryError) Error() string

Error returns the error message.

type Locator

type Locator interface {
	// ValidateRepository validates whether the given repository is a valid Git repository. This
	// function can be configured by passing ValidateRepositoryOptions.
	ValidateRepository(Repository, ...ValidateRepositoryOption) error
	// GetRepoPath returns the full path of the repository referenced by an RPC Repository message.
	// By default, it verifies that the path is an existing git directory. However, if invoked with
	// the `GetRepoPathOption` produced by `WithRepositoryVerificationSkipped()`, this validation
	// will be skipped. The errors returned are gRPC errors with relevant error codes and should be
	// passed back to gRPC without further decoration.
	GetRepoPath(repo Repository, opts ...GetRepoPathOption) (string, error)
	// GetStorageByName will return the path for the storage, which is fetched by
	// its key. An error is return if it cannot be found.
	GetStorageByName(storageName string) (string, error)

	// CacheDir returns the path to the cache dir for a storage.
	CacheDir(storageName string) (string, error)
	// TempDir returns the path to the temp dir for a storage.
	TempDir(storageName string) (string, error)
	// StateDir returns the path to the state dir for a storage.
	StateDir(storageName string) (string, error)
}

Locator allows to get info about location of the repository or storage at the local file system.

type Metadata

type Metadata struct {
	GitalyFilesystemID string `json:"gitaly_filesystem_id"`
}

Metadata contains metadata about the filesystem

func ReadMetadataFile

func ReadMetadataFile(storagePath string) (Metadata, error)

ReadMetadataFile reads and decodes the json metadata file

type Repository

type Repository interface {
	GetStorageName() string
	GetRelativePath() string
	GetGitObjectDirectory() string
	GetGitAlternateObjectDirectories() []string
}

Repository represents a storage-scoped repository.

type ServerInfo

type ServerInfo struct {
	Address string `json:"address"`
	Token   string `json:"token"`
}

ServerInfo contains information about how to reach a Gitaly server or a Praefect virtual storage. This is necessary for Gitaly RPC's involving more than one Gitaly. Without this information, Gitaly would not know how to reach the remote peer.

func ExtractGitalyServer

func ExtractGitalyServer(ctx context.Context, storageName string) (ServerInfo, error)

ExtractGitalyServer extracts server information for a specific storage

func (ServerInfo) Zero

func (si ServerInfo) Zero() bool

Zero returns true when no attributes have been set.

type TransactionID

type TransactionID uint64

TransactionID is an ID that uniquely identifies a Transaction.

func ExtractTransactionID

func ExtractTransactionID(ctx context.Context) TransactionID

ExtractTransactionID extracts the transaction ID from the context. The returned ID is zero if there was no transaction ID in the context.

type ValidateRepositoryConfig

type ValidateRepositoryConfig struct {
	// SkipStorageExistenceCheck determines whether the storage shall be checked for
	// existence or not. If set, the locator shall still perform parameter verification and
	// verify that whether the storage _would_ be valid if it existed, but not verify actual
	// existence. This will also skip the repository existence check. Required when
	// Praefect has not rewritten the repository storage name.
	SkipStorageExistenceCheck bool
	// SkipRepositoryExistenceCheck determines whether the repository shall be checked for
	// existence or not. If set, the locator shall still perform parameter verification and
	// verify that whether the repository _would_ be valid if it existed, but not verify actual
	// existence.
	SkipRepositoryExistenceCheck bool
}

ValidateRepositoryConfig is used to configure ValidateRepository.

type ValidateRepositoryOption

type ValidateRepositoryOption func(*ValidateRepositoryConfig)

ValidateRepositoryOption is an option that can be passed to ValidateRepository.

func WithSkipRepositoryExistenceCheck

func WithSkipRepositoryExistenceCheck() ValidateRepositoryOption

WithSkipRepositoryExistenceCheck causes ValidateRepository to not check for repository existence. All other tests will still be performed.

func WithSkipStorageExistenceCheck

func WithSkipStorageExistenceCheck() ValidateRepositoryOption

WithSkipStorageExistenceCheck causes ValidateRepository to not check for storage existence. Repository existence check will also be skipped.