drive

Documentation

Overview

Package drive is xftp's SharePoint document-library client: it resolves a SharePoint URL to a Graph drive, then exposes FTP-shaped operations over that drive — Stat, List, Download, Upload, Mkdir, Remove, Move. The URL may name just the site (binds the default library), a specific library, or a folder deep-linked from the browser (binds that library and seeds the starting folder). Uploads stream from a reader: files up to 250MB go in a single PUT, larger ones through a chunked, resumable upload session.

Index

• func SortChildren(items []Item)
• type Drive
  • func ResolveDrive(ctx context.Context, g *spauth.GraphClient, siteURL, library string) (*Drive, error)
  • func (d *Drive) Download(ctx context.Context, g *spauth.GraphClient, path string, w io.Writer) error
  • func (d *Drive) List(ctx context.Context, g *spauth.GraphClient, path string) ([]Item, error)
  • func (d *Drive) Mkdir(ctx context.Context, g *spauth.GraphClient, path string) error
  • func (d *Drive) MkdirIfMissing(ctx context.Context, g *spauth.GraphClient, path string) error
  • func (d *Drive) Move(ctx context.Context, g *spauth.GraphClient, src, dst string) error
  • func (d *Drive) Remove(ctx context.Context, g *spauth.GraphClient, path string) error
  • func (d *Drive) SetMTime(ctx context.Context, g *spauth.GraphClient, path string, t time.Time) error
  • func (d *Drive) Stat(ctx context.Context, g *spauth.GraphClient, path string) (Item, error)
  • func (d *Drive) Upload(ctx context.Context, g *spauth.GraphClient, path, contentType string, ...) error
  • func (d *Drive) Walk(ctx context.Context, g *spauth.GraphClient, root string, foldersOnly bool, ...) error
• type Item

Functions

func SortChildren

func SortChildren(items []Item)

SortChildren orders a folder listing in place: case-insensitively by name, with the exact name as a stable tiebreaker. Both xfind and xtree walk with this ordering so their output is deterministic and matches between the two.

Types

type Drive

type Drive struct {
	SiteID    string
	DriveID   string
	Name      string
	Hostname  string
	SitePath  string
	SourceURL string
	StartPath string
}

Drive is a resolved SharePoint document library the session operates on. SourceURL is kept so a future REPL "refresh"/reconnect can re-bind without re-prompting. StartPath is the library-relative folder the URL pointed into ("" for the library root), used to seed the REPL's working directory.

func ResolveDrive

func ResolveDrive(ctx context.Context, g *spauth.GraphClient, siteURL, library string) (*Drive, error)

ResolveDrive resolves a SharePoint URL to a Graph drive. Library selection follows three rules, in order: an explicit library name wins; otherwise a URL that points below the site is matched to a library by webUrl (with any folder remainder kept as the starting path); otherwise the site's default document library ("Documents"/"Shared Documents") is bound.

func (*Drive) Download

func (d *Drive) Download(ctx context.Context, g *spauth.GraphClient, path string, w io.Writer) error

Download streams the content of a remote file at the library-relative path into w. (FTP "get".)

func (*Drive) List

func (d *Drive) List(ctx context.Context, g *spauth.GraphClient, path string) ([]Item, error)

List returns the children of a library-relative folder path ("" or "/" for the library root). This is the read primitive behind an FTP "ls".

func (*Drive) Mkdir

func (d *Drive) Mkdir(ctx context.Context, g *spauth.GraphClient, path string) error

Mkdir creates a folder at the library-relative path. (FTP "mkdir".) Fails if something already exists at that path.

func (*Drive) MkdirIfMissing

func (d *Drive) MkdirIfMissing(ctx context.Context, g *spauth.GraphClient, path string) error

MkdirIfMissing creates the folder unless it is already there, so calling it twice is the same as calling it once. Mkdir stays strict for xftp, where an interactive "it's already there" is worth saying; a mirror wants the folder to exist and does not care who made it.

The existence check runs only after Mkdir fails, so the ordinary path still costs one round trip. Checking that way rather than reading the 409 out of the error also keeps this off Graph's exact wording: the errors here are formatted strings with no status code to match on, and a message that shifts under a service update would silently turn idempotence back into a failed run.

func (*Drive) Move

func (d *Drive) Move(ctx context.Context, g *spauth.GraphClient, src, dst string) error

Move renames or relocates an item from src to dst (both library-relative). (FTP "rename".) It resolves the destination's parent folder to an item ID and PATCHes the source — the id-based parentReference is more reliable than the path-based form.

func (*Drive) Remove

func (d *Drive) Remove(ctx context.Context, g *spauth.GraphClient, path string) error

Remove deletes the file or folder at the library-relative path. (FTP "delete"/"rmdir".) Folder deletes are recursive in Graph, so callers should confirm first.

func (*Drive) SetMTime

func (d *Drive) SetMTime(ctx context.Context, g *spauth.GraphClient, path string, t time.Time) error

SetMTime writes the filesystem last-modified time of the item at the library-relative path into its fileSystemInfo — the timestamp OneDrive clients use to mirror local mtimes (unlike lastModifiedDateTime, which is service-controlled and read-only). xsync stamps it after an upload so the remote copy carries the source file's mtime, keeping later size+mtime comparisons stable instead of re-uploading on every run. The time is sent at whole-second precision in UTC, which Graph accepts unambiguously.

func (*Drive) Stat

func (d *Drive) Stat(ctx context.Context, g *spauth.GraphClient, path string) (Item, error)

Stat returns metadata for a single item at the library-relative path ("" or "/" for the drive root). Used to validate "cd" targets and to size downloads.

func (*Drive) Upload

func (d *Drive) Upload(ctx context.Context, g *spauth.GraphClient, path, contentType string, r io.Reader, size int64) error

Upload streams size bytes from r to the library-relative remote path. (FTP "put".) Files at or below SimpleUploadMax go in a single PUT; larger files use a chunked, resumable upload session. An existing file at the path is replaced.

func (*Drive) Walk

func (d *Drive) Walk(ctx context.Context, g *spauth.GraphClient, root string, foldersOnly bool,
	visit func(it Item, itemPath string, depth int, isLast bool) (descend bool)) error

Walk recursively visits every item beneath the library-relative root folder, depth first, in SortChildren order. For each item it calls visit with the item, its library-relative path, its depth below root (root's direct children are depth 1), and whether it is the last child of its parent (so a tree view can draw └── vs ├──). When visit returns false for a folder, the walk does not descend into it — that's how depth and type filters prune the traversal. A List failure on any folder stops the walk and is returned.

When foldersOnly is set, files are dropped from each listing before visiting, so isLast reflects the last *folder* in a directory rather than the last item. A tree drawn from a folders-only walk would otherwise mark the last subfolder with ├── whenever a file sorts after it but goes unshown.

type Item

type Item struct {
	Name         string
	ID           string
	IsFolder     bool
	Size         int64
	ChildCount   int
	LastModified time.Time
	FSModified   time.Time
	// QuickXorHash is SharePoint's content hash for a file, base64-encoded as
	// Graph returns it; empty for folders and for files whose hash the service
	// has not yet computed. xsync uses it to settle a size-equal/mtime-diverged
	// comparison by content instead of re-transferring on a timestamp alone.
	QuickXorHash string
}

Item is one entry in a drive folder listing — the unit an FTP-style "ls" prints and "cd" descends into. LastModified is the service-level modification time (what "ls" shows); FSModified is the filesystem mtime from fileSystemInfo — the writable timestamp OneDrive clients mirror, which xsync uses for size+mtime comparisons. FSModified falls back to LastModified when a drive item carries no fileSystemInfo.