tlf

package
v0.0.0-...-66acf6f Latest Latest
Warning

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

Go to latest
Published: Jan 18, 2024 License: BSD-3-Clause, BSD-3-Clause Imports: 18 Imported by: 0

README

tlf

Top-level folder (TLF)-related types and functions for KBFS.

Errors returned by ID from this package are wrapped with pkg/errors, and so need errors.Cause() to unwrap them.

TODO: Do the other types in this package.

Documentation

Index

Constants

View Source
const (
	// HandleExtensionSep is the string that separates the folder
	// participants from an extension suffix in the TLF name.
	HandleExtensionSep = " "

	// HandleExtensionStaticTestDate is a static date used for tests (2016-03-14).
	HandleExtensionStaticTestDate = 1457913600
)
View Source
const (
	// UnknownKeying is a placeholder type for when TLF keying mode is unknown.
	UnknownKeying = KeyingType(Unknown)
	// PrivateKeying specifies the TLF keying mode used in classic private TLFs.
	PrivateKeying = KeyingType(Private)
	// PublicKeying specifies the TLF keying mode used in classic public TLFs.
	PublicKeying = KeyingType(Public)
	// TeamKeying specifies the TLF keying mode used for SingleTeam or
	// implicit team backed TLFs.
	TeamKeying = KeyingType(SingleTeam)
)
View Source
const (
	// TlfHandleExtensionSep is the string that separates the folder
	// participants from an extension suffix in the TLF name.
	TlfHandleExtensionSep = " "

	// PublicUIDName is the name given to keybase1.PublicUID.  This string
	// should correspond to an illegal or reserved Keybase user name.
	PublicUIDName = "_public"
)
View Source
const (
	// ReaderSep is the string that separates readers from writers in a
	// TLF name.
	ReaderSep = "#"
)

Variables

View Source
var NullID = ID{}

NullID is an empty ID

Functions

func ContainsLocalConflictExtensionPrefix

func ContainsLocalConflictExtensionPrefix(s string) bool

ContainsLocalConflictExtensionPrefix returns true if the string contains the local conflict string.

func FakeIDByte

func FakeIDByte(id ID) byte

FakeIDByte returns the byte used to create a fake TLF ID with FakeID.

func NormalizeAssertionOrName

func NormalizeAssertionOrName(mctx libkb.MetaContext, s string) (string, error)

NormalizeAssertionOrName normalizes the given assertion or name `s`.

TODO: this function can likely be replaced with a call to AssertionParseAndOnly when CORE-2967 and CORE-2968 are fixed.

func NormalizeNamesInTLF

func NormalizeNamesInTLF(mctx libkb.MetaContext, writerNames, readerNames []string,
	extensionSuffix string) (string, error)

NormalizeNamesInTLF takes a split TLF name and, without doing any resolutions or identify calls, normalizes all elements of the name. It then returns the normalized name.

func SplitAndNormalizeTLFName

func SplitAndNormalizeTLFName(mctx libkb.MetaContext, name string, public bool) (
	writerNames, readerNames []string,
	extensionSuffix string, err error)

SplitAndNormalizeTLFName returns separate lists of normalized writer and reader names, as well as the extension suffix, of the given `name`.

func SplitExtension

func SplitExtension(name string) (
	assertions, extensionSuffix string, err error)

SplitExtension separates any extension suffix from the assertions.

func SplitName

func SplitName(name string) (writerNames, readerNames []string,
	extensionSuffix string, err error)

SplitName splits a TLF name into components.

func UserIsOnlyWriter

func UserIsOnlyWriter(username kbname.NormalizedUsername, canon CanonicalName) bool

UserIsOnlyWriter returns true if and only if username is the only writer in a TLF represented by canon. In any error case, false is returned. This function only naively looks at the TLF name, so it should only be used on non-team TLFs.

Types

type BadNameError

type BadNameError struct {
	Name string
}

BadNameError indicates a top-level folder name that has an incorrect format.

func (BadNameError) Error

func (e BadNameError) Error() string

Error implements the error interface for BadNameError.

type BadTLFNameError

type BadTLFNameError struct {
	Name string
}

BadTLFNameError indicates a top-level folder name that has an incorrect format.

func (BadTLFNameError) Error

func (e BadTLFNameError) Error() string

Error implements the error interface for BadTLFNameError.

type CanonicalName

type CanonicalName string

CanonicalName is a string containing the canonical name of a TLF.

func MakeCanonicalName

func MakeCanonicalName(resolvedWriters []kbname.NormalizedUsername,
	unresolvedWriters []keybase1.SocialAssertion,
	resolvedReaders []kbname.NormalizedUsername,
	unresolvedReaders []keybase1.SocialAssertion,
	extensions []HandleExtension) CanonicalName

MakeCanonicalName makes a CanonicalName from components.

