path

package
v0.0.0-...-880cb89 Latest Latest
Warning

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

 Go to latest Published: Oct 11, 2024 License: Apache-2.0 Imports: 9 Imported by: 0

Documentation

Overview

Package path provides a set of functions for wrangling paths from the outside world into paths that corso can understand. Paths use the standard Unix path separator character '/'. If for some reason an individual element in a raw path contains the '/' character, it should be escaped with '\'. If the path contains '\' it should be escaped by turning it into '\\'.

Paths can be split into elements by splitting on '/' if the '/' is not escaped. Additionally, corso may operate on segments in a path. Segments are made up of one or more path elements.

Examples of paths splitting by elements and canonicalization with escaping: 1. 

input path: `this/is/a/path`
elements of path: `this`, `is`, `a`, `path`

2. 

input path: `this/is\/a/path`
elements of path: `this`, `is/a`, `path`

3. 

input path: `this/is\\/a/path`
elements of path: `this`, `is\`, `a`, `path`

4. 

input path: `this/is\\\/a/path`
elements of path: `this`, `is\/a`, `path`

5. 

input path: `this/is//a/path`
elements of path: `this`, `is`, `a`, `path`

6. 

input path: `this/is\//a/path`
elements of path: `this`, `is/`, `a`, `path`

7. 

input path: `this/is/a/path/`
elements of path: `this`, `is`, `a`, `path`

8. 

input path: `this/is/a/path\/`
elements of path: `this`, `is`, `a`, `path/`

Index

Constants

View Source 
const (
	PathSeparator = '/'
)

Variables

View Source 
var ErrorUnknownCategory = clues.New("unknown category string")
View Source 
var ErrorUnknownService = clues.New("unknown service string")

Functions

func ArePathsEquivalent 

func ArePathsEquivalent(path1, path2 string) bool

func LoggableDir 

func LoggableDir(ref string) string

LoggableDir takes in a path reference (of any structure) and conceals any non-standard elements (ids, filenames, foldernames, etc).

func Split 

func Split(segment string) []string

split takes an escaped string and returns a slice of path elements. The string is split on the path separator according to the escaping rules. The provided string must not contain an unescaped trailing path separator.

func TrimTrailingSlash 

func TrimTrailingSlash(element string) string

TrimTrailingSlash takes an escaped path element and returns an escaped path element with the trailing path separator character(s) removed if they were not escaped. If there were no trailing path separator character(s) or the separator(s) were escaped the input is returned unchanged.

func ValidateServiceAndCategory 

func ValidateServiceAndCategory(service ServiceType, category CategoryType) error

Types

type Builder 

type Builder struct {
	// contains filtered or unexported fields
}

Builder is a simple path representation that only tracks path elements. It can join, escape, and unescape elements. Higher-level packages are expected to wrap this struct to build resource-specific contexts (e.x. an ExchangeMailPath). Resource-specific paths allow access to more information like segments in the path. Builders that are turned into resource paths later on do not need to manually add prefixes for items that normally appear in the data layer (ex. tenant ID, service, resource ID, etc).

func BuildDriveLocation 

func BuildDriveLocation(
	driveID string,
	unescapedElements ...string,
) *Builder

BuildDriveLocation takes a driveID and a set of unescaped element names, including the root folder, and returns a *path.Builder containing the canonical path representation for the drive path.

func BuildGroupsDriveLocation 

func BuildGroupsDriveLocation(
	siteID string,
	driveID string,
	unescapedElements ...string,
) *Builder

BuildGroupsDriveLocation is same as BuildDriveLocation, but for group drives and thus includes siteID.

func GetDriveFolderPath 

func GetDriveFolderPath(p Path) (*Builder, error)

Returns the path to the folder within the drive (i.e. under `root:`)

func (Builder) Append 

func (pb Builder) Append(elements ...string) *Builder

Append creates a copy of this Builder and adds the given elements them to the end of the new Builder. Elements are added in the order they are passed.

func (Builder) Conceal 

func (pb Builder) Conceal() string

Conceal produces a concealed representation of the builder, suitable for logging, storing in errors, and other output.

func (Builder) Dir 

func (pb Builder) Dir() *Builder

Dir removes the last element from the builder.

func (Builder) Elements 

func (pb Builder) Elements() Elements

Elements returns all the elements in the path. This is a temporary function and will likely be updated to handle encoded elements instead of clear-text elements in the future.

func (Builder) Format 

func (pb Builder) Format(fs fmt.State, _ rune)

Format produces a concealed representation of the builder, even when used within a PrintF, suitable for logging, storing in errors, and other output.

func (Builder) HeadElem 

func (pb Builder) HeadElem() string

HeadElem returns the first element in the Builder.

func (Builder) LastElem 

func (pb Builder) LastElem() string

LastElem returns the last element in the Builder.

func (Builder) PlainString 

func (pb Builder) PlainString() string

