filesync

type Action struct {
	Kind ActionKind
	Rel  string
	// ConflictName is set only for ActionConflict: the name the SERVER's copy
	// is saved under locally so the user's own edit keeps its filename.
	ConflictName string
	// Reason is human-readable and shown in `filex sync run` output. Sync is
	// the one subsystem where people need to see why their file moved.
	Reason string
	// RemoteMod carries the server file's mtime (Unix millis) on download
	// and conflict actions, so the local copy can be stamped with it. 0 =
	// the storage reported none.
	RemoteMod int64
	// RemoteSize carries the size the server LISTED on download and conflict
	// actions. The engine refuses to install a body of any other length: it is
	// how a status report sent in place of a file (a 202 "preparing" JSON, a
	// proxy's error page) is told apart from the file.
	RemoteSize int64
	// Mixed marks a conflict between a folder on one side and a file on the
	// other. Nothing is downloaded or uploaded for it: the user is told.
	Mixed bool
	// Hold marks a conflict planned while the pair holds its local-only items
	// for a decision (Pair.HoldNew): it is settled if both sides turn out to
	// hold the same bytes, and otherwise left exactly as it is.
	Hold bool
	// LocalSig / RemoteSig are the two sides' signatures AT PLAN TIME
	// (Node.Signature(); "" = absent on that side). The plan is a decision
	// about the world as it was when the snapshots were taken, and these are
	// what let the engine notice that the world moved before the decision
	// was carried out:
	//
	//   - a download or local delete only replaces/removes the local file if
	//     it still carries LocalSig — otherwise it was edited here in the
	//     meantime and the "changed in both places" rule applies next round;
	//   - an upload is sent with RemoteSig as its precondition ("expect"), so
	//     the server refuses it if the file was saved in the browser after the
	//     listing — same rule, from the other side;
	//   - the new baseline row is built from them, never from a later
	//     snapshot (see ledger in engine.go).
	//
	// ⚠⚠ Measured before this existed: a web edit landing while a run was
	// already under way was written into the baseline as "agreed" by the
	// settle pass and never downloaded at all — the local file stayed old,
	// silently, until the next edit on either side.
	LocalSig  string
	RemoteSig string
}

type ActionKind string

type Baseline map[string]BaselineEntry

type BaselineEntry struct {
	Local  string `json:"local"`  // Signature() of the local node
	Remote string `json:"remote"` // Signature() of the remote node
	IsDir  bool   `json:"is_dir"`
}

type BusyError struct {
	Pair   string
	Holder LockHolder
}

type CopyCheck struct {
	Rel    string // pair-relative path
	Name   string // its name
	Size   int64
	SHA256 string // lower-case hex
}

type CopyFinder interface {
	FindCopy(ctx context.Context, c CopyCheck) (where string, err error)
}

type DiscardItem struct {
	Rel string
	// Where is, for a deleted file, where the server's copy is.
	Where string
	// Reason is, for a file left in place, why (Kept*).
	Reason string
	// Err is what went wrong, for KeptUnchecked and KeptFailed.
	Err string
}

type DiscardResult struct {
	Deleted []DiscardItem
	Kept    []DiscardItem
	// StillHeld is how many items the pair still holds afterwards (files and
	// the folders holding them); 0 is "the hold is over".
	StillHeld int
}

type Engine struct {
	Pair  Pair
	API   RemoteFS
	Store *Store
	// Transfers caps how many uploads/downloads run at once. 0 means
	// DefaultTransfers; 1 restores the fully serial engine.
	Transfers int
	// CheckpointEvery is how many settled transfers may pass before the
	// baseline is written mid-run (see ledger). 0 means
	// DefaultCheckpointEvery.
	CheckpointEvery int
	// Log receives one line per action. Optional.
	Log func(string)
	// Progress receives one short status line per phase — inventory counts,
	// transfer counts, settling — and stays on even when the per-action Log
	// is silenced. The desktop app runs the engine with --quiet and mirrors
	// the last stdout line into its panel; before this hook a large first
	// sync spent its whole inventory phase (minutes of per-folder listings)
	// printing nothing, and looked dead enough that people cancelled it.
	// Optional.
	Progress func(string)
	// OnProgress receives the same reports as figures (ProgressEvent). A
	// caller that says them in words of its own sets it: `filex sync run
	// --json` turns each into an event whose sentence is in the reader's
	// language, so the desktop app no longer reads the English line above
	// with regular expressions. Optional; independent of Progress.
	OnProgress func(ProgressEvent)
	// StopOn, when set, is asked about every action that failed; true ends
	// the pass at once — the rest of the plan is not attempted, the ledger is
	// still written — and the pass returns that error. The CLI sets it to
	// "the server no longer accepts this token": a revoked token must not be
	// tried once for every remaining file.
	StopOn func(error) bool
	// Now is injectable for tests.
	Now func() time.Time
	// GOOS is the operating system whose names the local folder follows
	// ("windows", "darwin", "linux"; empty: the one this runs on). A test sets
	// it to hold the Windows and macOS rules on a Linux machine.
	GOOS string
	// Lock is the pair's lock (Store.LockPair) when the caller holds it
	// across passes — `filex sync run --watch` does, for as long as it syncs
	// the pair. nil: each pass takes the lock itself and gives it back when
	// it ends. Either way no pass runs without it: a pair another process on
	// this computer is syncing fails the pass with a *BusyError before
	// anything is read (lock.go).
	Lock *PairLock
	// contains filtered or unexported fields
}

type ListedFile struct {
	Basename     string
	IsDir        bool
	Size         int64
	LastModified int64 // Unix millis; 0 = the storage does not report one
}

