Struct Attrs 

pub struct Attrs {
    pub size: Option<u64>,
    pub uid: Option<u32>,
    pub gid: Option<u32>,
    pub permissions: Option<u32>,
    pub atime: Option<u32>,
    pub mtime: Option<u32>,
}

The subset of SSH_FXP_ATTRS the origin layer needs.

size and mtime form the cache key, which is why a single READDIR can replace a per-file STAT and keep the round trips flat.

uid deliberately does not answer “does this log belong to the account it names”: it is a number, an author is a name, and turning one into the other needs a passwd lookup there is no way to perform over the sftp subsystem. owner_of_longname is what answers that.

Fields

size: Option<u64>

uid: Option<u32>

gid: Option<u32>

permissions: Option<u32>

atime: Option<u32>

mtime: Option<u32>

Implementations

impl Attrs

pub fn decode(d: &mut Dec<'_>) -> Option<Self>

Examples found in repository

examples/measure-roundtrips.rs (line 189)

async fn list(s: &mut Session, dir: &str) -> Result<Vec<(String, Attrs)>> {
    let id = s.alloc_id();
    s.queue(OPENDIR, &Enc::new().u32(id).str(dir.as_bytes()).done())
        .await?;
    s.flush().await?;
    let r = s.recv().await?;
    ensure!(
        r.kind == HANDLE,
        "opendir {dir} refused (reply type {})",
        r.kind
    );
    let handle = Dec::new(r.payload())
        .str()
        .context("opendir handle")?
        .to_vec();

    let mut out = Vec::new();
    loop {
        let id = s.alloc_id();
        s.queue(READDIR, &Enc::new().u32(id).str(&handle).done())
            .await?;
        s.flush().await?;
        let r = s.recv().await?;
        if r.kind == STATUS {
            break;
        }
        ensure!(r.kind == NAME, "readdir gave reply type {}", r.kind);
        let mut d = Dec::new(r.payload());
        let count = d.u32().context("readdir count")?;
        for _ in 0..count {
            let name = String::from_utf8_lossy(d.str().context("filename")?).into_owned();
            d.str().context("longname")?;
            let attrs = Attrs::decode(&mut d).context("attrs")?;
            out.push((name, attrs));
        }
    }

    let id = s.alloc_id();
    s.queue(CLOSE, &Enc::new().u32(id).str(&handle).done())
        .await?;
    s.flush().await?;
    s.recv().await?;
    Ok(out)
}

pub fn is_dir(&self) -> bool

Examples found in repository

examples/measure-roundtrips.rs (line 54)

async fn main() -> Result<()> {
    let mut args = std::env::args().skip(1);
    let host = args
        .next()
        .context("usage: measure-roundtrips <ssh-host> [remote-dir]")?;
    let dir = args.next().unwrap_or_else(|| "/usr/include".to_string());

    let (_child, w, r) = transport::open(&host)?;
    let mut s = Sftp::handshake(w, r).await?;
    println!("host {host}  sftp v{}", s.version());

    let tau = measure_tau(&mut s).await?;
    println!("tau (one round trip) = {:.1} ms", ms(tau));

    let entries = list(&mut s, &dir).await?;
    let files: Vec<String> = entries
        .iter()
        .filter(|(name, a)| {
            !a.is_dir() && !a.is_symlink() && a.size.unwrap_or(0) > 0 && name != "." && name != ".."
        })
        .map(|(name, _)| format!("{}/{}", dir.trim_end_matches('/'), name))
        .collect();
    ensure!(
        !files.is_empty(),
        "no regular non-empty files in {dir}; pass a different remote-dir"
    );
    println!(
        "{} entries in {dir}, {} usable files",
        entries.len(),
        files.len()
    );
    println!();

    let mut largest = 0usize;
    let mut largest_open = 0.0f64;
    let mut largest_read = 0.0f64;
    let mut prev_read = 0.0f64;
    let mut last_read = 0.0f64;
    for n in BATCH_SIZES {
        if n > files.len() {
            continue;
        }
        let batch = &files[..n];
        let (t_open, handles) = batch_open(&mut s, batch).await?;
        let (t_read, bytes) = batch_read(&mut s, &handles).await?;
        batch_close(&mut s, &handles).await?;

        let open_tau = t_open.as_secs_f64() / tau.as_secs_f64();
        let read_tau = t_read.as_secs_f64() / tau.as_secs_f64();
        println!(
            "n={n:<3} open {:>7.1} ms ({open_tau:>5.2} tau)   read {:>7.1} ms ({read_tau:>5.2} tau)   {bytes} B",
            ms(t_open),
            ms(t_read)
        );
        largest = n;
        largest_open = open_tau;
        largest_read = read_tau;
        if n > 1 {
            prev_read = last_read;
        }
        last_read = read_tau;
    }

    println!();
    ensure!(
        largest > 1,
        "only one usable file; cannot distinguish pipelined from serial"
    );
    // The verdict rests on opens alone. An open carries a path and nothing else, so
    // its cost is round trips and only round trips. A read also carries the file,
    // and under an injected per-packet delay the transfer dominates: 400 KB reads
    // as 15 tau however few round trips fetched it. Judging on reads made this
    // check fail on how much data the chosen directory happens to hold, which is
    // a property of the machine rather than of the code -- exactly the kind of
    // flaky gate that teaches people to ignore a red check.
    //
    // Reads still say something, just not in absolute terms: if doubling the batch
    // does not double the time, the round trips did not scale either.
    if prev_read > 0.0 {
        let growth = largest_read / prev_read;
        println!(
            "reads {largest_read:.2} tau at n={largest}, {growth:.2}x the previous batch (serial would be about 2x)"
        );
    }

    let serial = largest as f64;
    if largest_open < serial / PIPELINE_MARGIN {
        println!(
            "VERDICT pipelined: opens cost {largest_open:.2} tau at n={largest} (serial would cost about {serial:.0})"
        );
        Ok(())
    } else {
        bail!(
            "VERDICT serial: opens cost {largest_open:.2} tau at n={largest}, near the serial cost {serial:.0}. Invariant 1 (O(1) round trips per page) is not reachable over this transport."
        )
    }
}

pub fn is_symlink(&self) -> bool

Examples found in repository

examples/measure-roundtrips.rs (line 54)

async fn main() -> Result<()> {
    let mut args = std::env::args().skip(1);
    let host = args
        .next()
        .context("usage: measure-roundtrips <ssh-host> [remote-dir]")?;
    let dir = args.next().unwrap_or_else(|| "/usr/include".to_string());

    let (_child, w, r) = transport::open(&host)?;
    let mut s = Sftp::handshake(w, r).await?;
    println!("host {host}  sftp v{}", s.version());

    let tau = measure_tau(&mut s).await?;
    println!("tau (one round trip) = {:.1} ms", ms(tau));

    let entries = list(&mut s, &dir).await?;
    let files: Vec<String> = entries
        .iter()
        .filter(|(name, a)| {
            !a.is_dir() && !a.is_symlink() && a.size.unwrap_or(0) > 0 && name != "." && name != ".."
        })
        .map(|(name, _)| format!("{}/{}", dir.trim_end_matches('/'), name))
        .collect();
    ensure!(
        !files.is_empty(),
        "no regular non-empty files in {dir}; pass a different remote-dir"
    );
    println!(
        "{} entries in {dir}, {} usable files",
        entries.len(),
        files.len()
    );
    println!();

    let mut largest = 0usize;
    let mut largest_open = 0.0f64;
    let mut largest_read = 0.0f64;
    let mut prev_read = 0.0f64;
    let mut last_read = 0.0f64;
    for n in BATCH_SIZES {
        if n > files.len() {
            continue;
        }
        let batch = &files[..n];
        let (t_open, handles) = batch_open(&mut s, batch).await?;
        let (t_read, bytes) = batch_read(&mut s, &handles).await?;
        batch_close(&mut s, &handles).await?;

        let open_tau = t_open.as_secs_f64() / tau.as_secs_f64();
        let read_tau = t_read.as_secs_f64() / tau.as_secs_f64();
        println!(
            "n={n:<3} open {:>7.1} ms ({open_tau:>5.2} tau)   read {:>7.1} ms ({read_tau:>5.2} tau)   {bytes} B",
            ms(t_open),
            ms(t_read)
        );
        largest = n;
        largest_open = open_tau;
        largest_read = read_tau;
        if n > 1 {
            prev_read = last_read;
        }
        last_read = read_tau;
    }

    println!();
    ensure!(
        largest > 1,
        "only one usable file; cannot distinguish pipelined from serial"
    );
    // The verdict rests on opens alone. An open carries a path and nothing else, so
    // its cost is round trips and only round trips. A read also carries the file,
    // and under an injected per-packet delay the transfer dominates: 400 KB reads
    // as 15 tau however few round trips fetched it. Judging on reads made this
    // check fail on how much data the chosen directory happens to hold, which is
    // a property of the machine rather than of the code -- exactly the kind of
    // flaky gate that teaches people to ignore a red check.
    //
    // Reads still say something, just not in absolute terms: if doubling the batch
    // does not double the time, the round trips did not scale either.
    if prev_read > 0.0 {
        let growth = largest_read / prev_read;
        println!(
            "reads {largest_read:.2} tau at n={largest}, {growth:.2}x the previous batch (serial would be about 2x)"
        );
    }

    let serial = largest as f64;
    if largest_open < serial / PIPELINE_MARGIN {
        println!(
            "VERDICT pipelined: opens cost {largest_open:.2} tau at n={largest} (serial would cost about {serial:.0})"
        );
        Ok(())
    } else {
        bail!(
            "VERDICT serial: opens cost {largest_open:.2} tau at n={largest}, near the serial cost {serial:.0}. Invariant 1 (O(1) round trips per page) is not reachable over this transport."
        )
    }
}

Trait Implementations

impl Clone for Attrs

fn clone(&self) -> Attrs

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Copy for Attrs

impl Debug for Attrs

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Attrs

fn default() -> Attrs

Returns the “default value” for a type.