PlainString returns an unescaped, unmodified string of the builder. The result is not concealed, and is not suitable for logging or structured errors.

func (Builder) PopFront 

func (pb Builder) PopFront() *Builder

func (Builder) ShortRef 

func (pb Builder) ShortRef() string

ShortRef produces a truncated hash of the builder that acts as a unique identifier.

func (Builder) SplitUnescapeAppend 

func (pb Builder) SplitUnescapeAppend(s string) (*Builder, error)

SplitUnescapeAppend takes in an escaped string representing a directory path, splits the string, and appends it to the current builder.

func (Builder) String 

func (pb Builder) String() string

String returns a string that contains all path elements joined together. Elements of the path that need escaping are escaped. The result is not concealed, and is not suitable for logging or structured errors.

func (Builder) ToDataLayerPath 

func (pb Builder) ToDataLayerPath(
	tenant, resource string,
	service ServiceType,
	category CategoryType,
	isItem bool,
	elems ...string,
) (Path, error)

func (Builder) ToServiceCategoryMetadataPath 

func (pb Builder) ToServiceCategoryMetadataPath(
	tenant, resource string,
	service ServiceType,
	category CategoryType,
	isItem bool,
) (Path, error)

func (Builder) ToStreamStorePath 

func (pb Builder) ToStreamStorePath(
	tenant, purpose string,
	service ServiceType,
	isItem bool,
) (Path, error)

func (Builder) UnescapeAndAppend 

func (pb Builder) UnescapeAndAppend(elements ...string) (*Builder, error)

UnescapeAndAppend creates a copy of this Builder and adds one or more already escaped path elements to the end of the new Builder. Elements are added in the order they are passed.

func (*Builder) UpdateParent 

func (pb *Builder) UpdateParent(prev, cur *Builder) bool

UpdateParent updates leading elements matching prev to be cur and returns true if it was updated. If prev is not a prefix of this Builder changes nothing and returns false. If either prev or cur is nil does nothing and returns false.

type CategoryType 

type CategoryType int

CategoryType denotes what category of data the path corresponds to. The order of the enums below can be changed, but the string representation of each enum must remain the same or migration code needs to be added to handle changes to the string format. 

const (
	UnknownCategory           CategoryType = 0
	EmailCategory             CategoryType = 1  // email
	ContactsCategory          CategoryType = 2  // contacts
	EventsCategory            CategoryType = 3  // events
	FilesCategory             CategoryType = 4  // files
	ListsCategory             CategoryType = 5  // lists
	LibrariesCategory         CategoryType = 6  // libraries
	PagesCategory             CategoryType = 7  // pages
	DetailsCategory           CategoryType = 8  // details
	ChannelMessagesCategory   CategoryType = 9  // channelMessages
	ConversationPostsCategory CategoryType = 10 // conversationPosts
	ChatsCategory             CategoryType = 11 // chats
)

func ToCategoryType 

func ToCategoryType(s string) CategoryType

func (CategoryType) HumanString 

func (cat CategoryType) HumanString() string

HumanString produces a more human-readable string version of the category.

func (CategoryType) String 

func (i CategoryType) String() string

type DrivePath 

type DrivePath struct {
	DriveID string
	Root    string
	Folders Elements
}

TODO: Move this into m365/collection/drive drivePath is used to represent path components of an item within the drive i.e. Given `drives/b!X_8Z2zuXpkKkXZsr7gThk9oJpuj0yXVGnK5_VjRRPK-q725SX_8ZQJgFDK8PlFxA/root:/Folder1/Folder2/file`

driveID is `b!X_8Z2zuXpkKkXZsr7gThk9oJpuj0yXVGnK5_VjRRPK-q725SX_8ZQJgFDK8PlFxA` and folders[] is []{"Folder1", "Folder2"}

Should be compatible with all drive-based services (ex: oneDrive, sharePoint Libraries, etc)

func ToDrivePath 

func ToDrivePath(p Path) (*DrivePath, error)

type Elements 

type Elements []string

Elements are a PII Concealer-compliant slice of elements within a path.

func NewElements 

func NewElements(p string) Elements

NewElements creates a new Elements slice by splitting the provided string.

func (Elements) Builder 

func (el Elements) Builder() *Builder

Builder produces a *Builder{} containing the elements.

func (Elements) Conceal 

func (el Elements) Conceal() string

Conceal produces a concealed representation of the elements, suitable for logging, storing in errors, and other output.

func (Elements) Format 

func (el Elements) Format(fs fmt.State, _ rune)

Format produces a concealed representation of the elements, even when used within a PrintF, suitable for logging, storing in errors, and other output.

func (Elements) Last 

func (el Elements) Last() string

Last returns the last element. Returns "" if empty.

func (Elements) PlainString 

func (el Elements) PlainString() string

PlainString returns an unescaped, unmodified string of the joined elements. The result is not concealed, and is not suitable for logging or structured errors.

func (Elements) String 

func (el Elements) String() string