type Listing struct {
	Files []ListedFile
}

type LockHolder struct {
	PID   int       `json:"pid"`
	Exe   string    `json:"exe,omitempty"`
	Since time.Time `json:"since"`
}

type NameReport struct {
	// Rel is the server's path for ReasonSyncedAs and ReasonTaken, this
	// computer's for ReasonServerRefuses and ReasonImage (pair-relative).
	Rel    string `json:"rel"`
	Reason string `json:"reason"`
	// Other is the name here (ReasonSyncedAs, ReasonTaken) or the server's
	// item (ReasonImage).
	Other string `json:"other,omitempty"`
	// Why is ReasonSyncedAs's cause: a localname code or WhyTwin.
	Why string `json:"why,omitempty"`
}

type Node struct {
	Rel   string
	IsDir bool
	Size  int64
	// ModMillis is the modification time in Unix milliseconds. Local and remote
	// clocks are NEVER compared to each other — see Signature.
	ModMillis int64
}

type Options struct {
	// FirstRun suppresses every delete. With no baseline there is no way to
	// tell "you deleted this" from "you have not downloaded this yet", and
	// guessing wrong empties someone's folder. A first run is a union merge.
	FirstRun bool
	// Now stamps conflict copy names. Zero value means the caller did not care
	// (tests); the engine always sets it.
	Now time.Time
}

type Pair struct {
	ID     string `json:"id"`
	Local  string `json:"local"`  // absolute path on this machine
	Remote string `json:"remote"` // adapter://path on the server
	// Account is an opaque label the desktop app uses to remember which signed-in
	// server this pair belongs to. The engine only carries it.
	Account string `json:"account,omitempty"`
	Paused  bool   `json:"paused,omitempty"`
	// File marks a single-file pair: Local is a file path and Remote names a
	// file on the server. Same planner, same rules — the
	// snapshots just carry one entry.
	File bool `json:"file,omitempty"`
	// HoldNew says the pair holds this machine's unknown items for a decision
	// (hold.go), and Held how many. Both are READ from held/<pair-id>.json by
	// Store.LoadPairs and never written to pairs.json (see holdFile): they are
	// on the pair only so `sync list --json` — which the desktop app reads —
	// carries them.
	HoldNew bool `json:"hold_new,omitempty"`
	Held    int  `json:"held,omitempty"`
}

type PairLock struct {
	PairID string
	// contains filtered or unexported fields
}

type ProgressEvent struct {
	Phase         string
	Here          int
	Listing       bool
	Listed        int
	ListedFolders int
	Done, Total   int
	BytesDone     int64
	BytesTotal    int64
	ETA           time.Duration
	HasETA        bool
	Held          int
}

type RemoteFS interface {
	RemoteLister
	// Download writes the file at remote into w. size is what the listing
	// said (-1 = unknown); an implementation should refuse a body of any
	// other length before writing it, and the engine checks again after.
	Download(ctx context.Context, remote string, size int64, w io.Writer) (int64, error)
	// Upload writes localPath to remote. expect is the overwrite precondition
	// the server checks before it writes: "none" (the file must not exist
	// yet) or the listing signature "<size>:<mtime-ms>" the plan was made
	// from. A refusal must come back wrapping ErrRemoteChanged.
	//
	// It returns the file as the server listed it right after the write, or
	// nil when it cannot say — the engine then lists the folder itself. That
	// signature is what the baseline records for the server side; see ledger.
	Upload(ctx context.Context, localPath, remote, expect string) (*ListedFile, error)
	Mkdir(ctx context.Context, remote string) error
	Remove(ctx context.Context, remote string) error
}

type RemoteLister interface {
	List(ctx context.Context, remote string) (*Listing, error)
}

type Result struct {
	Planned      int
	Applied      int
	Uploaded     int
	Downloaded   int
	DeletedLocal int
	DeletedRemot int
	Conflicts    int
	Skipped      []string
	Errors       []string
	// Raced lists actions that stood down because the other side changed
	// while the pass was running (ErrLocalChanged / ErrRemoteChanged). They
	// are not failures: nothing was lost, and the next pass keeps both
	// versions. Reported apart from Errors so a live client can run that
	// next pass at once instead of showing an error.
	Raced    []string
	FirstRun bool
	// Full: the pass looked at the whole pair (Run), not some of its folders
	// (RunDirs). What a full pass reports - Names above all - is the whole
	// story; a targeted pass reports only the folders it looked at.
	Full     bool
	Duration time.Duration

	// Identical counts conflicts that turned out to hold the same bytes on
	// both sides: no copy was made and nothing was uploaded.
	Identical int
	// Held counts local items left alone for a decision (hold.go).
	Held int
	// Retry lists the folders (pair-relative, "" = the pair's root) holding
	// an action that failed, so a caller can retry just those (RunDirs)
	// instead of walking the whole pair again.
	Retry []string
	// Names lists the items whose names this pass could not use as they are
	// (localnames.go): a server item synced here under another name, one not
	// downloaded because that name is taken here, an item here the server
	// would refuse. Reported on every pass for as long as they are there.
	Names []NameReport
	// LocalFingerprint digests the local side as a FULL pass left it: the
	// snapshot the plan was made from, with what the pass itself wrote on
	// this machine folded in. ⚠ Never a later walk — an edit made while the
	// pass ran would be folded in too, and a watcher comparing fingerprints
	// would never see it as a change. "" for a targeted pass, and when the
	// pass did not get that far.
	LocalFingerprint string
}

type Side string

type Snapshot map[string]Node

type Store struct{ Dir string }