github.com/keybase/client/go@v0.0.0-20240309051027-028f7c731f8b/kbfs/test/engine.go (about)

     1  // Copyright 2016 Keybase Inc. All rights reserved.
     2  // Use of this source code is governed by a BSD
     3  // license that can be found in the LICENSE file.
     4  
     5  package test
     6  
     7  import (
     8  	"time"
     9  
    10  	"github.com/keybase/client/go/kbfs/data"
    11  	"github.com/keybase/client/go/kbfs/kbfsmd"
    12  	"github.com/keybase/client/go/kbfs/libkbfs"
    13  	"github.com/keybase/client/go/kbfs/tlf"
    14  	kbname "github.com/keybase/client/go/kbun"
    15  	"github.com/keybase/client/go/protocol/keybase1"
    16  )
    17  
    18  // User is an implementation-defined object which acts as a handle to a particular user.
    19  type User interface{}
    20  
    21  // Node is an implementation-defined object which acts as a handle to a particular filesystem node.
    22  type Node interface{}
    23  
    24  type username string
    25  
    26  type teamMembers struct {
    27  	writers []kbname.NormalizedUsername
    28  	readers []kbname.NormalizedUsername
    29  }
    30  
    31  type teamMap map[kbname.NormalizedUsername]teamMembers
    32  
    33  // Engine is the interface to the filesystem to be used by the test harness.
    34  // It may wrap libkbfs directly or it may wrap other users of libkbfs (e.g., libfuse).
    35  type Engine interface {
    36  	// Name returns the name of the engine.
    37  	Name() string
    38  	// InitTest is called by the test harness to initialize user
    39  	// instances and set up the configuration of the test.
    40  	// blockChange indicates the maximum size of each data block.
    41  	// blockChangeSize indicates the maximum size the list of block
    42  	// changes can be in each MD update, before it is written to a
    43  	// dedicated data block instead. If blockSize or blockChangeSize
    44  	// are zero, the engine defaults are used. bwKBps indicates a
    45  	// bandwidth constraint to simulate to the server in kilobytes per
    46  	// second; if zero, the engine defaults are used.  opTimeout
    47  	// specifies a per-operation timeout; if it is more than the
    48  	// default engine timeout, or if it is zero, it has no effect.
    49  	InitTest(ver kbfsmd.MetadataVer, blockSize int64,
    50  		blockChangeSize int64, batchSize int, bwKBps int,
    51  		opTimeout time.Duration, users []kbname.NormalizedUsername,
    52  		teams, implicitTeams teamMap, clock libkbfs.Clock,
    53  		journal bool) map[kbname.NormalizedUsername]User
    54  	// GetUID is called by the test harness to retrieve a user instance's UID.
    55  	GetUID(u User) keybase1.UID
    56  	// GetFavorites returns the set of all public or private
    57  	// favorites, based on the given bool.
    58  	GetFavorites(u User, t tlf.Type) (map[string]bool, error)
    59  	// GetRootDir is called by the test harness to get a handle to a TLF from the given user's
    60  	// perspective
    61  	GetRootDir(u User, tlfName string, t tlf.Type, expectedCanonicalTlfName string) (dir Node, err error)
    62  	// GetRootDirAtRevision is called by the test harness to get a
    63  	// handle to an archived TLF from the given user's perspective, at
    64  	// a given revision.
    65  	GetRootDirAtRevision(
    66  		u User, tlfName string, t tlf.Type, rev kbfsmd.Revision,
    67  		expectedCanonicalTlfName string) (dir Node, err error)
    68  	// GetRootDirAtTimeString is called by the test harness to get a
    69  	// handle to an archived TLF from the given user's perspective, at
    70  	// a given time.
    71  	GetRootDirAtTimeString(
    72  		u User, tlfName string, t tlf.Type, timeString string,
    73  		expectedCanonicalTlfName string) (dir Node, err error)
    74  	// GetRootDirAtRelTimeString is called by the test harness to get
    75  	// a handle to an archived TLF from the given user's perspective,
    76  	// at a given relative time from now.
    77  	GetRootDirAtRelTimeString(
    78  		u User, tlfName string, t tlf.Type, relTimeString string,
    79  		expectedCanonicalTlfName string) (dir Node, err error)
    80  	// CreateDir is called by the test harness to create a directory relative to the passed
    81  	// parent directory for the given user.
    82  	CreateDir(u User, parentDir Node, name string) (dir Node, err error)
    83  	// CreateFile is called by the test harness to create a file in the given directory as
    84  	// the given user.
    85  	CreateFile(u User, parentDir Node, name string) (file Node, err error)
    86  	// CreateFileExcl is called by the test harness to exclusively write to the given file as the given user.
    87  	CreateFileExcl(u User, parentDir Node, name string) (file Node, err error)
    88  	// CreateLink is called by the test harness to create a symlink in the given directory as
    89  	// the given user.
    90  	CreateLink(u User, parentDir Node, fromName string, toPath string) (err error)
    91  	// WriteFile is called by the test harness to write to the given file as the given user.
    92  	WriteFile(u User, file Node, data []byte, off int64, sync bool) (err error)
    93  	// TruncateFile is called by the test harness to truncate the given file as the given user, to the given size.
    94  	TruncateFile(u User, file Node, size uint64, sync bool) (err error)
    95  	// RemoveDir is called by the test harness as the given user to remove a subdirectory.
    96  	RemoveDir(u User, dir Node, name string) (err error)
    97  	// RemoveEntry is called by the test harness as the given user to remove a directory entry.
    98  	RemoveEntry(u User, dir Node, name string) (err error)
    99  	// Rename is called by the test harness as the given user to rename a node.
   100  	Rename(u User, srcDir Node, srcName string, dstDir Node, dstName string) (err error)
   101  	// ReadFile is called by the test harness to read from the given file as the given user.
   102  	ReadFile(u User, file Node, off int64, bs []byte) (length int, err error)
   103  	// Lookup is called by the test harness to return a node in the given directory by
   104  	// its name for the given user. In the case of a symlink the symPath will be set and
   105  	// the node will be nil.
   106  	Lookup(u User, parentDir Node, name string) (file Node, symPath string, err error)
   107  	// GetDirChildrenTypes is called by the test harness as the given user to return a map of child nodes
   108  	// and their type names.
   109  	GetDirChildrenTypes(u User, parentDir Node) (children map[string]string, err error)
   110  	// SetEx is called by the test harness as the given user to set/unset the executable bit on the
   111  	// given file.
   112  	SetEx(u User, file Node, ex bool) (err error)
   113  	// SetMtime is called by the test harness as the given user to
   114  	// set the mtime on the given file.
   115  	SetMtime(u User, file Node, mtime time.Time) (err error)
   116  	// GetMtime is called by the test harness as the given user to get
   117  	// the mtime of the given file.
   118  	GetMtime(u User, file Node) (mtime time.Time, err error)
   119  	// GetPrevResions is called by the test harness as the given user
   120  	// to get the previous revisions of the given file.
   121  	GetPrevRevisions(u User, file Node) (revs data.PrevRevisions, err error)
   122  	// SyncAll is called by the test harness as the given user to
   123  	// flush all writes buffered in memory to disk.
   124  	SyncAll(u User, tlfName string, t tlf.Type) (err error)
   125  
   126  	// All functions below don't take nodes so that they can be
   127  	// run before any real FS operations.
   128  
   129  	// DisableUpdatesForTesting is called by the test harness as
   130  	// the given user to disable updates to trigger conflict
   131  	// conditions.
   132  	DisableUpdatesForTesting(u User, tlfName string, t tlf.Type) (err error)
   133  	// MakeNaïveStaller returns a NaïveStaller associated with user u for
   134  	// stalling BlockOps or MDOps.
   135  	MakeNaïveStaller(u User) *libkbfs.NaïveStaller
   136  	// ReenableUpdates is called by the test harness as the given
   137  	// user to resume updates if previously disabled for testing.
   138  	ReenableUpdates(u User, tlfName string, t tlf.Type) (err error)
   139  	// SyncFromServer is called by the test harness as the given user
   140  	// to actively retrieve new metadata for a folder.
   141  	SyncFromServer(u User, tlfName string, t tlf.Type) (err error)
   142  	// ForceQuotaReclamation starts quota reclamation by the given
   143  	// user in the TLF corresponding to the given node.
   144  	ForceQuotaReclamation(u User, tlfName string, t tlf.Type) (err error)
   145  	// AddNewAssertion makes newAssertion, which should be a
   146  	// single assertion that doesn't already resolve to anything,
   147  	// resolve to the same UID as oldAssertion, which should be an
   148  	// arbitrary assertion that does already resolve to something.
   149  	// It only applies to the given user.
   150  	AddNewAssertion(u User, oldAssertion, newAssertion string) (err error)
   151  	// ChangeTeamName renames a team.
   152  	ChangeTeamName(u User, oldName, newName string) (err error)
   153  	// Rekey rekeys the given TLF under the given user.
   154  	Rekey(u User, tlfName string, t tlf.Type) (err error)
   155  	// EnableJournal is called by the test harness as the given
   156  	// user to enable journaling.
   157  	EnableJournal(u User, tlfName string, t tlf.Type) (err error)
   158  	// PauseJournal is called by the test harness as the given
   159  	// user to pause journaling.
   160  	PauseJournal(u User, tlfName string, t tlf.Type) (err error)
   161  	// ResumeJournal is called by the test harness as the given
   162  	// user to resume journaling.
   163  	ResumeJournal(u User, tlfName string, t tlf.Type) (err error)
   164  	// FlushJournal is called by the test harness as the given
   165  	// user to wait for the journal to flush, if enabled.
   166  	FlushJournal(u User, tlfName string, t tlf.Type) (err error)
   167  	// UnflushedPaths called by the test harness to find out which
   168  	// paths haven't yet been flushed from the journal.
   169  	UnflushedPaths(u User, tlfName string, t tlf.Type) (
   170  		paths []string, err error)
   171  	// UserEditHistory called by the test harness to get the edit
   172  	// history for the given user.
   173  	UserEditHistory(u User) (history []keybase1.FSFolderEditHistory, err error)
   174  	// DirtyPaths called by the test harness to find out which
   175  	// paths haven't yet been flushed out of memory.
   176  	DirtyPaths(u User, tlfName string, t tlf.Type) (paths []string, err error)
   177  	// TogglePrefetch is called by the test harness as the given user to toggle
   178  	// whether prefetching should be enabled
   179  	TogglePrefetch(u User, enable bool) error
   180  	// ForceConflict can force a stuck conflict in the given TLF.
   181  	ForceConflict(u User, tlfName string, t tlf.Type) (err error)
   182  	// ClearConflicts can clear the conflicts in a TLF by moving the
   183  	// conflict view out of the way.
   184  	ClearConflicts(u User, tlfName string, t tlf.Type) (err error)
   185  	// Shutdown is called by the test harness when it is done with the
   186  	// given user.
   187  	Shutdown(u User) error
   188  }