Skip to content
45 changes: 45 additions & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -654,12 +654,14 @@ Implemented command behavior:
- `ti fs mount-file-system --file-system-id <file-system-id> --mount-path ./workspace --mount-profile portable --pack-path /`
- `ti fs mount-file-system --file-system-id <file-system-id> --mount-path ./workspace --driver fuse --read-cache-size-mb 256 --read-cache-max-file-mb 16`
- `ti fs mount-file-system --file-system-id <file-system-id> --mount-path ./workspace --driver fuse --cache-dir ~/.ti/cache/workspace --write-back-cache=false`
- `ti fs mount-file-system --file-system-id <file-system-id> --mount-path ./workspace --driver fuse --durability close-sync`
- `ti fs mount-file-system --file-system-id <file-system-id> --mount-path ./workspace --remote-path /workspace --driver fuse --layer-ref layer-1`
- `ti fs mount-file-system --file-system-id <file-system-id> --mount-path ./workspace-v1 --remote-path /workspace --driver fuse --layer-ref layer-1 --checkpoint-id cp-1`
- `ti fs drain-file-system --mount-path ./workspace`
- `ti fs drain-file-system --mount-path ./workspace --timeout 30s`
- `ti fs unmount-file-system --mount-path ./workspace`
- `ti fs unmount-file-system --mount-path ./workspace --ignore-absent`
- `ti fs unmount-file-system --mount-path ./workspace --force`
- `ti fs-vault create-secret --secret-name db-prod --field DB_URL=mysql://example --field PASSWORD=@./password.txt`
- `ti fs-vault replace-secret --secret-path /n/vault/db-prod --from-directory ./secret-fields`
- `ti fs-vault read-secret --secret-name db-prod`
Expand Down Expand Up @@ -1149,6 +1151,49 @@ Background FS and vault mounts write only a non-secret locator under
original resource-scoped companion HOME without requiring the FS token again.
Successful unmount removes the locator; failed unmount preserves it for retry.

`ti fs unmount-file-system` drains before it detaches a FUSE mount and must never
report success while write-back work is still local. Parse the companion's
`mount drain --json` report instead of discarding it: `ti fs drain-file-system`
returns it as `response`, prints the pending counters in text output with one
shared formatter, fails with `fs.drain_pending_work` when work remains, and
refuses mounts the dry-run calls "not applicable" (WebDAV, and any non-`fs`
locator kind such as `vault`) with `fs.drain_not_applicable` instead of a raw
companion error. The unmount records the driver the companion actually mounted
in the non-secret mount locator, gates only FUSE file-system mounts on the
drain, blocks with the locator preserved while work is pending, and treats
`--force` as the only "accept the loss" path (reported as `drain.status:
"skipped"`). `--ignore-absent` is a cleanup idempotency flag: it may continue
only past a drain failure that reports no pending work (no report at all, or a
parsed report whose counters are all zero with a non-pending classification),
but the block condition is the parsed pending counters, never the engine's
`error_kind` alone and never the rendered summary (`DrainPending.HasPendingWork`
is the single predicate, with one block authority: the error code that already
folds the counters in), and the outcome must still report `drain.status:
"failed"` on both the `unmounted` and `absent` paths. A non-pending classification with
queued work still blocks. A locator written before the driver was recorded is never gated, so
an upgrade cannot block an existing unmount. The reported `durability` must
match the driver the companion reported, and `--durability` must reject an
explicitly empty value instead of treating it as the default. Do not drop these
outcomes from the result, and do not reimplement the drain in ti: the mount
control socket belongs to the companion. The companion's `--mode auto` rule is
mirrored in exactly one place (`companionMountMode`), because
`mountdriver.Resolve` is prerequisite-aware and would disagree with the
companion; see `docs/spec/done/0038-fs-mount-durability.md`.

`ti fs mount-file-system` forwards the selected write-durability tier to the
companion as `mount --durability`. The flag accepts `auto`, `interactive`,
`fsync`, `close-sync`, and `write-sync`, and defaults to `interactive` so an
ordinary mount keeps its documented behavior instead of following the engine's
`auto` default. Never collapse the tier back into the legacy
`--write-back-cache` boolean: keep that flag only as an alias (`true` means
`interactive`, `false` means `auto`), and refuse an inconsistent explicit
combination. FUSE mounts forward the tier, including `--driver auto` mounts on
platforms whose automatic choice is FUSE; WebDAV mounts forward none and reject
every explicit tier except `auto` with `fs.webdav_durability_unsupported`;
checkpoint mounts are read-only, force `auto`, and reject any other explicit
tier. Report the effective tier as `durability` in the mount result and do not
reintroduce the removed `write_back_cache` boolean.

