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
- Variables
- func ArePathsEquivalent(path1, path2 string) bool
- func LoggableDir(ref string) string
- func Split(segment string) []string
- func TrimTrailingSlash(element string) string
- func ValidateServiceAndCategory(service ServiceType, category CategoryType) error
- type Builder
- func (pb Builder) Append(elements ...string) *Builder
- func (pb Builder) Conceal() string
- func (pb Builder) Dir() *Builder
- func (pb Builder) Elements() Elements
- func (pb Builder) Format(fs fmt.State, _ rune)
- func (pb Builder) HeadElem() string
- func (pb Builder) LastElem() string
- func (pb Builder) PlainString() string
- func (pb Builder) PopFront() *Builder
- func (pb Builder) ShortRef() string
- func (pb Builder) SplitUnescapeAppend(s string) (*Builder, error)
- func (pb Builder) String() string
- func (pb Builder) ToDataLayerPath(tenant, resource string, service ServiceType, category CategoryType, ...) (Path, error)
- func (pb Builder) ToServiceCategoryMetadataPath(tenant, resource string, service ServiceType, category CategoryType, ...) (Path, error)
- func (pb Builder) ToStreamStorePath(tenant, purpose string, service ServiceType, isItem bool) (Path, error)
- func (pb Builder) UnescapeAndAppend(elements ...string) (*Builder, error)
- func (pb *Builder) UpdateParent(prev, cur *Builder) bool
- type CategoryType
- type DrivePath
- type Elements
- type Path
- func Build(tenant, resourceOwner string, service ServiceType, category CategoryType, ...) (Path, error)
- func BuildMetadata(tenant, resourceOwner string, service ServiceType, category CategoryType, ...) (Path, error)
- func BuildOrPrefix(tenant, resourceOwner string, service ServiceType, category CategoryType, ...) (Path, error)
- func BuildPrefix(tenant, resourceOwner string, s ServiceType, c CategoryType) (Path, error)
- func FromDataLayerPath(p string, isItem bool) (Path, error)
- func PrefixOrPathFromDataLayerPath(p string, isItem bool) (Path, error)
- type RestorePaths
- type ServiceType
Constants ¶
const (
PathSeparator = '/'
)
Variables ¶
var ErrorUnknownCategory = clues.New("unknown category string")
var ErrorUnknownService = clues.New("unknown service string")
Functions ¶
func ArePathsEquivalent ¶
func LoggableDir ¶
LoggableDir takes in a path reference (of any structure) and conceals any non-standard elements (ids, filenames, foldernames, etc).
func Split ¶
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 ¶
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 ¶
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 ¶
Returns the path to the folder within the drive (i.e. under `root:`)
func (Builder) Append ¶
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 ¶
Conceal produces a concealed representation of the builder, suitable for logging, storing in errors, and other output.
func (Builder) 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 ¶
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) PlainString ¶
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) ShortRef ¶
ShortRef produces a truncated hash of the builder that acts as a unique identifier.
func (Builder) SplitUnescapeAppend ¶
SplitUnescapeAppend takes in an escaped string representing a directory path, splits the string, and appends it to the current builder.
func (Builder) 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 (Builder) UnescapeAndAppend ¶
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 ¶
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 ¶
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 ¶
type Elements ¶
type Elements []string
Elements are a PII Concealer-compliant slice of elements within a path.
func NewElements ¶
NewElements creates a new Elements slice by splitting the provided string.
func (Elements) Conceal ¶
Conceal produces a concealed representation of the elements, suitable for logging, storing in errors, and other output.
func (Elements) Format ¶
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) PlainString ¶
PlainString returns an unescaped, unmodified string of the joined elements. 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 ¶
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.
type RestorePaths ¶
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 ExchangeMetadataService ServiceType = 4 // exchangeMetadata OneDriveMetadataService ServiceType = 5 // onedriveMetadata 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