String returns a string that contains all path elements joined together. Elements that need escaping are escaped. The result is not concealed, and is not suitable for logging or structured errors.

type Path 

type Path interface {
	String() string
	Service() ServiceType
	Category() CategoryType
	Tenant() string
	ProtectedResource() string
	Folder(escaped bool) string
	Folders() Elements
	Item() string
	// UpdateParent updates parent from old to new if the item/folder was
	// parented by old path
	UpdateParent(prev, cur Path) bool
	// PopFront returns a Builder object with the first element (left-side)
	// removed. As the resulting set of elements is no longer a valid resource
	// path a Builder is returned instead.
	PopFront() *Builder
	// Dir returns a Path object with the right-most element removed if possible.
	// If removing the right-most element would discard one of the required prefix
	// elements then an error is returned.
	Dir() (Path, error)
	// Elements returns all the elements in the path. This is a temporary function
	// and will likely be updated to handle encoded elements instead of clear-text
	// elements in the future.
	Elements() Elements
	Equal(other Path) bool
	// Append returns a new Path object with the given element added to the end of
	// the old Path if possible. If the old Path is an item Path then Append
	// returns an error.
	Append(isItem bool, elems ...string) (Path, error)
	// AppendItem is a shorthand for Append(true, someItem)
	AppendItem(item string) (Path, error)
	// ShortRef returns a short reference representing this path. The short
	// reference is guaranteed to be unique. No guarantees are made about whether
	// a short reference can be converted back into the Path that generated it.
	ShortRef() string
	// ToBuilder returns a Builder instance that represents the current Path.
	ToBuilder() *Builder

	// Every path needs to comply with these funcs to ensure that PII
	// is appropriately hidden from logging, errors, and other outputs.
	clues.Concealer
	fmt.Stringer
}

For now, adding generic functions to pull information from segments. Resources that don't have the requested information should return an empty string.

func Build 

func Build(
	tenant, resourceOwner string,
	service ServiceType,
	category CategoryType,
	hasItem bool,
	elements ...string,
) (Path, error)

func BuildMetadata 

func BuildMetadata(
	tenant, resourceOwner string,
	service ServiceType,
	category CategoryType,
	hasItem bool,
	elements ...string,
) (Path, error)

BuildMetadata is a shorthand for Builder{}.Append(...).ToServiceCategoryMetadataPath(...)

func BuildOrPrefix 

func BuildOrPrefix(
	tenant, resourceOwner string,
	service ServiceType,
	category CategoryType,
	hasItem bool,
	elements ...string,
) (Path, error)

BuildOrPrefix is the same as Build, but allows for 0-len folders (ie: only builds the prefix).

func BuildPrefix 

func BuildPrefix(
	tenant, resourceOwner string,
	s ServiceType,
	c CategoryType,
) (Path, error)

func FromDataLayerPath 

func FromDataLayerPath(p string, isItem bool) (Path, error)

FromDataLayerPath parses the escaped path p, validates the elements in p match a resource-specific path format, and returns a Path struct for that resource-specific type. If p does not match any resource-specific paths or is malformed returns an error.

func PrefixOrPathFromDataLayerPath 

func PrefixOrPathFromDataLayerPath(p string, isItem bool) (Path, error)

type RestorePaths 

type RestorePaths struct {
	StoragePath Path
	RestorePath Path
}

RestorePaths denotes the location to find an item in kopia and the path of the collection to place the item in for restore.

type ServiceType 

type ServiceType int

ServiceType denotes what service the path corresponds to. Metadata services are also included though they are only used for paths that house metadata for Corso backups.

Metadata services are not considered valid service types for resource paths though they can be used for metadata paths.

The string representaton of each enum _must remain the same_. In case of changes to those values, we'll need migration code to handle transitions across states else we'll get marshalling/unmarshalling errors. 

const (
	UnknownService            ServiceType = 0
	ExchangeService           ServiceType = 1  // exchange
	OneDriveService           ServiceType = 2  // onedrive
	SharePointService         ServiceType = 3  // sharepoint
	ExchangeMetadataService   ServiceType = 4  // exchangeMetadata
	OneDriveMetadataService   ServiceType = 5  // onedriveMetadata
	SharePointMetadataService ServiceType = 6  // sharepointMetadata
	GroupsService             ServiceType = 7  // groups
	GroupsMetadataService     ServiceType = 8  // groupsMetadata
	TeamsChatsService         ServiceType = 9  // teamsChats
	TeamsChatsMetadataService ServiceType = 10 // teamsChatsMetadata
)

func ToServiceType 

func ToServiceType(service string) ServiceType

func (ServiceType) HumanString 

func (svc ServiceType) HumanString() string

HumanString produces a more human-readable string version of the service.

func (ServiceType) String 

func (i ServiceType) String() string

func (ServiceType) ToMetadata 

func (svc ServiceType) ToMetadata() ServiceType

Source Files

View all Source files

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.