func MakeCanonicalNameForTeam

func MakeCanonicalNameForTeam(resolvedWriters []kbname.NormalizedUsername,
	unresolvedWriters []keybase1.SocialAssertion,
	resolvedReaders []kbname.NormalizedUsername,
	unresolvedReaders []keybase1.SocialAssertion,
	extensions []HandleExtension) CanonicalName

MakeCanonicalNameForTeam makes a CanonicalName from components for a team.

type ErrUnknownTLFType

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

ErrUnknownTLFType is returned by ParseTlfType when an unknown TLF type string is provided.

func (ErrUnknownTLFType) Error

func (e ErrUnknownTLFType) Error() string

Error implements the error interface.

type Handle

type Handle struct {
	Writers           []keybase1.UserOrTeamID    `codec:"w,omitempty"`
	Readers           []keybase1.UserOrTeamID    `codec:"r,omitempty"`
	UnresolvedWriters []keybase1.SocialAssertion `codec:"uw,omitempty"`
	UnresolvedReaders []keybase1.SocialAssertion `codec:"ur,omitempty"`
	ConflictInfo      *HandleExtension           `codec:"ci,omitempty"`
	FinalizedInfo     *HandleExtension           `codec:"fi,omitempty"`
	// contains filtered or unexported fields
}

Handle uniquely identified top-level folders by readers and writers.

NOTE: if you change this type, ensure you update the `NumField` check in `init`, and that the new fields are correctly checked for equality in `Handle.DeepEqual()`. TODO: Have separate types for writers vs. readers.

func MakeHandle

func MakeHandle(
	writers, readers []keybase1.UserOrTeamID,
	unresolvedWriters, unresolvedReaders []keybase1.SocialAssertion,
	extensions []HandleExtension) (Handle, error)

MakeHandle creates a Handle from the given list of readers and writers. If the given reader list contains just keybase1.PUBLIC_UID, then the returned handle will be for a public folder. Otherwise, it will be private. PUBLIC_UID shouldn't be in any list in any other case.

func (*Handle) DeepEqual

func (h *Handle) DeepEqual(other Handle) bool

DeepEqual returns true if the handle is equal to another handle. This can mutate the Handle in that it might sort its Writers, Readers, UnresolvedWriters, and UnresolvedReaders.

func (Handle) Extensions

func (h Handle) Extensions() (extensions []HandleExtension)

Extensions returns a list of extensions for the given handle.

func (Handle) HasUnresolvedUsers

func (h Handle) HasUnresolvedUsers() bool

HasUnresolvedUsers returns true if this handle has any unresolved writers or readers.

func (Handle) IsBackedByTeam

func (h Handle) IsBackedByTeam() bool

IsBackedByTeam returns true if h represents a TLF backed by a team. It could be either a SingleTeam TLF or a private/public TLF backed by an implicit team.

func (Handle) IsConflict

func (h Handle) IsConflict() bool

IsConflict returns true if the handle is a conflict handle.

func (Handle) IsFinal

func (h Handle) IsFinal() bool

IsFinal returns true if the handle has been finalized.

func (Handle) IsReader

func (h Handle) IsReader(user keybase1.UserOrTeamID) bool

IsReader returns whether or not the given user is a reader for the top-level folder represented by this Handle.

func (Handle) IsWriter

func (h Handle) IsWriter(user keybase1.UserOrTeamID) bool

IsWriter returns whether or not the given user is a writer for the top-level folder represented by this Handle.

func (Handle) ResolveAssertions

func (h Handle) ResolveAssertions(
	assertions map[keybase1.SocialAssertion]keybase1.UID) Handle

ResolveAssertions creates a new Handle given an existing one with while resolving the passed assertions.

func (Handle) ResolvedUsers

func (h Handle) ResolvedUsers() []keybase1.UserOrTeamID

ResolvedUsers returns the concatenation of h.Writers and h.Readers, except if the handle is public, the returned list won't contain PUBLIC_UID.

func (*Handle) ResolvedUsersEqual

func (h *Handle) ResolvedUsersEqual(
	writers []keybase1.UserOrTeamID, readers []keybase1.UserOrTeamID) bool

ResolvedUsersEqual checks whether the resolved users of this TLF matches the provided lists of writers and readers.

func (Handle) Type

func (h Handle) Type() Type

Type returns the type of TLF this Handle represents.

func (Handle) TypeForKeying

func (h Handle) TypeForKeying() KeyingType

TypeForKeying returns the keying type for the handle h.

func (Handle) UnresolvedUsers

func (h Handle) UnresolvedUsers() []keybase1.SocialAssertion

UnresolvedUsers returns the concatenation of h.UnresolvedWriters and h.UnresolvedReaders.

type HandleExtension

