rustfs/crates/e2e_test/src/protocols/README.md

# Protocol E2E Tests

FTPS, WebDAV, and SFTP protocol end-to-end tests for RustFS.

## Prerequisites

No external SSH tooling is required. The test framework generates ed25519
host keys in-process via russh::keys under the per-test temp directory
before each SFTP server spawn, and russh-sftp drives the protocol from the
test process directly.

## Running Tests

```bash
RUSTFS_BUILD_FEATURES=ftps,webdav,sftp cargo test --package e2e_test test_protocol_core_suite -- --test-threads=1 --nocapture
```

`RUSTFS_BUILD_FEATURES` controls which features the test rustfs binary is
built with. When this variable is set, the protocol test runner schedules
only entries whose protocol is present in the requested feature list. Leave
it unset to run every protocol entry.
`--test-threads=1` is required because every entry spawns a rustfs server
on fixed bind ports.

## Test Coverage

### FTPS Tests
- mkdir bucket
- cd to bucket
- put file
- ls list objects
- cd . (stay in current directory)
- cd / (return to root)
- cd nonexistent bucket (should fail)
- delete object
- cdup
- rmdir delete bucket

### WebDAV Tests
- PROPFIND at root (list buckets)
- MKCOL (create bucket)
- PUT (upload file)
- GET (download file)
- PROPFIND on bucket (list objects)
- DELETE file
- MOVE file (rename object)
- DELETE bucket
- Authentication failure test

### SFTP Tests

The SFTP suite lives in three entries plus a standalone idle-timeout case.
Every assertion runs against a freshly spawned rustfs binary with
`RUSTFS_SFTP_ENABLE=true`; the test framework also pins
`RUSTFS_SFTP_PART_SIZE=5242880` so the multipart boundary is deterministic.

#### sftp_core (`test_sftp_core_operations`)

Bind ports 9022 (SFTP) and 9200 (S3). 22 in-suite assertions covering the
core protocol surface plus cross-protocol consistency:

- Subsystem canary: SFTPv3 version exchange completes after password auth
- Bucket lifecycle: mkdir, root listing, rmdir, post-delete listing
- Small-file round-trip with SHA256 compare
- Stat on a file (size + file type) and on a bucket (directory)
- SETSTAT on a path returns ok
- Rename within bucket, listing reflects the rename
- Multipart-sized round-trip (just over 2 × part_size) with SHA256 compare
- Negative cases: symlink rejected, open of nonexistent file rejected,
  read_dir of nonexistent bucket rejected, path traversal rejected
- Spec-letter assertions: APPEND open returns an error, CREATE+EXCLUDE on an
  existing path returns an error, bad-password authentication is rejected
- Cross-protocol via aws-sdk-s3: SFTP write then S3 read with SHA256 match,
  S3 write then SFTP read with SHA256 match
- Cross-API directory visibility: SFTP-created sub-directory visible via S3
  ListObjectsV2, S3-created `__XLDIR__` marker visible via SFTP readdir as a
  directory entry

#### sftp_compliance (`test_sftp_compliance_suite`)

Bind ports 9024 (SFTP) and 9300 (S3). 14 compliance regression cases against
one shared server spawn. Each case carries a stable CMPTST-NN identifier:

- CMPTST-01: medium-binary upload then download with SHA256 compare
  (single-shot PutObject path below the multipart boundary)
- CMPTST-02: zero-byte upload, download, and stat-size match
- CMPTST-03: rm against a bucket path is rejected; the bucket is preserved
- CMPTST-04: rmdir against a non-empty bucket is rejected; the contained
  object survives
- CMPTST-05: rmdir against a non-empty sub-directory is rejected; the inner
  object survives
- CMPTST-06: open with a path-traversal pattern cannot leak a host file via
  SFTP read
- CMPTST-07: read_dir of `/..` either errors or returns a listing that
  contains no host system entries
- CMPTST-08: rename across buckets preserves payload and removes the source
  object
- CMPTST-09: paths with embedded spaces round-trip through the russh-sftp
  client
- CMPTST-10: read_link is rejected (S3 storage has no symlinks)
- CMPTST-11: SETSTAT on a path and FSETSTAT on a separate open handle both
  return ok (rsync, WinSCP transfer-success contract)
- CMPTST-12: rename to the same path is a no-op; the file persists with the
  original payload
- CMPTST-13: implicit-directory round-trip; uploading to a nested key
  creates the parent directory implicitly and three listing forms surface
  the inner file
- CMPTST-14: OPEN, WRITE, FSETSTAT, CLOSE on the same write handle all
  return ok (WinSCP wire shape)

#### sftp_compliance_readonly (`test_sftp_compliance_readonly`)

Bind ports 9025 (SFTP) and 9301 (S3). Spawns a second rustfs binary with
`RUSTFS_SFTP_READ_ONLY=true`; the S3 endpoint stays writable so the suite
can seed a bucket and a fixture object via aws-sdk-s3 before opening the
SFTP session. 7 compliance cases:

- CMPTST-15: put through SFTP is rejected
- CMPTST-16: rm through SFTP is rejected
- CMPTST-17: mkdir through SFTP is rejected
- CMPTST-18: rmdir through SFTP is rejected
- CMPTST-19: rename through SFTP is rejected
- CMPTST-20: ls through SFTP is allowed and lists the seeded bucket
- CMPTST-21: get through SFTP is allowed and returns the seeded payload
  byte-for-byte

The full case index lives at the top of `sftp_compliance.rs`; each helper's
log lines name its CMPTST-NN code so a failure in CI points at one named
property without consulting any external doc.

#### sftp_idle_timeout (`test_sftp_idle_timeout_disconnects`)

Bind ports 9023 (SFTP) and 9100 (S3). Spawns rustfs with
`RUSTFS_SFTP_IDLE_TIMEOUT=5`, sleeps 10 s past the timeout, then issues an
SFTP request and asserts the server has closed the session.