Do not implement or expose ti commands for Drive9 internal APIs that are not
part of Drive9's public CLI. In particular, do not reintroduce low-level layer
entry/object/event commands, low-level Git workspace/tree/state/object-pack/
Expand Down
10 changes: 10 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -179,6 +179,16 @@ Automatic mounting uses FUSE on Linux and WebDAV on macOS and Windows. macOS use

Mount commands start the companion runtime in the background, wait until the mount is ready, and then return a structured result. Use `ti fs unmount-file-system` or `ti fs-vault unmount-vault` to end a mount. The public CLI does not expose a foreground mount mode.

FUSE mounts choose their write durability with `--durability`: `auto` lets the companion measure round-trip time, `interactive` (the default) keeps writes durable in the local staging journal and uploads them after flush, `fsync` makes `fsync(2)` wait for the remote commit, `close-sync` makes `close(2)` remote-durable, and `write-sync` makes every write remote-durable before it returns. Use `close-sync` or `write-sync` when a caller must not lose an acknowledged write in the client; the interactive default leaves that window to the background uploader. The mount result reports the effective tier as `durability`. WebDAV mounts keep the engine's native write behavior: ti forwards no tier, reports `auto`, and rejects every other explicit tier. `--write-back-cache` remains as a legacy alias where `true` means `interactive` and `false` means `auto`. Checkpoint mounts are read-only, reject any tier other than `auto`, and report `auto`.

```shell
ti fs mount-file-system --file-system-id <file-system-id> --mount-path ~/my-workspace --driver fuse --durability close-sync
ti fs drain-file-system --mount-path ~/my-workspace
ti fs unmount-file-system --mount-path ~/my-workspace
```

`ti fs drain-file-system` reports the companion's drain result, including the pending counters (`open_handles`, `commit_queue_*`, `uploader_*`), so a caller can tell "fully uploaded" from "the background upload never finished"; it also refuses WebDAV and vault mounts, which have no drain, instead of failing with a raw companion error. `ti fs unmount-file-system` runs that drain itself before detaching a FUSE file-system mount and fails with `fs.drain_pending_work` while writes are still pending, keeping the mount locator so the command can be retried. `--force` is the only way to accept the undrained writes (the result then records `drain.status: "skipped"`); `--ignore-absent` stays a cleanup idempotency flag and continues only past a drain failure that reports no pending work - no report at all, or a zero-counter report with a non-pending classification (`drain.status: "failed"`) - never past pending work. WebDAV mounts keep their native write behavior and are not gated, and `ti fs-vault unmount-vault` is not gated either because the engine drains only file-system mounts.

Run a command against a remote Filesystem (Runtime is available only in AWS `us-east-1` and `us-west-2`):

```shell
Expand Down
127 changes: 127 additions & 0 deletions docs/spec/done/0038-fs-mount-durability.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,127 @@
# FUSE Mount Write Durability Selection

## Goal

Let a `ti fs mount-file-system` caller pick the write-durability tier the
ti-drive9 companion applies to a FUSE mount:

```bash
ti fs mount-file-system --file-system-id <id> --mount-path ./workspace
ti fs mount-file-system --file-system-id <id> --mount-path ./workspace --durability close-sync
ti fs mount-file-system --file-system-id <id> --mount-path ./workspace --driver fuse --durability write-sync
```

Before this spec, ti exposed only the boolean `--write-back-cache`, and only an
explicit `--driver fuse` mount forwarded anything: `true` (the default) pinned
the companion to `interactive`, and `false` forwarded nothing, so the companion
fell back to its own `auto` default. The companion has supported five tiers for
longer than ti has exposed them (`mount --durability auto|interactive|fsync|
close-sync|write-sync`), so a platform customer that needed `close-sync` or
`write-sync` had to mount around ti and drain by hand, which leaves the
client-side loss window unbounded and unobservable.

## User Outcome

A caller can state the durability it needs and get it, or get a clear error:

- `interactive` (default) keeps the previous behavior: writes are durable in the
local staging journal and the remote upload runs in the background after
flush.
- `close-sync` makes `close(2)` remote-durable, so a completed close means the
data left the client.
- `write-sync` makes every `write(2)` remote-durable before it returns.
- `fsync` makes `fsync(2)` wait for the remote commit while ordinary writes keep
the write-back policy.
- `auto` leaves the choice to the companion's round-trip measurement.

The mount result reports the effective tier, so a script can verify what it got
instead of assuming:

```json
{ "status": "mounted", "driver": "fuse", "durability": "close-sync" }
```

## Command Contract

`ti fs mount-file-system` (and its `ti fs mount` alias) gains:

- `--durability <string>`, default `interactive`, one of `auto`, `interactive`,
`fsync`, `close-sync`, `write-sync`. The value is trimmed and case-folded
before validation; anything else fails with `fs.invalid_mount_durability` and
exit code 2 before the companion runs. An explicitly empty value fails with
`fs.missing_mount_durability`, matching the CLI's rule for `--region` and
`--profile`, instead of being silently treated as the default.

`--write-back-cache` stays as a legacy alias so existing scripts keep working:

- `--write-back-cache=true` means `--durability=interactive`.
- `--write-back-cache=false` means `--durability=auto`.
- Setting both explicitly to inconsistent values fails with
`fs.conflicting_mount_durability` instead of silently preferring one.

### Forwarding rules

ti forwards the tier as `mount --durability <tier>` only when the mount resolves
to FUSE, mirroring the companion's own `--mode auto` rule (WebDAV on macOS and
Windows, FUSE elsewhere). That rule lives in one place,
`internal/fs/mount_durability.go`'s `companionMountMode`. It deliberately does
not use `mountdriver.Resolve`, which is prerequisite-aware (macFUSE on darwin)
and would forward a tier to a WebDAV mount the companion chose. The mount result
reconciles the reported `durability` with the driver the companion reports, so
the result never claims a tier that is not in effect:

- Explicit `--driver fuse`, and `--driver auto` on a platform whose automatic
choice is FUSE, forward the tier. An ordinary mount therefore keeps the
`interactive` default instead of following the companion's `auto` default.
- `--driver webdav` forwards no tier. WebDAV mounts keep the engine's native
write behavior, so an explicit tier other than `auto` fails with
`fs.webdav_durability_unsupported` and exit code 2. Reporting a tier that
cannot take effect would be worse than refusing it.
- Checkpoint mounts (`--layer-ref` plus `--checkpoint-id`) are read-only: they
force `auto`, forward nothing, and reject any other explicit tier with
`fs.checkpoint_mount_read_only`. `--write-back-cache=true` keeps its existing
rejection there.

The result reports the effective tier as `durability` (`auto` for WebDAV and
checkpoint mounts). It replaces the previous `write_back_cache` boolean: a
boolean cannot express five tiers, and keeping a derived boolean alongside the
tier invites it to disagree with the mount. The removed field was never
documented as a stable contract.

`--dry-run` reports the same effective tier in its request body and applies the
same validations, including the WebDAV rejection.

## Scope

In scope:

- `internal/cli` flag registration and option wiring.
- `internal/fs` tier normalization, legacy alias reconciliation, FUSE/WebDAV
and checkpoint rules, companion argv construction, mount result, and dry-run.
- README, AGENTS.md, e2e (fake companion argv + failures), and live e2e mount
coverage.

Out of scope:

- `ti fs-vault mount-vault`, which forwards no tier and reports `auto`.
- Any ti-native mount implementation. Mounting still belongs to the companion.
- Drive9-side behavior: ti only selects an existing engine tier.

## Verification

- Unit tests pin the tier table, the legacy alias mapping, the conflict error,
the explicit-empty rejection, the WebDAV and checkpoint rejections, the local
mirror of the companion's `--mode auto` rule, the forwarded argv for every
tier, the interactive default, and the dry-run body.
- `make e2e` covers the default and a strict tier end to end through the fake
companion, plus the invalid-value and WebDAV rejections. Mounts that assert a
forwarded tier pin `--driver fuse`, and the automatic-mode case branches on
the host platform, so the gate is green on macOS and Windows too.
- `make live-e2e-fs` and `make live-e2e-fs-git` mount with an explicit tier
(`close-sync`) and assert the reported value, and the live WebDAV mount
asserts `auto`.

The English PingCAP documentation pages under `docs/pingcap-docs/docs/` are a
submodule that was not checked out while this spec was implemented. The
published mount page must gain the `--durability` section; the tracked follow-up
is issue #98 in this repository and must land before the next release cut.
Loading