type HandleExtension struct {
	Date     int64                     `codec:"date"`
	Number   uint16                    `codec:"num"`
	Type     HandleExtensionType       `codec:"type"`
	Username kbname.NormalizedUsername `codec:"un,omitempty"`
	codec.UnknownFieldSetHandler
}

HandleExtension is information which identifies a particular extension.

func NewHandleExtension

func NewHandleExtension(extType HandleExtensionType, num uint16, un kbname.NormalizedUsername, now time.Time) (
	*HandleExtension, error)

NewHandleExtension returns a new HandleExtension struct populated with the date from the given time and conflict number.

func NewTestHandleExtensionStaticTime

func NewTestHandleExtensionStaticTime(extType HandleExtensionType, num uint16, un kbname.NormalizedUsername) (
	*HandleExtension, error)

NewTestHandleExtensionStaticTime returns a new HandleExtension struct populated with a static date for testing.

func ParseHandleExtensionSuffix

func ParseHandleExtensionSuffix(s string) ([]HandleExtension, error)

ParseHandleExtensionSuffix parses a TLF handle extension suffix string.

func (HandleExtension) String

func (e HandleExtension) String() string

String implements the fmt.Stringer interface for HandleExtension. Ex: "(conflicted copy 2016-05-09 #2)"

type HandleExtensionList

type HandleExtensionList []HandleExtension

HandleExtensionList allows us to sort extensions by type.

func (HandleExtensionList) Len

func (l HandleExtensionList) Len() int

func (HandleExtensionList) Less

func (l HandleExtensionList) Less(i, j int) bool

func (HandleExtensionList) Splat

func (l HandleExtensionList) Splat() (ci, fi *HandleExtension)

Splat will deconstruct the list for the caller into individual extension pointers (or nil.)

func (HandleExtensionList) Suffix

func (l HandleExtensionList) Suffix() string

Suffix outputs a suffix string for this extension list.

func (HandleExtensionList) SuffixForTeamHandle

func (l HandleExtensionList) SuffixForTeamHandle() string

SuffixForTeamHandle outputs a suffix string for this extension list for a handle that's backed by a team (which must be an implicit team, since there aren't any suffixes for regulat teams).

func (HandleExtensionList) Swap

func (l HandleExtensionList) Swap(i, j int)

type HandleExtensionMismatchError

type HandleExtensionMismatchError struct {
	Expected HandleExtension
	// Actual may be nil.
	Actual *HandleExtension
}

HandleExtensionMismatchError indicates the expected extension doesn't match the server's extension for the given handle.

func (HandleExtensionMismatchError) Error

Error implements the error interface for HandleExtensionMismatchError

type HandleExtensionType

type HandleExtensionType int

HandleExtensionType is the type of extension.

const (
	// HandleExtensionConflict means the handle conflicted as a result of a social
	// assertion resolution.
	HandleExtensionConflict HandleExtensionType = iota
	// HandleExtensionFinalized means the folder ended up with no more valid writers as
	// a result of an account reset.
	HandleExtensionFinalized
	// HandleExtensionLocalConflict means the handle conflicted as a
	// result of a local conflict branch.
	HandleExtensionLocalConflict
	// HandleExtensionUnknown means the type is unknown.
	HandleExtensionUnknown
)

func (HandleExtensionType) String

String implements the fmt.Stringer interface for HandleExtensionType

type ID

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

ID is a top-level folder ID

func FakeID

func FakeID(b byte, t Type) ID

FakeID creates a fake public or private TLF ID from the given byte.

func MakeIDFromTeam

func MakeIDFromTeam(t Type, tid keybase1.TeamID, epoch byte) (ID, error)

MakeIDFromTeam makes a deterministic TLF ID from a team ID and an epoch representing how many times a new TLF has been needed for this team. Returns NullID on failure.

func MakeRandomID

func MakeRandomID(t Type) (ID, error)

MakeRandomID makes a random ID using a cryptographically secure RNG. Returns NullID on failure.

func ParseID

func ParseID(s string) (ID, error)

ParseID parses a hex encoded ID. Returns NullID and an InvalidIDError on failure.

func (ID) Bytes

func (id ID) Bytes() []byte

Bytes returns the bytes of the TLF ID.

func (ID) GetEpochFromTeamTLF

func (id ID) GetEpochFromTeamTLF(tid keybase1.TeamID) (
	matches bool, epoch byte, err error)

GetEpochFromTeamTLF returns 1) whether this ID matches the given team TID, and 2) if so, which epoch it is.

func (ID) MarshalBinary

func (id ID) MarshalBinary() (data []byte, err error)

MarshalBinary implements the encoding.BinaryMarshaler interface for ID.

func (ID) MarshalText

func (id ID) MarshalText() ([]byte, error)

MarshalText implements the encoding.TextMarshaler interface for ID.

