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 

func (e HandleExtensionMismatchError) Error() string

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 

func (et HandleExtensionType) String(username kbname.NormalizedUsername) 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)

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.