func (ID) SafeType

func (id ID) SafeType() (Type, error)

SafeType returns the type of TLF represented by this ID. If the ID isn't valid, it returns tlf.Unknown along with an error.

func (ID) String

func (id ID) String() string

String implements the fmt.Stringer interface for ID.

func (ID) Type

func (id ID) Type() Type

Type returns the type of TLF represented by this ID.

Note that this function panics if the ID suffix is unknown, rather than returning tlf.Unknown.

func (*ID) UnmarshalBinary

func (id *ID) UnmarshalBinary(data []byte) error

UnmarshalBinary implements the encoding.BinaryUnmarshaler interface for ID.

func (*ID) UnmarshalText

func (id *ID) UnmarshalText(buf []byte) error

UnmarshalText implements the encoding.TextUnmarshaler interface for ID.

type InvalidIDError

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

InvalidIDError indicates that a TLF ID string is not parseable or invalid.

func (InvalidIDError) Error

func (e InvalidIDError) Error() string

type KeyingType

type KeyingType Type

KeyingType represents a TLF keying mode. It normally have the same values as Type.

func (KeyingType) String

func (t KeyingType) String() string

String implements the fmt.Stringer interface.

type NameNotCanonical

type NameNotCanonical struct {
	Name, NameToTry string
}

NameNotCanonical indicates that a name isn't a canonical, and that another (not necessarily canonical) name should be tried.

func (NameNotCanonical) Error

func (e NameNotCanonical) Error() string

type NoSuchNameError

type NoSuchNameError struct {
	Name string
}

NoSuchNameError indicates that the user tried to access a subdirectory entry that doesn't exist.

func (NoSuchNameError) Error

func (e NoSuchNameError) Error() string

Error implements the error interface for NoSuchNameError

type NoSuchUserError

type NoSuchUserError struct {
	Input string
}

NoSuchUserError indicates that the given user couldn't be resolved.

func (NoSuchUserError) Error

func (e NoSuchUserError) Error() string

Error implements the error interface for NoSuchUserError

func (NoSuchUserError) ToStatus

func (e NoSuchUserError) ToStatus() keybase1.Status

ToStatus implements the keybase1.ToStatusAble interface for NoSuchUserError

type PreferredName

type PreferredName string

PreferredName is a preferred TLF name.

func CanonicalToPreferredName

func CanonicalToPreferredName(username kbname.NormalizedUsername,
	canon CanonicalName) (PreferredName, error)

CanonicalToPreferredName returns the preferred TLF name, given a canonical name and a username. The username may be empty, and results in the canonical name being being returned unmodified.

type SocialAssertionList

type SocialAssertionList []keybase1.SocialAssertion

SocialAssertionList can be used to lexicographically sort SocialAssertions.

func (SocialAssertionList) Len

func (u SocialAssertionList) Len() int

func (SocialAssertionList) Less

func (u SocialAssertionList) Less(i, j int) bool

func (SocialAssertionList) Swap

func (u SocialAssertionList) Swap(i, j int)

type Type

type Type int

Type is the type of TLF represented by a particular ID (e.g., public, private, etc.)

const (
	// Unknown is a placeholder type for when TLF type information is not
	// available. It is the zero value of the type Type.
	Unknown Type = iota
	// Private represents a private TLF between one or more individual users.
	Private
	// Public represents a public TLF for one or more individual users.
	Public
	// SingleTeam represents a private TLF for a single Keybase team.
	SingleTeam
)

func ParseTlfTypeFromPath

func ParseTlfTypeFromPath(str string) (Type, error)

ParseTlfTypeFromPath parses str into a Type.

func TypeFromFolderType

func TypeFromFolderType(ft keybase1.FolderType) Type

TypeFromFolderType returns the Type corresponding to the given keybase1.FolderType.

func (Type) FolderType

func (t Type) FolderType() keybase1.FolderType

FolderType returns the keybase1.FolderType corresponding to the given TLF type.

func (Type) MarshalText

func (t Type) MarshalText() ([]byte, error)

MarshalText implements the encoding.TextMarshaler interface for Type.

func (Type) PathString

func (t Type) PathString() string

PathString returns the string representation of t, when they are used in a KBFS path. This is different from String() where this one returns 'team' instead of 'singleTeam' for SingleTeam.

func (Type) String

func (t Type) String() string

func (Type) ToKeyingType

func (t Type) ToKeyingType() KeyingType

ToKeyingType converts Type t into a KeyingType.

type UIDList

type UIDList []keybase1.UserOrTeamID

UIDList can be used to lexicographically sort UserOrTeamIDs.

func (UIDList) Len

func (u UIDList) Len() int

func (UIDList) Less

func (u UIDList) Less(i, j int) bool

func (UIDList) Swap

func (u UIDList) Swap(i, j int)

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL